@trim21/personal-pi-extensions 0.1.446 → 0.1.450

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.446",
+  "version": "0.1.450",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -94,7 +94,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@cortexkit/aft-bridge": "0.53.0",
+    "@cortexkit/aft-bridge": "0.54.0",
     "@mozilla/readability": "^0.6.0",
     "@vscode/tree-sitter-wasm": "^0.3.1",
     "jsonc-parser": "^3.3.1",
@@ -107,6 +107,6 @@
     "web-tree-sitter": "^0.26.12"
   },
   "optionalDependencies": {
-    "@cortexkit/aft-linux-x64": "0.53.0"
+    "@cortexkit/aft-linux-x64": "0.54.0"
   }
 }

package/src/aft/bridge.ts

@@ -13,6 +13,7 @@ import {
   type BridgeRequestOptions,
   createAftTransportPool,
   findBinary,
+  inlineUserConfigTier,
   readConfigTiers,
   resolveCortexKitConfigPaths,
   resolveCortexKitStorageRoot,
@@ -20,6 +21,8 @@ import {
 } from "@cortexkit/aft-bridge";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+import type { SemanticRemote } from "./config.js";
+
 /** Pi 会话 ID：Rust 侧用它做 session 作用域（undo/checkpoint），感知工具可留空。 */
 export function resolveSessionId(extCtx: ExtensionContext): string | undefined {
   const manager = (extCtx as unknown as { sessionManager?: { getSessionId?: () => string } })
@@ -53,26 +56,64 @@ export interface AftPool {
 /** semantic_search 等待索引构建完成的上限（与 Rust 侧 AFT_WAIT_FOR_SEMANTIC_READY_MS 一致）。 */
 export const SEMANTIC_INDEX_WAIT_TIMEOUT_MS = 600_000;
 
-/** 创建 transport pool。每个项目根一个常驻 aft 进程，跨 session 共享。 */
-export async function createAftPool(cwd: string): Promise<AftPool> {
+/**
+ * 调用图存储未就绪时查询侧的内联等待窗口。Rust 侧默认 0（纯异步：立即返回
+ * callgraph_building），非零时查询会在窗口内加入同一个 single-flight 构建，
+ * 就绪后直接返回真实结果。窗口必须明显小于 aft-bridge 给 callgraph 的 60s
+ * transport 预算，否则客户端先超时并触发 bridge hang 升级。
+ */
+export const CALLGRAPH_BUILD_WAIT_MS = 30_000;
+
+/**
+ * 本扩展替用户注入 embedding 密钥时使用的固定变量名。仅当用户只配了
+ * `semantic.api_key`（值）而没配 `semantic.api_key_env`（变量名）时生效。
+ */
+export const SEMANTIC_API_KEY_ENV = "AFT_SEMANTIC_API_KEY";
+
+/**
+ * 创建 transport pool。每个项目根一个常驻 aft 进程，跨 session 共享。
+ *
+ * `semantic` 决定 embedding 密钥如何送达子进程：aft 只从配置里读 `api_key_env`
+ * 这个「变量名」，再自己 `env::var` 取值，所以提供值时必须连带把名字告诉它。
+ * 两者都缺省时不注入任何凭据（无鉴权端点直接可用）。
+ */
+export async function createAftPool(cwd: string, semantic?: SemanticRemote): Promise<AftPool> {
   const binaryPath = await resolveAftBinary();
   const paths = resolveCortexKitConfigPaths(cwd);
+  const childEnv: Record<string, string> = {
+    // Rust 侧 semantic_search 在索引 Building 时阻塞等待构建完成
+    // （main.rs wait_for_semantic_index_before_search），避免首次搜索拿到
+    // 词法 fallback 的部分结果。语义搜索未启用时该逻辑直接跳过。
+    AFT_WAIT_FOR_SEMANTIC_READY: "1",
+    AFT_WAIT_FOR_SEMANTIC_READY_MS: String(SEMANTIC_INDEX_WAIT_TIMEOUT_MS),
+    // 调用图冷构建与 watcher 重建时让查询内联等待就绪，而不是把
+    // callgraph_building 直接吐给模型（见 CALLGRAPH_BUILD_WAIT_MS 注释）。
+    AFT_CALLGRAPH_BUILD_WAIT_MS: String(CALLGRAPH_BUILD_WAIT_MS),
+  };
+  const config = [...readConfigTiers(paths)];
+  if (semantic?.apiKey !== undefined) {
+    // childEnv 叠加在继承的 process.env 之上，所以配置里的值优先于 shell 同名变量。
+    // 密钥只进子进程环境，不进日志与工具输出。
+    childEnv[semantic.apiKeyEnv ?? SEMANTIC_API_KEY_ENV] = semantic.apiKey;
+    if (semantic.apiKeyEnv === undefined) {
+      // 用户没指定变量名：追加一份 user tier（后应用的 doc 覆盖先应用的）让 aft
+      // 知道该读 SEMANTIC_API_KEY_ENV，否则它不知道去哪个变量取值。
+      config.push(
+        ...inlineUserConfigTier(
+          { semantic: { api_key_env: SEMANTIC_API_KEY_ENV } },
+          "pi:semantic-api-key",
+        ),
+      );
+    }
+  }
   const pool = await createAftTransportPool({
     harness: "pi",
     binaryPath,
-    poolOptions: {
-      childEnv: {
-        // Rust 侧 semantic_search 在索引 Building 时阻塞等待构建完成
-        // （main.rs wait_for_semantic_index_before_search），避免首次搜索拿到
-        // 词法 fallback 的部分结果。语义搜索未启用时该逻辑直接跳过。
-        AFT_WAIT_FOR_SEMANTIC_READY: "1",
-        AFT_WAIT_FOR_SEMANTIC_READY_MS: String(SEMANTIC_INDEX_WAIT_TIMEOUT_MS),
-      },
-    },
+    poolOptions: { childEnv },
     configOverrides: {
       storage_dir: resolveCortexKitStorageRoot(),
       cortexkit_user_config_path: paths.userConfigPath,
-      config: readConfigTiers(paths),
+      config,
     },
   });
   pool.setConfigureOverride("harness", "pi");

package/src/aft/callgraph.md

@@ -15,4 +15,6 @@ op 选择：
 
 标记含义：`~` = 仅按名字解析的边（可能指向同名符号）；`[unresolved]` = 未解析到定义的调用点（外部库/stdlib 默认折叠为每父节点一条摘要，`includeUnresolved: true` 逐个列出）。
 
-符号未定义或调用图索引仍在构建时返回文本说明，不报错。
+符号未定义时返回文本说明，不报错。
+
+索引正在重建时，本工具会等待其就绪再返回结果；若返回 `callgraph_building`，稍后重试同一查询即可。

package/src/aft/config.ts

@@ -1,46 +1,119 @@
 /**
- * aft.jsonc 最小读取：只关心 JS 侧注册决策需要的字段
- * （enabled / semantic_search），完整配置由 Rust 侧从配置 tier 读取。
+ * aft.jsonc 最小读取：只关心 JS 侧注册决策需要的字段（enabled / semantic_search /
+ * semantic.backend / semantic.base_url），其余字段由 Rust 侧从配置 tier 自行读取。
  *
- * 只读用户级配置：semantic_search 涉及外部 embedding 后端，按 AFT 的信任
- * 边界语义只允许用户级控制（项目级配置不应替用户开启语义搜索）。
+ * 只读用户级配置：语义搜索涉及外部 embedding 端点与密钥，按 AFT 的信任边界只允许
+ * 用户级控制（项目级配置不应替用户开启语义搜索或注入 base_url）。
  *
- * JSONC 解析用微软 jsonc-parser（vscode 同源，处理注释与尾逗号），
- * 不手写解析器。
+ * 本仓库只接受外部 embedding 后端（openai_compatible / ollama）：aft 默认后端
+ * fastembed 走本地 ONNX Runtime，内网镜像不提供该运行时，所以即便用户开了
+ * semantic_search，外部后端未就绪时也不注册 aft_search。
+ *
+ * JSONC 解析用微软 jsonc-parser（vscode 同源，处理注释与尾逗号），不手写解析器；
+ * 分两层：rawConfigSchema 只描述依赖的外部形状并做基础类型校验，toReadConfig 负责
+ * 补默认值与后端语义判定。
  */
 
 import { existsSync, readFileSync } from "node:fs";
 
 import { parse } from "jsonc-parser";
+import { type Static, Type } from "typebox";
+
+import { parseWithSchema } from "../lib/parse-with-schema.js";
+
+/** aft 侧走 HTTP embeddings 端点的后端；fastembed（本地 ONNX）有意排除在外。 */
+const REMOTE_SEMANTIC_BACKENDS = ["openai_compatible", "ollama"] as const;
+
+export type RemoteSemanticBackend = (typeof REMOTE_SEMANTIC_BACKENDS)[number];
+
+/** 就绪的外部 embedding 后端：类型受支持且配了 base_url。 */
+export interface SemanticRemote {
+  backend: RemoteSemanticBackend;
+  baseUrl: string;
+  /**
+   * 用户自己指定的密钥环境变量名（可选覆盖）。配了就直接用该名，值由用户的
+   * shell 提供，或由 `apiKey` 注入到同名变量。
+   */
+  apiKeyEnv: string | undefined;
+  /**
+   * 密钥值（可选）。aft 只认环境变量名，所以未配 `apiKeyEnv` 时由本扩展注入成
+   * 固定的内部变量名并告诉 aft 去读它。undefined = 无鉴权端点（自建网关、ollama
+   * 都可以不带 key）。
+   */
+  apiKey: string | undefined;
+}
 
 export interface AftReadConfig {
   enabled: boolean;
   semanticSearch: boolean;
+  /** undefined = 外部后端未就绪（未配 backend、非远程后端、或缺 base_url）。 */
+  semanticRemote: SemanticRemote | undefined;
+}
+
+const DEFAULTS: AftReadConfig = {
+  enabled: true,
+  semanticSearch: false,
+  semanticRemote: undefined,
+};
+
+/** 上游（aft）控制的形状：只声明本仓库真正读取的字段，未声明的键由解析层忽略。 */
+const rawConfigSchema = Type.Object({
+  enabled: Type.Optional(Type.Boolean()),
+  semantic_search: Type.Optional(Type.Boolean()),
+  semantic: Type.Optional(
+    Type.Object({
+      backend: Type.Optional(Type.String()),
+      base_url: Type.Optional(Type.String()),
+      api_key_env: Type.Optional(Type.String()),
+      // 本扩展独有：aft 只读环境变量，密钥值由我们注入成 api_key_env 命名的变量。
+      api_key: Type.Optional(Type.String()),
+    }),
+  ),
+});
+
+type RawConfig = Static<typeof rawConfigSchema>;
+
+function isRemoteBackend(value: string): value is RemoteSemanticBackend {
+  return (REMOTE_SEMANTIC_BACKENDS as readonly string[]).includes(value);
 }
 
-const DEFAULTS: AftReadConfig = { enabled: true, semanticSearch: false };
+function trimmedOrUndefined(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+
+function remoteOf(semantic: RawConfig["semantic"]): SemanticRemote | undefined {
+  const backend = trimmedOrUndefined(semantic?.backend);
+  // 去掉尾斜杠：aft 侧按 base_url + /embeddings 拼请求。
+  const baseUrl = trimmedOrUndefined(semantic?.base_url)?.replace(/\/+$/, "");
+  if (backend === undefined || baseUrl === undefined) return undefined;
+  if (!isRemoteBackend(backend)) return undefined;
+  return {
+    backend,
+    baseUrl,
+    apiKeyEnv: trimmedOrUndefined(semantic?.api_key_env),
+    apiKey: trimmedOrUndefined(semantic?.api_key),
+  };
+}
 
-function readOne(path: string): AftReadConfig {
+function toReadConfig(raw: RawConfig): AftReadConfig {
+  return {
+    enabled: raw.enabled ?? DEFAULTS.enabled,
+    semanticSearch: raw.semantic_search ?? DEFAULTS.semanticSearch,
+    semanticRemote: remoteOf(raw.semantic),
+  };
+}
+
+/**
+ * 读用户级 aft.jsonc。文件缺失、非法 JSONC 或形状不符（含字段类型错误）时整体回退
+ * 默认值：注册决策宁可保守，不该因配置写错而让扩展加载失败。
+ */
+export function loadAftConfig(userConfigPath: string): AftReadConfig {
   try {
-    if (!existsSync(path)) return DEFAULTS;
-    const parsed: unknown = parse(readFileSync(path, "utf8"));
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return DEFAULTS;
-    }
-    const value = parsed as Record<string, unknown>;
-    return {
-      enabled: typeof value.enabled === "boolean" ? value.enabled : DEFAULTS.enabled,
-      semanticSearch:
-        typeof value.semantic_search === "boolean"
-          ? value.semantic_search
-          : DEFAULTS.semanticSearch,
-    };
+    if (!existsSync(userConfigPath)) return DEFAULTS;
+    const parsed: unknown = parse(readFileSync(userConfigPath, "utf8"));
+    return toReadConfig(parseWithSchema(rawConfigSchema, parsed ?? {}));
   } catch {
     return DEFAULTS;
   }
 }
-
-/** 读用户级 aft.jsonc。解析失败或文件缺失时回退默认值（不阻塞扩展加载）。 */
-export function loadAftConfig(userConfigPath: string): AftReadConfig {
-  return readOne(userConfigPath);
-}

package/src/aft/index.ts

@@ -3,9 +3,10 @@
  * + aft_refactor / aft_import（workspace-wide 重构与 import 管理，路径级写保护）。
  *
  * 感知工具只读，不触碰本仓库自己的 read/write/edit/bash 工具及其安全机制
- * （bwrap 沙箱、write-guard、reads 记账）。aft_search 仅当用户级
- * aft.jsonc 开启 semantic_search 时注册（本地语义索引需 ONNX 运行时，
- * 内网默认关闭）。aft_refactor / aft_import 的 Rust 命令不支持 preview，
+ * （bwrap 沙箱、write-guard、reads 记账）。aft_search 仅当用户级 aft.jsonc 开启
+ * semantic_search 且配好外部 embedding 后端（semantic.backend 为
+ * openai_compatible / ollama 且有 base_url）时注册；aft 默认的本地 ONNX
+ * fastembed 后端不使用。aft_refactor / aft_import 的 Rust 命令不支持 preview，
  * 写保护退化为路径级审批。
  *
  * 二进制缺失或 pool 创建失败时降级：不注册任何工具并在 session 开始时报
@@ -36,7 +37,7 @@ export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
 
   let pool: AftPool;
   try {
-    pool = await createAftPool(cwd);
+    pool = await createAftPool(cwd, cfg.semanticRemote);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     pi.on("session_start", (_event, ctx) => {
@@ -55,7 +56,17 @@ export default async function aftReadTools(pi: ExtensionAPI): Promise<void> {
   registerRefactorTool(pi, toolCtx);
   registerImportTool(pi, toolCtx);
   if (cfg.semanticSearch) {
-    registerSearchTool(pi, toolCtx);
+    if (cfg.semanticRemote) {
+      registerSearchTool(pi, toolCtx);
+    } else {
+      // 只开了开关、没配外部 embedding 后端：与其静默不注册，不如说明缺什么。
+      pi.on("session_start", (_event, ctx) => {
+        ctx.ui.notify(
+          "aft_search is not registered: semantic_search needs an external embedding backend (aft.jsonc semantic.backend = openai_compatible | ollama, plus base_url). The local ONNX fastembed default is not used here.",
+          "warning",
+        );
+      });
+    }
   }
 
   // 关闭 bridge pool。session_shutdown 是 pi 的正常生命周期；beforeExit 兜底

package/src/aft/outline.md

@@ -8,4 +8,4 @@
 - 目录递归上限 200 个文件；超出部分在结果中标记截断。
 - 只接受单个 target，不支持数组；跨文件批量用多次调用。
 
-分工：看结构用本工具；看某个符号的完整源码用 aft_zoom；看符号间调用关系用 aft_callgraph；按语义/文本搜代码用 aft_search。
+分工：看结构用本工具；看某个符号的完整源码用 aft_zoom；看符号间调用关系用 aft_callgraph。

package/src/aft/refactor.md

@@ -2,8 +2,52 @@
 
 workspace-wide 重构：跨文件移动符号、抽函数、内联，自动更新引用与 import。
 
-- `move`：把顶层符号（非嵌套函数/类方法）移到另一个文件，全 workspace 重写 import 与引用；执行前自动创建 checkpoint。需要 `symbol` + `destination`；同名符号歧义时用 `scope` 消歧。注意：move / rename 整个文件请用 aft_move（OS 层操作，不更新引用）。
+- `move`：把顶层符号（非嵌套函数/类方法）移到另一个文件，全 workspace 重写 import 与引用。需要 `symbol` + `destination`；同名符号歧义时用 `scope` 消歧。
 - `extract`：把行区间抽成新函数（TS/JS/TSX、Python）。需要 `name` + `start_line` + `end_line`（1 起，含端点）。
 - `inline`：把调用点替换为函数体。需要 `symbol` + `call_site_line`（1 起）。
 
-重构是写操作：不支持 preview（无 diff 预览），写保护退化为路径级审批——workspace 内目标自动放行，外部路径需要确认。重构前先看影响面：对目标符号跑 aft_callgraph `impact`，确认波及范围符合预期再动手。
+重构前先看影响面：对目标符号跑 aft_callgraph `impact`，确认波及范围符合预期再动手。
+
+#### 示例
+
+`path` 相对项目根，行号 1 起且含端点。
+
+跨文件移动顶层符号，自动重写全部 import 与引用：
+
+```json
+{
+  "op": "move",
+  "path": "src/aft/tools.ts",
+  "symbol": "buildPendantMarkdown",
+  "destination": "src/lib/pendant.ts"
+}
+```
+
+把行区间抽成新函数（先用 aft_outline 或 Read 定位区间）：
+
+```json
+{
+  "op": "extract",
+  "path": "src/aft/refactor.ts",
+  "name": "buildRefactorArgs",
+  "start_line": 121,
+  "end_line": 134
+}
+```
+
+`start_line` / `end_line` 指 `path` 文件里被抽取的代码，不是新函数所在的行。
+
+内联单个调用点：
+
+```json
+{
+  "op": "inline",
+  "path": "src/aft/refactor.ts",
+  "symbol": "requireField",
+  "call_site_line": 98
+}
+```
+
+`call_site_line` 是调用发生的那一行，不是函数定义行；只替换指定那一处，内联掉全部调用点后原定义不会被自动删除，需要自己清理。
+
+只支持顶层符号；嵌套函数与类方法不适用。

package/src/aft/refactor.ts

@@ -3,8 +3,8 @@
  *
  * 参数经 bridge.toolCall 以 agent 工具名 "refactor" 分派，Rust 侧 subc 翻译层
  * 按 op 转成内部命令（move_symbol / extract_function / inline_symbol）。
- * 与 ast_edit 不同，这些命令不支持 preview：写保护退化为路径级审批
- * （workspace 内自动放行，外部路径经 write-guard 确认，无 diff 预览）。
+ * 这些命令不支持 preview，写保护退化为路径级审批（workspace 内自动放行，
+ * 外部路径经 write-guard 确认，无 diff 预览）。
  */
 
 import { readFileSync } from "node:fs";
@@ -71,10 +71,9 @@ export function registerRefactorTool(pi: ExtensionAPI, ctx: AftToolContext): voi
     label: "aft_refactor",
     description: [
       "workspace-wide 重构：更新跨文件的 import 与引用。",
-      "move：把顶层符号（非嵌套函数/类方法）移到另一文件，全 workspace 重写 import；执行前自动创建 checkpoint。",
+      "move：把顶层符号（非嵌套函数/类方法）移到另一文件，全 workspace 重写 import。",
       "extract：把行区间抽成新函数（TS/JS/TSX、Python）。",
       "inline：把调用点替换为函数体。",
-      "move / rename 整个文件用 aft_move（OS 层操作，不更新引用）；移动代码符号用本工具 op=move。",
     ].join("\n"),
     promptSnippet: "Workspace-wide symbol move / function extraction / inlining",
     promptGuidelines: [REFACTOR_PROMPT],

package/src/aft/search.md

@@ -8,4 +8,4 @@
 - `includeTests: true`：包含测试文件，默认排除。
 - `path`：仅当要搜索另一个 Git 项目时设置（绝对或 ~ 路径）；默认搜索当前项目。
 
-需要语义索引可用（aft.jsonc 中 `semantic_search: true` 且 embedding 后端就绪）；否则退化为词法/正则通道。启用语义索引时，首次调用会阻塞到索引构建完成，避免拿到部分结果。
+索引首次构建时本工具会阻塞到构建完成，第一次调用可能明显更慢。

package/src/aft/tools.ts

@@ -389,9 +389,7 @@ export function registerSearchTool(pi: ExtensionAPI, ctx: AftToolContext): void
       "一个工具完成代码搜索：概念、标识符、错误串、正则、字面量、文件名自动路由到合适的引擎并按相关度排序。",
       "概念类查询（'ORM 如何构建并执行查询'）用自然语言整句——语义通道理解意图并匹配 docstring 和注释；",
       "精确名字、字符串、正则保持简短（'^export'、'Cargo.lock'）。",
-      "需要语义索引可用（aft.jsonc 中 semantic_search: true 且 embedding 后端就绪）；",
-      "否则退化为词法/正则匹配通道。",
-      "启用语义索引时，首次调用会阻塞到索引构建完成，避免返回部分结果。",
+      "索引首次构建时本调用会阻塞到构建完成，避免返回部分结果。",
     ].join("\n"),
     promptSnippet: "Search code by meaning or exact text",
     promptGuidelines: [SEARCH_PROMPT],

package/src/aft/ast-edit.ts

@@ -1,310 +0,0 @@
-/**
- * ast_edit —— 符号级/AST 感知编辑工具。
- *
- * 用 AFT 的 edit 命令做符号级替换 / 模糊匹配 / 批量编辑，流程：
- *   1. preview（只计算不写盘）拿所有变动文件的 before/after
- *   2. write-guard：工作区内自动放行，外部路径用真实 diff 审批
- *   3. 再次调用 edit（不带 preview）→ AFT 自己原子写盘（备份 + 格式化 +
- *      undo），本工具不再直接写文件
- *
- * 不维护 reads 记账：写盘后模型重新 Read 目标文件即可（与本仓库 Edit 的
- * 防呆不同，ast_edit 不要求先读）。
- */
-
-import {
-  type ExtensionAPI,
-  generateDiffString,
-  generateUnifiedPatch,
-} from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { Value } from "typebox/value";
-
-import { requireAbsolutePath } from "../claude-code/common.js";
-import { type ToolPendant } from "../lib/pendant.js";
-import { guardWriteAccess } from "../lib/write-guard.js";
-import { callAftTool } from "./bridge.js";
-import { type AftToolContext, bridgeFor, buildPendantMarkdown } from "./tools.js";
-
-// ── 纯函数（可测） ──────────────────────────────────────────────────────────
-
-export interface PreviewFile {
-  /** 绝对路径；symbol 模式（顶层 diff）时为调用方传入的 file_path 兜底。 */
-  file: string;
-  before: string;
-  after: string;
-}
-
-export interface PreviewExtract {
-  files: PreviewFile[];
-  /** 任一文件超过 512KB 未返回全文（diff.truncated）。 */
-  truncated: boolean;
-}
-
-/** AFT preview diff 条目：preview 模式下默认带 before/after，>512KB 只带 truncated。 */
-const previewDiffSchema = Type.Object({
-  before: Type.Optional(Type.String()),
-  after: Type.Optional(Type.String()),
-  truncated: Type.Optional(Type.Boolean()),
-});
-
-type PreviewDiff = { truncated: true } | { truncated: false; before: string; after: string };
-
-function findDiffObject(value: unknown): PreviewDiff | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  if (!Value.Check(previewDiffSchema, value)) return undefined;
-  if (value.truncated === true) return { truncated: true };
-  if (value.before === undefined || value.after === undefined) return undefined;
-  return { before: value.before, after: value.after, truncated: false };
-}
-
-/**
- * 从 AFT edit preview 响应提取所有变动文件的 before/after，供写保护审批。
- * 批量/单文件 edits/glob 模式在 `files[]`（每项带 `file` 与 `diff`）；
- * symbol 模式在顶层 `diff`（file 留空，由调用方兜底）。
- */
-export function extractPreviewFiles(response: Record<string, unknown>): PreviewExtract {
-  const rawFiles = response.files;
-  if (Array.isArray(rawFiles) && rawFiles.length > 0) {
-    const files: PreviewFile[] = [];
-    let truncated = false;
-    for (const raw of rawFiles as unknown[]) {
-      if (typeof raw !== "object" || raw === null) continue;
-      const entry = raw as Record<string, unknown>;
-      const diff = findDiffObject(entry.diff);
-      if (!diff) continue;
-      if (diff.truncated) {
-        truncated = true;
-        continue;
-      }
-      files.push({
-        file: typeof entry.file === "string" ? entry.file : "",
-        before: diff.before,
-        after: diff.after,
-      });
-    }
-    if (truncated || files.length > 0) return { files, truncated };
-  }
-  const top = findDiffObject(response.diff);
-  if (top) {
-    if (top.truncated) return { files: [], truncated: true };
-    return {
-      files: [{ file: "", before: top.before, after: top.after }],
-      truncated: false,
-    };
-  }
-  return { files: [], truncated: false };
-}
-
-/** 把本工具的参数名映射到 AFT edit wire 格式。 */
-export function mapEditItems(
-  items: {
-    old_string?: string;
-    new_string?: string;
-    start_line?: number | string;
-    end_line?: number | string;
-    content?: string;
-    occurrence?: number | string;
-  }[],
-): Record<string, unknown>[] {
-  return items.map((item) => {
-    const out: Record<string, unknown> = {};
-    if (item.old_string !== undefined) out.oldString = item.old_string;
-    if (item.new_string !== undefined) out.newString = item.new_string;
-    if (item.start_line !== undefined) out.startLine = item.start_line;
-    if (item.end_line !== undefined) out.endLine = item.end_line;
-    if (item.content !== undefined) out.content = item.content;
-    if (item.occurrence !== undefined) out.occurrence = item.occurrence;
-    return out;
-  });
-}
-
-/**
- * 参照 Edit 工具的结果输出：把 preview 的 before/after 转成行号 diff、
- * unified patch 与首个变更行。多文件（glob 批量）时逐文件拼接 diff/patch，
- * firstChangedLine 取首个文件的。
- */
-export function buildEditDiffDetails(
-  previewFiles: PreviewFile[],
-  fallbackFile: string,
-): { diff: string; patch: string; firstChangedLine: number | undefined } {
-  const parts = previewFiles.map((f) => {
-    const file = f.file || fallbackFile;
-    const diff = generateDiffString(f.before, f.after);
-    return {
-      file,
-      diff: diff.diff,
-      patch: generateUnifiedPatch(file, f.before, f.after),
-      firstChangedLine: diff.firstChangedLine,
-    };
-  });
-  if (parts.length === 0) {
-    return { diff: "", patch: "", firstChangedLine: undefined };
-  }
-  return {
-    diff: parts.map((p) => `--- ${p.file}\n${p.diff}`).join("\n"),
-    patch: parts.map((p) => `--- ${p.file}\n${p.patch}`).join("\n"),
-    firstChangedLine: parts[0]?.firstChangedLine,
-  };
-}
-
-// ── 工具 ────────────────────────────────────────────────────────────────────
-
-const EditItemParams = Type.Object({
-  old_string: Type.Optional(Type.String({ description: "要替换的文本" })),
-  new_string: Type.Optional(Type.String({ description: "替换后的文本" })),
-  start_line: Type.Optional(
-    Type.Union([Type.Number(), Type.String()], {
-      description: "行范围编辑：起始行（1 起）",
-    }),
-  ),
-  end_line: Type.Optional(
-    Type.Union([Type.Number(), Type.String()], {
-      description: "行范围编辑：结束行",
-    }),
-  ),
-  content: Type.Optional(Type.String({ description: "替换内容；空字符串删除这些行" })),
-  occurrence: Type.Optional(
-    Type.Union([Type.Number(), Type.String()], {
-      description: "第几次匹配（0 起）；多匹配时指定",
-    }),
-  ),
-});
-
-const AstEditParams = Type.Object(
-  {
-    file_path: Type.String({
-      description:
-        "要修改的文件（绝对路径）；配合 old_string+replace_all 可传绝对路径 glob（如 /path/src/**/*.ts）批量替换多个文件",
-    }),
-    old_string: Type.Optional(Type.String({ description: "精确/模糊匹配的旧文本" })),
-    new_string: Type.Optional(Type.String({ description: "替换后的新文本" })),
-    replace_all: Type.Optional(Type.Boolean({ description: "替换所有匹配（默认 false）" })),
-    occurrence: Type.Optional(
-      Type.Union([Type.Number(), Type.String()], {
-        description: "第几次匹配（0 起）；多匹配时指定",
-      }),
-    ),
-    symbol: Type.Optional(Type.String({ description: "要替换的符号名（函数/类等）" })),
-    content: Type.Optional(Type.String({ description: "符号的新实现内容" })),
-    edits: Type.Optional(
-      Type.Array(EditItemParams, {
-        description: "批量编辑（原子应用，全部成功或全部失败）",
-      }),
-    ),
-    append_content: Type.Optional(Type.String({ description: "追加到文件末尾" })),
-  },
-  { additionalProperties: false },
-);
-
-function buildWireArgs(
-  params: {
-    old_string?: string;
-    new_string?: string;
-    replace_all?: boolean;
-    occurrence?: number | string;
-    symbol?: string;
-    content?: string;
-    edits?: Record<string, unknown>[];
-    append_content?: string;
-  },
-  filePath: string,
-): Record<string, unknown> {
-  const rawArgs: Record<string, unknown> = { path: filePath };
-  const modes = [
-    params.old_string !== undefined,
-    params.symbol !== undefined,
-    params.edits !== undefined,
-    params.append_content !== undefined,
-  ].filter(Boolean).length;
-  if (modes !== 1) {
-    throw new Error(
-      "Provide exactly one mode: old_string+new_string, symbol+content, edits, or append_content",
-    );
-  }
-  if (params.old_string !== undefined) {
-    if (params.new_string === undefined) {
-      throw new Error("'new_string' is required with 'old_string'");
-    }
-    rawArgs.oldString = params.old_string;
-    rawArgs.newString = params.new_string;
-    if (params.replace_all) rawArgs.replaceAll = true;
-    if (params.occurrence !== undefined) rawArgs.occurrence = params.occurrence;
-  } else if (params.symbol !== undefined) {
-    if (params.content === undefined) {
-      throw new Error("'content' is required with 'symbol'");
-    }
-    rawArgs.symbol = params.symbol;
-    rawArgs.content = params.content;
-  } else if (params.edits !== undefined) {
-    rawArgs.edits = mapEditItems(params.edits);
-  } else if (params.append_content !== undefined) {
-    rawArgs.appendContent = params.append_content;
-  }
-  return rawArgs;
-}
-
-export function registerAstEditTool(pi: ExtensionAPI, ctx: AftToolContext): void {
-  pi.registerTool({
-    name: "ast_edit",
-    label: "ast_edit",
-    description: [
-      "符号级/AST 感知编辑：按符号名替换函数/类实现，或做模糊匹配/批量/追加编辑。",
-      "与 Edit 的区别：Edit 是精确字符串替换；ast_edit 支持 symbol+content（符号级，包含装饰器/注释/属性）、",
-      "edits[] 批量（原子）、fuzzy 匹配（4 步容错）与 append_content 追加。",
-      "old_string + replace_all 且 file_path 为 glob 时批量替换多个文件（结果为所有变动文件）。",
-      "写盘由 AFT 原子完成（自动备份、格式化）；调用前先以 preview 计算 diff 套用工作区写保护。",
-      "不要求先 Read（与本仓库 Edit 不同）；写入后如需确认可重新 Read 文件。四种模式互斥：",
-      "  • old_string + new_string（+ replace_all / occurrence；glob 批量需 replace_all）",
-      "  • symbol + content",
-      "  • edits[]（每项 old_string+new_string 或 start_line+end_line+content）",
-      "  • append_content",
-    ].join("\n"),
-    promptSnippet: "Symbol-aware / fuzzy file edits via AFT",
-    parameters: AstEditParams,
-    async execute(_id, params, _signal, _onUpdate, extCtx) {
-      const filePath = requireAbsolutePath(params.file_path);
-      const rawArgs = buildWireArgs(params, filePath);
-
-      // 第一步：preview（不写盘）拿所有变动文件的 before/after，供写保护审批。
-      // preview 必须经 options 传入（bridge 会放到 tool_call 消息顶层），
-      // 放进 arguments 会被 AFT 忽略并真的写盘。
-      const { response } = await callAftTool(bridgeFor(ctx), "edit", rawArgs, extCtx, {
-        preview: true,
-      });
-      const { files: previewFiles, truncated } = extractPreviewFiles(response);
-      if (truncated) {
-        throw new Error("ast_edit: file too large for preview (over 512KB)");
-      }
-      if (previewFiles.length === 0) {
-        throw new Error("ast_edit: preview did not return before/after content");
-      }
-
-      // 第二步：写保护——工作区内自动放行，外部路径用真实 diff 审批。
-      for (const preview of previewFiles) {
-        await guardWriteAccess(extCtx, {
-          toolName: "ast_edit",
-          absolutePath: preview.file || filePath,
-          change: { oldText: preview.before, newText: preview.after },
-        });
-      }
-
-      // 第三步：AFT 原子写盘（备份 + 格式化 + undo），结果由 Rust 格式化返回。
-      const { text } = await callAftTool(bridgeFor(ctx), "edit", rawArgs, extCtx);
-      const files = previewFiles.map((f) => f.file || filePath);
-      return {
-        content: [{ type: "text", text }],
-        details: {
-          files,
-          ...buildEditDiffDetails(previewFiles, filePath),
-          pendant: {
-            markdown: buildPendantMarkdown({
-              title: "ast_edit",
-              input: params,
-              output: text,
-            }),
-          } satisfies ToolPendant,
-        },
-      };
-    },
-  });
-}