pi-shepherd 0.1.2 → 0.2.0

package/shepherd/rules-tool.ts

@@ -1,142 +1,182 @@
-/**
- * Shepherd 规则编辑工具注册
- *
- * 注册 shepherd_rules 工具到 pi，提供规则文件的安全增删改查。
- * 支持 scope 参数区分全局/项目级规则。
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { addRule, deleteRule, updateRule } from "./rules-editor";
-import {
-	type Scope,
-	checkCrossScopeDuplicate,
-	ensureProjectDir,
-	getRulesFilePath,
-} from "./rules-tool-helpers";
-import {
-	handleListByIndex,
-	handleListSummary,
-	handleListVerbose,
-	scopeLabel,
-	textResult,
-} from "./rules-tool-list";
-
-export function registerRulesEditorTool(pi: ExtensionAPI, rulesDir: string, cwd?: string) {
-	const effectiveCwd = cwd || process.cwd();
-
-	pi.registerTool({
-		name: "shepherd_rules",
-		label: "Shepherd Rules Editor",
-		description:
-			"安全编辑 shepherd 规则文件。支持 list（列出所有规则）、add（添加规则）、update（部分更新规则）、delete（删除规则）。" +
-			"scope='global' 操作全局规则 (~/.pi/agent/extensions/shepherd/rules.json)；" +
-			"scope='project' 操作当前项目规则 (<cwd>/.pi/extensions/shepherd-rules.json)。" +
-			"写入前自动校验必填字段和正则合法性，写入后回读验证，失败自动从备份恢复。" +
-			"同签名规则（tool+hook+pattern/check+action）自动覆盖而非追加。",
-		parameters: {
-			type: "object",
-			properties: {
-				action: {
-					type: "string",
-					enum: ["list", "add", "update", "delete"],
-					description: "操作类型",
-				},
-				scope: {
-					type: "string",
-					enum: ["global", "project"],
-					description:
-						"操作目标：global=全局规则（默认），project=当前项目规则。list 不传 scope 时返回全局+项目合并列表（标注来源），写操作默认 global。",
-				},
-				rule: {
-					type: "object",
-					description: "add 时传入的完整规则对象（必须含 comment 和 reason）",
-				},
-				index: {
-					type: "number",
-					description:
-						"规则编号（0-based，仅在对应 scope 文件内的索引）。list 时传 index 显示该条规则的完整 JSON；update/delete 时指定要操作的规则。",
-				},
-				verbose: {
-					type: "boolean",
-					description:
-						"list 时传 true 显示每条规则的完整字段（含 reason、conditions、pattern 等），默认 false 只显示摘要。",
-				},
-				changes: {
-					type: "object",
-					description: "update 时要修改的字段（只传需要改的）",
-				},
-			},
-			required: ["action"],
-		},
-		async execute(
-			_toolCallId: string,
-			params: {
-				action: "list" | "add" | "update" | "delete";
-				scope?: Scope;
-				rule?: Record<string, unknown>;
-				index?: number;
-				verbose?: boolean;
-				changes?: Record<string, unknown>;
-			},
-		) {
-			const scope = params.scope;
-
-			switch (params.action) {
-				case "list": {
-					// index 指定 → 显示单条完整 JSON
-					if (params.index !== undefined) {
-						return handleListByIndex(scope, params.index, rulesDir, effectiveCwd);
-					}
-					// verbose=true → 显示所有规则的完整信息
-					if (params.verbose === true) {
-						return handleListVerbose(scope, rulesDir, effectiveCwd);
-					}
-					// 默认摘要模式
-					return handleListSummary(scope, rulesDir, effectiveCwd);
-				}
-				case "add": {
-					if (!params.rule) return textResult("❌ add 需要 rule 参数");
-					const targetScope = scope || "global";
-					const filePath = getRulesFilePath(targetScope, rulesDir, effectiveCwd);
-					if (targetScope === "project") ensureProjectDir(effectiveCwd);
-					const result = addRule(filePath, params.rule);
-					if (!result.success) return textResult(`❌ ${result.error}`);
-					const warning = checkCrossScopeDuplicate(
-						targetScope,
-						rulesDir,
-						effectiveCwd,
-						params.rule,
-					);
-					const overwrittenMsg = result.overwritten ? " (覆盖已有同签名规则)" : "";
-					const warningMsg = warning ? `\n${warning}` : "";
-					return textResult(
-						`✅ ${scopeLabel(targetScope)}规则已添加 [${targetScope}:${result.index}]${overwrittenMsg}${warningMsg}`,
-					);
-				}
-				case "update": {
-					if (params.index === undefined) return textResult("❌ update 需要 index 参数");
-					if (!params.changes) return textResult("❌ update 需要 changes 参数");
-					const targetScope = scope || "global";
-					const filePath = getRulesFilePath(targetScope, rulesDir, effectiveCwd);
-					const result = updateRule(filePath, params.index, params.changes);
-					return result.success
-						? textResult(`✅ ${scopeLabel(targetScope)}规则 [${targetScope}:${params.index}] 已更新`)
-						: textResult(`❌ ${result.error}`);
-				}
-				case "delete": {
-					if (params.index === undefined) return textResult("❌ delete 需要 index 参数");
-					const targetScope = scope || "global";
-					const filePath = getRulesFilePath(targetScope, rulesDir, effectiveCwd);
-					const result = deleteRule(filePath, params.index);
-					return result.success
-						? textResult(
-								`✅ ${scopeLabel(targetScope)}规则已删除: ${(result.deleted as any)?.comment || ""}`,
-							)
-						: textResult(`❌ ${result.error}`);
-				}
-				default:
-					return textResult(`❌ 未知操作: ${(params as any).action}`);
-			}
-		},
-	});
-}
+/**
+ * Shepherd 规则编辑工具注册
+ *
+ * 注册 shepherd_rules 工具到 pi，提供规则文件的安全增删改查。
+ * 支持 scope 参数区分全局/项目级规则。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { addRule, deleteRule, updateRule } from "./rules-editor";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import {
+	checkCrossScopeDuplicate,
+	ensureProjectDir,
+	getRulesFilePath,
+	type Scope,
+} from "./rules-tool-helpers";
+import {
+	handleListByIndex,
+	handleListSummary,
+	handleListVerbose,
+	scopeLabel,
+	textResult,
+} from "./rules-tool-list";
+
+export function registerRulesEditorTool(
+	pi: ExtensionAPI,
+	rulesDir: string,
+	cwd?: string,
+) {
+	const effectiveCwd = cwd || process.cwd();
+
+	pi.registerTool({
+		name: "shepherd_rules",
+		label: "Shepherd Rules Editor",
+		description:
+			"安全编辑 shepherd 规则文件。支持 list（列出所有规则）、add（添加规则）、update（部分更新规则）、delete（删除规则）。" +
+			"scope='global' 操作全局规则 (~/.pi/agent/extensions/shepherd/rules.json)；" +
+			"scope='project' 操作当前项目规则 (<cwd>/.pi/extensions/shepherd-rules.json)。" +
+			"写入前自动校验必填字段和正则合法性，写入后回读验证，失败自动从备份恢复。" +
+			"同签名规则（tool+hook+pattern/check+action）自动覆盖而非追加。" +
+			"\n\n⚠️ 关闭/禁用规则：action 是规则匹配后的执行动作（block/notify/rewrite/steer），不能用来关闭规则。" +
+			"想临时关掉某条提示请用 update(index=N, changes={enabled:false})（保留规则，以后改 enabled:true 恢复）；" +
+			"彻底删除用 delete(index=N)。操作前先 list(verbose=true) 找到目标规则 index。",
+		promptSnippet: "编辑 shepherd 防护规则",
+		parameters: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: ["list", "add", "update", "delete"],
+					description: "操作类型",
+				},
+				scope: {
+					type: "string",
+					enum: ["global", "project"],
+					description:
+						"操作目标：global=全局规则（默认），project=当前项目规则。list 不传 scope 时返回全局+项目合并列表（标注来源），写操作默认 global。",
+				},
+				rule: {
+					type: "object",
+					description: "add 时传入的完整规则对象（必须含 comment 和 reason）",
+				},
+				index: {
+					type: "number",
+					description:
+						"规则编号（0-based，仅在对应 scope 文件内的索引）。list 时传 index 显示该条规则的完整 JSON；update/delete 时指定要操作的规则。",
+				},
+				verbose: {
+					type: "boolean",
+					description:
+						"list 时传 true 显示每条规则的完整字段（含 reason、conditions、pattern 等），默认 false 只显示摘要。",
+				},
+				changes: {
+					type: "object",
+					description: "update 时要修改的字段（只传需要改的）",
+				},
+			},
+			required: ["action"],
+		},
+		// 注：SDK 的 registerTool 用 TypeBox Static<TParams> 推断 params 类型，
+		// 但 shepherd 用手写 JSON schema，泛型退化为无意义类型（TS2322）。
+		// 此处 execute params 用宽松类型（SDK 设计层面的逃生舱），
+		// 内部用类型断言取精确值，any 不扩散到业务逻辑。
+		async execute(
+			_toolCallId: string,
+			rawParams: Record<string, unknown>,
+			_signal?: AbortSignal,
+			_onUpdate?: unknown,
+			_ctx?: unknown,
+		) {
+			const params = rawParams as {
+				action: "list" | "add" | "update" | "delete";
+				scope?: Scope;
+				rule?: Record<string, unknown>;
+				index?: number;
+				verbose?: boolean;
+				changes?: Record<string, unknown>;
+			};
+			const scope = params.scope;
+
+			switch (params.action) {
+				case "list": {
+					// index 指定 → 显示单条完整 JSON
+					if (params.index !== undefined) {
+						return handleListByIndex(
+							scope,
+							params.index,
+							rulesDir,
+							effectiveCwd,
+						);
+					}
+					// verbose=true → 显示所有规则的完整信息
+					if (params.verbose === true) {
+						return handleListVerbose(scope, rulesDir, effectiveCwd);
+					}
+					// 默认摘要模式
+					return handleListSummary(scope, rulesDir, effectiveCwd);
+				}
+				case "add": {
+					if (!params.rule) return textResult("❌ add 需要 rule 参数");
+					const targetScope = scope || "global";
+					const filePath = getRulesFilePath(
+						targetScope,
+						rulesDir,
+						effectiveCwd,
+					);
+					if (targetScope === "project") ensureProjectDir(effectiveCwd);
+					const result = addRule(filePath, params.rule);
+					if (!result.success) return textResult(`❌ ${result.error}`);
+					const warning = checkCrossScopeDuplicate(
+						targetScope,
+						rulesDir,
+						effectiveCwd,
+						params.rule,
+					);
+					const overwrittenMsg = result.overwritten
+						? " (覆盖已有同签名规则)"
+						: "";
+					const warningMsg = warning ? `\n${warning}` : "";
+					return textResult(
+						`✅ ${scopeLabel(targetScope)}规则已添加 [${targetScope}:${result.index}]${overwrittenMsg}${warningMsg}`,
+					);
+				}
+				case "update": {
+					if (params.index === undefined)
+						return textResult("❌ update 需要 index 参数");
+					if (!params.changes) return textResult("❌ update 需要 changes 参数");
+					const targetScope = scope || "global";
+					const filePath = getRulesFilePath(
+						targetScope,
+						rulesDir,
+						effectiveCwd,
+					);
+					const result = updateRule(filePath, params.index, params.changes);
+					return result.success
+						? textResult(
+								`✅ ${scopeLabel(targetScope)}规则 [${targetScope}:${params.index}] 已更新`,
+							)
+						: textResult(`❌ ${result.error}`);
+				}
+				case "delete": {
+					if (params.index === undefined)
+						return textResult("❌ delete 需要 index 参数");
+					const targetScope = scope || "global";
+					const filePath = getRulesFilePath(
+						targetScope,
+						rulesDir,
+						effectiveCwd,
+					);
+					const result = deleteRule(filePath, params.index);
+					return result.success
+						? textResult(
+								`✅ ${scopeLabel(targetScope)}规则已删除: ${(result.deleted as any)?.comment || ""}`,
+							)
+						: textResult(`❌ ${result.error}`);
+				}
+				default:
+					return textResult(`❌ 未知操作: ${(params as any).action}`);
+			}
+		},
+	} as ToolDefinition<any, any, any>);
+}

package/shepherd/rules-validate.ts

@@ -1,44 +1,89 @@
-/**
- * Shepherd 规则校验逻辑
- */
-
-const VALID_ACTIONS = ["block", "notify", "rewrite", "steer"] as const;
-const VALID_HOOKS = ["tool_call", "tool_result", "agent_end", "session_shutdown"] as const;
-
-export interface ValidationResult {
-	valid: boolean;
-	errors: string[];
-}
-
-/** 校验单条规则 */
-export function validateRule(rule: Record<string, unknown>): ValidationResult {
-	const errors: string[] = [];
-
-	if (!rule.comment || typeof rule.comment !== "string" || !rule.comment.trim()) {
-		errors.push("缺少必填字段: comment");
-	}
-	if (!rule.reason || typeof rule.reason !== "string" || !rule.reason.trim()) {
-		errors.push("缺少必填字段: reason");
-	}
-	if (rule.action && !VALID_ACTIONS.includes(rule.action as any)) {
-		errors.push(`action 值 "${rule.action}" 不合法，可选: ${VALID_ACTIONS.join(", ")}`);
-	}
-	if (rule.hook && !VALID_HOOKS.includes(rule.hook as any)) {
-		errors.push(`hook 值 "${rule.hook}" 不合法，可选: ${VALID_HOOKS.join(", ")}`);
-	}
-	if (rule.pattern) {
-		try { new RegExp(rule.pattern as string, (rule.flags as string) || ""); }
-		catch (e: unknown) { errors.push(`pattern 正则编译失败: ${e.message}`); }
-	}
-	if (Array.isArray(rule.conditions)) {
-		for (let i = 0; i < rule.conditions.length; i++) {
-			const cond = rule.conditions[i] as Record<string, unknown>;
-			if (cond.pattern) {
-				try { new RegExp(cond.pattern as string, (cond.flags as string) || ""); }
-				catch (e: unknown) { errors.push(`conditions[${i}].pattern 正则编译失败: ${e.message}`); }
-			}
-		}
-	}
-
-	return { valid: errors.length === 0, errors };
-}
+/**
+ * Shepherd 规则校验逻辑
+ */
+
+const VALID_ACTIONS = ["block", "notify", "rewrite", "steer"] as const;
+const VALID_HOOKS = [
+	"tool_call",
+	"tool_result",
+	"agent_end",
+	"message_end",
+	"session_shutdown",
+	"session_compact",
+] as const;
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: string[];
+}
+
+/** 校验单条规则 */
+export function validateRule(rule: Record<string, unknown>): ValidationResult {
+	const errors: string[] = [];
+
+	// 归一化：将 disabled 转为 enabled
+	if ("disabled" in rule) {
+		const v = rule.disabled;
+		delete rule.disabled;
+		if (v === true && rule.enabled === undefined) rule.enabled = false;
+		if (v === false && rule.enabled === undefined) rule.enabled = true;
+	}
+
+	if (
+		!rule.comment ||
+		typeof rule.comment !== "string" ||
+		!rule.comment.trim()
+	) {
+		errors.push("缺少必填字段: comment");
+	}
+	if (!rule.reason || typeof rule.reason !== "string" || !rule.reason.trim()) {
+		errors.push("缺少必填字段: reason");
+	}
+	if (rule.action && !VALID_ACTIONS.includes(rule.action as any)) {
+		let msg = `action 值 "${rule.action}" 不合法，可选: ${VALID_ACTIONS.join(", ")}`;
+		// 常见误用：试图用 skip/disable/off 等新增规则去"关闭"某条提示。
+		// action 表示规则匹配后的执行动作，不是"关闭"操作；正确做法是 update + enabled:false。
+		const actionStr = String(rule.action).toLowerCase();
+		if (/skip|disable|off|close|stop|mute/.test(actionStr)) {
+			msg +=
+				"。action 是规则匹配后的执行动作，无法用来「关闭」规则。" +
+				"想临时关闭某条已存在的规则请用 update(index=N, changes={enabled:false})（保留规则，日后改 enabled:true 恢复）；彻底删除用 delete(index=N)。" +
+				"操作前先 list 找到目标规则的 index。";
+		}
+		errors.push(msg);
+	}
+	if (rule.hook && !VALID_HOOKS.includes(rule.hook as any)) {
+		errors.push(
+			`hook 值 "${rule.hook}" 不合法，可选: ${VALID_HOOKS.join(", ")}`,
+		);
+	}
+	if (rule.pattern) {
+		try {
+			new RegExp(rule.pattern as string, (rule.flags as string) || "");
+		} catch (e: unknown) {
+			const msg = e instanceof Error ? e.message : String(e);
+			errors.push(`pattern 正则编译失败: ${msg}`);
+		}
+	}
+	if (Array.isArray(rule.conditions)) {
+		for (let i = 0; i < rule.conditions.length; i++) {
+			const cond = rule.conditions[i] as Record<string, unknown>;
+			const validFields = ["path", "text", "glob", "result", "command", "reason"];
+			if (cond.field && !validFields.includes(cond.field as string)) {
+				errors.push(
+					`conditions[${i}].field 值无效: "${cond.field}"，合法值: ${validFields.join(", ")}`,
+				);
+			}
+			if (cond.pattern) {
+				try {
+					new RegExp(cond.pattern as string, (cond.flags as string) || "");
+				} catch (e: unknown) {
+					const msg = e instanceof Error ? e.message : String(e);
+					errors.push(`conditions[${i}].pattern 正则编译失败: ${msg}`);
+				}
+			}
+		}
+	}
+
+	return { valid: errors.length === 0, errors };
+}