local-diff-reviewer 4.0.0 → 4.0.2

package/README.md

@@ -143,7 +143,13 @@ npx --yes local-diff-reviewer \
 
 `thread` 评论会以 `author: "agent"` 写入：如果同一锚点已经存在 thread，会作为新的 comment 追加进去；否则创建 replied thread。`reply` 会向目标 thread 追加一条 agent 回复并把状态切到 replied。为避免 agent finding 反复注入导致刷屏，同一 thread 内相同正文的 agent comment 会被视为重复并跳过。若路径不在当前 diff 中、行号无法定位或内容重复，脚本会跳过并在终端打印 warning。
 
-当 agent 收到从 UI 复制出的 `[thread:<id>]` prompt 并完成处理后，应使用 `type: "reply"` 把处理结果写回原 thread，作为 `author: "agent"` 的 comment 保留在评论流里。回复内容应简要说明已修改什么，或说明为什么没有修改。
+当 agent 收到从 UI 复制出的 `[thread:<id>]` prompt 并完成处理后，应使用 `type: "reply"` 把处理结果写回原 thread，作为 `author: "agent"` 的 comment 保留在评论流里。回复内容默认保持结论式、尽量短：
+
+- 已按评论完成修改时，优先使用 `已处理`。
+- 需要补充一点点定位信息时，可使用 `已处理：xxx`。
+- 未修改时，再简短说明原因，例如 `未处理：当前实现已覆盖该场景。`
+
+除非用户明确需要更详细的回写说明，否则不要重复整段 diff、实现细节或长篇解释。
 
 从 UI 复制出的 prompt 示例：
 

package/SKILL.md

@@ -36,7 +36,7 @@ npx --yes local-diff-reviewer [args...] \
 
 After a newly started script prints a local URL, open it in the Codex browser when available. If the script reports `Diff Review refreshed`, do not open another page: the already open review page updates automatically. If browser automation is not available, report the URL.
 
-When the user gives you copied prompt text containing `[thread:<id>]`, treat it as an existing review thread. After you answer or make code/doc changes for that thread, append a concise agent reply to the same thread with `--comment '{"type":"reply","threadId":"<id>","body":"..."}'` the next time you launch or refresh the viewer. If the viewer is already running and you can reach the API, post the same reply to `/api/threads/<id>/comments` with `author: "agent"`. Do this for every handled thread unless the user explicitly asks you not to write back. The reply should say what changed or why no change was made, not repeat the full diff.
+When the user gives you copied prompt text containing `[thread:<id>]`, treat it as an existing review thread. After you answer or make code/doc changes for that thread, append a concise agent reply to the same thread with `--comment '{"type":"reply","threadId":"<id>","body":"..."}'` the next time you launch or refresh the viewer. If the viewer is already running and you can reach the API, post the same reply to `/api/threads/<id>/comments` with `author: "agent"`. Do this for every handled thread unless the user explicitly asks you not to write back. Prefer conclusion-first, minimal replies such as `已处理`, `已处理：xxx`, or `未处理：原因...`; do not repeat the full diff or long implementation details unless the user explicitly wants that detail.
 
 ## Review Scope
 

package/dist/cli/start.js

@@ -8,7 +8,7 @@ import { basename as basename3, dirname as dirname3, join as join5, resolve as r
 import { fileURLToPath } from "node:url";
 
 // src/server/storage.ts
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { homedir, platform } from "node:os";
 import { basename, dirname, join } from "node:path";
@@ -46,38 +46,71 @@ function getMergedThreadStatus(threads) {
 }
 
 // src/server/storage.ts
+var commentWriteQueues = /* @__PURE__ */ new Map();
 async function readComments(repoRoot) {
   return readCommentStore(repoRoot);
 }
-async function attachLegacyComments(repoRoot, diffHash2, diffFiles) {
-  const store = await readCommentStore(repoRoot);
-  let changed = false;
-  for (const thread of store.threads) {
-    if (!thread.diffHash) {
-      thread.diffHash = diffHash2;
-      changed = true;
+async function updateComments(repoRoot, updater) {
+  const previousQueue = commentWriteQueues.get(repoRoot) ?? Promise.resolve();
+  const queuedWrite = previousQueue.catch(() => void 0).then(async () => {
+    const store = await readCommentStore(repoRoot);
+    const { changed, result } = await updater(store);
+    if (changed) {
+      await writeComments(repoRoot, store);
     }
-    const file = diffFiles.find((item) => item.path === thread.filePath);
-    if (!thread.fileSnapshotHash && file && (thread.diffHash === diffHash2 || getThreadStatus(thread) === "submit")) {
-      thread.fileSnapshotHash = file.snapshotHash;
-      changed = true;
+    return result;
+  });
+  const queueTail = queuedWrite.then(() => void 0, () => void 0);
+  commentWriteQueues.set(repoRoot, queueTail);
+  try {
+    return await queuedWrite;
+  } finally {
+    if (commentWriteQueues.get(repoRoot) === queueTail) {
+      commentWriteQueues.delete(repoRoot);
     }
   }
-  if (changed) await writeComments(repoRoot, store);
+}
+async function attachLegacyComments(repoRoot, diffHash2, diffFiles) {
+  await updateComments(repoRoot, (store) => {
+    let changed = false;
+    for (const thread of store.threads) {
+      if (!thread.diffHash) {
+        thread.diffHash = diffHash2;
+        changed = true;
+      }
+      const file = diffFiles.find((item) => item.path === thread.filePath);
+      if (!thread.fileSnapshotHash && file && (thread.diffHash === diffHash2 || getThreadStatus(thread) === "submit")) {
+        thread.fileSnapshotHash = file.snapshotHash;
+        changed = true;
+      }
+    }
+    return { changed, result: void 0 };
+  });
 }
 async function readCommentStore(repoRoot) {
   const path = commentsPath(repoRoot);
   try {
-    return normalizeStore(JSON.parse(await readFile(path, "utf8")));
-  } catch {
+    const text = await readFile(path, "utf8");
+    return normalizeStore(parseCommentStore(text));
+  } catch (error) {
+    if (!isMissingFileError(error)) {
+      const recovered = await recoverCommentStore(repoRoot, path, error);
+      if (recovered) return recovered;
+    }
     return readLegacyComments(repoRoot);
   }
 }
 async function writeComments(repoRoot, store) {
   const path = commentsPath(repoRoot);
+  const tempPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(store, null, 2)}
+  try {
+    await writeFile(tempPath, `${JSON.stringify(store, null, 2)}
 `, "utf8");
+    await rename(tempPath, path);
+  } finally {
+    await rm(tempPath, { force: true }).catch(() => void 0);
+  }
 }
 function commentsPath(repoRoot) {
   const repoName = basename(repoRoot) || "repo";
@@ -92,11 +125,71 @@ function commentLogsDir() {
 }
 async function readLegacyComments(repoRoot) {
   try {
-    return normalizeStore(JSON.parse(await readFile(join(repoRoot, ".diff-review", "comments.json"), "utf8")));
+    return normalizeStore(parseCommentStore(await readFile(join(repoRoot, ".diff-review", "comments.json"), "utf8")));
   } catch {
     return { threads: [] };
   }
 }
+async function recoverCommentStore(repoRoot, path, cause) {
+  try {
+    const recovered = normalizeStore(parseRecoverableCommentStore(await readFile(path, "utf8")));
+    await writeComments(repoRoot, recovered);
+    return recovered;
+  } catch {
+    console.warn(`Failed to read comment store ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return void 0;
+  }
+}
+function parseCommentStore(text) {
+  const parsed = JSON.parse(text);
+  if (!Array.isArray(parsed.threads)) return { threads: [] };
+  return parsed;
+}
+function parseRecoverableCommentStore(text) {
+  const end = findRootJsonObjectEnd(text);
+  if (end === -1) throw new Error("Comment store does not contain a complete JSON object");
+  return parseCommentStore(text.slice(0, end));
+}
+function findRootJsonObjectEnd(text) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let started = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (!started) {
+      if (/\s/.test(char)) continue;
+      if (char !== "{") return -1;
+      started = true;
+    }
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return index + 1;
+    }
+  }
+  return -1;
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
 function normalizeStore(store) {
   const groups = /* @__PURE__ */ new Map();
   for (const thread of store.threads) {
@@ -132,36 +225,35 @@ function earliestTimestamp(values) {
 async function importAgentComments(repoRoot, diffHash2, diffFiles, rawComments) {
   const result = { imported: 0, skipped: [] };
   if (rawComments.length === 0) return result;
-  const store = await readComments(repoRoot);
-  for (let index = 0; index < rawComments.length; index += 1) {
-    const label = `--comment #${index + 1}`;
-    const parsed = parseImportComment(rawComments[index], label, result);
-    if (!parsed) continue;
-    if (parsed.type === "reply") {
-      if (appendAgentReply(store.threads, parsed, result, label)) {
-        result.imported += 1;
+  await updateComments(repoRoot, (store) => {
+    for (let index = 0; index < rawComments.length; index += 1) {
+      const label = `--comment #${index + 1}`;
+      const parsed = parseImportComment(rawComments[index], label, result);
+      if (!parsed) continue;
+      if (parsed.type === "reply") {
+        if (appendAgentReply(store.threads, parsed, result, label)) {
+          result.imported += 1;
+        }
+        continue;
       }
-      continue;
-    }
-    const thread = buildAgentThread(parsed, diffHash2, diffFiles, result, label);
-    if (!thread) continue;
-    const existingThread = store.threads.find((item) => item.fileSnapshotHash === thread.fileSnapshotHash && sameAnchor(item.anchor, thread.anchor));
-    if (hasDuplicateAgentComment(store.threads, thread)) {
-      result.skipped.push(`${label}: duplicate agent comment skipped`);
-      continue;
-    }
-    if (existingThread) {
-      existingThread.comments.push(thread.comments[0]);
-      existingThread.status = getOpenThreadStatus(existingThread);
-      existingThread.updatedAt = thread.updatedAt;
-    } else {
-      store.threads.push(thread);
+      const thread = buildAgentThread(parsed, diffHash2, diffFiles, result, label);
+      if (!thread) continue;
+      const existingThread = store.threads.find((item) => item.fileSnapshotHash === thread.fileSnapshotHash && sameAnchor(item.anchor, thread.anchor));
+      if (hasDuplicateAgentComment(store.threads, thread)) {
+        result.skipped.push(`${label}: duplicate agent comment skipped`);
+        continue;
+      }
+      if (existingThread) {
+        existingThread.comments.push(thread.comments[0]);
+        existingThread.status = getOpenThreadStatus(existingThread);
+        existingThread.updatedAt = thread.updatedAt;
+      } else {
+        store.threads.push(thread);
+      }
+      result.imported += 1;
     }
-    result.imported += 1;
-  }
-  if (result.imported > 0) {
-    await writeComments(repoRoot, store);
-  }
+    return { changed: result.imported > 0, result: void 0 };
+  });
   return result;
 }
 function parseImportComment(raw, label, result) {
@@ -852,6 +944,7 @@ function getThreadLocation(thread) {
 
 // src/server/file-watcher-service.ts
 import { watch } from "node:fs";
+var IGNORED_REPO_PATH_PREFIXES = ["node_modules", "dist"];
 var FileWatcherService = class {
   constructor(repoRoot) {
     this.repoRoot = repoRoot;
@@ -927,7 +1020,10 @@ var FileWatcherService = class {
   }
   tryWatch(path, options) {
     try {
-      const watcher = watch(path, options ?? {}, () => {
+      const watcher = watch(path, options ?? {}, (_eventType, filename) => {
+        if (path === this.repoRoot && this.shouldIgnoreRepoChange(filename)) {
+          return;
+        }
         this.handleChange();
       });
       this.watchers.push(watcher);
@@ -941,6 +1037,14 @@ var FileWatcherService = class {
       this.send(client, event);
     });
   }
+  /**
+   * 过滤 dev server 产物目录，避免 npm run dev 之类的启动副作用误触发 Refresh。
+   */
+  shouldIgnoreRepoChange(filename) {
+    if (!filename) return false;
+    const normalizedPath = String(filename).replaceAll("\\", "/").replace(/^\.\//, "");
+    return IGNORED_REPO_PATH_PREFIXES.some((prefix) => normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`));
+  }
   send(res, event) {
     res.write(`data: ${JSON.stringify(event)}
 
@@ -1107,8 +1211,6 @@ async function startServer(state, port = 4966) {
         res.status(400).json({ error: "Comment file is not present in the current diff" });
         return;
       }
-      const store = await readComments(state.session.repoRoot);
-      const existingThread = store.threads.find((thread2) => thread2.fileSnapshotHash === file.snapshotHash && sameAnchor(thread2.anchor, body.anchor));
       const comment = {
         id: crypto.randomUUID(),
         body: commentBody,
@@ -1116,27 +1218,28 @@ async function startServer(state, port = 4966) {
         createdAt: now,
         updatedAt: now
       };
-      if (existingThread) {
-        existingThread.comments.push(comment);
-        existingThread.status = getOpenThreadStatus(existingThread);
-        existingThread.updatedAt = now;
-        await writeComments(state.session.repoRoot, store);
-        res.status(201).json(existingThread);
-        return;
-      }
-      const thread = {
-        id: crypto.randomUUID(),
-        filePath: body.filePath,
-        anchor: body.anchor,
-        diffHash: state.session.diffHash,
-        fileSnapshotHash: file.snapshotHash,
-        status: "submit",
-        comments: [comment],
-        createdAt: now,
-        updatedAt: now
-      };
-      store.threads.push(thread);
-      await writeComments(state.session.repoRoot, store);
+      const thread = await updateComments(state.session.repoRoot, (store) => {
+        const existingThread = store.threads.find((item) => item.fileSnapshotHash === file.snapshotHash && sameAnchor(item.anchor, body.anchor));
+        if (existingThread) {
+          existingThread.comments.push(comment);
+          existingThread.status = getOpenThreadStatus(existingThread);
+          existingThread.updatedAt = now;
+          return { changed: true, result: existingThread };
+        }
+        const nextThread = {
+          id: crypto.randomUUID(),
+          filePath: body.filePath,
+          anchor: body.anchor,
+          diffHash: state.session.diffHash,
+          fileSnapshotHash: file.snapshotHash,
+          status: "submit",
+          comments: [comment],
+          createdAt: now,
+          updatedAt: now
+        };
+        store.threads.push(nextThread);
+        return { changed: true, result: nextThread };
+      });
       res.status(201).json(thread);
     } catch (error) {
       next(error);
@@ -1145,12 +1248,6 @@ async function startServer(state, port = 4966) {
   app.post("/api/threads/:id/comments", async (req, res, next) => {
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const store = await readComments(state.session.repoRoot);
-      const thread = store.threads.find((item) => item.id === req.params.id);
-      if (!thread) {
-        res.status(404).json({ error: "Thread not found" });
-        return;
-      }
       const body = req.body;
       const commentBody = body.body?.trim();
       if (!commentBody) {
@@ -1164,40 +1261,59 @@ async function startServer(state, port = 4966) {
         createdAt: now,
         updatedAt: now
       };
-      thread.comments.push(comment);
-      if (thread.status !== "resolved") {
-        thread.status = getOpenThreadStatus(thread);
-      }
-      thread.updatedAt = now;
-      await writeComments(state.session.repoRoot, store);
-      res.status(201).json(comment);
+      const commentResult = await updateComments(state.session.repoRoot, (store) => {
+        const thread = store.threads.find((item) => item.id === req.params.id);
+        if (!thread) {
+          throw new Error("THREAD_NOT_FOUND");
+        }
+        thread.comments.push(comment);
+        if (thread.status !== "resolved") {
+          thread.status = getOpenThreadStatus(thread);
+        }
+        thread.updatedAt = now;
+        return { changed: true, result: comment };
+      });
+      res.status(201).json(commentResult);
     } catch (error) {
+      if (error instanceof Error && error.message === "THREAD_NOT_FOUND") {
+        res.status(404).json({ error: "Thread not found" });
+        return;
+      }
       next(error);
     }
   });
   app.patch("/api/threads/:id", async (req, res, next) => {
     try {
-      const store = await readComments(state.session.repoRoot);
-      const thread = store.threads.find((item) => item.id === req.params.id);
-      if (!thread) {
+      const thread = await updateComments(state.session.repoRoot, (store) => {
+        const currentThread = store.threads.find((item) => item.id === req.params.id);
+        if (!currentThread) {
+          throw new Error("THREAD_NOT_FOUND");
+        }
+        let changed = false;
+        if (req.body.status === "resolved" || req.body.status === "replied" || req.body.status === "submit") {
+          currentThread.status = req.body.status === "resolved" ? "resolved" : getOpenThreadStatus(currentThread);
+          currentThread.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+          changed = true;
+        }
+        return { changed, result: currentThread };
+      });
+      res.json(thread);
+    } catch (error) {
+      if (error instanceof Error && error.message === "THREAD_NOT_FOUND") {
         res.status(404).json({ error: "Thread not found" });
         return;
       }
-      if (req.body.status === "resolved" || req.body.status === "replied" || req.body.status === "submit") {
-        thread.status = req.body.status === "resolved" ? "resolved" : getOpenThreadStatus(thread);
-        thread.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-      }
-      await writeComments(state.session.repoRoot, store);
-      res.json(thread);
-    } catch (error) {
       next(error);
     }
   });
   app.delete("/api/threads/:id", async (req, res, next) => {
     try {
-      const store = await readComments(state.session.repoRoot);
-      store.threads = store.threads.filter((item) => item.id !== req.params.id);
-      await writeComments(state.session.repoRoot, store);
+      await updateComments(state.session.repoRoot, (store) => {
+        const nextThreads = store.threads.filter((item) => item.id !== req.params.id);
+        const changed = nextThreads.length !== store.threads.length;
+        store.threads = nextThreads;
+        return { changed, result: void 0 };
+      });
       res.status(204).end();
     } catch (error) {
       next(error);
@@ -1206,67 +1322,93 @@ async function startServer(state, port = 4966) {
   app.patch("/api/threads/:id/comments/:commentId", async (req, res, next) => {
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const store = await readComments(state.session.repoRoot);
-      const thread = store.threads.find((item) => item.id === req.params.id);
-      if (!thread) {
+      const nextBody = String(req.body?.body ?? "").trim();
+      if (!nextBody) {
+        res.status(400).json({ error: "Comment body is required" });
+        return;
+      }
+      const comment = await updateComments(state.session.repoRoot, (store) => {
+        const thread = store.threads.find((item) => item.id === req.params.id);
+        if (!thread) {
+          throw new Error("THREAD_NOT_FOUND");
+        }
+        if (getThreadStatus(thread) !== "submit") {
+          throw new Error("THREAD_NOT_EDITABLE");
+        }
+        const currentComment = thread.comments.find((item) => item.id === req.params.commentId);
+        if (!currentComment) {
+          throw new Error("COMMENT_NOT_FOUND");
+        }
+        if (currentComment.author === "agent") {
+          throw new Error("AGENT_COMMENT_READ_ONLY");
+        }
+        currentComment.body = nextBody;
+        currentComment.updatedAt = now;
+        thread.updatedAt = now;
+        return { changed: true, result: currentComment };
+      });
+      res.json(comment);
+    } catch (error) {
+      if (error instanceof Error && error.message === "THREAD_NOT_FOUND") {
         res.status(404).json({ error: "Thread not found" });
         return;
       }
-      if (getThreadStatus(thread) !== "submit") {
+      if (error instanceof Error && error.message === "THREAD_NOT_EDITABLE") {
         res.status(400).json({ error: "Only submitted comments can be edited" });
         return;
       }
-      const comment = thread.comments.find((item) => item.id === req.params.commentId);
-      if (!comment) {
+      if (error instanceof Error && error.message === "COMMENT_NOT_FOUND") {
         res.status(404).json({ error: "Comment not found" });
         return;
       }
-      if (comment.author === "agent") {
+      if (error instanceof Error && error.message === "AGENT_COMMENT_READ_ONLY") {
         res.status(400).json({ error: "Agent comments are read-only" });
         return;
       }
-      const nextBody = String(req.body?.body ?? "").trim();
-      if (!nextBody) {
-        res.status(400).json({ error: "Comment body is required" });
-        return;
-      }
-      comment.body = nextBody;
-      comment.updatedAt = now;
-      thread.updatedAt = now;
-      await writeComments(state.session.repoRoot, store);
-      res.json(comment);
-    } catch (error) {
       next(error);
     }
   });
   app.delete("/api/threads/:id/comments/:commentId", async (req, res, next) => {
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const store = await readComments(state.session.repoRoot);
-      const thread = store.threads.find((item) => item.id === req.params.id);
-      if (!thread) {
+      await updateComments(state.session.repoRoot, (store) => {
+        const thread = store.threads.find((item) => item.id === req.params.id);
+        if (!thread) {
+          throw new Error("THREAD_NOT_FOUND");
+        }
+        if (getThreadStatus(thread) !== "submit") {
+          throw new Error("THREAD_NOT_EDITABLE");
+        }
+        const comment = thread.comments.find((item) => item.id === req.params.commentId);
+        if (!comment) {
+          throw new Error("COMMENT_NOT_FOUND");
+        }
+        if (comment.author === "agent") {
+          throw new Error("AGENT_COMMENT_READ_ONLY");
+        }
+        thread.comments = thread.comments.filter((item) => item.id !== req.params.commentId);
+        thread.updatedAt = now;
+        store.threads = store.threads.filter((item) => item.id !== thread.id || thread.comments.length > 0);
+        return { changed: true, result: void 0 };
+      });
+      res.status(204).end();
+    } catch (error) {
+      if (error instanceof Error && error.message === "THREAD_NOT_FOUND") {
         res.status(404).json({ error: "Thread not found" });
         return;
       }
-      if (getThreadStatus(thread) !== "submit") {
+      if (error instanceof Error && error.message === "THREAD_NOT_EDITABLE") {
         res.status(400).json({ error: "Only submitted comments can be deleted" });
         return;
       }
-      const comment = thread.comments.find((item) => item.id === req.params.commentId);
-      if (!comment) {
+      if (error instanceof Error && error.message === "COMMENT_NOT_FOUND") {
         res.status(404).json({ error: "Comment not found" });
         return;
       }
-      if (comment.author === "agent") {
+      if (error instanceof Error && error.message === "AGENT_COMMENT_READ_ONLY") {
         res.status(400).json({ error: "Agent comments are read-only" });
         return;
       }
-      thread.comments = thread.comments.filter((item) => item.id !== req.params.commentId);
-      thread.updatedAt = now;
-      store.threads = store.threads.filter((item) => item.id !== thread.id || thread.comments.length > 0);
-      await writeComments(state.session.repoRoot, store);
-      res.status(204).end();
-    } catch (error) {
       next(error);
     }
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-diff-reviewer",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "private": false,
   "description": "Open a local GitHub-style diff review Web UI for the current repository.",
   "repository": {