ccstatusline-zh 配置文件与 JSON Payload 参考指南：settings.json 字段逐项解析-北京尧图网络

【免费下载链接】ccstatusline-zhccstatusline 的中文汉化版 - Claude Code CLI 可定制状态栏格式化工具项目地址https://gitcode.com/gh_mirrors/cc/ccstatusline-zh点击查看免费下载ccstatusline-zh是 Claude Code CLI 的可定制状态栏格式化工具中文汉化版支持 90 种组件、Powerline 主题与交互式 TUI 配置。本文带你逐项读懂它的两个核心 JSON状态栏自身的settings.json配置文件以及 Claude Code 每次通过 stdin 传入的状态数据 Payload。一、先分清两个 settings.json新手最容易混淆的一点ccstatusline-zh 涉及两个不同的 settings.json路径和用途完全不同。文件路径Linux/macOS作用Claude Code 的状态栏挂载配置~/.claude/settings.json告诉 Claude Code「用哪个命令渲染状态栏」ccstatusline-zh 自己的外观配置~/.config/ccstatusline/settings.json定义组件、颜色、分隔符、Powerline 等Windows 下对应%USERPROFILE%\.claude\settings.json和%USERPROFILE%\.config\ccstatusline\settings.json。在 Claude Code 侧只需写一小段{ statusLine: { type: command, command: ccstatusline-zh, padding: 0, refreshInterval: 10 } }padding控制状态栏上下留白refreshInterval1–60 秒仅 Claude Code ≥ 2.1.97 生效控制刷新频率。这个文件由 TUI 的「安装到 Claude Code」菜单自动写入一般无需手写。二、ccstatusline 的 settings.json 顶层字段真正需要动手的是~/.config/ccstatusline/settings.json。仓库自带的 official-cc.json 就是一份完整的导出配置样例。顶层字段如下字段类型默认值含义version数字4配置 schema 版本旧版本配置首次加载时自动迁移lines二维数组3 行状态栏的布局最多 3 行每行是一个组件数组flexMode字符串full终端宽度处理方式见下文compactThreshold数字60full-until-compact模式下的切换阈值上下文百分比colorLevel0–32颜色能力0 无颜色 / 1 16 色 / 2 256 色 / 3 TruecolordefaultSeparator字符串—组件之间自动插入的分隔符字符defaultPadding/defaultPaddingSide字符串both组件默认内边距及作用侧both/left/rightinheritSeparatorColors布尔false分隔符是否继承前一个组件的颜色globalBold布尔false全局加粗overrideForegroundColor/overrideBackgroundColor字符串—强制全局前景/背景色支持gradient:渐变色minimalistMode布尔false极简模式所有组件切换为无标签纯值显示numberFormat对象—按数值类型全局设置显示精度见下文gitCacheTtlSeconds0–605Git 子进程输出的缓存时长0表示按.git/HEAD/index变化失效customCommandCacheTtlSeconds0–600自定义命令输出的缓存时长0表示每次渲染都执行terminalWidthCacheTtlSeconds0–3005终端宽度探测失败结果的缓存时长0表示每次重探测powerline对象见下Powerline 主题与分隔符配置exportedBy字符串—导出时记录的工具版本号导入时会被忽略三个 TTL 字段中「0 的含义各不相同」是常见坑Git 缓存的 0 是永不过期靠文件修改时间失效而终端宽度和自定义命令的 0 是关闭缓存。flexMode的三种取值取值行为full始终使用完整终端宽度默认可能因自动压缩提示而换行full-minus-40始终预留 40 字符防止自动压缩消息导致换行full-until-compact动态切换上下文占比超过compactThreshold时才预留 40 字符numberFormat全局精度可在 NumberFormat.ts 中找到定义numberFormat: { token: { style: compact, decimals: 2 }, cost: { style: precise } }五种类别token令牌、speed速度、percent占比、memory内存、cost费用style三种precise保留尾零如1.0M、compact去掉无效尾零如1.1M、whole整数如1Mdecimals可设 0–6 位小数全局设置优先于单个组件的设置。三、lines 中的组件字段逐项解析lines是二维数组外层最多 3 个元素代表 3 行内层数组是该行按顺序渲染的组件。每个组件是一个对象所有可用字段定义在 Widget.ts字段说明id组件唯一标识TUI 自动生成 UUID勿手动重复type组件类型 ID保持英文如model、git-branch、context-bar、custom-commandcolor/backgroundColor前景色 / 背景色支持cyan等命名色及gradient:渐变bold是否加粗dim暗淡样式true整体暗淡parens仅括号内暗淡numberFormat单组件数值格式结构同全局numberFormatrawValue纯值模式去掉标签只显示数值如Ctx: 18.6k→18.6kcharacter自定义分隔符字符用于separator类型customText/customSymbol自定义文本 / 单字符符号或 EmojicommandPath自定义命令要执行的 Shell 命令maxWidth输出最大宽度超过则截断preserveColors自定义命令是否保留 ANSI 颜色timeout自定义命令超时毫秒默认 1000merge与前一组件合并显示true或no-paddingexcludeFromAutoAlignPowerline 自动对齐时排除该组件布尔metadata组件专属选项字符串键值对见下组件 IDtype与中文名对照可参考 README 的组件清单例如model 模型、git-branch Git 分支、session-cost 会话费用。汉化版只翻译了界面文字配置字段始终与上游兼容。metadata里常见的高频键metadata是各组件自己的「选项区」不同组件支持的键不同全部为字符串值。源码中实际用到的键包括键用途出现场景hide隐藏条件逗号分隔列表如no-git,zero几乎所有组件按h配置display/format显示模式如进度条长/短、图标文本等上下文条、计时器、语音状态等label覆盖标签文字按e编辑前缀支持标签的组件nerdFont是否使用 Nerd Font 图标语音、Vim 模式、沙箱状态invert/inverse反转进度条填充方向计时器、进度条类cursor进度条时间游标用量条fishStyle/abbreviateHome/segments路径风格、主目录缩写、分段限制当前工作目录linkToIDE根目录链接到 VS Code / CursorGit 根目录url/text超链接目标与显示文字链接组件OSC 8timezone/locale/hour12/absolute/weekday时区、区域、12/24 小时制、绝对时间戳重置计时器historyClaude 服务状态附 48 小时故障历史条Claude StatusttlSeconds缓存计时器 TTL5 分钟 / 1 小时Cache Timerwindow速度组件滚动窗口0–120 秒0 全会话均值Input/Output/Total SpeedweekdaysOnly超额每日预算是否只计工作日Extra Usage Daily Budgethide字段的典型取值no-git无 Git 仓库时隐藏、zero数值为零时隐藏、no-data无数据占位符时隐藏、not-fork、empty等。旧版本中分散在各组件的hideNoGit、hideZero等布尔键首次加载时会由迁移逻辑自动转换为统一的hide键见 migrations.ts。一份真实组件片段摘自 personal-cc.json{ id: 5, type: git-branch, color: magenta }更复杂的例子当前目录纯值 fish 风格路径{ id: 7c3459f2-..., type: current-working-dir, rawValue: true, metadata: { fishStyle: true } } 建议绝大多数场景直接用ccstatusline-zh setup启动 TUI 图形化编辑settings.json主要用于备份、跨机器迁移和进阶微调。四、powerline 配置块Powerline 模式弧形分隔符风格效果见 screenshots/powerline-flex.png由powerline对象控制定义在 PowerlineConfig.ts字段默认说明enabledfalse是否启用 Powerline 渲染separators[\uE0B0]分隔符字形数组Nerd Font 字符separatorInvertBackground[false]对应每个分隔符是否反转背景色startCaps/endCaps[]行首/行尾端帽字形theme—内置主题名TUI 中「Powerline 设置」选择autoAlignfalse多行组件按共享列自动对齐continueThemeAcrossLinesfalse主题色跨行延续Powerline 模式下手动分隔符会被禁用但弹性分隔符flex-separator仍可作为布局占位使用。五、配置的安全机制损坏不会覆盖你的文件加载逻辑在 config.ts值得了解三点文件缺失首次运行→ 自动写入内置默认配置JSON 损坏或格式无效→ 保留原文件不动本次运行回退到内存默认值并在状态栏前置一个「无效配置」警告徽标TUI 中也会提示需你确认后才允许覆盖旧版本配置→ 自动迁移到当前版本当前version: 4且只有迁移结果校验通过后才会写回磁盘。保存采用「临时文件原子重命名」并发读取不会读到写了一半的文件0600等私有权限也会被保留。导入 / 导出TUI 主菜单的「导出配置」会写入 JSON默认~/ccstatusline-zh-config.json带exportedBy版本标记「导入配置」支持替换或合并两种模式合并时只覆盖文件中显式存在的字段且新增 Shell 命令会完整展示并要求确认默认选取消防止误执行来路不明的命令。六、JSON Payload 参考Claude Code 传入什么数据ccstatusline-zh 以管道模式运行时Claude Code 会向 stdin 传入一段 JSON工具据此渲染状态栏。完整示例见 payload.example.json其 schema 定义在 StatusJSON.ts顶层字段内容供哪些组件使用hook_event_name事件名固定Status—session_id会话 IDClaude 会话 IDtranscript_path会话转录 JSONL 文件路径Token 累计、会话时钟、压缩计数等cwd/workspace当前目录 / 项目目录当前目录、Git 组件model模型 ID 与显示名字符串或对象模型、上下文窗口推断versionClaude Code 版本版本相关组件output_style当前输出风格风格组件effort.level思考力度low/medium/high/xhigh/max思考力度costtotal_cost_usd、total_duration_ms、total_api_duration_ms、total_lines_added/removed会话费用、费用速率context_window窗口大小、累计/当前输入输出 Token、缓存读写 Token、已用/剩余百分比上下文系列、Token 系列、缓存系列rate_limitsfive_hour/seven_day/seven_day_sonnet/seven_day_opus的used_percentage与resets_atUnix 秒时段/周用量、重置计时器vim.modeVim 模式如NORMALVim 模式worktree工作树名称/路径/分支/原始分支Git 工作树系列几个实用细节数字字段允许传字符串工具会自动做数字 coercion旧版 Claude Code 传格式略有差异也能正常解析自定义命令组件收到的是同一份 JSON 额外注入的terminal_width字段检测到的终端列宽方便脚本自适应输出用量类数据周用量、超额用量等不在这份 Payload 里而是 ccstatusline-zh 主动调用用量 API 获取并缓存。手动测试 Payload不启动 Claude Code 也能验证配置效果cat scripts/payload.example.json | ccstatusline-zh想用自己的配置文件测试时加上--configcat scripts/payload.example.json | ccstatusline-zh --config ./my-settings.json七、快速上手清单npm install -g ccstatusline-zh全局安装ccstatusline-zh setup启动 TUI完成「安装到 Claude Code」自动生成~/.claude/settings.json挂载项在 TUI 中按需添加组件、调颜色、选 Powerline 主题所有修改最终落盘到~/.config/ccstatusline/settings.json跨机器迁移用「导出配置 / 导入配置」直接拷贝 JSON 也可以旧版本字段会自动迁移遇到状态栏空白先确认该工作区已被 Claude Code 信任详见 docs/USAGE.md 的排查章节再检查settings.json是否为合法 JSON。想深入每个组件的显示模式与快捷键建议通读 docs/USAGE.md配置文件默认值则以 Settings.ts 中的 schema 为准。赞分享【免费下载链接】ccstatusline-zhccstatusline 的中文汉化版 - Claude Code CLI 可定制状态栏格式化工具项目地址https://gitcode.com/gh_mirrors/cc/ccstatusline-zh点击查看免费下载相关推荐its-matrix-computation硬件配置完全参考昇腾910B1 JSON参数逐字段详解its matrix computation硬件配置完全参考昇腾910B1 JSON参数逐字段详解 its matrix computationSimNPU高性能计算CANNregnetx_160.tv2_in1k 配置参考config.json 与 pretrained_cfg 字段逐项详解完整指南regnetx_160.tv2_in1k 配置参考config.json 与 pretrained_cfg 字段逐项详解完整指南 regnetx_160.ESP32-S2 驱动 SSD1963TFT_eSPI 一次点亮的 4 个坑ESP32 S2 驱动 SSD1963TFT_eSPI 一次点亮的 4 个坑 5 英寸 SSD1963 屏接到 ESP32 S2 DevKitC 1 上刷完嵌入式GUI图形学上一篇mincss常见问题解答解决90%的使用难题下一篇Amaze UI npm包发布指南分享你的自定义组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ccstatusline-zh 配置文件与 JSON Payload 参考指南：settings.json 字段逐项解析

相关推荐

洛雪音乐桌面版：跨平台免费开源音乐聚合播放器，五源合一还能接脚本

qptp 时间同步流程

车道识别模型---Unet环境部署和个人数据集训练教程

更多资讯

一文理清 Excel 只读：分清类型，轻松解除

别只调Prompt了！大模型落地避坑指南：从Prompt→Context→Harness的进阶之路

Personal Agent的技术底座与落地边界

【文献泛读】SplatFlow: Self-Supervised Dynamic Gaussian Splatting in Neural Motion FlowField for Aut｜2025

高卫国版《数值线性代数》和Trefethen版《Numerical Linear Algebra》两本教材的详细对比

2026—10-27

今日更新

微信个人号API开发案例：图片/语音/视频消息怎么下载解析存到本地？

Python股票自动交易系统源码解析：从行情获取到风控的完整链路

视酷酷信IM源码部署指南：Java 17+MySQL 8.0.33实战配置

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？