pi-shepherd 0.1.1 → 0.1.2

package/README.en.md

@@ -2,6 +2,8 @@
 
 # pi-shepherd
 
+[Source Code](https://github.com/catlain/pi-shepherd) | [npm](https://www.npmjs.com/package/pi-shepherd)
+
 Line count guard and behavior rules extension for [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — rule-driven hooks for tool calls, agent end, and session events.
 
 ## What It Does

package/README.md

@@ -4,6 +4,8 @@
 
 # pi-shepherd
 
+[源码仓库](https://github.com/catlain/pi-shepherd) | [npm](https://www.npmjs.com/package/pi-shepherd)
+
 Line count guard and behavior rules extension for [pi-coding-agent](https://github.com/earendil-works/pi-coding-agent) — rule-driven hooks for tool calls, agent end, and session events.
 
 ## What It Does

package/index.ts

@@ -225,5 +225,5 @@ export default function shepherdExtension(pi: ExtensionAPI) {
 	registerToolResult(pi, _toolState, RULES_DIR, _rulesOpts);
 
 	// ── shepherd_rules 工具：规则文件安全编辑 ───────────────────
-	registerRulesEditorTool(pi, join(RULES_DIR, "rules.json"));
+	registerRulesEditorTool(pi, RULES_DIR, process.cwd());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-shepherd",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Line count guard and behavior rules extension for pi-coding-agent",
   "main": "index.ts",
   "scripts": {
@@ -40,9 +40,6 @@
     "vitest.config.ts",
     "package.json"
   ],
-  "bundleDependencies": [
-    "@pi-atelier/shared-utils"
-  ],
   "keywords": [
     "pi-package"
   ],

package/rules.json

@@ -38,9 +38,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[Rust] 编辑后必须格式检查 + 跑测试",
+		"comment": "[Rust] 编辑/写入后必须格式检查 + 跑测试",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -53,24 +53,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[Rust][write] 写入后必须格式检查 + 跑测试",
-		"hook": "tool_result",
-		"tool": "write",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.rs$",
-				"flags": ""
-			}
-		],
-		"reason": "写入了 Rust 文件，必须：1) 运行 cargo clippy 做格式和 lint 检查；2) 跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
-	},
-	{
-		"comment": "[TypeScript] 编辑后必须跑测试",
+		"comment": "[TypeScript] 编辑/写入后必须跑测试",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -82,21 +67,6 @@
 		"reason": "编辑了 TypeScript 文件，必须跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
 		"enabled": true
 	},
-	{
-		"comment": "[TypeScript][write] 写入后必须跑测试",
-		"hook": "tool_result",
-		"tool": "write",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.ts$",
-				"flags": ""
-			}
-		],
-		"reason": "写入了 TypeScript 文件，必须跑覆盖该代码的单元测试（如无测试则先补充），修复所有测试问题确保通过。",
-		"enabled": true
-	},
 	{
 		"comment": "收尾规则 — agent_end 时提醒 commit + 记忆 + 总结，commit 必须带 session ID",
 		"hook": "agent_end",
@@ -142,9 +112,9 @@
 		"subagent": false
 	},
 	{
-		"comment": "[dev] 编辑扩展代码时提醒参考规范",
+		"comment": "[dev] 编辑/写入扩展代码时提醒参考规范",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"conditions": [
 			{
 				"field": "path",
@@ -152,15 +122,15 @@
 			}
 		],
 		"action": "steer",
-		"reason": "📝 编辑了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
+		"reason": "📝 编辑/写入了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
 		"requireSuccess": true,
 		"subagent": false,
 		"enabled": true
 	},
 	{
-		"comment": "[dev] 写入扩展代码时提醒参考规范",
+		"comment": "[dev] 编辑/写入扩展代码后提醒跑 typecheck",
 		"hook": "tool_result",
-		"tool": "write",
+		"tool": "edit|write",
 		"conditions": [
 			{
 				"field": "path",
@@ -168,39 +138,7 @@
 			}
 		],
 		"action": "steer",
-		"reason": "📝 写入了扩展代码。如果尚未阅读扩展开发规范，请先 read 根目录或项目目录下 extensions/README.md；如果已阅读且有新知识，更新到该文件。已阅读且无新知识则无视。",
-		"requireSuccess": true,
-		"subagent": false,
-		"enabled": true
-	},
-	{
-		"comment": "[dev] 编辑扩展代码后提醒跑 typecheck",
-		"hook": "tool_result",
-		"tool": "edit",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
-			}
-		],
-		"action": "steer",
-		"reason": "📝 编辑了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
-		"requireSuccess": true,
-		"subagent": false,
-		"enabled": true
-	},
-	{
-		"comment": "[dev] 写入扩展代码后提醒跑 typecheck",
-		"hook": "tool_result",
-		"tool": "write",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "extensions/.*\\.ts$"
-			}
-		],
-		"action": "steer",
-		"reason": "📝 写入了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
+		"reason": "📝 编辑/写入了扩展 TypeScript 代码。请运行 `cd extensions && bash check.sh <扩展名> --typecheck` 确认无类型错误。如果已跑过则无视。",
 		"requireSuccess": true,
 		"subagent": false,
 		"enabled": true
@@ -208,25 +146,7 @@
 	{
 		"comment": "[TS] 禁止空格缩进 — TS 文件必须用 Tab",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.ts$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n  [\\S ]"
-			}
-		],
-		"reason": "❌ TS 文件要求 Tab 缩进，不是空格。请用 Tab 缩进重写代码。",
-		"enabled": true
-	},
-	{
-		"comment": "[TS][write] 禁止空格缩进 — TS 文件必须用 Tab",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -244,25 +164,7 @@
 	{
 		"comment": "[Python] 禁止 Tab 缩进 — Python 必须用 4 空格",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.py$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n\\t"
-			}
-		],
-		"reason": "❌ Python 文件禁止 Tab 缩进，必须用 4 空格（PEP 8）。",
-		"enabled": true
-	},
-	{
-		"comment": "[Python][write] 禁止 Tab 缩进 — Python 必须用 4 空格",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -280,25 +182,7 @@
 	{
 		"comment": "[Rust] 禁止 Tab 缩进 — Rust 必须用 4 空格",
 		"hook": "tool_call",
-		"tool": "edit",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.rs$"
-			},
-			{
-				"field": "text",
-				"pattern": "\\n\\t"
-			}
-		],
-		"reason": "❌ Rust 文件禁止 Tab 缩进，必须用 4 空格（rustfmt）。",
-		"enabled": true
-	},
-	{
-		"comment": "[Rust][write] 禁止 Tab 缩进 — Rust 必须用 4 空格",
-		"hook": "tool_call",
-		"tool": "write",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -351,9 +235,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[deps] 编辑 package.json 时提醒依赖合规检查",
+		"comment": "[deps] 编辑/写入 package.json 时提醒依赖合规检查",
 		"hook": "tool_result",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "notify",
 		"conditions": [
 			{
@@ -364,20 +248,6 @@
 		"reason": "📦 编辑了 package.json 依赖字段。请对照 DEPENDENCY-GUIDE.md 检查合规性：① pi SDK 必须放 peerDependencies + optionalDependencies，禁止放 dependencies/devDependencies；② shared-utils 运行时引用放 dependencies（开发放 devDependencies）；③ 检查 files 白名单是否存在；④ 添加新依赖后运行 scan-deps.sh 验证无嵌套/版本冲突。",
 		"enabled": true
 	},
-	{
-		"comment": "[deps][write] 写入 package.json 时提醒依赖合规检查",
-		"hook": "tool_result",
-		"tool": "write",
-		"action": "notify",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "package\\.json$"
-			}
-		],
-		"reason": "📦 写入了 package.json 依赖字段。请对照 DEPENDENCY-GUIDE.md 检查合规性：① pi SDK 必须放 peerDependencies + optionalDependencies，禁止放 dependencies/devDependencies；② shared-utils 运行时引用放 dependencies（开发放 devDependencies）；③ 检查 files 白名单是否存在；④ 添加新依赖后运行 scan-deps.sh 验证无嵌套/版本冲突。",
-		"enabled": true
-	},
 	{
 		"comment": "[通用] 脚本执行失败时提醒先 --help",
 		"hook": "tool_result",
@@ -394,9 +264,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[roadmap] 禁止直接编辑 roadmap JSON — 必须用 roadmap 工具",
+		"comment": "[roadmap] 禁止直接编辑/写入 roadmap JSON — 必须用 roadmap 工具",
 		"hook": "tool_call",
-		"tool": "edit",
+		"tool": "edit|write",
 		"action": "block",
 		"conditions": [
 			{
@@ -407,20 +277,6 @@
 		"reason": "⛔ 禁止直接编辑 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接改 JSON 会绕过这些机制导致数据不一致。",
 		"enabled": true
 	},
-	{
-		"comment": "[roadmap] 禁止直接写入 roadmap JSON — 必须用 roadmap 工具",
-		"hook": "tool_call",
-		"tool": "write",
-		"action": "block",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "\\.roadmap\\.json$|\\broadmap/roadmap\\.json$"
-			}
-		],
-		"reason": "⛔ 禁止直接写入 roadmap JSON！请用 roadmap 工具操作（自动处理时间戳/ID分配/状态级联/归档/doing同步）：\n查看：roadmap_list（列表）、roadmap_show（详情）、roadmap_next（待办）\n创建：roadmap_plan（完整JSON创建/更新）、roadmap_create + roadmap_add_epic/story/task（逐步构建）\n修改：roadmap_update(roadmapId, item_id, {status/title/description/priority}) — 更新单个项\n完成：roadmap_done(roadmapId, taskId) — 标记完成并级联更新\n归档：roadmap_archive(roadmapId) — 归档已完成项\n直接改 JSON 会绕过这些机制导致数据不一致。",
-		"enabled": true
-	},
 	{
 		"comment": "[roadmap] 禁止通过 bash/python 脚本直接读写 roadmap JSON — 必须用 roadmap 工具",
 		"hook": "tool_call",
@@ -436,29 +292,9 @@
 		"enabled": true
 	},
 	{
-		"comment": "[GDScript] 编辑 .gd 文件后提醒写/跑 GUT 测试",
-		"reason": "跟 Python/Rust/TS 规则一致——编辑代码后提醒补充单元测试。触发条件：edit 工具的 file 参数匹配 .gd 扩展名。提醒内容：是否有对应的 GUT 测试？如果没有，建议补写。如果有，提醒跑 run_unit_tests.sh 验证。",
-		"trigger": {
-			"tool": "edit",
-			"event": "tool_result",
-			"match": "\\.gd$"
-		},
-		"action": "notify"
-	},
-	{
-		"action": "notify",
-		"comment": "[GDScript][write] 写入 .gd 文件后提醒写/跑 GUT 测试",
-		"reason": "跟 edit 规则配对。新建 .gd 文件时提醒创建对应的测试文件。",
-		"trigger": {
-			"event": "tool_result",
-			"match": "\\.gd$",
-			"tool": "write"
-		}
-	},
-	{
-		"comment": "[settings] 禁止 edit settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"comment": "[settings] 禁止 edit/write settings.json — 必须用 patchSettingsSectionWithBackup",
 		"reason": "直接编辑 settings.json 曾导致配置丢失（119 行变 3 行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
-		"tool": "edit",
+		"tool": "edit|write",
 		"hook": "tool_call",
 		"action": "block",
 		"message": "⛔ 禁止直接 edit settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
@@ -469,32 +305,19 @@
 			}
 		]
 	},
-	{
-		"action": "block",
-		"comment": "[settings] 禁止 write settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
-		"conditions": [
-			{
-				"field": "path",
-				"pattern": "settings\\.json$|settings\\.json\\.bak"
-			}
-		],
-		"hook": "tool_call",
-		"message": "⛔ 禁止直接 write settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
-		"reason": "直接编辑 settings.json 曾导致配置丢失（119 行变 3 行）。必须使用 patchSettingsSectionWithBackup 或 settings_rollback。",
-		"tool": "write"
-	},
 	{
 		"action": "block",
 		"comment": "[settings] 禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
 		"conditions": [
 			{
 				"field": "command",
-				"pattern": "settings\\.json"
+				"pattern": "^(?!.*\\b(git|grep|find|ls|cat|head|tail|diff|test|python3.*json\\.load)\\b).*settings\\.json",
+				"flags": "s"
 			}
 		],
 		"hook": "tool_call",
 		"message": "⛔ 禁止通过 bash 修改 settings.json！使用 patchSettingsSectionWithBackup() 安全修改，或 settings_rollback 回滚。",
-		"reason": "禁止 bash 直接修改 settings.json — 必须用 patchSettingsSectionWithBackup 或 settings_rollback",
+		"reason": "禁止通过 bash 直接写入 settings.json（如 echo > / sed -i / python 写入），但允许 git 操作（status/diff/reset/checkout/restore/add/rm/log）和只读命令（grep/find/ls/cat/head/tail/diff/test/python3 解析读取）",
 		"tool": "bash"
 	},
 	{
@@ -505,12 +328,5 @@
 		"condition": "bash command contains 'git commit' and exit code is 0",
 		"action": "notify",
 		"message": "commit 成功。检查是否有远程仓库（git remote），有的话立即 git push 同步到远程。"
-	},
-	{
-		"comment": "UI 布局改动提醒",
-		"reason": "编辑 GameScene.gd 或 UI 相关代码时，先查 debug_summary().ui_layout 确认位置，改完用 debug_toggle_borders() 验证无重叠",
-		"pattern": "GameScene\\.gd",
-		"type": "notify",
-		"action": "notify"
 	}
 ]

package/shepherd/index.ts

@@ -23,6 +23,7 @@ export {
 	loadRulesFromFile,
 	type Rule,
 	ruleMatches,
+	toolMatches,
 } from "./rules";
 export {
 	type ResettableRule,

package/shepherd/rules-editor.ts

@@ -32,11 +32,24 @@ export interface ListResult {
 	error?: string;
 }
 
+export interface RuleDetail {
+	index: number;
+	[key: string]: unknown;
+}
+
+export interface ListDetailResult {
+	rules: RuleDetail[];
+	count: number;
+	error?: string;
+}
+
 export interface WriteResult {
 	success: boolean;
 	error?: string;
 	index?: number;
 	deleted?: { comment: string; [key: string]: unknown };
+	overwritten?: boolean;
+	warning?: string;
 }
 
 // ── 文件操作辅助 ──────────────────────────────────────────
@@ -77,6 +90,48 @@ function safeWrite(filePath: string, rules: Record<string, unknown>[]): WriteRes
 	}
 }
 
+// ── 去重签名 ─────────────────────────────────────────────
+
+/** 规范化 conditions 数组：按 field+pattern 排序，取关键属性 */
+function normalizeConditions(
+	conditions: Array<Record<string, unknown>>,
+): string {
+	const normalized = conditions
+		.map((c) => ({ f: c.field || "", p: c.pattern || "" }))
+		.sort((a, b) => (a.f + a.p).localeCompare(b.f + b.p));
+	return JSON.stringify(normalized);
+}
+
+/** 生成规则去重签名 key */
+export function dedupKey(rule: Record<string, unknown>): string {
+	const tool = (rule.tool as string) || "";
+	const hook = (rule.hook as string) || "";
+	const action = (rule.action as string) || "";
+	let trigger: string;
+	if (Array.isArray(rule.conditions) && rule.conditions.length > 0) {
+		trigger = normalizeConditions(rule.conditions as Array<Record<string, unknown>>);
+	} else if (rule.pattern) {
+		trigger = rule.pattern as string;
+	} else if (rule.check) {
+		trigger = rule.check as string;
+	} else {
+		trigger = "";
+	}
+	return `${tool}|${hook}|${trigger}|${action}`;
+}
+
+/** 在规则数组中查找签名相同的规则，返回 index 或 null */
+export function findDuplicateBySignature(
+	rules: Record<string, unknown>[],
+	newRule: Record<string, unknown>,
+): number | null {
+	const newKey = dedupKey(newRule);
+	for (let i = 0; i < rules.length; i++) {
+		if (dedupKey(rules[i]) === newKey) return i;
+	}
+	return null;
+}
+
 // ── 公开 API ─────────────────────────────────────────────
 
 export function listRules(filePath: string): ListResult {
@@ -96,11 +151,36 @@ export function listRules(filePath: string): ListResult {
 	};
 }
 
+export function listRulesDetail(filePath: string): ListDetailResult {
+	const { rules, error } = readFile(filePath);
+	if (error) return { rules: [], count: 0, error };
+	return {
+		rules: rules.map((r, i) => ({ index: i, ...r })),
+		count: rules.length,
+	};
+}
+
+export function getRuleDetail(filePath: string, index: number): RuleDetail | { error: string } {
+	const { rules, error } = readFile(filePath);
+	if (error) return { error };
+	if (index < 0 || index >= rules.length) return { error: `编号越界: ${index}（共 ${rules.length} 条）` };
+	return { index, ...rules[index] };
+}
+
 export function addRule(filePath: string, rule: Record<string, unknown>): WriteResult {
 	const { rules, error } = readFile(filePath);
 	if (error) return { success: false, error };
 	const validation = validateRule(rule);
 	if (!validation.valid) return { success: false, error: validation.errors.join("; ") };
+	// 去重检测：签名相同则覆盖
+	const dupIdx = findDuplicateBySignature(rules, rule);
+	if (dupIdx !== null) {
+		rules[dupIdx] = rule;
+		const writeResult = safeWrite(filePath, rules);
+		return writeResult.success
+			? { success: true, index: dupIdx, overwritten: true }
+			: writeResult;
+	}
 	rules.push(rule);
 	const writeResult = safeWrite(filePath, rules);
 	return writeResult.success ? { success: true, index: rules.length - 1 } : writeResult;

package/shepherd/rules-tool-helpers.ts

@@ -0,0 +1,120 @@
+/**
+ * Shepherd 规则工具辅助函数
+ *
+ * scope 路径推导、合并列表、跨 scope 去重检测。
+ */
+
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { listRules } from "./rules-editor";
+import { findDuplicateBySignature } from "./rules-editor";
+
+/** 项目级规则文件名 */
+const PROJECT_RULES_FILE = "shepherd-rules.json";
+
+export type Scope = "global" | "project";
+
+/** 根据 scope 推导规则文件路径 */
+export function getRulesFilePath(
+	scope: Scope | undefined,
+	globalDir: string,
+	cwd: string,
+): string {
+	if (scope === "project") {
+		return path.join(cwd, ".pi", "extensions", PROJECT_RULES_FILE);
+	}
+	// 默认 global
+	return path.join(globalDir, "rules.json");
+}
+
+export interface ListRuleItem {
+	index: number;
+	comment: string;
+	scope: Scope;
+	enabled?: boolean;
+	action?: string;
+	tool?: string;
+	hook?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * 按_scope 列出规则。scope 不传时返回全局+项目合并列表。
+ */
+export function listRulesByScope(
+	globalDir: string,
+	cwd: string,
+	scope?: Scope,
+): ListRuleItem[] {
+	const results: ListRuleItem[] = [];
+
+	if (!scope || scope === "global") {
+		const globalPath = path.join(globalDir, "rules.json");
+		if (fs.existsSync(globalPath)) {
+			const r = listRules(globalPath);
+			if (!r.error && r.rules) {
+				for (const rule of r.rules) {
+					results.push({ ...rule, scope: "global" });
+				}
+			}
+		}
+	}
+
+	if (!scope || scope === "project") {
+		const projectPath = path.join(cwd, ".pi", "extensions", PROJECT_RULES_FILE);
+		if (fs.existsSync(projectPath)) {
+			const r = listRules(projectPath);
+			if (!r.error && r.rules) {
+				for (const rule of r.rules) {
+					results.push({ ...rule, scope: "project" });
+				}
+			}
+		}
+	}
+
+	return results;
+}
+
+/**
+ * 跨 scope 去重检测：写入 A scope 时检查 B scope 是否有签名相同的规则。
+ * 返回 warning 字符串或 null。
+ */
+export function checkCrossScopeDuplicate(
+	targetScope: Scope,
+	globalDir: string,
+	cwd: string,
+	newRule: Record<string, unknown>,
+): string | null {
+	const otherScope: Scope = targetScope === "global" ? "project" : "global";
+	const otherPath = getRulesFilePath(otherScope, globalDir, cwd);
+
+	if (!fs.existsSync(otherPath)) return null;
+
+	const content = fs.readFileSync(otherPath, "utf-8");
+	let rules: Record<string, unknown>[];
+	try {
+		const parsed = JSON.parse(content);
+		if (!Array.isArray(parsed)) return null;
+		rules = parsed;
+	} catch {
+		return null;
+	}
+
+	const dupIdx = findDuplicateBySignature(rules, newRule);
+	if (dupIdx !== null) {
+		const scopeLabel = otherScope === "global" ? "全局" : "项目级";
+		return `⚠ ${scopeLabel}已有相似规则 [${otherScope}:${dupIdx}]`;
+	}
+
+	return null;
+}
+
+/**
+ * 确保项目级规则文件的目录存在
+ */
+export function ensureProjectDir(cwd: string): void {
+	const dir = path.join(cwd, ".pi", "extensions");
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+}