pi-error-retry 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# pi-error-retry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+独立 Pi 扩展，移植 `@local/dsh-error-retry` 的规则重试行为，并增加输出长度截断后的自动续写。当前在本机 Pi **1.4.0** 上验证。
+
+## 必须区分的两种行为
+
+| 情况 | 行为 | 模型上下文 |
+| --- | --- | --- |
+| `stopReason: "error"` 且规则命中 | 无限重试当前模型请求 | 追加 `context_edit`，省略失败回复；不插入“继续”或新的用户输入 |
+| `stopReason: "length"` | 自动继续完成原任务 | 保留截断回复，追加明确续写提示；不从头重试 |
+| 未匹配错误 | 本扩展不接管 | Pi 原有重试／恢复策略不变 |
+| 用户停止、取消或卸载 | 停止 | 不在后台定时唤醒会话 |
+
+Pi 中的 `Response was truncated before completion.` 对应第二种情况。续写不增加错误重试计数，也不使用错误退避。再次截断会再次续写，直至正常完成或用户停止。
+
+Pi 自带的有限错误重试先行；它耗尽后，本扩展接管匹配错误。扩展重试发起的新请求仍可能经过 Pi 原有有限重试。不会全局关闭内置重试，也不会把所有错误都设为无限重试。
+
+### 为什么重试不会重放工具
+
+例如：原任务 → 工具 A 已执行 → 请求下一步失败。本扩展仅省略这个失败回复，下一次请求仍包含工具 A 的结果，不重新提交原任务，也不重新执行工具 A。
+
+截断时，Pi 本身会将截断回复中的工具调用标记失败，不执行可能残缺的参数。本扩展保留这些结果，要求模型重新生成尚未执行的调用的完整参数。它与自然工具后续共用一次 continuation，不额外叠加第二次请求。
+
+## 安装
+
+从 npm 安装：
+
+```sh
+pi install npm:pi-error-retry
+```
+
+也可直接从 GitHub 安装：
+
+```sh
+pi install git:github.com/librola/pi-error-retry
+```
+
+在现有 Pi 会话中执行 `/reload`；新会话自动加载。克隆后的本地源码无需编译，也可临时加载：
+
+```sh
+pi -e ./pi-error-retry/index.ts
+```
+
+安装声明位于 `~/.pi/agent/settings.json` 的 `packages` 数组。本扩展只注册事件和用户命令，没有新增模型可调用的配置工具。
+
+不要同时启用其他错误恢复／长度续写扩展，避免竞争触发。
+
+## 配置和编辑
+
+用户配置文件：
+
+```text
+~/.pi/agent/error-retry.json
+```
+
+设置了 `PI_CODING_AGENT_DIR` 时使用该目录。规则只从用户目录读取，不读取项目里的规则覆盖。
+
+```text
+/error-retry        查看规则数量、配置位置和两种恢复行为
+/error-retry edit   用 Pi 原生 JSON 编辑器修改规则
+/error-retry stop   停止当前请求
+```
+
+Pi 原生编辑器适用于 TUI 和支持该对话协议的 RPC 客户端；不提供 DSH 的插件详情页。JSON／print 模式请直接编辑文件。
+
+- 规则每次由扩展接管错误前重新读取，不需要重新加载或卸载扩展。
+- 保存时校验配置并原子写入；文件原文充当 revision，跨窗口保存使用排他锁。版本冲突不会覆盖他人修改。
+- 非法草稿或保存失败不显示成功，并可以保留草稿继续编辑、主动读取最新配置，或取消。
+- 保存不取消已经排定的等待；已排定的重试可能完成一次，下一次错误判定读取新规则。立即停止请使用标准停止按钮或 `/error-retry stop`。
+- 非法配置、读取失败或正则匹配超时不被当成命中，也不静默回退为宽泛规则。
+
+### 规则格式
+
+```json
+{
+  "rules": [
+    { "mode": "contains", "pattern": "Quota service is temporarily unavailable." },
+    { "mode": "regex", "pattern": "^temporary overload(?:\\s|$)", "flags": "i" }
+  ]
+}
+```
+
+- 规则之间为 **OR**，任意一条命中就无限重试。
+- `contains` 区分大小写，不接受 `flags`。
+- `regex` 使用 JavaScript 正则，不写外围斜线；`flags` 只允许不重复的 `i/m/s/u`，不允许有状态的 `g/y`。
+- `pattern` 不能为空或纯空白；有意义的前后空白会保留。
+- 整组匹配在 `node:vm` 中共享 **25ms** 预算，超时不接管。这里只用 VM 限制正则回溯，不把它当成恶意代码安全沙箱。
+- 显式提供 `rules` 完全替换默认规则，不追加。`{"rules":[]}` 仅关闭本扩展的错误重试，**不会关闭长度续写或 Pi 内置重试**。
+
+不提供文件或省略 `rules` 时，默认与 DSH 源码一致，使用两条完整句子：
+
+1. `Requests have exceeded the throughput limit on your Provisioned-Managed deployment. If you continue to exceed your limit, consider increasing the number of provisioned throughput units deployed.`
+2. `Your request exceeds the maximum size allowed by your deployment's quota.`
+
+`examples/error-retry.json` 提供从 DSH 配置迁移的 10 条示例规则；按需复制到用户配置文件使用。安装不会自动用示例覆盖你的配置，扩展默认列表仍保持上述两条。
+
+## 等待、日志和范围
+
+- 匹配错误的重试次数和累计等待时间均不设上限。
+- 本地退避约为 1、2、4、8、16、30 秒，带 10% 抖动，最大 30 秒。
+- 有效 `Retry-After-Ms`／`Retry-After` 响应头优先，支持毫秒、秒和 HTTP 日期；服务端长等待不截短，定时器分段避免溢出。
+- 最终结束边界没有运行取消信号。因此边界只准备重试，实际等待在下一次 `agent_start`、发送模型请求之前进行，使用运行信号与扩展生命周期信号。标准停止可以立即取消长等待。
+- 重试等待显示状态栏；`pi-error-retry.recovery` 非消息条目记录 `retry`、`retry-started` 和 `continue`。计数从当前分支日志恢复，按提供方、模型及规范化策略隔离；成功步骤、新用户输入或规则变化重置。
+- 失败回复及其用量仍保留在原始会话历史和统计中，只从后续模型上下文省略，不删除历史。
+- 用户已排队的新输入或其他扩展已选定的 continuation 优先，不追加竞争请求。
+- 作用范围为加载了此扩展的 Pi Agent 主循环，包括同样加载此包的 Pi 子会话；不包装工具内部 HTTP、辅助总结调用或外部 CLI。外部子代理不会因为父会话加载而自动获得此扩展。
+- 加载扩展不会自动唤醒已经结束的旧错误回合，需要用户手动继续。
+
+**风险：无限重试可能产生无限请求和费用。** 配额／请求大小问题未必能靠等待修复，过宽正则也可能永远不成功。请保留明确规则，遇到永久错误及时停止并修正输入或部署。
+
+## 验证
+
+开发依赖安装不会安装另一份 Pi：
+
+```sh
+npm install --ignore-scripts --legacy-peer-deps
+export PI_TEST_PACKAGE=/path/to/pi-coding-agent/package.json
+npm run check
+npm test
+```
+
+`PI_TEST_PACKAGE` 指向已安装 Pi 的包清单。不设置时从项目依赖中寻找宿主 Pi。测试使用真实 SDK、扩展 TypeScript 加载器、会话上下文投影及模拟 provider；不调用真实模型，也不读取用户模型凭据。临时文件在系统临时目录中创建和清理。
+
+覆盖：101 次连续错误、内置重试串联、请求输入不变、截断前文保留、截断后错误重试、已执行工具不重放、截断工具不执行、取消长等待、规则热更新／冲突／校验、正则超时、退避、服务端等待及日志计数隔离。
+
+当前 **32 项测试通过**，TypeScript 严格类型检查通过。
+
+另有一个已独立对照复现的宿主限制：SDK 直接对活动会话调用 `session.dispose()` 时，Pi 1.4.0 会先解绑持久化订阅，随后可能报告 `turn_end could not resolve the persisted assistant entry ID`；仅注册空 `turn_end` 处理器、不加载本扩展也能复现。本扩展不会因此继续请求，也不会访问已失效的上下文。该宿主问题未修改；正常标准停止已验证，SDK 集成建议先 `await session.abort()` 再 `session.dispose()`。
+
+真实提供方故障恢复和客户端 UI 交互尚未人工验收；SDK 与加载器验证不等同于实际付费请求验收。

package/examples/error-retry.json

@@ -0,0 +1,45 @@
+{
+  "rules": [
+    {
+      "mode": "contains",
+      "pattern": "Requests have exceeded the throughput limit on your Provisioned-Managed deployment. If you continue to exceed your limit, consider increasing the number of provisioned throughput units deployed."
+    },
+    {
+      "mode": "contains",
+      "pattern": "Your request exceeds the maximum size allowed by your deployment's quota."
+    },
+    {
+      "mode": "contains",
+      "pattern": "No available PLB channels. Is the PLB down"
+    },
+    {
+      "mode": "contains",
+      "pattern": "has been reached: 600000 tokens per 60 seconds."
+    },
+    {
+      "mode": "contains",
+      "pattern": "The model was unable to complete inference due to an internal error."
+    },
+    {
+      "mode": "regex",
+      "pattern": "Models Proxy:\\s*The\\s+(?:[A-Za-z][A-Za-z-]*\\s+){0,4}limit for model\\s+\\\\?\"[^\"\\r\\n]+\\\\?\"\\s+has been reached:\\s*\\d+(?:\\.\\d+)?\\s+tokens per\\s+\\d+(?:\\.\\d+)?\\s+seconds?\\.\\s*Please retry after\\s+\\d+(?:\\.\\d+)?\\s+seconds?\\.",
+      "flags": "i"
+    },
+    {
+      "mode": "contains",
+      "pattern": "Models Proxy: 502 Bad Gateway"
+    },
+    {
+      "mode": "contains",
+      "pattern": "pi-ai stream idle timeout after 300000ms"
+    },
+    {
+      "mode": "contains",
+      "pattern": "Quota service is temporarily unavailable."
+    },
+    {
+      "mode": "contains",
+      "pattern": "Upstream service unavailable"
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,203 @@
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, SessionEntry, TurnEndEvent } from "@earendil-works/pi-coding-agent";
+import { readConfig, saveConfig } from "./src/config.ts";
+import { matchesRules, policyKey, providerRetryAfter, retryDelay, waitForRetry } from "./src/rules.ts";
+
+export const RECOVERY_ENTRY = "pi-error-retry.recovery";
+export const CONTINUE_MESSAGE =
+	"上一条回复因单次输出长度限制被截断。请从停止处继续完成原任务，不要重述已输出内容，不要重复已完成的工具操作。如果工具调用被截断，请重新生成完整参数，仅重发尚未执行的调用。";
+
+interface RetryRecord {
+	kind: "retry";
+	retryId: string;
+	retry: number;
+	policyKey: string;
+	provider: string;
+	model: string;
+	messageEntryId: string;
+	delayMs: number;
+	errorMessage: string;
+}
+
+export function previousRetry(branch: SessionEntry[], key: string, provider: string, model: string): RetryRecord | undefined {
+	// 仅重建当前分支的当前请求步骤；成功、用户新输入或续写消息均开启新步骤。
+	for (const entry of [...branch].reverse()) {
+		if (entry.type === "message") {
+			const message = entry.message;
+			if (message.role === "user" || (message.role === "assistant" && message.stopReason !== "error")) return;
+		}
+		if (entry.type === "custom_message") return;
+		if (entry.type !== "custom" || entry.customType !== RECOVERY_ENTRY) continue;
+		const record = entry.data as Partial<RetryRecord> | undefined;
+		if (record?.kind !== "retry" || record.provider !== provider || record.model !== model) continue;
+		if (record.policyKey !== key) return;
+		if (typeof record.retry === "number" && Number.isSafeInteger(record.retry) && record.retry > 0 &&
+			typeof record.retryId === "string") return record as RetryRecord;
+		return;
+	}
+}
+
+export function registerErrorRetry(pi: ExtensionAPI, configPath: string): void {
+	let lifetime = new AbortController();
+	let lastTurn: { event: TurnEndEvent; responseDelay: number | undefined } | undefined;
+	let responseDelay: number | undefined;
+	let pendingRetry: RetryRecord | undefined;
+
+	pi.on("session_start", () => {
+		lifetime = new AbortController();
+		lastTurn = undefined;
+		pendingRetry = undefined;
+	});
+	pi.on("session_shutdown", () => lifetime.abort());
+	pi.on("before_agent_start", () => {
+		// 加载扩展不会唤醒旧错误；新的用户请求也不能继承旧的排队等待。
+		lastTurn = undefined;
+		pendingRetry = undefined;
+	});
+	pi.on("turn_start", () => { responseDelay = undefined; });
+	pi.on("after_provider_response", (event) => { responseDelay = providerRetryAfter(event.headers); });
+
+	pi.on("agent_start", async (_event, ctx) => {
+		const record = pendingRetry;
+		pendingRetry = undefined;
+		if (!record) return;
+		const signal = ctx.signal;
+		if (!signal || signal.aborted || lifetime.signal.aborted) return;
+		const cancellation = AbortSignal.any([signal, lifetime.signal]);
+		const cancel = () => {
+			// 在取消事件的同步阶段清理，dispose 随后会使 ctx 失效，不能在 await 后再访问它。
+			lastTurn = undefined;
+			pendingRetry = undefined;
+			ctx.ui.setStatus("error-retry", undefined);
+			if (!signal.aborted) ctx.abort();
+		};
+		cancellation.addEventListener("abort", cancel, { once: true });
+		ctx.ui.setStatus("error-retry", `无限重试 #${record.retry}，等待 ${(record.delayMs / 1000).toFixed(1)} 秒`);
+		try {
+			// 最终边界没有运行信号：把等待放到下一次 agent_start，才能被标准停止按钮取消。
+			if (!await waitForRetry(record.delayMs, cancellation)) return;
+			pi.appendEntry(RECOVERY_ENTRY, {
+				kind: "retry-started", retryId: record.retryId, retry: record.retry,
+				messageEntryId: record.messageEntryId,
+			});
+		} finally {
+			cancellation.removeEventListener("abort", cancel);
+			if (!cancellation.aborted) ctx.ui.setStatus("error-retry", undefined);
+		}
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		lastTurn = { event, responseDelay };
+		const message = event.message;
+		if (message.role !== "assistant" || message.stopReason !== "length" || event.outcome === "aborted" ||
+			ctx.signal?.aborted || lifetime.signal.aborted || event.continue || ctx.hasPendingMessages() ||
+			event.context.pendingMessages.length > 0) return;
+		// length 不是错误重试：保留回复和 Pi 的截断工具失败结果，追加明确续写提示。
+		// turn_end 的一次 continuation 与自然工具后续共用调度，不会额外请求两次。
+		return {
+			continue: true,
+			entries: [
+				{
+					type: "custom" as const, customType: RECOVERY_ENTRY,
+					data: { kind: "continue", messageEntryId: event.messageEntryId },
+				},
+				{
+					type: "custom_message" as const, customType: "pi-error-retry.continue",
+					content: CONTINUE_MESSAGE, display: true,
+				},
+			],
+		};
+	});
+
+	pi.on("agent_before_settle", (event, ctx) => {
+		const turn = lastTurn?.event;
+		const message = turn?.message;
+		if (!turn || message?.role !== "assistant" || message.stopReason !== "error" || event.outcome !== "error" ||
+			lifetime.signal.aborted || event.continue || ctx.hasPendingMessages() ||
+			event.context.pendingMessages.length > 0) return;
+		// 内置有限重试与溢出恢复先行；已被其他恢复省略的失败不再接管。
+		if (!event.context.contextEntries.some((entry) => entry.sourceEntry.id === turn.messageEntryId)) return;
+		let key: string;
+		try {
+			const { config } = readConfig(configPath);
+			if (!config.rules.length || !matchesRules(config.rules, message.errorMessage ?? "")) return;
+			key = policyKey(config.rules);
+		} catch (error) {
+			ctx.ui.notify(`错误重试未接管：${error instanceof Error ? error.message : String(error)}`, "warning");
+			return;
+		}
+		const previous = previousRetry(ctx.sessionManager.getBranch(), key, message.provider, message.model);
+		const retry = (previous?.retry ?? 0) + 1;
+		const record: RetryRecord = {
+			kind: "retry", retryId: previous?.retryId ?? randomUUID(), retry, policyKey: key,
+			provider: message.provider, model: message.model, messageEntryId: turn.messageEntryId,
+			delayMs: retryDelay(retry, lastTurn?.responseDelay), errorMessage: message.errorMessage ?? "",
+		};
+		pendingRetry = record;
+		// 追加省略记录而非删除历史；原失败及用量保留，模型上下文回到失败前的请求。
+		// 没有“继续”或伪用户消息，因此不会从头重放已经完成的工具。
+		return {
+			continue: true,
+			entries: [
+				{ type: "context_edit" as const, targetId: turn.messageEntryId, replacement: null },
+				{ type: "custom" as const, customType: RECOVERY_ENTRY, data: record },
+			],
+		};
+	});
+
+	pi.registerCommand("error-retry", {
+		description: "查看错误重试规则；/error-retry edit 编辑规则，/error-retry stop 停止当前请求",
+		handler: async (args, ctx) => {
+			const action = args.trim();
+			if (action === "stop") {
+				pendingRetry = undefined;
+				ctx.abort();
+				return;
+			}
+			if (action && action !== "edit") {
+				ctx.ui.notify("用法：/error-retry [edit|stop]", "warning");
+				return;
+			}
+			try {
+				const snapshot = readConfig(configPath);
+				if (action !== "edit") {
+					ctx.ui.notify(`错误规则：${snapshot.config.rules.length} 条（命中后无限重试）；长度截断：自动继续。配置：${configPath}`, "info");
+					return;
+				}
+				if (!ctx.hasUI) {
+					ctx.ui.notify(`当前模式没有编辑器，请手动编辑 ${configPath}`, "warning");
+					return;
+				}
+				let draft = JSON.stringify(snapshot.config, null, 2);
+				while (true) {
+					const edited = await ctx.ui.editor("错误重试规则（JSON）；保存不会取消已排定的等待", draft);
+					if (edited === undefined) return;
+					draft = edited;
+					try {
+						const config = saveConfig(configPath, JSON.parse(draft), snapshot.revision);
+						ctx.ui.notify(`已保存 ${config.rules.length} 条规则；下次错误判定自动生效`, "info");
+						return;
+					} catch (error) {
+						ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+						// 保存失败保留草稿；发生版本冲突时不更新旧 revision，禁止覆盖他人的修改。
+						const choice = await ctx.ui.select("规则尚未保存", ["继续修改草稿", "放弃草稿并读取最新配置", "取消"]);
+						if (choice === "继续修改草稿") continue;
+						if (choice !== "放弃草稿并读取最新配置") return;
+						const latest = readConfig(configPath);
+						snapshot.revision = latest.revision;
+						draft = JSON.stringify(latest.config, null, 2);
+					}
+				}
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}
+
+export default function (pi: ExtensionAPI): void {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+	registerErrorRetry(pi, join(agentDir, "error-retry.json"));
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "pi-error-retry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "按规则无限重试 Pi 模型错误，并在长度截断时自动继续",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/librola/pi-error-retry.git"
+  },
+  "homepage": "https://github.com/librola/pi-error-retry#readme",
+  "bugs": {
+    "url": "https://github.com/librola/pi-error-retry/issues"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "examples/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check": "node scripts/check.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { type RetryConfig, validateConfig } from "./rules.ts";
+
+export interface ConfigSnapshot {
+	config: RetryConfig;
+	// 使用文件原文检测其他窗口的保存，缺失文件与空文件必须区分。
+	revision: string | null;
+}
+
+export function readConfig(path: string): ConfigSnapshot {
+	let revision: string | null;
+	try {
+		revision = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		revision = null;
+	}
+	return { config: validateConfig(revision === null ? {} : JSON.parse(revision)), revision };
+}
+
+export function saveConfig(path: string, value: unknown, expectedRevision: string | null): RetryConfig {
+	const config = validateConfig(value);
+	mkdirSync(dirname(path), { recursive: true });
+	const lockPath = `${path}.lock`;
+	let lock: number;
+	try {
+		lock = openSync(lockPath, "wx", 0o600);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("其他窗口正在保存，请稍后重试");
+		throw error;
+	}
+	const temporary = `${path}.${randomUUID()}.tmp`;
+	try {
+		if (readConfig(path).revision !== expectedRevision) {
+			throw new Error("规则已被其他窗口修改；草稿未保存，请读取最新配置后重新编辑");
+		}
+		writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+		renameSync(temporary, path);
+		return config;
+	} finally {
+		try {
+			unlinkSync(temporary);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		} finally {
+			closeSync(lock);
+			unlinkSync(lockPath);
+		}
+	}
+}

package/src/rules.ts

@@ -0,0 +1,116 @@
+import { Script, createContext } from "node:vm";
+
+export type RetryRule =
+	| { mode: "contains"; pattern: string }
+	| { mode: "regex"; pattern: string; flags?: string };
+
+export interface RetryConfig {
+	rules: RetryRule[];
+}
+
+export const DEFAULT_RULES: readonly RetryRule[] = [
+	{
+		mode: "contains",
+		pattern:
+			"Requests have exceeded the throughput limit on your Provisioned-Managed deployment. If you continue to exceed your limit, consider increasing the number of provisioned throughput units deployed.",
+	},
+	{
+		mode: "contains",
+		pattern: "Your request exceeds the maximum size allowed by your deployment's quota.",
+	},
+];
+
+export function validateConfig(value: unknown): RetryConfig {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("配置必须是 JSON 对象");
+	}
+	const object = value as Record<string, unknown>;
+	if (Object.keys(object).some((key) => key !== "rules")) throw new Error("配置仅接受 rules 字段");
+	if (object.rules === undefined) return { rules: DEFAULT_RULES.map((rule) => ({ ...rule })) };
+	if (!Array.isArray(object.rules)) throw new Error("rules 必须是数组");
+	const rules = object.rules.map((value: unknown, index): RetryRule => {
+		const prefix = `规则 ${index + 1}：`;
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${prefix}必须是对象`);
+		const rule = value as Record<string, unknown>;
+		if (Object.keys(rule).some((key) => !["mode", "pattern", "flags"].includes(key))) {
+			throw new Error(`${prefix}仅接受 mode、pattern、flags`);
+		}
+		if (typeof rule.pattern !== "string" || !/\S/.test(rule.pattern)) {
+			throw new Error(`${prefix}pattern 不能为空`);
+		}
+		if (rule.mode === "contains") {
+			if (rule.flags !== undefined) throw new Error(`${prefix}contains 不接受 flags`);
+			return { mode: "contains", pattern: rule.pattern };
+		}
+		if (rule.mode !== "regex") throw new Error(`${prefix}mode 必须是 contains 或 regex`);
+		if (rule.flags !== undefined && (typeof rule.flags !== "string" || !/^[imsu]*$/.test(rule.flags))) {
+			throw new Error(`${prefix}flags 仅支持 i/m/s/u`);
+		}
+		const flags = rule.flags as string | undefined;
+		try {
+			new RegExp(rule.pattern, flags);
+		} catch (error) {
+			throw new Error(`${prefix}${error instanceof Error ? error.message : String(error)}`);
+		}
+		return { mode: "regex", pattern: rule.pattern, ...(flags === undefined ? {} : { flags }) };
+	});
+	return { rules };
+}
+
+export function policyKey(rules: RetryRule[]): string {
+	// OR 规则的排序、重复项和正则标志顺序不改变策略；有效空白不能丢失。
+	const normalized = rules.map((rule) => JSON.stringify(rule.mode === "contains"
+		? rule
+		: { mode: rule.mode, pattern: rule.pattern, flags: new RegExp(rule.pattern, rule.flags).flags }));
+	return JSON.stringify(["pi-error-retry", 1, [...new Set(normalized)].sort()]);
+}
+
+const matchScript = new Script(`rules.some(rule => rule.mode === "contains"
+	? message.includes(rule.pattern)
+	: new RegExp(rule.pattern, rule.flags).test(message))`);
+
+export function matchesRules(rules: RetryRule[], message: string): boolean {
+	// 整组规则共享 25ms 预算；异常由调用方交回 Pi，不把超时当成命中。
+	return matchScript.runInContext(createContext({ rules, message }), { timeout: 25 }) === true;
+}
+
+export function retryDelay(retry: number, providerDelay?: number, random = Math.random): number {
+	if (providerDelay !== undefined && Number.isFinite(providerDelay) && providerDelay > 0) return providerDelay;
+	const base = Math.min(1000 * 2 ** Math.min(retry - 1, 5), 30000);
+	return Math.min(30000, Math.round(base * (0.9 + random() * 0.2)));
+}
+
+export function providerRetryAfter(headers: Record<string, string>, now = Date.now()): number | undefined {
+	const normalized = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+	const millis = normalized["retry-after-ms"];
+	if (millis !== undefined && millis.trim() && Number.isFinite(Number(millis)) && Number(millis) > 0) {
+		return Number(millis);
+	}
+	const value = normalized["retry-after"];
+	if (!value?.trim()) return undefined;
+	const seconds = Number(value);
+	const delay = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(value) - now;
+	return Number.isFinite(delay) && delay > 0 ? delay : undefined;
+}
+
+export async function waitForRetry(delayMs: number, signal: AbortSignal): Promise<boolean> {
+	let remaining = delayMs;
+	while (remaining > 0) {
+		if (signal.aborted) return false;
+		// 服务端长等待不截短，分段避免 Node 定时器溢出。
+		const slice = Math.min(remaining, 2147483647);
+		const completed = await new Promise<boolean>((resolve) => {
+			const finish = (result: boolean) => {
+				clearTimeout(timer);
+				signal.removeEventListener("abort", abort);
+				resolve(result);
+			};
+			const abort = () => finish(false);
+			const timer = setTimeout(() => finish(true), slice);
+			signal.addEventListener("abort", abort, { once: true });
+		});
+		if (!completed) return false;
+		remaining -= slice;
+	}
+	return !signal.aborted;
+}