步骤 1：安装插件#

1
pi install npm:pi-pattern-retry

安装后，pi 会自动在 settings.json 的 packages 数组里加入 "npm:pi-pattern-retry"。

步骤 2：确认 settings.json 已注册#

打开（Windows 路径）：

1
C:\Users\<你的用户名>\.pi\agent\settings.json

打开（Linux路径）：

1
/home/<你的用户名>/.pi/agent/settings.json

确认 packages 数组中包含这一项：

1
"npm:pi-pattern-retry"

⚠️ 若没有，手动补上这一行字符串到 packages 数组，保存后重启 pi。

步骤 3：创建配置文件（最关键的一步！）#

插件只读取这两个路径的配置文件，其它路径一律忽略：

• 全局：~/.pattern-retry.json
• 项目级覆盖：<当前工作目录>/.pattern-retry.json（同名 pattern 覆盖全局，新 pattern 追加）

在 Windows 上，~ 即用户主目录：

1
C:\Users\<你的用户名>\.pattern-retry.json
2
/home/<你的用户名>/.pattern-retry.json

🔴 最常见的失效原因：把配置放到了别的目录（例如 .pi/agent/ 下），插件根本不会去读。 另一个常见错误：用了 retryRules / trigger / delayMs / maxRetries 这种字段名——插件不认这些字段，正确格式见步骤 4。

在该路径下新建 .pattern-retry.json，内容见步骤 4。

步骤 4：写入配置内容#

1
{
2
  "enabled": true,
3
  "patterns": [
4
    {
5
      "name": "only-503-fast-retry",
6
      "match": { "source": "providerStatus", "kind": "regex", "value": "^503$" },
7
      "scheduleSec": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
8
      "message": "continue",
9
      "stopOnProgress": true
10
    },
11
    {
12
      "name": "only-503-fast-retry-err",
13
      "match": { "source": "errorMessage", "kind": "regex", "value": "^503" },
14
      "scheduleSec": [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
15
      "message": "continue",
16
      "stopOnProgress": true
17
    }
18
  ]
19
}

1
node -e "const n=1000; const p={enabled:true,patterns:[{name:'only-503-fast-retry',match:{source:'providerStatus',kind:'regex',value:'^503$'},scheduleSec:Array(n).fill(1),message:'continue',stopOnProgress:true},{name:'only-503-fast-retry-err',match:{source:'errorMessage',kind:'regex',value:'^503'},scheduleSec:Array(n).fill(1),message:'continue',stopOnProgress:true}]}; require('fs').writeFileSync((process.env.USERPROFILE||require('os').homedir())+'/.pattern-retry.json', JSON.stringify(p,null,2)); console.log('written:', (process.env.USERPROFILE||require('os').homedir())+'/.pattern-retry.json');"

步骤 5：重启 pi 会话#

1
pi

重启后插件才会加载新配置。

步骤 6：验证生效#

在 pi 会话内执行：

1
/pattern-retry-status

应能看到两个 pattern 的 attempt / max / exhausted / scheduled 状态信息。

match 语义#

• source: "providerStatus" → 匹配十进制状态码字符串，如 "503"、"429"。
• source: "errorMessage" → 匹配 assistant 消息的 errorMessage，为空则不匹配。
• kind: "contains" → 大小写敏感子串；kind: "regex" → 正则，需大小写不敏感时自己在 value 里加 (?i) 或用 i flag 形式。

模板变量（message 中可用）#

本指南中 message 固定为 continue，不使用变量——直接把 continue 当作下一条用户输入发给 pi。

❌ 陷阱 1：配置文件放错路径#

插件只读 ~/.pattern-retry.json 和 <cwd>/.pattern-retry.json。放到 .pi/agent/、.pi/ 下都不会被读取。

自检：确认文件就在 C:\Users\<你的用户名>\.pattern-retry.json。

❌ 陷阱 2：字段名写错#

retryRules、trigger、delayMs、maxRetries 这些字段插件完全不认。正确字段是 patterns 数组 + match + scheduleSec + message。写成旧格式等于没配置。

❌ 陷阱 3：HOME 环境变量覆盖主目录#

插件取主目录的代码是 process.env.HOME || os.homedir()。

• 正常 Windows：HOME 未设置 → 用 os.homedir() = C:\Users\<用户名> ✅
• 若你在 Git Bash / MSYS2 / WSL 里运行 pi，HOME 可能被设成 /c/Users/... 或 /home/...，导致插件去那个路径找配置。

自检：在运行 pi 的同一终端里执行 echo $HOME（Git Bash）或 echo %HOME%（CMD）。如果非空且不是你想放配置的目录，把 .pattern-retry.json 放到那个 HOME 指向的目录，或清掉该环境变量。

❌ 陷阱 4：^503 误匹配#

only-503-fast-retry-err 用 ^503 匹配 errorMessage 开头。任何以 503 开头的错误信息都会触发重试。若发现没遇到真 503 却一直狂发 continue，检查日志里 trigger:matched 的 textLen 和实际错误文本，必要时把 value 收紧（如 ^503\b 或更精确串）。

❌ 陷阱 5：scheduleSec 写成百万级数组#

旧本机配置把 scheduleSec 写成 100 万个 1，文件 5.7 MB，纯属浪费。用「步骤 4」的命令生成几百~几千次即可，文件仅几 KB。

❌ 陷阱 6：改了配置没重启#

配置只在会话启动时加载。改完 .pattern-retry.json 必须重启 pi，否则不生效。