多个原因都说得通
竞态、陈旧状态和丢失回调可能产生相同症状。探针负责区分它们。
Pi 扩展 0.1.9
先拿到证据，再修改代码。
pi-debug-mode 是面向 Pi 编码智能体的 Cursor 风格调试模式。它向 Pi 注入调试指令，要求 Pi 用竞争假设和定向运行时探针确认原因，然后再修复。
01 / 何时使用
静态检查不足以确认原因时使用。
直接问题或明显的静态缺陷仍适合普通提示词。问题原因取决于程序运行过程时，再进入 Debug Mode。
问题需要人工操作
只有人能完成复现步骤或判断界面结果时，使用人工检查点。
日志必须放在关键分支
在能够区分假设的位置添加临时探针，并统一标记为 pi-debug。
修复后必须再跑一次
使用相同步骤复现。确认结果后，才移除探针并报告修复。
02 / 方法
从症状到已验证修复的五个步骤。
扩展把固定的证据流程加入当前 Pi 会话。它不替代 Pi，也不启动独立服务。
-
检查真实执行路径
注入的指令要求 Pi 先读取相关代码，并在修改前提出三到五个竞争假设。
-
添加定向运行时探针
指令要求 Pi 只添加能够区分这些假设的临时
pi-debug探针。 -
执行一次复现
debug_reproduction提供 Guided 反馈或 Autopilot。Autopilot 让 Pi 自己完成机器检查，只在视觉、点击、触控或审美判断时再次请求人工检查。 -
修复证据支持的原因
指令要求 Pi 读取证据，更新假设，然后修改最小的根因路径。
-
验证并清理
Pi 重复相同的机器检查，读取实际输出，移除临时探针并报告证据。Autopilot 的模式交接不等于修复确认。
03 / 证据
安装前先看完整流程。
页面中的动态预览会自动播放。它来自真实 Pi TUI 录屏片段；链接中的长录屏包含完整的真实机器会话。
页面内动态预览、真实终端证据和独立交互演示。
完整录屏包含竞争假设、临时探针、复现选择器、证据检查、根因修复、人工确认、探针清理和通过的测试。
04 / 选择
按问题需要选择调试流程。
这些方式处理不同任务。Guided 模式在检查点收集反馈。Autopilot 让 Pi 自己完成机器检查，只在软件无法判断时请求人工意见。
| 方式 | 运行时证据 | 人工检查点 | 结束条件 |
|---|---|---|---|
| 普通调试提示词 | 取决于提示词和 Agent 回复。 | 可选。 | 由提示词定义。 |
| 通用 Agent 模式 | 取决于该模式的工具和指令。 | 取决于该模式。 | 由该模式定义。 |
pi-debug-mode | 注入的指令要求在修复前提出竞争假设并添加定向探针。 | Guided 模式在检查点询问。Autopilot 只询问视觉、点击、触控或审美判断。 | Pi 报告机器证据，清理探针，并保留人工确认边界。 |
05 / 安装
从 npm 或固定 Git tag 安装。
两个命令都固定到 0.1.9。安装后重启 Pi，再用 /debug 描述症状和预期结果。
npm
通过 Pi 的 npm 来源安装。
pi install npm:pi-debug-mode@0.1.9GitHub
通过 Pi 的 Git 来源安装不可变 tag。
pi install git:github.com/liush2yuxjtu/pi-debug-mode@v0.1.9
06 / 权限
扩展使用 Pi 的现有权限。
检查建议执行的工具调用，并把调试日志视为可能包含应用输入的数据。
系统权限
Pi 扩展拥有与 Pi 相同的系统权限。调试会话可能添加临时探针并读取本地日志。
可选使用遥测
使用遥测默认关闭。明确开启后，只向你配置的 HTTPS 收集端点发送匿名漏斗事件。详见 遥测协议。
模型提供商边界
你配置的 Pi 模型提供商可能收到 Pi 在会话中发送的提示词、工具输出和日志。不要在复现步骤中放入秘密信息。
07 / 常见问题
适用边界和常见问题。
什么时候应该使用 pi-debug-mode？
当问题需要运行时证据、存在多个竞争假设，或修改代码前需要人工复现时，使用 pi-debug-mode。
哪些数据会离开本机？
使用遥测默认关闭。明确开启后，扩展只发送 协议中定义的匿名漏斗事件。你配置的 Pi 模型提供商仍可能收到 Pi 在会话中发送的提示词、工具输出和日志。
它能证明每次修复都正确吗？
不能。它的调试指令要求先取证并在修复后验证，但薄弱的探针、不完整的复现或缺失的测试仍可能让问题没有彻底解决。