使用帮助：让 OpenCode 接入 mdreviewer

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

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

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

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "servers": {
         "mdreviewer": {
           "type": "local",
           "command": ["D:/Apps/mdreviewer/mdreviewer-mcp.exe"],
           "environment": {
             "MDREVIEWER_TOKEN_FILE": "C:/Users/you/.mdreviewer/agents/agt_xxx.token"
           }
         }
       }
     }
   }

   OpenCode V2 的几个关键点： 服务器必须挂在 mcp.servers 下，V2 不再直接放在 mcp 下； type 必须是 local；command 是数组，不是字符串； 环境变量键名是 environment，不是 env； 要临时停用写 disabled: true，不要再写 enabled。 弹层里生成的配置已经按 V2 格式写好，直接复制最稳。
5. 让 OpenCode 重载配置并自检。保存 opencode.json 后 OpenCode 会自动重载 MCP 配置；如果工具列表还没更新，执行 /reload，或打开 /mcps 确认 mdreviewer 是 connected。然后在 OpenCode 里说：

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

   返回 ok 且有档案名，就接上了。也可以先在「MCP 配置」弹层点 测试连接，确认 15 个工具可用。
   工具名前缀：OpenCode V2 会把工具显示成 mdreviewer_md_ping；在 Code Mode 下是 tools.mdreviewer.md_ping。 按工具列表里实际显示的名字调用即可，语义与本文的 md_* 相同。

2. 安装 OpenCode skill（建议）

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

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

   <项目目录>\.opencode\skills\mdreviewer-review\

   也可以放到全局：~/.config/opencode/skills/mdreviewer-review/。 目录名就是技能 ID，文件名必须是 SKILL.md。 Claude 兼容路径 <项目目录>\.claude\skills\mdreviewer-review\ 也能识别。
2. 如果安装目录里没有 skill，可以现场生成：

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

   然后把 %TEMP%\mdreviewer-skill\opencode\ 下的两个文件复制到上面的目录。
3. 保存后 OpenCode 会自动重载 skill；如果没识别，执行 /reload 再检查技能列表。

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

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

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

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

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

1. 对 OpenCode 说：

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

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

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

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

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

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

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

7. 常见问题排查

现象	原因 / 处理
OpenCode 里没有 md_ping / md_me	先确认 opencode.json 的 JSON 合法、mdreviewer 确实在 mcp.servers 下；保存后等 OpenCode 自动重载，仍没有就执行 /reload， 并在 /mcps 里确认 mdreviewer 为 connected。 也可以先在 mdreviewer 的「MCP 配置 → 测试连接」确认 15 个工具可用。
配置看起来对，但工具列表为空	检查四件事：服务器是否挂在 mcp.servers 下；command 是不是数组； type 是不是 local；环境变量键名是不是 environment。 写成 V1 的 mcp.mdreviewer、command 字符串或 env 都会导致配置不生效；停用应写 disabled: true，不要写 enabled。
401 / 凭据无效	配置里的 MDREVIEWER_TOKEN_FILE 路径不对，或档案被轮换了凭据。回设置页重新 「复制配置」并更新 opencode.json。
403 doc_not_granted	这篇文档没授权给该档案。打开文档 → 「交给智能体」里勾选 OpenCode 并授权。
403 智能体凭据不能调用人工评审接口	正常：接受/放行只允许人。 OpenCode 只能调 /api/agent/v1/*。
工具能连上，但 OpenCode 不按流程走	skill 没装或没重新加载。确认 .opencode\skills\mdreviewer-review\SKILL.md 存在且文件名正确， 再重新打开 OpenCode 会话。
409 原文已变化 / quote_mismatch	OpenCode 的基准过期或 quote 不是逐字复制。让它重新 md_get_source 再提交。
顶栏没有「放行」	当前没有「修订中」的候选：先接受一份修订，或它已经被放行/取代。
收件箱里没有 OpenCode 的修订	检查文档是否已授权、mdreviewer 是否在运行； 文件通道看 outbox 里是否留下 *.error.json。
OpenCode 在另一台机器 / 云端	MCP 是本机 stdio：它拉起的 mdreviewer-mcp.exe 必须和 mdreviewer 在同一台机器上。跨机器请改用文件通道 或 REST（需要网络可达与凭据）。

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

9. 与 Hermes / WorkBuddy 的差异

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

需要其它宿主的版本？Hermes 示例 · WorkBuddy 接入。