ccstatusline-zh

ccstatusline-zh

🎨 Claude Code CLI 高度可定制状态栏格式化工具 — 中文汉化版

在终端中显示模型信息、Git 分支、Token 用量及其他实时指标

本项目是 ccstatusline 的中文汉化 Fork，当前同步至上游 v2.2.19 版本（含 Voice Status、版本固定全局安装、Jujutsu VCS、CompactionCounter、超额用量组件、Git 子进程缓存等最新功能）。所有用户可见的界面文本（组件名称、分类、描述、菜单标签、提示信息等）均已翻译为中文，方便中文用户使用。

📚 目录

• 关于本项目
• 功能特性
• 快速开始
• Windows 支持
• 使用方法
• 可用组件
• 配置界面（TUI）
• API 文档
• 开发指南
• 致谢
• 许可证

🌏 关于本项目

ccstatusline-zh 是 ccstatusline 的中文汉化版本。

ccstatusline 是一个优秀的 Claude Code CLI 状态栏格式化工具，支持 50+ 种可定制组件、Powerline 主题、交互式 TUI 配置界面等丰富功能。本项目在其基础上，将所有用户可见的英文文本直接替换为中文，包括：

• 72 个组件的名称、描述、分类标签（含 v2.2.13 新增的 Voice Status / 周 Sonnet 用量 / 周 Opus 用量，v2.2.17 新增的超额用量占比 / 超额用量剩余）
• TUI 配置界面的全部菜单项、帮助文本、提示信息、对话框
• 布局组件（分隔符、弹性分隔符）的名称和描述
• 极简模式 / Minimalist Mode、模糊搜索组件选择器、Powerline 主题色延续（v2.2.8）
• 上下文窗口、Git 文件状态系列（已暂存 / 未暂存 / 未跟踪 / 干净）、短条形百分比模式、GitLab 支持、Reset Timer 时区/IANA 选择、TUI 环绕导航、refreshInterval 配置（v2.2.10）
• Jujutsu VCS 系列（书签 / 工作区 / 根目录 / 变更 / 增删 / 描述 / 修订）、CompactionCounter 压缩计数、用量时间游标、Reset Timer 绝对时间戳、Powerline 端帽数量解锁、思考力度组件 xhigh 等级（v2.2.12）
• Voice Status 语音状态组件、周 Sonnet / 周 Opus 用量组件、Timer 短进度条、Hook 输出静默（v2.2.13）
• 版本固定全局安装（Pinned global install）、管理安装 / 检查更新菜单、npm 仓库更新检测、固定安装版本不一致防错屏幕（v2.2.14–v2.2.16）
• 超额用量占比 / 超额用量剩余组件（按量付费月度超额额度，支持禁用时隐藏）、用量 API 空值桶兼容、Git 命令旧版本兼容与 --no-optional-locks 锁规避（v2.2.17–v2.2.18）
• Git 子进程输出持久化缓存（可配置 TTL，按 .git/HEAD / .git/index mtime 失效）、CCSTATUSLINE_WIDTH 终端宽度覆盖、固定全局安装设为默认安装项、Windows 隐藏辅助进程窗口（v2.2.19）
• 确认对话框 "是 / 否"
• 分类筛选 "全部" 等界面元素

内部标识符（如 settings.json 中的 widget type ID "model"、"git-branch" 等）保持英文不变，确保与上游版本的配置文件完全兼容。

与上游的差异

项目	ccstatusline	ccstatusline-zh
界面语言	英文	中文
配置兼容性	—	✅ 共用相同 settings.json
功能差异	—	无，功能完全一致
同步版本	最新	v2.2.19（+ jj widgets / CompactionCounter / Voice Status / 版本固定安装 / 超额用量组件 / Git 子进程缓存 / 中文化覆盖）

✨ 功能特性

• 50+ 种可定制组件 — 模型、Git（含 PR / 冲突 / 暂存 / Origin / Upstream / 工作树等细分组件）、Token、上下文、会话、费用、速度等
• 交互式 TUI 配置 — 按 ccstatusline-zh setup 启动可视化配置界面
• Powerline 风格 — 内置多款 Powerline 主题，支持自定义分隔符，支持主题色跨行延续
• 极简模式 — 一键让所有组件切换到"无标签"模式，状态栏更精简
• 模糊搜索组件 — 添加组件时支持子串 / 首字母 / 模糊匹配，带实时高亮
• Claude 账户邮箱 — 状态栏显示当前登录的 Claude 账户邮箱
• 多行布局 — 支持多行状态栏配置
• 实时预览 — 配置时即时预览效果
• 自定义颜色 — 每个组件支持独立的前景色和背景色设置
• 自定义命令 & 文本 & 符号 — 可嵌入自定义 Shell 命令输出、静态文本或单字符符号/Emoji
• 可点击链接 — 支持 OSC8 终端超链接（Git 分支、Git PR、仓库根目录等可配置）
• 跨平台 — 支持 macOS、Linux、Windows

🚀 快速开始

安装

通过 npm 全局安装：

npm install -g ccstatusline-zh

或者使用 Bun：

bun install -g ccstatusline-zh

💡 提示：v2.2.14 起 ccstatusline 增加了「固定版本全局安装」选项，TUI 中选择 固定全局安装 即可锁定当前版本，避免 @latest 跟随上游。详见 TUI 安装流程。

配置 Claude Code

在 Claude Code 设置中添加状态栏配置。编辑 ~/.claude/settings.json：

{
  "statusLine": {
    "type": "command",
    "command": "ccstatusline-zh",
    "padding": 0,
    "refreshInterval": 10
  }
}

如果使用 npx 或 bunx 运行，可以使用以下命令：

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline-zh@latest",
    "padding": 0
  }
}

refreshInterval 仅在 Claude Code ≥ 2.1.97 时生效，TUI 中可设置为 1-60 秒，留空则不写入该字段。

其他支持的 command 取值：

• bunx -y ccstatusline-zh@latest
• ccstatusline-zh（用于自管理 / 全局安装）

如需固定版本，可在 TUI 安装时选择「固定全局安装」，TUI 会全局安装当前版本并将 command 写为 ccstatusline-zh。

启动配置界面

ccstatusline-zh setup

这将打开交互式 TUI 配置界面，你可以：

• 添加、删除、重新排列组件
• 设置颜色和样式
• 选择 Powerline 主题
• 实时预览状态栏效果

🪟 Windows 支持

ccstatusline-zh 完整支持 Windows 系统。安装方式相同：

npm install -g ccstatusline-zh

Windows 下 Claude Code 的配置路径为 %USERPROFILE%\.claude\settings.json。

📖 使用方法

基本用法

安装并配置 statusLine 后，ccstatusline-zh 会在每次 Claude Code 更新状态时自动运行。状态数据通过 stdin 以 JSON 格式传入。

手动测试

cat scripts/payload.example.json | ccstatusline-zh

自定义配置文件路径

ccstatusline-zh --config /path/to/custom-settings.json

命令行参数

参数	说明
setup	启动交互式 TUI 配置界面
--config <path>	指定自定义配置文件路径
--version	显示版本号

🧩 可用组件

核心

组件	说明
模型	显示当前 Claude 模型名称
风格	显示当前输出风格
版本	显示 ccstatusline-zh 版本号
思考力度	显示当前思考力度等级
Vim 模式	显示当前 Vim 模式
语音状态	显示 Claude Code 语音输入是否启用（4 种格式 + Nerd 字体）

Git

组件	说明
Git 分支	显示当前 Git 分支名，支持 GitHub 链接
Git PR	显示当前分支的 PR 信息（链接、状态、标题）
Git 变更	显示未提交的文件变更统计
Git 新增	显示未提交的新增行数
Git 删除	显示未提交的删除行数
Git 状态	汇总状态指示：+暂存 / *未暂存 / ?未跟踪 / !冲突
Git 已暂存	存在已暂存变更时显示 +
Git 未暂存	存在未暂存变更时显示 *
Git 未跟踪	存在未跟踪文件时显示 ?
Git 冲突	显示合并冲突数量
Git 超前/滞后	显示相对 upstream 的提交领先/落后数
Git SHA	显示简短提交哈希
Git Origin 所有者/仓库	显示 origin 远程的 owner / repo
Git Upstream 所有者/仓库	显示 upstream 远程的 owner / repo
Git 是否 Fork	当仓库是 upstream 的 fork 时显示标识
Git 根目录	显示 Git 仓库根目录名
Git 工作树	显示 Git 工作树信息
Git 工作树模式/名称/分支	工作树模式指示与详细信息

Token

组件	说明
输入 Token	显示输入 Token 数量
输出 Token	显示输出 Token 数量
缓存 Token	显示缓存 Token 数量
总 Token	显示 Token 合计

Token 速度

组件	说明
输入速度	显示输入 Token 速度 (tok/s)
输出速度	显示输出 Token 速度 (tok/s)
总速度	显示总 Token 速度 (tok/s)

上下文

组件	说明
上下文长度	显示当前上下文 Token 数
上下文 %	显示上下文使用百分比
上下文 %（可用）	显示可用上下文百分比
上下文进度条	以进度条形式显示上下文用量

会话

组件	说明
会话时钟	显示当前会话持续时间
会话费用	显示当前会话预估费用
会话名称	显示 Claude Code 会话名称
会话用量	显示会话 API 用量
周用量	显示本周 API 用量
周 Sonnet 用量	显示本周 Sonnet 模型 API 用量
周 Opus 用量	显示本周 Opus 模型 API 用量
超额用量占比	显示超额用量（按量付费）占比
超额用量剩余	显示每月超额用量额度的剩余金额（美元）
时段计时器	显示当前 5 小时时段已用时间
时段重置计时	显示时段重置窗口剩余时间
周重置计时	显示周重置剩余时间
Claude 会话 ID	显示当前 Claude 会话 ID
Claude 账户邮箱	显示当前登录的 Claude 账户邮箱
技能	显示 Claude Code 技能调用信息

环境

组件	说明
当前目录	显示当前工作目录
终端宽度	显示终端列数
内存用量	显示系统内存使用情况

自定义

组件	说明
自定义文本	显示用户自定义文本
自定义命令	执行 Shell 命令并显示输出
自定义符号	显示自定义单字符符号或 Emoji
链接	显示可点击的终端超链接

布局

组件	说明
分隔符	组件之间的固定分隔符
弹性分隔符	自动填充剩余空间的弹性分隔符

🖥️ 配置界面（TUI）

运行 ccstatusline-zh setup 打开交互式配置界面。

主菜单功能

• 编辑状态栏 — 添加、删除、移动、配置组件
• Powerline 设置 — 选择主题和自定义分隔符
• 全局样式覆盖 — 设置全局颜色和样式
• 终端选项 — 配置终端宽度和颜色级别
• 配置状态行 — 配置 Claude Code 状态行刷新间隔（Claude Code ≥ 2.1.97）
• 安装到 Claude Code — 选择自动更新 / 固定全局安装两种方式
• 管理安装 — 已固定安装时可检查 npm 更新、运行全局更新命令、卸载
• 检查更新 — 查询 npm 仓库最新版本并对比当前版本

快捷键

按键	功能
↑ ↓	导航
Enter	选择/确认
a	添加组件
d	删除组件
e	编辑组件
w	组件选项
/	搜索
q	退出

📡 API 文档

详细的 API 文档和 JSON Payload 格式说明请参考上游项目：

👉 ccstatusline API Documentation

🛠️ 开发指南

环境要求

• Bun >= 1.0
• Node.js >= 14.0.0

本地开发

# 克隆仓库
git clone https://github.com/huangguang1999/ccstatusline-zh.git
cd ccstatusline-zh

# 安装依赖
bun install

# 运行示例
bun run example

# 启动 TUI
bun run start setup

# 构建
bun run build

# 代码检查
bun run lint

项目结构

src/
├── ccstatusline.ts          # 入口文件
├── widgets/                 # 组件目录（72 个组件）
│   ├── Model.ts
│   ├── GitBranch.ts
│   ├── TokensInput.ts
│   ├── shared/              # 共享工具函数
│   └── ...
├── tui/                     # TUI 配置界面
│   ├── App.tsx
│   └── components/          # 界面组件
├── utils/                   # 工具函数
└── types/                   # 类型定义

🙏 致谢

• ccstatusline — 原始项目，由 sirmalloc 开发维护
• Claude Code — Anthropic 的 CLI 编码助手
• Ink — React 终端渲染框架

📄 许可证

本项目遵循 MIT 许可证，与上游项目保持一致。

如果这个汉化版对你有帮助，欢迎 ⭐ Star！

上游项目 · 问题反馈