@zhushanwen/pi-retry-rules 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,18 @@
-# Temporary Holding Version
+# @zhushanwen/pi-retry-rules
 
-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.
+Retryable error rules for Pi: rewrites finalized `stopReason=error` assistant messages via the
+official `message_end` hook (appending a `[taiji-retry:` marker) so that throttling-class provider
+errors hit pi-ai's native retryable word list and the native retry loop (auto_retry events,
+exponential backoff, failed-attempt omission) takes over.
+
+- Decision pipeline: two-tier order — `non_retryable` verdict rules exclude first (per source),
+  then same-verdict rules by source priority `custom > remote > builtin`, first match wins.
+- Matching channels: regex against `errorMessage` (ReDoS-guarded) + JSON-snippet dot-path
+  extraction (`"${status}: ${body-json}"` openai-compat form).
+- Config file: `<agentDir>/config/retry-rules-ext-config.json` (mtime hot reload; written by the
+  taiji runtime — single data source, this extension is a pure consumer).
+- Disable path: no dedicated switch — turn off pi's native retry settings
+  (`enabled=false` / `maxRetries=0`); the native gate is checked before the retryable-word-list
+  verdict, so rewrites never trigger retries when disabled.
+- Semantic SSOT: `packages/shared/src/retry-rules.ts` (this bundle carries a mirrored copy with
+  behavior-lock tests).

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@zhushanwen/pi-retry-rules",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Retryable error rules for Pi — message_end rewrite triggers the native retry loop for throttling-class provider errors, with configurable rules (builtin baseline ⊕ remote overlay ⊕ user custom) and ReDoS-guarded matching.",
+  "type": "module",
+  "main": "index.ts",
+  "taiji": {
+    "role": "universal",
+    "startupConfig": [
+      {
+        "path": "config/retry-rules-ext-config.json",
+        "content": {
+          "version": 1,
+          "customRules": [],
+          "effectiveRules": []
+        }
+      }
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension",
+    "retry",
+    "rate-limit"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "!src/__tests__/",
+    "index.ts",
+    "skills/",
+    "vitest.config.ts"
+  ],
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.6.2",
+    "@zhushanwen/pi-llm-shared": "0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
+    "vitest": "^4.1.8",
+    "@taiji/shared": "0.10.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
 }

package/skills/retry-rules-ext-config/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: retry-rules-ext-config
+description: "配置 @zhushanwen/pi-retry-rules（可重试错误规则）或排查「为什么没重试」时加载。含配置文件路径、RetryRulesExtConfig schema（version/customRules/effectiveRules）、规则字段值域（verdict 三态 retryable/non_retryable/conditional、match 双通道 pattern/jsonPath、kind 值域、source 优先序）、长度与条数上限、判定管线两层序、改写标记 [taiji-retry: 识别、热重载时机、默认值、示例、停用通道（pi 原生 retry 配置）。触发词：重试规则、为什么没重试、没触发重试、429 重试、限流重试、retry-rules 配置、retry rules config。"
+---
+
+# retry-rules 配置指南
+
+> @zhushanwen/pi-retry-rules：对 `stopReason=error` 的 assistant 消息按重试规则判定，命中 retryable 规则时在 errorMessage 末尾追加 `[taiji-retry:` 标记（追加式，原文完整保留），使错误命中 pi-ai 原生可重试词表，从而触发 pi 原生重试全链路（auto_retry 事件 + 指数退避 + 失败尝试从上下文剔除）。
+
+## 配置文件位置
+
+`<agentDir>/config/retry-rules-ext-config.json`
+
+- `<agentDir>` = pi agent 目录（pi 的 `getAgentDir` 派生，`PI_CODING_AGENT_DIR` 覆盖，默认 `~/.pi/agent`；taiji 隔离环境为 `~/.taiji/agent`）
+- 走 llm-shared 泛型 config（config/ 子目录 + getAgentDir 派生 + mtime+size 缓存 + 原子写）
+- taiji 桌面端由 runtime 启动序列首建该文件（`taiji.startupConfig` 声明）；独立 pi 用户手建同样生效
+- 文件缺失 → 空规则集（判定不生效，pi 原生词表兜底），不告警（属正常初始态）；坏 JSON / 字段非法 → 回落默认空规则集并记 extension 告警日志（`<agentDir>/logs/retry-rules-<日期>.log`，同一条损坏文件只告警一次，修正保存后自下一轮判定生效）
+
+## Schema
+
+```ts
+interface RetryRulesExtConfig {
+  version: 1;                        // 固定为 1
+  customRules: RetryableErrorRule[]; // 用户自定义规则段（taiji 设置页编辑写入，source=custom）
+  effectiveRules: RetryableErrorRule[]; // 生效规则集（判定管线直读此段）
+}
+```
+
+- `effectiveRules` = taiji runtime 侧合并视图（编译期基线 ⊕ 远程覆盖 ⊕ 用户自定义）的落盘结果；extension 是纯消费方，独立 pi 用户手编该段同样生效
+- 判定只消费 `effectiveRules`；`customRules` 是用户编辑段的持久化形态（runtime 重算合并视图时读取）
+
+## 单条规则字段
+
+```ts
+interface RetryableErrorRule {
+  id: string;            // ≤64 字符、不含空白，如 zhipu-1302；同文件内不可重复
+  name: string;          // ≤120 字符的简短名称
+  verdict: "retryable" | "non_retryable" | "conditional"; // 裁决三态（见下）
+  match: Match[];        // 匹配条件列表，1-8 条，全部命中才算命中（AND）
+  class: string;         // 失败分类（provider/harness/agent/user/engine），必填
+  kind?: string;         // 失败细分（可选，值域受 class 约束，见下）；判定管线不消费
+  httpStatusClass?: number; // 400-599 整数（可选，纯溯源/展示分组，判定不消费）
+  waitHint?: string;     // ≤200 字符等待提示（可选，settings 展示用，判定不消费）
+  source: "custom" | "remote" | "builtin"; // 出处（判定排序键，见「判定管线」）
+}
+```
+
+match 双通道（二选一按 `kind` 字段区分）：
+
+```ts
+{ kind: "pattern"; pattern: string }   // 正则通道：对整条 errorMessage 做正则（忽略大小写）
+{ kind: "jsonPath"; path: string; operator: "equals" | "contains" | "exists"; value?: string }
+// jsonPath 通道：从 errorMessage 提取首个 JSON 平衡片段，按点路径取值后比较
+//（openai 兼容层 errorMessage 形如 "429: {json}"，body 内业务码可经 path 提取）
+```
+
+校验规则（违反即整份配置回落空规则集并告警，错误文案含修复动作）：
+
+| 字段 | 上限/值域 |
+|---|---|
+| id | ≤64 字符，不含空白，文件内唯一 |
+| name | ≤120 字符，非空 |
+| pattern | ≤200 字符；拒绝嵌套量词等高回溯构造（ReDoS 防护）；须是合法正则 |
+| jsonPath path | ≤128 字符，不含空白，点路径形态（如 `error.code`、`errors.0.type`） |
+| jsonPath operator | equals / contains / exists 三选一；非 exists 时 value 必填（≤256 字符） |
+| match 条数 | 1-8 条 |
+| 规则条数 | 每段 ≤200 条 |
+| httpStatusClass | 400-599 整数 |
+| waitHint | ≤200 字符 |
+| kind（值域） | provider → `rate_limited` / `protocol_unsupported`；harness → `turn_budget_exhausted` / `timeout`；agent → `no_deliverable`；user → `cancelled`；class=`engine` → 须以 `engine_` 开头（如 `engine_aborted`） |
+
+## 判定管线（两层序，命中即断）
+
+1. **第一层排除**：任一 `verdict=non_retryable` 规则命中 → 不改写（先排除再放行，账户类错误永不误重试，不分 source）
+2. **第二层裁决**：按 source 优先序 `custom > remote > builtin` 找首条命中规则——`retryable` → 追加标记触发重试；`conditional` → 不改写（「等不到的人/账户动作」类，恢复指引经轮应答传达）
+3. **全未命中** → 不改写，pi 原生词表兜底（`rate.?limit` / `429` / `too many requests` 等仍可触发原生重试）
+
+## 生效时机（判定粒度热重载）
+
+每轮 message_end 判定直读配置（mtime+size 读时刷新），**文件变更自下一轮判定起生效，无需重启**；判定进行中的当轮不受影响。去重：同一条损坏文件版本只告警一次，修正保存（mtime/size 变化）后重读重校。
+
+## 排查「为什么没重试」
+
+| 现象 | 处置 |
+|---|---|
+| 错误消息带 `[taiji-retry:` 标记但没重试 | 检查 pi 原生「LLM 调用重试」设置（`enabled=false` 或重试次数已耗尽）——原生重试门在词表判定之前检查，标记只是让错误可被判为可重试 |
+| 错误消息不带标记且没重试 | 无规则命中且未落 pi 原生词表；确认该错误码事实是否已登记规则（可加 customRules），或错误消息形态与 pattern/jsonPath 通道不匹配 |
+| 配置保存后判定不生效 | 查 `<agentDir>/logs/retry-rules-<日期>.log` 告警——校验失败已回落空规则集，按错误文案修正字段值域后保存 |
+| 想彻底停用本机制 | 见下「停用通道」 |
+
+## 停用通道
+
+无独立 enabled 开关——停用复用 pi 原生「LLM 调用重试」设置：`enabled=false` 或 `maxRetries=0`。原生重试门位于 errorMessage 词表判定之前，前置门关闭后本扩展的改写不会触发任何重试，自然回落失败如实分类。
+
+## 配置示例
+
+内置基线一条限流规则 + 用户自定义一条 jsonPath 业务码规则：
+
+```json
+{
+  "version": 1,
+  "customRules": [
+    {
+      "id": "my-provider-1302",
+      "name": "某服务商账户限流业务码",
+      "verdict": "retryable",
+      "class": "provider",
+      "kind": "rate_limited",
+      "source": "custom",
+      "match": [{ "kind": "jsonPath", "path": "error.code", "operator": "equals", "value": "1302" }]
+    }
+  ],
+  "effectiveRules": [
+    {
+      "id": "openai-429",
+      "name": "OpenAI 429 限流",
+      "verdict": "retryable",
+      "class": "provider",
+      "kind": "rate_limited",
+      "httpStatusClass": 429,
+      "source": "builtin",
+      "match": [{ "kind": "pattern", "pattern": "rate limit exceeded" }]
+    }
+  ]
+}
+```
+
+默认（startupConfig 首建形态）：`{ "version": 1, "customRules": [], "effectiveRules": [] }`——空规则集 = 判定不生效，pi 原生词表兜底。

package/src/config.ts

@@ -0,0 +1,294 @@
+/**
+ * retry-rules ext-config 读取与校验（bundle 自包含复制体）。
+ *
+ * 类型与校验语义 SSOT = packages/shared/src/retry-rules.ts（subagent-observability
+ * §3.3.12）——extension bundle 自包含不 import shared 运行时代码（network-proxy 同款
+ * 惯例：结构类型本地声明 + 行为镜像锁定测试），本文件是复制体；漂移时以 shared 为准，
+ * __tests__/config.test.ts 锁两侧行为一致 + 域常量值级对账（import shared
+ * RETRY_RULES_DOMAIN，仅测试面消费、不进 bundle——复制体常量漂移即红）；
+ * 校验通道跨包对拍 = __tests__/retry-rules-validation-parity.test.ts（同一规则输入
+ * 矩阵断言两侧 validateRetryRuleFields ok 与错误同判 + 基线全量过本文件读侧 guard；
+ * source 校验边界是该测试内登记的有意差异面——shared 组装前不校验 source，本文件
+ * 读侧校验组装后落盘形态，source 必填）。
+ *
+ * 配置文件 = <agentDir>/config/retry-rules-ext-config.json（llm-shared getConfigPath
+ * 推导；写入侧 = taiji runtime RMW——内置基线 ⊕ 远程覆盖 ⊕ 用户自定义的合并权威在
+ * runtime，extension 是纯消费方，单一数据源）。热重载 = loadConfig 读时刷新（mtime+size），
+ * 判定点每次直接调 loadRetryRulesConfig，禁止上层闭包缓存（llm-shared 头注热重载契约；
+ * 改动下一轮判定即生效，在途退避不中断——重试状态机由 pi 持有）。
+ *
+ * 停用通道（控制旋钮，§3.3.12 用户停用通道登记）：本配置无独立 enabled 开关——停用
+ * 复用既有「LLM 调用重试」卡的 pi 原生 retry 配置（enabled=false / maxRetries=0）。
+ * pi 重试决策点先检查 `!settings.enabled || _retryAttempt >= settings.maxRetries` 即直接
+ * 不重试（node_modules pi-coding-agent dist/core/agent-session.js:787 实装核实——该门
+ * 位于读 errorMessage 词表的 _isRetryableError 之前），本扩展的 message_end 改写只影响
+ * 后续可重试性判定，前置门关闭后改写不触发任何重试——停用即自然回落失败如实分类。
+ */
+
+import { loadConfig } from "@zhushanwen/pi-llm-shared";
+
+import type { RetryableErrorRule, RetryRuleMatch, RetryRuleSource, RetryRuleVerdict } from "./rules.js";
+
+/** llm-shared loadConfig 的包名（决定文件名 retry-rules-ext-config.json）。 */
+const CONFIG_PKG = "retry-rules";
+
+const VERDICTS: readonly string[] = ["retryable", "non_retryable", "conditional"];
+const OPERATORS: readonly string[] = ["equals", "contains", "exists"];
+const SOURCES: readonly string[] = ["custom", "remote", "builtin"];
+
+/**
+ * per-class kind 合法值域（镜像 shared RETRY_RULE_KINDS_BY_CLASS；权威 =
+ * sdk FAILURE_CAUSE_KINDS_BY_CLASS / FailureCause 判别联合）。engine 透传族是
+ * `engine_${string}` 开放前缀面不进本表，校验走前缀形态判定。值级对账由
+ * __tests__/config.test.ts 锁定（复制体漂移即红）。
+ */
+export const KINDS_BY_CLASS: Readonly<Record<string, readonly string[]>> = {
+	provider: ["rate_limited", "protocol_unsupported"],
+	harness: ["turn_budget_exhausted", "timeout"],
+	agent: ["no_deliverable"],
+	user: ["cancelled"],
+};
+
+// 常量导出面仅供镜像锁定测试做值级对账（__tests__/config.test.ts），bundle 体积不受影响
+export const ID_MAX_LEN = 64;
+export const NAME_MAX_LEN = 120;
+export const PATTERN_MAX_LEN = 200;
+export const JSON_PATH_MAX_LEN = 128;
+export const MATCH_VALUE_MAX_LEN = 256;
+export const WAIT_HINT_MAX_LEN = 200;
+export const MATCH_COUNT_MAX = 8;
+export const RULES_MAX = 200;
+/** HTTP 状态大类合法区间（4xx/5xx 语义码段；镜像 shared RetryRuleHttpStatusClass 校验域）。 */
+export const HTTP_STATUS_CLASS_MIN = 400;
+export const HTTP_STATUS_CLASS_MAX = 599;
+
+/** 校验结果信封：ok 或面向用户的错误清单（每条含修复动作，逐项收集不短路）。 */
+export type RetryRulesValidationResult = { ok: true } | { ok: false; errors: string[] };
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function strWithin(v: unknown, max: number): v is string {
+	return typeof v === "string" && v.length > 0 && v.length <= max;
+}
+
+/** 危险正则静态检测（镜像 shared isDangerousRetryPattern：长度上限 + 嵌套量词 + 相邻区间量词）。 */
+export function isDangerousRetryPattern(pattern: string): boolean {
+	if (pattern.length > PATTERN_MAX_LEN) return true;
+	if (/\((?:[^()\\]|\\.)*[+*]\)[+*{]/.test(pattern)) return true;
+	if (/\{(?:\d+),(?:\d+)?\}\s*\{/.test(pattern)) return true;
+	return false;
+}
+
+/** 匹配条件校验（pattern / jsonPath 双通道逐项收集）。 */
+function collectMatchErrors(match: unknown, label: string): string[] {
+	if (!Array.isArray(match)) {
+		return [`${label} 必须是匹配条件列表，请至少添加一条匹配条件`];
+	}
+	if (match.length === 0) {
+		return [`${label} 不能为空，请至少添加一条匹配条件`];
+	}
+	if (match.length > MATCH_COUNT_MAX) {
+		return [`${label} 条数超过上限 ${MATCH_COUNT_MAX}，请合并条件`];
+	}
+	const errors: string[] = [];
+	for (let i = 0; i < match.length; i++) {
+		const item = match[i];
+		const at = `${label} 第 ${i + 1} 条`;
+		if (!isRecord(item)) {
+			errors.push(`${at} 必须是对象，请重新编辑该匹配条件`);
+			continue;
+		}
+		errors.push(...collectOneMatchErrors(item, at));
+	}
+	return errors;
+}
+
+/** 单条匹配条件校验（按 kind 双通道分发；未知通道报错）。 */
+function collectOneMatchErrors(item: Record<string, unknown>, at: string): string[] {
+	if (item["kind"] === "pattern") return collectPatternMatchErrors(item, at);
+	if (item["kind"] === "jsonPath") return collectJsonPathMatchErrors(item, at);
+	return [`${at} 匹配通道必须是 pattern 或 jsonPath，请重新选择匹配方式`];
+}
+
+/** pattern 通道校验（长度上限 → 危险构造 → 语法有效性，逐项收集）。 */
+function collectPatternMatchErrors(item: Record<string, unknown>, at: string): string[] {
+	const errors: string[] = [];
+	const pattern = item["pattern"];
+	if (!strWithin(pattern, PATTERN_MAX_LEN)) {
+		errors.push(`${at}（正则）为空或超过 ${PATTERN_MAX_LEN} 字符，请缩短正则表达式`);
+		return errors;
+	}
+	if (isDangerousRetryPattern(pattern)) {
+		errors.push(`${at}（正则）包含嵌套量词等高回溯构造，存在卡死风险，请简化正则（如用具体字符类替换 .+ 嵌套）`);
+		return errors;
+	}
+	try {
+		new RegExp(pattern as string, "i");
+	} catch {
+		errors.push(`${at}（正则）语法无效，请修正后保存`);
+	}
+	return errors;
+}
+
+/** jsonPath 通道校验（点路径形态 → 比较方式词表 → 比较值非 exists 必填）。 */
+function collectJsonPathMatchErrors(item: Record<string, unknown>, at: string): string[] {
+	const errors: string[] = [];
+	const path = item["path"];
+	const operator = item["operator"];
+	const value = item["value"];
+	if (!strWithin(path, JSON_PATH_MAX_LEN) || /\s/.test(path)) {
+		return [`${at}（JSON 路径）为空、超过 ${JSON_PATH_MAX_LEN} 字符或含空白，请填写如 error.code 的点路径`];
+	}
+	if (typeof operator !== "string" || !OPERATORS.includes(operator)) {
+		return [`${at}（JSON 路径）比较方式必须是 equals / contains / exists 之一`];
+	}
+	if (operator !== "exists" && !strWithin(value, MATCH_VALUE_MAX_LEN)) {
+		errors.push(`${at}（JSON 路径）比较值不能为空且不超过 ${MATCH_VALUE_MAX_LEN} 字符`);
+	}
+	return errors;
+}
+
+/**
+ * kind 字段校验（镜像 shared collectKindErrors：值域闭合面按 class 归属判定）：
+ * class ∈ KINDS_BY_CLASS → kind ∈ 该 class 词表；class="engine" → engine_ 前缀开放面；
+ * class 缺失/非法时不单独判 kind 值域（class 自身错误已收集）。
+ */
+function collectKindErrors(kind: unknown, failureClass: unknown): string[] {
+	if (kind === undefined) return [];
+	if (typeof kind !== "string" || kind === "") {
+		return [`失败分类细分（kind）必须是非空字符串: ${JSON.stringify(kind) ?? String(kind)}`];
+	}
+	if (failureClass === "engine") {
+		if (!kind.startsWith("engine_")) {
+			return [`engine 类规则的 kind 必须以 engine_ 开头（如 engine_aborted）: ${kind}`];
+		}
+		return [];
+	}
+	const allowed = typeof failureClass === "string" ? KINDS_BY_CLASS[failureClass] : undefined;
+	if (allowed === undefined) return [];
+	if (!allowed.includes(kind)) {
+		return [
+			`kind 必须是该分类的合法值之一（${allowed.join(" / ")}）: ${kind}——请修正 kind 或改选匹配的分类（class）`,
+		];
+	}
+	return [];
+}
+
+/** 单条规则校验（镜像 shared validateRetryRuleFields；source 字段同时域校验）。 */
+export function validateRetryRuleFields(rule: unknown): RetryRulesValidationResult {
+	if (!isRecord(rule)) {
+		return { ok: false, errors: [`重试规则必须是对象: ${JSON.stringify(rule) ?? String(rule)}`] };
+	}
+	const errors = [
+		...collectRuleHeaderErrors(rule),
+		...collectMatchErrors(rule["match"], "匹配条件"),
+		...collectRuleOptionalFieldErrors(rule),
+	];
+	return errors.length > 0 ? { ok: false, errors } : { ok: true };
+}
+
+/** 头字段校验（id / name / verdict / class / kind / source，逐项收集不短路）。 */
+function collectRuleHeaderErrors(rule: Record<string, unknown>): string[] {
+	const errors: string[] = [];
+	const { id, name, verdict, class: failureClass, source } = rule;
+	if (!strWithin(id, ID_MAX_LEN) || /\s/.test(id)) {
+		errors.push(`规则 ID 为空、超过 ${ID_MAX_LEN} 字符或含空白，请填写如 zhipu-1302 的短标识`);
+	}
+	if (!strWithin(name, NAME_MAX_LEN)) {
+		errors.push(`规则名称为空或超过 ${NAME_MAX_LEN} 字符，请填写简短名称`);
+	}
+	if (typeof verdict !== "string" || !VERDICTS.includes(verdict)) {
+		errors.push(`裁决必须是 retryable / non_retryable / conditional 之一: ${JSON.stringify(verdict) ?? String(verdict)}`);
+	}
+	if (typeof failureClass !== "string") {
+		errors.push("失败分类（class）不能为空，请选择该错误所属的分类");
+	}
+	errors.push(...collectKindErrors(rule["kind"], failureClass));
+	if (typeof source !== "string" || !SOURCES.includes(source)) {
+		errors.push(`规则出处（source）必须是 custom / remote / builtin 之一: ${JSON.stringify(source) ?? String(source)}`);
+	}
+	return errors;
+}
+
+/** 可选字段校验（httpStatusClass / waitHint，提供才校验）。 */
+function collectRuleOptionalFieldErrors(rule: Record<string, unknown>): string[] {
+	const errors: string[] = [];
+	if (rule["httpStatusClass"] !== undefined) {
+		const c = rule["httpStatusClass"];
+		if (typeof c !== "number" || !Number.isInteger(c) || c < HTTP_STATUS_CLASS_MIN || c > HTTP_STATUS_CLASS_MAX) {
+			errors.push(`HTTP 状态大类必须是 ${HTTP_STATUS_CLASS_MIN}-${HTTP_STATUS_CLASS_MAX} 的整数: ${JSON.stringify(c) ?? String(c)}`);
+		}
+	}
+	if (rule["waitHint"] !== undefined && !strWithin(rule["waitHint"], WAIT_HINT_MAX_LEN)) {
+		errors.push(`等待提示为空或超过 ${WAIT_HINT_MAX_LEN} 字符，请留空或填写简短提示`);
+	}
+	return errors;
+}
+
+function validateRuleList(rules: unknown, label: string): string[] {
+	if (!Array.isArray(rules)) return [`${label} 必须是规则列表`];
+	if (rules.length > RULES_MAX) return [`${label} 条数超过上限 ${RULES_MAX}`];
+	const errors: string[] = [];
+	const seen = new Set<string>();
+	for (let i = 0; i < rules.length; i++) {
+		const result = validateRetryRuleFields(rules[i]);
+		if (!result.ok) errors.push(...result.errors.map((e) => `${label} 第 ${i + 1} 条：${e}`));
+		const id = isRecord(rules[i]) ? rules[i]["id"] : undefined;
+		if (typeof id === "string" && id !== "") {
+			if (seen.has(id)) errors.push(`${label} 第 ${i + 1} 条：规则 ID「${id}」重复，请修改 ID`);
+			seen.add(id);
+		}
+	}
+	return errors;
+}
+
+/** 默认配置：空规则集（判定不生效 = pi 原生词表兜底；与 package.json startupConfig 声明深相等）。 */
+export const DEFAULT_RETRY_RULES_EXT_CONFIG = {
+	version: 1 as const,
+	customRules: [],
+	effectiveRules: [],
+};
+
+/** ext-config 文件形状 guard（读侧 normalize 前置）。 */
+export function isRetryRulesExtConfig(v: unknown): v is {
+	version: 1;
+	customRules: RetryableErrorRule[];
+	effectiveRules: RetryableErrorRule[];
+} {
+	if (!isRecord(v) || v["version"] !== 1) return false;
+	if (!Array.isArray(v["customRules"]) || !Array.isArray(v["effectiveRules"])) return false;
+	return validateRuleList(v["customRules"], "customRules").length === 0 && validateRuleList(v["effectiveRules"], "effectiveRules").length === 0;
+}
+
+/**
+ * loadConfig 的 normalize：校验通过的 raw 即合法配置（校验 = 运行时 guard，断言有兜底）。
+ * 非法配置 throw（含逐项错误清单）→ loadConfig 回落 defaults 并把消息交给 onWarning——
+ * 非法配置不静默修正（network-proxy 域同款语义），回落空集 = 判定不生效的安全态。
+ */
+export function normalizeRetryRulesConfig(raw: unknown): {
+	version: 1;
+	customRules: RetryableErrorRule[];
+	effectiveRules: RetryableErrorRule[];
+} {
+	if (!isRetryRulesExtConfig(raw)) {
+		const errors = [
+			...validateRuleList(isRecord(raw) ? raw["customRules"] : undefined, "customRules"),
+			...validateRuleList(isRecord(raw) ? raw["effectiveRules"] : undefined, "effectiveRules"),
+		];
+		throw new Error((errors.length > 0 ? errors : ["配置形状必须是 { version: 1, customRules, effectiveRules }"]).join("；"));
+	}
+	return raw;
+}
+
+/** 读取配置（llm-shared mtime+size 读时刷新热重载；调用方每次判定直取，禁闭包缓存）。 */
+export function loadRetryRulesConfig(onWarning?: (msg: string) => void): {
+	version: 1;
+	customRules: RetryableErrorRule[];
+	effectiveRules: RetryableErrorRule[];
+} {
+	return loadConfig(CONFIG_PKG, DEFAULT_RETRY_RULES_EXT_CONFIG, normalizeRetryRulesConfig, onWarning);
+}
+
+export type { RetryableErrorRule, RetryRuleMatch, RetryRuleSource, RetryRuleVerdict };

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * Retryable Error Rules Extension（subagent-observability §3.3.12 / W6，探针实证路径一）。
+ *
+ * 机制：pi 无「重试决策」extension 钩子（auto_retry 是 session 内部事件，不进 extension
+ * 事件族），但 `message_end` 官方钩子可原地替换已定稿消息（MessageEndEventResult.message，
+ * types.d.ts:1078-1081「replacement must keep the original message role」）。本扩展对
+ * stopReason=error 的 assistant 消息按重试规则判定，命中 retryable 规则时在 errorMessage
+ * 末尾追加 `[taiji-retry:` 锚标记（追加式非替换式——原文完整保留，pi 会话记录持久化形态
+ * 无信息丢失），使 pi-ai 的 isRetryableAssistantError 原生词表命中（`rate.?limit`/`429`/
+ * `too many requests`），从而触发 pi 原生重试全链路（auto_retry 事件族 + 指数退避 + 失败
+ * 尝试从模型上下文剔除，探针双组对照实证：改写组全链路触发、对照组直接终局）。
+ *
+ * 判定管线两层序与双匹配通道见 rules.ts（SSOT = packages/shared/src/retry-rules.ts）；
+ * 配置热重载见 config.ts（mtime+size 读时刷新，下一轮判定即生效）。
+ *
+ * 停用通道：无独立开关——停用复用 pi 原生 retry 配置（enabled=false / maxRetries=0），
+ * pi 重试决策点在 errorMessage 词表判定之前先检查该门（agent-session.js:787 实装核实），
+ * 停用后改写不触发任何重试，自然回落失败如实分类（档 A）。
+ *
+ * 接线：mandatory-extensions.json 登 infrastructure（structured-output 同链）——infrastructure
+ * 包恒载进主进程与孙进程扩展白名单（pi-host resolveGrandchildExtensionPaths argv 通道），
+ * 零新增接线机制。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
+
+import { loadRetryRulesConfig } from "./config.js";
+import { appendRetryMarker, evaluateRetryRules } from "./rules.js";
+
+type PiAPI = ExtensionAPI;
+
+const logger = getLogger("retry-rules");
+
+/** message_end 事件中本扩展消费的消息字段面（AgentMessage 判定所需的窄视图）。 */
+interface AssistantErrorMessage { // oe-exempt:20261024:test:message_end 改写入参的结构化窄面（pi 消息子集），单消费点 rewriteMessageForRetry；真实第二变体 = pi 消息形态演化，暂内联
+	role: string;
+	stopReason?: string;
+	errorMessage?: string;
+}
+
+// re-export 供测试与外部直接调用（import 路径 ../src/index.js 保持稳定）
+export { appendRetryMarker, evaluateRetryRules } from "./rules.js";
+export {
+	DEFAULT_RETRY_RULES_EXT_CONFIG,
+	isDangerousRetryPattern,
+	loadRetryRulesConfig,
+	validateRetryRuleFields,
+} from "./config.js";
+
+/**
+ * 对单条已定稿消息执行重试判定；命中 retryable 规则返回改写消息（追加标记），否则 undefined。
+ * 泛型守恒：入参 T 透传到返回 message（spread + errorMessage 覆盖，其余字段原样）——
+ * 钩子处传入 pi 的 AgentMessage 即返回 AgentMessage 形态（MessageEndEventResult 契约：
+ * replacement 须保持原消息 role），独立导出（纯函数形态）供单测覆盖。
+ */
+export function rewriteMessageForRetry<T extends AssistantErrorMessage>(message: T): { message: T } | undefined {
+	if (message.role !== "assistant" || message.stopReason !== "error") return undefined;
+	if (typeof message.errorMessage !== "string" || message.errorMessage === "") return undefined;
+	// 非法配置 / 坏 JSON：loadConfig 已回落 defaults（空规则集，判定不生效——pi 原生词表兜底），
+	// 告警接 extension logger（appendEntry 持久化 + <agentDir>/logs/retry-rules-<日期>.log 文件日志），
+	// 不传回调则降级零痕迹。去重 = loadConfig 的 mtime+size 缓存（llm-shared config.ts：损坏文件
+	// 按 mtime+size 缓存 defaults，不重读不重复回调）——每条 message_end 判定虽直读本入口，
+	// 同一损坏文件版本只告警一次；用户修正保存（mtime/size 变化）后重读重校再告警。
+	const config = loadRetryRulesConfig((warning) => logger.warn(`${warning}（已回落空规则集，本扩展重试判定暂不生效；修正配置文件后自下一轮判定生效）`));
+	const decision = evaluateRetryRules(message.errorMessage, config.effectiveRules);
+	if (decision.action !== "rewrite") return undefined;
+	return { message: { ...message, errorMessage: appendRetryMarker(message.errorMessage) } };
+}
+
+// ── Extension entry ────────────────────────────────────────────
+
+export default function retryRulesExtension(pi: PiAPI): void {
+	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle，最早期调用）；
+	// 注入后 module 级 logger 的 warn 经 appendEntry 落 session JSONL（不进 LLM 上下文）。
+	setPiHandle(pi);
+
+	pi.on("message_end", (event) => {
+		return rewriteMessageForRetry(event.message);
+	});
+}

package/src/rules.ts

@@ -0,0 +1,179 @@
+/**
+ * 重试规则判定管线（bundle 自包含复制体）。
+ *
+ * 语义 SSOT = packages/shared/src/retry-rules.ts（subagent-observability §3.3.12）——
+ * extension bundle 自包含不 import shared 运行时代码（extensions 对 shared 的既有惯例：
+ * 结构类型本地声明 + 行为镜像锁定测试），本文件是复制体；漂移时以 shared 为准，
+ * __tests__/rules.test.ts 锁两侧行为一致（用例与 shared 同款对拍）。
+ *
+ * 判定管线两层序（设计定稿）：
+ *   第一层按 verdict 排除——non_retryable 规则优先于 retryable/conditional（先排除再放行，
+ *   账户类错误永不误重试，不区分 source）；第二层同 verdict 内按 source 序
+ *   custom > remote > builtin，命中即断；全未命中 = 不改写（pi 原生词表兜底）。
+ */
+
+// ───────────────────────── 词表 ─────────────────────────
+
+/** 规则裁决三态（verdict 字面统一下划线形态）。 */
+export type RetryRuleVerdict = "retryable" | "non_retryable" | "conditional";
+
+/** 规则出处（两层序第二层排序键：custom > remote > builtin）。 */
+export type RetryRuleSource = "custom" | "remote" | "builtin";
+
+/** 单条匹配条件（对 errorMessage 文本；match[] 全部命中才算命中，AND 语义）。 */
+export type RetryRuleMatch =
+	| { kind: "pattern"; pattern: string }
+	| { kind: "jsonPath"; path: string; operator: "equals" | "contains" | "exists"; value?: string };
+
+/** 单条重试判定规则（class/kind 字段为分类码表共用 schema 位——判定管线不消费，§3.3.12 条目 schema）。 */
+export interface RetryableErrorRule { // oe-exempt:20261026:framework:ext-config 契约的 bundle 自包含复制体声明（SSOT=shared，镜像锁定测试锚定）
+
+	id: string;
+	name: string;
+	verdict: RetryRuleVerdict;
+	match: RetryRuleMatch[];
+	class: string;
+	/** FailureCause kind 细分（可选，值域校验镜像 shared validateRetryRuleFields——判定管线不消费）。 */
+	kind?: string;
+	httpStatusClass?: number;
+	waitHint?: string;
+	source: RetryRuleSource;
+}
+
+/** ext-config 判定消费段（effectiveRules）所在文件 schema。 */
+export interface RetryRulesExtConfig { // oe-exempt:20261026:framework:ext-config 契约的 bundle 自包含复制体声明（SSOT=shared，镜像锁定测试锚定）
+
+	version: 1;
+	customRules: RetryableErrorRule[];
+	effectiveRules: RetryableErrorRule[];
+}
+
+/** 域常量（镜像 shared RETRY_RULES_DOMAIN.textMaxLen；导出仅供镜像锁定测试值级对账）。 */
+export const TEXT_MAX_LEN = 8192;
+
+/** SOURCE 判定序（两层序第二层）：custom > remote > builtin。 */
+const SOURCE_ORDER: readonly RetryRuleSource[] = ["custom", "remote", "builtin"];
+
+// ───────────────────────── 匹配（双通道 + ReDoS 运行时防护） ─────────────────────────
+
+/** JSON 片段提取：首个 `{` 起的括号平衡段（字符串字面量感知）；无平衡段返回 null。 */
+export function extractJsonSegment(text: string): string | null {
+	const start = text.indexOf("{");
+	if (start < 0) return null;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (ch === '"') {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return text.slice(start, i + 1);
+		}
+	}
+	return null;
+}
+
+/** 点路径取值（`error.code` / `errors.0.type`）；任一层缺失返回 undefined。 */
+function readJsonPath(root: unknown, path: string): unknown {
+	let current: unknown = root;
+	for (const segment of path.split(".")) {
+		if (current === null || typeof current !== "object") return undefined;
+		current = (current as Record<string, unknown>)[segment];
+	}
+	return current;
+}
+
+/** 单条匹配条件判定（message 已截断）。 */
+function matchesCondition(message: string, condition: RetryRuleMatch): boolean {
+	if (condition.kind === "pattern") {
+		try {
+			return new RegExp(condition.pattern, "i").test(message);
+		} catch {
+			// 运行时兜底（写侧校验已拒非法源；本侧防线覆盖绕过 runtime 直改文件的第三方便携形态）：无效源恒不命中
+			return false;
+		}
+	}
+	const segment = extractJsonSegment(message);
+	if (segment === null) return false;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(segment);
+	} catch {
+		return false;
+	}
+	const actual = readJsonPath(parsed, condition.path);
+	if (condition.operator === "exists") return actual !== undefined;
+	if (actual === undefined || actual === null) return false;
+	const actualText = typeof actual === "string" ? actual : JSON.stringify(actual);
+	if (condition.operator === "equals") return actualText === condition.value;
+	return actualText.includes(condition.value ?? "");
+}
+
+/** 单条规则判定：match[] 全部命中才算命中（AND）。 */
+export function matchRetryRule(message: string, rule: RetryableErrorRule): boolean {
+	return rule.match.every((condition) => matchesCondition(message, condition));
+}
+
+// ───────────────────────── 判定管线（两层序，命中即断） ─────────────────────────
+
+/** 判定结论：rewrite = 追加标记触发 pi 原生重试；keep = 不改写（reason 说明不动因）。 */
+export type RetryRuleDecision =
+	| { action: "rewrite" }
+	| { action: "keep"; reason: "empty_message" | "non_retryable_hit" | "conditional_hit" | "no_rule_match" };
+
+export function evaluateRetryRules(message: string, rules: readonly RetryableErrorRule[]): RetryRuleDecision {
+	if (message.trim() === "") return { action: "keep", reason: "empty_message" };
+	const truncated = message.length > TEXT_MAX_LEN ? message.slice(0, TEXT_MAX_LEN) : message;
+	// 第一层：verdict 排除（先排除再放行——用户可重试规则击穿账户类硬约束的方向被结构封死）
+	for (const rule of rules) {
+		if (rule.verdict === "non_retryable" && matchRetryRule(truncated, rule)) {
+			return { action: "keep", reason: "non_retryable_hit" };
+		}
+	}
+	// 第二层：同 verdict 内按 source 序，首个命中规则裁决（命中即断）
+	for (const source of SOURCE_ORDER) {
+		for (const rule of rules) {
+			if (rule.source !== source) continue;
+			if (!matchRetryRule(truncated, rule)) continue;
+			if (rule.verdict === "retryable") return { action: "rewrite" };
+			return { action: "keep", reason: "conditional_hit" };
+		}
+	}
+	return { action: "keep", reason: "no_rule_match" };
+}
+
+// ───────────────────────── 改写标记（探针实证锚文本） ─────────────────────────
+
+/**
+ * 追加式改写标记（§3.3.12 改写落盘约束 + 探针实证）：
+ * - 前缀 `[taiji-retry:` 是本机制触发重试的识别约定（现无按标记消费的观测方，观测侧
+ *   可凭标记区分机制触发与 pi 原生词表命中的重试——后者无标记）；
+ * - 锚文本 `rate limit 429 too many requests` 实测命中 pi-ai RETRYABLE 词表的
+ *   `rate.?limit` / `429` / `too many requests` 三条，且不含 NON_RETRYABLE 词表任何成员
+ *   （node_modules @earendil-works/pi-ai dist/utils/retry.js 1.0.0 实装核对）；
+ * - 追加式非替换式：原 errorMessage 完整保留在前段（pi 会话记录持久化改写形态，无信息丢失）。
+ */
+export const RETRY_REWRITE_MARKER = " [taiji-retry: rate limit 429 too many requests]";
+
+/** 改写标记前缀（幂等判定用）。 */
+export const RETRY_REWRITE_MARKER_PREFIX = "[taiji-retry:";
+
+/** 追加式改写：原文保留 + 标记追加；已带标记时原样返回（幂等）。 */
+export function appendRetryMarker(errorMessage: string): string {
+	if (errorMessage.includes(RETRY_REWRITE_MARKER_PREFIX)) return errorMessage;
+	return `${errorMessage}${RETRY_REWRITE_MARKER}`;
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { taijiTestConfig } from "../../../test-guard/factory.ts"
+
+export default taijiTestConfig({
+	test: {
+		include: ["src/__tests__/**/*.test.ts"],
+	},
+});