@zhushanwen/pi-permission 0.0.1

package/src/classifier/prompt.ts

@@ -0,0 +1,52 @@
+/**
+ * AI Classifier prompt 构造（I4 classifyRisk 用）
+ *
+ * - CLASSIFIER_SYSTEM_PROMPT：约束 LLM 仅返回严格 JSON
+ * - buildClassifierUserPrompt(ctx)：把待审工具调用拼成 user message
+ *
+ * 设计原则：prompt 短（控制成本/延迟）+ 强约束输出格式（配合 json-parser 三层容错）。
+ */
+
+import type { ToolInvocationContext } from "../types.js";
+
+/**
+ * System prompt：约束 LLM 作为权限风险分类器。
+ *
+ * 要求输出 JSON `{ outcome, risk_level, reasoning, confidence }`：
+ * - outcome ∈ {allow, deny, ask}
+ * - risk_level ∈ {low, medium, high}
+ * - reasoning：简短人类可读理由（英文/中文均可，≤1 句）
+ * - confidence：0-1 浮点
+ *
+ * 故意保持 ~80 token，降低首次调用延迟与成本。
+ */
+export const CLASSIFIER_SYSTEM_PROMPT = `You are a security risk classifier for tool invocations in an AI coding agent.
+Evaluate the given tool invocation for destructive or unsafe operations.
+
+Reply with ONLY a JSON object (no markdown, no prose before/after):
+{"outcome": "allow" | "deny" | "ask", "risk_level": "low" | "medium" | "high", "reasoning": "one short sentence", "confidence": 0.0-1.0}
+
+Rules:
+- allow: safe operations (read-only commands, writing to project directory, git status/diff/log, ls, cat, echo, grep, find)
+- deny: clearly destructive AND irreversible (rm -rf /, mkfs, force push to main, drop database, format disk)
+- ask: potentially dangerous or system-wide changes (rm with recursion, sudo, writing to system dirs like /etc, network operations, deleting multiple files)
+- For file writes: allow if writing to user's project/cwd directory; ask if writing to system dirs or sensitive paths (~/.ssh, /etc)
+- confidence = your certainty in the outcome (0.0 = guessing, 1.0 = certain)`;
+
+/**
+ * 构造 user prompt：把 ToolInvocationContext 的关键字段拼成可读文本。
+ *
+ * 缺省字段用 "(none)" 占位，保证 LLM 看到稳定结构。
+ */
+export function buildClassifierUserPrompt(ctx: ToolInvocationContext): string {
+	const lines: string[] = [
+		`tool: ${ctx.toolName}`,
+		`command: ${ctx.command ?? "(none)"}`,
+		`path: ${ctx.path ?? "(none)"}`,
+		`cwd: ${ctx.cwd}`,
+	];
+	if (ctx.agentName) {
+		lines.push(`agent: ${ctx.agentName}`);
+	}
+	return `Evaluate this tool invocation:\n${lines.join("\n")}`;
+}

package/src/commands.ts

@@ -0,0 +1,234 @@
+/**
+ * /permission 命令
+ *
+ * W1 版本：文本菜单模式（ctx.ui.notify 显示当前模式 + 提示用 /permission <mode> 切换）。
+ * 交互式方向键菜单（ctx.ui.custom + 自定义 Component）留待 W6 或后续迭代。
+ *
+ * 用法：
+ *   /permission              显示当前模式和可用模式列表
+ *   /permission yolo         切换到 yolo 模式
+ *   /permission auto         切换到 auto 模式
+ *   /permission approve      切换到 approve 模式
+ *   /permission strict       切换到 strict 模式
+ *   /permission status       显示当前配置详情
+ */
+
+import type { ResolvedModelEntry } from "./classifier/model-resolver.js";
+import { type ModelPickerContext,pickModelViaOverlay } from "./model-picker.js";
+import { type RuleEditorContext,type RuleEditorResult } from "./rule-editor.js";
+import { applyOps } from "./rule-templates.js";
+import {
+	isValidPermissionMode,
+	MODE_DESCRIPTIONS,
+	MODE_LABELS,
+	PERMISSION_MODES,
+	type PermissionConfig,
+	type PermissionMode,
+} from "./types.js";
+
+/** 命令处理器返回的文本消息（由 ctx.ui.notify 显示） */
+export function handlePermissionCommand(
+	args: string | undefined,
+	config: PermissionConfig,
+	onSave: (config: PermissionConfig) => { success: boolean; error?: string },
+): string {
+	const trimmed = (args ?? "").trim();
+
+	// 无参数：显示当前模式 + 可用模式
+	if (!trimmed) {
+		return formatStatusMessage(config);
+	}
+
+	// status 子命令：详细配置
+	if (trimmed === "status") {
+		return formatDetailedStatus(config);
+	}
+
+	// 切换模式
+	if (isValidPermissionMode(trimmed)) {
+		return switchMode(trimmed, config, onSave);
+	}
+
+	// 未知参数
+	return `[pi-permission] Unknown mode '${trimmed}'. Available: ${PERMISSION_MODES.join(", ")}. Usage: /permission [mode|status|rule|model]`;
+}
+
+// ──────────────────────── 消息格式化 ────────────────────────
+
+function formatStatusMessage(config: PermissionConfig): string {
+	const lines: string[] = [];
+	lines.push("[pi-permission] Current mode: " + modeHighlight(config.mode));
+	lines.push("");
+	lines.push("Available modes (by strictness, low → high):");
+	for (const mode of PERMISSION_MODES) {
+		const marker = mode === config.mode ? "►" : " ";
+		lines.push(`  ${marker} ${mode.padEnd(8)} — ${MODE_DESCRIPTIONS[mode]}`);
+	}
+	lines.push("");
+	lines.push("Switch with: /permission <mode>");
+	return lines.join("\n");
+}
+
+function formatDetailedStatus(config: PermissionConfig): string {
+	const lines: string[] = [];
+	lines.push("[pi-permission] Configuration:");
+	lines.push(`  mode:       ${modeHighlight(config.mode)}`);
+	lines.push(`  enabled:    ${config.enabled}`);
+	lines.push(`  classifier:`);
+	lines.push(`    enabled:           ${config.classifier.enabled}`);
+	lines.push(`    model:             ${config.classifier.model}`);
+	lines.push(`    timeout:           ${config.classifier.timeout}s`);
+	lines.push(`    autoApproveLow:    ${config.classifier.autoApproveLowRisk}`);
+	lines.push(`    autoDenyHigh:      ${config.classifier.autoDenyHighRisk}`);
+	lines.push(`  userRules:  ${config.userRules.length} rule(s)`);
+	return lines.join("\n");
+}
+
+function switchMode(
+	mode: PermissionMode,
+	config: PermissionConfig,
+	onSave: (config: PermissionConfig) => { success: boolean; error?: string },
+): string {
+	if (mode === config.mode) {
+		return `[pi-permission] Already in ${MODE_LABELS[mode]} mode.`;
+	}
+
+	const newConfig: PermissionConfig = {
+		mode,
+		enabled: config.enabled,
+		classifier: { ...config.classifier },
+		userRules: config.userRules.map((r) => ({ ...r })),
+	};
+	const result = onSave(newConfig);
+
+	if (!result.success) {
+		return `[pi-permission] Failed to switch to ${MODE_LABELS[mode]} mode: ${result.error ?? "unknown error"}`;
+	}
+
+	return `[pi-permission] Switched to ${MODE_LABELS[mode]} mode.\n  ${MODE_DESCRIPTIONS[mode]}`;
+}
+
+function modeHighlight(mode: PermissionMode): string {
+	// 纯文本标记（项目规范禁 emoji），用括号标注
+	return `${MODE_LABELS[mode]} (${mode})`;
+}
+
+// ──────────────────────── /permission model（W7） ────────────────────────
+
+/** handlePermissionModelCommand 的依赖（DI 便于测试 mock）。 */
+export interface PermissionModelCommandDeps {
+	/** 列出可用模型（按 provider 分组）。 */
+	listModels: () => Map<string, ResolvedModelEntry[]>;
+	/** 保存新配置，返回 {success, error?}。 */
+	save: (config: PermissionConfig) => { success: boolean; error?: string };
+}
+
+/**
+ * /permission model 命令：overlay 选择 classifier model（provider/model 或 auto）。
+ *
+ * 流程：
+ *  1. listModels：拿可用模型 Map。空 → 降级 notify + return。
+ *  2. pickModelViaOverlay：TUI/RPC/headless 三模式分发。
+ *  3. 写回：save(newConfig)。失败 → notify error。
+ *
+ * 用依赖注入（deps 参数）便于测试 mock listModels/save。
+ * ctx 用 ModelPickerContext 子集（mode + ui.notify/custom/select）。
+ */
+export async function handlePermissionModelCommand(
+	ctx: ModelPickerContext,
+	config: PermissionConfig,
+	deps: PermissionModelCommandDeps,
+): Promise<void> {
+	const current = config.classifier.model;
+
+	// 1. listModels
+	const models = deps.listModels();
+	if (models.size === 0) {
+		ctx.ui.notify(
+			"[pi-permission] No available models. Configure ~/.pi/agent/models.json first.",
+			"warning",
+		);
+		return;
+	}
+
+	// 2. pickModelViaOverlay
+	const selected = await pickModelViaOverlay(ctx, current, models);
+	if (selected === undefined) {
+		ctx.ui.notify("[pi-permission] Model selection cancelled.", "info");
+		return;
+	}
+
+	// 3. 写回（仅改 classifier.model，保留其余字段）
+	const newConfig: PermissionConfig = {
+		mode: config.mode,
+		enabled: config.enabled,
+		classifier: { ...config.classifier, model: selected },
+		userRules: config.userRules.map((r) => ({ ...r })),
+	};
+	const result = deps.save(newConfig);
+	if (!result.success) {
+		ctx.ui.notify(
+			`[pi-permission] Failed to save: ${result.error ?? "unknown error"}`,
+			"error",
+		);
+		return;
+	}
+	ctx.ui.notify(`[pi-permission] AI classifier model set to: ${selected}`, "info");
+}
+
+// ──────────────────────── /permission rule（W8） ────────────────────────
+
+/** handlePermissionRuleCommand 的依赖（DI 便于测试 mock）。 */
+export interface PermissionRuleCommandDeps {
+	/** 保存新配置，返回 {success, error?}。 */
+	save: (config: PermissionConfig) => { success: boolean; error?: string };
+	/** 规则编辑 overlay（注入便于测试 mock）。 */
+	editRulesViaOverlay: (
+		ctx: RuleEditorContext,
+		initialRules: readonly import("./types.js").Rule[],
+		sessionIdCounter: () => string,
+		rpcDeps?: import("./rule-editor.js").RuleEditorRpcDeps,
+	) => Promise<RuleEditorResult>;
+}
+
+/**
+ * /permission rule 命令：overlay CRUD 编辑 userRules。
+ *
+ * 流程：
+ *  1. editRulesViaOverlay：TUI/RPC/headless 三模式分发。
+ *  2. ops 非空 → applyOps + saveConfig + notify。
+ *  3. 空 → notify no changes。
+ */
+export async function handlePermissionRuleCommand(
+	ctx: RuleEditorContext,
+	config: PermissionConfig,
+	sessionIdCounter: () => string,
+	deps: PermissionRuleCommandDeps,
+): Promise<void> {
+	// 1. editRulesViaOverlay
+	const ops = await deps.editRulesViaOverlay(ctx, config.userRules, sessionIdCounter);
+
+	if (ops === undefined || ops.length === 0) {
+		ctx.ui.notify("[pi-permission] No changes applied.", "info");
+		return;
+	}
+
+	// 2. applyOps + save
+	const newUserRules = applyOps([...config.userRules], ops);
+	const newConfig: PermissionConfig = {
+		mode: config.mode,
+		enabled: config.enabled,
+		classifier: { ...config.classifier },
+		userRules: newUserRules,
+	};
+	const result = deps.save(newConfig);
+	if (!result.success) {
+		ctx.ui.notify(
+			`[pi-permission] Failed to save rules: ${result.error ?? "unknown error"}`,
+			"error",
+		);
+		return;
+	}
+
+	ctx.ui.notify(`[pi-permission] ${ops.length} change(s) applied.`, "info");
+}

package/src/config.ts

@@ -0,0 +1,216 @@
+/**
+ * 配置加载 / 保存 / mtime 缓存
+ *
+ * 对应 I6 loadAndWatchConfig。参考 pi-permission-system extension-config.ts。
+ * 文件位置：~/.pi/agent/permission-config.json（支持 PI_CODING_AGENT_DIR 覆盖）。
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+	DEFAULT_CLASSIFIER_CONFIG,
+	DEFAULT_CONFIG,
+	isValidPermissionMode,
+	type ClassifierConfig,
+	type PermissionConfig,
+	type Rule,
+} from "./types.js";
+
+// ──────────────────────── 路径解析 ────────────────────────
+
+/** PI_CODING_AGENT_DIR 环境变量覆盖 ~/.pi/agent 基础路径 */
+function getAgentDir(): string {
+	const override = process.env.PI_CODING_AGENT_DIR?.trim();
+	if (override) return override;
+	return join(homedir(), ".pi", "agent");
+}
+
+/** 配置文件完整路径 */
+export function getConfigPath(): string {
+	return join(getAgentDir(), "permission-config.json");
+}
+
+// ──────────────────────── mtime 缓存 ────────────────────────
+
+interface CacheEntry {
+	mtimeMs: number;
+	size: number;
+	config: PermissionConfig;
+}
+
+/** 深拷贝 config（防止调用方修改污染缓存） */
+function cloneConfig(config: PermissionConfig): PermissionConfig {
+	return {
+		mode: config.mode,
+		enabled: config.enabled,
+		classifier: { ...config.classifier },
+		userRules: config.userRules.map((r) => ({ ...r })),
+	};
+}
+
+/** 模块级缓存：path → {mtimeMs, config}。单进程多 session 共享读缓存是安全的（配置只读） */
+const configCache = new Map<string, CacheEntry>();
+
+/** 测试用：清空缓存 */
+export function clearConfigCache(): void {
+	configCache.clear();
+}
+
+// ──────────────────────── 归一化 ────────────────────────
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeClassifierConfig(raw: unknown): ClassifierConfig {
+	const record = isPlainObject(raw) ? raw : {};
+	const timeout = Number(record.timeout);
+	return {
+		enabled: record.enabled !== false,
+		model: typeof record.model === "string" && record.model.length > 0 ? record.model : DEFAULT_CLASSIFIER_CONFIG.model,
+		timeout: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_CLASSIFIER_CONFIG.timeout,
+		autoApproveLowRisk: record.autoApproveLowRisk !== false,
+		autoDenyHighRisk: record.autoDenyHighRisk !== false,
+	};
+}
+
+function normalizeRule(raw: unknown, fallbackId: string): Rule | null {
+	if (!isPlainObject(raw)) return null;
+	const tool = typeof raw.tool === "string" ? raw.tool : "*";
+	const pattern = typeof raw.pattern === "string" ? raw.pattern : "*";
+	const action = raw.action;
+	if (action !== "allow" && action !== "deny" && action !== "ask") return null;
+	const source = raw.source === "user" ? "user" : raw.source === "builtin-safe" ? "builtin-safe" : raw.source === "builtin-danger" ? "builtin-danger" : "user";
+	const id = typeof raw.id === "string" && raw.id.length > 0 ? raw.id : fallbackId;
+	const description = typeof raw.description === "string" ? raw.description : undefined;
+	return { id, tool, pattern, action, source, ...(description !== undefined ? { description } : {}) };
+}
+
+function normalizeConfig(raw: unknown): PermissionConfig {
+	const record = isPlainObject(raw) ? raw : {};
+	const mode = isValidPermissionMode(record.mode) ? record.mode : DEFAULT_CONFIG.mode;
+	const enabled = record.enabled !== false;
+	const classifier = normalizeClassifierConfig(record.classifier);
+	const userRulesRaw = Array.isArray(record.userRules) ? record.userRules : [];
+	const userRules = userRulesRaw
+		.map((r, i) => normalizeRule(r, `user-${i + 1}`))
+		.filter((r): r is Rule => r !== null);
+	return { mode, enabled, classifier, userRules };
+}
+
+// ──────────────────────── 默认配置文件创建 ────────────────────────
+
+function createDefaultConfigContent(): string {
+	return `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`;
+}
+
+function ensureConfigFile(configPath: string, onWarning?: (msg: string) => void): void {
+	if (existsSync(configPath)) return;
+	try {
+		mkdirSync(dirname(configPath), { recursive: true });
+		writeFileSync(configPath, createDefaultConfigContent(), { encoding: "utf-8", mode: 0o600 });
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		onWarning?.(`[pi-permission] Failed to create default config at '${configPath}': ${message}`);
+	}
+}
+
+// ──────────────────────── 加载（带 mtime 缓存） ────────────────────────
+
+/**
+ * 加载配置，文件未变化时返回缓存。
+ *
+ * @param configPath 配置文件路径（默认 getConfigPath()）
+ * @param onWarning 非致命问题（创建失败、解析失败）的警告回调
+ */
+export function loadAndWatchConfig(
+	configPath: string = getConfigPath(),
+	onWarning?: (msg: string) => void,
+): PermissionConfig {
+	ensureConfigFile(configPath, onWarning);
+
+	let stat;
+	try {
+		stat = statSync(configPath);
+	} catch {
+		// 文件不可 stat（权限问题/被删除）→ 用缓存或默认
+		const cached = configCache.get(configPath);
+		return cached ? cloneConfig(cached.config) : cloneConfig(DEFAULT_CONFIG);
+	}
+
+	const cached = configCache.get(configPath);
+	// mtime + size 双 key：防止 APFS 等文件系统 mtime 精度截断导致快速连续保存后缓存失效。
+	//
+	// 已知 limitation（m5）：mtime + size 不是内容指纹，「同毫秒同字节大小但内容不同」的写入
+	// （如交换两条等长 userRules 的顺序）会误命中缓存返回旧 config。完整消除需内容哈希（如 sha256），
+	// 但每次 load 都算哈希成本过高（config 可能较大），且 permission-config 写入频率低（用户手动编辑
+	// 或 /permission 命令）、mtime 变化的概率远高于同毫秒同大小写不同内容，故权衡采用 mtime+size。
+	// saveConfig 已在写后立即用新 stat 更新缓存（见下方 saveConfig），覆盖最常见的「写后读」竞态。
+	if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+		return cloneConfig(cached.config);
+	}
+
+	try {
+		const raw = readFileSync(configPath, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		const config = normalizeConfig(parsed);
+		configCache.set(configPath, { mtimeMs: stat.mtimeMs, size: stat.size, config });
+		return cloneConfig(config);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		onWarning?.(`[pi-permission] Config parse failed at '${configPath}', using default: ${message}`);
+		const fallback = { ...DEFAULT_CONFIG, classifier: { ...DEFAULT_CLASSIFIER_CONFIG } };
+		// 解析失败也更新缓存 mtime+size，避免每次都重读损坏文件
+		configCache.set(configPath, { mtimeMs: stat.mtimeMs, size: stat.size, config: fallback });
+		return cloneConfig(fallback);
+	}
+}
+
+// ──────────────────────── 保存（原子写） ────────────────────────
+
+/**
+ * 保存配置（原子写：tmp 文件 + rename）。
+ *
+ * @returns 成功返回 {success:true}；失败返回 {success:false, error}
+ */
+export function saveConfig(
+	config: PermissionConfig,
+	configPath: string = getConfigPath(),
+): { success: boolean; error?: string } {
+	// 信任调用方传入的已类型化对象，不重新 normalize（避免 normalizeRule 重分配 fallback id 覆盖用户意图）
+	const tmpPath = `${configPath}.tmp`;
+	const content = `${JSON.stringify(config, null, 2)}\n`;
+
+	try {
+		mkdirSync(dirname(configPath), { recursive: true });
+		writeFileSync(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+		renameSync(tmpPath, configPath);
+
+		// 更新缓存（用新文件的 mtime + size）
+		try {
+			const newStat = statSync(configPath);
+			configCache.set(configPath, { mtimeMs: newStat.mtimeMs, size: newStat.size, config: cloneConfig(config) });
+		} catch (statErr) {
+			// stat 失败不影响保存成功；缓存下次 load 时会重读。记录原因便于调试。
+			console.warn(`[pi-permission] saveConfig stat after write failed:`, statErr instanceof Error ? statErr.message : String(statErr));
+		}
+
+		return { success: true };
+	} catch (error) {
+		try {
+			if (existsSync(tmpPath)) unlinkSync(tmpPath);
+		} catch (cleanupErr) {
+			// tmp 清理失败不能阻塞保存失败的返回；记录原因
+			console.warn(`[pi-permission] saveConfig tmp cleanup failed:`, cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr));
+		}
+		const message = error instanceof Error ? error.message : String(error);
+		return { success: false, error: `Failed to save config at '${configPath}': ${message}` };
+	}
+}
+
+/** 测试/内部用：设置特定路径的缓存（绕过文件系统） */
+export function setConfigCache(configPath: string, config: PermissionConfig, mtimeMs: number, size: number): void {
+	configCache.set(configPath, { mtimeMs, size, config });
+}