@trim21/personal-pi-extensions 0.1.448 → 0.1.451

package/README.md

@@ -372,6 +372,13 @@ read/edit/write 工具内置 LSP 诊断（写文件后等待并报告 ERROR 级
       "settings": {}, // → didChangeConfiguration / workspace/configuration 请求
     },
   },
+  "maxOpenDocuments": 32, // 驻留文档上限（LRU 容量），缺省 32
+  "watch": {
+    "enabled": true, // 工作区文件监听，缺省 true
+    "debounceMs": "300ms", // 事件去抖，缺省 300ms；也支持 "5s" / "1m"
+    "maxBatch": 500, // 单批事件上限，缺省 500，超出截断并提示一次
+    "ignore": [], // 追加忽略 glob（相对工作区根）
+  },
 }
 ```
 
@@ -384,9 +391,13 @@ read/edit/write 工具内置 LSP 诊断（写文件后等待并报告 ERROR 级
 - `startupTimeoutMs` / `diagnosticsWaitMs`：per-server 超时，覆盖全局配置与默认值
 - `initializationOptions` 与 `settings` 按 LSP 语义分离：前者进 initialize 请求，后者进 didChangeConfiguration / workspace/configuration 请求
 
-内置默认服务器（typescript / pyright / ruff / clangd）始终存在；`servers` 以 key 为服务器 id 与默认合并——同 key 整体覆盖（整个配置替换默认）、新 key 新增、`"enabled": false` 移除（如 `"clangd": { "enabled": false }`）。executable 的发现逻辑（如 tsserver 路径、venv 里的 python）不内置，需要时用 `bin` / `args` / `settings` 自行表达。
+没有内置默认服务器：`servers` 的 key 就是服务器 id，全部来自你的配置，未定义 `servers` 时不启动任何语言服务器。executable 的发现逻辑（如 tsserver 路径、venv 里的 python）不内置，需要时用 `bin` / `args` / `settings` 自行表达。
+
+启用控制只有顶层两处：`enabled`（白名单）与 `disabled`（排除），按服务器 id 生效。`enabled` 里的 id 必须是已配置服务器，否则视为配置错误；`disabled` 里未注册的 id 直接忽略。全局超时字段（`initializeTimeoutMs` 等）同样配在顶层。
+
+顶层 `watch` 段控制工作区文件监听（事件源是会话 cwd 的递归 fs.watch，非本 agent 写入的改动——如 `git checkout`、外部格式化——也会以 `workspace/didChangeWatchedFiles` 批量通知服务器）；内置忽略 `node_modules`、`.git`、`dist`、`build`、`.venv`、`venv`、`target`、`coverage`，`ignore` 可追加。`maxOpenDocuments` 是保持 open 的文档上限（LRU）：超过时最久未使用的文档会被 `didClose`，服务器回落到读磁盘。`watch.enabled: false` 可整体关闭监听，回到仅工具触发同步的现状。
 
-旧的 `enabled`（白名单）/ `disabled`（排除）与全局超时字段（`initializeTimeoutMs` 等）继续可用。`enabled` 里的 id 必须是已注册服务器，否则视为配置错误；`disabled` 里未注册的 id 直接忽略。
+服务器记录里不认识的键会被忽略：历史配置中残留的 `"clangd": { "enabled": false }` 已无任何效果，要禁用某个已配置的服务器请改用顶层 `disabled`。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.448",
+  "version": "0.1.451",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

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/claude-code/files.ts

@@ -349,9 +349,9 @@ export function registerFileTools(
       }
       const snapshot = { ...snapshotOf(buffer), offset, limit };
       state.reads.set(key, snapshot);
-      // LSP warm-up 是后台任务，失败不影响读取
-      void service.touchFile(filePath, ctx.cwd).catch(() => {
-        // 后台 warm-up 失败不影响读取
+      // LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
+      void service.notifyFile(filePath, ctx.cwd).catch(() => {
+        // 后台通知失败不影响读取
       });
       return {
         content: [{ type: "text", text: formatted.text }],