pi-shepherd 0.1.0

package/shepherd/line-count.ts

@@ -0,0 +1,86 @@
+/**
+ * 文件行数检查
+ * edit/write 后自动检测文件行数，超阈值时注入 ephemeral 提醒
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pushWarning } from "./ephemeral.js";
+
+// ── 代码文件阈值 ─────────────────────────────────────────────
+const LINE_WARN = 200;
+const LINE_MUST = 300;
+const LINE_BAN = 500;
+
+// ── 记忆文件阈值 ─────────────────────────────────────────────
+const MEMORY_LINE_LIMIT = 200;
+
+const CHECKED_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".py", ".rs", ".go"]);
+
+/** 判断路径是否为记忆文件（memory/ 或 .pi/memory/ 下的 .md，排除索引文件 MEMORY.md） */
+function isMemoryFile(filePath: string): boolean {
+	if (!filePath.endsWith(".md")) return false;
+	const name = path.basename(filePath);
+	if (name === "MEMORY.md") return false;
+	const normalized = filePath.replace(/\\/g, "/");
+	return /\/memory\//.test(normalized);
+}
+
+export function checkLineCount(filePath: string): void {
+	const ext = path.extname(filePath);
+
+	// 记忆文件检查
+	if (isMemoryFile(filePath)) {
+		checkMemoryFile(filePath);
+		return;
+	}
+
+	// 代码文件检查
+	if (!CHECKED_EXTENSIONS.has(ext)) return;
+
+	let lines: number;
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		lines = content.split("\n").length;
+	} catch {
+		return;
+	}
+
+	const name = path.basename(filePath);
+
+	if (lines >= LINE_BAN) {
+		pushWarning(
+			`❌ 严禁: ${name} 已有 ${lines} 行（阈值 ${LINE_BAN} 行）。\n` +
+				`拆分建议：提取公共函数/工具类到独立文件，目标每个文件 ≤ 200 行。`,
+		);
+	} else if (lines >= LINE_MUST) {
+		pushWarning(
+			`🔴 必须拆分: ${name} 已有 ${lines} 行（阈值 ${LINE_MUST} 行）。\n` +
+				`拆分建议：提取公共函数/工具类到独立文件，目标每个文件 ≤ 200 行。`,
+		);
+	} else if (lines >= LINE_WARN) {
+		pushWarning(
+			`⚠️ 应主动检查: ${name} 已有 ${lines} 行（阈值 ${LINE_WARN} 行）。\n` +
+				`拆分建议：提取公共函数/工具类到独立文件，目标每个文件 ≤ 200 行。`,
+		);
+	}
+}
+
+/** 记忆文件行数检查：超过 200 行必须拆分 */
+function checkMemoryFile(filePath: string): void {
+	let lines: number;
+	try {
+		const content = fs.readFileSync(filePath, "utf-8");
+		lines = content.split("\n").length;
+	} catch {
+		return;
+	}
+
+	if (lines >= MEMORY_LINE_LIMIT) {
+		const name = path.basename(filePath);
+		pushWarning(
+			`📝 记忆文件过长: ${name} 已有 ${lines} 行（上限 ${MEMORY_LINE_LIMIT} 行）。\n` +
+				`必须拆分：每个记忆文件一个主题，拆分后用 memory_update 或手动更新 MEMORY.md 索引。`,
+		);
+	}
+}

package/shepherd/rules-editor.ts

@@ -0,0 +1,135 @@
+/**
+ * Shepherd 规则文件安全编辑器
+ *
+ * 提供 rules.json 的安全增删改查：
+ * - 写入前校验（必填字段、正则合法性、枚举值）
+ * - 自动备份（.bak）
+ * - 写入后回读验证
+ * - 失败自动回滚
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { validateRule } from "./rules-validate";
+export { validateRule } from "./rules-validate";
+export type { ValidationResult } from "./rules-validate";
+
+// ── 类型 ──────────────────────────────────────────────────
+
+export interface RuleSummary {
+	index: number;
+	comment: string;
+	action?: string;
+	tool?: string;
+	hook?: string;
+	enabled?: boolean;
+	pattern?: string;
+}
+
+export interface ListResult {
+	rules: RuleSummary[];
+	count: number;
+	error?: string;
+}
+
+export interface WriteResult {
+	success: boolean;
+	error?: string;
+	index?: number;
+	deleted?: { comment: string; [key: string]: unknown };
+}
+
+// ── 文件操作辅助 ──────────────────────────────────────────
+
+interface FileData {
+	rules: Record<string, unknown>[];
+	error?: string;
+}
+
+function readFile(filePath: string): FileData {
+	if (!fs.existsSync(filePath)) return { rules: [] };
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) {
+			return { rules: [], error: `顶层必须是 JSON 数组，当前是 ${typeof parsed}` };
+		}
+		return { rules: parsed };
+	} catch (e: unknown) {
+		return { rules: [], error: `JSON 解析失败: ${e.message}` };
+	}
+}
+
+function safeWrite(filePath: string, rules: Record<string, unknown>[]): WriteResult {
+	const backupPath = `${filePath}.bak`;
+	if (fs.existsSync(filePath)) fs.copyFileSync(filePath, backupPath);
+	const dir = path.dirname(filePath);
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(filePath, JSON.stringify(rules, null, "\t"), "utf-8");
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) throw new Error("not array");
+		return { success: true };
+	} catch {
+		if (fs.existsSync(backupPath)) fs.copyFileSync(backupPath, filePath);
+		return { success: false, error: "写入后验证失败，已从备份恢复" };
+	}
+}
+
+// ── 公开 API ─────────────────────────────────────────────
+
+export function listRules(filePath: string): ListResult {
+	const { rules, error } = readFile(filePath);
+	if (error) return { rules: [], count: 0, error };
+	return {
+		rules: rules.map((r, i) => ({
+			index: i,
+			comment: (r.comment as string) || "",
+			action: r.action as string | undefined,
+			tool: r.tool as string | undefined,
+			hook: r.hook as string | undefined,
+			enabled: r.enabled as boolean | undefined,
+			pattern: r.pattern as string | undefined,
+		})),
+		count: rules.length,
+	};
+}
+
+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("; ") };
+	rules.push(rule);
+	const writeResult = safeWrite(filePath, rules);
+	return writeResult.success ? { success: true, index: rules.length - 1 } : writeResult;
+}
+
+export function updateRule(
+	filePath: string,
+	index: number,
+	changes: Record<string, unknown>,
+): WriteResult {
+	if (index < 0) return { success: false, error: `编号越界: ${index}` };
+	const { rules, error } = readFile(filePath);
+	if (error) return { success: false, error };
+	if (index >= rules.length) return { success: false, error: `编号越界: ${index}（共 ${rules.length} 条）` };
+	const merged = { ...rules[index], ...changes };
+	const validation = validateRule(merged);
+	if (!validation.valid) return { success: false, error: validation.errors.join("; ") };
+	rules[index] = merged;
+	return safeWrite(filePath, rules);
+}
+
+export function deleteRule(filePath: string, index: number): WriteResult {
+	if (index < 0) return { success: false, error: `编号越界: ${index}` };
+	const { rules, error } = readFile(filePath);
+	if (error) return { success: false, error };
+	if (index >= rules.length) return { success: false, error: `编号越界: ${index}（共 ${rules.length} 条）` };
+	const deleted = rules.splice(index, 1)[0];
+	const writeResult = safeWrite(filePath, rules);
+	return writeResult.success
+		? { success: true, deleted: { comment: (deleted.comment as string) || "", ...deleted } }
+		: writeResult;
+}

package/shepherd/rules-tool.ts

@@ -0,0 +1,99 @@
+/**
+ * Shepherd 规则编辑工具注册
+ *
+ * 注册 shepherd_rules 工具到 pi，提供规则文件的安全增删改查。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { addRule, deleteRule, listRules, updateRule } from "./rules-editor";
+
+/** 构造 pi 工具 execute 的标准返回格式 */
+function textResult(text: string) {
+	return { content: [{ type: "text" as const, text }] };
+}
+
+export function registerRulesEditorTool(pi: ExtensionAPI, rulesFilePath: string) {
+	pi.registerTool({
+		name: "shepherd_rules",
+		label: "Shepherd Rules Editor",
+		description:
+			"安全编辑 shepherd 规则文件。支持 list（列出所有规则）、add（添加规则）、update（部分更新规则）、delete（删除规则）。" +
+			"写入前自动校验必填字段和正则合法性，写入后回读验证，失败自动从备份恢复。",
+		parameters: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: ["list", "add", "update", "delete"],
+					description: "操作类型",
+				},
+				rule: {
+					type: "object",
+					description: "add 时传入的完整规则对象（必须含 comment 和 reason）",
+				},
+				index: {
+					type: "number",
+					description: "update/delete 时指定规则编号（0-based）",
+				},
+				changes: {
+					type: "object",
+					description: "update 时要修改的字段（只传需要改的）",
+				},
+			},
+			required: ["action"],
+		},
+		async execute(
+			_toolCallId: string,
+			params: {
+				action: "list" | "add" | "update" | "delete";
+				rule?: Record<string, unknown>;
+				index?: number;
+				changes?: Record<string, unknown>;
+			},
+		) {
+			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"),
+					);
+				}
+				case "add": {
+					if (!params.rule) return textResult("❌ add 需要 rule 参数");
+					const result = addRule(rulesFilePath, params.rule);
+					return result.success
+						? textResult(`✅ 规则已添加 [${result.index}]`)
+						: textResult(`❌ ${result.error}`);
+				}
+				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);
+					return result.success
+						? textResult(`✅ 规则 [${params.index}] 已更新`)
+						: textResult(`❌ ${result.error}`);
+				}
+				case "delete": {
+					if (params.index === undefined) return textResult("❌ delete 需要 index 参数");
+					const result = deleteRule(rulesFilePath, params.index);
+					return result.success
+						? textResult(`✅ 规则已删除: ${(result.deleted as any)?.comment || ""}`)
+						: textResult(`❌ ${result.error}`);
+				}
+				default:
+					return textResult(`❌ 未知操作: ${(params as any).action}`);
+			}
+		},
+	});
+}

package/shepherd/rules-validate.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 };
+}

package/shepherd/rules.ts

@@ -0,0 +1,283 @@
+/**
+ * Guard 规则类型定义 + 规则加载/编译/匹配 + git 辅助函数
+ */
+
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pushRuleError } from "./ephemeral.js";
+import type { ResettableRule, StateCondition } from "./state-tracker.js";
+import type { ToolEvent } from "./tool-event-types.js";
+
+// ── 类型定义 ──────────────────────────────────────────────────
+
+export interface Condition {
+	field: "path" | "text" | "glob";
+	pattern: string;
+	flags?: string;
+	_compiled?: RegExp;
+}
+
+export interface Rule {
+	comment: string;
+	hook?: "tool_call" | "tool_result" | "agent_end" | "session_shutdown"; // 默认 "tool_call"
+	tool?: string; // 默认 "bash"
+	// 单条件模式（向后兼容）：pattern 匹配 command（bash）或 path（edit/write）
+	pattern?: string;
+	flags?: string;
+	// 多条件 AND 模式：设置了 conditions 时忽略 pattern
+	conditions?: Condition[];
+	action?: "block" | "notify" | "rewrite" | "steer"; // 默认 "block"
+	reason: string;
+	enabled?: boolean;
+	// session_shutdown / agent_end 专用：内置检查类型
+	check?: "git_uncommitted" | "has_edits" | "always";
+	// agent_end 专用：只在指定 stopReason 时触发（默认 ["stop"]）
+	stopReason?: ("stop" | "length" | "toolUse" | "error" | "aborted")[];
+	// 有状态规则：状态条件（与 conditions 正则是 AND 关系）
+	state?: StateCondition;
+	// 有状态规则：当这些工具执行后重置此规则的计数
+	resetOn?: string[];
+	// 子代理控制：false 表示在子代理环境中跳过此规则（默认 true）
+	subagent?: boolean;
+	// 工具依赖：全部可用才触发（AND 语义），不设或空数组 = 不限制
+	requiresTools?: string[];
+	// 仅成功时触发：true 时跳过 isError 的 tool_result（默认 false）
+	requireSuccess?: boolean;
+	// 运行时：已触发标记（防重复）
+	_triggered?: boolean;
+	// 编译后的正则（运行时填充，单条件模式）
+	_compiled?: RegExp;
+}
+
+// ── Git 辅助函数 ──────────────────────────────────────────────
+
+/** 检测 git 工作区是否有未提交的改动 */
+export function hasGitUncommittedChanges(): boolean {
+	try {
+		const cwd = process.cwd();
+		const status = execSync("git status --porcelain", {
+			timeout: 5000,
+			stdio: ["pipe", "pipe", "pipe"],
+			cwd,
+		})
+			.toString()
+			.trim();
+		// 只关注已跟踪文件的变更（M/A/D/R 等），忽略 untracked（?? 前缀）
+		const tracked = status
+			.split("\n")
+			.filter((line) => line && !line.startsWith("??"));
+		return tracked.length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/** 当前是否在 worktree 中 */
+export function isInWorktree(): boolean {
+	try {
+		const cwd = process.cwd();
+		if (/\/\.worktrees\/[^/]+/.test(cwd)) return true;
+		const gitDir = execSync("git rev-parse --git-dir", {
+			timeout: 3000,
+			stdio: ["pipe", "pipe", "pipe"],
+			cwd,
+		})
+			.toString()
+			.trim();
+		const commonDir = execSync("git rev-parse --git-common-dir", {
+			timeout: 3000,
+			stdio: ["pipe", "pipe", "pipe"],
+			cwd,
+		})
+			.toString()
+			.trim();
+		return gitDir !== commonDir && gitDir !== ".git";
+	} catch {
+		return false;
+	}
+}
+
+/** 当前是否在子代理环境中 */
+export const isSubagent = () =>
+	!!(process.env.PI_SUBAGENT_AGENT || process.env.PI_SUBAGENT_SESSION);
+
+// ── 代码文件扩展名 ─────────────────────────────────────────
+
+/** 代码文件扩展名正则（glob 或文件名末尾） */
+export const CODE_EXT_RE = /\.(py|rs|ts|js|toml|json)(\*|"|')?$/;
+
+// ── 规则加载/编译/匹配 ────────────────────────────────────────
+
+// RULES_PATH 已移除——规则路径由 loadRules(rulesDir) 参数传入
+
+/** 从单个文件加载规则（不编译），处理文件不存在和 JSON 解析错误 */
+export function loadRulesFromFile(filePath: string): {
+	rules: Rule[];
+	error?: string;
+} {
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) {
+			const fileName = path.basename(filePath);
+			return {
+				rules: [],
+				error: `${fileName}: 顶层必须是 JSON 数组，当前是 ${typeof parsed}`,
+			};
+		}
+		return { rules: parsed };
+	} catch (e: unknown) {
+		if (e.code === "ENOENT") return { rules: [] };
+		const fileName = path.basename(filePath);
+		return { rules: [], error: `${fileName}: JSON 解析失败 — ${e.message}` };
+	}
+}
+
+/** 编译规则：正则编译 + 默认值填充 */
+export function compileRules(rules: Rule[]): Rule[] {
+	// 过滤禁用规则
+	const active = rules.filter((r) => r.enabled !== false);
+	for (const rule of active) {
+		// 多条件模式：编译每个 condition
+		if (rule.conditions && rule.conditions.length > 0) {
+			for (const cond of rule.conditions) {
+				cond._compiled = new RegExp(cond.pattern, cond.flags || "");
+			}
+		} else if (rule.pattern) {
+			// 单条件模式：编译 pattern（向后兼容）
+			rule._compiled = new RegExp(rule.pattern, rule.flags || "");
+		}
+		// 填充默认值
+		if (!rule.hook) rule.hook = "tool_call";
+		if (!rule.tool) rule.tool = "bash";
+		if (!rule.action) rule.action = "block";
+	}
+	return active;
+}
+
+/** 加载所有规则并校验格式，返回编译后的规则列表 */
+export interface LoadRulesOptions {
+	/** 项目级规则文件前缀，默认 "shepherd-rules-" */
+	projectRulesPattern?: string;
+}
+
+export function loadRules(
+	rulesDir?: string,
+	options?: LoadRulesOptions,
+): Rule[] {
+	const allRules: Rule[] = [];
+	const errors: string[] = [];
+	const prefix = options?.projectRulesPattern || "shepherd-rules-";
+
+	// 1. 全局规则：由消费者传入规则文件所在目录
+	if (rulesDir) {
+		const result = loadRulesFromFile(path.join(rulesDir, "rules.json"));
+		allRules.push(...result.rules);
+		if (result.error) errors.push(result.error);
+	}
+
+	// 2. 项目级规则（<cwd>/.pi/extensions/{prefix}*.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")) {
+				const result = loadRulesFromFile(path.join(projectExtDir, file));
+				allRules.push(...result.rules);
+				if (result.error) errors.push(result.error);
+			}
+		}
+	}
+
+	// 格式校验失败时推入 shepherd 提示缓冲区
+	if (errors.length > 0) {
+		const msg = errors.join("；");
+		console.error(`[shepherd] 规则文件格式错误: ${msg}`);
+		pushRuleError(msg);
+	}
+
+	return compileRules(allRules);
+}
+
+/** 从事件中提取匹配目标（多字段）
+ * @param phase 调用阶段："tool_call" 时 git commit 会被短路（避免 commit message 误触发 block 规则），
+ *              "tool_result" 时不短路（允许 git commit 后的 steer/notify 规则触发）
+ */
+export function getMatchTargets(
+	tool: string,
+	event: ToolEvent,
+	phase?: string,
+): Record<string, string> {
+	if (tool === "bash") {
+		const command = (event.input as any)?.command || "";
+		// git commit 的 message 可能包含 sed -i / echo >> 等关键词，跳过匹配
+		// 注意：命令可能是 "cd xxx && git commit ..." 格式
+		// 但仅在 tool_call 阶段短路——tool_result 阶段需要匹配 git commit 后的 steer 规则
+		if (phase === "tool_call" && /(^|&&|;)\s*git\s+commit\b/.test(command)) {
+			return {} as Record<string, string>;
+		}
+		return {
+			command,
+			path: "",
+			text: "",
+			glob: "",
+		};
+	}
+	// grep 工具：提取 glob（文件过滤）、path（搜索目录）、text（搜索模式）
+	if (tool === "grep") {
+		const pathVal = (event.input as any)?.path || "";
+		const globVal = (event.input as any)?.glob || "";
+		const patternVal = (event.input as any)?.pattern || "";
+
+		// 有 glob 时必须是代码扩展名，无 glob 时默认全搜（也触发提醒）
+		if (globVal && !CODE_EXT_RE.test(globVal)) {
+			return {} as Record<string, string>;
+		}
+		return { path: pathVal, text: patternVal, command: "", glob: globVal };
+	}
+	// edit / write / 其他工具
+	const pathVal = (event.input as any)?.path || "";
+	let text = "";
+	if (tool === "edit") {
+		const edits = (event.input as any)?.edits;
+		if (Array.isArray(edits)) {
+			text = edits
+				.flatMap((e: { oldText?: string; newText?: string }) => [e.oldText || "", e.newText || ""])
+				.join("\n");
+		}
+	} else if (tool === "write") {
+		text = (event.input as any)?.content || "";
+	}
+	return { path: pathVal, text, command: "", glob: "" };
+}
+
+/** 判断规则是否匹配事件 */
+export function ruleMatches(
+	rule: Rule,
+	tool: string,
+	targets: Record<string, string>,
+): boolean {
+	// 多条件 AND 模式
+	if (rule.conditions && rule.conditions.length > 0) {
+		return rule.conditions.every((cond) => {
+			const target = targets[cond.field] || "";
+			return cond._compiled?.test(target) ?? false;
+		});
+	}
+	// 单条件模式（向后兼容）
+	if (rule._compiled) {
+		const target = targets[tool === "bash" ? "command" : "path"] || "";
+		return rule._compiled.test(target);
+	}
+	return false;
+}
+
+/** rtk 可用性（模块加载时检测） */
+export const isRtkAvailable: boolean = (() => {
+	try {
+		execSync("which rtk", { timeout: 2000, stdio: "pipe" });
+		return true;
+	} catch {
+		return false;
+	}
+})();