附录 B 命令与配置速查

附录 B 命令与配置速查

本速查覆盖全书后半本用到的命令、配置与环境变量。全部条目基于 v0.41.0，写法示意，以官方文档为准——尤其子命令名、参数名与环境变量名，升级版本后必须逐项核对（第 11.1 节清单）。

一、安装与依赖

# install_headroom.sh —— 安装姿势（基于 v0.41.0，写法示意，以官方文档为准）
pip install headroom==0.41.0        # 精确锁定版本（0.x 纪律）
pip install "headroom[onnx]"        # 可选依赖组：本地推理等 extras 名称以官方文档为准
​

依赖环境变量（第 11.2 节）：

二、接入命令

# wrap_commands.sh —— 一键接入与撤销（基于 v0.41.0，写法示意，以官方文档为准）
headroom wrap claude-code      # 包装 Claude Code；zcode、codex、grok 等同理
headroom wrap --list           # 查看受支持名单与已包装状态
headroom unwrap claude-code    # 撤销包装并还原配置
headroom proxy --port 8787     # 启动本地转发进程；应用改指向该地址即可
​

18 个受支持 Agent（官方口径，v0.41.0）：Claude Code、Codex、Grok、Cursor（手动）、Aider、Copilot CLI、Copilot VS Code、OpenClaw、OpenCode、Cline、Continue、Goose、OpenHands、Mistral Vibe、Oh My Pi、Kimi CLI、Cortex Code、ZCode。

三、观测与评测命令

# observe_and_bench.sh —— 观测四件套与基准（基于 v0.41.0，写法示意，以官方文档为准）
headroom savings                                   # 累计节省读数
headroom dashboard                                 # 面板
headroom perf                                      # 压缩层性能开销
headroom doctor                                    # 环境与依赖体检（排错第一现场）
headroom bench --seed 20260902 --scenario sre-debug # 复现四场景基准（场景名示意）
​

四场景基准读数（官方自测口径）：代码搜索 21%、SRE 调试 57%、代码库探索 42%、issue 分诊 30%。

四、关键配置形态

# headroom_cache.yaml —— 缓存协同配置（基于 v0.41.0，写法示意，以官方文档为准）
compression:
  mode: cache          # 缓存协同模式：live-zone 追加式压缩
  live_zone: true      # 新增字节先压缩再并入冻结前缀
cache_aligner:
  enabled: true        # 只标记易变内容，从不改写 prompt
telemetry:
  prometheus: true     # 指标输出供第 10 章观测
​

# output_shaper.sh —— 输出侧治理总开关（默认关）
export HEADROOM_OUTPUT_SHAPER=1    # 开启 verbosity steering + effort routing
​

五、SDK 集成形态对照

六、记忆与学习命令

# memory_commands.sh —— 记忆与学习（基于 v0.41.0，写法示意，以官方文档为准）
headroom learn --dry-run            # 挖掘失败会话，只出候选纠正清单
headroom learn --write agents-md    # 人审通过后写入指定项目记忆文件（参数示意）
​

项目记忆文件四个落点：CLAUDE.local.md（个人本地）、CLAUDE.md（Claude 系共享）、AGENTS.md（跨工具通用）、GEMINI.md（Gemini 系）。

七、MCP 工具族

wrap 联装 Serena（语义代码导航，可关闭）。Headroom 自身提供 MCP 工具族，其中检索工具为 headroom_retrieve；工具族完整名单与启用方式以官方文档为准。

八、口径速记

• 收益与性能数字：官方自测口径或官方口径；本书构造的演示数字：示意值。
• 星数类热度数字：社区口径、增速需甄别。
• 输出侧节省 31.7%（95% CI 27.7~35.7%）：官方口径，自标估计值。
• SharedContext 约 80% 降低：官方口径，有适用条件（第 8.2 节）。
• 所有引用复现工具：seed 20260902、四场景基准、10% holdout 对照（第 10 章）。