使用帮助：以 Hermes 为例跑完一次评审

Hermes 负责出稿 / 改稿，mdreviewer 负责校验、留痕和版本；接受和放行永远由人完成。 全程只需要一个顶栏按钮开始：待我评审。

流程总览

1. 一次性准备（约 3 分钟）

1. 确认发布包完整。mdreviewer.exe、mdreviewer-mcp.exe、amckit.dll 必须在同一目录；Hermes 调用的是其中的 mdreviewer-mcp.exe。
2. 在应用里建档并授权。打开 mdreviewer → 设置 → 智能体 → 新建档案（类型选 MCP）。 然后打开要评审的 Markdown，点顶栏 交给智能体，勾选该档案并点 「授权所选智能体」。MCP / REST 是直连，不需要批次；勾选即完成文档级授权（默认拒绝）。
3. 生成 Hermes 配置（不用命令行）。打开 设置 → 智能体，在档案卡片上点 MCP 配置 → 宿主选 Hermes → 预览确认后点 「写入 Hermes 配置」（只替换 mcp_servers.mdreviewer 段，写入前自动备份原文件； 新建时直接创建 %LOCALAPPDATA%\hermes\config.yaml）。也可以点「复制配置」手动粘贴。
   写完要重载 Hermes：运行中的 Hermes 不会热加载新 MCP； 重启 Hermes（或在其 MCP 设置里点重新加载）后，md_ping / md_me 才会出现。 不确定服务是否正常，先点弹层里的「测试连接」。
   命令行仍可用（脚本/批量）： mdreviewer.exe mcp-config --host=hermes --print；图形界面会把 exe 路径、令牌路径和缩进都算好，通常不需要再执行它。
4. 令牌已包含在配置里。生成的 YAML 会写入该档案的 MDREVIEWER_TOKEN_FILE，不需要手动填。若之后点过「轮换凭据」， 回到「MCP 配置」重新生成/写入即可。
5. 让 Hermes 自检。在 Hermes 里说：

   请调用 md_ping 确认 mdreviewer 连接正常，再调用 md_me 告诉我我是谁。

   返回 ok 且有档案名，就接上了。

2. 批注驱动：人先写批注，Hermes 按批注改

适合“我已经看出一批问题，让 Hermes 去改”的场景。

1. 在正文里选中文字 → 右键「添加意见」；写完在「意见」Tab 里把批注完成（接受）。
2. 点顶栏 交给智能体，选择批次、勾选文件通道档案，点「授权所选智能体」生成送达单 （MCP / REST 直连的档案不需要批次，勾选授权即可）。
3. 对 Hermes 说：

   请按 mdreviewer 的批注工单改这篇文档：
   1) md_batches 找到进行中的批次
   2) md_claim 领取
   3) md_get_ticket / md_get_source 读工单与正文
   4) md_propose 提交逐块提案（quote 逐字复制）
   5) md_wait 等我裁决，不要直接改文件

4. 回到 mdreviewer：顶栏出现 提案 N，点开逐块裁决（见第 4 节）。

3. 作者驱动：Hermes 先出稿 / 先改，人来评审

适合“从零起稿、大改一版、没有现成批注”的场景。新文档要先由人建一个空文件： Hermes 不能创建文件，也不能直接写盘。在 mdreviewer 里「新建草稿」保存成目标 .md， 再在「交给智能体」里勾选 Hermes 并授权。

1. 对 Hermes 说：

   你先写一版 / 先改这篇文档，交 mdreviewer 给我评审：
   - 用 md_submit_revision：path=<文档绝对路径>，summary=<这轮改了什么>
   - 小改用 changes（逐块补丁）；大改或新稿用 content（整篇新正文）
   - 提交后用 md_wait 等我的裁决，不要直接写文件

2. Hermes 返回 revision_id 并进入等待；候选只落在 mdreviewer 的候选区，目标文件没变。
3. 你打开顶栏 待我评审，点这一行 → 自动打开文档并弹出裁决面板。
4. 接受后保存为 X.Y（如 0.1）；点顶栏 放行 才生成 X+1.0 正式版。

4. 裁决与放行：界面上怎么做

你要做的事	位置	结果
看所有文档里等着你处理的修订	顶栏「待我评审」	点一行直接打开该文档并进入裁决
接受某些块	裁决面板勾选 → 「接受选中的块」	生成 X.Y，状态 修订，正文由页面保存
否决某些块	勾选 → 「否决（填原因）」	块标 已否决，原因回传给 Hermes，不产生版本
把本轮修订定版	顶栏「放行」→ 确认	生成 X+1.0，状态 定版，本轮关闭
看历史	「版本」Tab	按 X.Y 展示修订 / 定版 / 已被取代 / 已否决
回看 Hermes 回传 / 文件通道结果	顶栏「消息」	保留最近 200 条动态；点条目打开对应文档，修订类直接进裁决面板

5. 澄清问答：Hermes 不确定时

Hermes 不应该猜。它会把某条批注标成 clarify 并附上具体问题：

1. 意见列表里出现 待澄清 徽标；点开意见详情，能看到「澄清问答」。
2. 在回复框里回答 → 「回复智能体」。回答只追加到线程，不会替你接受或否决这条意见。
3. Hermes 用 md_opinions（或再次领取工单）读回你的回答，继续改稿。

6. 常见问题排查

现象	原因 / 处理
401 / 凭据无效	YAML 里的 MDREVIEWER_TOKEN_FILE 路径不对，或档案被轮换了凭据。回设置页重新复制路径。
403 doc_not_granted	这篇文档没授权给该档案。打开文档 → 「交给智能体」里勾选授权。
页面接口返回 403 智能体凭据不能调用人工评审接口	正常：接受/放行只允许人。Hermes 只能调 /api/agent/v1/*。
Hermes 里没有 md_ping / md_me	配置已写入，但运行中的 Hermes 还没重载。先在 mdreviewer 的「MCP 配置 → 测试连接」确认 15 个工具可用，然后重启 Hermes（或在其 MCP 设置里点重新加载）；命令行 hermes mcp test mdreviewer 也可验证。
Hermes 只能看到某一个文档	授权是文档级且显式记录的。不需要就打开「交给智能体」，在该档案旁点 「撤销授权」；需要别的文档就打开它再授权一次。
409 原文已变化 / quote_mismatch	Hermes 的基准过期或 quote 不是逐字复制。让它重新 md_get_source 再提交。
顶栏没有「放行」	当前没有「修订中」的候选：先接受一份修订，或它已经被放行/取代。
收件箱里没有 Hermes 的修订	检查是否已入库、文档是否授权；文件通道看 outbox 里是否留下 *.error.json。
文件通道提交被拒	文件会改名为 *.rejected.json，同目录 *.error.json 写明逐块原因（多为 missing_reason / quote_mismatch）。

7. 硬约束（设计上不可协商）

8. 附：不能发 HTTP 的智能体（文件通道）

有些智能体只能读写目录，不能调 MCP/HTTP。此时用 outbox 投递：

• 按批注改：写 <批次>_proposal.json（需要 doc_id + batch_id + changes）。
• 作者驱动：写 <名字>_revision.json（path + summary， 加 changes 或 content）。

扫描器每 4 秒收一次；成功改名 *.done.json，失败改名 *.rejected.json 并写 *.error.json。成功后同样出现在「待我评审」，裁决方式完全一样。