@trim21/personal-pi-extensions 0.1.642 → 0.1.644

package/package.json

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

package/src/claude-code/files.ts

@@ -17,7 +17,8 @@ import {
   createReadsState,
   type FileSnapshot,
   type ReadsState,
-  readStateKey,
+  recordRead,
+  recordReads,
   requireCurrentRead,
   restoreReads,
   snapshotOf,
@@ -247,13 +248,11 @@ export function registerFileTools(
           { type: "text", text: `Read image file [${imageMime}]` },
           { type: "image", data, mimeType: imageMime },
         ];
-        const snapshot = snapshotOf(image, false);
-        const key = await readStateKey(filePath);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, filePath, snapshotOf(image, false));
         return {
           content,
           details: {
-            reads: { [key]: snapshot },
+            reads,
             pendant: {
               subtitle: formatSubtitlePath(ctx.cwd, filePath),
               title: "Read",
@@ -264,7 +263,6 @@ export function registerFileTools(
 
       const offset = params.offset ?? 1;
       const limit = params.limit;
-      const key = await readStateKey(filePath);
       const buffer = await readFile(filePath);
 
       if (isBinary(buffer.subarray(0, SAMPLE_BYTES))) {
@@ -285,8 +283,7 @@ export function registerFileTools(
           `File content (${estimatedTokens} tokens) exceeds maximum allowed tokens (${MAX_READ_TOKENS}). Use offset and limit parameters to read specific portions of the file, or search for specific content instead of reading the whole file.`,
         );
       }
-      const snapshot = snapshotOf(buffer);
-      state.reads.set(key, snapshot);
+      const reads = await recordRead(state, filePath, snapshotOf(buffer));
       // 与 Edit / Write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
         notify: (message, level) => ctx.ui.notify(message, level),
@@ -300,7 +297,7 @@ export function registerFileTools(
           },
         ],
         details: {
-          reads: { [key]: snapshot },
+          reads,
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -384,9 +381,7 @@ export function registerFileTools(
             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 reads = await recordRead(state, filePath, snapshotOf(newString));
           const diff = generateDiffString("", convertLeadingTabsToSpaces(newString));
           signal?.throwIfAborted();
           const diagnostics = await getService().lspDiagnosticsForFile(filePath, ctx.cwd, {
@@ -399,7 +394,7 @@ export function registerFileTools(
               diff: diff.diff,
               patch: generateUnifiedPatch(filePath, "", convertLeadingTabsToSpaces(newString)),
               firstChangedLine: diff.firstChangedLine,
-              reads: { [key]: snapshot },
+              reads,
             },
             diagnostics,
           ];
@@ -436,8 +431,7 @@ export function registerFileTools(
             "File is a Jupyter Notebook. Use the NotebookEditTool to edit this file.",
           );
         }
-        const key = await readStateKey(filePath);
-        requireCurrentRead(state, key, filePath, content);
+        await requireCurrentRead(state, filePath, content);
         await access(filePath, constants.R_OK | constants.W_OK);
         signal?.throwIfAborted();
         const original = content.toString("utf8");
@@ -450,8 +444,7 @@ export function registerFileTools(
           signal,
         });
         await writeFile(filePath, restored, "utf8");
-        const snapshot = snapshotOf(restored);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, filePath, snapshotOf(restored));
         // patch/diff 仅供显示：前导 tab 转空格，避免 UI 渲染错位（对齐 Claude Code）
         const diff = generateDiffString(
           convertLeadingTabsToSpaces(original),
@@ -475,7 +468,7 @@ export function registerFileTools(
               convertLeadingTabsToSpaces(restored),
             ),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [key]: snapshot },
+            reads,
           },
           diagnostics,
         ];
@@ -527,13 +520,11 @@ export function registerFileTools(
         [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);
+            await requireCurrentRead(state, filePath, content);
             original = content.toString("utf8");
           }
         } catch (error) {
@@ -552,10 +543,7 @@ export function registerFileTools(
         });
         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 reads = await recordRead(state, filePath, snapshotOf(params.content));
         const diff = generateDiffString(original ?? "", params.content);
         const text =
           original === undefined
@@ -572,7 +560,7 @@ export function registerFileTools(
             diff: diff.diff,
             patch: generateUnifiedPatch(filePath, original ?? "", params.content),
             firstChangedLine: diff.firstChangedLine,
-            reads: { [resolvedKey]: snapshot },
+            reads,
           },
           diagnostics,
         ];
@@ -639,16 +627,14 @@ export default function claudeCodeFileTools(
       onEnabled: (pi, service) => {
         registerLspRenameTool(pi, service, {
           policy,
-          recordReads: async (applied) => {
-            const reads: Record<string, FileSnapshot> = {};
-            for (const fileEdit of applied) {
-              const key = await readStateKey(fileEdit.path);
-              const snapshot = snapshotOf(fileEdit.newText);
-              state.reads.set(key, snapshot);
-              reads[key] = snapshot;
-            }
-            return reads;
-          },
+          recordReads: (applied) =>
+            recordReads(
+              state,
+              applied.map((fileEdit) => ({
+                path: fileEdit.path,
+                snapshot: snapshotOf(fileEdit.newText),
+              })),
+            ),
         });
         registerLspInspectTools(pi, service);
       },

package/src/lib/file-reads.ts

@@ -6,11 +6,15 @@
  * - 工具名集合：claude-code 是大写 Read/Edit/Write，opencode 是小写；
  * - 指纹来源：claude-code 手里已有内容，直接 snapshotOf(content)；opencode 的
  *   read 是流式分页读取，整文件指纹用 fileDigest(path)。
+ *
+ * 记账 key 的解析与读写由本模块独占（readStateKey / recordRead / require*），
+ * 调用点只给路径与快照，不自己拼 details 里的 map。
  */
 
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { realpath } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
@@ -72,32 +76,73 @@ export async function digestIfExists(filePath: string): Promise<string | undefin
 }
 
 /**
- * 记账 key：解析 symlink 后的真实路径。文件尚不存在（Write 新建 / Edit 空
- * old_string 创建）时 realpath 抛 ENOENT，回退到调用方给出的路径。
+ * 记账 key：解析 symlink 后的真实路径。文件尚未落盘（Write 新建 / Edit 空
+ * old_string 创建）时向上找到最深的已存在祖先、解析它再把剩余路径段拼回去——
+ * 结果与文件落盘后 realpath(filePath) 相同，因此调用点不必关心算 key 的时机
+ * （写入路径尤其容易在创建分支上算早）。
  */
 export async function readStateKey(filePath: string): Promise<string> {
-  try {
-    return await realpath(filePath);
-  } catch (error) {
-    if (isMissingPath(error)) {
+  const pending: string[] = [];
+  let current = filePath;
+  for (;;) {
+    try {
+      return join(await realpath(current), ...pending.toReversed());
+    } catch (error) {
+      if (!isMissingPath(error)) {
+        throw error;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      // 一路到文件系统根仍不存在：无法解析，回退调用方给出的路径
       return filePath;
     }
-    throw error;
+    pending.push(basename(current));
+    current = parent;
   }
 }
 
+/**
+ * 记账「这些文件的内容即各自的 snapshot」：解析 key 写入 state，返回可直接放进
+ * 工具 details 的 reads 片段。
+ *
+ * 这一侧是对象而不是 Map：details 是 JSON（宿主按 `JsonValue` 写进 session
+ * JSONL），Map 序列化过去会变成 `{}`，记账就丢了；读取方向与之相对（
+ * `deserializeReads` 从同一个对象形状还原成 Map）。
+ */
+export async function recordReads(
+  state: ReadsState,
+  entries: readonly { path: string; snapshot: FileSnapshot }[],
+): Promise<Record<string, FileSnapshot>> {
+  const reads: Record<string, FileSnapshot> = {};
+  for (const entry of entries) {
+    const key = await readStateKey(entry.path);
+    state.reads.set(key, entry.snapshot);
+    reads[key] = entry.snapshot;
+  }
+  return reads;
+}
+
+/** 单文件记账：`recordReads` 的单项形式。 */
+export async function recordRead(
+  state: ReadsState,
+  filePath: string,
+  snapshot: FileSnapshot,
+): Promise<Record<string, FileSnapshot>> {
+  return await recordReads(state, [{ path: filePath, snapshot }]);
+}
+
 function snapshotsEqual(left: FileSnapshot, right: FileSnapshot): boolean {
   return left.digest === right.digest;
 }
 
 /** 校验「已读且未变」：未读过、非文本、指纹不符都拒绝写入。 */
-export function requireCurrentRead(
+export async function requireCurrentRead(
   state: ReadsState,
-  key: string,
   filePath: string,
   currentContent: Uint8Array | string,
-): void {
-  const readSnapshot = state.reads.get(key);
+): Promise<void> {
+  const readSnapshot = state.reads.get(await readStateKey(filePath));
   if (!readSnapshot) {
     throw new Error("File has not been read yet. Read it first before writing to it.");
   }
@@ -113,21 +158,17 @@ export function requireCurrentRead(
 
 /**
  * 过期校验：该文件已有读取记录时，要求磁盘上的当前指纹与记录一致，否则拒绝
- * 写入；从未读过（没有记录）时直接放行。
+ * 写入；从未读过（没有记录）时直接放行，且不做整文件指纹计算。
  *
  * opencode 的 write 用这个：没读过的文件允许直接写，读过之后再被外部改动就必须
- * 重新 read。`currentDigest` 为 undefined（文件已不存在）同样算过期。
+ * 重新 read。文件已不存在（指纹 undefined）同样算过期。
  */
-export function requireUnchangedRead(
-  state: ReadsState,
-  key: string,
-  currentDigest: string | undefined,
-): void {
-  const readSnapshot = state.reads.get(key);
+export async function requireUnchangedRead(state: ReadsState, filePath: string): Promise<void> {
+  const readSnapshot = state.reads.get(await readStateKey(filePath));
   if (!readSnapshot) {
     return;
   }
-  if (currentDigest === undefined || readSnapshot.digest !== currentDigest) {
+  if (readSnapshot.digest !== (await digestIfExists(filePath))) {
     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.",
     );

package/src/lib/lsp/client.ts

@@ -282,21 +282,33 @@ export const clientDefaults = {
   maxOpenDocuments: 32,
 } as const;
 
-export interface CreateInput {
+/**
+ * 客户端可调项的唯一定义：`create()` 的覆盖参数、`lsp.ts` 的 `ResolvedLspConfig`
+ * 与 `resolveConfig` 共用同一份字段集合，新增旋钮只需在这里声明一次即可被
+ * 配置解析与客户端构造同时要求。超时均为解析后的毫秒数，缺省值见 clientDefaults。
+ */
+export interface LspClientOptions {
+  /** push 诊断去抖（ms）。 */
+  diagnosticsDebounceMs: number;
+  /** document 模式诊断等待上限（ms）。 */
+  diagnosticsDocumentWaitTimeoutMs: number;
+  /** 上一份诊断为空的文档的等待上限（ms）；缺省见 clientDefaults。 */
+  diagnosticsSilentWaitTimeoutMs: number;
+  /** full 模式诊断等待上限（ms）。 */
+  diagnosticsFullWaitTimeoutMs: number;
+  /** 单次 pull 诊断请求超时（ms）。 */
+  diagnosticsRequestTimeoutMs: number;
+  /** 服务器 initialize 握手超时（ms）。 */
+  initializeTimeoutMs: number;
+  /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
+  maxOpenDocuments: number;
+}
+
+export interface CreateInput extends Partial<LspClientOptions> {
   serverID: string;
   server: LspServerHandle;
   root: string;
   directory: string;
-  /** 可覆盖的超时参数（缺省用 client 默认值，由全局/本地 lsp.json 配置注入）。 */
-  diagnosticsDebounceMs?: number;
-  diagnosticsDocumentWaitTimeoutMs?: number;
-  /** 上一份诊断为空的文档的等待上限；缺省见 clientDefaults。 */
-  diagnosticsSilentWaitTimeoutMs?: number;
-  diagnosticsFullWaitTimeoutMs?: number;
-  diagnosticsRequestTimeoutMs?: number;
-  initializeTimeoutMs?: number;
-  /** 驻留文档上限（LRU 容量，缺省 32）；超过时淘汰最久未使用并 didClose。 */
-  maxOpenDocuments?: number;
   /** 覆盖 rename 覆盖校验的轮询节奏（缺省见 DEFAULT_RENAME_VERIFICATION_TIMING）。 */
   renameVerificationTiming?: Partial<RenameVerificationTiming>;
 }

package/src/lib/lsp/lsp.ts

@@ -37,6 +37,7 @@ import {
   type Diagnostic,
   type Info as LspClient,
   type InspectLocation,
+  type LspClientOptions,
   LspMethodNotSupportedError,
   RenameNotPossibleError,
   WATCH_KIND_CHANGE,
@@ -68,7 +69,7 @@ const watchConfigSchema = Type.Object({
   ignore: Type.Optional(Type.Array(Type.String())),
 });
 
-/** lsp.json 的配置项（全局与本地同构；只描述用户可写的原始形态，缺省见 configDefaults）。 */
+/** lsp.json 的配置项（全局与本地同构；只描述用户可写的原始形态，缺省见 watchDefaults / clientDefaults）。 */
 const lspConfigSchema = Type.Object({
   /** 配置文件版本（当前 1）；未知版本会被 typebox 严格校验拒绝。 */
   version: Type.Optional(Type.Number()),
@@ -78,7 +79,7 @@ const lspConfigSchema = Type.Object({
   enabled: Type.Optional(Type.Array(Type.String())),
   /** 从启用集中排除的服务器 id（缺省 = 无）。 */
   disabled: Type.Optional(Type.Array(Type.String())),
-  /** 工作区文件监听配置（缺省全部字段见 configDefaults.watch）。 */
+  /** 工作区文件监听配置（缺省全部字段见 watchDefaults）。 */
   watch: Type.Optional(watchConfigSchema),
   /** 驻留文档上限（LRU 容量），超过时淘汰最久未使用并 didClose。 */
   maxOpenDocuments: Type.Optional(Type.Number({ minimum: 1 })),
@@ -99,18 +100,12 @@ const lspConfigSchema = Type.Object({
 /** 配置值（单文件解析结果）；超时字段为原始写法（number 或字符串），换算在 resolveConfig。 */
 export type LspConfig = Static<typeof lspConfigSchema>;
 
-/**
- * 解析期缺省（单一来源）。超时/LRU 与 client.create 共用 clientDefaults；
- * watch 无 client 对应项，数值在此集中。
- */
-const configDefaults = {
-  watch: {
-    enabled: true,
-    debounceMs: 300,
-    flushMs: 1_000,
-    maxBatch: 500,
-  },
-  maxOpenDocuments: clientDefaults.maxOpenDocuments,
+/** 解析期缺省：watch 段（无 client 对应项，数值在此集中）；客户端参数缺省见 clientDefaults。 */
+const watchDefaults = {
+  enabled: true,
+  debounceMs: 300,
+  flushMs: 1_000,
+  maxBatch: 500,
 } as const;
 
 /** 服务器启动失败后自动重试的冷却（ms）；冷却内跳过，之后下次触碰自动重试。 */
@@ -127,8 +122,12 @@ interface EffectiveWatchConfig {
   ignore: string[];
 }
 
-/** 全局 + 本地合并并解析后的生效配置：所有字段为确定值，无"未配置"歧义。 */
-export interface ResolvedLspConfig {
+/**
+ * 全局 + 本地合并并解析后的生效配置：所有字段为确定值，无"未配置"歧义。
+ * 客户端参数的整体形状复用 `LspClientOptions`（定义在 client.ts，与
+ * `create()` 的覆盖参数同源），因此这里不再逐字段重声明。
+ */
+export interface ResolvedLspConfig extends LspClientOptions {
   /** 合并后的服务器定义（未配置任何服务器时为空表）。 */
   servers: Record<string, ServerConfig>;
   /** enabled 白名单（undefined = 全部启用）。 */
@@ -137,15 +136,6 @@ export interface ResolvedLspConfig {
   disabled: Set<string> | undefined;
   /** 工作区监听配置（缺省值已应用）。 */
   watch: EffectiveWatchConfig;
-  /** 驻留文档 LRU 容量。 */
-  maxOpenDocuments: number;
-  /** 以下超时均为换算后的毫秒数（缺省见 configDefaults / clientDefaults）。 */
-  diagnosticsDebounceMs: number;
-  diagnosticsDocumentWaitTimeoutMs: number;
-  diagnosticsSilentWaitTimeoutMs: number;
-  diagnosticsFullWaitTimeoutMs: number;
-  diagnosticsRequestTimeoutMs: number;
-  initializeTimeoutMs: number;
 }
 
 /** "500" → 500、"5s" → 5000、"1m" → 60000；无效字符串返回 NaN（由调用方兜底缺省）。 */
@@ -177,7 +167,7 @@ function toMs(value: number | string | undefined): number | undefined {
 }
 
 /**
- * 把合并后的原始配置解析为生效配置：应用 configDefaults 缺省、字符串时长换算、
+ * 把合并后的原始配置解析为生效配置：应用 watchDefaults / clientDefaults 缺省、字符串时长换算、
  * 白名单转 Set；per-server 的 workingDir / rootMarkers 互斥校验在此完成
  * （配置解析期抛错，与 enabled 白名单校验同层）。
  */
@@ -195,13 +185,13 @@ export function resolveConfig(raw: LspConfig): ResolvedLspConfig {
     enabled: raw.enabled === undefined ? undefined : new Set(raw.enabled),
     disabled: raw.disabled === undefined ? undefined : new Set(raw.disabled),
     watch: {
-      enabled: raw.watch?.enabled ?? configDefaults.watch.enabled,
-      debounceMs: toMs(raw.watch?.debounceMs) ?? configDefaults.watch.debounceMs,
-      flushMs: configDefaults.watch.flushMs,
-      maxBatch: raw.watch?.maxBatch ?? configDefaults.watch.maxBatch,
+      enabled: raw.watch?.enabled ?? watchDefaults.enabled,
+      debounceMs: toMs(raw.watch?.debounceMs) ?? watchDefaults.debounceMs,
+      flushMs: watchDefaults.flushMs,
+      maxBatch: raw.watch?.maxBatch ?? watchDefaults.maxBatch,
       ignore: raw.watch?.ignore ?? [],
     },
-    maxOpenDocuments: raw.maxOpenDocuments ?? configDefaults.maxOpenDocuments,
+    maxOpenDocuments: raw.maxOpenDocuments ?? clientDefaults.maxOpenDocuments,
     diagnosticsDebounceMs: toMs(raw.diagnosticsDebounceMs) ?? clientDefaults.diagnosticsDebounceMs,
     diagnosticsDocumentWaitTimeoutMs:
       toMs(raw.diagnosticsDocumentWaitTimeoutMs) ?? clientDefaults.diagnosticsDocumentWaitTimeoutMs,
@@ -848,19 +838,22 @@ export function createLspService(
           reportStartupFailure(key, adapter.id, root, "binary not found", notify);
           return;
         }
+        const overrides: Partial<LspClientOptions> = {};
+        if (adapter.diagnosticsWaitMs !== undefined) {
+          overrides.diagnosticsDocumentWaitTimeoutMs = adapter.diagnosticsWaitMs;
+        }
+        if (adapter.startupTimeoutMs !== undefined) {
+          overrides.initializeTimeoutMs = adapter.startupTimeoutMs;
+        }
         const client = await create({
           serverID: adapter.id,
           server: handle,
           root,
           directory: cwd,
-          diagnosticsDebounceMs: config.diagnosticsDebounceMs,
-          diagnosticsDocumentWaitTimeoutMs:
-            adapter.diagnosticsWaitMs ?? config.diagnosticsDocumentWaitTimeoutMs,
-          diagnosticsSilentWaitTimeoutMs: config.diagnosticsSilentWaitTimeoutMs,
-          diagnosticsFullWaitTimeoutMs: config.diagnosticsFullWaitTimeoutMs,
-          diagnosticsRequestTimeoutMs: config.diagnosticsRequestTimeoutMs,
-          initializeTimeoutMs: adapter.startupTimeoutMs ?? config.initializeTimeoutMs,
-          maxOpenDocuments: config.maxOpenDocuments,
+          // 客户端参数整体取自生效配置（ResolvedLspConfig extends LspClientOptions），
+          // 不做逐字段搬运：新增旋钮时漏接线会静默失效，这里靠展开消除该位置。
+          ...config,
+          ...overrides,
         });
         if (state.closing || state.disabled) {
           await client.shutdown();

package/src/opencode/files.ts

@@ -38,11 +38,11 @@ import { Type } from "typebox";
 
 import {
   createReadsState,
-  digestIfExists,
   fileDigest,
   type FileSnapshot,
   type ReadsState,
-  readStateKey,
+  recordRead,
+  recordReads,
   requireCurrentRead,
   requireUnchangedRead,
   restoreReads,
@@ -500,13 +500,11 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
           { type: "text", text: "Image read successfully" },
           { type: "image", data: base64, mimeType },
         ];
-        const key = await readStateKey(absolutePath);
-        const snapshot = snapshotOf(buffer, false);
-        state.reads.set(key, snapshot);
+        const reads = await recordRead(state, absolutePath, snapshotOf(buffer, false));
         return {
           content,
           details: {
-            reads: { [key]: snapshot },
+            reads,
             pendant: { subtitle: formatSubtitlePath(ctx.cwd, absolutePath) },
           },
         };
@@ -521,7 +519,6 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
 
       // 记账指纹先于分页读取：文件若在读取期间被改动，指纹对应的是改动前的
       // 内容，后续 edit 会要求重新 read（失败方向安全）。
-      const key = await readStateKey(absolutePath);
       const snapshot: FileSnapshot = { digest: await fileDigest(absolutePath), textEditable: true };
 
       const effectiveOffset = offset || 1;
@@ -555,7 +552,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
         outputText = `${header}${numbered}\n\n(End of file - total ${page.count} lines)${footer}`;
       }
 
-      state.reads.set(key, snapshot);
+      const reads = await recordRead(state, absolutePath, snapshot);
 
       // opencode: 与 edit / write 同一条驻留路径：didOpen 后等待该文件的诊断并报告
       const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
@@ -572,7 +569,7 @@ function registerReadTool(pi: ExtensionAPI, getService: () => LspService, state:
         content,
         details: {
           ...details,
-          reads: { [key]: snapshot },
+          reads,
           pendant: {
             subtitle: formatSubtitlePath(
               ctx.cwd,
@@ -667,16 +664,14 @@ function registerEditTool(
             await mkdir(dirname(absolutePath), { recursive: true });
             signal?.throwIfAborted();
             await writeFile(absolutePath, newString, "utf8");
-            // 新建文件无需先 read（无处可读），写后记账；realpath 要等文件落盘
-            const key = await readStateKey(absolutePath);
-            const snapshot = snapshotOf(newString);
-            state.reads.set(key, snapshot);
+            // 新建文件无需先 read（无处可读），写后记账
+            const reads = await recordRead(state, absolutePath, snapshotOf(newString));
             const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
               signal,
             });
             return [
               "Edit applied successfully.",
-              { diff: "", patch: "", firstChangedLine: 0, reads: { [key]: snapshot } },
+              { diff: "", patch: "", firstChangedLine: 0, reads },
               diagnostics,
             ] as const;
           }
@@ -702,8 +697,7 @@ function registerEditTool(
 
           // 指纹校验必须发生在写入之前：未 read 或外部已改动都拒绝编辑
           const rawContent = await readFile(absolutePath, "utf8");
-          const key = await readStateKey(absolutePath);
-          requireCurrentRead(state, key, absolutePath, rawContent);
+          await requireCurrentRead(state, absolutePath, rawContent);
 
           const applied = applyEdit(rawContent, oldString, newString, replaceAll);
           signal?.throwIfAborted();
@@ -715,8 +709,7 @@ function registerEditTool(
             signal,
           });
           await writeFile(absolutePath, applied.finalContent, "utf8");
-          const snapshot = snapshotOf(applied.finalContent);
-          state.reads.set(key, snapshot);
+          const reads = await recordRead(state, absolutePath, snapshotOf(applied.finalContent));
 
           const diffOld = normalizeToLF(applied.contentOld);
           const diffNew = normalizeToLF(applied.contentNew);
@@ -731,7 +724,7 @@ function registerEditTool(
               diff: diffResult.diff,
               patch,
               firstChangedLine: diffResult.firstChangedLine,
-              reads: { [key]: snapshot },
+              reads,
             },
             diagnostics,
           ] as const;
@@ -811,12 +804,9 @@ function registerWriteTool(
         async () => {
           signal?.throwIfAborted();
 
-          const key = await readStateKey(absolutePath);
           // write 不要求先读过；但若已有读取记录，磁盘内容必须仍是读取时的样子，
           // 否则先重新 read（外部改动过的文件不让盲写覆盖）
-          if (state.reads.has(key)) {
-            requireUnchangedRead(state, key, await digestIfExists(absolutePath));
-          }
+          await requireUnchangedRead(state, absolutePath);
 
           // opencode: desiredBom = source.bom || next.bom —— 保留原文件 BOM，
           // 否则用新内容自带的 BOM。旧内容整读一次，既是 BOM 的来源，也是审批预览
@@ -842,14 +832,13 @@ function registerWriteTool(
           await mkdir(dir, { recursive: true });
           signal?.throwIfAborted();
           await writeFile(absolutePath, finalContent, "utf8");
-          // 写后记账（key 在写入前已算过）：紧接着的 edit 不该再要求重新 read
-          const snapshot = snapshotOf(finalContent);
-          state.reads.set(key, snapshot);
+          // 写后记账：紧接着的 edit 不该再要求重新 read
+          const reads = await recordRead(state, absolutePath, snapshotOf(finalContent));
           const diagnostics = await getService().lspDiagnosticsForFile(absolutePath, ctx.cwd, {
             signal,
           });
 
-          return ["Wrote file successfully.", { reads: { [key]: snapshot } }, diagnostics] as const;
+          return ["Wrote file successfully.", { reads }, diagnostics] as const;
         },
       );
 
@@ -906,16 +895,14 @@ export default function opencodeFileTools(
       onEnabled: (pi, service) => {
         registerLspRenameTool(pi, service, {
           policy,
-          recordReads: async (applied) => {
-            const reads: Record<string, FileSnapshot> = {};
-            for (const fileEdit of applied) {
-              const key = await readStateKey(fileEdit.path);
-              const snapshot = snapshotOf(fileEdit.newText);
-              state.reads.set(key, snapshot);
-              reads[key] = snapshot;
-            }
-            return reads;
-          },
+          recordReads: (applied) =>
+            recordReads(
+              state,
+              applied.map((fileEdit) => ({
+                path: fileEdit.path,
+                snapshot: snapshotOf(fileEdit.newText),
+              })),
+            ),
         });
         registerLspInspectTools(pi, service);
       },