pi-error-retry 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 更新日志
+
+## 0.2.0
+
+- 新增 `/error-retry import <文件路径>` 和 `/error-retry export <文件路径>`。
+- 兼容 DSH v1 规则文件、原生配置对象和裸规则数组；导出文件可直接导入 DSH。
+- 导入先校验、确认后替换，并保留配置冲突和会话生命周期保护。
+- 导出原子创建新文件，不覆盖已有目标；支持默认规则导出、1 MiB 大小限制和失败清理。
+- 源码改由 `librola/pi-extensions-shuyuan` 统一管理，npm 包名保持 `pi-error-retry`。
+
+## 0.1.0
+
+- 按规则无限重试匹配的模型错误，并在输出长度截断后自动续写。
+- 提供规则编辑、热更新、配置冲突校验和标准停止行为。

package/README.md

@@ -1,6 +1,6 @@
 # pi-error-retry
 
-独立 Pi 扩展，移植 `@local/dsh-error-retry` 的规则重试行为，并增加输出长度截断后的自动续写。当前在本机 Pi **1.4.0** 上验证。
+独立 Pi 扩展，移植 `@local/dsh-error-retry` 的规则重试行为，并增加输出长度截断后的自动续写及规则导入／导出命令。当前在本机 Pi **1.5.2** 上验证。
 
 ## 必须区分的两种行为
 
@@ -29,10 +29,10 @@ Pi 自带的有限错误重试先行；它耗尽后，本扩展接管匹配错
 pi install npm:pi-error-retry
 ```
 
-也可直接从 GitHub 安装：
+本扩展现与 `pi-background-bash` 在[统一仓库](../README.md)管理。直接从 GitHub 安装两个扩展：
 
 ```sh
-pi install git:github.com/librola/pi-error-retry
+pi install git:github.com/librola/pi-extensions-shuyuan
 ```
 
 在现有 Pi 会话中执行 `/reload`；新会话自动加载。克隆后的本地源码无需编译，也可临时加载：
@@ -41,6 +41,8 @@ pi install git:github.com/librola/pi-error-retry
 pi -e ./pi-error-retry/index.ts
 ```
 
+仅安装本扩展时，使用 `pi install ~/pi-dev/pi-extensions-shuyuan/pi-error-retry`。不要与原来的独立包重复加载。
+
 安装声明位于 `~/.pi/agent/settings.json` 的 `packages` 数组。本扩展只注册事件和用户命令，没有新增模型可调用的配置工具。
 
 不要同时启用其他错误恢复／长度续写扩展，避免竞争触发。
@@ -56,9 +58,11 @@ pi -e ./pi-error-retry/index.ts
 设置了 `PI_CODING_AGENT_DIR` 时使用该目录。规则只从用户目录读取，不读取项目里的规则覆盖。
 
 ```text
-/error-retry        查看规则数量、配置位置和两种恢复行为
-/error-retry edit   用 Pi 原生 JSON 编辑器修改规则
-/error-retry stop   停止当前请求
+/error-retry                 查看规则数量、配置位置和两种恢复行为
+/error-retry edit            用 Pi 原生 JSON 编辑器修改规则
+/error-retry stop            停止当前请求
+/error-retry import <路径>   校验规则文件，确认后替换当前规则
+/error-retry export <路径>   将当前有效规则导出为 DSH v1 JSON 文件
 ```
 
 Pi 原生编辑器适用于 TUI 和支持该对话协议的 RPC 客户端；不提供 DSH 的插件详情页。JSON／print 模式请直接编辑文件。
@@ -69,6 +73,21 @@ Pi 原生编辑器适用于 TUI 和支持该对话协议的 RPC 客户端；不
 - 保存不取消已经排定的等待；已排定的重试可能完成一次，下一次错误判定读取新规则。立即停止请使用标准停止按钮或 `/error-retry stop`。
 - 非法配置、读取失败或正则匹配超时不被当成命中，也不静默回退为宽泛规则。
 
+### 导入与导出
+
+```text
+/error-retry import ~/Downloads/dsh-error-retry-rules.json
+/error-retry export ~/Downloads/pi-error-retry-rules.json
+/error-retry import "./rules backup.json"
+```
+
+- 导入兼容 DSH 的 `{ "version": 1, "rules": [...] }`、本插件的 `{ "rules": [...] }`，也接受裸规则数组；空数组合法，缺少 `rules`、未知版本、额外字段及非法规则会被拒绝。用户配置文件仍只保存 `{ "rules": [...] }`，格式不变。
+- 导入先解析并复用保存校验，再显示来源、规则数量和风险确认。确认后**替换整组规则，不追加**；取消、校验失败或确认期间发生配置冲突都不会覆盖原配置。TUI 和支持确认对话的 RPC 客户端可用；JSON／print 模式不跳过确认，因而拒绝导入。
+- 导出当前已保存的有效规则，不包含编辑器未保存草稿、会话状态或凭据。没有用户配置文件时导出默认规则，不顺便创建用户配置。输出格式为 `{ "version": 1, "rules": [...] }`，可直接导入 DSH。
+- 导出**只创建新文件，不覆盖已有文件或符号链接**，也不能导出到正在使用的配置路径。目标目录需已存在；文件权限为 0600，原子发布完整内容，失败时清理临时文件。导入和导出文件均限制为 1 MiB。
+- 路径相对于当前会话的工作目录，支持绝对路径、`~/`、空格及成对的单／双引号；不展开环境变量或通配符，不执行 shell。路径是 **Pi 进程所在机器**的文件路径；Pi Web 不会把浏览器本机文件自动上传或下载。
+- 命令不调用模型、不写模型上下文；导入不自动 reload、不取消已排定等待，新规则从下一次错误判定生效。reload 或会话切换会取消尚未完成的导入确认。
+
 ### 规则格式
 
 ```json
@@ -110,7 +129,9 @@ Pi 原生编辑器适用于 TUI 和支持该对话协议的 RPC 客户端；不
 
 ## 验证
 
-开发依赖安装不会安装另一份 Pi：
+统一开发优先在仓库根目录执行 `npm ci --include=dev --ignore-scripts --legacy-peer-deps` 和 `npm run check`，参见[根目录说明](../README.md#开发与验证)。
+
+也可在本扩展目录独立开发；以下安装方式不会自动安装 peer Pi：
 
 ```sh
 npm install --ignore-scripts --legacy-peer-deps
@@ -121,9 +142,9 @@ npm test
 
 `PI_TEST_PACKAGE` 指向已安装 Pi 的包清单。不设置时从项目依赖中寻找宿主 Pi。测试使用真实 SDK、扩展 TypeScript 加载器、会话上下文投影及模拟 provider；不调用真实模型，也不读取用户模型凭据。临时文件在系统临时目录中创建和清理。
 
-覆盖：101 次连续错误、内置重试串联、请求输入不变、截断前文保留、截断后错误重试、已执行工具不重放、截断工具不执行、取消长等待、规则热更新／冲突／校验、正则超时、退避、服务端等待及日志计数隔离。
+覆盖：101 次连续错误、内置重试串联、请求输入不变、截断前文保留、截断后错误重试、已执行工具不重放、截断工具不执行、取消长等待、规则热更新／冲突／校验、正则超时、退避、服务端等待及日志计数隔离；另覆盖 DSH／原生／裸数组导入、确认与取消、并发配置冲突、生命周期失效、默认规则导出、文件大小边界、路径解析、禁止覆盖、原子发布和磁盘写入失败清理，以及真实 SDK 的命令派发与导入后规则生效。
 
-当前 **32 项测试通过**，TypeScript 严格类型检查通过。
+当前 **51 项测试通过**，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()`。
 

package/index.ts

@@ -3,6 +3,7 @@ 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 { exportRulesFile, readRulesFile, resolveRulesFilePath } from "./src/transfer.ts";
 import { matchesRules, policyKey, providerRetryAfter, retryDelay, waitForRetry } from "./src/rules.ts";
 
 export const RECOVERY_ENTRY = "pi-error-retry.recovery";
@@ -148,19 +149,50 @@ export function registerErrorRetry(pi: ExtensionAPI, configPath: string): void {
 	});
 
 	pi.registerCommand("error-retry", {
-		description: "查看错误重试规则；/error-retry edit 编辑规则，/error-retry stop 停止当前请求",
+		description: "查看规则；edit 编辑，stop 停止，import <路径> 导入，export <路径> 导出",
 		handler: async (args, ctx) => {
-			const action = args.trim();
-			if (action === "stop") {
+			const commandLifetime = lifetime;
+			if (commandLifetime.signal.aborted) return;
+			const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(args.trim());
+			const action = match?.[1] ?? "";
+			const argument = match?.[2]?.trim() ?? "";
+			if (action === "stop" && !argument) {
 				pendingRetry = undefined;
 				ctx.abort();
 				return;
 			}
-			if (action && action !== "edit") {
-				ctx.ui.notify("用法：/error-retry [edit|stop]", "warning");
+			if ((action && !["edit", "import", "export"].includes(action)) ||
+				(action === "edit" && argument) || (["import", "export"].includes(action) && !argument)) {
+				ctx.ui.notify("用法：/error-retry [edit|stop|import <文件路径>|export <文件路径>]", "warning");
 				return;
 			}
 			try {
+				if (action === "import" || action === "export") {
+					const path = resolveRulesFilePath(argument, ctx.cwd);
+					if (action === "export") {
+						const config = exportRulesFile(configPath, path);
+						ctx.ui.notify(`已导出 ${config.rules.length} 条规则：${path}（DSH v1 格式）`, "info");
+						return;
+					}
+					if (!ctx.hasUI) {
+						ctx.ui.notify("当前模式无法确认替换规则，请在 TUI 或支持确认对话的 RPC 客户端导入", "warning");
+						return;
+					}
+					const snapshot = readConfig(configPath);
+					const incoming = readRulesFile(path);
+					const confirmed = await ctx.ui.confirm("导入错误重试规则",
+						`从 ${path} 导入 ${incoming.rules.length} 条规则，将替换当前 ${snapshot.config.rules.length} 条规则。保存不取消已排定的等待；无限重试可能产生持续请求和费用。是否继续？`,
+						{ signal: commandLifetime.signal });
+					// 对话可能跨越 reload 或会话切换；旧命令不能继续写文件或通知新会话。
+					if (commandLifetime.signal.aborted) return;
+					if (!confirmed) {
+						ctx.ui.notify("已取消导入，规则未修改", "info");
+						return;
+					}
+					const config = saveConfig(configPath, incoming, snapshot.revision);
+					ctx.ui.notify(`已导入 ${config.rules.length} 条规则，替换原规则；下次错误判定自动生效`, "info");
+					return;
+				}
 				const snapshot = readConfig(configPath);
 				if (action !== "edit") {
 					ctx.ui.notify(`错误规则：${snapshot.config.rules.length} 条（命中后无限重试）；长度截断：自动继续。配置：${configPath}`, "info");
@@ -191,7 +223,9 @@ export function registerErrorRetry(pi: ExtensionAPI, configPath: string): void {
 					}
 				}
 			} catch (error) {
-				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				if (!commandLifetime.signal.aborted) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
 			}
 		},
 	});

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "pi-error-retry",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "按规则无限重试 Pi 模型错误，并在长度截断时自动继续",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/librola/pi-error-retry.git"
+    "url": "git+https://github.com/librola/pi-extensions-shuyuan.git",
+    "directory": "pi-error-retry"
   },
-  "homepage": "https://github.com/librola/pi-error-retry#readme",
+  "homepage": "https://github.com/librola/pi-extensions-shuyuan/tree/main/pi-error-retry#readme",
   "bugs": {
-    "url": "https://github.com/librola/pi-error-retry/issues"
+    "url": "https://github.com/librola/pi-extensions-shuyuan/issues"
   },
   "files": [
+    "CHANGELOG.md",
     "index.ts",
     "src/",
     "examples/"

package/src/transfer.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, linkSync, openSync, readSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { readConfig } from "./config.ts";
+import { type RetryConfig, validateConfig } from "./rules.ts";
+
+const MAX_RULES_FILE_BYTES = 1024 * 1024;
+
+/** 将命令剩余参数作为一个路径，不执行 shell 或展开环境变量。 */
+export function resolveRulesFilePath(argument: string, cwd: string): string {
+	let path = argument.trim();
+	if (path.startsWith('"') || path.startsWith("'")) {
+		if (path.length < 2 || path.at(-1) !== path[0]) throw new Error("文件路径的引号必须成对");
+		path = path.slice(1, -1);
+	}
+	if (!path.trim() || path.includes("\0")) throw new Error("请提供有效的 JSON 文件路径");
+	if (path === "~") path = homedir();
+	else if (path.startsWith("~/")) path = join(homedir(), path.slice(2));
+	return resolve(cwd, path);
+}
+
+/** 读取 DSH v1、原生配置对象或裸规则数组，统一使用现有规则校验。 */
+export function readRulesFile(path: string): RetryConfig {
+	// 非阻塞打开后检查同一个描述符，拒绝 FIFO、设备等可能让命令一直等待的输入。
+	const file = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	let text: string;
+	try {
+		const stat = fstatSync(file);
+		if (!stat.isFile()) throw new Error("导入路径必须是普通 JSON 文件");
+		if (stat.size > MAX_RULES_FILE_BYTES) throw new Error("规则文件过大（超过 1 MiB）");
+		// 读取上限不依赖最初的 stat，文件并发增长也不会无限分配内存。
+		const buffer = Buffer.alloc(MAX_RULES_FILE_BYTES + 1);
+		let size = 0;
+		while (size < buffer.length) {
+			const count = readSync(file, buffer, size, buffer.length - size, null);
+			if (count === 0) break;
+			size += count;
+		}
+		if (size > MAX_RULES_FILE_BYTES) throw new Error("规则文件过大（超过 1 MiB）");
+		text = buffer.subarray(0, size).toString("utf8").replace(/^\uFEFF/, "");
+	} finally {
+		closeSync(file);
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		throw new Error(`JSON 解析失败：${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (Array.isArray(value)) return validateConfig({ rules: value });
+	if (!value || typeof value !== "object") throw new Error("规则文件必须包含 rules 数组或直接提供规则数组");
+	const object = value as Record<string, unknown>;
+	if (Object.keys(object).some((key) => key !== "version" && key !== "rules")) {
+		throw new Error("规则文件仅接受 version、rules 字段");
+	}
+	if (object.version !== undefined && object.version !== 1) throw new Error("不支持的规则文件版本，仅支持 version: 1");
+	// 导入缺少 rules 的文件不能意外启用默认规则；用户配置读取的旧行为不变。
+	if (!Array.isArray(object.rules)) throw new Error("规则文件必须包含 rules 数组");
+	return validateConfig({ rules: object.rules });
+}
+
+/** 导出当前有效规则为 DSH v1 文件，原子创建新文件，绝不覆盖已有目标。 */
+export function exportRulesFile(configPath: string, destination: string): RetryConfig {
+	const config = readConfig(configPath).config;
+	const target = join(realpathSync(dirname(destination)), basename(destination));
+	let active = resolve(configPath);
+	try {
+		active = join(realpathSync(dirname(active)), basename(active));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	if (target === active) throw new Error("不能导出到正在使用的配置文件，请选择其他路径");
+	const rules = config.rules.map((rule) => rule.mode === "regex" ? { ...rule, flags: rule.flags ?? "" } : { ...rule });
+	const text = `${JSON.stringify({ version: 1, rules }, null, 2)}\n`;
+	if (Buffer.byteLength(text) > MAX_RULES_FILE_BYTES) throw new Error("导出规则文件过大（超过 1 MiB）");
+	const temporary = `${target}.${randomUUID()}.tmp`;
+	const file = openSync(temporary, "wx", 0o600);
+	try {
+		try {
+			writeFileSync(file, text);
+		} finally {
+			closeSync(file);
+		}
+		// 同目录硬链接一次发布完整内容；目标在检查后被创建也不会被覆盖。
+		try {
+			linkSync(temporary, target);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`导出目标已存在，未覆盖：${destination}`);
+			throw error;
+		}
+	} finally {
+		unlinkSync(temporary);
+	}
+	return config;
+}