mdreview

mdreview-service

一个容器化的 Markdown 审阅微服务。Agent 通过 POST 提交 Markdown，获取供人工审阅的 URL，并通过 HTTP 轮询反馈。一个服务可处理多项审阅，并通过 ID 隔离。无需为每个进程单独启动进程，也无需与 Agent 共享文件系统。

落地页： mdreview.space（通过 .github/workflows/pages.yml 从 GitHub Pages 提供；源文件位于 web/site/）。

文档： mdreview.space/docs：入门指南、操作指南和故障排除文档，通过服务自身的 Markdown 渲染器呈现（源文件位于 web/site/docs/）。

开始使用：托管或自托管

使用 mdreview 有两种方式；任选其一。

1. 托管（在线）。 一个托管实例运行在 mdreview.space（应用位于 app.mdreview.space）。使用任意电子邮件地址登录（你会收到一个一次性链接；无需邀请码）。有三种方式可以连接你的 Agent。

claude.ai 自定义连接器（无需令牌）。 在 claude.ai 中打开 Settings, Connectors, Add custom connector 并输入：

https://app.mdreview.space/mcp

Claude 会打开 mdreview 登录页面；输入你的电子邮件地址，点击一次性链接，并在授权页面批准连接。它可在 claude.ai 网页版、桌面端和移动端使用。你可以随时在 Account 页面撤销连接。

Claude Code 插件。 在 Claude Code 中运行：

/plugin marketplace add ranawaqas-ai/mdreview-service
/plugin install mdreview@mdreview

系统会提示你输入令牌（登录后在 Account 页面创建），并将其保存在你的密钥链中。插件更新通过 /plugin update 获取；封装程序不会在插件中自行更新。

安装程序。 在运行 Agent 的机器上（需要 claude CLI 和 python3），使用 Account 页面提供的令牌：

curl -fsSL https://mdreview.space/install.sh | MDREVIEW_TOKEN=mdr_xxx sh

这会将仅使用标准库的 MCP 封装程序下载到 ~/.mdreview，并以用户级配置将其注册到 Claude Code；退出并重新打开 Claude Code 后即可连接。省略 MDREVIEW_TOKEN=…，系统会改为提示你输入令牌。（如需手动配置，或使用非 Claude Code 的 MCP 客户端，请参阅 MCP 服务。）

2. 自托管（本地）。 克隆并自行运行（无需账户，无需身份验证，运行于 localhost）。参阅 运行，然后将 Agent 的 MCP MDREVIEW_BASE 指向 http://localhost:8137。如果你希望所有内容都运行在自己的机器上，请选择此方式。

仅使用 Python 标准库（镜像体积小，无需通过 pip 安装）。独立自包含：marked、Mermaid、KaTeX、 highlight.js 和脚注渲染器均已随附，并通过 /static 提供，因此浏览器无需使用 CDN。查看器按照 Jekyll/MathJax 网站的方式渲染 Markdown：LaTeX 数学公式（行内 $…$ / \(…\)，独立公式 $$…$$ / \[…\]；正文或货币中的 $ 保持原样）、Mermaid 图表、GFM 脚注（[^id] 引用 → 有序的反向引用章节），以及语法高亮的围栏代码（采用双配色主题，在浅色和深色面板中都清晰易读）。

运行

make up        # serves on http://localhost:8137
# or:
docker build -f infra/Dockerfile -t mdreview-service .
docker run -d -p 8137:8080 -v mdreview-data:/data mdreview-service

make up（compose）是标准的本地 Docker 运行方式；服务监听 8137，并重用命名卷 mdreview-data，因此重建或重新创建容器后，你的审阅内容仍会保留。

健康检查：curl localhost:8137/healthz -> {"ok":true}。

反馈和源文件会保存在 /data 卷中，并在重启后继续保留。

迁移旧版手动运行的容器

如果你有一个较早手动启动的实例（使用非标准端口，例如 :8139 的 docker run），可以在不丢失数据的情况下将其迁移到标准的 compose 流程：mdreview-data 卷会原样重用：

docker rm -f mdreview     # stop the hand-run container (the mdreview-data volume survives)
make up                   # compose recreates it on 8137, mounting the same mdreview-data volume

由于 compose 卷现在使用显式的 name: mdreview-data 声明（而不是带项目名前缀的 infra_mdreview-data），make up 挂载的正是旧容器使用的卷。使用 curl localhost:8137/healthz 确认，并检查审阅内容仍然显示。

流程

1. Agent：POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
2. Agent 将 review_url 提供给人工审核者。
3. 人工审核者打开链接，选择文本或点击段落编号，然后输入备注（自动保存）。
4. Agent 轮询 GET /api/reviews/{id}/status，然后调用 GET /api/reviews/{id}/feedback。
5. Agent 应用修改，并调用 PUT /api/reviews/{id}/source {markdown} -> 人工审核者的页面会 实时重新加载，并将已处理的备注划掉。按需重复此流程。

配置（环境变量）

变量	默认值	含义
PORT	8080	容器内监听端口
MDREVIEW_DATA	/data	存储目录（挂载一个卷）
MDREVIEW_PUBLIC_BASE	空	如果设置（例如 https://review.example.com），review_url/feedback_url 将使用此值；否则使用请求的 Host 标头
MDREVIEW_ENABLE_LATEX	关闭	选择启用 LaTeX 论文审核模式（见下文）。需要 mdreview-service-latex 镜像（Tectonic）；默认的精简镜像不包含 LaTeX 工具链

运维指南

原先放在这里的运行手册已移出，以便本页更易阅读：

指南	内容
HTTP API	所有路由、请求和响应格式
MCP 服务	运行 stdio 服务、冒烟测试
LaTeX 论文审核	启用方式、模板、编译循环、镜像运行手册
监视器	Agent 监视器、可信基础模式、容器化运行
设计系统	§01-§10，工单引用的 UI 规则
自主运行	Agent 如何在此处交付更改

备注

• 按 ID 隔离多租户，因此并发审核不会冲突。没有身份验证（面向可信网络 / 本地网络）；如果要公开访问，请将其置于带身份验证的反向代理之后。
• 仪表板（/）和 GET /api/reviews 列出所有审核：这对于可信网络环境来说没问题，但公开访问时应在前面配置身份验证。
• 上方的 MCP 封装器是在 docs/future-mcp.md 中设计的，并作为设计和决策记录予以保留。
• Agent 集成详情请参阅 CLAUDE.md。
• 非 Docker、按文件运行的 CLI 版本位于 ../mdreview（将反馈写入源文件旁的文件中）。此服务是联网的多会话版本。

许可证

Apache License 2.0。

隐私政策

位于 app.mdreview.space 的托管服务会存储你的账户邮箱、审核内容和评论，以及登录安全记录。该服务不使用分析工具或跟踪 Cookie，不会出售你的数据，也不会使用你的数据训练 AI 模型。完整政策（包括数据保留、删除和第三方服务）请访问 https://mdreview.space/privacy/。如有疑问，请联系 [email protected]。可自托管的实例会将所有数据保存在你的设备上。