状态栏命令与 JSON 输入

用脚本格式化 stdin 状态，处理缺失字段、刷新定时与五秒超时。

This page has not been translated into English yet. The original Chinese version is shown below.

Command 模式把结构化会话状态写入命令 stdin，并把 stdout 最多两行显示在 footer。它适合自定义格式，不能把昂贵任务直接放入频繁刷新路径。

最小例子

以下配置需要已有 jq，只显示模型名：

{
  "ui": {
    "statusLine": {
      "type": "command",
      "command": "jq -r '.model.display_name'",
      "respectUserColors": false,
      "hideContextIndicator": false
    }
  }
}

respectUserColors 默认 false，true 保留命令 ANSI 颜色。命令输出不会自动分析是否已包含上下文，所以 hideContextIndicator 默认 false；重复显示时需自行设置 true。

输入字段

结构	内容
session_id、version	会话与产品版本
model.display_name	当前模型名
context_window	context_window_size、used_percentage、remaining_percentage、current_usage、total_input_tokens、total_output_tokens
workspace.current_dir	当前工作目录
git.branch	仅仓库内提供 git 对象
worktree	活动 worktree 的 name、path、branch、original_cwd、original_branch
metrics.models	每模型 API 次数/错误/耗时与 prompt、completion、total、cached、thoughts token
metrics.files	total_lines_added、total_lines_removed
vim.mode	启用 Vim 时的 INSERT / NORMAL

worktree 仅在对应活动 worktree 上下文提供，不能假设对象总存在。current_usage 来自上次 API 的当前上下文，累计输入输出另有字段。读取 git.branch 可直接用输入，不必每次再执行 Git。

stdin 只能消费一次。复杂脚本先保存 input=$(cat)，再解析同一变量；不要串联多次独立读取 stdin 并期待每次都有完整 JSON。

刷新与 shell

一般状态变动会触发运行；时钟、外部配额等不伴随 agent 事件的数据可设 refreshInterval，单位秒，最小一秒。

macOS/Linux 使用 /bin/sh，Windows 默认 cmd.exe。脚本使用 Bash 专有语法时应明确调用 bash，不要假定 sh 或 cmd 支持。复杂逻辑可放脚本文件，在 command 中引用。

超过五秒的命令会被终止，失败时状态栏清空。先用合法 JSON 手动测试脚本，确认字段缺失时仍能输出；频繁调用的重工作应另做缓存，状态栏只读取结果。

配置必须位于 ui.statusLine，根级 statusLine 不生效。它与Hook 执行器的 shell、超时和输出协议不同，不能照搬 Hook 参数。