explain

name	explain
description	Explain a codebase in four modes: `framework` produces a high-level architecture walkthrough saved to `codebase-walkthrough[-<slug>].md`; `impl <path>` explains a specific implementation saved to `codebase-impl-<slug>.md`; `run <identifier>` explains a specific execution run by tracing code + logs, saved to `codebase-run-<slug>.md`; `debug [<identifier>] [<question>]` diagnoses failures and verifies fixes, saved to `codebase-debug-<slug>.md`. `<slug>` is a short (≤12 chars) tag derived from the identifier so repeated runs don't overwrite each other.
metadata	{"short-description":"Codebase architecture, implementation, run & debug explainer"}

explain — Codebase Explainer

Usage

/explain framework
/explain impl <path>
/explain run <identifier>
/explain debug [<identifier>] [<question>]

<identifier> can be a run ID, log directory, timestamp, workspace name, tmux pane (e.g. MySession:7.0), or any hint that helps locate the specific run to explain. If omitted, explain the most recent run.

<question> is an optional free-text focus: a hypothesis to verify ("是不是 Codex 提前退出了"), a feature to check ("resume 机制是否生效"), or a specific failure to investigate ("为什么 exit 23").

---

Mode: framework

Produce a full architecture walkthrough and write it to codebase-walkthrough[-<slug>].md （<slug> 可省略；如果同一个仓库里想比较多个子模块的框架视图，用被考察的子目录/模块名作为 slug）。

Steps

1. 大模块识别 — 列出顶层的所有大模块（组件、服务、包），每个模块写清楚：

   • 功能职责（1–3 句）
   • 与其他模块之间的顶层接口（function call / RESTful API / message queue 等），指明接口定义所在的完整相对路径。
   • 不列模块内部的子接口。

2. 程序入口 & 执行流 — 找到所有程序入口（main、entrypoint、CLI command 等），按执行顺序逐步讲解系统运行过程：

   • 每个关键调用点注明它在上层的哪里被调用（完整相对路径 + 行号）。
   • 如果有多个程序需要启动，说明各自运行的环境（uv/conda/docker/虚拟机/物理机）和机器。

3. 架构改进意见 — 给出框架层面的设计改进建议，优先关注：

   • 模块数量、命名与直觉/使用场景的一致性
   • 接口冗余、任务定义不清晰、参数设置不合理

---

Mode: impl <path>

写入 codebase-impl-<slug>.md（<slug> 从 <path> 的 basename 派生，见「输出文件命名」一节）。

Steps

1. 内部结构 — 说明该实现内部主要分哪几个大块（类、函数组、文件）。

2. 技巧与注意事项 — 对于实现的核心功能，提炼出关键技巧和注意事项，使得初级程序员也能实现相同功能。排列时把大多数人不知道的放在前面。

3. 运行环境 — 如果涉及特殊环境（uv/conda/docker/虚拟机），说明在哪个环境哪台机器上运行。

Explaining changes / diffs

当用户要求解释当前改动、diff、stash、PR changes、或“这次修改怎么执行”时，按 impl 类报告写入 codebase-impl-<slug>.md，但内容要以 change behavior 为中心：

1. 先给一张改动范围 roadmap：列出本次 diff 直接改变的机制、文件和调用位置。
2. 凡是在说明“本次改动新增/改变了什么行为、配置、分支、metadata、依赖或输出”时， 句首使用 ± 前缀；普通控制流解释、调用位置、运行时证据、旧行为背景不加 ±。
3. 只展开和本次改动直接相关的关键分支；不要枚举改动前后行为完全相同的普通控制流。
4. 对每个改动相关分支，构造一组具体的运行时变量场景（参数、metadata、flag、 返回值、异常对象等），并明确写出“改动前怎么走 / 改动后怎么走”。
5. “正常通过”类分支只有在它本身被 diff 改变，或它是理解新增条件边界所必需时才写； 否则省略。写时要标明它和本次改动的关系，不要把它写成完整控制流巡礼。
6. 每个 before/after 判断都必须挂 diff 或当前代码证据，仍然遵守「每一句断言都要挂证据」。

---

Mode: debug [<identifier>] [<question>]

诊断一次运行的失败原因，验证特定功能/修复是否生效。写入 codebase-debug-<slug>.md （<slug> 从 <identifier> 派生；若 identifier 省略，用最近一次运行的 run id / 时间戳末段）。

与 run 模式的关系：两者结构类似（都是从启动到结束逐步追踪），区别在于侧重点：

• run 没有特别重的侧重点，均匀地解释每个阶段做了什么。
• debug 的侧重点是异常：重点展开异常之处，追踪这个异常是如何一步步引导出最终 bug 的；正常运行的部分一行带过。

Locating the run

1. 如果 <identifier> 是 tmux pane（如 MySession:7.0），先 capture pane 内容。
2. 如果是 log dir / workspace name / timestamp，定位日志文件。
3. 如果省略，取最近一次运行。

Steps

1. Triage（快速总览） — 不写废话，优先用短表；如果路径或证据会让表格在 terminal 里横向爆炸，就改用每个 workspace 一个小节/短 bullet：

   Workspace	阶段	Exit Code	一句话原因

   标注几个成功几个失败。

2. 从启动到出错的完整链条 — 这是 debug 模式的核心。对每个失败的 workspace，按执行顺序逐步追踪，从入口一直到报错那一行。每一步都必须包含：

   a. 源码位置 — 完整路径/file.py:行号 + Class->function 可读路径 b. 参考代码 — 摘出该步的关键代码片段（3-10 行），让读者不用打开文件就能理解逻辑 c. 运行时证据 — 如果该步产生了 log 输出，原文摘录相关行（不转述） d. 跳转说明 — 这一步结束后控制流去了哪里（正常路径 vs 实际走的路径）

   格式示例：

   ### Step N: <简述>
   
   **源码**: `ai4ai/agents/developer/run.sh:210` → `run_codex_on_gpu()`
   **代码**:
   ​```bash
   rsync -azL -e "ssh ... -p ${REMOTE_PORT}" \
     "${WORKSPACE_DIR}/" "${REMOTE_USER}@${REMOTE_HOST}:${remote_root}/"
   ​```
   **Log 证据**:
   > symlink has no referent: ".../model/artifacts/snapshot"
   > rsync error: ... (code 23) at main.c(1338) [sender=3.2.7]
   
   **跳转**: rsync exit 23 → `set -e` (run.sh:26) 终止脚本 → EXIT trap (run.sh:368)
   

   要求：

   • 链条必须从程序入口开始（run.sh / loop.py:main()），不能从中间开始
   • 链条必须到达实际报错的那一行，不能在中间停下
   • 每步之间的调用关系必须显式写出（谁调了谁、在哪一行）
   • 如果某个步骤是"正常通过"的，一行带过即可（如 "setup_remote_codex 成功"）
   • 在失败点之后，追踪错误是如何传播的（exit code 如何传递、是否被捕获或丢弃）

3. Root Cause 总结 — 用一段话明确回答"为什么失败了"：

   • 出错的值是什么，正确的值应该是什么
   • 如果有计算/路径错误，列出推导过程
   • 如果是外部原因（API 错误、机器不可达），引用原始错误信息

4. Feature 验证（仅当 <question> 涉及功能检查时）:

   对每个要验证的功能：

   • 是否触发了？ — 日志中触发的证据（原文引用）或缺失的证据
   • 行为是否正确？ — 对比代码预期 vs 实际表现
   • 效果如何？ — 带来了什么实际改善或没有改善

5. 修复建议 — 按优先级排列：

   优先级	问题	修复位置 (file:line)	具体改法

---

Mode: run <identifier>

Explain how a specific execution run actually worked, tracing code paths against real log output. Write to codebase-run-<slug>.md（<slug> 从 <identifier> 派生；若 identifier 省略，用最近一次运行的 run id / 时间戳末段）。

Locating the run

1. Use <identifier> (run ID, log dir, timestamp, workspace name) to find the run's log files and output artifacts. Search log directories, workspace dirs, etc.
2. If <identifier> is omitted, find the most recent run (latest log dir by timestamp).

Steps

1. Architecture Overview + 调用栈树 — Draw the execution flow as an ASCII diagram showing the entry point, each stage/step, and which sub-processes or agents are spawned. Include full paths to the source files that define each stage.

   For run mode, also include a 调用栈树 / 调用树 before the prose walkthrough:

   • The tree must show the concrete call order: entrypoint → stage runner → function / method calls → subprocess / tmux / remote process / sidecar / agent.
   • Each important tree node must include a jumpable source location (完整路径/file:line), and, when the node was observed in the actual run, the matching runtime evidence (log/path:line, pid, tmux session, command, or output artifact).
   • If the run contains multiple concrete cases (e.g. multiple workspaces, lanes, sidecars, retries, shards, or agents), first show the shared mechanism tree, then list a separate actual call tree for each concrete case. The per-case tree should make it obvious which branches actually ran and which declared branches did not run.
   • The tree is not optional: it is the primary orientation device for understanding the run's call order.

2. 详细逐步追踪 — For each stage of the run, in execution order:

   • 代码入口: which code file + line triggers this stage (full path:line).
   • 实际命令: the shell command or function call that was executed.
   • Log 摘要: read the stage's log file; report:
     • First few lines (startup, config, banner).
     • Key events (what the agent/process actually did, decisions made).
     • Last few lines (final status, exit code, token usage if applicable).
     • Error messages if any.
   • 产出文件: list the files this stage created or modified (full paths).

3. Timeline & Metrics — Summarize wall-clock timing per stage and overall, plus any resource metrics found in logs (token counts, GPU usage, data sizes, etc.) as a table.

4. Data Flow — ASCII diagram showing how data/artifacts flow between stages: what each stage reads as input and what it produces as output.

5. 结果判定 — Explain the final outcome: success/failure classification, why, and what the key evidence was. If the run failed, pinpoint where and likely why.

---

General rules

输出文件命名

• 每个模式的输出文件都带一个短 <slug> 后缀，这样多次 explain 不同对象时不会互相覆盖。
• <slug> 规则：
  • 长度 ≤ 12 个字符，宁可信息略少也不要长。
  • 只保留 [A-Za-z0-9_.-]；其他字符（/、:、空格等）统一替换为 -，并把连续的 - 折叠成一个。
  • 从 identifier 里取最能区分本次调用的那一段，通常是末段：
    • impl ai4ai/agents/developer/run.sh → run.sh
    • run logs/2026-04-23-1530/dev-a → dev-a 或 1530-dev-a
    • debug MySession:7.0 → 7.0 或 mys-7.0
    • debug 2026-04-23T15:30 exit23 → exit23（<question> 的关键词比时间戳更有辨识度时优先用它）
  • 如果截断后和项目里已有的同类文件重名，再追加一个短区分段（如时间戳末 4 位）。
• framework 模式默认不加 slug（通常一个仓库只会跑一次）；只有当你要对同仓库的多个子模块分别生成框架视图时才加。
• 文件名中的 <slug> 用连字符和前缀连接，不用下划线：codebase-impl-run.sh.md 而不是 codebase_impl_run.sh.md。

每一句断言都要挂证据

这条是硬约束，适用于全部四个模式的所有段落（不只是 debug/run 的 per-step 区块）：

• 正文里每一句对代码行为、运行结果、时间、数字、配置值的陈述，后面必须紧跟一个证据：要么是 完整路径/file:line（或 :a-b 行段），要么是一段原文摘录的 log/代码片段（用 > 引用或围栏代码块，不要转述）。
• 如果同一个 claim 需要多个证据，就列全；不要"见附录"式的集中堆在最后。
• Root Cause / Feature 验证 / 修复建议 / Triage 表的"一句话原因"列 —— 也必须带证据，不能只有结论。
• 数字必须可复现：每个数字（步数、次数、大小、耗时）都要注明是从哪个文件 / 哪条命令 / 哪段 log 数出来的。
• 找不到证据就写"无直接证据，推断依据是 X"并把 X 也挂证据；不允许无依据的结论。
• 重要或需要整理的片段（函数定义、关键 log 行、JSON 子对象）直接内联贴内容——读者不打开文件也能看懂。

Terminal 友好输出

• 报告默认面向 terminal / Vim 阅读：保留 heading、bullet、短段落等结构信息，避免大段长句。
• 尽量避免过长行；长路径、长命令、长 JSON/log 片段单独放进 fenced code block。
• 不要用会横向爆炸的宽表承载长路径或长证据；必要时把表格改成每项一个小节。
• 区分代码/机制与运行/日志时，使用 Nerd Font 标记：
  • 󰅩 表示代码、机制、控制流、配置规则或修复位置。
  • 󰄉 表示某次运行的现场、日志、进程、指标、状态或输出。
• 不使用 emoji 做结构标记，避免 terminal 中字符宽度不稳定。

路径格式

• 文件引用始终写从项目根目录开始的完整相对路径，格式：path/to/file.py:line。
  • 指明功能范围或连续代码/日志范围时，使用 path/to/file.py:start-end。
    • 正确：ai4ai/agents/developer/run.sh:713-764
    • 错误：ai4ai/agents/developer/run.sh:713 到 ai4ai/agents/developer/run.sh:764
  • 所有位置都必须用完整路径：正文、表格、代码块注释、执行流图，无一例外。
    • 正确：configs/tmux/ai/lib.sh:11
    • 错误：lib.sh:11
  • 一定要写清楚行数，方便我定位；最好能带上能定位到代码的更容易读的路径，比如AAAA[class]->BBBB[func]
  • 我平时会使用 vim 的 gf 来做代码跳转，请务必保证用完整路径，让我跳转的时候能到准确位置。
    • 一定不要省略路径！ 如果你写成 path/a......z/file.py:line，我就会很难定位到它。

其他

• 输出文件直接写在项目根目录，Markdown 格式，不要写在子目录里。
• explain 生成的 codebase-*.md 输出默认只是本地阅读产物，不要 git add、commit 或纳入提交；只有用户明确要求提交这些 explain 结果时才 stage/commit。
• 语言跟随用户：用户用中文问就用中文写，用英文问就用英文写。