@zhushanwen/pi-permission 1.3.2 → 1.3.4

package/package.json

@@ -1,11 +1,29 @@
 {
   "name": "@zhushanwen/pi-permission",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Pi permission extension — four permission modes (yolo/auto/approve/strict) with three-layer pipeline (AST + rules + AI classifier).",
   "type": "module",
   "main": "src/index.ts",
   "xyz-agent": {
-    "role": "universal"
+    "role": "universal",
+    "startupConfig": [
+      {
+        "path": "config/permission-ext-config.json",
+        "content": {
+          "mode": "yolo",
+          "enabled": true,
+          "classifier": {
+            "enabled": true,
+            "model": "auto",
+            "timeout": 90,
+            "autoApproveLowRisk": true,
+            "autoDenyHighRisk": true,
+            "thinkingLevel": "off"
+          },
+          "userRules": []
+        }
+      }
+    ]
   },
   "pi": {
     "extensions": [
@@ -32,12 +50,13 @@
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",
     "web-tree-sitter": "^0.26.11",
-    "@zhushanwen/pi-llm-shared": "0.4.0"
+    "@zhushanwen/pi-extension-logger": "0.3.1",
+    "@zhushanwen/pi-llm-shared": "0.4.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1"
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -51,9 +70,9 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.2",
-    "@earendil-works/pi-coding-agent": "^0.84.2",
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },

package/src/__tests__/config.test.ts

@@ -9,6 +9,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
 import { DEFAULT_CONFIG } from "../types.js";
 import {
 	clearConfigCache,
@@ -127,42 +137,36 @@ describe("WT3: 配置解析容错（malformed JSON）", () => {
 		// 用户照旧设计文档配对象形式 selector（不受支持）
 		writeFileSync(configPath, JSON.stringify({ classifier: { model: { type: "available" } } }), "utf-8");
 
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			const config = loadAndWatchConfig();
-			// 回落默认 auto（不再静默）
-			expect(config.classifier.model).toBe("auto");
-			// warn 提示忽略无效 classifier.model
-			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Ignoring invalid classifier.model"));
-		} finally {
-			warnSpy.mockRestore();
-		}
+	loggerMock.warn.mockClear();
+		const config = loadAndWatchConfig();
+		// 回落默认 auto（不再静默）
+		expect(config.classifier.model).toBe("auto");
+		// warn 提示忽略无效 classifier.model
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("Ignoring invalid classifier.model"),
+		);
 	});
 
-	it("classifier.model 传数字 → console.warn + 回落默认 auto", () => {
+	it("classifier.model 传数字 → logger.warn + 回落默认 auto", () => {
 		writeFileSync(configPath, JSON.stringify({ classifier: { model: 42 } }), "utf-8");
 
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			const config = loadAndWatchConfig();
-			expect(config.classifier.model).toBe("auto");
-			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Ignoring invalid classifier.model"));
-		} finally {
-			warnSpy.mockRestore();
-		}
+		loggerMock.warn.mockClear();
+		const config = loadAndWatchConfig();
+		expect(config.classifier.model).toBe("auto");
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("Ignoring invalid classifier.model"),
+		);
 	});
 
 	it("classifier.model 合法 string（'auto' / 'provider/model-id'）→ 不 warn", () => {
 		writeFileSync(configPath, JSON.stringify({ classifier: { model: "zhipu/glm-4-flash" } }), "utf-8");
 
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			const config = loadAndWatchConfig();
-			expect(config.classifier.model).toBe("zhipu/glm-4-flash");
-			expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Ignoring invalid classifier.model"));
-		} finally {
-			warnSpy.mockRestore();
-		}
+	loggerMock.warn.mockClear();
+		const config = loadAndWatchConfig();
+		expect(config.classifier.model).toBe("zhipu/glm-4-flash");
+		expect(loggerMock.warn).not.toHaveBeenCalledWith(
+			expect.stringContaining("Ignoring invalid classifier.model"),
+		);
 	});
 
 	it("userRules 含非法条目时过滤掉", () => {
@@ -275,23 +279,21 @@ describe("[MIGRATION] legacy config 降级告警（ensureConfigFile 兜底）",
 		const legacyPath = join(tempDir, "permission-config.json");
 		writeFileSync(legacyPath, JSON.stringify({ mode: "strict" }), "utf-8");
 
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			loadAndWatchConfig();
-			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Legacy config detected"));
-			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("downgrade"));
-		} finally {
-			warnSpy.mockRestore();
-		}
+	loggerMock.warn.mockClear();
+		loadAndWatchConfig();
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("Legacy config detected"),
+		);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("downgrade"),
+		);
 	});
 
 	it("旧路径不存在 → 不触发 legacy 告警", () => {
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			loadAndWatchConfig();
-			expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Legacy config detected"));
-		} finally {
-			warnSpy.mockRestore();
-		}
+		loggerMock.warn.mockClear();
+		loadAndWatchConfig();
+		expect(loggerMock.warn).not.toHaveBeenCalledWith(
+			expect.stringContaining("Legacy config detected"),
+		);
 	});
 });

package/src/__tests__/footer-provider.test.ts

@@ -16,6 +16,16 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
 import {
 	FOOTER_HANDSHAKE_KEY,
 	type FooterLineRenderer,
@@ -211,8 +221,8 @@ describe("TC6/TC7：requestFooterRender", () => {
 // ──────────────────────── TC8：version mismatch → 重建 slot ────────────────────────
 
 describe("TC8：version mismatch → readSlot 丢弃 + ensureSlot 重建", () => {
-	it("slot.version !== 1 → 注册时建新 slot（丢弃旧的），并 console.warn", () => {
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+	it("slot.version !== 1 → 注册时建新 slot（丢弃旧的），并 logger.warn", () => {
+		loggerMock.warn.mockClear();
 		// 污染槽位：version=99
 		Reflect.set(globalThis, FOOTER_HANDSHAKE_KEY, {
 			version: 99,
@@ -222,10 +232,10 @@ describe("TC8：version mismatch → readSlot 丢弃 + ensureSlot 重建", () =>
 		const slot = getRawSlot() as { version: number; pending: unknown[] };
 		expect(slot.version).toBe(1); // 重建为 version=1
 		expect(slot.pending).toHaveLength(1);
-		expect(warnSpy).toHaveBeenCalledWith(
+		expect(loggerMock.warn).toHaveBeenCalledWith(
 			expect.stringContaining("version mismatch"),
+			expect.any(Object),
 		);
-		warnSpy.mockRestore();
 	});
 
 	it("pending 非 Array → 视为无 slot，重建", () => {

package/src/__tests__/pipeline.test.ts

@@ -7,6 +7,16 @@
  */
 import { describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
 import {
 	applyAutoApproveOverrides,
 	buildApprovalRequest,
@@ -708,9 +718,9 @@ describe("M5b: runLayer3WithRacing headless 模式（纯等 AI，不启动 user
 
 // ──────────────────────── m3: extractCommand 非字符串 bash command 告警 ────────────────────────
 
-describe("m3: bash 工具收到非字符串 command 时 console.warn（不静默）", () => {
+describe("m3: bash 工具收到非字符串 command 时 logger.warn（不静默）", () => {
 	it("command 为数字 → warn 被调用 + fail-closed（不 throw，送下游）", async () => {
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		loggerMock.warn.mockClear();
 		const deps = makeDeps({
 			classify: () => Promise.resolve(allowClassifier("low")),
 			approve: () => new Promise<UserDecision>(() => undefined),
@@ -718,21 +728,19 @@ describe("m3: bash 工具收到非字符串 command 时 console.warn（不静默
 		// command 为数字（异常输入）
 		const decision = await checkPermission("bash", { command: 123 }, "auto", DEFAULT_CFG, [], deps, ctxBase);
 		// warn 被调用（记录异常）
-		expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("non-string command"));
-		warnSpy.mockRestore();
+		expect(loggerMock.warn).toHaveBeenCalledWith(expect.stringContaining("non-string command"), expect.any(Object));
 		// fail-closed：不 throw，正常返回决策（AI allow low → allow）
 		expect(decision.action).toBe("allow");
 	});
 
 	it("command 为合法字符串 → 不 warn", async () => {
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+		loggerMock.warn.mockClear();
 		const deps = makeDeps({
 			analyze: () => Promise.resolve(cleanAnalysis([["ls"]])),
 			matchArgv: () => ({ action: "allow", matchedRule: undefined }),
 		});
 		await checkPermission("bash", { command: "ls" }, "approve", DEFAULT_CFG, [], deps, ctxBase);
-		expect(warnSpy).not.toHaveBeenCalled();
-		warnSpy.mockRestore();
+		expect(loggerMock.warn).not.toHaveBeenCalled();
 	});
 });
 

package/src/__tests__/production.test.ts

@@ -21,6 +21,16 @@ import type { ApprovalContext } from "../approval.js";
 import type { CheckPermissionDeps } from "../pipeline.js";
 import { createPipelineDeps, createProductionClassifier, toSelector } from "../production.js";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+	createLogger: () => loggerMock,
+	setPiHandle: vi.fn(),
+}));
+
 // vi.mock 必须在 import 之前（vitest hoisting）。替换 llm-shared 的 resolveModel + callLLM
 // 为可控 mock，默认透传 actual（真实实现），单测用 mockImplementation/mockResolvedValue 精确控制。
 vi.mock("@zhushanwen/pi-llm-shared", async (importOriginal) => {
@@ -174,14 +184,10 @@ describe("resolveModel 装配（resolveModel + callLLM）", () => {
 		vi.mocked(resolveModelShared).mockReturnValue(MOCK_MODEL_A);
 		vi.mocked(callLLMShared).mockResolvedValue({ ok: true, content: "x" });
 		const classifier = createProductionClassifier(makeMockCtx());
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-		try {
-			await classifier.classifyRisk(CTX, CFG_REF);
-			// onLog 实装为 console.warn（production.ts），成功路径日志在 LLM 调用前输出
-			expect(warnSpy).toHaveBeenCalledWith("[pi-permission] classifier: using model model-a");
-		} finally {
-			warnSpy.mockRestore();
-		}
+		loggerMock.warn.mockClear();
+		await classifier.classifyRisk(CTX, CFG_REF);
+		// onLog 实装为 logger.warn（production.ts），成功路径日志在 LLM 调用前输出
+		expect(loggerMock.warn).toHaveBeenCalledWith("[pi-permission] classifier: using model model-a");
 	});
 
 	it("TC5: callLLM 返回 ok:false（LLM 调用失败）→ classifier fail-closed fallback（不 throw）", async () => {

package/src/__tests__/startup-config-declaration.test.ts

@@ -0,0 +1,34 @@
+/**
+ * startupConfig 声明守护测试：断言 package.json `xyz-agent.startupConfig` 声明的
+ * content 与代码 DEFAULT_CONFIG 常量深相等，防止两侧任一改动未同步（漂移）。
+ * 机制：runtime 启动序列统一 ensure（extension-startup-config.ts），声明即首建内容。
+ *
+ * 运行：cd extensions/universal/permission && npx vitest run src/__tests__/startup-config-declaration.test.ts
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_CONFIG } from "../types.js";
+
+/** package.json `xyz-agent.startupConfig` 声明条目的最小形状（守护断言用）。 */
+interface StartupConfigEntry {
+	path: string;
+	content: unknown;
+}
+
+const pkg = JSON.parse(
+	readFileSync(join(fileURLToPath(import.meta.url), "../../../package.json"), "utf-8"),
+) as { "xyz-agent"?: { startupConfig?: StartupConfigEntry[] } };
+
+describe("startupConfig 声明守护", () => {
+	it("声明 content 与代码 DEFAULT_CONFIG 深相等", () => {
+		const entry = pkg["xyz-agent"]?.startupConfig?.find(
+			(e: StartupConfigEntry) => e.path === "config/permission-ext-config.json",
+		);
+		expect(entry).toBeDefined();
+		expect(entry?.content).toEqual(DEFAULT_CONFIG);
+	});
+});

package/src/ast/analyzer.ts

@@ -19,13 +19,19 @@
  */
 
 import type { Node, Tree } from "web-tree-sitter";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import type { BashAnalysis } from "../types.js";
 import { getBashParser } from "./loader.js";
 
+const logger = getLogger("pi-permission/ast");
+
 /** 超过此长度的输入直接拒（防止 wasm 解析巨型 payload DoS）。 */
 const MAX_COMMAND_LENGTH = 65536;
 
+/** 带引号 token 的最小长度（首尾引号各占 1 字符）；满足才能安全剥引号。 */
+const MIN_QUOTED_TOKEN_LENGTH = 2;
+
 /**
  * Codex ALLOWED_KINDS（11 个 named node）。
  * 遇到不在此集合的 named node 即判定为危险结构。
@@ -73,7 +79,7 @@ function parseDoubleQuotedString(node: Node): string | null {
 	}
 	const raw = node.text;
 	// 去掉首尾的 `"`（raw 形如 `"hello world"`）
-	if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+	if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= MIN_QUOTED_TOKEN_LENGTH) {
 		return raw.slice(1, -1);
 	}
 	// 异常 grammar（理论上不会到这）—— 原样返回
@@ -89,7 +95,7 @@ function parseRawString(node: Node): string | null {
 		return null;
 	}
 	const raw = node.text;
-	if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2) {
+	if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= MIN_QUOTED_TOKEN_LENGTH) {
 		return raw.slice(1, -1);
 	}
 	return raw;
@@ -230,7 +236,7 @@ export async function analyzeBashStructure(command: string): Promise<BashAnalysi
 	} catch (err) {
 		// 任何意外异常 → fail-closed
 		const msg = err instanceof Error ? err.message : String(err);
-		console.warn(`[pi-permission/ast] analyzeBashStructure exception: ${msg}`);
+		logger.warn("analyzeBashStructure exception", { error: msg });
 		return failClosed(msg || "EXCEPTION");
 	} finally {
 		// G1 critical: Tree 是 wasm 堆对象，不受 V8 GC 管，必须显式 delete 释放。

package/src/ast/loader.ts

@@ -6,7 +6,7 @@
  *  - 初始化 Parser 运行时（locateFile 指向 wasm 目录）
  *  - 加载 bash grammar，构造并缓存 Parser 单例（promise memoization，天然并发互斥）
  *
- * 失败策略（fail-closed）：任一步抛错 → console.warn + 返回 null，永不 throw。
+ * 失败策略（fail-closed）：任一步抛错 → logger.warn + 返回 null，永不 throw。
  * analyzer 拿到 null 时降级为 { clean:false, parseError:true }。
  *
  * 注意（实测 web-tree-sitter 0.26.11 的事实，与 pi-lens 用的 0.24.5 有差异）：
@@ -25,6 +25,9 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { Language, Parser } from "web-tree-sitter";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("pi-permission/ast");
 
 const nodeRequire = createRequire(import.meta.url);
 
@@ -119,7 +122,7 @@ export function getBashParser(): Promise<Parser | null> {
 			// fail-closed：清空缓存让下次调用重试，warn 后返回 null。
 			parserPromise = null;
 			const msg = err instanceof Error ? err.message : String(err);
-			console.warn(`[pi-permission/ast] getBashParser init failed: ${msg}`);
+			logger.warn("getBashParser init failed", { error: msg });
 			return null;
 		}
 	})();

package/src/commands.ts

@@ -55,6 +55,9 @@ export function handlePermissionCommand(
 
 // ──────────────────────── 消息格式化 ────────────────────────
 
+/** 模式列表 mode 列的 padEnd 宽度（最长 'approve' 7 字符 + 1 间隔，保证描述列对齐）。 */
+const MODE_COLUMN_WIDTH = 8;
+
 function formatStatusMessage(config: PermissionConfig): string {
 	const lines: string[] = [];
 	lines.push("[pi-permission] Current mode: " + modeHighlight(config.mode));
@@ -62,7 +65,7 @@ function formatStatusMessage(config: PermissionConfig): string {
 	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(`  ${marker} ${mode.padEnd(MODE_COLUMN_WIDTH)} — ${MODE_DESCRIPTIONS[mode]}`);
 	}
 	lines.push("");
 	lines.push("Switch with: /permission <mode>");

package/src/config.ts

@@ -25,6 +25,7 @@ import {
 	loadConfig,
 	saveConfig as saveLlmConfig,
 } from "@zhushanwen/pi-llm-shared";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 
 import {
 	DEFAULT_CLASSIFIER_CONFIG,
@@ -38,6 +39,8 @@ import {
 /** llm-shared 泛型 config 的包名（决定文件名 permission-ext-config.json，llm-shared getConfigPath 追加 -ext-config.json 后缀）。 */
 const CONFIG_PKG = "permission";
 
+const logger = getLogger("pi-permission");
+
 // ──────────────────────── 路径解析 ────────────────────────
 
 /** 配置文件完整路径：<agentDir>/config/permission-ext-config.json（llm-shared 推导）。 */
@@ -71,7 +74,7 @@ function normalizeClassifierConfig(raw: unknown): ClassifierConfig {
 	// C3b：classifier.model 只接受 string（'auto' 或 'provider/model-id'）。对象形式（如
 	// `{ "type": "available" }`）不受支持，此前会被静默忽略回落默认——现在显式 warn 消除静默。
 	if (record.model !== undefined && !(typeof record.model === "string" && record.model.length > 0)) {
-		console.warn("[pi-permission] Ignoring invalid classifier.model (expected string 'auto' or 'provider/model-id'), using default auto");
+		logger.warn("Ignoring invalid classifier.model (expected string 'auto' or 'provider/model-id'), using default auto");
 	}
 	// thinkingLevel 校验：合法值为 'off'|'minimal'|'low'|'medium'|'high'|'xhigh'|'max'
 	const thinkingLevel = isModelThinkingLevel(record.thinkingLevel)
@@ -113,8 +116,11 @@ function normalizeConfig(raw: unknown): PermissionConfig {
 
 // ──────────────────────── 默认配置文件创建 ────────────────────────
 
+/** 默认配置文件 JSON 序列化的缩进空格数。 */
+const CONFIG_JSON_INDENT_SPACES = 2;
+
 function createDefaultConfigContent(): string {
-	return `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`;
+	return `${JSON.stringify(DEFAULT_CONFIG, null, CONFIG_JSON_INDENT_SPACES)}\n`;
 }
 
 function ensureConfigFile(configPath: string, onWarning?: (msg: string) => void): void {
@@ -140,8 +146,8 @@ function warnLegacyConfigIfExists(): void {
 	const legacyPath = join(getAgentDir(), "permission-config.json");
 	if (!existsSync(legacyPath)) return;
 	const newPath = join(getAgentDir(), "config", "permission-ext-config.json");
-	console.warn(
-		`[pi-permission] Legacy config detected at '${legacyPath}' but new config '${newPath}' is missing. ` +
+	logger.warn(
+		`Legacy config detected at '${legacyPath}' but new config '${newPath}' is missing. ` +
 			`Migration did not run — defaulting to yolo mode, which may downgrade your previous strict/auto setting. ` +
 			`Remove the legacy file or move it to the new path after migrating.`,
 	);

package/src/footer-provider.ts

@@ -16,9 +16,12 @@
 // 纯 globalThis 反射实现：不静态 import pi-statusline（permission 的可选 peerDep，
 // 未安装时静态 import 会致整个 permission 加载失败），运行时结构兼容即可。
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { MODE_LABELS, type PermissionMode } from "./types.js";
 import type { PermissionPalette } from "./statusline-palette.js";
 
+const logger = getLogger("pi-permission");
+
 // ── 协议契约字面量（必须与 pi-statusline 的 footer-handshake-access.ts 完全一致）──
 // Symbol.for 字符串是跨包稳定契约：pi-statusline(owner) 与 permission(consumer) 通过同一
 // Symbol 读/写 globalThis slot。字符串不一致 → 握手静默失败（双方各持独立 slot，永不对齐）。
@@ -81,9 +84,10 @@ function readSlot(): FooterHandshakeSlot | undefined {
 	if (!("version" in slot) || !("pending" in slot)) return undefined;
 	const loose = slot as { version: unknown; pending: unknown };
 	if (loose.version !== HANDSHAKE_VERSION) {
-		console.warn(
-			`[pi-permission] footer handshake version mismatch (got ${String(loose.version)}, expected ${HANDSHAKE_VERSION}); discarding and recreating.`,
-		);
+		logger.warn("footer handshake version mismatch, discarding and recreating", {
+			got: String(loose.version),
+			expected: HANDSHAKE_VERSION,
+		});
 		return undefined;
 	}
 	if (!Array.isArray(loose.pending)) return undefined;

package/src/index.ts

@@ -18,9 +18,11 @@ import {
 	type ExtensionContext,
 	getAgentDir,
 } from "@earendil-works/pi-coding-agent";
-
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { migrateLegacyConfig } from "@zhushanwen/pi-llm-shared";
 
+const logger = getLogger("pi-permission");
+
 import { listAvailableModels } from "./classifier/model-resolver.js";
 import { handlePermissionCommand, handlePermissionModelCommand, handlePermissionRuleCommand } from "./commands.js";
 import { loadAndWatchConfig, saveConfig } from "./config.js";
@@ -45,8 +47,8 @@ import { paletteFromTheme, type PermissionPalette } from "./statusline-palette.j
 // 模块级 once flag 防同进程重复触发；agentDir 由 getAgentDir() 推导（尊重 PI_CODING_AGENT_DIR）。
 let configMigrationChecked = false;
 
-/** 默认配置 warning 回调（loadAndWatchConfig 共用，透传 console.warn）。 */
-const defaultConfigWarn = (msg: string): void => console.warn(msg);
+/** 默认配置 warning 回调（loadAndWatchConfig 共用，透传 logger.warn）。 */
+const defaultConfigWarn = (msg: string): void => logger.warn(msg);
 
 // ──────────────────────── tool_call event 最小子集 ────────────────────────
 
@@ -68,6 +70,14 @@ interface ToolCallResult {
 	reason?: string;
 }
 
+/**
+ * ctx.ui.select / ctx.ui.input 的 opts 参数索引（第 3 个参数，0-based）。
+ * 类型位置提取 opts 时用 `Parameters<typeof ...>[typeof _UI_OPTIONS_PARAM_INDEX]`
+ * （字面量索引会触发 no-magic-numbers，typeof 常量索引语义等价）。
+ * 仅类型位置使用、运行时无值引用，按项目约定加 `_` 前缀豁免 no-unused-vars。
+ */
+const _UI_OPTIONS_PARAM_INDEX = 2;
+
 // ──────────────────────── 扩展工厂 ────────────────────────
 
 /**
@@ -133,7 +143,7 @@ export default function permissionExtension(pi: ExtensionAPI): void {
 						mode: ctx.mode,
 						ui: {
 							notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
-							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) =>
+							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[typeof _UI_OPTIONS_PARAM_INDEX]) =>
 								ctx.ui.select(title, options, opts),
 							custom: <T,>(
 								factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
@@ -143,7 +153,7 @@ export default function permissionExtension(pi: ExtensionAPI): void {
 							// 连接 ctx.ui.input（rule-editor custom 模板文本输入用）。
 							// approval.ts 已声明可选 input（SDK 提供，mock 可能缺失）。
 							...(typeof ctx.ui.input === "function"
-								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[typeof _UI_OPTIONS_PARAM_INDEX]) => ctx.ui.input(title, placeholder, opts) }
 								: {}),
 						},
 					},
@@ -170,7 +180,7 @@ export default function permissionExtension(pi: ExtensionAPI): void {
 						modelRegistry: ctx.modelRegistry,
 						ui: {
 							notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
-							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) =>
+							select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[typeof _UI_OPTIONS_PARAM_INDEX]) =>
 								ctx.ui.select(title, options, opts),
 							custom: <T,>(
 								factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
@@ -179,13 +189,13 @@ export default function permissionExtension(pi: ExtensionAPI): void {
 								ctx.ui.custom<T>(factory as Parameters<typeof ctx.ui.custom<T>>[0], options),
 							// 连接 ctx.ui.input（与 rule handler 一致；model picker 当前不用，但保持 ctx 对称）。
 							...(typeof ctx.ui.input === "function"
-								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+								? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[typeof _UI_OPTIONS_PARAM_INDEX]) => ctx.ui.input(title, placeholder, opts) }
 								: {}),
 						},
 					},
 					config,
 					{
-						listModels: (pickerCtx) => listAvailableModels(pickerCtx, (m) => console.warn(m)),
+						listModels: (pickerCtx) => listAvailableModels(pickerCtx, (m) => logger.warn(m)),
 						save: (newConfig) => {
 							const r = saveConfig(newConfig);
 							if (r.success) requestFooterRender();
@@ -313,7 +323,7 @@ async function processToolCall(
 		mode: ctx.mode,
 		ui: {
 			notify: (msg: string, type?: "info" | "warning" | "error") => ctx.ui.notify(msg, type),
-			select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[2]) => ctx.ui.select(title, options, opts),
+			select: (title: string, options: string[], opts?: Parameters<typeof ctx.ui.select>[typeof _UI_OPTIONS_PARAM_INDEX]) => ctx.ui.select(title, options, opts),
 			custom: <T,>(
 				factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => unknown,
 				options?: { overlay?: boolean },
@@ -322,7 +332,7 @@ async function processToolCall(
 			// W6 T9 G3：Reject-with-Reason。ctx.ui.input 存在则透传（采集真实拒绝理由）。
 			// approval.ts 的 collectRejectReason 会用 typeof 判断是否可用，不可用则 fallback。
 			...(typeof ctx.ui.input === "function"
-				? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[2]) => ctx.ui.input(title, placeholder, opts) }
+				? { input: (title: string, placeholder?: string, opts?: Parameters<typeof ctx.ui.input>[typeof _UI_OPTIONS_PARAM_INDEX]) => ctx.ui.input(title, placeholder, opts) }
 				: {}),
 		},
 	};
@@ -352,7 +362,7 @@ async function processToolCall(
 	} catch (error) {
 		// fail-closed：异常 → block + reason（绝不放行）
 		const msg = error instanceof Error ? error.message : String(error);
-		console.warn(`[pi-permission] tool_call handler exception for ${toolName}: ${msg}`);
+		logger.warn("tool_call handler exception", { toolName, error: msg });
 		return {
 			block: true,
 			reason: `[pi-permission] internal error (fail-closed): ${msg}`,

package/src/model-picker.ts

@@ -53,6 +53,9 @@ const AUTO_VALUE = "__auto__";
 /** SelectList 最大可见行数（picker overlay 不超过终端高度）。 */
 const MAX_VISIBLE_ITEMS = 10;
 
+/** box 边框左右各占用 1 列（│ × 2）。 */
+const BORDER_OVERHEAD = 2;
+
 // ──────────────────────── 辅助组件（inline Component stub，避免依赖 Box 的 padding/bg） ────────────────────────
 
 /**
@@ -127,14 +130,11 @@ export class ProviderModelSelectorComponent extends Container {
 		this.currentList?.handleInput(data);
 	}
 
-	/** box 边框左右各占用 1 列（│ × 2） */
-	private static readonly BORDER_OVERHEAD = 2;
-
 	/**
 	 * 重写 render：用 box 边框包裹 Container 子组件的输出。
 	 */
 	override render(width: number): string[] {
-		const innerWidth = Math.max(0, width - ProviderModelSelectorComponent.BORDER_OVERHEAD);
+		const innerWidth = Math.max(0, width - BORDER_OVERHEAD);
 		const inner = super.render(innerWidth);
 		const lines: string[] = [];
 		lines.push(`\u250C${"\u2500".repeat(innerWidth)}\u2510`);

package/src/pipeline.ts

@@ -16,6 +16,7 @@
  * checkPermission 永不 throw（caller index.ts 的 tool_call handler 依赖此契约）。
  */
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { matchRules } from "./rules/matcher.js";
 import { wildcardToRegExp } from "./rules/wildcard.js";
 import type {
@@ -39,6 +40,8 @@ import type {
 // pipeline.js import 这些类型，不破坏现有 import 路径）。
 export type { ApprovalRequest, CheckPermissionDeps } from "./types.js";
 
+const logger = getLogger("pi-permission");
+
 // ──────────────────────── buildApprovalRequest ────────────────────────
 
 /**
@@ -533,9 +536,9 @@ function extractCommand(toolName: string, input: Record<string, unknown>): strin
 	if (typeof cmd === "string") return cmd;
 	// m3：bash + command 非字符串（异常输入）→ 记录警告，fail-closed 送下游
 	// （不静默跳过 AST，避免危险命令因类型异常绕过检查）。
-	console.warn(
-		`[pi-permission] bash tool received non-string command (type=${typeof cmd}); ` +
-			`skipping AST analysis (fail-closed: forwarded to downstream layers)`,
+	logger.warn(
+		"bash tool received non-string command (skipping AST analysis, fail-closed: forwarded to downstream layers)",
+		{ type: typeof cmd },
 	);
 	return undefined;
 }

package/src/production.ts

@@ -19,9 +19,12 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { callLLM, resolveModel as resolveModelShared, type ModelSelector } from "@zhushanwen/pi-llm-shared";
 
 import { type ApprovalContext, requestUserApproval } from "./approval.js";
+
+const logger = getLogger("pi-permission");
 import { analyzeBashStructure } from "./ast/index.js";
 import { createClassifier } from "./classifier/index.js";
 import type { CheckPermissionDeps } from "./pipeline.js";
@@ -65,7 +68,7 @@ export function createProductionClassifier(ctx: ExtensionContext): {
 			return resolveModelShared(ctx, toSelector(config.model));
 		},
 		callLLM: (opts) => callLLM(ctx, opts),
-		onLog: (msg: string) => console.warn(msg),
+		onLog: (msg: string) => logger.warn(msg),
 	});
 }
 

package/src/rule-editor-component.ts

@@ -11,7 +11,7 @@
  * WR8：focusIndex 模 5（Custom form 5 项 Tab 循环）。
  */
 
-import { type Component, Container, Input, type SelectItem, SelectList, type SelectListTheme, truncateToWidth } from "@earendil-works/pi-tui";
+import { type Component, Container, Input, isFocusable, type SelectItem, SelectList, type SelectListTheme, truncateToWidth } from "@earendil-works/pi-tui";
 import { matchesKey } from "@earendil-works/pi-tui";
 
 import {
@@ -36,6 +36,19 @@ const THEME: SelectListTheme = {
 
 const MAX_VISIBLE = 12;
 
+/** box 边框左右各占用 1 列（│ × 2）。 */
+const BORDER_OVERHEAD = 2;
+
+/** custom form 焦点指示前缀（▶ + 空格，1 显示列 + 1 空格）。 */
+const FOCUS_INDICATOR_PREFIX = "\u25B6 ";
+
+/** scope 选择：all/subcmd 二选一全可见。 */
+const SCOPE_LIST_MAX_VISIBLE = 2;
+/** action 选择：allow/deny/ask 三选一全可见。 */
+const ACTION_LIST_MAX_VISIBLE = 3;
+/** submit 选择：Submit/Cancel 二选一全可见。 */
+const SUBMIT_LIST_MAX_VISIBLE = 2;
+
 // ──────────────────────── TextLines component ────────────────────────
 
 class TextLines implements Component {
@@ -123,11 +136,8 @@ export class RuleEditorComponent extends Container {
 
 	// ──────────────────────── 边框渲染 ────────────────────────
 
-	/** box 边框左右各占用 1 列（│ × 2） */
-	private static readonly BORDER_OVERHEAD = 2;
-
 	override render(width: number): string[] {
-		const innerWidth = Math.max(0, width - RuleEditorComponent.BORDER_OVERHEAD);
+		const innerWidth = Math.max(0, width - BORDER_OVERHEAD);
 		let inner = super.render(innerWidth);
 
 		// custom form 焦点指示（M4）：当前焦点字段的标签加 ▶ 前缀
@@ -169,11 +179,11 @@ export class RuleEditorComponent extends Container {
 		return lines.map((line) => {
 			// 精确匹配当前焦点标签 → 加 ▶ 前缀
 			if (line === focusedLabel) {
-				return `\u25B6 ${line}`;
+				return FOCUS_INDICATOR_PREFIX + line;
 			}
 			// 焦点已转移：去掉其他标签行残留的 ▶ 前缀（避免重复渲染累积）
-			if (line.startsWith("\u25B6 ") && fieldLabels.includes(line.slice(2))) {
-				return line.slice(2);
+			if (line.startsWith(FOCUS_INDICATOR_PREFIX) && fieldLabels.includes(line.slice(FOCUS_INDICATOR_PREFIX.length))) {
+				return line.slice(FOCUS_INDICATOR_PREFIX.length);
 			}
 			return line;
 		});
@@ -468,7 +478,7 @@ export class RuleEditorComponent extends Container {
 			{ value: "__all__", label: `${cmd} * (all subcommands)`, description: `Allow/deny all invocations of ${cmd}` },
 			{ value: "__subcmd__", label: `${cmd} <subcommand> *`, description: `Allow/deny a specific subcommand` },
 		];
-		const list = new SelectList(scopeItems, 2, this.theme);
+		const list = new SelectList(scopeItems, SCOPE_LIST_MAX_VISIBLE, this.theme);
 		list.onSelect = (item: SelectItem): void => {
 			if (item.value === "__all__") {
 				this.fillSelections.cmd = cmd;
@@ -674,7 +684,7 @@ export class RuleEditorComponent extends Container {
 			{ value: "deny", label: "deny" },
 			{ value: "ask", label: "ask" },
 		];
-		const actionList = new SelectList(actionItems, 3, this.theme);
+		const actionList = new SelectList(actionItems, ACTION_LIST_MAX_VISIBLE, this.theme);
 		actionList.onSelect = (item: SelectItem): void => {
 			this.fillSelections.action = item.value as PermissionAction;
 		};
@@ -709,7 +719,7 @@ export class RuleEditorComponent extends Container {
 			{ value: "__submit__", label: "[Submit]" },
 			{ value: "__cancel__", label: "[Cancel]" },
 		];
-		const submitList = new SelectList(submitItems, 2, this.theme);
+		const submitList = new SelectList(submitItems, SUBMIT_LIST_MAX_VISIBLE, this.theme);
 		submitList.onSelect = (item: SelectItem): void => {
 			if (item.value === "__submit__") {
 				this.commitFill();
@@ -875,8 +885,8 @@ export class RuleEditorComponent extends Container {
 	private syncCustomFocus(): void {
 		for (let i = 0; i < this.customChildren.length; i++) {
 			const child = this.customChildren[i];
-			if (child !== undefined && "focused" in child) {
-				(child as unknown as { focused: boolean }).focused = i === this.customFocusIndex;
+			if (child !== undefined && isFocusable(child)) {
+				child.focused = i === this.customFocusIndex;
 			}
 		}
 	}

package/src/rules/builtins.ts

@@ -117,6 +117,9 @@ function executableNameLookupKey(raw: string): string | undefined {
 
 // ── 合并短 flag 检查工具（G4: 合并 flag 如 -fo 需检测任意位置的 -o）──
 
+/** 短 flag 簇（`-x`）的最小长度：`-` + 至少 1 个 flag 字符。 */
+const MIN_SHORT_FLAG_CLUSTER_LENGTH = 2;
+
 /**
  * 检查短 flag 簇中是否含某个字符（如 `-fo` 含 `o`）。
  *
@@ -129,7 +132,7 @@ function executableNameLookupKey(raw: string): string | undefined {
  */
 function shortFlagClusterHasChar(arg: string, flagChar: string): boolean {
 	// 只处理短 flag 簇：单个 - 开头，非 --，长度 ≥ 2
-	if (!arg.startsWith("-") || arg.startsWith("--") || arg.length < 2) return false;
+	if (!arg.startsWith("-") || arg.startsWith("--") || arg.length < MIN_SHORT_FLAG_CLUSTER_LENGTH) return false;
 	// arg 去掉开头的 -，检查剩余字符
 	return arg.slice(1).includes(flagChar);
 }