ccstatusline-zh

ccstatusline-zh

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

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

本项目是 ccstatusline 的中文汉化 Fork，当前同步至上游 v2.2.22 版本（含缓存命中率 / 缓存读写组件、超额已用组件、压缩计数 compact_boundary 精准检测、弹性分隔符 Powerline 渲染修复等最新功能）。所有用户可见的界面文本（组件名称、分类、描述、菜单标签、提示信息等）均已翻译为中文，方便中文用户使用。

📚 目录

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

🌏 关于本项目

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

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

• 77 个组件的名称、描述、分类标签（含 v2.2.13 新增的 Voice Status / 周 Sonnet 用量 / 周 Opus 用量，v2.2.17 新增的超额用量占比 / 超额用量剩余，v2.2.20 新增的 Remote Control Status，v2.2.22 新增的缓存命中率 / 缓存读取 / 缓存写入 / 超额已用）
• 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）
• Remote Control Status 远程控制状态组件、渐变色前景色支持、周重置计时器星期显示模式、Windows npm shim 执行修复、超额用量单位换算修正、Input/Output Token 组件优先使用累计转录指标、UsageFetch 缓存隔离改进（v2.2.20）
• 缓存命中率 / 缓存读取 / 缓存写入（Cache Hit Rate / Cache Read / Cache Write）、超额已用组件（Extra Usage Used）、压缩计数改用 compact_boundary 标记精准检测（不再依赖上下文百分比推断）、弹性分隔符 Powerline 路径修复、可覆盖字符字形（Glyph override）、每组件暗淡样式（整体暗淡 / 括号暗淡）、invalid settings.json 非破坏性恢复与警告（v2.2.21–v2.2.22）
• 确认对话框 “是 / 否”
• 分类筛选 “全部” 等界面元素

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

与上游的差异

✨ 功能特性

• 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

命令行参数

🧩 可用组件

核心

Git

Token

Token 速度

上下文

会话

环境

自定义

布局

🖥️ 配置界面（TUI）

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

主菜单功能

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

快捷键

📡 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 许可证，与上游项目保持一致。