md-review-server 0.1.1 → 0.1.2

package/README.md

@@ -6,35 +6,130 @@
 
 ![demo](./assets/demo.gif)
 
-`md-review-server` 是面向 Codex 文档迭代的本地 Markdown 可视化评审服务。它提供浏览器预览、选区批注、sidecar 评论文件、HTTP API 和内置 `markdown-review-loop` Codex skill，用于把“用户可视化评论 -> agent 读取评论 -> 生成下一版 Markdown -> 回写评论状态”串成一个本地评审循环。
+`md-review-server` 是面向 Codex 的本地 Markdown 可视化评审工具。
+
+在 Codex 中，纯对话方式适合提出整体修改要求，但不方便对长文中的具体文本进行圈选和批注。`md-review-server` 提供浏览器评审页面和 `markdown-review-loop` skill，让用户可以在浏览器中阅读 Markdown、留下局部评论，再由 Codex 根据评论生成下一版文档，形成“批注 -> 修订 -> 再评审”的迭代流程。
+
+## 使用场景
+
+- 需要在浏览器里阅读 Markdown，并对具体段落做批注。
+- 需要让 Codex 根据批注生成下一版文档。
+- 需要对技术方案、README、机制说明、复盘草稿做多轮修改。
+- 需要保留 `v1`、`v2`、`v3` 等多个版本，方便回看每轮改动。
+
+适合处理的问题包括：
+
+- 章节结构需要调整。
+- 表达不够清晰，需要重写。
+- 某段内容缺少背景、边界或结论。
+- 长文需要分轮评审，先看结构，再看内容，再看措辞。
+
+## 示意流程
+
+| 1. 进入流程                                         | 2. Review & comment                                               | 3. Review & comment                                               | 4. Review 完毕，提交                                            | 5. 查看结果 & loop                                                 |
+| --------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ |
+| ![进入流程](./assets/review-loop/01-enter-flow.png) | ![Review and comment](./assets/review-loop/02-review-comment.png) | ![Review and comment](./assets/review-loop/03-review-comment.png) | ![Review 完毕，提交](./assets/review-loop/04-submit-review.png) | ![查看结果并进入下一轮](./assets/review-loop/05-review-result.png) |
 
 ## 快速开始
 
-### 使用 Codex Skill
+### 安装
+
+推荐让 Codex 自动安装：
 
-安装或更新内置 `markdown-review-loop` skill：
+```text
+帮我安装 skill：https://www.npmjs.com/package/md-review-server
+```
+
+也可以手动安装：
 
 ```sh
 npx -y md-review-server@latest skill install
 ```
 
-检查本机 skill 状态：
+检查状态：
 
 ```sh
 npx -y md-review-server@latest skill doctor
 ```
 
-在 Codex 中显式触发：
+看到 `Status: up to date` 即可使用。
+
+### 启动评审循环
+
+在 Codex 中输入：
+
+```text
+使用 $markdown-review-loop 帮我启动 docs/example.md 的评审循环。
+```
+
+Codex 会打开本地评审页面。用户在浏览器中阅读文档，并对需要修改的位置创建评论。
+
+### 在浏览器中评论
+
+在浏览器中操作：
+
+1. 选中需要修改的文字。
+2. 点击 `Comment`。
+3. 输入评论。
+4. 提交评论。
+
+### 让 Codex 生成下一版
+
+评论完成后，回到 Codex 输入：
+
+```text
+评论完了
+```
+
+Codex 会根据评论生成新版本，例如：
+
+```text
+example.v1.md -> example.v2.md
+```
+
+### 继续评审
+
+如果还需要继续修改，在浏览器中切换到新版文档，继续评论。然后对 Codex 说：
+
+```text
+我已经在 v2 上补充了新评论，继续生成 v3。
+```
+
+推荐使用版本化文件名：
+
+```text
+example.v1.md
+example.v2.md
+example.v3.md
+```
+
+查看历史版本：
+
+![查看历史版本](./assets/review-loop/06-history-versions.png)
+
+### 常用话术
+
+启动评审：
 
 ```text
 使用 $markdown-review-loop 帮我启动这份 Markdown 的评审循环。
 ```
 
-skill 会启动或复用本地 review server，读取 open 评论，生成下一版 Markdown，并通过 HTTP API 回写 `resolved`、`partially_resolved` 或 `unresolved` 状态。
+生成下一版：
+
+```text
+评论完了，读取评论并生成下一版。
+```
+
+继续下一轮：
 
-### 手动启动 Review Server
+```text
+我已经在新版上补充了评论，继续处理。
+```
 
-无需全局安装时可直接运行：
+## 手动启动 Review Server
+
+不使用 Codex skill 时，可以直接启动本地评审页面：
 
 ```sh
 npx -y md-review-server@latest docs --port 3030 --active-file docs/guide.md
@@ -47,7 +142,9 @@ npm install -g md-review-server
 md-review-server docs --port 3030
 ```
 
-## 功能
+默认只监听 `127.0.0.1`。如果使用 `--host 0.0.0.0`，服务会在启动时输出安全提示。
+
+## 主要能力
 
 - 内置 `markdown-review-loop` Codex skill，可通过 npm 安装和更新
 - 按原始结构预览 Markdown 和 MDX 文件
@@ -62,21 +159,29 @@ md-review-server docs --port 3030
 - 点击评论行号跳转到对应内容
 - Markdown 文件变更后通过 SSE 自动刷新
 
-## 安装
+## 评论管理
 
-```sh
-npm install -g md-review-server
-```
+### 添加评论
 
-也可以在仓库中直接运行：
+1. 在 Markdown 预览区域选择文本
+2. 点击出现的 `Comment` 按钮
+3. 输入评论内容
+4. 按 `Cmd/Ctrl+Enter` 或点击 `Submit`
 
-```sh
-pnpm install
-pnpm build
-node bin/md-review.js docs --port 3030
-```
+### 编辑评论
 
-## 使用方式
+1. 点击评论上的编辑按钮
+2. 修改文本框中的内容
+3. 按 `Cmd/Ctrl+Enter` 或点击 `Save`
+4. 按 `Escape` 或点击 `Cancel` 放弃修改
+
+### 快捷键
+
+- `Cmd/Ctrl+Enter`：提交或保存评论
+- `Escape`：取消编辑
+- `Cmd+K`：目录模式中聚焦搜索框
+
+## CLI 使用方式
 
 ```sh
 md-review-server [options]              # 浏览当前目录下的 Markdown 文件
@@ -110,9 +215,9 @@ md-review-server skill install
 md-review-server skill update --force
 ```
 
-默认只监听 `127.0.0.1`。如果使用 `--host 0.0.0.0`，服务会在启动时输出安全提示；MVP 不包含认证能力。
+## 进阶说明
 
-## 评论数据
+### 评论数据
 
 评论由服务端写入 Markdown 所在 review 目录：
 
@@ -152,21 +257,21 @@ review 文件使用 JSON 存储，核心字段包括：
 - `unresolved`：无法处理，需记录原因
 - `ignored`：明确跳过
 
-## HTTP API
+### HTTP API
 
-### 获取会话信息
+#### 获取会话信息
 
 ```sh
 curl http://127.0.0.1:3030/api/session
 ```
 
-### 获取待处理评论
+#### 获取待处理评论
 
 ```sh
 curl 'http://127.0.0.1:3030/api/comments?file=guide.v2.md&status=open'
 ```
 
-### 创建评论
+#### 创建评论
 
 ```sh
 curl -X POST 'http://127.0.0.1:3030/api/comments' \
@@ -180,7 +285,7 @@ curl -X POST 'http://127.0.0.1:3030/api/comments' \
   }'
 ```
 
-### 批量回写状态
+#### 批量回写状态
 
 ```sh
 curl -X PATCH 'http://127.0.0.1:3030/api/comments' \
@@ -198,71 +303,6 @@ curl -X PATCH 'http://127.0.0.1:3030/api/comments' \
   }'
 ```
 
-## Codex 评审循环
-
-推荐使用目录模式启动 review server：
-
-```sh
-md-review-server docs --port 3030 --active-file docs/guide.v2.md
-```
-
-典型流程：
-
-1. Codex 生成一个版本化 Markdown 文件，例如 `guide.v2.md`
-2. 用户在浏览器中选区并创建评论
-3. 服务端将评论写入 `.reviews/*.review.json`
-4. Codex 通过 `GET /api/comments?status=open` 获取待处理评论
-5. Codex 生成下一版 Markdown，例如 `guide.v3.md`
-6. Codex 通过批量 `PATCH /api/comments` 回写每条评论的处理状态
-7. 用户在同一个 review server 中选择新版本继续评审
-
-### 安装 Codex Skill
-
-包内提供 `markdown-review-loop` skill，用于让 Codex 自动执行启动 review server、读取评论、生成下一版 Markdown 和回写状态的流程。
-
-```sh
-npx -y md-review-server@latest skill install
-```
-
-如果已经全局安装 `md-review-server`，也可以直接运行 `md-review-server skill install`。
-
-安装后可通过 `$markdown-review-loop` 显式触发，例如：
-
-```text
-使用 $markdown-review-loop 帮我启动这份 Markdown 的评审循环。
-```
-
-skill 依赖本机可运行 `md-review-server`。本地开发阶段可以先在仓库中执行 `npm link`，或使用发布后的 npm 包。
-
-更新 skill：
-
-```sh
-npx -y md-review-server@latest skill update
-md-review-server skill doctor
-```
-
-## 评论管理
-
-### 添加评论
-
-1. 在 Markdown 预览区域选择文本
-2. 点击出现的 `Comment` 按钮
-3. 输入评论内容
-4. 按 `Cmd/Ctrl+Enter` 或点击 `Submit`
-
-### 编辑评论
-
-1. 点击评论上的编辑按钮
-2. 修改文本框中的内容
-3. 按 `Cmd/Ctrl+Enter` 或点击 `Save`
-4. 按 `Escape` 或点击 `Cancel` 放弃修改
-
-### 快捷键
-
-- `Cmd/Ctrl+Enter`：提交或保存评论
-- `Escape`：取消编辑
-- `Cmd+K`：目录模式中聚焦搜索框
-
 ## 本地开发
 
 ```sh

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "md-review-server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Visual Markdown review server with Codex skill, sidecar comments, and HTTP APIs",
   "type": "module",
   "bin": {
     "md-review-server": "bin/md-review.js"
   },
   "files": [
+    "assets",
     "bin/md-review.js",
     "bin/skill-manager.js",
     "dist",