md-review-server 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,152 @@
 # md-review-server
 
-简体中文 | [日本語](./README-ja.md)
+[![npm version](https://img.shields.io/npm/v/md-review-server.svg)](https://www.npmjs.com/package/md-review-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-md--review--server-black.svg)](https://github.com/tracyxiong1/md-review-server)
 
 ![demo](./assets/demo.gif)
 
-`md-review-server` 是一个本地 Markdown 可视化评审服务。它保留 `md-review` 的 Markdown 预览、选区评论、评论列表和文件树能力，并将评论存储迁移到 sidecar review 文件，同时提供本地 HTTP API，供 Codex、其他 agent 或脚本读取评论并回写处理状态。
+`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 自动安装：
+
+```text
+帮我安装 skill：https://www.npmjs.com/package/md-review-server
+```
+
+也可以手动安装：
+
+```sh
+npx -y md-review-server@latest skill install
+```
+
+检查状态：
+
+```sh
+npx -y md-review-server@latest skill doctor
+```
+
+看到 `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 的评审循环。
+```
+
+生成下一版：
+
+```text
+评论完了，读取评论并生成下一版。
+```
+
+继续下一轮：
+
+```text
+我已经在新版上补充了评论，继续处理。
+```
+
+## 手动启动 Review Server
+
+不使用 Codex skill 时，可以直接启动本地评审页面：
+
+```sh
+npx -y md-review-server@latest docs --port 3030 --active-file docs/guide.md
+```
+
+也可以全局安装：
+
+```sh
+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 文件
 - 解析并展示 Frontmatter 元数据
 - 对选中文本和指定行范围创建评论
@@ -20,21 +159,29 @@
 - 点击评论行号跳转到对应内容
 - 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 文件
@@ -68,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 目录：
 
@@ -110,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' \
@@ -138,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' \
@@ -156,79 +303,48 @@ 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
+pnpm install
+pnpm dev
+pnpm test
+pnpm build
+pnpm lint
 ```
 
-典型流程：
+## 发布流程
 
-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 中选择新版本继续评审
+项目使用 GitHub Actions 和 npm Trusted Publishing 发布 npm 包，不需要在 GitHub Secrets 中保存长期 `NPM_TOKEN`。
 
-### 安装 Codex Skill
+npm 包后台需要配置 Trusted Publisher：
 
-包内提供 `markdown-review-loop` skill，用于让 Codex 自动执行启动 review server、读取评论、生成下一版 Markdown 和回写状态的流程。
+- Package：`md-review-server`
+- Publisher：GitHub Actions
+- Owner：`tracyxiong1`
+- Repository：`md-review-server`
+- Workflow filename：`release-please.yml`
 
-```sh
-npx -y md-review-server@latest skill install
-```
+发布步骤：
 
-如果已经全局安装 `md-review-server`，也可以直接运行 `md-review-server skill install`。
+1. 使用语义化 commit 合并改动到 `main`
+2. `release-please` 自动创建或更新 release PR
+3. 合并 release PR 后，workflow 创建 GitHub Release 和版本 tag
+4. 同一个 workflow 在 tag 对应代码上执行 `lint`、`test`、`build`
+5. 验证 npm 上不存在同版本后，通过 OIDC 发布到 npm
 
-安装后可通过 `$markdown-review-loop` 显式触发，例如：
-
-```text
-使用 $markdown-review-loop 帮我启动这份 Markdown 的评审循环。
-```
-
-skill 依赖本机可运行 `md-review-server`。本地开发阶段可以先在仓库中执行 `npm link`，或使用发布后的 npm 包。
-
-更新 skill：
+也可以手动创建版本 tag 触发同一个发布流程：
 
 ```sh
-npx -y md-review-server@latest skill update
-md-review-server skill doctor
+npm version patch
+git push origin main --tags
 ```
 
-## 评论管理
-
-### 添加评论
-
-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
-pnpm install
-pnpm dev
-pnpm test
-pnpm build
-pnpm lint
+npm view md-review-server version --registry=https://registry.npmjs.org/
+npx -y md-review-server@latest skill doctor
 ```
 
 ## License

package/bin/skill-manager.js

@@ -1,11 +1,4 @@
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 
 export const SKILL_NAME = 'markdown-review-loop';
@@ -98,7 +91,9 @@ export function printSkillStatus(status) {
   console.log(`Bundled: ${status.bundledVersion || 'missing'}`);
   console.log(`Installed: ${status.installedVersion || 'missing'}`);
   console.log(`Path: ${status.target}`);
-  console.log(`Status: ${status.upToDate ? 'up to date' : status.installed ? 'update available' : 'not installed'}`);
+  console.log(
+    `Status: ${status.upToDate ? 'up to date' : status.installed ? 'update available' : 'not installed'}`,
+  );
 }
 
 export function printSkillHelp() {
@@ -115,11 +110,7 @@ Examples:
 `);
 }
 
-export function handleSkillCommand({
-  packageRoot,
-  argv,
-  env = process.env,
-} = {}) {
+export function handleSkillCommand({ packageRoot, argv, env = process.env } = {}) {
   const subcommand = argv[0] || 'doctor';
   const force = argv.includes('--force');
   const quiet = argv.includes('--quiet');

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "md-review-server",
-  "version": "0.1.0",
-  "description": "Local Markdown review server with visual comments, sidecar storage, and HTTP APIs",
+  "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",
@@ -51,14 +52,21 @@
   "keywords": [
     "markdown",
     "review",
+    "codex",
+    "skill",
+    "agent",
     "cli",
     "preview",
     "comments",
+    "http-api",
+    "sidecar",
     "documentation"
   ],
-  "author": "ryo-manba",
+  "author": "tracyxiong1",
+  "contributors": [
+    "ryo-manba"
+  ],
   "license": "MIT",
-  "funding": "https://github.com/ryo-manba/md-review?sponsor=1",
   "packageManager": "pnpm@10.23.0",
   "dependencies": {
     "@hono/node-server": "^1.19.6",

package/server/app.js

@@ -137,7 +137,11 @@ export function createApp(options = {}) {
 
     try {
       const files = await scanMarkdownFiles(baseDir);
-      return c.json({ files, baseDir, selectedFile: resolveSelectedFile(files, options.activeFile) });
+      return c.json({
+        files,
+        baseDir,
+        selectedFile: resolveSelectedFile(files, options.activeFile),
+      });
     } catch (err) {
       console.error('Error scanning markdown files:', err.message);
       return jsonError(c, 'Failed to scan markdown files');

package/server/comment-store.js

@@ -1,13 +1,7 @@
 import { mkdir, readFile, readdir, rename, writeFile } from 'fs/promises';
 import { dirname, extname, isAbsolute, join, resolve } from 'path';
 
-const VALID_STATUSES = new Set([
-  'open',
-  'resolved',
-  'partially_resolved',
-  'unresolved',
-  'ignored',
-]);
+const VALID_STATUSES = new Set(['open', 'resolved', 'partially_resolved', 'unresolved', 'ignored']);
 
 function normalizeReviewFile(file) {
   if (!file || typeof file !== 'string') {

package/skills/markdown-review-loop/SKILL.md

@@ -132,6 +132,7 @@ docs/example.v1.md:L42
 
 ```md
 ## C001
+
 source: docs/example.v1.md:L42-L48
 quote: "长行中的局部选区"
 status: open

package/skills/markdown-review-loop/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "Markdown 评审循环"
-  short_description: "可视化批注、修订并跟踪 Markdown 评审。"
-  default_prompt: "使用 $markdown-review-loop 打开可视化 Markdown 评审，收集批注并生成下一版修订稿。"
+  display_name: 'Markdown 评审循环'
+  short_description: '可视化批注、修订并跟踪 Markdown 评审。'
+  default_prompt: '使用 $markdown-review-loop 打开可视化 Markdown 评审，收集批注并生成下一版修订稿。'

package/skills/markdown-review-loop/references/review-template.md

@@ -9,6 +9,7 @@ document: docs/example.v1.md
 next_version: docs/example.v2.md
 
 ## C001
+
 source: docs/example.v1.md:L42-L48
 quote: "ABase 写入不在 RDS 事务内"
 status: open
@@ -16,6 +17,7 @@ comment: 需要补充 RDS 与 ABase 一致性边界。
 resolution:
 
 ## C002
+
 source: docs/example.v1.md:L77
 quote:
 status: open
@@ -27,6 +29,7 @@ resolution:
 
 ```md
 ## C001
+
 source: docs/example.v1.md:L42-L48
 quote: "ABase 写入不在 RDS 事务内"
 status: resolved