使用帮助：让 WorkBuddy 接入 mdreviewer

WorkBuddy 通过本机 stdio MCP 连接 mdreviewer；它负责出稿 / 改稿 / 提交候选， mdreviewer 负责校验、留痕和版本。接受和放行永远由人完成，WorkBuddy 不能直接写目标文件。

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

1. 确认发布包完整。mdreviewer.exe、mdreviewer-mcp.exe、 amckit.dll 必须在同一目录；WorkBuddy 拉起的是其中的 mdreviewer-mcp.exe。安装包里的 skill\workbuddy\ 也留着，下一步要用。
2. 在应用里建档。打开 mdreviewer → 设置 → 智能体 → 新建档案，类型选 MCP， 名称可以填 WorkBuddy。
3. 授权要评审的文档。打开目标 Markdown，点顶栏 交给智能体，勾选 WorkBuddy 档案，点「授权所选智能体」。 MCP / REST 是直连，不需要批次；勾选即完成文档级授权（默认拒绝）。
4. 生成 WorkBuddy 的 MCP 配置。设置 → 智能体 → 档案卡片 MCP 配置 → 宿主选 WorkBuddy → 点「复制配置」。 打开 %USERPROFILE%\.workbuddy\mcp.json，把 mdreviewer 这一项 合并到已有的 mcpServers 中，不要整份覆盖；没有这个文件就新建。

   {
     "mcpServers": {
       "mdreviewer": {
         "command": "D:/Apps/mdreviewer/mdreviewer-mcp.exe",
         "args": [],
         "env": {
           "MDREVIEWER_TOKEN_FILE": "C:/Users/you/.mdreviewer/agents/agt_xxx.token"
         }
       }
     }
   }

   路径用正斜杠：JSON 里反斜杠是转义符， D:\Apps\... 会变成非法 JSON。弹层里生成的配置已经是正斜杠，直接复制最稳。 WorkBuddy 不能由本程序一键写入，所以这一步是复制粘贴。
5. 重启 WorkBuddy 并自检。在 WorkBuddy 会话里说：

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

   返回 ok 且有档案名，就接上了。也可以先在「MCP 配置」弹层点 测试连接，确认 15 个工具可用。

2. 安装 WorkBuddy skill（建议）

MCP 工具是能力，skill 是“什么时候该做什么”的流程约束。建议一起装上：

1. 从安装目录复制 skill\workbuddy\SKILL.md 和 skill\workbuddy\proposal.schema.json 到：

   %USERPROFILE%\.workbuddy\skills\mdreviewer-review\

   目录名用 mdreviewer-review，文件名必须是 SKILL.md。 macOS / Linux 对应 ~/.workbuddy/skills/mdreviewer-review/。
2. 如果安装目录里没有 skill，可以现场生成：

   mdreviewer.exe agent-skill --format=workbuddy --out %TEMP%\mdreviewer-skill

   然后把 %TEMP%\mdreviewer-skill\workbuddy\ 下的两个文件复制到上面的目录。
3. 重启 WorkBuddy。skill 和 MCP 配置都在启动时加载，运行中的会话不会热更新。

3. 批注驱动：人先写批注，WorkBuddy 按批注改

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

1. 在正文里选中文字 → 右键「添加意见」；写完在「意见」Tab 里把批注完成（接受）。
2. 点顶栏 交给智能体，确认 WorkBuddy 已勾选授权。
3. 对 WorkBuddy 说：

   请按 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. 作者驱动：WorkBuddy 先出稿 / 先改，人来评审

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

1. 对 WorkBuddy 说：

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

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

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

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

6. 澄清问答：WorkBuddy 不确定时

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

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

7. 常见问题排查

现象	原因 / 处理
WorkBuddy 里没有 md_ping / md_me	先确认 %USERPROFILE%\.workbuddy\mcp.json 的 JSON 合法、mdreviewer 确实在 mcpServers 下；在 mdreviewer 的「MCP 配置 → 测试连接」确认 15 个工具可用， 然后完全退出并重启 WorkBuddy。
401 / 凭据无效	配置里的 MDREVIEWER_TOKEN_FILE 路径不对，或档案被轮换了凭据。回设置页重新 「复制配置」并更新 mcp.json。
403 doc_not_granted	这篇文档没授权给该档案。打开文档 → 「交给智能体」里勾选 WorkBuddy 并授权。
403 智能体凭据不能调用人工评审接口	正常：接受/放行只允许人。 WorkBuddy 只能调 /api/agent/v1/*。
工具能连上，但 WorkBuddy 不按流程走	skill 没装或没重启。确认 %USERPROFILE%\.workbuddy\skills\mdreviewer-review\SKILL.md 存在且文件名正确， 重启 WorkBuddy。
409 原文已变化 / quote_mismatch	WorkBuddy 的基准过期或 quote 不是逐字复制。让它重新 md_get_source 再提交。
顶栏没有「放行」	当前没有「修订中」的候选：先接受一份修订，或它已经被放行/取代。
收件箱里没有 WorkBuddy 的修订	检查文档是否已授权、mdreviewer 是否在运行； 文件通道看 outbox 里是否留下 *.error.json。
WorkBuddy 在另一台机器 / 云端	MCP 是本机 stdio：它拉起的 mdreviewer-mcp.exe 必须和 mdreviewer 在同一台机器上。跨机器请改用文件通道 或 REST（需要网络可达与凭据）。

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

9. 与 Hermes 的差异

项目	WorkBuddy	Hermes
MCP 配置	%USERPROFILE%\.workbuddy\mcp.json 的 mcpServers（JSON）	%LOCALAPPDATA%\hermes\config.yaml 的 mcp_servers（YAML）
配置写入	复制粘贴，合并到已有 mcpServers	可在应用里一键写入（自动备份）
skill 目录	%USERPROFILE%\.workbuddy\skills\mdreviewer-review\SKILL.md	%LOCALAPPDATA%\hermes\skills\mdreviewer-review\SKILL.md
工具与协议	同一套 md_* 工具、同一份 REST 契约和权限边界

需要 Hermes 的版本？打开 Hermes 版帮助。