pi-shepherd 0.1.1 → 0.1.2

package/shepherd/rules-tool-list.ts

@@ -0,0 +1,126 @@
+/**
+ * Shepherd 规则工具 — list 输出格式化
+ *
+ * 处理 list 的两种输出模式：摘要模式和 verbose（完整 JSON）模式。
+ */
+
+import {
+	getRuleDetail,
+	listRules,
+	listRulesDetail,
+} from "./rules-editor";
+import {
+	type Scope,
+	getRulesFilePath,
+	listRulesByScope,
+} from "./rules-tool-helpers";
+
+/** 构造 pi 工具 execute 的标准返回格式 */
+export function textResult(text: string) {
+	return { content: [{ type: "text" as const, text }] };
+}
+
+export const scopeLabel = (s: Scope) => (s === "global" ? "全局" : "项目级");
+
+/** 按编号查看单条规则的完整 JSON */
+export function handleListByIndex(
+	scope: Scope | undefined,
+	index: number,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	const effectiveScope = scope || "global";
+	const filePath = getRulesFilePath(effectiveScope, rulesDir, effectiveCwd);
+	const detail = getRuleDetail(filePath, index);
+	if ("error" in detail) return textResult(`❌ ${detail.error}`);
+	const { index: _, ...ruleData } = detail;
+	return textResult(
+		`📋 规则 [${effectiveScope}:${index}] 完整内容:\n${JSON.stringify(ruleData, null, "\t")}`,
+	);
+}
+
+/** verbose 模式：显示每条规则的完整 JSON */
+export function handleListVerbose(
+	scope: Scope | undefined,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	if (!scope) {
+		// 全部 scope
+		const parts: string[] = [];
+		const globalPath = getRulesFilePath("global", rulesDir, effectiveCwd);
+		const projectPath = getRulesFilePath("project", rulesDir, effectiveCwd);
+
+		const gResult = listRulesDetail(globalPath);
+		if (gResult.rules.length > 0) {
+			parts.push("── 全局规则 ──");
+			for (const r of gResult.rules) {
+				const { index: _, ...data } = r;
+				parts.push(`[global:${r.index}] ${JSON.stringify(data, null, "\t")}`);
+			}
+		}
+		const pResult = listRulesDetail(projectPath);
+		if (pResult.rules.length > 0) {
+			parts.push("── 项目级规则 ──");
+			for (const r of pResult.rules) {
+				const { index: _, ...data } = r;
+				parts.push(`[project:${r.index}] ${JSON.stringify(data, null, "\t")}`);
+			}
+		}
+		if (parts.length === 0) return textResult("暂无规则（全局和项目级均为空）。");
+		return textResult(parts.join("\n\n"));
+	}
+	// 指定 scope
+	const filePath = getRulesFilePath(scope, rulesDir, effectiveCwd);
+	const result = listRulesDetail(filePath);
+	if (result.error) return textResult(`❌ ${result.error}`);
+	if (result.count === 0) return textResult(`暂无${scopeLabel(scope)}规则。`);
+	return textResult(
+		result.rules
+			.map((r) => {
+				const { index: _, ...data } = r;
+				return `[${scope}:${r.index}] ${JSON.stringify(data, null, "\t")}`;
+			})
+			.join("\n\n"),
+	);
+}
+
+/** 摘要模式：一行一条，只显示 comment + action + tool + hook */
+export function handleListSummary(
+	scope: Scope | undefined,
+	rulesDir: string,
+	effectiveCwd: string,
+) {
+	if (!scope) {
+		const items = listRulesByScope(rulesDir, effectiveCwd);
+		if (items.length === 0) return textResult("暂无规则（全局和项目级均为空）。");
+		return textResult(
+			items
+				.map(
+					(r) =>
+						`[${r.scope}:${r.index}] ${r.comment}` +
+						(r.enabled === false ? " (disabled)" : "") +
+						(r.action ? ` — ${r.action}` : "") +
+						(r.tool ? ` on ${r.tool}` : "") +
+						(r.hook ? ` @ ${r.hook}` : ""),
+				)
+				.join("\n"),
+		);
+	}
+	const filePath = getRulesFilePath(scope, rulesDir, effectiveCwd);
+	const result = listRules(filePath);
+	if (result.error) return textResult(`❌ ${result.error}`);
+	if (result.count === 0) return textResult(`暂无${scopeLabel(scope)}规则。`);
+	return textResult(
+		result.rules
+			.map(
+				(r) =>
+					`[${scope}:${r.index}] ${r.comment}` +
+					(r.enabled === false ? " (disabled)" : "") +
+					(r.action ? ` — ${r.action}` : "") +
+					(r.tool ? ` on ${r.tool}` : "") +
+					(r.hook ? ` @ ${r.hook}` : ""),
+			)
+			.join("\n"),
+	);
+}

package/shepherd/rules-tool.ts

@@ -2,23 +2,37 @@
  * Shepherd 规则编辑工具注册
  *
  * 注册 shepherd_rules 工具到 pi，提供规则文件的安全增删改查。
+ * 支持 scope 参数区分全局/项目级规则。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { addRule, deleteRule, listRules, updateRule } from "./rules-editor";
+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";
 
-/** 构造 pi 工具 execute 的标准返回格式 */
-function textResult(text: string) {
-	return { content: [{ type: "text" as const, text }] };
-}
+export function registerRulesEditorTool(pi: ExtensionAPI, rulesDir: string, cwd?: string) {
+	const effectiveCwd = cwd || process.cwd();
 
-export function registerRulesEditorTool(pi: ExtensionAPI, rulesFilePath: string) {
 	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: {
@@ -27,13 +41,25 @@ export function registerRulesEditorTool(pi: ExtensionAPI, rulesFilePath: 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: "update/delete 时指定规则编号（0-based）",
+					description:
+						"规则编号（0-based，仅在对应 scope 文件内的索引）。list 时传 index 显示该条规则的完整 JSON；update/delete 时指定要操作的规则。",
+				},
+				verbose: {
+					type: "boolean",
+					description:
+						"list 时传 true 显示每条规则的完整字段（含 reason、conditions、pattern 等），默认 false 只显示摘要。",
 				},
 				changes: {
 					type: "object",
@@ -46,49 +72,66 @@ export function registerRulesEditorTool(pi: ExtensionAPI, rulesFilePath: string)
 			_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": {
-					const result = listRules(rulesFilePath);
-					if (result.error) return textResult(`❌ ${result.error}`);
-					if (result.count === 0) return textResult("暂无规则。");
-					return textResult(
-						result.rules
-							.map(
-								(r) =>
-									`[${r.index}] ${r.comment}` +
-									(r.enabled === false ? " (disabled)" : "") +
-									(r.action ? ` — ${r.action}` : "") +
-									(r.tool ? ` on ${r.tool}` : "") +
-									(r.hook ? ` @ ${r.hook}` : ""),
-						)
-							.join("\n"),
-					);
+					// 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 result = addRule(rulesFilePath, params.rule);
-					return result.success
-						? textResult(`✅ 规则已添加 [${result.index}]`)
-						: textResult(`❌ ${result.error}`);
+					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 result = updateRule(rulesFilePath, params.index, params.changes);
+					const targetScope = scope || "global";
+					const filePath = getRulesFilePath(targetScope, rulesDir, effectiveCwd);
+					const result = updateRule(filePath, params.index, params.changes);
 					return result.success
-						? textResult(`✅ 规则 [${params.index}] 已更新`)
+						? textResult(`✅ ${scopeLabel(targetScope)}规则 [${targetScope}:${params.index}] 已更新`)
 						: textResult(`❌ ${result.error}`);
 				}
 				case "delete": {
 					if (params.index === undefined) return textResult("❌ delete 需要 index 参数");
-					const result = deleteRule(rulesFilePath, params.index);
+					const targetScope = scope || "global";
+					const filePath = getRulesFilePath(targetScope, rulesDir, effectiveCwd);
+					const result = deleteRule(filePath, params.index);
 					return result.success
-						? textResult(`✅ 规则已删除: ${(result.deleted as any)?.comment || ""}`)
+						? textResult(
+								`✅ ${scopeLabel(targetScope)}规则已删除: ${(result.deleted as any)?.comment || ""}`,
+							)
 						: textResult(`❌ ${result.error}`);
 				}
 				default:

package/shepherd/rules.ts

@@ -21,7 +21,7 @@ export interface Condition {
 export interface Rule {
 	comment: string;
 	hook?: "tool_call" | "tool_result" | "agent_end" | "session_shutdown"; // 默认 "tool_call"
-	tool?: string; // 默认 "bash"
+	tool?: string; // 默认 "bash"，支持 "|" 分隔多值匹配（如 "edit|write"）
 	// 单条件模式（向后兼容）：pattern 匹配 command（bash）或 path（edit/write）
 	pattern?: string;
 	flags?: string;
@@ -177,11 +177,11 @@ export function loadRules(
 		if (result.error) errors.push(result.error);
 	}
 
-	// 2. 项目级规则（<cwd>/.pi/extensions/{prefix}*.json）
+	// 2. 项目级规则（<cwd>/.pi/extensions/{prefix}*.json 或 shepherd-rules.json）
 	const projectExtDir = path.join(process.cwd(), ".pi", "extensions");
 	if (fs.existsSync(projectExtDir)) {
 		for (const file of fs.readdirSync(projectExtDir).sort()) {
-			if (file.startsWith(prefix) && file.endsWith(".json")) {
+			if (file.endsWith(".json") && (file.startsWith(prefix) || file === "shepherd-rules.json")) {
 				const result = loadRulesFromFile(path.join(projectExtDir, file));
 				allRules.push(...result.rules);
 				if (result.error) errors.push(result.error);
@@ -247,6 +247,12 @@ export function getMatchTargets(
 		}
 	} else if (tool === "write") {
 		text = (event.input as any)?.content || "";
+	} else {
+		// 其他工具：把所有参数序列化为 text，供 conditions 的 text field 匹配
+		const input = event.input as any;
+		if (input && typeof input === "object") {
+			text = JSON.stringify(input);
+		}
 	}
 	return { path: pathVal, text, command: "", glob: "" };
 }
@@ -272,6 +278,12 @@ export function ruleMatches(
 	return false;
 }
 
+/** tool 字段匹配：支持 "|" 分隔的多值（如 "edit|write"） */
+export function toolMatches(ruleTool: string | undefined, eventTool: string): boolean {
+	if (!ruleTool) return true; // 未指定 tool 时默认匹配所有（由 hook 类型决定范围）
+	return ruleTool.split("|").map((t) => t.trim()).includes(eventTool);
+}
+
 /** rtk 可用性（模块加载时检测） */
 export const isRtkAvailable: boolean = (() => {
 	try {

package/shepherd/tool-hooks.ts

@@ -20,6 +20,7 @@ import {
 	loadRules,
 	type Rule,
 	ruleMatches,
+	toolMatches,
 } from "./rules.js";
 import type { ResettableRule, StateTracker } from "./state-tracker.js";
 
@@ -63,7 +64,7 @@ export function registerToolCall(
 		}
 
 		const rules = loadRules(rulesDir, rulesOptions).filter(
-			(r) => r.hook === "tool_call" && r.tool === event.toolName,
+			(r) => r.hook === "tool_call" && toolMatches(r.tool, event.toolName!),
 		);
 		if (rules.length === 0) return;
 
@@ -139,7 +140,7 @@ export function registerToolResult(
 			if (isSubagent() && rule.subagent === false) continue;
 			if (!toolsAvailable(rule, pi, state)) continue;
 			if (rule.requireSuccess && event.isError) continue;
-			if (rule.tool && rule.tool !== event.toolName) continue;
+			if (rule.tool && !toolMatches(rule.tool, event.toolName!)) continue;
 
 			// 正则条件匹配
 			if (rule.conditions || rule.pattern) {

package/node_modules/@pi-atelier/shared-utils/README.en.md

@@ -1,182 +0,0 @@
-[中文文档](README.md) | English
-
-# pi-shared-utils
-
-Shared utility library for the [pi](https://github.com/earendil-works/pi-coding-agent) extension ecosystem — memory file parsing, path constants, settings management, tool output truncation, and more. Used by 7+ pi extensions.
-
-## Why You Need It
-
-If you're building a pi extension, you'll inevitably need the same building blocks: reading settings, parsing memory files, truncating tool output, finding agent directories. pi-shared-utils provides these as a single dependency so every extension doesn't reinvent the wheel.
-
-**Used by**: pi-memory, pi-context, pi-shepherd, pi-roadmap, pi-session-analyzer, pi-workflow, and more.
-
-## How It Works
-
-```
-pi-shared-utils provides 6 independent modules:
-
-┌─────────────────────────────────────────────────┐
-│  memory-parser  ── parse topic--kw1,kw2.md file names
-│  paths         ── standard pi agent path constants
-│  settings      ── read/write extension config sections in settings.json
-│  tool-output   ── truncate tool output (prevent context overflow)
-│  agents        ── discover sub-agent definition files
-│  ephemeral     ── session-scoped hint/label stack
-└─────────────────────────────────────────────────┘
-```
-
-Each module is independently importable — use only what you need.
-
-## Installation
-
-```bash
-pi install git:github.com/catlain/pi-atelier
-```
-
-> This is a workspace package inside the pi-atelier monorepo and typically doesn't need to be installed standalone. Other independent extensions include it automatically via `bundledDependencies`.
-
-## Exported Modules
-
-### Memory File Parsing (`memory-parser`)
-
-Parses `topic--kw1,kw2,kw3.md`-format memory file names and scans directories to generate an index.
-
-```ts
-import { parseFileName, buildFileName, scanMemoryDir } from "@pi-atelier/shared-utils";
-
-// Parse file name → { topic, keywords }
-const { topic, keywords } = parseFileName("coding_standards--编码,git,lint.md");
-// topic = "coding_standards", keywords = ["编码", "git", "lint"]
-
-// Build file name from parts
-const name = buildFileName("coding_standards", ["编码", "git", "lint"]);
-// "coding_standards--编码,git,lint.md"
-
-// Scan directory, returns MemoryEntry[]
-const entries = await scanMemoryDir("/path/to/memory");
-```
-
-### Path Constants (`paths`)
-
-Standard pi agent paths, so you never hardcode them.
-
-| Constant | Path | Description |
-|------|------|------|
-| `AGENT_DIR` | `~/.pi/agent/` | Agent root directory |
-| `SETTINGS_PATH` | `~/.pi/agent/settings.json` | Global settings |
-| `MODELS_CONFIG_PATH` | `~/.pi/agent/models.json` | Model configuration |
-| `MCP_CONFIG_PATH` | `~/.pi/agent/mcp.json` | MCP server configuration |
-| `MCP_CACHE_PATH` | `~/.pi/agent/mcp-cache/` | MCP tool cache |
-| `AGENTS_DIR` | `~/.pi/agent/agents/` | Sub-agent definitions |
-| `GLOBAL_RULES_PATH` | `~/.pi/agent/rules.md` | Global rules |
-| `MEMORY_DIR` | `~/.pi/agent/memory/` | Global memory |
-| `MEMORY_MD_PATH` | `MEMORY.md` | Memory index file name |
-
-### Settings Management (`settings`)
-
-Read and write extension-specific config sections in `settings.json`.
-
-```ts
-import { getSettingsSection, patchSettingsSection, getSettingsValue, setSettingsValue } from "@pi-atelier/shared-utils";
-
-// Read extension config section
-const config = await getSettingsSection("my-extension");
-
-// Update config incrementally
-await patchSettingsSection("my-extension", { enabled: true });
-
-// Read/write a single value
-const val = await getSettingsValue("my-extension", "key", "default");
-await setSettingsValue("my-extension", "key", "new-value");
-```
-
-### Tool Output Truncation (`tool-output`)
-
-Prevent large tool results from overflowing the LLM context.
-
-```ts
-import { truncateToolOutput, truncatedResult, TOOL_OUTPUT_MAX_LINES } from "@pi-atelier/shared-utils";
-
-// Truncate overly long output
-const result = truncateToolOutput(longText, { maxLines: 200 });
-// { text: "...", truncated: true, originalLines: 1500, keptLines: 200 }
-
-// Shortcut: returns pi tool result format
-return truncatedResult(text);  // auto-truncates + returns { content: [{ type: "text", text }] }
-```
-
-### Sub-Agent Discovery (`agents`)
-
-Scan the `~/.pi/agent/agents/` directory for sub-agent definition files.
-
-```ts
-import { discoverAgents, getAgentDescription, formatAgentsList } from "@pi-atelier/shared-utils";
-
-// Discover all available sub-agents
-const agents = await discoverAgents();
-// [{ name: "pv-executor", description: "...", filePath: "..." }, ...]
-
-// Get description for a single agent
-const desc = await getAgentDescription("pv-executor");
-
-// Format as a readable list
-const list = formatAgentsList(agents);
-```
-
-### Session-Scoped Data (`ephemeral`)
-
-A hint/label stack for the current session that vanishes when the session ends. Useful for lightweight state passing across tool calls.
-
-```ts
-import { pushHint, hasHints, peekHints, drainHints, peekLabels } from "@pi-atelier/shared-utils";
-
-pushHint({ key: "recent-files", values: ["file1.ts", "file2.ts"] });
-const has = hasHints("recent-files");
-const hints = peekHints("recent-files");   // peek without removing
-const all = drainHints();                   // retrieve and clear
-```
-
-## Best Practices
-
-### ✅ Recommended
-- Import only the modules you need to keep bundle size small
-- Use `truncatedResult()` for all tool outputs — prevents context overflow
-- Use `paths` constants instead of hardcoding `~/.pi/agent/...`
-- Use `settings` module for any persistent configuration
-
-### ❌ Not Recommended
-- Don't hardcode pi paths — they may change between versions
-- Don't return raw tool output without truncation
-- Don't use `ephemeral` for persistent data — it's session-scoped only
-
-## Limitations
-
-| Limitation | Detail |
-|------------|--------|
-| Memory file format only | Only supports `topic--kw1,kw2.md` naming convention |
-| No validation | Settings reads don't validate schema — caller must handle |
-| Ephemeral is in-memory | Lost on process restart, not persisted to disk |
-| Token estimation | `tool-output` truncates by lines, not by token count |
-
-## Architecture
-
-```
-pi-shared-utils/
-├── src/
-│   ├── index.ts           # Re-exports all modules
-│   ├── memory-parser.ts   # Memory file name parsing + directory scanning
-│   ├── paths.ts           # Path constants (AGENT_DIR, SETTINGS_PATH, ...)
-│   ├── settings.ts        # settings.json section read/write
-│   ├── tool-output.ts     # Output truncation + truncatedResult helper
-│   ├── agents.ts          # Sub-agent discovery from ~/.pi/agent/agents/
-│   ├── ephemeral.ts       # Session-scoped hint/label stack
-│   └── __tests__/         # Unit tests
-├── package.json
-└── tsconfig.json
-```
-
-**Dependencies**: Zero runtime dependencies (pure Node.js).
-
-## License
-
-MIT