Pi 工具错误恢复

要解决什么问题

Pi、Codex 或其它带工具链的 Agent 在执行 Shell、MCP、浏览器桥接（CDP / Playwright）、包管理器或 Git 集成时，一旦调用失败，常见反应是反复执行同一条命令——既浪费上下文，也可能把环境改坏。本技能针对的是「工具执行失败」这一具体场景，而不是日常闲聊或纯推理写作。

典型触发包括：工具调用报错、命令非零退出、Pi 扩展未被正确识别、MCP 无法启动或配置无效、npm/pnpm 引擎版本不匹配、Git refspec 等集成错误，以及你即将使用已知容易踩坑的工具前。

技能如何工作

核心原则是 禁止盲目重试：只有在命令、环境变量、依赖或扩展状态确实变化，或用户明确同意时，才允许再次执行。

失败后会走固定八步流程：

1. 提取上下文——工具名、命令、稳定错误片段、退出码、OS/shell 等，且不收集密钥。
2. 生成检索关键词——用工具名 + 稳定错误短语等拼成紧凑检索串。
3. 检索本地 Recipe——优先在默认目录用 rg 搜 Markdown recipe；无 rg 时用 grep 等等价方式。
4. 边界降级——目录不存在则创建并继续诊断；为空则声明「尚无已验证 recipe」，走通用清单并征得同意后再做有风险操作。
5. 严格匹配——至少满足「同工具 / 同稳定错误 / 同命令族 / 同环境类 / 同症状」中的两项，才视为可应用的已验证方案；只命中一项仅作提示。
6. 安全修复——读文档、doctor/version、补本地目录、在上下文清楚时装项目依赖等可逆操作可自动做；删文件、sudo、rm -rf、改 shell 启动文件、git push、部署等须先询问。
7. 可观测验证——修复后必须能观察到成功（例如命令退出码为 0、MCP 列出工具），猜测不算验证通过。
8. 沉淀 Recipe——仅在「见过失败 → 试过修复 → 修复有效 → 验证清楚 → 无敏感信息」后，以 小写-连字符.md 写入本地库。

无匹配时按 Fallback 排查清单 顺序：读错误原文 → 工作目录 → 命令是否存在 → 版本 → 配置文件 → 权限 → 最小 status 命令 → 再改环境 → 每次修复后验证。

包内还带 Pi/Chrome 路由、MCP cwd、Playwright 浏览器未安装、PowerShell 执行策略等模板类别，项目特有方案应在真实修复成功后再追加。

适用边界

• 不要用于与普通对话、写作无关的任务。
• 不要把网页搜索结果当作本地已验证 recipe；不要把未验证的猜测写入 recipe 或隐瞒部分失败。
• Recipe 仅存本地 Markdown，无需外网服务，适合离线或内网环境；但这也意味着库一开始可能为空，需要靠真实故障修复逐步积累。