ccstatusline-zh

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

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

本项目是 ccstatusline 的中文汉化 Fork，当前中文包版本为 2.2.31，同步至上游 v2.2.30 + main@35440e4（2026-09-28 核对，包含自定义命令缓存、终端宽度探测优化、用量修复和配置界面按需加载）。所有用户可见的界面文本（组件名称、分类、描述、菜单标签、提示信息等）均已翻译为中文，方便中文用户使用。

上次同步的完整上游提交：35440e4a93ac8aba7e57973ac004a68adcc51089。后续同步以此提交为基线，中文包与上游版本号独立递增。

📚 目录

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

🌏 关于本项目

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

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

• 88 个组件的名称、描述、分类标签（含 v2.2.13 新增的 Voice Status / 周 Sonnet 用量 / 周 Opus 用量，v2.2.17 新增的超额用量占比 / 超额用量剩余，v2.2.20 新增的 Remote Control Status，v2.2.22 新增的缓存命中率 / 缓存读取 / 缓存写入 / 超额已用，v2.2.24 新增的缓存计时器 / Git CI 状态 / 沙箱状态，v2.2.26 新增的周 Fable 用量）
• 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）
• 缓存计时器 / Git CI 状态 / 沙箱状态组件、单侧默认内边距、选择性 Powerline 对齐、Git 分支与根目录宽度限制、当前目录字符、可配置上下文窗口兜底值、可组合压缩指标、--version 参数、用量缓存与加载态修复、异步 Git PR/CI 检查刷新（v2.2.23–v2.2.25）
• 周 Fable 用量组件、迁移账号的 limits[] 用量 API 兼容、压缩后上下文长度修正、隐藏组件分隔符保留、配置导入/导出及差异预览（v2.2.26–v2.2.27）
• Claude 服务状态及 48 小时故障历史、统一隐藏条件与旧配置自动迁移、按组件和数值类型设置显示精度、大转录文件流式读取与单次扫描、Git 冲突为零时的显示选项、用量锁与 Git 临时文件恢复修复（上游 v2.2.28–v2.2.29）
• 自定义命令可选输出缓存与超时控制、终端宽度探测优化及失败结果缓存、更多 Git / Jujutsu 组件符号定制、重置计时器无数据时隐藏、macOS 按配置目录选取用量凭据、访问令牌刷新时保留用量缓存、模型周额度为零时正确显示、新配置默认使用完整终端宽度、Git 命令 5 秒超时、配置界面按需加载（上游 v2.2.30 + main@35440e4）
• 确认对话框 "是 / 否"
• 分类筛选 "全部" 等界面元素

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

与上游的差异

✨ 功能特性

• 88 种可定制组件 — 模型、Git（含 PR / CI / 冲突 / 暂存 / 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 安装流程。

固定全局安装可省去每次状态栏重绘时的包解析。上游在 Windows 的测量显示，bunx ...@latest 每次都会重新解析版本标签，耗时高于固定版本；如果重绘延迟明显，优先使用固定全局安装。

配置 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 格式传入。

隐藏条件与数值格式

在组件编辑器中按 h 打开该组件支持的隐藏条件，使用空格切换并按 Enter 保存。例如，无 Git 仓库、无用量数据、数值为零时可以隐藏组件；已有隐藏选项会自动迁移。装饰文本和符号还可跟随合并目标隐藏。

数值组件按 . 循环切换固定小数、紧凑和整数格式；全局覆盖菜单按 n，可分别设置令牌、速度、占比、内存和费用。全局设置优先于组件设置，settings.json 中还可通过 decimals 指定 0–6 位小数。

Claude 服务状态组件按 h 切换故障历史。中文状态用于界面显示，纯值模式保留 ok、minor 等上游状态值，兼容脚本读取。

手动测试

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），以及 Git、自定义命令和终端宽度的缓存时长
• 导出配置 — 将当前配置保存为 JSON 文件，用于备份或分享
• 导入配置 — 从 JSON 文件加载配置并预览替换或合并后的差异
• 安装到 Claude Code — 选择自动更新 / 固定全局安装两种方式
• 管理安装 — 已固定安装时可检查 npm 更新、运行全局更新命令、卸载
• 检查更新 — 查询 npm 仓库最新版本并对比当前版本

快捷键

重置计时器可按 h 设置无数据时隐藏；日期模式下按 f 切换 12/24 小时格式，周重置计时器在时间模式下按 o 切换仅显示小时。

自定义命令缓存默认关闭，可设置为 0–60 秒；终端宽度探测失败结果默认缓存 5 秒，可设置为 0–300 秒，填 0 关闭缓存。已检测到的宽度会在下次渲染时重新检测。新配置默认使用完整终端宽度，已有 flexMode 设置保持不变。

📡 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/                 # 组件目录（87 个组件）
│   ├── Model.ts
│   ├── GitBranch.ts
│   ├── TokensInput.ts
│   ├── shared/              # 共享工具函数
│   └── ...
├── tui/                     # TUI 配置界面
│   ├── App.tsx
│   └── components/          # 界面组件
├── utils/                   # 工具函数
└── types/                   # 类型定义

🙏 致谢

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

📄 许可证

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

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

上游项目 · 问题反馈