@trim21/personal-pi-extensions 0.1.540 → 0.1.541

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.540",
+  "version": "0.1.541",
   "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

@@ -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,25 @@ 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 {
+        text: diagnosticText,
+        errorCount,
+        warningCount,
+      } = 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, diagnosticText, errorCount),
+          },
+        ],
         details: {
           reads: { [key]: snapshot },
           pendant: {
-            subtitle: formatSubtitlePath(ctx.cwd, filePath),
+            subtitle: formatSubtitlePath(ctx.cwd, filePath, errorCount, warningCount),
             title: "Read",
           } satisfies ToolPendant,
         },
@@ -355,6 +363,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"),
@@ -570,7 +579,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],
@@ -693,8 +702,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/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";
@@ -397,9 +397,8 @@ 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,
@@ -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,23 +922,8 @@ 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,
@@ -1184,7 +1168,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,26 @@ 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 {
+        text: diagnosticText,
+        errorCount,
+        warningCount,
+      } = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, { signal });
+      content = [
+        {
+          type: "text",
+          text: appendLspDiagnosticText(outputText, diagnosticText, errorCount),
+        },
+      ];
 
       return {
         content,
         details: {
           ...details,
-          pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) },
+          pendant: {
+            subtitle: formatSubtitlePath(ctx.cwd, absolutePath, errorCount, warningCount),
+          },
         },
       };
     },