code-walkthrough

代码导览

采用经过验证的导览：先确认实际代码和输出，再通过一场不可变的 Navi 导览引导观众。

准备会话

1. 确认 termctrl、Neovim 0.10 或更高版本以及 navi.nvim 均已就绪。

2. 在项目根目录中以前台可见会话启动 Neovim：

   termctrl run walkthrough -- nvim
   

3. 从另一个进程使用 Terminal Control 检查并驱动同一会话。若可用，优先通过 Terminal Control MCP 使用 interact；否则使用 termctrl show、termctrl send 和 termctrl wait。

4. 如果可见终端过窄，请在编排导览前调整大小。演示或录制期间保持尺寸稳定。

当人和 Agent 看到同一个稳定的 Neovim 屏幕，且 Agent 能通过 Terminal Control 检查屏幕时，会话便已就绪。

确定讲解路线

1. 如果讲解目标尚不明确，询问观众结束后应理解什么或能够解释什么。
2. 阅读相关代码，并运行能够证明其当前行为的最小范围命令。
3. 检查实际可见结果。不要根据预期或记忆中的结果写说明。
4. 选择一条概念路线。有效的路线通常从外部行为讲到产生该行为的机制，再到观察到的结果。

不要把概览、故障诊断、实现导览和修复合并成一个讲解序列。只有当每个计划停靠点都是回答同一个连贯问题所必需的，路线才算确定。

编写一场不可变的导览

如果导览是临时的，请在源代码树之外创建 JSON 文件。模式唯一且稳定时使用字面模式；只有当确切位置本身是重点时才使用行号。

[
  {
    "file": "src/example.test.ts",
    "pattern": "it(\"updates subscribers\"",
    "end_pattern": "expect(runs).toBe(2)",
    "message": "The public contract starts here: one write must cause one additional run."
  },
  {
    "file": "src/example.ts",
    "pattern": "export function notify",
    "end_pattern": "subscriber()",
    "message": "The implementation reaches every subscriber through this loop."
  }
]

加载它，不要修改：

:NaviLoad /absolute/path/to/tour.json

遵循以下规则：

• 每条助手回复最多创建一场导览。
• 将已展示的导览视为不可变。不要在同一条回复中改写其停靠点或备注。
• 从行为或调用位置开始，再深入实现细节。
• 对构成一个简单机制的相邻代码行，使用一个范围停靠点。
• 只有在不同位置之间确有讲解路线时，才使用多个停靠点。
• 大部分解释放在简短、自然的 Navi 备注中；聊天内容保持简短。
• 在有助于解释行为时，将简洁且已验证的输出放在关键断言或结果处。
• 如果验证结果推翻了解释，请停止并说明。只能在下一条回复中清除或替换导览。

当每个停靠点都能解析、第一个停靠点可见，且备注与已验证的代码和输出一致时，导览便已完成。

展示导览

除非观众要求你带领，否则让观众控制节奏：

]n           next stop
[n           previous stop
<leader>np  pick a stop
<leader>nc  clear the tour

这些是建议的按键映射，并非 Navi 默认设置。如果无法使用，请改用 :NaviNext、:NaviPrev、:NaviPick 和 :NaviClear。

暂停回答问题时，不要替换当前导览。后续解释可以聚焦当前代码范围或检查输出；不同的概念路线应留到之后的导览中。

使用 OBS 录制

如果目标产物是面向人的演示（包括自然的节奏、旁白、窗口边框或其他视觉背景），请使用 OBS。

1. 添加一个窗口捕获源，捕获包含 termctrl run 的终端窗口。
2. 录制前裁掉无关标签页、提示符、通知和私人路径。
3. 编写导览前设置好终端尺寸、字体大小、OBS 画布和捕获裁剪区域，确保备注换行效果与录制时完全一致。
4. 进行一段简短的测试录制。检查文字是否清晰可读、麦克风音量是否合适、终端对比度是否足够，以及 Navi 备注是否完整显示。
5. 开始 OBS 录制，展示这场不可变的导览，然后在最后一帧停留足够长、便于阅读后停止录制。

OBS 是此分支中的主要录制工具。Terminal Control 仍用于 Agent 控制和验证。

保留终端证据

如果用户需要终端原生回放、截图或调试证据，而不是完整的 OBS 演示，请使用 Terminal Control 工件。

• 随时使用 termctrl save walkthrough --format png --out artifacts/current 捕获当前屏幕。

• 会话启动时必须启用录制；目前无法为已运行的前台会话添加录制。

• 如需进行终端原生录制，请在演示前使用 --record 重新启动：

  termctrl run walkthrough --record artifacts/walkthrough.termctrl -- nvim
  

• 在有意义的时刻添加标记，然后在会话结束后检查或导出录制内容：

  termctrl mark walkthrough contract
  termctrl mark walkthrough mechanism
  termctrl markers artifacts/walkthrough.termctrl
  termctrl video artifacts/walkthrough.termctrl --out artifacts/walkthrough.mp4
  

除非用户明确需要相关工件，否则不要录制或保留可能包含机密的终端输入、源代码、路径或输出。

完成

除非用户希望保持会话开启，否则请清除演示并停止会话：

:NaviClear

termctrl stop walkthrough

报告已验证的行为、演示的操作流程以及保留的工件路径。当观看者已走完操作流程、终端会话处于所需的最终状态，并且所有承诺提供的工件均已检查后，演示即告完成。

工具参考

• Terminal Control：https://github.com/anomalyco/terminal-control
• Navi：https://github.com/kitlangton/navi.nvim