@zhushanwen/pi-permission 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-permission",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "Pi permission extension — four permission modes (yolo/auto/approve/strict) with three-layer pipeline (AST + rules + AI classifier).",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/legacy-tool-names.test.ts

@@ -0,0 +1,199 @@
+/**
+ * 旧工具名精确规则迁移测试（tool-declaration-slimming D3 / U-B1 验收条款②）。
+ *
+ * 表驱动六用例（五分支 + 分支5b 反向混合集）：
+ *  1. 精确旧名展开——subagent → start/manage/message、workflow → run/control，
+ *     展开顺序承重（D3 契约①），pattern/action/source/description 保留；
+ *  2. wildcard 不动——'*' 与其他含通配形态的 tool 一律原样；
+ *  3. 幂等——迁移结果再迁移深度相等（无旧名即零变化）；
+ *  4. 展开后 id 全唯一——makeNextIdCounter 从既有 user-N 最大值 +1 递增，
+ *     不与既有规则冲突、展开条目互不冲突；
+ *  5. 混合 wildcard 场景保序——经真实 matcher（matchNonBashTool，last-match-wins）
+ *     断言「新名调用在迁移后规则集上的结论 = 迁移前旧名调用在原规则集上的结论；
+ *     wildcard 对各调用的结论迁移前后不变」。旧名调用在迁移后不可达（旧工具名不再
+ *     注册，D3「旧名不保留别名」），不对其迁移后结论作断言；
+ *  5b. 反向混合集（wildcard deny 在前、精确 allow 在后）——与分支5互为镜像，
+ *     区分度弱，承重位置锚 = 精确条目仍在 wildcard 之前。
+ *
+ * 匹配器行为注释：matchNonBashTool 的 tool 字段经 wildcardToRegExp 全锚定匹配
+ * （精确名 = 精确匹配，'*' = 匹配全部）；pattern 对 path 匹配（path 缺省时对
+ * toolName）。测试用 path 固定为 "/x" 让 pattern '*' 命中路径、隔离 tool 维度。
+ */
+import { describe, expect, it } from "vitest";
+
+import type { Rule } from "../types.js";
+import { migrateLegacyToolRules } from "../rules/legacy-tool-names.js";
+import { matchNonBashTool } from "../pipeline.js";
+
+function userRule(overrides: Partial<Rule> & { id: string; tool: string }): Rule {
+	return {
+		pattern: "*",
+		action: "deny",
+		source: "user",
+		...overrides,
+	};
+}
+
+describe("旧工具名精确规则迁移（D3）— 表驱动六用例（五分支 + 分支5b 反向混合集）", () => {
+	it("分支1：精确旧名展开（subagent 三条 + workflow 两条，展开顺序承重，其余字段保留）", () => {
+		const rules: Rule[] = [
+			userRule({ id: "user-1", tool: "subagent", pattern: "*", action: "deny", description: "no subagent" }),
+			userRule({ id: "user-2", tool: "workflow", pattern: "*", action: "ask", description: "ask workflow" }),
+		];
+
+		const migrated = migrateLegacyToolRules(rules);
+
+		expect(migrated).toHaveLength(5);
+		// 展开顺序（D3 契约①）：subagent → start/manage/message；workflow → run/control
+		expect(migrated.map((r) => r.tool)).toEqual([
+			"subagent_start",
+			"subagent_manage",
+			"subagent_message",
+			"workflow_run",
+			"workflow_control",
+		]);
+		// 同 pattern/action/source/description 保留（只换 tool 名与 id）
+		expect(migrated[0]).toMatchObject({ pattern: "*", action: "deny", source: "user", description: "no subagent" });
+		expect(migrated[3]).toMatchObject({ pattern: "*", action: "ask", source: "user", description: "ask workflow" });
+		// 原数组不被改写（纯函数）
+		expect(rules).toHaveLength(2);
+		expect(rules[0]?.tool).toBe("subagent");
+	});
+
+	it("分支2：wildcard 与其他工具规则不动；无旧名时零拷贝快速路径", () => {
+		const wildcardRule = userRule({ id: "user-7", tool: "*", action: "allow" });
+		const bashRule = userRule({ id: "user-8", tool: "bash", pattern: "git *" });
+		const readGlobRule = userRule({ id: "user-9", tool: "read*", pattern: "*" });
+		const rules = [wildcardRule, bashRule, readGlobRule];
+		const migrated = migrateLegacyToolRules(rules);
+
+		// 无旧名规则 → 返回原数组引用（零拷贝快速路径），条目零变化
+		expect(migrated).toBe(rules);
+		expect(migrated.map((r) => r.tool)).toEqual(["*", "bash", "read*"]);
+	});
+
+	it("分支3：幂等（已迁移配置再迁移深度相等）", () => {
+		const legacy: Rule[] = [
+			userRule({ id: "user-1", tool: "subagent", action: "deny" }),
+			userRule({ id: "user-2", tool: "workflow", action: "ask" }),
+			userRule({ id: "user-3", tool: "*", action: "allow" }),
+		];
+		const once = migrateLegacyToolRules(legacy);
+		const twice = migrateLegacyToolRules(once);
+
+		expect(twice).toEqual(once);
+		expect(twice).toHaveLength(once.length);
+	});
+
+	it("分支4：展开后 id 全唯一（不与既有冲突、互不冲突、makeNextIdCounter 递增形态）", () => {
+		const rules: Rule[] = [
+			userRule({ id: "user-2", tool: "subagent", action: "deny" }),
+			userRule({ id: "user-5", tool: "read", action: "allow" }),
+			userRule({ id: "user-3", tool: "workflow", action: "ask" }),
+		];
+		const migrated = migrateLegacyToolRules(rules);
+
+		const ids = migrated.map((r) => r.id);
+		expect(new Set(ids).size).toBe(ids.length);
+		// 未迁移规则 id 保持不变
+		expect(migrated.find((r) => r.tool === "read")?.id).toBe("user-5");
+		// 展开条目全部是新分配的 user-N（> 既有最大值 5）
+		const expandedIds = migrated.filter((r) => r.tool.startsWith("subagent_") || r.tool.startsWith("workflow_")).map((r) => r.id);
+		expect(expandedIds).toHaveLength(5);
+		for (const id of expandedIds) {
+			expect(id).toMatch(/^user-(\d+)$/);
+			expect(Number.parseInt(id.slice(5), 10)).toBeGreaterThan(5);
+		}
+	});
+
+	it("分支5：混合 wildcard 场景保序（真实 matcher：新名结论 = 迁移前旧名结论；wildcard 结论不变）", () => {
+		// 混合规则集 A：精确 deny 在前、wildcard allow 在后——last-match-wins 下
+		// 尾部 wildcard allow 覆盖前面的精确 deny（旧名调用结论 = allow）。
+		// 若迁移把展开规则错误地追加到数组尾部（D3 契约①禁止的实装），新名 deny 会
+		// 落到 wildcard allow 之后 → 结论翻成 deny ≠ 旧行为，本断言即红灯。
+		const mixed: Rule[] = [
+			userRule({ id: "user-1", tool: "subagent", pattern: "*", action: "deny" }),
+			userRule({ id: "user-2", tool: "workflow", pattern: "*", action: "deny" }),
+			userRule({ id: "user-3", tool: "*", pattern: "*", action: "allow" }),
+			userRule({ id: "user-4", tool: "read", pattern: "*", action: "allow" }),
+		];
+
+		const migrated = migrateLegacyToolRules(mixed);
+
+		// 保序：精确规则与其展开条目的相对位置不变（wildcard 仍在展开条目之后）
+		const tools = migrated.map((r) => r.tool);
+		expect(tools).toEqual([
+			"subagent_start",
+			"subagent_manage",
+			"subagent_message",
+			"workflow_run",
+			"workflow_control",
+			"*",
+			"read",
+		]);
+
+		// ① 迁移前旧名调用的结论
+		const before = {
+			subagent: matchNonBashTool("subagent", "/x", mixed).action,
+			workflow: matchNonBashTool("workflow", "/x", mixed).action,
+		};
+		// ② 迁移后新名调用的结论（拆分后旧名不可达，只有新名可调用）
+		const after = {
+			subagentStart: matchNonBashTool("subagent_start", "/x", migrated).action,
+			subagentManage: matchNonBashTool("subagent_manage", "/x", migrated).action,
+			subagentMessage: matchNonBashTool("subagent_message", "/x", migrated).action,
+			workflowRun: matchNonBashTool("workflow_run", "/x", migrated).action,
+			workflowControl: matchNonBashTool("workflow_control", "/x", migrated).action,
+		};
+
+		expect(after.subagentStart).toBe(before.subagent);
+		expect(after.subagentManage).toBe(before.subagent);
+		expect(after.subagentMessage).toBe(before.subagent);
+		expect(after.workflowRun).toBe(before.workflow);
+		expect(after.workflowControl).toBe(before.workflow);
+		// 显式值锚（场景 A 真实结论）：尾部 wildcard allow 覆盖精确 deny
+		expect(before.subagent).toBe("allow");
+		expect(after.subagentStart).toBe("allow");
+
+		// ③ wildcard 与其他规则对各调用的结论迁移前后不变
+		expect(matchNonBashTool("read", "/x", migrated).action).toBe(matchNonBashTool("read", "/x", mixed).action);
+		expect(matchNonBashTool("bash", "/x", migrated).action).toBe(matchNonBashTool("bash", "/x", mixed).action);
+	});
+
+	it("分支5b：反向混合集（wildcard deny 在前、精确 allow 在后）保序——新名结论 = 旧名结论", () => {
+		// 与分支5互为镜像：旧名调用结论 = deny（尾部精确 allow 被…不——allow 在
+		// wildcard deny 之后，last-match-wins 下 allow 胜。若错误追加，新名 allow
+		// 落在最后 → 仍 allow，本场景区分度弱；承重面是「精确条目仍在 wildcard
+		// 之前」的位置锚 + 与分支5合并覆盖两个方向）。
+		const mixed: Rule[] = [
+			userRule({ id: "user-1", tool: "*", pattern: "*", action: "deny" }),
+			userRule({ id: "user-2", tool: "subagent", pattern: "*", action: "allow" }),
+			userRule({ id: "user-3", tool: "workflow", pattern: "*", action: "ask" }),
+		];
+		const migrated = migrateLegacyToolRules(mixed);
+
+		// 位置锚：展开条目紧跟原规则原位（wildcard deny 保持在前）
+		expect(migrated.map((r) => r.tool)).toEqual([
+			"*",
+			"subagent_start",
+			"subagent_manage",
+			"subagent_message",
+			"workflow_run",
+			"workflow_control",
+		]);
+
+		const beforeSubagent = matchNonBashTool("subagent", "/x", mixed).action;
+		const beforeWorkflow = matchNonBashTool("workflow", "/x", mixed).action;
+		expect(matchNonBashTool("subagent_start", "/x", migrated).action).toBe(beforeSubagent);
+		expect(matchNonBashTool("subagent_manage", "/x", migrated).action).toBe(beforeSubagent);
+		expect(matchNonBashTool("subagent_message", "/x", migrated).action).toBe(beforeSubagent);
+		expect(matchNonBashTool("workflow_run", "/x", migrated).action).toBe(beforeWorkflow);
+		expect(matchNonBashTool("workflow_control", "/x", migrated).action).toBe(beforeWorkflow);
+		// 显式值锚：尾部精确 allow/ask 胜出前部 wildcard deny
+		expect(beforeSubagent).toBe("allow");
+		expect(beforeWorkflow).toBe("ask");
+		// wildcard deny 对无关工具的结论迁移前后不变（bash 只被头部 wildcard deny 命中）
+		expect(matchNonBashTool("bash", "/x", migrated).action).toBe(matchNonBashTool("bash", "/x", mixed).action);
+		expect(matchNonBashTool("bash", "/x", mixed).action).toBe("deny");
+	});
+});

package/src/config.ts

@@ -36,6 +36,7 @@ import {
 	type PermissionConfig,
 	type Rule,
 } from "./types.js";
+import { migrateLegacyToolRules } from "./rules/legacy-tool-names.js";
 
 /** llm-shared 泛型 config 的包名（决定文件名 permission-ext-config.json，llm-shared getConfigPath 追加 -ext-config.json 后缀）。 */
 const CONFIG_PKG = "permission";
@@ -139,11 +140,18 @@ function warnLegacyConfigIfExists(): void {
 /**
  * 加载配置：文件缺失时创建默认配置文件并返回默认值；
  * 坏 JSON / normalize 失败回落默认值（onWarning 回调）。mtime+size 缓存由 llm-shared 提供。
+ *
+ * 返回前应用旧工具名精确规则迁移（rules/legacy-tool-names.ts，tool-declaration-slimming
+ * D3：subagent/workflow 拆分改名后，持久化的旧名精确规则原地展开为新名规则——
+ * 原地替换保序 + makeNextIdCounter 新 id + 幂等；只内存展开，不回写落盘，加载路径纯读）。
+ * 所有配置消费方（pipeline / rule-editor / statusline / commands）都经本入口取 config，
+ * 迁移单点在此即全消费面生效。
  */
 export function loadAndWatchConfig(onWarning?: (msg: string) => void): PermissionConfig {
 	const configPath = getConfigPath();
 	ensureConfigFile(configPath, onWarning);
-	return loadConfig(CONFIG_PKG, DEFAULT_CONFIG, normalizeConfig, onWarning);
+	const config = loadConfig(CONFIG_PKG, DEFAULT_CONFIG, normalizeConfig, onWarning);
+	return { ...config, userRules: migrateLegacyToolRules(config.userRules) };
 }
 
 // ──────────────────────── 保存（原子写） ────────────────────────

package/src/rules/legacy-tool-names.ts

@@ -0,0 +1,70 @@
+/**
+ * 旧工具名精确规则一次性迁移（tool-declaration-slimming D3 / U-B1）。
+ *
+ * 背景：subagent-workflow 扩展的 `subagent`/`workflow` 工具已拆分为
+ * subagent_start/subagent_manage/subagent_message 与 workflow_run/workflow_control，
+ * 旧名不保留别名（探针 PB-fork）。用户权限规则按工具名匹配（`Rule.tool`）并持久化
+ * 落盘（config.ts saveConfig），旧名精确规则随改名失配——deny 静默退化成 ask/AI 分类。
+ *
+ * 迁移语义（D3 两条契约）：
+ *  ① 展开落位与保序——精确匹配旧名的用户规则**原地替换**为其新名展开（展开顺序
+ *     subagent → start/manage/message、workflow → run/control），与未迁移规则的相对
+ *     次序保持不变。matcher 是 last-match-wins 按数组顺序遍历（rules/matcher.ts
+ *     lastMatchWins），「收集展开规则追加到数组尾部」式实装会静默翻转混合规则集
+ *     （精确规则与 wildcard 规则共存）的 deny/allow 胜负且无报错。
+ *  ② 新 id——展开出的每条分配新 id（复用 rule-templates.ts 的 makeNextIdCounter，
+ *     从既有 user-N 最大值 +1 递增），禁止克隆原对象共享 id：Rule.id 语义为唯一 id
+ *     （types.ts），rule-editor 按 id 键控删除（rule-editor.ts delete op），同 id 多条
+ *     会导致删除错乱。
+ *
+ * 范围与幂等：
+ *  - 只迁移**精确等于**旧名的 tool 字段（`rule.tool === "subagent"` / `"workflow"`）；
+ *    wildcard（`'*'`）与其他含通配形态的规则一律不动（D3：wildcard 规则不动）。
+ *  - 幂等：新名不在旧名集合中，已迁移的配置再次加载零变化。
+ *  - 只在内存展开（loadAndWatchConfig 读时迁移），不回写落盘——加载路径保持纯读；
+ *    用户下次经 rule-editor 保存时自然持久化新名形态。
+ *
+ * 跨包契约登记：本表展开目标名与 subagent-workflow 的工具注册名互为跨包隐式契约
+ * （两包无 import 依赖，漂移零报错）——SW 工具再拆分/改名须同步本表（旧名进 key、
+ * 新名进展开目标），失配后果 = 旧名 deny 规则静默退化成 ask/AI 分类。登记条目见
+ * docs/extensions/extension-conventions.md「跨包隐式契约：permission 旧名展开表
+ * ↔ subagent-workflow 工具注册名」。
+ */
+
+import type { Rule } from "../types.js";
+import { makeNextIdCounter } from "../rule-templates.js";
+
+/** 精确旧名 → 拆分新名展开表（顺序承重：D3 契约①的展开次序）。 */
+const LEGACY_TOOL_NAME_EXPANSION: Readonly<Record<string, readonly string[]>> = {
+	subagent: ["subagent_start", "subagent_manage", "subagent_message"],
+	workflow: ["workflow_run", "workflow_control"],
+};
+
+/**
+ * 对规则数组做旧名精确规则迁移（纯函数，幂等，保序）。
+ *
+ * - 非迁移规则原样保留（同对象引用），相对次序不变；
+ * - 命中旧名的规则原地展开为 N 条新名规则（pattern/action/source/description 保留，
+ *   tool 换新名、id 全新递增分配）；
+ * - 无旧名规则时返回原数组引用（零拷贝快速路径）。
+ */
+export function migrateLegacyToolRules(rules: Rule[]): Rule[] {
+	const hasLegacy = rules.some((rule) => LEGACY_TOOL_NAME_EXPANSION[rule.tool] !== undefined);
+	if (!hasLegacy) return rules;
+
+	// 新 id 分配基准 = 迁移前全部既有规则（含将被展开的旧名规则本身）——
+	// makeNextIdCounter 从 user-N 最大值 +1 递增，展开条目不与任何既有 id 冲突。
+	const nextId = makeNextIdCounter(rules);
+	const result: Rule[] = [];
+	for (const rule of rules) {
+		const expansion = LEGACY_TOOL_NAME_EXPANSION[rule.tool];
+		if (expansion === undefined) {
+			result.push(rule);
+			continue;
+		}
+		for (const tool of expansion) {
+			result.push({ ...rule, id: nextId(), tool });
+		}
+	}
+	return result;
+}