@trim21/personal-pi-extensions 0.1.452 → 0.1.456

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.452",
+  "version": "0.1.456",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -24,6 +24,7 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "sandbox": "tsx bin/sandbox.ts",
+    "aft-search": "tsx bin/aft-search.ts",
     "build:holder": "esbuild src/bwrap/holder.ts --format=esm --target=node24 --outfile=src/bwrap/holder.js",
     "prepare": "husky"
   },
@@ -43,6 +44,7 @@
     "@types/turndown": "^5.0.6",
     "@typescript/native": "npm:typescript@^7.0.2",
     "@vitest/coverage-v8": "^4.1.10",
+    "citty": "^0.2.2",
     "esbuild": "^0.28.2",
     "eslint": "^10.8.1",
     "eslint-config-prettier": "10.1.8",

package/src/aft/bridge.ts

@@ -23,7 +23,7 @@ import {
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import type { SemanticRemote } from "./config.js";
-import { bridgeLogger } from "./logger.js";
+import { type AftLogger, createAftLogger } from "./logger.js";
 
 /** Pi 会话 ID：Rust 侧用它做 session 作用域（undo/checkpoint），感知工具可留空。 */
 export function resolveSessionId(extCtx: ExtensionContext): string | undefined {
@@ -55,6 +55,23 @@ export interface AftPool {
   projectRoot: string;
 }
 
+/** 一次 session 生命周期内的 bridge 状态：日志落盘 + 常驻 aft 子进程。 */
+export interface AftState {
+  logger: AftLogger;
+  pool: AftPool;
+}
+
+/** 创建一份 session 级 bridge 状态；日志落在 tmp/{sessionId}/aft-plugin.log。 */
+export async function createAftState(
+  cwd: string,
+  sessionId: string | undefined,
+  semantic?: SemanticRemote,
+): Promise<AftState> {
+  const logger = createAftLogger(sessionId);
+  const pool = await createAftPool(cwd, logger, semantic);
+  return { logger, pool };
+}
+
 /** semantic_search 等待索引构建完成的上限（与 Rust 侧 AFT_WAIT_FOR_SEMANTIC_READY_MS 一致）。 */
 export const SEMANTIC_INDEX_WAIT_TIMEOUT_MS = 600_000;
 
@@ -79,10 +96,14 @@ export const SEMANTIC_API_KEY_ENV = "AFT_SEMANTIC_API_KEY";
  * 这个「变量名」，再自己 `env::var` 取值，所以提供值时必须连带把名字告诉它。
  * 两者都缺省时不注入任何凭据（无鉴权端点直接可用）。
  */
-export async function createAftPool(cwd: string, semantic?: SemanticRemote): Promise<AftPool> {
+export async function createAftPool(
+  cwd: string,
+  logger: AftLogger,
+  semantic?: SemanticRemote,
+): Promise<AftPool> {
   // 必须在任何 bridge 代码运行前注册：不设 logger 时 aft-bridge 会把 child
   // stderr / 生命周期日志 fallback 到 console.error，raw 输出打进 pi 的 stderr 破坏 TUI。
-  setActiveLogger(bridgeLogger);
+  setActiveLogger(logger);
   const binaryPath = await resolveAftBinary();
   const paths = resolveCortexKitConfigPaths(cwd);
   const childEnv: Record<string, string> = {
@@ -114,7 +135,7 @@ export async function createAftPool(cwd: string, semantic?: SemanticRemote): Pro
   const pool = await createAftTransportPool({
     harness: "pi",
     binaryPath,
-    poolOptions: { childEnv, logger: bridgeLogger },
+    poolOptions: { childEnv, logger },
     configOverrides: {
       storage_dir: resolveCortexKitStorageRoot(),
       cortexkit_user_config_path: paths.userConfigPath,

package/src/aft/imports.ts

@@ -15,7 +15,13 @@ import { Type } from "typebox";
 import { type ToolPendant } from "../lib/pendant.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { callAftTool } from "./bridge.js";
-import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+import {
+  type AftToolContext,
+  bridgeFor,
+  buildPendantMarkdown,
+  compactArgs,
+  resolvePathArg,
+} from "./tools.js";
 
 /** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
 const IMPORT_PROMPT = readFileSync(
@@ -101,19 +107,20 @@ export function registerImportTool(pi: ExtensionAPI, ctx: AftToolContext): void
       const filePath = resolvePathArg(extCtx.cwd, params.path);
       await guardWriteAccess(extCtx, { toolName: "aft_import", absolutePath: filePath });
 
-      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
-      if (params.module !== undefined && params.module.trim() !== "") {
-        rawArgs.module = params.module;
-      }
-      if (params.names !== undefined) rawArgs.names = params.names;
-      if (params.default_import !== undefined) rawArgs.defaultImport = params.default_import;
-      if (params.namespace !== undefined) rawArgs.namespace = params.namespace;
-      if (params.alias !== undefined) rawArgs.alias = params.alias;
-      if (params.modifiers !== undefined) rawArgs.modifiers = params.modifiers;
-      if (params.import_kind !== undefined) rawArgs.importKind = params.import_kind;
-      if (params.remove_name !== undefined) rawArgs.removeName = params.remove_name;
-      if (params.type_only !== undefined) rawArgs.typeOnly = params.type_only;
-      if (params.validate !== undefined) rawArgs.validate = params.validate;
+      const rawArgs = compactArgs({
+        op: params.op,
+        path: filePath,
+        module: params.module,
+        names: params.names,
+        defaultImport: params.default_import,
+        namespace: params.namespace,
+        alias: params.alias,
+        modifiers: params.modifiers,
+        importKind: params.import_kind,
+        removeName: params.remove_name,
+        typeOnly: params.type_only,
+        validate: params.validate,
+      });
 
       const { text } = await callAftTool(bridgeFor(ctx), "import", rawArgs, extCtx);
       return {

package/src/aft/index.ts

@@ -9,8 +9,10 @@
  * fastembed 后端不使用。aft_refactor / aft_import 的 Rust 命令不支持 preview，
  * 写保护退化为路径级审批。
  *
- * 二进制缺失或 pool 创建失败时降级：不注册任何工具并在 session 开始时报
- * 一次错，而不是让每个工具调用失败。
+ * bridge 状态（日志 + 常驻 aft 子进程）的生命周期跟 session 走：session_start
+ * 时用当次 session id 创建（日志落在 tmp/{sessionId}/aft-plugin.log），
+ * session_shutdown / 进程退出时释放。工具实现经 getState() 取状态，
+ * session 未初始化时抛错。
  *
  * Usage:
  *   pi -e ./aft/index.ts
@@ -19,7 +21,7 @@
 import { resolveCortexKitConfigPaths } from "@cortexkit/aft-bridge";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { type AftPool, createAftPool, shutdownAftPool } from "./bridge.js";
+import { createAftState, resolveSessionId, shutdownAftPool } from "./bridge.js";
 import { loadAftConfig } from "./config.js";
 import { registerImportTool } from "./imports.js";
 import { registerRefactorTool } from "./refactor.js";
@@ -30,26 +32,30 @@ import {
   registerZoomTool,
 } from "./tools.js";
 
-export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
+export default function aftReadTools(pi: ExtensionAPI): void {
   const cwd = process.cwd();
   const cfg = loadAftConfig(resolveCortexKitConfigPaths(cwd).userConfigPath);
   if (!cfg.enabled) return;
 
-  let pool: AftPool;
-  try {
-    pool = await createAftPool(cwd, cfg.semanticRemote);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    pi.on("session_start", (_event, ctx) => {
-      ctx.ui.notify(
-        `AFT tools are disabled: ${message}. Install @cortexkit/aft-<platform> via your npm mirror (locked to the same version as @cortexkit/aft-bridge), then reload.`,
-        "error",
+  // bridge 状态跟 session 生命周期走，作用域就是本工厂闭包，不落到模块级。
+  let state: Awaited<ReturnType<typeof createAftState>> | null = null;
+
+  // 预热：提前解析二进制并拉起 bridge 子进程；失败直接抛给 pi（runner 捕获
+  // 后上报 ExtensionError），工具调用侧经 getState() 抛未初始化错误。
+  pi.on("session_start", async (_event, ctx) => {
+    state = await createAftState(cwd, resolveSessionId(ctx), cfg.semanticRemote);
+  });
+
+  const getState = (): Awaited<ReturnType<typeof createAftState>> => {
+    if (!state) {
+      throw new Error(
+        "AFT is not initialized for this session (no session_start event has fired yet)",
       );
-    });
-    return;
-  }
+    }
+    return state;
+  };
 
-  const toolCtx = { cwd, pool: pool.pool };
+  const toolCtx = { cwd, getState };
   registerOutlineTool(pi, toolCtx);
   registerZoomTool(pi, toolCtx);
   registerCallgraphTool(pi, toolCtx);
@@ -69,16 +75,18 @@ export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
     }
   }
 
-  // 关闭 bridge pool。session_shutdown 是 pi 的正常生命周期；beforeExit 兜底
-  // 进程自然退出（不能注册 SIGINT/SIGTERM——那会吞掉 pi 主进程自己的信号处理）。
-  let shuttingDown = false;
+  // 释放当前 session 的 bridge 状态。session_shutdown 是 pi 的正常生命周期；
+  // beforeExit 兜底进程自然退出（不能注册 SIGINT/SIGTERM——那会吞掉 pi 主进程
+  // 自己的信号处理）。释放后下个 session_start 用新 session id 重建。
   const shutdown = async (): Promise<void> => {
-    if (shuttingDown) return;
-    shuttingDown = true;
+    const current = state;
+    state = null;
+    if (!current) return;
     try {
-      await shutdownAftPool(pool);
+      await shutdownAftPool(current.pool);
+      await current.logger.drain();
     } catch {
-      // 关闭失败不影响退出流程
+      // 释放失败不影响退出流程
     }
   };
   process.once("beforeExit", () => void shutdown());

package/src/aft/logger.ts

@@ -1,5 +1,5 @@
 /**
- * AFT 扩展日志：落盘到 agent dir 的 tmp/（<agentDir>/tmp/aft-plugin.log）。
+ * AFT 扩展日志：落盘到 agent dir 的 tmp/{sessionId}/（<agentDir>/tmp/<sessionId>/aft-plugin.log）。
  *
  * aft-bridge 会把 aft 子进程的 stderr 逐行转发给 logger；不设置 logger 时它
  * fallback 到 console.error，raw 文本直接打进 pi 进程的 stderr，破坏 TUI。
@@ -15,15 +15,27 @@ const TAG = "[aft-pi]";
 const FLUSH_INTERVAL_MS = 500;
 const BUFFER_SIZE_LIMIT = 50;
 
-function logFilePath(): string {
-  return join(getAgentDir(), "tmp", "aft-plugin.log");
+/** aft-bridge 的 Logger 接口 + drain。 */
+export interface AftLogger {
+  log(message: string, meta?: { sessionId?: string }): void;
+  warn(message: string, meta?: { sessionId?: string }): void;
+  error(message: string, meta?: { sessionId?: string }): void;
+  getLogFilePath(): string;
+  /** 立即落盘，供测试与关闭路径使用。 */
+  drain(): Promise<void>;
 }
 
-function createLogger() {
+export function createAftLogger(sessionId?: string): AftLogger {
   let sink: RotatingLogSink | null = null;
   let buffer: string[] = [];
   let flushTimer: ReturnType<typeof setTimeout> | null = null;
 
+  function logFilePath(): string {
+    return sessionId
+      ? join(getAgentDir(), "tmp", sessionId, "aft-plugin.log")
+      : join(getAgentDir(), "tmp", "aft-plugin.log");
+  }
+
   // sink 懒创建：getAgentDir() 读 PI_CODING_AGENT_DIR，测试里先改 env 再触发写入。
   function getSink(): RotatingLogSink {
     sink ??= new RotatingLogSink(logFilePath());
@@ -52,10 +64,10 @@ function createLogger() {
     }
   }
 
-  function write(level: string, message: string, sessionId?: string): void {
+  function write(level: string, message: string, lineSessionId?: string): void {
     try {
       const timestamp = new Date().toISOString();
-      const sessionPrefix = sessionId ? ` [${sessionId}]` : "";
+      const sessionPrefix = lineSessionId ? ` [${lineSessionId}]` : "";
       buffer.push(`[${timestamp}] ${level} ${TAG}${sessionPrefix} ${message}\n`);
       if (buffer.length >= BUFFER_SIZE_LIMIT) {
         flush();
@@ -68,9 +80,15 @@ function createLogger() {
   }
 
   return {
-    log: (message: string, sessionId?: string): void => write("INFO", message, sessionId),
-    warn: (message: string, sessionId?: string): void => write("WARN", message, sessionId),
-    error: (message: string, sessionId?: string): void => write("ERROR", message, sessionId),
+    log(message, meta) {
+      write("INFO", message, meta?.sessionId);
+    },
+    warn(message, meta) {
+      write("WARN", message, meta?.sessionId);
+    },
+    error(message, meta) {
+      write("ERROR", message, meta?.sessionId);
+    },
     getLogFilePath: logFilePath,
     drain: async (): Promise<void> => {
       flush();
@@ -78,40 +96,3 @@ function createLogger() {
     },
   };
 }
-
-const logger = createLogger();
-
-export function log(message: string): void {
-  logger.log(message);
-}
-
-export function warn(message: string): void {
-  logger.warn(message);
-}
-
-export function error(message: string): void {
-  logger.error(message);
-}
-
-export function getLogFilePath(): string {
-  return logger.getLogFilePath();
-}
-
-/** aft-bridge 的 Logger 适配：child stderr / bridge 生命周期日志都走这里。 */
-export const bridgeLogger = {
-  log(message: string, meta?: { sessionId?: string }): void {
-    logger.log(message, meta?.sessionId);
-  },
-  warn(message: string, meta?: { sessionId?: string }): void {
-    logger.warn(message, meta?.sessionId);
-  },
-  error(message: string, meta?: { sessionId?: string }): void {
-    logger.error(message, meta?.sessionId);
-  },
-  getLogFilePath: (): string => logger.getLogFilePath(),
-};
-
-/** 立即落盘，供测试与关闭路径使用。 */
-export async function drainLogger(): Promise<void> {
-  await logger.drain();
-}

package/src/aft/refactor.ts

@@ -17,7 +17,13 @@ import { Type } from "typebox";
 import { type ToolPendant } from "../lib/pendant.js";
 import { guardWriteAccess } from "../lib/write-guard.js";
 import { callAftTool } from "./bridge.js";
-import { type AftToolContext, bridgeFor, buildPendantMarkdown, resolvePathArg } from "./tools.js";
+import {
+  type AftToolContext,
+  bridgeFor,
+  buildPendantMarkdown,
+  compactArgs,
+  resolvePathArg,
+} from "./tools.js";
 
 /** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
 const REFACTOR_PROMPT = readFileSync(
@@ -118,20 +124,17 @@ export function registerRefactorTool(pi: ExtensionAPI, ctx: AftToolContext): voi
         await guardWriteAccess(extCtx, { toolName: "aft_refactor", absolutePath: target });
       }
 
-      const rawArgs: Record<string, unknown> = { op: params.op, path: filePath };
-      if (params.symbol !== undefined && params.symbol.trim() !== "") {
-        rawArgs.symbol = params.symbol;
-      }
-      if (destination !== undefined) rawArgs.destination = destination;
-      if (params.scope !== undefined && params.scope.trim() !== "") {
-        rawArgs.scope = params.scope;
-      }
-      if (params.name !== undefined && params.name.trim() !== "") {
-        rawArgs.name = params.name;
-      }
-      if (startLine !== undefined) rawArgs.startLine = startLine;
-      if (endLine !== undefined) rawArgs.endLine = endLine;
-      if (callSiteLine !== undefined) rawArgs.callSiteLine = callSiteLine;
+      const rawArgs = compactArgs({
+        op: params.op,
+        path: filePath,
+        symbol: params.symbol,
+        destination,
+        scope: params.scope,
+        name: params.name,
+        startLine,
+        endLine,
+        callSiteLine,
+      });
 
       const { text } = await callAftTool(bridgeFor(ctx), "refactor", rawArgs, extCtx);
       return {

package/src/aft/tools.ts

@@ -13,7 +13,6 @@ import { fileURLToPath } from "node:url";
 
 import {
   type AftProjectTransport,
-  type AftTransportPool,
   coerceBoolean,
   coerceOptionalInt,
   coerceTargetParam,
@@ -25,7 +24,7 @@ import { Type } from "typebox";
 
 import { formatDisplayPath, formatSubtitlePath } from "../lib/path.js";
 import { type ToolPendant } from "../lib/pendant.js";
-import { callAftTool, SEMANTIC_INDEX_WAIT_TIMEOUT_MS } from "./bridge.js";
+import { type AftState, callAftTool, SEMANTIC_INDEX_WAIT_TIMEOUT_MS } from "./bridge.js";
 
 /** 工具使用指南，以 markdown 形式维护，读起来像文档。 */
 const OUTLINE_PROMPT = readFileSync(
@@ -53,11 +52,25 @@ export function resolvePathArg(cwd: string, input: string): string {
 
 export interface AftToolContext {
   cwd: string;
-  pool: AftTransportPool;
+  /** 当前 session 的 bridge 状态；session 未初始化时抛错。 */
+  getState(): AftState;
 }
 
 export function bridgeFor(ctx: AftToolContext): AftProjectTransport {
-  return ctx.pool.getBridge(ctx.cwd);
+  return ctx.getState().pool.pool.getBridge(ctx.cwd);
+}
+
+/**
+ * 丢弃 undefined 与空白字符串字段：bridge 参数经 JSON.stringify 发给 Rust 侧，
+ * 「缺 key」与「空字符串」在 Rust 端语义不同，这里把空串统一归一成缺省。
+ * false / 空数组等是合法取值，保留。
+ */
+export function compactArgs(args: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(args).filter(
+      ([, value]) => value !== undefined && !(typeof value === "string" && value.trim() === ""),
+    ),
+  );
 }
 
 /** 人类视角的调用记录：input params + 与 LLM 相同的输出结果。 */
@@ -132,11 +145,11 @@ export function registerOutlineTool(pi: ExtensionAPI, ctx: AftToolContext): void
         const stats = await stat(resolved).catch(() => null);
         filesMode = stats?.isDirectory() ?? false;
       }
-      const rawArgs: Record<string, unknown> = {
+      const rawArgs = compactArgs({
         target: filesMode ? target : resolved,
-      };
-      if (filesMode) rawArgs.files = true;
-      if (params.includeTests !== undefined) rawArgs.includeTests = params.includeTests;
+        files: filesMode ? true : undefined,
+        includeTests: params.includeTests,
+      });
 
       const subtitle = buildOutlineSubtitle(extCtx.cwd, target);
 
@@ -198,19 +211,17 @@ export function registerZoomTool(pi: ExtensionAPI, ctx: AftToolContext): void {
     promptGuidelines: [ZOOM_PROMPT],
     parameters: ZoomParams,
     async execute(_id, params, _signal, _onUpdate, extCtx) {
-      const rawArgs: Record<string, unknown> = {
+      const rawArgs = compactArgs({
         filePath: resolvePathArg(extCtx.cwd, params.path),
-        ...(params.symbols && { symbols: params.symbols }),
-      };
-
-      const contextLines = coerceOptionalInt(
-        params.contextLines,
-        "contextLines",
-        1,
-        Number.MAX_SAFE_INTEGER,
-      );
-      if (contextLines !== undefined) rawArgs.contextLines = contextLines;
-      if (coerceBoolean(params.callgraph)) rawArgs.callgraph = true;
+        symbols: params.symbols,
+        contextLines: coerceOptionalInt(
+          params.contextLines,
+          "contextLines",
+          1,
+          Number.MAX_SAFE_INTEGER,
+        ),
+        callgraph: coerceBoolean(params.callgraph) ? true : undefined,
+      });
 
       const subtitle = buildZoomSubtitle(extCtx.cwd, params);
 
@@ -305,26 +316,17 @@ export function registerCallgraphTool(pi: ExtensionAPI, ctx: AftToolContext): vo
     promptGuidelines: [CALLGRAPH_PROMPT],
     parameters: CallgraphParams,
     async execute(_id, params, _signal, _onUpdate, extCtx) {
-      const rawArgs: Record<string, unknown> = {
+      const rawArgs = compactArgs({
         op: params.op,
         filePath: resolvePathArg(extCtx.cwd, params.path),
         symbol: params.symbol,
-      };
-      const depth = coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER);
-      if (depth !== undefined) rawArgs.depth = depth;
-      if (params.expression !== undefined && params.expression !== "") {
-        rawArgs.expression = params.expression;
-      }
-      if (params.toSymbol !== undefined && params.toSymbol !== "") {
-        rawArgs.toSymbol = params.toSymbol;
-      }
-      if (params.toPath !== undefined && params.toPath !== "") {
-        rawArgs.toFile = resolvePathArg(extCtx.cwd, params.toPath);
-      }
-      if (params.includeTests !== undefined) rawArgs.includeTests = params.includeTests;
-      if (params.includeUnresolved !== undefined) {
-        rawArgs.includeUnresolved = params.includeUnresolved;
-      }
+        depth: coerceOptionalInt(params.depth, "depth", 1, Number.MAX_SAFE_INTEGER),
+        expression: params.expression,
+        toSymbol: params.toSymbol,
+        toFile: params.toPath ? resolvePathArg(extCtx.cwd, params.toPath) : undefined,
+        includeTests: params.includeTests,
+        includeUnresolved: params.includeUnresolved,
+      });
 
       const { text, response } = await callAftTool(
         bridgeFor(ctx),
@@ -398,12 +400,12 @@ export function registerSearchTool(pi: ExtensionAPI, ctx: AftToolContext): void
       if (typeof params.query !== "string" || params.query.trim().length === 0) {
         throw new Error("'query' must be a non-empty string");
       }
-      const rawArgs: Record<string, unknown> = { query: params.query };
-      if (params.topK !== undefined) rawArgs.topK = params.topK;
-      if (params.includeTests !== undefined) rawArgs.includeTests = params.includeTests;
-      if (params.path !== undefined && params.path !== "") {
-        rawArgs.path = resolvePathArg(extCtx.cwd, params.path);
-      }
+      const rawArgs = compactArgs({
+        query: params.query,
+        topK: params.topK,
+        includeTests: params.includeTests,
+        path: params.path ? resolvePathArg(extCtx.cwd, params.path) : undefined,
+      });
 
       const { text, response } = await callAftTool(bridgeFor(ctx), "search", rawArgs, extCtx, {
         // 默认 search 传输超时仅 60s，会早于索引等待（600s）触发；覆盖为等待

package/src/bwrap/holder.js

@@ -1,12 +1,11 @@
 import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 const args = process.argv.slice(2);
 const configBase64 = args[0];
 const mihomoPath = args[1];
-const slirp4netnsPath = args[2];
-const tunMtu = Number(args[3]);
-if (!configBase64 || !mihomoPath || !slirp4netnsPath || !tunMtu) {
+const tunMtu = Number(args[2]);
+const mihomoHome = args[3];
+if (!configBase64 || !mihomoPath || !tunMtu || !mihomoHome) {
   process.exit(2);
 }
 process.chdir("/");
@@ -27,16 +26,8 @@ async function waitFor(attempts, delayMs, predicate) {
 async function main() {
   process.stdin.resume();
   process.stdin.on("end", () => process.exit(0));
-  const status = await readFile("/proc/self/status", "utf8");
-  const hostPid = /^NSpid:\s+(.+)$/m.exec(status)?.[1].split(/\s+/, 1)[0];
-  if (!hostPid) {
-    throw new Error("Failed to resolve host pid from NSpid");
-  }
-  spawn(slirp4netnsPath, ["-c", `--mtu=${tunMtu}`, "--netns-type=pid", hostPid, "tap0"], {
-    stdio: ["ignore", "inherit", "inherit"]
-  });
   await waitFor(100, 100, tap0Exists);
-  const mihomo = spawn(mihomoPath, ["-config", configBase64], {
+  const mihomo = spawn(mihomoPath, ["-d", mihomoHome, "-config", configBase64], {
     stdio: ["ignore", "inherit", "inherit"]
   });
   const stop = () => {

package/src/bwrap/holder.ts

@@ -1,17 +1,19 @@
 /* eslint-disable no-console, unicorn/no-process-exit -- 独立 CLI 脚本，由 unshare 直接执行 */
 import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 
-// 用法：unshare -Urnp --fork --kill-child node holder.ts <config-base64> <mihomo> <slirp4netns> <mtu>
+// 用法：unshare -Urnp --fork --kill-child node holder.ts <config-base64> <mihomo> <mtu> <mihomo-home-dir>
 // 本进程是 pid namespace 的 init：无论以何种方式退出（含 SIGKILL），内核都会清理该 pid ns 内的
-// slirp4netns / mihomo，userns/netns 引用随之归零。
+// mihomo，userns/netns 引用随之归零。slirp4netns 由宿主侧启动（egress 必须留在宿主 netns，
+// 否则出站流量会绕回 mihomo 的 TUN 被 dns-hijack 自劫持），它通过 exit-fd 绑定本进程的生命周期：
+// fd 3 是 exit-fd 的写端（network-stack 经 unshare 传入），本进程存活期间保持打开，死亡即关闭，
+// slirp4netns 侧收到 HUP 自行退出并释放 tap fd，netns 引用随之归零。
 const args = process.argv.slice(2);
 const configBase64 = args[0];
 const mihomoPath = args[1];
-const slirp4netnsPath = args[2];
-const tunMtu = Number(args[3]);
-if (!configBase64 || !mihomoPath || !slirp4netnsPath || !tunMtu) {
+const tunMtu = Number(args[2]);
+const mihomoHome = args[3];
+if (!configBase64 || !mihomoPath || !tunMtu || !mihomoHome) {
   process.exit(2);
 }
 
@@ -40,28 +42,15 @@ async function waitFor(
 
 async function main(): Promise<void> {
   // 宿主（pi）进程死亡检测：宿主以任何方式退出（含 SIGKILL）都会关闭它持有的 stdin 写端，
-  // 这里读到 EOF 即自杀（init 退出即触发内核清理整个 pid ns）。
+  // 这里读到 EOF 即自杀（init 退出即触发内核清理整个 pid ns，顺带关闭 exit-fd 写端）。
   process.stdin.resume();
   process.stdin.on("end", () => process.exit(0));
 
-  // 宿主视角 pid（NSpid 第一项）：/proc 挂载是宿主的（-Urnp 不含 -m，宿主视角下
-  // /proc/1 是 systemd 而非本 pid ns 的 init），slirp4netns 的 setns 必须走宿主 /proc
-  const status = await readFile("/proc/self/status", "utf8");
-  const hostPid = /^NSpid:\s+(.+)$/m.exec(status)?.[1].split(/\s+/, 1)[0];
-  if (!hostPid) {
-    throw new Error("Failed to resolve host pid from NSpid");
-  }
-
-  // slirp4netns 提供 egress：本进程已在目标 userns/netns 内，setns 到自身 netns（no-op）；
-  // 日志 inherit 到 holder 的 stdout/stderr，宿主侧诊断（--verbose）可见
-  spawn(slirp4netnsPath, ["-c", `--mtu=${tunMtu}`, "--netns-type=pid", hostPid, "tap0"], {
-    stdio: ["ignore", "inherit", "inherit"],
-  });
-
-  // mihomo 日志透传到 holder 的 stdout/stderr，宿主侧监听 "Tun adapter listening" 判定就绪
+  // tap0 由宿主侧的 slirp4netns（fork 进本 netns）创建，就绪后再拉起 mihomo。
+  // mihomo 日志透传到 holder 的 stdout/stderr，宿主侧监听 "Tun adapter listening" 判定就绪。
   await waitFor(100, 100, tap0Exists);
 
-  const mihomo = spawn(mihomoPath, ["-config", configBase64], {
+  const mihomo = spawn(mihomoPath, ["-d", mihomoHome, "-config", configBase64], {
     stdio: ["ignore", "inherit", "inherit"],
   });
 

package/src/bwrap/mihomo-config.ts

@@ -20,6 +20,8 @@ export interface MihomoConfig {
   mode: "rule";
   "log-level": "info";
   ipv6: false;
+  /** 出站静态绑定 slirp 接口（固定名 tap0）。 */
+  "interface-name": string;
   dns: {
     enable: true;
     ipv6: false;
@@ -173,6 +175,11 @@ export function generateMihomoConfig(options: MihomoConfigOptions): MihomoConfig
     mode: "rule",
     "log-level": "info",
     ipv6: false,
+    // 静态绑定 tap0：auto-detect-interface 在启动瞬间可能探测到未就绪的接口
+    //（tap0 尚由 slirp4netns 创建），monitor 事后纠正但 DNS 拨号已经走错接口，
+    // 上游查询进自己的 TUN 被 dns-hijack 自劫持形成回环（allowlist 域名全部
+    // SERVFAIL）。slirp 接口名固定是 tap0，直接写死最可靠。
+    "interface-name": "tap0",
     dns: {
       enable: true,
       ipv6: false,

package/src/bwrap/network-stack.ts

@@ -1,7 +1,11 @@
 import { type ChildProcess, spawn } from "node:child_process";
-import { readFile, readlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readlink } from "node:fs/promises";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 import { forEachLine } from "../lib/proc.js";
 import { generateMihomoConfig, TUN_MTU } from "./mihomo-config.js";
 
@@ -178,12 +182,15 @@ export interface NetworkStack {
 
 interface NetworkStackState {
   holderPid: number;
+  slirpPid: number;
 }
 
 /** 兜底：调用方忘记 stop() 时，对象被 GC 回收后 kill 残留进程。 */
 const stackFinalizer = new FinalizationRegistry<NetworkStackState>((state) => {
-  // SIGTERM 经 unshare --kill-child 转发给 init，内核清理 pid ns 内全部进程
+  // SIGTERM 经 unshare --kill-child 转发给 init，内核清理 pid ns 内全部进程；
+  // slirp4netns 在宿主侧持有 tap fd，单独终止
   killProcess(state.holderPid);
+  killProcess(state.slirpPid);
 });
 
 /**
@@ -203,10 +210,17 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
   const config = generateMihomoConfig({ allowlist, dnsServers });
   const configBase64 = Buffer.from(JSON.stringify(config)).toString("base64");
 
+  // mihomo 工作目录（-d）：cache.db 等落在这里，而不是它默认的 ~/.config/mihomo/
+  //（后者不存在时 mihomo 每次启动都告警且 fakeip 映射无持久化）。每次启动用独立
+  // uuid 目录，避免并发的多个 holder 争抢 bbolt 文件锁。
+  const mihomoHome = join(getAgentDir(), "tmp", `mihomo-${randomUUID()}`);
+  await mkdir(mihomoHome, { recursive: true });
+
   let holder: ChildProcess | undefined;
+  let slirp: ChildProcess | undefined;
   try {
     // unshare -p --fork：node 成为 pid namespace 的 init，任何方式退出（含 SIGKILL）
-    // 内核都会清理 pid ns 内全部进程（slirp4netns/mihomo），ns 引用随之归零；
+    // 内核都会清理 pid ns 内全部进程（mihomo），ns 引用随之归零；
     // --kill-child=SIGTERM：宿主侧 SIGTERM unshare 时转发给 init 走优雅退出
     holder = spawn(
       "unshare",
@@ -219,8 +233,8 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
         HOLDER_PATH,
         configBase64,
         mihomoPath,
-        slirp4netnsPath,
         String(TUN_MTU),
+        mihomoHome,
       ],
       {
         env: {
@@ -228,8 +242,9 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
           PATH: `${process.env.PATH ?? ""}:${SBIN_PATH_SUFFIX}`,
         },
         // stdin 保持 pipe：本进程持有写端，进程退出（含 SIGKILL）时内核关闭 fd，
-        // holder 读到 EOF 即自杀（init 退出 → 内核清理 pid ns）
-        stdio: ["pipe", "pipe", "pipe"],
+        // holder 读到 EOF 即自杀（init 退出 → 内核清理 pid ns）。
+        // fd 3：exit-fd 写端，传给 holder 持有（holder 死亡 → 读端 HUP → slirp4netns 退出）。
+        stdio: ["pipe", "pipe", "pipe", "pipe"],
       },
     );
     forwardOutput(holder, holderOutput);
@@ -239,9 +254,45 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
     const holderPid = holder.pid;
     await waitForNewUserns(holderPid);
 
+    // slirp4netns 提供 egress，必须在宿主 netns 启动：它的 egress socket 决定出站
+    // 视角，留在沙盒 netns 里会被 mihomo 的 TUN 策略路由 + dns-hijack 自劫持成环
+    //（上游 DNS 查询自己劫自己，allowlist 域名全部 SERVFAIL）。tap fd 会被它持有
+    // 而 pin 住 netns，因此用 exit-fd（holder 的 fd 3 写端的读端）绑定 holder 生命
+    // 周期：holder 退出 → 读端 HUP → slirp4netns 退出 → tap fd 释放。
+    // --userns-path / --netns-type=pid 都指向 unshare 进程：它创建并持有目标
+    // userns/netns（node holder 是它的子进程，同 ns）。
+    // exit-fd 的读端 fd：从 holder 的额外 stdio pipe 取父进程侧的原始 fd。
+    // Node 没有公开 API 拿它（stdio[3].fd 恒为 undefined，只能读 _handle，且仅在
+    // 子进程存活期间有效）；pipe 要跨两个子进程共享（holder 持写端、slirp4netns
+    // 持读端），所以必须把父进程侧的 fd 重新 dup 给 slirp4netns。
+    const exitReadFd = (holder.stdio[3] as unknown as { _handle?: { fd?: number } } | null)?._handle
+      ?.fd;
+    if (typeof exitReadFd !== "number") {
+      throw new TypeError("Failed to resolve exit-fd from holder stdio");
+    }
+    slirp = spawn(
+      slirp4netnsPath,
+      [
+        "-c",
+        `--mtu=${TUN_MTU}`,
+        `--userns-path=/proc/${String(holderPid)}/ns/user`,
+        "--netns-type=pid",
+        String(holderPid),
+        "tap0",
+        // exit-fd：本子进程的 fd 3（stdio 第 4 项 dup 为 fd 3）
+        "-e",
+        "3",
+      ],
+      { stdio: ["ignore", "pipe", "pipe", exitReadFd] },
+    );
+    forwardOutput(slirp, holderOutput);
+    if (slirp.pid === undefined) {
+      throw new Error("Failed to start slirp4netns");
+    }
+
     await waitForMihomoStarted(holder);
 
-    const state: NetworkStackState = { holderPid };
+    const state: NetworkStackState = { holderPid, slirpPid: slirp.pid };
     const stack: NetworkStack = {
       exec: async (execOptions: NetworkStackExecOptions) => {
         const child = spawn(
@@ -311,10 +362,14 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
       },
       stop: async () => {
         const children = await readChildPids(state.holderPid);
+        // slirp4netns 持有 tap fd（pin 住 netns），必须随 holder 一起显式终止；
+        // 先杀它再杀 holder，避免 stop() 与 exit-fd HUP 的收尾时序竞争
+        killProcess(state.slirpPid);
         // SIGTERM unshare → --kill-child 转发 SIGTERM 给 init（pid ns 的 pid 1），
         // init 优雅停 mihomo 后退出，内核清理 pid ns 内全部进程，ns 引用随之归零
         killProcess(state.holderPid);
         await waitForExit(state.holderPid);
+        await waitForExit(state.slirpPid);
         // 兜底：init 未在超时内退出 → SIGKILL init → 内核清 pid ns
         for (const pid of children) {
           killProcess(pid, "SIGKILL");
@@ -326,7 +381,11 @@ export async function startNetworkStack(options: NetworkStackOptions): Promise<N
     return stack;
   } catch (error) {
     // 失败清理：holder（unshare）的 SIGTERM 经 --kill-child 转发给 init，
-    // init 退出时内核清理 pid ns 内全部进程；调用方拿不到 stack，这里只能靠自己
+    // init 退出时内核清理 pid ns 内全部进程；slirp4netns 在宿主侧，需单独终止
+    //（exit-fd 写端也会随 holder 死亡关闭，这里主动杀只是不等到 HUP 轮询）
+    if (slirp?.pid) {
+      killProcess(slirp.pid);
+    }
     if (holder?.pid) {
       const children = await readChildPids(holder.pid);
       killProcess(holder.pid);

package/src/lib/lsp/client.ts

@@ -31,6 +31,18 @@ const FILE_CHANGE_CHANGED = 2;
 const FILE_CHANGE_DELETED = 3;
 const TEXT_DOCUMENT_SYNC_INCREMENTAL = 2;
 
+/** LSP WatchKind 位掩码（FileSystemWatcher.kind，缺省 create|change|delete）。 */
+export const WATCH_KIND_CREATE = 1;
+export const WATCH_KIND_CHANGE = 2;
+export const WATCH_KIND_DELETE = 4;
+const WATCH_KIND_ALL = WATCH_KIND_CREATE | WATCH_KIND_CHANGE | WATCH_KIND_DELETE;
+
+/** 服务器通过 client/registerCapability 注册的单个 watcher。 */
+export interface WatcherGlob {
+  pattern: string;
+  kind: number;
+}
+
 const FILE_CHANGE_TYPE: Record<FileChangeType, number> = {
   created: FILE_CHANGE_CREATED,
   changed: FILE_CHANGE_CHANGED,
@@ -77,7 +89,7 @@ interface CapabilityRegistration {
   registerOptions?: {
     identifier?: string;
     workspaceDiagnostics?: boolean;
-    watchers?: { globPattern?: string }[];
+    watchers?: { globPattern?: string; kind?: number }[];
   };
 }
 
@@ -115,8 +127,8 @@ export interface LspClient {
     /** 把工作区文件事件批量通知服务器；驻留文档不在此通道（走 didOpen/didChange/退场）。 */
     watchedFiles(changes: FileChange[]): Promise<void>;
   };
-  /** 服务器注册的 workspace/didChangeWatchedFiles watchers glob（去重）。 */
-  watchPatterns(): string[];
+  /** 服务器注册的 workspace/didChangeWatchedFiles watchers（pattern + kind，按 pattern+kind 去重）。 */
+  watchers(): WatcherGlob[];
   readonly diagnostics: Map<string, Diagnostic[]>;
   waitForDiagnostics(request: {
     path: string;
@@ -247,8 +259,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
   const pullDiagnostics = new Map<string, Diagnostic[]>();
   const published = new Map<string, { at: number; version?: number }>();
   const diagnosticRegistrations = new Map<string, CapabilityRegistration>();
-  /** registration id → workspace/didChangeWatchedFiles watchers glob。 */
-  const watcherRegistrations = new Map<string, string[]>();
+  /** registration id → workspace/didChangeWatchedFiles watchers（pattern + WatchKind 位）。 */
+  const watcherRegistrations = new Map<string, WatcherGlob[]>();
   const registrationListeners = new Set<() => void>();
   const diagnosticListeners = new Set<(input: { path: string; serverID: string }) => void>();
   /** resolvedPath → 客户端已发送的最新文档版本（didOpen=0，didChange 递增）。 */
@@ -307,8 +319,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
       if (registration.method === "workspace/didChangeWatchedFiles") {
         const watchers =
           registration.registerOptions?.watchers
-            ?.map((watcher) => watcher.globPattern)
-            .filter((pattern): pattern is string => typeof pattern === "string") ?? [];
+            ?.map((watcher) => ({
+              pattern: watcher.globPattern,
+              kind: watcher.kind ?? WATCH_KIND_ALL,
+            }))
+            .filter((watcher): watcher is WatcherGlob => typeof watcher.pattern === "string") ?? [];
         watcherRegistrations.set(registration.id, watchers);
       } else if (registration.method === "textDocument/diagnostic") {
         diagnosticRegistrations.set(registration.id, registration);
@@ -754,8 +769,15 @@ export async function create(input: CreateInput): Promise<LspClient> {
     get serverID() {
       return input.serverID;
     },
-    watchPatterns(): string[] {
-      return [...new Set([...watcherRegistrations.values()].flat())];
+    watchers(): WatcherGlob[] {
+      return [
+        ...new Set(
+          [...watcherRegistrations.values()].flat().map((w) => JSON.stringify([w.pattern, w.kind])),
+        ),
+      ].map((key) => {
+        const [pattern, kind] = JSON.parse(key) as [string, number];
+        return { pattern, kind };
+      });
     },
     get connection() {
       return connection;

package/src/lib/lsp/diagnostic.ts

@@ -1,10 +1,10 @@
 /**
- * 诊断报告格式化：报告 ERROR 与 WARN，每个文件最多 20 条。
+ * 诊断报告格式化：报告 ERROR 与 WARN，每个文件最多 5 条。
  */
 
 import type { Diagnostic } from "./client.js";
 
-const MAX_PER_FILE = 20;
+const MAX_PER_FILE = 5;
 
 const SEVERITY_LABELS: Record<number, string> = {
   1: "ERROR",

package/src/lib/lsp/lsp.ts

@@ -27,7 +27,15 @@ import { type Static, Type } from "typebox";
 import { Value } from "typebox/value";
 
 import { type LspServerAdapter } from "./adapter.js";
-import { create, type CreateInput, type Diagnostic, type Info as LspClient } from "./client.js";
+import {
+  create,
+  type CreateInput,
+  type Diagnostic,
+  type Info as LspClient,
+  WATCH_KIND_CHANGE,
+  WATCH_KIND_CREATE,
+  WATCH_KIND_DELETE,
+} from "./client.js";
 import { report } from "./diagnostic.js";
 import { createAdapters, mergeServerRecords, serverConfigSchema } from "./server-config.js";
 import { type FileChange, watchWorkspace, type WorkspaceWatcher } from "./watcher.js";
@@ -346,10 +354,26 @@ export function createLspService(
           if (!containsPath(change.path, cwd) || !containsPath(change.path, client.root)) {
             return false;
           }
-          const patterns = client.watchPatterns();
-          if (patterns.length > 0) {
-            const candidate = relative(client.root, change.path).split(sep).join("/");
-            if (patterns.every((pattern) => !minimatch(candidate, pattern))) return false;
+          const watchers = client.watchers();
+          if (watchers.length > 0) {
+            // pattern 可能是相对 glob（pyright 的 "**"）也可能是绝对 glob
+            // （gopls 的 "/workspace/**/*.{go,mod}"），两个候选任一命中即转发；
+            // 并按各 watcher 注册的 WatchKind 位过滤事件类型
+            const relativeCandidate = relative(client.root, change.path).split(sep).join("/");
+            const absoluteCandidate = change.path.split(sep).join("/");
+            const kindBit =
+              change.type === "created"
+                ? WATCH_KIND_CREATE
+                : change.type === "changed"
+                  ? WATCH_KIND_CHANGE
+                  : WATCH_KIND_DELETE;
+            const matched = watchers.some(
+              (watcher) =>
+                (watcher.kind & kindBit) !== 0 &&
+                (minimatch(relativeCandidate, watcher.pattern) ||
+                  minimatch(absoluteCandidate, watcher.pattern)),
+            );
+            if (!matched) return false;
           }
           const extensions = state.clientExtensions.get(client);
           return (