@trim21/personal-pi-extensions 0.1.575 → 0.1.577

package/README.md

@@ -138,7 +138,9 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 
 所有匹配策略按顺序尝试，第一个匹配成功即返回。同时自动处理 BOM、CRLF/LF 行尾转换和文件写入队列。`filePath` 接受绝对路径或相对工作目录的路径。
 
-edit 要求目标文件已被 `read` 读过且内容未变（内容指纹比对，与 Claude Code 风格 Edit 同一套语义）：没读过报 `File has not been read yet. Read it first before editing it.`，读后文件被外部改动报 `File has been modified since read...`，两种情况都要重新 `read`。`read`/`edit`/`write`/`lsp-rename` 都会刷新记账并随工具结果持久化，session 恢复 / fork / rewind 后依然有效；`write` 本身不要求先读，但写后会刷新记账，紧随其后的 `edit` 不必重新读。
+edit 要求目标文件已被 `read` 读过且内容未变（内容指纹比对，与 Claude Code 风格 Edit 同一套语义）：没读过报 `File has not been read yet. Read it first before writing to it.`，读后文件被外部改动报 `File has been modified since read...`，两种情况都要重新 `read`。
+
+`write` 不要求先读——没读过的文件可以直接写；但如果该文件已被读过、之后又被外部改动（或删除），`write` 会与 `edit` 一样要求重新 `read`，不让读取记录过期的内容被盲覆盖。`read`/`edit`/`write`/`lsp-rename` 都会刷新记账并随工具结果持久化，session 恢复 / fork / rewind 后依然有效；写完也会刷新，紧随其后的 `edit` 不必重新读。
 
 ### 使用
 

package/package.json

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

package/src/lib/file-reads.ts

@@ -45,6 +45,25 @@ export async function fileDigest(filePath: string): Promise<string> {
   return hash.digest("hex");
 }
 
+/** ENOENT / ENOTDIR：路径不存在。 */
+function isMissingPath(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+/** 磁盘上当前内容的指纹；文件已不存在时返回 undefined（视为「与读取时不同」）。 */
+export async function digestIfExists(filePath: string): Promise<string | undefined> {
+  try {
+    return await fileDigest(filePath);
+  } catch (error) {
+    if (isMissingPath(error)) return undefined;
+    throw error;
+  }
+}
+
 /**
  * 记账 key：解析 symlink 后的真实路径。文件尚不存在（Write 新建 / Edit 空
  * old_string 创建）时 realpath 抛 ENOENT，回退到调用方给出的路径。
@@ -53,13 +72,7 @@ export async function readStateKey(filePath: string): Promise<string> {
   try {
     return await realpath(filePath);
   } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error.code === "ENOENT" || error.code === "ENOTDIR")
-    ) {
-      return filePath;
-    }
+    if (isMissingPath(error)) return filePath;
     throw error;
   }
 }
@@ -89,6 +102,27 @@ export function requireCurrentRead(
   }
 }
 
+/**
+ * 过期校验：该文件已有读取记录时，要求磁盘上的当前指纹与记录一致，否则拒绝
+ * 写入；从未读过（没有记录）时直接放行。
+ *
+ * opencode 的 write 用这个：没读过的文件允许直接写，读过之后再被外部改动就必须
+ * 重新 read。`currentDigest` 为 undefined（文件已不存在）同样算过期。
+ */
+export function requireUnchangedRead(
+  state: ReadsState,
+  key: string,
+  currentDigest: string | undefined,
+): void {
+  const readSnapshot = state.reads.get(key);
+  if (!readSnapshot) return;
+  if (currentDigest === undefined || readSnapshot.digest !== currentDigest) {
+    throw new Error(
+      "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.",
+    );
+  }
+}
+
 /**
  * 从工具结果 details 恢复已读记账（跨进程 resume / reload / fork）。数据来自
  * session 文件，可能缺失或损坏：逐条 TypeBox 校验，非法条目丢弃。只接受

package/src/lib/lsp/client.ts

@@ -307,6 +307,16 @@ interface ServerCapabilities {
 export const clientDefaults = {
   diagnosticsDebounceMs: 150,
   diagnosticsDocumentWaitTimeoutMs: 5_000,
+  /**
+   * document 模式等待上限的补充：该文档上一份诊断为空（服务器手里是干净文档）时，
+   * 内容变化后只用这段安静期等新 push，不再等满 diagnosticsDocumentWaitTimeoutMs。
+   *
+   * typescript-language-server 的 FileDiagnostics.update 在「该类诊断上一轮为空、
+   * 这一轮仍为空」时直接 return 不推送，且它不实现 pull 诊断；这类文档等满整个
+   * 窗口也只会在窗口末尾返回同样的「无诊断」，白等一次编辑。诊断集合变成非空时
+   * 服务器必定推送，所以短安静期不会漏掉这次变更引入的错误。
+   */
+  diagnosticsSilentWaitTimeoutMs: 1_500,
   diagnosticsFullWaitTimeoutMs: 10_000,
   diagnosticsRequestTimeoutMs: 3_000,
   initializeTimeoutMs: 45_000,
@@ -321,6 +331,8 @@ export interface CreateInput {
   /** 可覆盖的超时参数（缺省用 client 默认值，由全局/本地 lsp.json 配置注入）。 */
   diagnosticsDebounceMs?: number;
   diagnosticsDocumentWaitTimeoutMs?: number;
+  /** 上一份诊断为空的文档的等待上限；缺省见 clientDefaults。 */
+  diagnosticsSilentWaitTimeoutMs?: number;
   diagnosticsFullWaitTimeoutMs?: number;
   diagnosticsRequestTimeoutMs?: number;
   initializeTimeoutMs?: number;
@@ -522,6 +534,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
   const diagnosticsDebounceMs = input.diagnosticsDebounceMs ?? clientDefaults.diagnosticsDebounceMs;
   const diagnosticsDocumentWaitTimeoutMs =
     input.diagnosticsDocumentWaitTimeoutMs ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs;
+  const diagnosticsSilentWaitTimeoutMs =
+    input.diagnosticsSilentWaitTimeoutMs ?? clientDefaults.diagnosticsSilentWaitTimeoutMs;
   const diagnosticsFullWaitTimeoutMs =
     input.diagnosticsFullWaitTimeoutMs ?? clientDefaults.diagnosticsFullWaitTimeoutMs;
   const diagnosticsRequestTimeoutMs =
@@ -599,6 +613,8 @@ export async function create(input: CreateInput): Promise<LspClient> {
         at: Date.now(),
         version: typeof params.version === "number" ? params.version : undefined,
       });
+      const document = files[filePath];
+      if (document !== undefined) document.lastPushEmpty = params.diagnostics.length === 0;
       updatePushDiagnostics(filePath, params.diagnostics);
     },
   );
@@ -702,7 +718,15 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("workspace/didChangeConfiguration", { settings });
   }
 
-  const files: Record<string, { version: number; text: string } | undefined> = {};
+  /**
+   * syncedAt：最后一次把该文档内容同步给服务器的时刻（didOpen / didChange）。
+   * lastPushEmpty：服务器对该文档最近一次 push 是否为空（无诊断），随驻留记录
+   * 一起在 didClose 时清除——只在当前驻留周期内成立。
+   */
+  const files: Record<
+    string,
+    { version: number; text: string; syncedAt: number; lastPushEmpty?: boolean } | undefined
+  > = {};
 
   // ── 驻留 LRU ────────────────────────────────────────────────────────────────
 
@@ -1009,7 +1033,20 @@ export async function create(input: CreateInput): Promise<LspClient> {
     after?: number;
     signal?: AbortSignal;
   }): Promise<void> {
+    // 服务器对当前内容的最新结论已在手（最后一次 push 晚于最后一次内容同步，
+    // 即此后没有再通知过内容变化）：直接返回已有结果。部分服务器在诊断集合
+    // 不变时不再推送（typescript-language-server 空→空不发布），等新 push 只会
+    // 耗满整个窗口后得到同样的「无诊断」。
+    const known = published.get(request.path);
+    const document = files[request.path];
+    if (known !== undefined && document !== undefined && known.at >= document.syncedAt) return;
+
     const startedAt = request.after ?? Date.now();
+    // 「上一份 push 为空」的文档用短安静期（见 clientDefaults.diagnosticsSilentWaitTimeoutMs）。
+    const budget =
+      files[request.path]?.lastPushEmpty === true
+        ? Math.min(diagnosticsDocumentWaitTimeoutMs, diagnosticsSilentWaitTimeoutMs)
+        : diagnosticsDocumentWaitTimeoutMs;
     // pull 与 push 语义相同：都是等「当前文档版本」的诊断结果，统一一个循环。
     // 先 pull（拿到即返回）；pull 超时说明服务器未响应，不再重试 pull，只等
     // 版本匹配的 push 兜底；版本不匹配的 push 一律忽略（防迟到旧结果）。
@@ -1017,11 +1054,11 @@ export async function create(input: CreateInput): Promise<LspClient> {
       path: request.path,
       version: request.version,
       after: startedAt,
-      timeout: diagnosticsDocumentWaitTimeoutMs,
+      timeout: budget,
     });
 
     while (!connectionClosed && !request.signal?.aborted) {
-      const remaining = diagnosticsDocumentWaitTimeoutMs - (Date.now() - startedAt);
+      const remaining = budget - (Date.now() - startedAt);
       if (remaining <= 0) return;
       const result = await requestDocumentDiagnostics(request.path);
       if (result.matched) return;
@@ -1088,13 +1125,21 @@ export async function create(input: CreateInput): Promise<LspClient> {
 
     const document = files[resolvedPath];
     if (document !== undefined) {
+      // 内容与服务器已知文本一致：不重复通知（didChange 会把已有诊断判为过期，
+      // 而部分服务器对内容未产生新结论的文档不再推送，见 diagnosticsSilentWaitTimeoutMs）。
+      if (document.text === text) {
+        touch(resolvedPath);
+        return document.version;
+      }
+
       // didChange：内容已变，旧诊断立即失效。清空缓存避免等待窗口内服务器
       // 重算未完成时（大项目可远超窗口）聚合到过期诊断；新 push 到达即填充。
       pushDiagnostics.delete(resolvedPath);
       pullDiagnostics.delete(resolvedPath);
 
       const next = document.version + 1;
-      files[resolvedPath] = { version: next, text };
+      // 保留 lastPushEmpty：安静期判据看的是「变更前服务器最后一份结论是否为空」
+      files[resolvedPath] = { ...document, version: next, text, syncedAt: Date.now() };
       documentVersions.set(resolvedPath, next);
       await connection.sendNotification("textDocument/didChange", {
         textDocument: { uri, version: next },
@@ -1118,7 +1163,7 @@ export async function create(input: CreateInput): Promise<LspClient> {
     await connection.sendNotification("textDocument/didOpen", {
       textDocument: { uri, languageId, version: 0, text },
     });
-    files[resolvedPath] = { version: 0, text };
+    files[resolvedPath] = { version: 0, text, syncedAt: Date.now() };
     documentVersions.set(resolvedPath, 0);
     touch(resolvedPath);
     await evictExcess();

package/src/lib/lsp/lsp.ts

@@ -86,6 +86,8 @@ const lspConfigSchema = Type.Object({
   diagnosticsDebounceMs: Type.Optional(timeoutValue),
   /** document 模式诊断等待上限（ms）。 */
   diagnosticsDocumentWaitTimeoutMs: Type.Optional(timeoutValue),
+  /** 上一份诊断为空的文档的等待上限（ms）；见 clientDefaults.diagnosticsSilentWaitTimeoutMs。 */
+  diagnosticsSilentWaitTimeoutMs: Type.Optional(timeoutValue),
   /** full 模式诊断等待上限（ms）。 */
   diagnosticsFullWaitTimeoutMs: Type.Optional(timeoutValue),
   /** 单次 pull 诊断请求超时（ms）。 */
@@ -140,6 +142,7 @@ export interface ResolvedLspConfig {
   /** 以下超时均为换算后的毫秒数（缺省见 configDefaults / clientDefaults）。 */
   diagnosticsDebounceMs: number;
   diagnosticsDocumentWaitTimeoutMs: number;
+  diagnosticsSilentWaitTimeoutMs: number;
   diagnosticsFullWaitTimeoutMs: number;
   diagnosticsRequestTimeoutMs: number;
   initializeTimeoutMs: number;
@@ -198,6 +201,8 @@ export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
     diagnosticsDebounceMs: toMs(raw.diagnosticsDebounceMs) ?? clientDefaults.diagnosticsDebounceMs,
     diagnosticsDocumentWaitTimeoutMs:
       toMs(raw.diagnosticsDocumentWaitTimeoutMs) ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs,
+    diagnosticsSilentWaitTimeoutMs:
+      toMs(raw.diagnosticsSilentWaitTimeoutMs) ?? clientDefaults.diagnosticsSilentWaitTimeoutMs,
     diagnosticsFullWaitTimeoutMs:
       toMs(raw.diagnosticsFullWaitTimeoutMs) ?? clientDefaults.diagnosticsFullWaitTimeoutMs,
     diagnosticsRequestTimeoutMs:
@@ -791,6 +796,7 @@ export function createLspService(
           diagnosticsDebounceMs: config.diagnosticsDebounceMs,
           diagnosticsDocumentWaitTimeoutMs:
             adapter.diagnosticsWaitMs ?? config.diagnosticsDocumentWaitTimeoutMs,
+          diagnosticsSilentWaitTimeoutMs: config.diagnosticsSilentWaitTimeoutMs,
           diagnosticsFullWaitTimeoutMs: config.diagnosticsFullWaitTimeoutMs,
           diagnosticsRequestTimeoutMs: config.diagnosticsRequestTimeoutMs,
           initializeTimeoutMs: adapter.startupTimeoutMs ?? config.initializeTimeoutMs,

package/src/opencode/files.ts

@@ -11,8 +11,9 @@
  *   不接 PDF、不接 <system-reminder>；图片 magic 检测保留。
  * - edit：匹配引擎 + 把 old/new 转到文件换行后再替换；写后等待文档诊断。
  *   edit 要求文件已被 read 读过且内容未变（read 记账见下）。
- * - write：BOM 保留（source.bom || next.bom）；写后同 edit 的诊断输出。write 本身
- *   不要求先 read，但会刷新记账，保证紧接着的 edit 不必重新 read。
+ * - write：BOM 保留（source.bom || next.bom）；写后同 edit 的诊断输出。write 不
+ *   要求先 read（未读过的文件可直接写），但若已有读取记录而磁盘内容已变，则要求
+ *   重新 read；写完刷新记账，保证紧接着的 edit 不必重新 read。
  *
  * read 记账：read / edit / write / lsp-rename 各自把受影响文件的内容指纹写进
  * details.reads（随 session 持久化），session_start / session_tree 时从当前分支
@@ -37,11 +38,13 @@ import { Type } from "typebox";
 
 import {
   createReadsState,
+  digestIfExists,
   fileDigest,
   type FileSnapshot,
   type ReadsState,
   readStateKey,
   requireCurrentRead,
+  requireUnchangedRead,
   restoreReads,
   snapshotOf,
 } from "../lib/file-reads.js";
@@ -790,6 +793,13 @@ function registerWriteTool(
         async () => {
           signal?.throwIfAborted();
 
+          const key = await readStateKey(absolutePath);
+          // write 不要求先读过；但若已有读取记录，磁盘内容必须仍是读取时的样子，
+          // 否则先重新 read（外部改动过的文件不让盲写覆盖）
+          if (state.reads.has(key)) {
+            requireUnchangedRead(state, key, await digestIfExists(absolutePath));
+          }
+
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
           // 否则用新内容自带的 BOM
           let existing: Buffer | undefined;
@@ -810,8 +820,7 @@ function registerWriteTool(
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
           await writeFile(absolutePath, desiredBom + nextText, "utf8");
-          // write 不要求先 read，但写后记账：紧接着的 edit 不该再要求重新 read
-          const key = await readStateKey(absolutePath);
+          // 写后记账（key 在写入前已算过）：紧接着的 edit 不该再要求重新 read
           const snapshot = snapshotOf(desiredBom + nextText);
           state.reads.set(key, snapshot);
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {

package/src/skills/lsp-config/SKILL.md

@@ -27,12 +27,13 @@ description: Use when 编写、检查或排查 LSP 语言服务器配置 ——
 
 ```
 version / servers / enabled / disabled / watch / maxOpenDocuments /
-diagnosticsDebounceMs / diagnosticsDocumentWaitTimeoutMs /
+diagnosticsDebounceMs / diagnosticsDocumentWaitTimeoutMs / diagnosticsSilentWaitTimeoutMs /
 diagnosticsFullWaitTimeoutMs / diagnosticsRequestTimeoutMs / initializeTimeoutMs
 ```
 
 - `enabled`：只启用列出的服务器 id（缺省 = 全部启用）；`disabled`：从启用集中排除
-- 时长字段：毫秒数字，或带单位的字符串（`"300ms"` / `"5s"` / `"1m"` / `"2h"`，空单位按 ms）；默认值见 `clientDefaults`（client.ts）：debounce 150ms、document 等待 5s、full 等待 10s、pull 请求 3s、initialize 45s、`maxOpenDocuments` 32
+- 时长字段：毫秒数字，或带单位的字符串（`"300ms"` / `"5s"` / `"1m"` / `"2h"`，空单位按 ms）；默认值见 `clientDefaults`（client.ts）：debounce 150ms、document 等待 5s、安静期 1.5s、full 等待 10s、pull 请求 3s、initialize 45s、`maxOpenDocuments` 32
+- `diagnosticsSilentWaitTimeoutMs`：只用于「该文档上一份诊断为空」的情形——内容变化后最多只等这段安静期，不再等满 `diagnosticsDocumentWaitTimeoutMs`。typescript-language-server 在诊断集合空→空时不重复推送且不实现 pull 诊断，这类文档等满整个窗口也只会得到同样的「无诊断」，白等一次编辑；集合变成非空时服务器必定推送，所以调小它不会漏掉变更引入的错误，调大则更保守（默认 1.5s，约等于实测热态推送延迟的三倍）。设为不小于 `diagnosticsDocumentWaitTimeoutMs` 即等价于不做这个缩短
 - `watch`：`enabled` / `debounceMs`（缺省 300）/ `maxBatch`（缺省 500）/ `ignore`（glob，相对**每个被监听的项目根**的 POSIX 路径）。注意 `flushMs` 只在默认值里、**不可配**
 - 监听范围不是整个 cwd，而是**当前活跃服务器 client 的项目根**：root 在 cwd 内就只监听 root（被其他 root 包含的 root 不重复监听，root 是 cwd 的祖先时退化为 cwd）；没有活跃 client 就不监听。因此容器 cwd（`~/projects` 下多个仓库）里只有活跃服务器所在的项目会被 watch；`ignore` 的匹配基准也随之是各自的项目根。资源耗尽（ENOSPC）时该 root 的监听器会停止并提示一次，调大 `fs.inotify.max_user_watches` 后跑 `/lsp-reload` 重试