local-diff-reviewer 1.0.1 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # diff-review
 
-![Diff 审查台界面截图](./docs/images/diff-review-ui.jpg)
+![Diff 审查台界面截图](https://cdn.jsdelivr.net/npm/local-diff-reviewer@latest/docs/images/diff-review-ui.jpg)
 
 AI chat 里的本地代码审查工具。可以直接用 CLI 打开，也可以安装成 agent skill。
 
@@ -9,7 +9,7 @@ AI chat 里的本地代码审查工具。可以直接用 CLI 打开，也可以
 Try it first:
 
 ```bash
-npx local-diff-reviewer
+npx --yes local-diff-reviewer
 ```
 
 Install and use:
@@ -36,59 +36,13 @@ npx skills add Mone-Lee/diff-review
 - 支持通过内部 `--comment` 参数预置 agent findings / replies。
 - 支持复制极简 AI prompt。
 
-## 评论定位原理（新手友好版）
-
-很多人会直觉认为：评论只和“第几行”绑定。  
-比如删掉第 10 行后，原来第 11 行顶上来变成第 10 行，评论也应该跟着走。
-
-这个工具不是这样做的。它用的是“锚点”定位，锚点至少包含：
-
-- 文件路径（`filePath`）
-- 行号（`lineNumber`）
-- 行所在版本（`side`：旧版本 `old` / 新版本 `new`，代码 Diff 专用）
-
-这意味着评论绑定的是“哪一个版本里的哪一行”，而不是“屏幕上现在第几行”。
-
-### 为什么删除内容后评论可能不显示？
-
-- 对代码 Diff 行评论：
-  - 如果评论当时加在被删除的旧行上，它的锚点是 `old + 行号`。
-  - 删除后右侧展示的是新版本内容（`new`），`old` 锚点找不到对应渲染位置时，就不会显示在行内。
-- 对 Markdown 行评论：
-  - 评论绑定的是 source line（源文件行号）。
-  - 被评论的那段 Markdown 真被删掉后，预览里没有对应块可挂载，行内自然不显示。
-
-### 一个非常短的例子
-
-1. 你在 `old` 版本第 20 行加了评论。  
-2. 后续改动把第 20 行删除，并让后面内容上移。  
-3. 新内容虽然“占了第 20 行的位置”，但它属于 `new` 版本，不是原来的 `old` 行。  
-4. 所以系统不会把旧评论自动贴到新内容上。
-
-这样做的好处是：避免评论“串行”到语义完全不同的内容上，减少误导。
-
-复制出的 prompt 包含 thread id、定位信息和评论内容。thread id 用于让 agent 后续通过 `--comment '{"type":"reply",...}'` 精确回复原评论：
-
-```text
-[thread:<thread-id>]
-文件路径:行号
-评论内容
-```
-
-文件级评论不包含行号：
-
-```text
-[thread:<thread-id>]
-文件路径
-评论内容
-```
-
 ## CLI 使用方式
 
 ```bash
 local-diff-reviewer
 local-diff-reviewer staged
 local-diff-reviewer HEAD~1 HEAD
+local-diff-reviewer --repo /path/to/project
 ```
 
 这三种模式分别表示：
@@ -97,6 +51,22 @@ local-diff-reviewer HEAD~1 HEAD
 - `staged`：审查已经 `git add`、但还没有提交的改动。
 - `revision`：审查两个 revision 之间的差异，例如 `local-diff-reviewer HEAD~1 HEAD` 会比较 `HEAD~1..HEAD`。
 
+如果命令不是在目标项目目录里启动，可以用 `--repo <path>` 显式指定要审查的 Git 仓库：
+
+```bash
+local-diff-reviewer --repo /path/to/project
+local-diff-reviewer --repo /path/to/project staged
+```
+
+每次启动都会创建独立的本地 review 会话。多个项目里分别执行 `local-diff-reviewer` 或 `/diff-review` 时，打开的页面会分别绑定启动时的项目，不会被最后一次启动覆盖。默认优先使用 `127.0.0.1:4966`；如果端口已被占用，会自动选择一个空闲端口。
+
+```text
+项目 A /diff-review -> http://127.0.0.1:4966  -> 项目 A diff
+项目 B /diff-review -> http://127.0.0.1:<空闲端口> -> 项目 B diff
+```
+
+注意：本地开发的 `--dev` 模式仍使用 Vite dev server，端口和 API proxy 是固定的；多项目并行审查请使用默认的构建页面模式。
+
 ## Skill 使用方式
 
 在 AI chat 中使用：
@@ -113,7 +83,7 @@ local-diff-reviewer HEAD~1 HEAD
 npx skills add Mone-Lee/diff-review
 ```
 
-skill 会从目标 workspace 运行 `npx local-diff-reviewer [args...]`。
+skill 会针对目标 workspace 运行 `npx --yes local-diff-reviewer --repo <workspace> [args...]`。
 
 ### 预置 agent 评论
 
@@ -122,28 +92,28 @@ CLI 支持重复传入 `--comment <json>`，用于在打开 UI 前把 agent 审
 代码 diff 行评论：
 
 ```bash
-npx local-diff-reviewer \
+npx --yes local-diff-reviewer \
   --comment '{"type":"thread","filePath":"src/foo.ts","position":{"side":"new","line":36},"body":"这里没有处理空数组，可能导致运行时报错。"}'
 ```
 
 Markdown source line 评论：
 
 ```bash
-npx local-diff-reviewer \
+npx --yes local-diff-reviewer \
   --comment '{"type":"thread","filePath":"README.md","position":{"type":"markdown","line":22},"body":"这里可以补充 old/new side 的例子。"}'
 ```
 
 文件级评论：
 
 ```bash
-npx local-diff-reviewer \
+npx --yes local-diff-reviewer \
   --comment '{"type":"thread","filePath":"src/foo.ts","body":"这个文件的错误处理策略需要统一。"}'
 ```
 
 回复已有 thread：
 
 ```bash
-npx local-diff-reviewer \
+npx --yes local-diff-reviewer \
   --comment '{"type":"reply","threadId":"<thread-id>","body":"同意，这里应该按 repoRoot 隔离评论存储。"}'
 ```
 
@@ -157,6 +127,24 @@ npx local-diff-reviewer \
 - `replied`：已有 agent 内容，或从 resolved 重新打开。
 - `resolved`：用户确认完成后的状态。
 
+## 发布流程
+
+```bash
+npm run release
+npm run release minor
+npm run release major
+```
+
+该命令会按顺序执行：
+
+- `npm run release:check`
+- `npm version <patch|minor|major>`（默认 `patch`）
+- `npm publish`
+- `git push`
+- `git push --tags`
+
+只有在 `npm publish` 成功后，才会自动推送提交和标签到 GitHub。
+
 ## 本地开发
 
 ```bash

package/SKILL.md

@@ -16,16 +16,18 @@ Use this skill when the user asks for `/diff-review`, wants to inspect current w
 - `/diff-review staged`: review staged diff.
 - `/diff-review <base> <target>`: review diff between two Git revisions.
 
-Do not ask the user to run a shell CLI manually. Run the package command from the workspace root:
+Do not ask the user to run a shell CLI manually. Determine the target workspace/repository from the user's active environment context, then pass it explicitly with `--repo`:
 
 ```bash
-npx local-diff-reviewer [args...]
+npx --yes local-diff-reviewer --repo /absolute/path/to/target/workspace [args...]
 ```
 
+Do not use the skill package directory or this skill's install directory as the review target unless that is the workspace the user asked to review.
+
 When you have concrete review findings or answers to existing review comments, preload them with one `--comment` JSON argument per comment before launching the viewer:
 
 ```bash
-npx local-diff-reviewer [args...] \
+npx --yes local-diff-reviewer --repo /absolute/path/to/target/workspace [args...] \
   --comment '{"type":"thread","filePath":"src/foo.ts","position":{"side":"new","line":36},"body":"Explain the finding in the user language."}' \
   --comment '{"type":"reply","threadId":"existing-thread-id","body":"Answer the existing thread as the agent."}'
 ```

package/dist/cli/start.js

@@ -860,12 +860,22 @@ async function startServer(state, port = 4966) {
   app.use((error, _req, res, _next) => {
     res.status(500).json({ error: error.message });
   });
-  return new Promise((resolve3) => {
+  return listen(app, port);
+}
+function listen(app, port) {
+  return new Promise((resolve3, reject) => {
     const server = app.listen(port, "127.0.0.1", () => {
       const address = server.address();
       const actualPort = typeof address === "object" && address ? address.port : port;
       resolve3(`http://127.0.0.1:${actualPort}`);
     });
+    server.once("error", (error) => {
+      if (error.code === "EADDRINUSE" && port !== 0) {
+        listen(app, 0).then(resolve3, reject);
+        return;
+      }
+      reject(error);
+    });
   });
 }
 function selectPromptThreads(threads, scope) {
@@ -880,9 +890,9 @@ function selectPromptThreads(threads, scope) {
 var packageRoot = resolve2(dirname2(fileURLToPath(import.meta.url)), "../..");
 var builtWebDist = join4(packageRoot, "dist", "web");
 async function main() {
-  const { dev, reviewArgs, comments } = parseCliOptions(process.argv.slice(2));
+  const { dev, repo, reviewArgs, comments } = parseCliOptions(process.argv.slice(2));
   const mode = parseReviewMode(reviewArgs);
-  const repoRoot = await getRepoRoot(process.cwd());
+  const repoRoot = await getRepoRoot(repo ?? process.cwd());
   const diff = await getDiff(mode, repoRoot);
   const diffFiles = parseUnifiedDiff(diff);
   const session = {
@@ -914,6 +924,7 @@ async function main() {
 function parseCliOptions(args) {
   const reviewArgs = [];
   const comments = [];
+  let repo;
   let dev = false;
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -921,6 +932,19 @@ function parseCliOptions(args) {
       dev = true;
       continue;
     }
+    if (arg === "--repo") {
+      const value = args[index + 1];
+      if (!value) throw new Error("--repo requires a path value");
+      repo = resolve2(value);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--repo=")) {
+      const value = arg.slice("--repo=".length);
+      if (!value) throw new Error("--repo requires a path value");
+      repo = resolve2(value);
+      continue;
+    }
     if (arg === "--comment") {
       const comment = args[index + 1];
       if (!comment) throw new Error("--comment requires a JSON value");
@@ -936,7 +960,7 @@ function parseCliOptions(args) {
     }
     reviewArgs.push(arg);
   }
-  return { dev, reviewArgs, comments };
+  return { dev, repo, reviewArgs, comments };
 }
 function modeLabel(mode) {
   if (mode.kind === "revision") return `${mode.base}..${mode.target}`;
@@ -944,7 +968,7 @@ function modeLabel(mode) {
 }
 function startVite() {
   const child = spawn("npm", ["run", "web:dev"], {
-    cwd: process.cwd(),
+    cwd: packageRoot,
     stdio: "inherit",
     shell: process.platform === "win32",
     env: { ...process.env, BROWSER: "none" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-diff-reviewer",
-  "version": "1.0.1",
+  "version": "1.0.5",
   "private": false,
   "description": "Open a local GitHub-style diff review Web UI for the current repository.",
   "repository": {
@@ -12,11 +12,15 @@
     "url": "https://github.com/Mone-Lee/diff-review/issues"
   },
   "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
   "bin": {
-    "local-diff-reviewer": "./dist/cli/start.js"
+    "local-diff-reviewer": "dist/cli/start.js"
   },
   "files": [
     "dist",
+    "docs/images",
     "SKILL.md",
     "README.md"
   ],
@@ -29,7 +33,8 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "skill:check": "node scripts/validate-skill.mjs",
     "release:check": "node scripts/release-check.mjs",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "release": "node scripts/release.mjs"
   },
   "dependencies": {
     "express": "^5.2.1",
@@ -55,4 +60,4 @@
     "typescript": "^5.9.3",
     "vite": "^8.0.12"
   }
-}
+}