@trim21/personal-pi-extensions 0.1.448 → 0.1.451

package/src/lib/lsp/watcher.ts

@@ -0,0 +1,174 @@
+/**
+ * 工作区文件监听器：单个递归 fs.watch + 去抖批量回调。
+ *
+ * - 事件源用 `node:fs/promises` 的 `watch(dir, { recursive: true, signal })`，
+ *   不引入 chokidar（与仓库"FS 一律用 node:fs/promises"约定一致）；
+ * - create / delete / rename 在底层都表现为 `rename`，内容改动为 `change`，
+ *   故 LSP 的 created / changed / deleted 类型由 `lstat` 判定；
+ * - 尾部去抖（缺省 300ms）合并短时洪峰，最长 flushMs（缺省 1s）强制清批；
+ * - 内置忽略 `node_modules` / `.git` / `dist` / `build` / `.venv` / `venv` /
+ *   `target` / `coverage`，配置可追加；
+ * - 单批超过 maxBatch（缺省 500）截断并回调 onTruncated 提示一次；
+ * - 目录事件默认丢弃；目录被删除时上报（isDirectory: true），由上层对其中
+ *   的驻留文档补 deleted 事件。监听器启动或运行期失败时调用 onError 降级，
+ *   不抛错。
+ */
+
+import { lstat, watch } from "node:fs/promises";
+import { join, normalize, relative, sep } from "node:path";
+
+import { minimatch } from "minimatch";
+
+export type FileChangeType = "created" | "changed" | "deleted";
+
+export interface FileChange {
+  /** 绝对路径（normalized）。 */
+  path: string;
+  type: FileChangeType;
+  /** 目录被删除时 true（created/changed 目录事件默认不上报）。 */
+  isDirectory: boolean;
+}
+
+export const DEFAULT_IGNORE = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.venv/**",
+  "**/venv/**",
+  "**/target/**",
+  "**/coverage/**",
+];
+
+export interface WatchOptions {
+  /** 尾部去抖窗口（ms，缺省 300）。 */
+  debounceMs?: number;
+  /** 从首个事件起的最长 flush 间隔（ms，缺省 1_000）。 */
+  flushMs?: number;
+  /** 单批上限，超出截断（缺省 500）。 */
+  maxBatch?: number;
+  /** 追加忽略 glob（相对工作区根的 POSIX 路径）。 */
+  ignore?: string[];
+  /** 监听器不可用（无法启动 / 运行期失败）时的降级提示回调。 */
+  onError?: (message: string) => void;
+  /** 单批超限被截断时回调（提示一次，不逐条刷屏）。 */
+  onTruncated?: () => void;
+}
+
+export interface WorkspaceWatcher {
+  stop(): Promise<void>;
+}
+
+function isIgnored(path: string, dir: string, patterns: string[]): boolean {
+  const candidate = relative(dir, path).split(sep).join("/");
+  if (candidate.startsWith("..")) return false;
+  return patterns.some((pattern) => minimatch(candidate, pattern));
+}
+
+/**
+ * 启动对 dir 的递归监听。onBatch 收到去抖合并后的批次；stop 后不再回调。
+ * 返回的 promise 只在监听器无法建立（目录不存在等）时 reject——运行期
+ * 错误一律走 onError 降级。
+ */
+export function watchWorkspace(
+  dir: string,
+  onBatch: (changes: FileChange[]) => void,
+  options?: WatchOptions,
+): Promise<WorkspaceWatcher> {
+  const debounceMs = options?.debounceMs ?? 300;
+  const flushMs = options?.flushMs ?? 1_000;
+  const maxBatch = options?.maxBatch ?? 500;
+  const ignorePatterns = [...DEFAULT_IGNORE, ...(options?.ignore ?? [])];
+  const abort = new AbortController();
+
+  // 从 stat 成功事件学习已知目录，目录被删除时据此标记 isDirectory
+  const seenDirectories = new Set<string>();
+
+  let pending: FileChange[] = [];
+  let flushTimer: ReturnType<typeof setTimeout> | undefined;
+  let maxTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const clearTimers = (): void => {
+    if (flushTimer) clearTimeout(flushTimer);
+    if (maxTimer) clearTimeout(maxTimer);
+    flushTimer = undefined;
+    maxTimer = undefined;
+  };
+
+  const flush = (): void => {
+    clearTimers();
+    if (pending.length === 0) return;
+    let batch = pending;
+    pending = [];
+    if (batch.length > maxBatch) {
+      batch = batch.slice(0, maxBatch);
+      options?.onTruncated?.();
+    }
+    onBatch(batch);
+  };
+
+  const push = (change: FileChange): void => {
+    if (pending.length === 0) maxTimer = setTimeout(flush, flushMs);
+    pending.push(change);
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flush, debounceMs);
+  };
+
+  const classify = async (
+    filename: string,
+    eventType: "rename" | "change",
+  ): Promise<FileChange | undefined> => {
+    const path = normalize(join(dir, filename));
+    if (path === dir) return undefined;
+    let isDirectory = false;
+    let exists = true;
+    try {
+      const info = await lstat(path);
+      isDirectory = info.isDirectory();
+      if (isDirectory) seenDirectories.add(path);
+    } catch {
+      exists = false;
+      if (seenDirectories.delete(path)) isDirectory = true;
+    }
+    if (eventType === "change") {
+      if (!exists) return { path, type: "deleted", isDirectory };
+      if (isDirectory) return undefined;
+      return { path, type: "changed", isDirectory };
+    }
+    // rename：创建 / 删除 / 移入移出
+    if (!exists) return { path, type: "deleted", isDirectory };
+    if (isDirectory) return undefined;
+    return { path, type: "created", isDirectory };
+  };
+
+  const consumer = (async () => {
+    try {
+      const iterator = watch(dir, { recursive: true, signal: abort.signal });
+      for await (const event of iterator) {
+        if (!event.filename) continue;
+        const change = await classify(
+          event.filename,
+          event.eventType === "change" ? "change" : "rename",
+        );
+        if (!change) continue;
+        if (isIgnored(change.path, dir, ignorePatterns)) continue;
+        push(change);
+      }
+    } catch (error) {
+      if (abort.signal.aborted) return;
+      options?.onError?.(`workspace watcher failed for ${dir}: ${String(error)}`);
+    }
+  })();
+
+  // 目录不存在 / 无权限等启动期问题在这里暴露，让调用方可以降级
+  return lstat(dir).then(() => ({
+    async stop(): Promise<void> {
+      abort.abort();
+      try {
+        await consumer;
+      } catch {
+        // 监听器已因 abort 正常退出
+      }
+    },
+  }));
+}

package/src/opencode/files.ts

@@ -431,9 +431,9 @@ function registerReadTool(pi: ExtensionAPI, service: LspService): void {
 
       content = [{ type: "text", text: outputText }];
 
-      // opencode: LSP warm-up 是后台任务，失败不影响读取
-      void service.touchFile(absolutePath, ctx.cwd).catch(() => {
-        // 后台 warm-up 失败不影响读取
+      // opencode: LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
+      void service.notifyFile(absolutePath, ctx.cwd).catch(() => {
+        // 后台通知失败不影响读取
       });
 
       return {

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,
-        },
-      };
-    },
-  });
-}