Pi Tool Error Recovery Skill

> 中文：这是一个给 Pi / Codex / AI Agent 使用的工具错误恢复 Skill。它不会替你“瞎重试”，而是先识别错误、检索本地已验证方案、执行安全修复、验证结果，并把成功经验沉淀为可复用的 Markdown recipe。

> English: This skill helps Pi/Codex/AI agents recover from failed tools by searching local verified recipes, applying safe fixes, verifying the result, and saving only confirmed fixes.

1. When to Use / 什么时候触发

Use this skill when any of these happens:

• A tool call fails.
• A shell command exits with a non-zero code.
• A Pi extension command fails or is treated as normal chat.
• An MCP server fails to start, lists no tools, or reports invalid config.
• A browser bridge, Chrome extension, CDP, or Playwright workflow fails.
• npm / pnpm / node / package manager behavior fails.
• Git / GitHub / API integration fails.
• The agent is about to use a tool that has known setup issues.

中文触发条件：

• 工具调用失败。
• Shell 命令失败。
• Pi 扩展命令没有被正确识别。
• MCP server 无法启动、无工具、配置错误。
• 浏览器桥接、Chrome 扩展、CDP、Playwright 报错。
• npm / pnpm / node / 包管理器报错。
• Git / GitHub / API 集成报错。
• 即将使用一个已知容易出问题的工具。

Do not use this skill for normal chatting, ordinary reasoning, general writing, or tasks unrelated to tool execution.

2. Core Principle / 核心原则

Do not guess -> search recipes -> match carefully -> apply safe fix -> verify -> save only verified fixes
不要猜 -> 先查 recipe -> 谨慎匹配 -> 只做安全修复 -> 验证成功 -> 只沉淀已验证方案

The agent must avoid blind retries. A retry is allowed only when there is a clear reason, such as a changed command, fixed environment variable, reloaded extension, installed missing dependency, or user-approved action.

3. Recipe Store / Recipe 存储位置

Default local recipe directory:

~/.pi/agent/tool-recipes/

If it does not exist, create it:

mkdir -p ~/.pi/agent/tool-recipes

Windows PowerShell equivalent:

New-Item -ItemType Directory -Force "$HOME\.pi\agent\tool-recipes"

All recipes are Markdown files. No network service is required. No foreign service is required. This is friendly to domestic / offline environments.

4. Recovery Workflow / 恢复流程

When a tool or command fails, follow this exact flow:

Step 1 — Extract Context / 提取上下文

Collect only information needed for debugging:

• Tool name
• Command or action
• Error message
• Exit code
• OS / shell if visible
• Package / extension / integration name
• Recent command changes if relevant

Never collect or store secrets.

Step 2 — Build Search Keywords / 生成检索关键词

Create a compact search string from stable identifiers:

<tool>|<command>|<package>|<main error phrase>|<exit code>|<OS>

Examples:

rg -i "npm|missing script|package.json|dev" ~/.pi/agent/tool-recipes/
rg -i "mcp|server|ENOENT|command not found" ~/.pi/agent/tool-recipes/
rg -i "playwright|browser|install|chromium" ~/.pi/agent/tool-recipes/

Step 3 — Search Recipes / 检索 Recipe

Preferred search command:

rg -i "<keywords>" ~/.pi/agent/tool-recipes/

If rg is not installed, use fallback commands:

# macOS / Linux fallback
grep -RniE "<keywords>" ~/.pi/agent/tool-recipes/

# Windows PowerShell fallback
Get-ChildItem "$HOME\.pi\agent\tool-recipes" -Recurse -Filter *.md | Select-String -Pattern "<keywords>"

Step 4 — Handle Edge Cases / 边界情况降级

If the recipe directory is missing:

1. Create the directory.
2. Continue with safe diagnosis.
3. Do not claim that a recipe exists.

If the recipe directory is empty:

1. Say: No verified local recipe found yet.
2. Use the fallback diagnosis checklist.
3. Ask for user approval before risky actions.
4. Save a new recipe only after the fix is verified.

If recipe search fails:

1. Try the fallback search command.
2. If search still fails, list the directory.
3. Continue with manual diagnosis and report that recipe search failed.

If multiple recipes match:

1. Prefer the recipe with the same tool + same stable error signature.
2. If still ambiguous, use the safest read-only verification first.
3. Do not apply destructive fixes automatically.

Step 5 — Match Strictly / 严格匹配

A recipe matches only if at least two of these are true:

• Same tool or integration.
• Same stable error phrase.
• Same failed command family.
• Same environment class, such as Windows PowerShell, WSL, macOS, browser bridge, Node package manager.
• Same symptom pattern.

If only one condition matches, treat it as a hint, not as a verified fix.

Step 6 — Apply Safe Fix / 执行安全修复

Safe fixes can be applied without extra confirmation when they are local and reversible, such as:

• Reading documentation files.
• Running doctor / status / version commands.
• Creating a missing local recipe directory.
• Installing non-sensitive local project dependencies after user context is clear.
• Restarting the local tool process.

Ask before risky actions listed in the safety section.

Step 7 — Verify / 验证

Verification must be observable. Examples:

command exits with code 0
/tool doctor passes
MCP server lists tools
npm run dev starts successfully
pnpm test passes
browser bridge connects
Git push succeeds after correct branch selection

A recipe is not verified if it is only a guess.

Step 8 — Save Recipe / 沉淀 Recipe

Save or append a recipe only when:

1. The original failure was observed.
2. A fix was tried.
3. The fix worked.
4. Verification is clear.
5. No secrets or private data are included.

Use lowercase hyphenated file names:

npm-node.md
mcp-server.md
browser-cdp.md
playwright.md
git.md
windows-powershell.md
misc.md

5. Fallback Diagnosis Checklist / 通用降级排查清单

When no recipe matches, diagnose in this order:

1. Read the exact error: identify stable phrases, not the whole noisy log.
2. Check location: confirm current working directory and project root.
3. Check command availability: command -v, where, Get-Command.
4. Check versions: node -v, npm -v, python --version, java -version, etc.
5. Check config files: package.json, mcp config, extension config, env examples.
6. Check permissions: read/write permission, execution policy, browser permission.
7. Try a minimal doctor/status command.
8. Ask before modifying system state.
9. Verify after every fix.
10. Save a recipe only after success.

中文速记：先看错误原文，再看目录，再看命令是否存在，再看版本，再看配置，再看权限，最后才修改环境。

6. Safety Rules / 安全规则

Never save:

• Passwords / 密码
• API keys / API 密钥
• Tokens / 令牌
• Cookies / Cookie
• Private credentials / 私密凭据
• Payment data / 支付信息
• Private account data / 私人账号数据
• One-time personal information / 一次性个人信息

Always ask before:

• deleting files
• running sudo
• running rm -rf
• modifying system directories
• changing shell startup files such as .zshrc, .bashrc, PowerShell profile
• git commit / git push
• deployment
• publishing packages
• external account changes
• submitting forms through logged-in browser sessions
• changing browser security flags

Redaction rule:

Replace secrets with <REDACTED_SECRET> before saving any recipe.

7. Output Format / 输出格式

When using this skill, respond in this structure:

## Tool Error Recovery

### Error Detected
- Tool:
- Command / Action:
- Error Signature:
- Environment:

### Recipe Search
- Query:
- Result:

### Matched Recipe
- Recipe:
- Match confidence:
- Why it matches:

### Action Taken
- Steps:
- Safety notes:

### Verification
- Verification method:
- Result:

### Saved Recipe
- Status:
- Path:

### Next Time
- Reuse trigger:
- One-line fix:

If no recipe is saved:

Saved Recipe: Not saved because the fix was not verified.

If no recipe exists:

Recipe Search: No verified local recipe found yet. I will use the fallback diagnosis checklist and save a recipe only after the fix is verified.

8. Anti-patterns / 反模式

Do not:

• Retry the same failing command repeatedly without changing anything.
• Save guessed fixes as verified recipes.
• Store secrets in recipes.
• Apply a recipe just because one keyword matches.
• Delete lockfiles, caches, or config files without explaining why.
• Run destructive commands without user approval.
• Treat web search results as verified local recipes.
• Hide partial failure from the user.

9. Built-in Recipe Categories / 内置 Recipe 类别

This package includes common verified recipe templates for:

• Pi / Chrome extension command routing
• Recipe store missing or empty
• npm missing script
• npm EBADENGINE / Node version mismatch
• pnpm workspace filter issues
• MCP server command not found / wrong cwd
• Playwright browser not installed
• Browser CDP port connection issues
• Git src refspec main does not match any
• Windows PowerShell execution policy and PATH issues
• WSL command location mismatch

More project-specific recipes should be added after real verified fixes.