Environment

Environment

• Python: use uv run python (not python3 — modules not available outside venv)

### 2. 文件路径纠正 → CLAUDE.md

模型反复猜错的错误路径，以及正确位置：

```markdown
### File Path Corrections
- `axion-common/src/.../AxionSparkConstants.scala`
  → actually at `axion-spark-common/src/.../AxionSparkConstants.scala`

3. 搜索范围 → CLAUDE.md

哪些目录该搜（过窄的路径会失败，更宽的才能命中）：

### Search Scope
- Don't search `axion-model/` → use `axion/` (the repo root)

4. 命令模式 → CLAUDE.md

命令应该如何（以及不应该如何）执行：

### Command Patterns
- **user_prefers_manual**: User rejected gradle 18 times — show the command, don't execute
- **python_runtime**: Use `uv run python` not `python3` (ModuleNotFoundError)

5. 已知大文件 → CLAUDE.md

读这些文件时必须用 offset/limit：

### Known Large Files
- `proxy/server.py` (~8000 lines) — always use offset/limit

6. 重试预防 → MEMORY.md

从实际纠正推导出的具体建议，防止同样的无效重试。

7. 权限备注 → MEMORY.md

被反复拒绝的命令——模型应改为向用户"建议"而不是直接执行。

6. 经验写到哪里：Agent 原生的上下文文件

经验类型	Claude Code	Codex	Gemini CLI
环境、路径、命令	CLAUDE.local.md（默认）或 CLAUDE.md（--target CLAUDE.md）	AGENTS.md	GEMINI.md
重试模式、权限	MEMORY.md	instructions.md	GEMINI.md

产出文件是 agent-native 的：Claude Code 默认写 CLAUDE.local.md（被 git 忽略、属于个人）；想落到团队共享文件时传 --target CLAUDE.md。同一份经验，用各 Agent 各自会读取的文件格式落地。

7. 基于 Marker 的更新：重复运行不产生重复内容

Headroom 在每个文件中管理一个清晰定界的区块（实现见 writer.py）：

<!-- headroom:learn:start -->
## Headroom Learned Patterns
*Auto-generated by `headroom learn` — do not edit manually*
...
<!-- headroom:learn:end -->

再次运行时，只有 marker 之间的内容被替换，文件其余部分原样保留。源码中有两处细节值得注意：

1. 合并语义：_merge_recommendations 会把上一次运行中、本次没有再出现的 section 保留下来（"carried forward"），即重跑不会悄悄丢掉已积累的经验；同名的 section 以最新一次分析为准。想完全重建区块，手动删除该区块后重跑即可。
2. 容错读取：_read_text_tolerant 用 UTF-8 宽松解码读取既有上下文文件，避免文件中混入一个 cp1252 杂字节（如 em-dash 的 0x97）就导致整个 --apply 中断；写回时以 UTF-8 重新编码完成自我修复。

对应测试覆盖在 tests/test_learn/test_writer.py 与 tests/test_learn/test_integration.py。

8. 插件架构：每个 Agent 一个自包含插件

Plugin Registry (auto-discovered)
├── ClaudeCodePlugin  →  Analyzer (LLM)  →  ClaudeCodeWriter  →  CLAUDE.md / MEMORY.md
├── CodexPlugin       →  Analyzer (LLM)  →  CodexWriter       →  AGENTS.md / instructions.md
├── GeminiPlugin      →  Analyzer (LLM)  →  GeminiWriter      →  GEMINI.md
└── (your plugin)     →  Analyzer (LLM)  →  (your writer)     →  (your file)

注册表与自动发现（registry.py）分两层：

1. 内置插件：遍历 headroom.learn.plugins.* 子模块，凡模块顶层暴露 plugin = 插件实例 的即被注册（当前内置 claude、codex、gemini、grok、opencode 五个）；
2. 外部插件：通过 headroom.learn_plugin entry point 组注册，同名时外部插件覆盖内置插件；加载失败的插件只记 warning，不影响整体。

Analyzer 是共享的：所有 Agent 复用同一个 LLM 分析器，分析逻辑与 Agent 无关。

为新的 Agent 添加支持

按 base.py 中的示例：

1. 创建 headroom/learn/plugins/myagent.py；
2. 实现 LearnPlugin + ConversationScanner（扫描器 + 写入器工厂 + 检测）；
3. 在模块作用域加 plugin = MyAgentPlugin()；
4. 完成——headroom learn --agent myagent 自动可用（--agent 的取值由注册表动态校验，见 cli/learn.py 的 _AgentChoice）。

或者安装外部插件包（通过 entry point 注册，例如文档中的 pip install headroom-learn-cursor）。

支持的 Agent 一览

Agent	扫描源	写入器	输出文件
Claude Code	~/.claude/projects/*.jsonl	ClaudeCodeWriter	CLAUDE.md, MEMORY.md
OpenAI Codex	~/.codex/sessions/*.json	CodexWriter	AGENTS.md, instructions.md
Gemini CLI	~/.gemini/tmp/*/chats/session-*.json	GeminiWriter	GEMINI.md
Grok CLI	~/.grok/sessions/<workspace>/<session-id>/updates.jsonl	GrokWriter	GROK.md
OpenCode	SQLite 数据库 ~/.local/share/opencode/opencode.db（或 opencode-local.db；可用 HEADROOM_OPENCODE_DB 覆盖）	CodexWriter（共享）	AGENTS.md, instructions.md

9. CLI 完整参考

headroom learn [OPTIONS]

Options:
  --project PATH               项目目录（默认：当前目录）
  --all                        分析所有已发现的项目（与 --project 互斥）
  --apply                      写入推荐（默认：dry-run）
  --target TEXT                写入的目标上下文文件（Claude Code 默认 CLAUDE.local.md）
  --main-only                  只扫描顶层主会话，跳过嵌套的 subagent/workflow 转录
  --agent [auto|claude|codex|gemini|grok|opencode]
                               要分析的 Agent（默认：auto 自动检测）
  --model TEXT                 分析用 LLM（默认：从 API key 或已装 CLI 自动检测）
  --workers / -j INTEGER       并行分析 worker（最小 1，默认：min(CPU 核数, 8)）
  --verbosity                  分析输出冗长度级别而非失败模式
  --llm-judge                  用 LLM 对冗长度质量评分（需配合 --verbosity）

几个源码层面可以补充的确定性行为：

• 参数组合的前置校验：--all 与 --project 互斥、--llm-judge 必须配合 --verbosity，违反时直接抛出 click.UsageError（learn.py）；--verbosity --all --apply 也会被拒绝，因为 verbosity 只持久化一个全局级别；
• --main-only 的当前语义（以 CLI 帮助文本 为准）：只扫描顶层主会话、跳过 Claude Code 嵌套的 subagent/workflow 转录；默认扫描全部；
• --workers 默认值为 min(os.cpu_count(), 8)（learn.py），传 1 可强制串行；
• 跨 Agent 容错：auto 模式下某个 Agent/项目扫描失败只打印警告并跳过，不会中断整轮分析（learn.py）；
• 项目定位：不带 --project 时先匹配当前目录，未命中则逐级向上匹配父目录（learn.py），未找到时会列出可用项目提示你改用 --all 或 --project。

10. 冗长度学习（--verbosity）

headroom learn --verbosity 走的是另一条独立流程：不分析失败，而是从行为信号推断你偏好的输出冗长度（1–4 级：1=轻省略、2=无客套+不复读、3=只给结论、4=电报式碎片），并写入 verbosity.json 配置档。

它的行为信号提取逻辑见 verbosity.py，几个关键设计：

• 中断率（interrupt rate）：用户在回答中途打断的比例（解析 [Request interrupted by user 标记），是"太啰嗦"的推力信号；
• 快速跳过率（fast-skip rate）：回复在"读完整段答案所需时间的一半"之前到达，说明用户根本没读完。阈值是长度自适应的（按 250 词/分钟的阅读速度换算，而非固定秒数），且只对 ≥150 词的回答计分；
• 复读率（echo ratio）：输出中复述已有上下文的比例（回看最近 4 条消息）。

--apply 时的副作用与限制（原文档强调，源码 learn.py 印证）：

1. 写出 verbosity.json（级别档）与 output_savings.json（分层基线，作为输出节省度量的合成对照组）；
2. 输出整形器（output shaper）默认是关闭的，且需要 beta 运行时灰度通道。--verbosity --apply 会尝试对本地运行中的代理热开启（POST /admin/runtime-env）；如果代理不存在或被通道拦截，则打印提示：需先 export HEADROOM_ROLLOUT_CHANNEL=beta 和 HEADROOM_OUTPUT_SHAPER=1，再执行 headroom wrap ...；
3. 想让整形器跨代理重启保持开启，需在启动代理前导出上述两个环境变量。

标志位交互（与第 9 节校验逻辑一致）：--llm-judge 需要 --verbosity；--verbosity --all --apply 被拒绝；--target、--main-only、--workers 等在 verbosity 模式下会被显式提示忽略。当前 verbosity 流程仅支持 Claude Code 转录（learn.py）。--llm-judge 通过 LiteLLM 调用 LLM 覆盖启发式级别，失败时静默回退到启发式（best-effort，learn.py）。

11. LLM 后端选择

headroom learn 需要一个 LLM 来分析会话。analyzer.py 中的自动选择优先级为：

优先级	来源	示例
1	--model 标志	headroom learn --model gpt-4o
2	API key 环境变量	ANTHROPIC_API_KEY（→ claude-sonnet-4-6）、OPENAI_API_KEY（→ gpt-4o）、GEMINI_API_KEY（→ gemini/gemini-flash-latest）
3	HEADROOM_LEARN_CLI 环境变量	export HEADROOM_LEARN_CLI=gemini
4	自动检测已安装的 CLI	依次检查 PATH 中的 claude、gemini、codex

全部落空时抛出带配置指引的 RuntimeError，CLI 层会打印错误并以退出码 1 结束（fail-fast，learn.py）。

没有 API key 也能用

如果你通过订阅使用 Claude Code / Gemini CLI / Codex（没有裸 API key），headroom learn 可以直接把它们当作 LLM 后端调用：

# 自动检测 PATH 中的 claude —— 无需 API key
headroom learn

# 显式选择 CLI 后端
headroom learn --model gemini-cli

# 通过环境变量固定 CLI
export HEADROOM_LEARN_CLI=codex
headroom learn