Batch Review

批量评审

一款协作式代码和 Markdown 评审工具，连接人工评审者与 AI Agent。双方都可以浏览文件、查看 git 差异、留下结构化评论，并保存最终评审报告——实时协作，全程使用同一界面。

---

功能

功能	说明
三栏评审 UI	左侧为文件浏览器和 git 更改，中间为查看器，右侧为评论串
Markdown 渲染	完整渲染 .md 文件，包括通过 KaTeX 支持的 GitHub 风格数学公式：行内 $…$ 和 GitHub 的美元符号加反引号行内格式、显示型 $$…$$ 块，以及围栏式 math 代码块；还支持 Mermaid 围栏式图表和 WaveDrom 围栏式图表（数字时序图、位字段／寄存器图，以及逻辑／原理图），每种图表都带有工具栏开关，可在渲染视图和源代码视图之间切换；选中任意段落即可添加评论
HTML 预览	.html 和 .htm 文件会在中间面板的沙箱预览中渲染，并禁用脚本；选择已渲染元素、文本或可视区域即可添加关联到源文件的评论，区域评论还会保存 PNG 裁剪图
PDF 查看	.pdf 文件会在中间面板中渲染，支持按页添加文本或区域评论，也支持重新加载
DOCX/PPTX 查看	.docx 和 .pptx 文件会在浏览器中通过 docx-preview 和 @aiden0z/pptx-renderer 本地渲染；选择文档文本或经过规范化的页面／幻灯片区域即可添加评论，Office 区域选择会以 PNG 截图形式保存在评审 JSON／Markdown 输出文件旁，无需 LibreOffice 或 Microsoft Office
Office 文档安全性	Office 包以二进制数据形式获取；git 差异模式会将它们报告为二进制文件，而不会显示容易误导的 ZIP/XML 文本
语法高亮	通过 Monaco Editor 支持所有常见语言（Python、TypeScript、Go、Rust 等）
行内 git 差异	点击更改的文件，即可查看本地更改、之前的提交／引用与 HEAD 之间的差异，或当前检出版本与 GitHub PR head 之间的行内红绿统一差异
结构化评论	每条评论都会自动记录 @filename:L10-15 行引用，并在适用时提供更丰富的渲染视图锚点；Office 锚点包含文档类型、页码／幻灯片、规范化区域、所选文本和渲染器指纹
过时评论恢复	文本评论过时时，可直接在右侧面板中根据当前文件刷新其已存储的高亮内容
AI 协作	MCP 服务提供多种工具，让 AI Agent 与人工评审者协同评审——UI 会实时更新，并在 Agent 更改评论时显示屏幕通知。还提供节省 token 的 CLI 客户端模式（batch-review <verb>），供编码 Agent 使用；并提供带有评审工作流技能的 Claude Code 插件
双格式输出	同时将评审保存为便于机器读取的 JSON 和便于人类阅读的 Markdown
恢复会话	启动时，如果 {output-dir}/{output}.json 已存在，就会自动加载评论
跨平台	可在 Windows 和 Linux 上运行
主题切换	可通过左侧面板顶部栏，在原始深色主题和暖色浅色主题之间切换 Web UI

GitHub 风格数学示例

预览使用 编写数学表达式中的分隔符规则：行内 $…$、GitHub 的美元符号-反引号行内形式（解析前会重写为 $…$）、显示公式 $$…$$，以及围栏式 math 代码块。渲染使用的是 KaTeX，而非 GitHub 的 MathJax，因此即使 Markdown 语法一致，少数不常见的宏也可能有所不同。

此应用不会在 Markdown 预览中嵌入原始 HTML，因此这里无法使用 GitHub 提供的 <span>$</span> 变通方法来表示正文中的字面美元符号——在数学公式中，请按照 GitHub 文档的说明将 $ 转义为 \$。

示例：

行内公式：$\sqrt{3x-1}+(1+x)^2$

美元符号-反引号（兼容 GitHub）：$e^{i\pi} + 1 = 0$

$$ \nabla_\theta J(\theta) = \mathbb{E}{(s, a) \sim \pi\theta} \left[\nabla_\theta \log \pi_\theta(a \mid s), R(s, a)\right] $$

WaveDrom 示例

围栏式 ```wavedrom 代码块会被解析为 WaveJSON（通过 JSON5，因此键可以不加引号或使用单引号），并以内嵌方式渲染，同时提供与 Mermaid 相同的源码/渲染结果工具栏切换。支持三种图表类型，并根据 JSON 结构自动选择：

数字时序图（signal）：

{signal: [
  {name: 'clk',  wave: 'p.....'},
  {name: 'data', wave: 'x.345x', data: ['head', 'body', 'tail']},
  {name: 'req',  wave: '0.1..0'},
  {name: 'ack',  wave: '1.....'}
]}

位字段/寄存器图（reg）：

{reg: [
  {bits: 7, name: 'opcode'},
  {bits: 5, name: 'rd'},
  {bits: 3, name: 'funct3'},
  {bits: 5, name: 'rs1'},
  {bits: 12, name: 'imm[11:0]'}
], config: {bits: 32}}

逻辑/原理图（assign）：

{assign: [["z", ["|", "a", ["&", "b", "c"]]]]}

---

架构

运行时，Batch Review 是一个单体 Python 应用，负责提供浏览器 UI、为该 UI 提供 REST 和 WebSocket 端点，并可选择向 MCP 客户端开放同一审查会话。

flowchart LR
    CLI["CLI entry point<br/>`uv run batch-review`"]
    Browser["Browser UI<br/>React + Zustand"]
    McpHost["MCP host<br/>Cursor / Claude Desktop / VS Code / other clients"]
    AgentCli["Coding agent<br/>Claude Code / Cursor CLI / Codex<br/>`batch-review <verb>`"]

    subgraph Backend["Batch Review backend process"]
        Server["FastAPI app<br/>static frontend `/`<br/>REST `/api/*`<br/>WebSocket `/ws`"]
        Mcp["FastMCP server<br/>stdio transport<br/>HTTP transport `/mcp`"]
        State["Shared AppState<br/>repo root, comments, MCP session,<br/>connected WebSocket clients"]
    end

    Repo["Git repository under review"]
    Output["Saved review output<br/>`review_comments.json`<br/>`review_comments.md`"]
    PortFile[".batch_review/server.json<br/>discovery file"]

    CLI --> Server
    CLI --> Mcp
    Server --> Browser
    Browser -->|"REST reads/writes"| Server
    Browser <-->|"live sync"| Server
    Server --> State
    Mcp --> State
    McpHost -->|"stdio or HTTP MCP"| Mcp
    AgentCli -->|"REST `/api/*`"| Server
    AgentCli -.->|"reads for discovery"| PortFile
    Server -.->|"writes on start"| PortFile
    State -->|"read files, diffs, existing review data"| Repo
    State -->|"save/load review reports"| Output
    State -.->|"broadcast UI events"| Browser

• 浏览器从 FastAPI 服务加载 React 应用，通过 REST 获取文件/评论/配置，并通过 /ws 保持同步。
• MCP 工具和 REST 路由都操作同一个内存中的 AppState，因此 Agent 创建的评论会立即显示在 UI 中。
• 在 --mcp 模式下，HTTP 服务会继续提供 Web UI，同时 FastMCP 也会通过 stdio 为编辑器和 CLI 宿主运行。
• 在 CLI 客户端模式下，编码 Agent 会调用 batch-review <verb>（例如 add-comment、diff），由其调用相同的 REST 端点——不会将 MCP 工具架构加载到 Agent 上下文中。服务启动时会写入 .batch_review/server.json，以便 CLI 动词发现服务。

---

分发

• PyPI — batch-review-mcp — 为 pip / uv 发布的 wheel 和 sdist。
• 官方 MCP 注册表 — io.github.hevangel/batch-review-mcp — 最新发布的服务元数据（JSON API；注册表网站仍处于预览阶段）。

---

要求

• Python ≥ 3.13，需安装 uv
• Node.js ≥ 22（用于一次性前端构建；与 GitHub Actions 版本一致）

---

安装

git clone https://github.com/hevangel/batch-review-mcp.git
cd batch-review-mcp
uv sync

首次运行时，如果 frontend/dist/ 不存在，将自动构建 React 前端（需要 Node.js 和 npm 位于 PATH 中）。

---

使用方法

独立模式（默认打开浏览器）

# Review the current directory
uv run batch-review

# Review a specific git repository
uv run batch-review --root /path/to/your/repo

# Custom host / port
uv run batch-review --root /path/to/repo --host 0.0.0.0 --port 9100

# Specify output filenames
uv run batch-review --root /path/to/repo --output review --output-dir /tmp/reviews
# → saves /tmp/reviews/review.json and /tmp/reviews/review.md

如果默认端口已被占用，服务会自动在 9000–9999 范围内选择一个空闲端口。

MCP stdio 模式（Claude Desktop / Cursor / 任意 MCP 客户端；默认打开浏览器）

uv run batch-review --mcp --root /path/to/repo

HTTP 服务会在后台线程中启动（因此浏览器 UI 仍可访问），默认浏览器会打开应用 URL（与独立模式相同；使用 --no-browser 可跳过），MCP stdio 传输则在主线程中运行。

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "batch-review": {
      "command": "uv",
      "args": ["run", "batch-review", "--mcp", "--root", "/path/to/repo"]
    }
  }
}

CLI 客户端模式（节省 token 的 Agent 接口）

对于编码 Agent（Claude Code、Cursor CLI、Codex 等），与将 18 个 MCP 工具 schema 加载到上下文中相比，CLI 客户端模式更节省 token。每个动词调用一次进程，并向 stdout 输出单个 JSON 文档。CLI 通过 REST 与正在运行的服务通信，因此每条评论和每处高亮都会实时显示在人工审核者的浏览器 UI 中。

# Start the server in the background (browser opens by default)
batch-review start --root .
# {"web_url": "http://127.0.0.1:9000", "pid": 12345, "port": 9000}

# List changed files
batch-review changes
# [{"path": "main.py", "status": "M", ...}, ...]

# Inspect a diff
batch-review diff main.py

# Add a comment anchored to a line range
batch-review add-comment main.py 10 15 "This null check is redundant."

# Save the review report (JSON + Markdown)
batch-review save

# Stop the server when done
batch-review stop

服务发现 — 动词会按优先级自动发现正在运行的服务：BATCH_REVIEW_WEB_URL 环境变量、<repo_root>/.batch_review/server.json（由 start 写入），然后探测 9000–9999 端口。

动词参考 — 所有动词都接受 --root PATH（默认为 cwd）：

动词	参数	说明
start	[--port N] [--no-browser]	在后台启动服务
stop	—	停止正在运行的服务
config	—	服务配置（输出文件名前缀、目录、Web URL）
url	—	连接 URL（Web UI、WebSocket、MCP HTTP）
changes	[--mode local|commit|pr] [--base REF] [--pr N]	列出已更改的文件
diff	<path> [--mode ...]	统一差异 + 原始/修改后的内容
ls	[path] [--depth N]	列出文件/目录
file	<path>	读取文件内容 + 行数 + 语言
add-comment	<path> <L1> <L2> [text] [--highlighted TEXT]	添加评论
list-comments	—	列出所有评论
update-comment	<id> <text>	编辑评论文本
delete-comment	<id>	删除一条评论
clear	—	删除所有评论
delete-outdated	—	删除过时评论
recompute-stale	—	重新计算过时标记
save	[--stem NAME] [--dir DIR]	保存为 JSON + Markdown
load	<stem>	加载已保存的审核
list-reviews	—	列出已保存的审核文件名前缀
open	<path> [--mode view|diff]	在浏览器 UI 中打开文件
highlight	<path> <L1> <L2>	在 UI 中高亮行范围
jump	<comment-id>	跳转到 UI 中评论所在位置

输出约定：JSON 输出到 stdout，进度消息输出到 stderr，出错时返回非零退出码。start 动词向后兼容——如果服务已在运行，它会报告现有 URL，而不是启动重复服务。

Claude Code 插件

此仓库附带一个 Claude Code 插件（仅 CLI — 不包含 MCP 服务条目，因此 Agent 不会将工具 schema 加载到上下文中）。可从市场安装：

/plugin marketplace add hevangel/batch-review-mcp
/plugin install batch-review@batch-review

插件包含：

• 技能（skills/batch-review/SKILL.md）— 使用 CLI 动词教会 Agent 审核工作流。
• 命令（commands/batch-review.md）— 一个触发该技能的 /batch-review 斜杠命令。
• 插件清单（.claude-plugin/plugin.json）+ 市场（.claude-plugin/marketplace.json）。

Agent 技能（skills.sh）

审核工作流技能也可通过 npx skills CLI 安装到任何支持开放的 Agent Skills 标准的 Agent 中（Claude Code、Cursor、Codex、Gemini CLI、Copilot、ZCode 等 60 多种）：

# Install globally (available across all your projects)
npx skills add hevangel/batch-review-mcp --global --yes

# Or install into a specific agent only
npx skills add hevangel/batch-review-mcp --skill batch-review --agent claude-code --global

# List available skills without installing
npx skills add hevangel/batch-review-mcp --list

安装后，当你要求 Agent 审核代码、检查差异或留下审核评论时，该技能会自动触发。通过安装遥测，skills.sh 会自动发现并列出该技能——无需手动提交。

官方 MCP 注册表

此项目在根目录中包含用于 Model Context Protocol 注册表（预览版）的 server.json。该条目使用 registryType": "mcpb"：下载 URL 必须指向公开的 GitHub Release 资源，且 fileSha256 必须与该资源的字节完全一致（Release 工作流会在 Linux 上构建 .mcpb，其结果可能与在 Windows 上打包的文件不同）。

新版本的推荐发布顺序（例如 v0.4.3）：

1. 更新 pyproject.toml、mcpb/manifest.json 和 server.json 中的 version（包括顶层的 version，以及 packages[0].identifier URL：.../releases/download/v0.4.3/batch-review-mcp-0.4.3.mcpb）。
2. 将此次发布准备更改提交并推送到 main。
3. 推送标签（例如 git tag v0.4.3 && git push origin v0.4.3）。
4. Release 工作流会再次构建 Linux 资源，运行 scripts/update_server_json_mcpb_sha.py，根据 Linux 构建的 .mcpb 在工作流工作区中更新 server.json，运行 scripts/verify_release_mcp_registry.py，创建或更新 GitHub Release，通过 GitHub Actions OIDC 将 server.json 发布到 MCP 注册表（mcp-publisher login github-oidc），并在配置了 PYPI_API_TOKEN 时将 wheel/sdist 发布到 PyPI。如果 identifier 或版本与标签不匹配，或者更新后的 server.json 仍与 Linux 构建的 .mcpb 不匹配，任务就会失败，从而避免将有问题的资源发布到注册表。

单独的 MCP 注册表预检（Linux MCPB 哈希） 工作流现已变为可选。如果你想在打标签前检查 Linux 构建的 bundle 字节，或排查注册表不匹配问题，它仍然很有用；但常规发布不再需要手动将 SHA 复制到 server.json 中。

两个 CI 工作流都使用 npm ci --legacy-peer-deps 安装前端依赖。前端特意将 react-pdf/pdfjs-dist 固定为 4.8.69，而 @aiden0z/pptx-renderer 声明的可选 PDF.js peer 依赖要求 >=5 <7；在 GitHub Actions 使用的 Node 22/npm 10 环境中，直接运行 npm ci 会导致 peer 依赖解析失败。Office PDF 回退功能已禁用，因此接受锁定的依赖树不会改变应用程序 bundle。

如果标签已存在，但 Release 工作流本身需要仅涉及工作流的修复，你可以通过 Actions 手动运行 workflow_dispatch，并提供 release_tag （例如 v0.4.3）。此手动流程会检出指定标签，叠加来自 main 的当前发布元数据，并沿用现有标签名称，因此你无需移动标签或从不同的代码修订版本重新构建，就能恢复发布。该重新运行流程 也会修复 MCP 注册表发布：工作流会使用当前 main 分支元数据重新发布 server.json，并在验证/发布前重新计算 Linux fileSha256。

scripts/build_mcpb.py 会在 mcpb pack 后以确定性的方式重写打包归档，因此，对于同一源代码树，预检得到的 Linux SHA 应与 Release 工作流中再次得到的 Linux SHA 一致。

本地运行 mcp-publisher login github 仍适用于偶尔进行手动发布，但常规的标签发布不再需要通过工作站确认设备代码。

CLI 参数

batch-review 命令会根据第一个参数进行分派：如果它是已知的 CLI 动词（start、stop、changes、diff、add-comment 等），则会作为节省令牌的客户端，通过 REST 与正在运行的服务通信。否则，它会作为服务运行，并接受以下参数：

参数	默认值	说明
--root PATH	当前目录	要审查的 Git 仓库
--host HOST	127.0.0.1	绑定地址
--port PORT	9000	首选端口（若被占用则自动递增）
--output NAME	review_comments	保存输出的基础文件名（不含扩展名）
--output-dir DIR	仓库根目录	输出文件的写入目录
--mcp	关闭	启用 MCP stdio 传输
--no-browser	false（省略）	正常行为（省略此参数）：在独立模式、--dev 和 --mcp 下，服务就绪约 1.2 秒后会自动打开浏览器。传入 --no-browser 可禁用此行为。
--skip-build	关闭	跳过 npm 构建步骤

完整的动词参考请参阅上文的 CLI 客户端模式，或运行 batch-review --help。

---

UI 操作指南

左侧面板 — 两个标签页

Files 标签页 — 按需加载的目录树。首次渲染时只加载前几层，以确保大型仓库仍能保持响应；展开文件夹时会按需加载其子项，同时更深层的文件夹会在后台继续加载。点击文件即可在中央面板中打开。

顶部栏还在重新加载控件旁提供了主题切换开关。应用默认以深色模式启动，并会在浏览器中记住你的浅色／深色模式选择。

Git 标签页 — 列出相对于当前比较模式发生更改的文件，并显示状态标记：

• 🟡 M 已修改
• 🟢 A 已添加
• 🔴 D 已删除
• ⚪ U 未跟踪

使用 Local 查看工作树／索引相对于 HEAD 的更改，使用 Commit 查看之前的提交／引用相对于当前 HEAD 的更改，或使用 PR 查看当前检出内容相对于 GitHub PR 头部的更改（输入 PR 编号或 URL）。点击已更改的文件，即可在内联差异模式下打开，并显示所选左右两侧的标签。

中心面板

• 未选择文件 — 显示简洁的入门面板，其中包含应用标题和简短提醒：在左侧打开文件或差异，添加评论，然后保存审阅。
• Markdown 文件 — 完整渲染，并提供工具栏切换，可在渲染预览和 Markdown 源码之间切换。相对路径的图片嵌入内容会以内联方式渲染；兼容 GitHub 的数学语法（KaTeX）支持行内 $…$、美元符号加反引号的行内语法、显示公式 $$…$$ 和围栏数学代码块（GitHub 文档）；Mermaid 围栏代码块可通过中心面板工具栏在渲染图表和原始源码之间切换；WaveDrom 围栏代码块（```wavedrom）会渲染数字时序图；位字段／寄存器图（reg）和逻辑／原理图（assign）也可通过相同的源码／渲染视图切换工具栏进行切换。指向其他仓库文件的链接会在应用中打开；类似 other.md#heading 的链接会打开该文件，并在中心面板中跳转到对应标题。
• HTML 文件 — 在禁用脚本的沙盒预览中渲染，并提供工具栏切换回源码。悬停／点击渲染后的元素，或选择渲染后的文本，即可创建评论；评论会锚定到源 HTML 行范围以及元素选择器／指纹。对于视觉布局问题，请使用 区域 模式；该模式会保存归一化的渲染页面矩形，并将 PNG 裁剪图保存到审阅 JSON 旁边。仓库本地 CSS 和图片资源通过安全的原始内容端点加载。
• PDF 文件 — 在中心面板中逐页渲染。即使点击工具栏的“添加”按钮，文本选择评论也会记住该页上高亮的文本；区域评论则会保留页面矩形，并将 PNG 裁剪图保存到审阅 JSON 旁边（Ctrl+Alt+C）。
• DOCX 文件 — 在浏览器中本地渲染为尽力还原的 Word 页面，并按比例缩小以适应中心面板的可用内容宽度，同时保持页面比例；适配计算会包括渲染后页面的所有后代元素，因此会在缩放前纳入宽内容。选择文本可创建带页面信息的文档锚点，或切换到 区域 模式，对页面上的视觉区域发表评论；所选区域会捕获为 PNG，并保存到审阅 JSON／Markdown 输出旁边。此功能使用 docx-preview；复杂的 Word 布局和分页可能与 Microsoft Word 不同，文档锚点会作为尽力生成的指纹保留，而不是由后端验证的过期文本范围。
• PPTX 文件 — 使用 @aiden0z/pptx-renderer 在本地渲染为浏览器原生幻灯片。可选择浏览器渲染器提供的文本，或使用 区域 模式选择幻灯片矩形；选定的幻灯片区域会捕获为 PNG 文件，并保存到审阅 JSON／Markdown 输出旁边。为保持现有 PDF.js 4.x 依赖不变，已禁用嵌入式 EMF／PDF 回退渲染。
• Office 差异 — DOCX／PPTX 更改会作为二进制包报告，而不是显示原始 ZIP／XML 差异。请打开当前文档查看器进行视觉审阅；目前尚未提供语义化的新旧文档差异比较。
• 代码文件 — 使用 Monaco Editor 并提供语法高亮。选择行，然后点击工具栏中的 + 添加评论。
• 差异视图 — Monaco DiffEditor 会以内联方式显示所选的比较两侧（红色 = 已删除，绿色 = 已添加）。通过 Git 选项卡切回普通视图，或点击 Files 选项卡中的文件。

右侧面板

每条评论都会显示：

• @filename:L10-15 引用 — 点击可跳转到中央面板中的对应位置
• 用于填写审核备注的文本区域（失焦时自动保存）
• 对于已过时的文本评论，文本框内会显示一个刷新图标，可重新捕获该行范围内当前高亮的文本并清除过时状态
• 删除按钮

💾 Save Review 按钮会将所有评论保存到：

• {output-dir}/{output}.json — 机器可读的 JSON 数组
• {output-dir}/{output}.md — 按文件分组的人类可读 Markdown 报告

渲染后的 HTML、PDF、DOCX 和 PPTX 区域截图会以 PNG 文件的形式保存在同一输出目录中，并在匹配的 JSON 评论中通过文件名引用（自定义输出路径也会一并复制这些截图）。

服务器启动时，如果该 JSON 文件已存在，就会加载到会话中，以便你继续已保存的审核（无效文件会跳过，并记录日志警告）。通过右侧面板中的文件夹按钮加载已保存的审核时，页脚中显示的当前审核名称也会更新，因此后续保存默认会使用该审核名称。

---

MCP 工具

AI Agent 通过 http://localhost:PORT/mcp（HTTP 传输）或 stdio（--mcp 标志）连接。

MCP 接口有意采用以审核为先的设计。Batch Review 并非通用的仓库浏览器或编辑器 API；它是一个共享审核状态的服务，用于：

• 确定审核范围
• 检查差异以及足够的文件上下文
• 添加或更新带锚点的审核评论
• 保存或恢复审核会话

典型的 Agent 工作流如下：

1. 调用 get_git_changes()
2. 对值得审核的文件调用 get_git_diff(path)
3. 仅在需要额外的非差异上下文时使用 get_file_content(path)
4. 添加或更新评论，也可通过打开、高亮和跳转工具操作共享 UI
5. 使用审核文件工具保存或加载审核会话

协议兼容性

此服务现使用 fastmcp 4.0.2，以及 MCP Python SDK 2.x（mcp>=2.0.0,<3.0）。FastMCP 4 支持两个时代的 MCP 协议，因此现有主机可以继续使用旧版的、与连接关联的 initialize 握手，而现代客户端则使用无状态协议路径。

旧版时代使用协议修订版本 2025-11-25，并在流式 HTTP 中通过 Mcp-Session-Id 管理会话。MCP 规范的现代修订版 2026-07-28 以每个请求的 _meta.io.modelcontextprotocol/* 字段取代该握手，为流式 HTTP 添加 MCP-Protocol-Version / Mcp-Method / Mcp-Name 标头，并要求提供 server/discover。FastMCP 和 MCP SDK 负责此协商及传输行为；Batch Review 不会再添加与之竞争的协议兼容层。

FastMCP 4.0.2 还要求使用较新版本的 Starlette，因此项目在升级 FastMCP 的同时声明了 fastapi>=0.133.0 和 uvicorn[standard]>=0.35.0。可复现的确切版本记录在 uv.lock 中，目前为 FastMCP 4.0.2 和 MCP 2.1.1。

当前使用的协议版本会在 get_config MCP 工具和 GET /api/config REST 端点中通过 protocol 键提供：

{
  "active_protocol_version": "2026-07-28",
  "supported_protocol_versions": ["2025-11-25", "2026-07-28"],
  "pending_protocol_versions": [],
  "modern_era_available": true
}

这些值的唯一事实来源是 backend/mcp_compat.py。

仓库本地 MCP 宿主配置

此仓库包含已纳入版本控制的默认配置，让常见 Agent 可以同时使用 Batch Review 和 Playwright：

产品	配置文件	格式
Cursor（编辑器和 agent CLI）	.cursor/mcp.json	mcpServers，其中包含 "type": "stdio"
VS Code / GitHub Copilot	.vscode/mcp.json	servers，其中包含 "type": "stdio"（参考文档）
Claude Code	.mcp.json	项目级 mcpServers（stdio）
OpenAI Codex CLI	.codex/config.toml	[mcp_servers.NAME] stdio 配置块（为受信任的项目加载）
Gemini CLI	.gemini/settings.json	顶层 mcpServers（指南）

所有配置都会运行 uv run batch-review --mcp --root . --skip-build，因此审查根目录是宿主用作服务当前工作目录的工作区目录。Cursor 的 agent CLI 不一定会展开 args 中的 ${workspaceFolder}，因此这些配置使用 "." 作为 --root（VS Code 在 .vscode/mcp.json 中仍可使用 ${workspaceFolder}，该宿主会展开它）。

验证 stdio MCP

# Smoke test with the official Python MCP client
uv run python scripts/test_mcp_client.py

# Cursor Agent CLI (after install: https://cursor.com/docs/cli )
cd /path/to/batch_review_mcp
agent mcp enable batch-review
agent mcp list-tools batch-review
agent --approve-mcps -p "Your prompt that may call MCP tools"

工具	描述
init_batch_review_session(coding_agent, model_name?, client_version?)	每次 MCP 连接后首先调用；注册主机和模型。在此调用成功之前，其他工具都会返回错误（get_config、get_review_web_url 和资源 batch-review://server/urls 除外）。
get_git_changes()	列出相对于 HEAD 的已更改文件
get_git_diff(path)	统一差异以及原始/修改后的内容
add_comment(...)	添加审查评论；源代码评论使用行范围，而 DOCX/PPTX 评论可以使用 document_kind、document_page、标准化区域、document_anchor 和 document_fingerprint；在 UI 中显示简短通知
update_comment(comment_id, text)	编辑评论正文；显示 UI 通知
delete_comment(id)	删除评论；显示 UI 通知
clear_all_comments()	一次性移除所有内存中的评论；显示 UI 通知
delete_outdated_comments()	移除 outdated 为 true 的评论；显示 UI 通知
list_comments()	列出所有内存中的评论
recompute_comment_stale()	重新扫描文件并与 highlighted_text 比较，设置每条评论的 outdated 标记；显示 UI 通知
list_review_files()	列出 output_dir 中 *.json 审查文件的主文件名
load_review_by_stem(stem)	用 {stem}.json 中的评论替换现有评论；显示 UI 通知
save_comments(output_stem?, output_dir?)	保存 JSON 和 Markdown 报告，并返回路径
get_file_content(path)	将文件内容作为结构化数据读取（content、line_count、language、path），适用于仅靠差异上下文不够的情况
list_directory(path)	为需要查看审查文件树的主机提供精简的仓库导航辅助工具
open_file_in_ui(path, mode)	在中央面板中打开文件（view 或 diff）；相同的路径和模式会刷新视图
highlight_in_ui(path, line_start?, line_end?, pdf_page?, region_x1?, …)	源文件： line_start–line_end（从 1 开始）。PDF： pdf_page 和该页上 0–1 范围内的标准化 region_*。图像： 原始像素坐标中的 region_*。DOCX/PPTX： document_page 和标准化 region_*（以及可选的 document_kind/锚点字段）
jump_to_comment_in_ui(comment_id)	与点击评论的 @file:L… 链接效果相同：打开文件并高亮该锚点
get_config()	返回 output_stem、output_dir 和 web_ui_url（服务器已绑定时）
get_review_web_url()	返回运行中应用的 web_ui、websocket 和 mcp_http URL
(资源)	MCP 资源 URI batch-review://server/urls — 与 get_review_web_url 返回相同的 URL JSON（resources/read）；在调用 init_batch_review_session 之前即可读取

Agent 应在连接后立即调用 init_batch_review_session（并提供非空的 coding_agent，例如 Cursor 或 Claude Desktop）。服务器会强制执行此要求：先调用任何其他工具都会收到明确的“请调用 init…”错误。

评论的添加、更新、删除、全部清除、删除过时评论、重新计算评论过时状态以及加载审查记录，还会在右侧面板底部显示可关闭的 toast 通知（样式类似保存后的路径提示）。

---

输出格式

JSON（review_comments.json）

[
  {
    "id": "4c66b5fc-...",
    "file_path": "src/auth.py",
    "line_start": 42,
    "line_end": 55,
    "reference": "@src/auth.py:L42-55",
    "text": "Token is never validated — add expiry check.",
    "highlighted_text": "…",
    "region_screenshot_file": null,
    "region_screenshot_width": null,
    "region_screenshot_height": null,
    "outdated": false,
    "created_at": "2026-04-15T10:00:00+00:00"
  }
]

Markdown（review_comments.md）

# Code Review

_Generated: 2026-04-15 10:00 UTC — 3 comment(s)_

---

## src/auth.py

### `@src/auth.py:L42-55`
> Token is never validated — add expiry check.

---

---

开发

# Backend only (no frontend build needed)
uv run batch-review --root . --skip-build --no-browser

# Frontend dev server (proxies API to port 9000)
cd frontend && npm run dev

# Full production build
cd frontend && npm run build

对于贡献者文档，请使用实际产生更改的 AI 会话日期命名 session_history/ 文件，而不要复制较早条目中的日期。

---

许可证

MIT