@trim21/personal-pi-extensions 0.1.540 → 0.1.542

package/package.json

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

package/src/claude-code/edit.md

@@ -4,6 +4,7 @@ Performs exact string replacements in files.
 
 Usage:
 
+- You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
 - When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
 - ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
 - Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.

package/src/claude-code/files.ts

@@ -14,7 +14,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
-import { appendLspDiagnosticText } from "../lib/lsp/diagnostic.js";
+import { appendLspDiagnosticText, type DiagnosticReport } from "../lib/lsp/diagnostic.js";
 import { registerLspInspectTools } from "../lib/lsp/inspect-tool.js";
 import { createLspManager, type LspService, type LspServiceOptions } from "../lib/lsp/lsp.js";
 import { registerLspRenameTool } from "../lib/lsp/rename-tool.js";
@@ -199,9 +199,8 @@ async function readStateKey(filePath: string): Promise<string> {
 }
 
 /**
- * 校验「若曾读过则内容未变」。key 与 currentContent 由调用方提供：调用方每次
- * 工具调用只 realpath / readFile 一次，避免重复 IO。从未读过时直接放行，
- * 不强制先 Read；存在已读快照时校验文本可编辑且 digest 一致。
+ * 校验「已读且未变」。key 与 currentContent 由调用方提供：调用方每次工具调用
+ * 只 realpath / readFile 一次，避免重复 IO。
  */
 function requireCurrentRead(
   state: ClaudeCodeState,
@@ -210,7 +209,9 @@ function requireCurrentRead(
   currentContent: Uint8Array,
 ): void {
   const readSnapshot = state.reads.get(key);
-  if (!readSnapshot) return;
+  if (!readSnapshot) {
+    throw new Error("File has not been read yet. Read it first before writing to it.");
+  }
   if (!readSnapshot.textEditable) {
     throw new Error(`Cannot edit or overwrite a binary file with a text tool: ${filePath}`);
   }
@@ -331,18 +332,26 @@ export function registerFileTools(
       }
       const snapshot = snapshotOf(buffer);
       state.reads.set(key, snapshot);
-      // LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
-      void getService()
-        .notifyFile(filePath, ctx.cwd)
-        .catch(() => {
-          // 后台通知失败不影响读取
-        });
+      // 与 Edit / Write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
+      const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
+        notify: (message, level) => ctx.ui.notify(message, level),
+      });
       return {
-        content: [{ type: "text", text: formatted.text }],
+        content: [
+          {
+            type: "text",
+            text: appendLspDiagnosticText(formatted.text, diagnostics.text),
+          },
+        ],
         details: {
           reads: { [key]: snapshot },
           pendant: {
-            subtitle: formatSubtitlePath(ctx.cwd, filePath),
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              filePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
             title: "Read",
           } satisfies ToolPendant,
         },
@@ -355,6 +364,7 @@ export function registerFileTools(
     label: "Edit",
     description: [
       "Performs exact string replacements in files.",
+      "You must use Read on the file before editing it.",
       "old_string must match exactly and must be unique unless replace_all is true.",
       "This tool does not use regular expressions or fuzzy matching.",
     ].join("\n"),
@@ -385,178 +395,167 @@ export function registerFileTools(
           replaceAll: params.replace_all,
         },
       });
-      const [message, details, diagnosticText, errorCount, warningCount] =
-        await withFileMutationQueue<[string, FileToolDetails, string, number, number]>(
-          filePath,
-          async () => {
-            const oldString = params.old_string;
-            const newString = params.new_string;
-            if (oldString === newString) {
-              throw new Error(
-                "No changes to make: old_string and new_string are exactly the same.",
-              );
-            }
-            // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
-            if (oldString === "") {
-              let exists = true;
-              try {
-                const value = await stat(filePath);
-                if (value.isFile()) {
-                  const content = await readFile(filePath, "utf8");
-                  if (content.trim() !== "") {
-                    throw new Error("Cannot create new file - file already exists.");
-                  }
-                }
-              } catch (error) {
-                if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-                  exists = false;
-                } else {
-                  throw error;
-                }
-              }
-              if (!exists) await mkdir(dirname(filePath), { recursive: true });
-              await writeFile(filePath, newString, "utf8");
-              const snapshot = snapshotOf(newString);
-              const key = await readStateKey(filePath);
-              state.reads.set(key, snapshot);
-              const diff = generateDiffString("", convertLeadingTabsToSpaces(newString));
-              signal?.throwIfAborted();
-              const {
-                text: diagnosticText,
-                errorCount,
-                warningCount,
-              } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
-                notify: (message, level) => ctx.ui.notify(message, level),
-                signal,
-              });
-              return [
-                `The file ${filePath} has been updated successfully.`,
-                {
-                  diff: diff.diff,
-                  patch: generateUnifiedPatch(filePath, "", convertLeadingTabsToSpaces(newString)),
-                  firstChangedLine: diff.firstChangedLine,
-                  reads: { [key]: snapshot },
-                },
-                diagnosticText,
-                errorCount,
-                warningCount,
-              ];
-            }
-            const replaceAll = params.replace_all ?? false;
-            // 防止 OOM 的大文件检查（对齐 Claude Code）
-            try {
-              const { size } = await stat(filePath);
-              if (size > MAX_EDIT_FILE_SIZE) {
-                throw new Error(
-                  `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
-                );
-              }
-            } catch (error) {
-              if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-                throw error;
+      const [message, details, diagnostics] = await withFileMutationQueue<
+        [string, FileToolDetails, DiagnosticReport]
+      >(filePath, async () => {
+        const oldString = params.old_string;
+        const newString = params.new_string;
+        if (oldString === newString) {
+          throw new Error("No changes to make: old_string and new_string are exactly the same.");
+        }
+        // 空 old_string：创建新文件或填充空文件（不需要先 Read，对齐 Claude Code）
+        if (oldString === "") {
+          let exists = true;
+          try {
+            const value = await stat(filePath);
+            if (value.isFile()) {
+              const content = await readFile(filePath, "utf8");
+              if (content.trim() !== "") {
+                throw new Error("Cannot create new file - file already exists.");
               }
             }
-            let content: Buffer;
-            try {
-              content = await readFile(filePath);
-            } catch (error) {
-              if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-                const suggestion = await didYouMean(filePath, ctx.cwd);
-                throw new Error(
-                  `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
-                  { cause: error },
-                );
-              }
+          } catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+              exists = false;
+            } else {
               throw error;
             }
-            if (extname(filePath).toLowerCase() === ".ipynb") {
-              throw new Error(
-                "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
-              );
-            }
-            const key = await readStateKey(filePath);
-            requireCurrentRead(state, key, filePath, content);
-            await access(filePath, constants.R_OK | constants.W_OK);
-            signal?.throwIfAborted();
-            const original = content.toString("utf8");
-
-            // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
-            const crlfCount = (original.match(/\r\n/g) ?? []).length;
-            const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
-            const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
-            const normalized = original.replaceAll("\r\n", "\n");
-            const actualOldString = findActualString(normalized, oldString) ?? oldString;
-            const matches = normalized.split(actualOldString).length - 1;
-            if (matches === 0) {
-              throw new Error(`String to replace not found in file.\nString: ${oldString}`);
-            }
-            if (!replaceAll && matches > 1) {
-              throw new Error(
-                `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
-              );
-            }
-            const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
-            // 删除场景（new_string 为空）：old_string 不以换行结尾且文件里是
-            // "old_string\n" 时连换行一起删，避免留下空行（对齐 Claude Code
-            // applyEditToFile 的 stripTrailingNewline 语义）
-            let searchString = actualOldString;
-            if (
-              actualNewString === "" &&
-              !actualOldString.endsWith("\n") &&
-              normalized.includes(actualOldString + "\n")
-            ) {
-              searchString = actualOldString + "\n";
-            }
-            // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
-            const updated = replaceAll
-              ? normalized.split(searchString).join(actualNewString)
-              : normalized.replace(searchString, () => actualNewString);
-            const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
-            await writeFile(filePath, restored, "utf8");
-            const snapshot = snapshotOf(restored);
-            state.reads.set(key, snapshot);
-            // patch/diff 仅供显示：前导 tab 转空格，避免 UI 渲染错位（对齐 Claude Code）
-            const diff = generateDiffString(
+          }
+          if (!exists) await mkdir(dirname(filePath), { recursive: true });
+          await writeFile(filePath, newString, "utf8");
+          const snapshot = snapshotOf(newString);
+          const key = await readStateKey(filePath);
+          state.reads.set(key, snapshot);
+          const diff = generateDiffString("", convertLeadingTabsToSpaces(newString));
+          signal?.throwIfAborted();
+          const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
+            notify: (message, level) => ctx.ui.notify(message, level),
+            signal,
+          });
+          return [
+            `The file ${filePath} has been updated successfully.`,
+            {
+              diff: diff.diff,
+              patch: generateUnifiedPatch(filePath, "", convertLeadingTabsToSpaces(newString)),
+              firstChangedLine: diff.firstChangedLine,
+              reads: { [key]: snapshot },
+            },
+            diagnostics,
+          ];
+        }
+        const replaceAll = params.replace_all ?? false;
+        // 防止 OOM 的大文件检查（对齐 Claude Code）
+        try {
+          const { size } = await stat(filePath);
+          if (size > MAX_EDIT_FILE_SIZE) {
+            throw new Error(
+              `File is too large to edit (${formatFileSize(size)}). Maximum editable file size is ${formatFileSize(MAX_EDIT_FILE_SIZE)}.`,
+            );
+          }
+        } catch (error) {
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
+        }
+        let content: Buffer;
+        try {
+          content = await readFile(filePath);
+        } catch (error) {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            const suggestion = await didYouMean(filePath, ctx.cwd);
+            throw new Error(
+              `File does not exist. Note: your current working directory is ${ctx.cwd}.${suggestion ? ` Did you mean ${suggestion}?` : ""}`,
+              { cause: error },
+            );
+          }
+          throw error;
+        }
+        if (extname(filePath).toLowerCase() === ".ipynb") {
+          throw new Error(
+            "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
+          );
+        }
+        const key = await readStateKey(filePath);
+        requireCurrentRead(state, key, filePath, content);
+        await access(filePath, constants.R_OK | constants.W_OK);
+        signal?.throwIfAborted();
+        const original = content.toString("utf8");
+
+        // CRLF 规范化后匹配（old_string 不需要带 \r），写回时恢复原行尾
+        const crlfCount = (original.match(/\r\n/g) ?? []).length;
+        const lfCount = (original.match(/(?<!\r)\n/g) ?? []).length;
+        const lineEnding = crlfCount > lfCount ? "\r\n" : "\n";
+        const normalized = original.replaceAll("\r\n", "\n");
+        const actualOldString = findActualString(normalized, oldString) ?? oldString;
+        const matches = normalized.split(actualOldString).length - 1;
+        if (matches === 0) {
+          throw new Error(`String to replace not found in file.\nString: ${oldString}`);
+        }
+        if (!replaceAll && matches > 1) {
+          throw new Error(
+            `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${oldString}`,
+          );
+        }
+        const actualNewString = preserveQuoteStyle(oldString, actualOldString, newString);
+        // 删除场景（new_string 为空）：old_string 不以换行结尾且文件里是
+        // "old_string\n" 时连换行一起删，避免留下空行（对齐 Claude Code
+        // applyEditToFile 的 stripTrailingNewline 语义）
+        let searchString = actualOldString;
+        if (
+          actualNewString === "" &&
+          !actualOldString.endsWith("\n") &&
+          normalized.includes(actualOldString + "\n")
+        ) {
+          searchString = actualOldString + "\n";
+        }
+        // split/join 与函数替换：replacement 含 $ 时不会触发 $& 等特殊语义
+        const updated = replaceAll
+          ? normalized.split(searchString).join(actualNewString)
+          : normalized.replace(searchString, () => actualNewString);
+        const restored = lineEnding === "\r\n" ? updated.replaceAll("\n", "\r\n") : updated;
+        await writeFile(filePath, restored, "utf8");
+        const snapshot = snapshotOf(restored);
+        state.reads.set(key, snapshot);
+        // patch/diff 仅供显示：前导 tab 转空格，避免 UI 渲染错位（对齐 Claude Code）
+        const diff = generateDiffString(
+          convertLeadingTabsToSpaces(original),
+          convertLeadingTabsToSpaces(restored),
+        );
+        const text = replaceAll
+          ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
+          : `The file ${filePath} has been updated successfully.`;
+        signal?.throwIfAborted();
+        const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
+          notify: (message, level) => ctx.ui.notify(message, level),
+        });
+        return [
+          text,
+          {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(
+              filePath,
               convertLeadingTabsToSpaces(original),
               convertLeadingTabsToSpaces(restored),
-            );
-            const text = replaceAll
-              ? `The file ${filePath} has been updated. All occurrences were successfully replaced.`
-              : `The file ${filePath} has been updated successfully.`;
-            signal?.throwIfAborted();
-            const {
-              text: diagnosticText,
-              errorCount,
-              warningCount,
-            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
-              notify: (message, level) => ctx.ui.notify(message, level),
-            });
-            return [
-              text,
-              {
-                diff: diff.diff,
-                patch: generateUnifiedPatch(
-                  filePath,
-                  convertLeadingTabsToSpaces(original),
-                  convertLeadingTabsToSpaces(restored),
-                ),
-                firstChangedLine: diff.firstChangedLine,
-                reads: { [key]: snapshot },
-              },
-              diagnosticText,
-              errorCount,
-              warningCount,
-            ];
+            ),
+            firstChangedLine: diff.firstChangedLine,
+            reads: { [key]: snapshot },
           },
-        );
+          diagnostics,
+        ];
+      });
 
-      const text = appendLspDiagnosticText(message, diagnosticText, errorCount);
+      const text = appendLspDiagnosticText(message, diagnostics.text);
       return {
         content: [{ type: "text" as const, text }],
         details: {
           ...details,
           pendant: {
-            subtitle: formatSubtitlePath(ctx.cwd, filePath, errorCount, warningCount),
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              filePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
             title: "Edit",
           } satisfies ToolPendant,
         },
@@ -570,7 +569,7 @@ export function registerFileTools(
     description: [
       "Writes a file to the local filesystem.",
       "This tool overwrites an existing file with the full content provided.",
-      "Prefer Edit for partial changes.",
+      "If the file exists, you must use Read first. Prefer Edit for partial changes.",
     ].join("\n"),
     promptSnippet: "Create or overwrite files",
     promptGuidelines: [WRITE_PROMPT],
@@ -591,66 +590,65 @@ export function registerFileTools(
         absolutePath: filePath,
         change: { oldText: "", newText: params.content },
       });
-      const [message, details, diagnosticText, errorCount, warningCount] =
-        await withFileMutationQueue<[string, FileToolDetails, string, number, number]>(
-          filePath,
-          async () => {
-            let original: string | undefined;
-            let key: string | undefined;
-            try {
-              const value = await stat(filePath);
-              if (value.isFile()) {
-                const content = await readFile(filePath);
-                key = await readStateKey(filePath);
-                requireCurrentRead(state, key, filePath, content);
-                original = content.toString("utf8");
-              }
-            } catch (error) {
-              if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
-                throw error;
-              }
-            }
-            signal?.throwIfAborted();
-            await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, params.content, "utf8");
-            const snapshot = snapshotOf(params.content);
-            // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
-            const resolvedKey = key ?? (await readStateKey(filePath));
-            state.reads.set(resolvedKey, snapshot);
-            const diff = generateDiffString(original ?? "", params.content);
-            const text =
-              original === undefined
-                ? `File created successfully at: ${filePath}`
-                : `The file ${filePath} has been updated successfully.`;
-            signal?.throwIfAborted();
-            const {
-              text: diagnosticText,
-              errorCount,
-              warningCount,
-            } = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
-              notify: (message, level) => ctx.ui.notify(message, level),
-            });
-            return [
-              text,
-              {
-                diff: diff.diff,
-                patch: generateUnifiedPatch(filePath, original ?? "", params.content),
-                firstChangedLine: diff.firstChangedLine,
-                reads: { [resolvedKey]: snapshot },
-              },
-              diagnosticText,
-              errorCount,
-              warningCount,
-            ];
+      const [message, details, diagnostics] = await withFileMutationQueue<
+        [string, FileToolDetails, DiagnosticReport]
+      >(filePath, async () => {
+        let original: string | undefined;
+        let key: string | undefined;
+        try {
+          const value = await stat(filePath);
+          if (value.isFile()) {
+            const content = await readFile(filePath);
+            key = await readStateKey(filePath);
+            requireCurrentRead(state, key, filePath, content);
+            original = content.toString("utf8");
+          }
+        } catch (error) {
+          if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+          }
+        }
+        signal?.throwIfAborted();
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, params.content, "utf8");
+        const snapshot = snapshotOf(params.content);
+        // 新建文件：writeFile 之后 realpath 才能解析；覆盖写则复用上面的 key
+        const resolvedKey = key ?? (await readStateKey(filePath));
+        state.reads.set(resolvedKey, snapshot);
+        const diff = generateDiffString(original ?? "", params.content);
+        const text =
+          original === undefined
+            ? `File created successfully at: ${filePath}`
+            : `The file ${filePath} has been updated successfully.`;
+        signal?.throwIfAborted();
+        const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
+          notify: (message, level) => ctx.ui.notify(message, level),
+        });
+        return [
+          text,
+          {
+            diff: diff.diff,
+            patch: generateUnifiedPatch(filePath, original ?? "", params.content),
+            firstChangedLine: diff.firstChangedLine,
+            reads: { [resolvedKey]: snapshot },
           },
-        );
+          diagnostics,
+        ];
+      });
 
-      const text = appendLspDiagnosticText(message, diagnosticText, errorCount);
+      const text = appendLspDiagnosticText(message, diagnostics.text);
       return {
         content: [{ type: "text" as const, text }],
         details: {
           ...details,
-          pendant: { subtitle: formatSubtitlePath(ctx.cwd, filePath, errorCount, warningCount) },
+          pendant: {
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              filePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
+          },
         },
       };
     },
@@ -693,8 +691,8 @@ export default function claudeCodeFileTools(pi: ExtensionAPI, options?: LspServi
   const state = createClaudeCodeState();
 
   // LSP 专属工具（lsp-rename / inspect 族）仅在 lsp.json 存在 enabled 服务器时
-  // 注册（session_start 校验后）；本工具集维护 reads 记账，rename 落盘的文件
-  // 要标记为已读并随 details 持久化（restoreFileReads 依赖 details.reads）。
+  // 注册（session_start 校验后）；本工具集跟踪 read-before-write 状态，rename
+  // 落盘的文件要标记为已读并随 details 持久化（restoreFileReads 依赖 details.reads）。
   const manager = createLspManager(
     pi,
     {

package/src/claude-code/write.md

@@ -5,6 +5,7 @@ Writes a file to the local filesystem.
 Usage:
 
 - This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
 - Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
 - NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
 - Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

package/src/lib/lsp/diagnostic.ts

@@ -17,6 +17,20 @@ function severityOf(diagnostic: Diagnostic): number {
   return diagnostic.severity ?? 1;
 }
 
+/** 单个文件的诊断报告；计数覆盖该文件全部 ERROR / WARN，不受每文件上限影响。 */
+export interface DiagnosticReport {
+  /** 空字符串表示没有 ERROR / WARN。 */
+  text: string;
+  errorCount: number;
+  warningCount: number;
+}
+
+export const EMPTY_DIAGNOSTIC_REPORT: DiagnosticReport = {
+  text: "",
+  errorCount: 0,
+  warningCount: 0,
+};
+
 export function prettyDiagnostic(diagnostic: Diagnostic): string {
   const severity = SEVERITY_LABELS[severityOf(diagnostic)] ?? "ERROR";
   const line = diagnostic.range.start.line + 1;
@@ -27,25 +41,38 @@ export function prettyDiagnostic(diagnostic: Diagnostic): string {
   return `${severity} [${line}:${col}] ${message}`;
 }
 
-/** 返回空字符串表示没有 ERROR / WARN。ERROR 在前，WARN 在后。 */
-export function report(file: string, issues: Diagnostic[]): string {
+function pluralize(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** 未列出部分的构成：`3 errors, 4 warnings`（为 0 的一类省略；单复数按数量）。 */
+function hiddenSummary(hidden: Diagnostic[]): string {
+  const errors = hidden.filter((item) => severityOf(item) === 1).length;
+  const warnings = hidden.length - errors;
+  return [
+    ...(errors > 0 ? [pluralize(errors, "error")] : []),
+    ...(warnings > 0 ? [pluralize(warnings, "warning")] : []),
+  ].join(", ");
+}
+
+/** 返回空 text 表示没有 ERROR / WARN。ERROR 在前，WARN 在后，超出上限的部分只报数量。 */
+export function report(file: string, issues: Diagnostic[]): DiagnosticReport {
   const errors = issues.filter((item) => severityOf(item) === 1);
   const warnings = issues.filter((item) => item.severity === 2);
   const relevant = [...errors, ...warnings];
-  if (relevant.length === 0) return "";
+  if (relevant.length === 0) return EMPTY_DIAGNOSTIC_REPORT;
   const limited = relevant.slice(0, MAX_PER_FILE);
-  const more = relevant.length - MAX_PER_FILE;
-  const suffix = more > 0 ? `\n... and ${more} more` : "";
-  return `<diagnostics file="${file}">\n${limited.map((d) => prettyDiagnostic(d)).join("\n")}${suffix}\n</diagnostics>`;
+  const hidden = relevant.slice(MAX_PER_FILE);
+  const suffix = hidden.length > 0 ? `\n... and ${hiddenSummary(hidden)}` : "";
+  return {
+    text: `<diagnostics file="${file}">\n${limited.map((d) => prettyDiagnostic(d)).join("\n")}${suffix}\n</diagnostics>`,
+    errorCount: errors.length,
+    warningCount: warnings.length,
+  };
 }
 
 /** 把 LSP 诊断块接到工具成功文案后面；无诊断时原样返回。 */
-export function appendLspDiagnosticText(
-  message: string,
-  diagnosticText: string,
-  errorCount: number,
-): string {
-  if (!diagnosticText) return message;
-  const kind = errorCount > 0 ? "errors" : "warnings";
-  return `${message}\n\nLSP ${kind} detected in this file:\n${diagnosticText}`;
+export function appendLspDiagnosticText(message: string, diagnosticText: string): string {
+  if (diagnosticText === "") return message;
+  return `${message}\n\nLSP diagnostics detected in this file\n${diagnosticText}`;
 }

package/src/lib/lsp/lsp.ts

@@ -16,7 +16,7 @@
  *   的 id 直接忽略；
  * - client 按 (root, serverID) 缓存，并发 spawn 去重，启动失败记入
  *   broken（冷却期内跳过，冷却过后下次触碰自动重试）并主动 notify；
- * - 工具只与 touchFile / notifyFile / diagnostics / lspDiagnosticsForFile 四个方法打交道；通知回调按请求传入。
+ * - 工具只与 touchFile / diagnostics / lspDiagnosticsForFile 三个方法打交道；通知回调按请求传入。
  */
 
 import { readFileSync } from "node:fs";
@@ -43,7 +43,7 @@ import {
   WATCH_KIND_CREATE,
   WATCH_KIND_DELETE,
 } from "./client.js";
-import { report } from "./diagnostic.js";
+import { type DiagnosticReport, EMPTY_DIAGNOSTIC_REPORT, report } from "./diagnostic.js";
 import {
   createAdapters,
   matchesInclude,
@@ -397,14 +397,13 @@ export interface LspService {
     diagnostics?: "document" | "full",
     options?: LspRequestOptions,
   ): Promise<void>;
-  /** read 用：只发文件事件通知服务器磁盘上有该文件，不驻留、不等诊断。 */
-  notifyFile(file: string, cwd: string, options?: LspRequestOptions): Promise<void>;
   diagnostics(): Promise<Record<string, Diagnostic[]>>;
+  /** read / edit / write 用：等待文档诊断并返回该文件的 ERROR / WARN 报告与计数。 */
   lspDiagnosticsForFile(
     file: string,
     cwd: string,
     options?: LspRequestOptions,
-  ): Promise<{ text: string; errorCount: number; warningCount: number }>;
+  ): Promise<DiagnosticReport>;
   /**
    * 符号重命名：只面向 kind 为 "language" 的服务器（linter 不参与符号级
    * 功能）；多 client 按配置顺序取第一个成功结果，全部失败时抛聚合错误。
@@ -736,7 +735,7 @@ export function createLspService(
   /**
    * 记录一次启动失败：进入 broken（冷却期内跳过）、渲染 status，并按节流
    * 间隔主动 notify。错误上报优先走会话级 sessionNotify——不依赖触发请求
-   * 恰好携带 notify（否则 Read warm-up 等静默通道会把失败吞掉）；未注入
+   * 恰好携带 notify（否则 opencode 工具集等不带请求级 notify 的通道会把失败吞掉）；未注入
    * 会话通知时退回请求级 notify 兜底。
    */
   function reportStartupFailure(
@@ -881,7 +880,7 @@ export function createLspService(
 
   /**
    * 打开文档让服务器索引 / 产出诊断。diagnostics 传 "document" 时最多等 5s，
-   * "full" 最多等 10s；不传则只通知不等待（read 的 warm-up 用）。
+   * "full" 最多等 10s；不传则只 didOpen 不等待。
    */
   async function touchFile(
     file: string,
@@ -923,37 +922,19 @@ export function createLspService(
   }
 
   /**
-   * read 的 warm-up：通知服务器磁盘上有这个文件（D5），不 didOpen 驻留、不等诊断。
-   * 驻留文档若磁盘已被外部改写会顺带触发退场。
-   */
-  async function notifyFile(file: string, cwd: string, options?: LspRequestOptions): Promise<void> {
-    const clients = await getClients(file, cwd, options?.notify);
-    await Promise.all(
-      clients.map((client) =>
-        client.notify.watchedFiles([{ path: file, type: "changed", isDirectory: false }]),
-      ),
-    ).catch(() => {
-      // 文件事件通知失败不影响读取
-    });
-  }
-
-  /**
-   * edit/write 用：等待文档诊断并返回该文件的 ERROR / WARN 报告（text 空串表示无此类诊断）
-   * 与数量。内部所有 LSP 失败都会被吞掉，不干扰写操作本身。
+   * read / edit / write 用：等待文档诊断并返回该文件的 ERROR / WARN 报告（text 空串表示无此类诊断）
+   * 与数量。内部所有 LSP 失败都会被吞掉，不干扰读取或写操作本身。
    */
   async function lspDiagnosticsForFile(
     file: string,
     cwd: string,
     options?: LspRequestOptions,
-  ): Promise<{ text: string; errorCount: number; warningCount: number }> {
-    if (options?.signal?.aborted) return { text: "", errorCount: 0, warningCount: 0 };
+  ): Promise<DiagnosticReport> {
+    if (options?.signal?.aborted) return EMPTY_DIAGNOSTIC_REPORT;
     await touchFile(file, cwd, "document", options);
     const all = await diagnostics();
     const normalized = normalize(file);
-    const issues = all[normalized] ?? [];
-    const errorCount = issues.filter((item) => (item.severity ?? 1) === 1).length;
-    const warningCount = issues.filter((item) => item.severity === 2).length;
-    return { text: report(normalized, issues), errorCount, warningCount };
+    return report(normalized, all[normalized] ?? []);
   }
 
   /** 符号重命名：只面向 language 类服务器；按配置顺序取第一个成功结果。 */
@@ -1184,7 +1165,6 @@ export function createLspService(
 
   return {
     touchFile,
-    notifyFile,
     diagnostics,
     lspDiagnosticsForFile,
     rename,

package/src/opencode/files.ts

@@ -7,7 +7,7 @@
  *
  * 对齐官方 v1（packages/opencode/src/tool/{read,edit,write}.ts）：
  * - read：流式分行（LF / CRLF / CR）、每行 `N: ` 行号前缀、单行 2000
- *   字符截断、1 起始 offset、目录排序；读取后后台 LSP warm-up。
+ *   字符截断、1 起始 offset、目录排序；读取后等待并报告该文档的诊断。
  *   不接 PDF、不接 <system-reminder>；图片 magic 检测保留。
  * - edit：匹配引擎 + 把 old/new 转到文件换行后再替换；写后等待文档诊断。
  * - write：BOM 保留（source.bom || next.bom）；写后同 edit 的诊断输出。
@@ -431,20 +431,29 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService): void
         outputText = `${header}${numbered}\n\n(End of file - total ${page.count} lines)${footer}`;
       }
 
-      content = [{ type: "text", text: outputText }];
-
-      // opencode: LSP 文件事件通知是后台任务，失败不影响读取（read 不驻留文档）
-      void getService()
-        .notifyFile(absolutePath, ctx.cwd)
-        .catch(() => {
-          // 后台通知失败不影响读取
-        });
+      // opencode: 与 edit / write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
+      const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
+        signal,
+      });
+      content = [
+        {
+          type: "text",
+          text: appendLspDiagnosticText(outputText, diagnostics.text),
+        },
+      ];
 
       return {
         content,
         details: {
           ...details,
-          pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) },
+          pendant: {
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              absolutePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
+          },
         },
       };
     },
@@ -497,8 +506,9 @@ function registerEditTool(pi: ExtensionAPI, getService: () => LspService): void
         change: { oldText: oldString, newText: newString, replaceAll },
       });
 
-      const [message, details, diagnosticText, errorCount, warningCount] =
-        await withFileMutationQueue(absolutePath, async () => {
+      const [message, details, diagnostics] = await withFileMutationQueue(
+        absolutePath,
+        async () => {
           signal?.throwIfAborted();
 
           // opencode: 前置校验，先于空 oldString 分支
@@ -523,17 +533,13 @@ function registerEditTool(pi: ExtensionAPI, getService: () => LspService): void
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
-            const {
-              text: diagnosticText,
-              errorCount,
-              warningCount,
-            } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+            const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
+              signal,
+            });
             return [
               "Edit applied successfully.",
               { diff: "", patch: "", firstChangedLine: 0 },
-              diagnosticText,
-              errorCount,
-              warningCount,
+              diagnostics,
             ] as const;
           }
 
@@ -565,27 +571,29 @@ function registerEditTool(pi: ExtensionAPI, getService: () => LspService): void
           const diffNew = normalizeToLF(applied.contentNew);
           const diffResult = generateDiffString(diffOld, diffNew);
           const patch = generateUnifiedPatch(filePath, diffOld, diffNew);
-          const {
-            text: diagnosticText,
-            errorCount,
-            warningCount,
-          } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+          const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
+            signal,
+          });
           return [
             "Edit applied successfully.",
             { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
-            diagnosticText,
-            errorCount,
-            warningCount,
+            diagnostics,
           ] as const;
-        });
+        },
+      );
 
-      const text = appendLspDiagnosticText(message, diagnosticText, errorCount);
+      const text = appendLspDiagnosticText(message, diagnostics.text);
       return {
         content: [{ type: "text" as const, text }],
         details: {
           ...details,
           pendant: {
-            subtitle: formatSubtitlePath(ctx.cwd, absolutePath, errorCount, warningCount),
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              absolutePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
           },
         },
       };
@@ -641,8 +649,9 @@ function registerWriteTool(pi: ExtensionAPI, getService: () => LspService): void
       });
       const dir = dirname(absolutePath);
 
-      const [message, details, diagnosticText, errorCount, warningCount] =
-        await withFileMutationQueue(absolutePath, async () => {
+      const [message, details, diagnostics] = await withFileMutationQueue(
+        absolutePath,
+        async () => {
           signal?.throwIfAborted();
 
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
@@ -665,28 +674,26 @@ function registerWriteTool(pi: ExtensionAPI, getService: () => LspService): void
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
           await writeFile(absolutePath, desiredBom + nextText, "utf8");
-          const {
-            text: diagnosticText,
-            errorCount,
-            warningCount,
-          } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+          const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
+            signal,
+          });
 
-          return [
-            "Wrote file successfully.",
-            {},
-            diagnosticText,
-            errorCount,
-            warningCount,
-          ] as const;
-        });
+          return ["Wrote file successfully.", {}, diagnostics] as const;
+        },
+      );
 
-      const text = appendLspDiagnosticText(message, diagnosticText, errorCount);
+      const text = appendLspDiagnosticText(message, diagnostics.text);
       return {
         content: [{ type: "text" as const, text }],
         details: {
           ...details,
           pendant: {
-            subtitle: formatSubtitlePath(ctx.cwd, absolutePath, errorCount, warningCount),
+            subtitle: formatSubtitlePath(
+              ctx.cwd,
+              absolutePath,
+              diagnostics.errorCount,
+              diagnostics.warningCount,
+            ),
           },
         },
       };