md-review-server 0.1.0 → 0.1.1

package/README.md

@@ -1,13 +1,55 @@
 # 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 可视化评审服务。它提供浏览器预览、选区批注、sidecar 评论文件、HTTP API 和内置 `markdown-review-loop` Codex skill，用于把“用户可视化评论 -> agent 读取评论 -> 生成下一版 Markdown -> 回写评论状态”串成一个本地评审循环。
+
+## 快速开始
+
+### 使用 Codex Skill
+
+安装或更新内置 `markdown-review-loop` skill：
+
+```sh
+npx -y md-review-server@latest skill install
+```
+
+检查本机 skill 状态：
+
+```sh
+npx -y md-review-server@latest skill doctor
+```
+
+在 Codex 中显式触发：
+
+```text
+使用 $markdown-review-loop 帮我启动这份 Markdown 的评审循环。
+```
+
+skill 会启动或复用本地 review server，读取 open 评论，生成下一版 Markdown，并通过 HTTP API 回写 `resolved`、`partially_resolved` 或 `unresolved` 状态。
+
+### 手动启动 Review Server
+
+无需全局安装时可直接运行：
+
+```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
+```
 
 ## 功能
 
+- 内置 `markdown-review-loop` Codex skill，可通过 npm 安装和更新
 - 按原始结构预览 Markdown 和 MDX 文件
 - 解析并展示 Frontmatter 元数据
 - 对选中文本和指定行范围创建评论
@@ -26,7 +68,7 @@
 npm install -g md-review-server
 ```
 
-当前首轮交付以本地使用为主，也可以在仓库中直接运行：
+也可以在仓库中直接运行：
 
 ```sh
 pnpm install
@@ -231,6 +273,40 @@ pnpm build
 pnpm lint
 ```
 
+## 发布流程
+
+项目使用 GitHub Actions 和 npm Trusted Publishing 发布 npm 包，不需要在 GitHub Secrets 中保存长期 `NPM_TOKEN`。
+
+npm 包后台需要配置 Trusted Publisher：
+
+- Package：`md-review-server`
+- Publisher：GitHub Actions
+- Owner：`tracyxiong1`
+- Repository：`md-review-server`
+- Workflow filename：`release-please.yml`
+
+发布步骤：
+
+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
+
+也可以手动创建版本 tag 触发同一个发布流程：
+
+```sh
+npm version patch
+git push origin main --tags
+```
+
+发布完成后可验证：
+
+```sh
+npm view md-review-server version --registry=https://registry.npmjs.org/
+npx -y md-review-server@latest skill doctor
+```
+
 ## License
 
 [MIT](./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,7 +1,7 @@
 {
   "name": "md-review-server",
-  "version": "0.1.0",
-  "description": "Local Markdown review server with visual comments, sidecar storage, and HTTP APIs",
+  "version": "0.1.1",
+  "description": "Visual Markdown review server with Codex skill, sidecar comments, and HTTP APIs",
   "type": "module",
   "bin": {
     "md-review-server": "bin/md-review.js"
@@ -51,14 +51,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