建议审批 (Review Panel)

@quan-huayan/dsh-review-panel 是 DeepSeek Harness 的一个插件包，提供一个工具：review_items。

它把 AI 已经想清楚的一批建议/意见/改动清单交给用户逐条裁决：接受、拒绝，或者自己改写后再接受。每条还可以单独留一句批注。整批处理完，review_items 才返回，模型拿到的是每一条的最终决定。

它不是提问工具。用途边界：

场景	该用的工具
要用户在给定选项里选一个、需要补信息才能继续、要批准某次操作或计划	ask_user_question
已经有明确结论，只需要用户逐条采纳或否决	review_items

两者最大的区别是形状：review_items 输出的是一张卡片（一屏看完、可批量操作、可改写），而不是一叠问题。

安装

插件按 profile 安装。在你的 profile 目录（例如 $DSH_HOME/profiles/web）里：

npm install @quan-huayan/dsh-review-panel

然后在同一个 profile 的 package.json 里把它加进 dsh.profile.bundles：

{
  "dependencies": {
    "@quan-huayan/dsh-review-panel": "^0.1.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "@quan-huayan/dsh-review-panel"
      ]
    }
  }
}

重启（或让 HMR 重载）后，工具就会出现在模型可用的工具表里。这个包自带 cordis.patch.yml，插件会把自己插入 profile 的组合层，不需要手工改 cordis.patch.yml。

需要一个带 Web 前端的 profile：卡片是插件的客户端半边渲染的。在 headless/纯 SDK 组合里，工具仍然注册，但会直接返回「当前组合里没有可用的 Web 审批界面」，不会把清单交出去。

工具参数

参数	类型	说明
title	string，必填	这批评审的标题，例如「关于缓存层的 6 条修改意见」。
items	array，必填	要逐条裁决的条目，按你希望用户处理的顺序排列。
items[].id	string，可选	稳定 id；省略时按顺序自动编号为 item-1、item-2……
items[].title	string，必填	一句话结论，卡片标题行显示。
items[].detail	string，可选	说明、依据或建议改法。

items 为空时工具不会阻塞，直接返回一条提示。

返回值

阻塞到用户提交整批决定（或中断）为止，返回结构化结果：

{
  "title": "关于缓存层的 2 条修改意见",
  "callId": "call-abc",
  "released": false,
  "items": [
    { "id": "item-1", "title": "先加一层本地缓存", "decision": "accept", "annotation": "先量一下命中率" },
    { "id": "item-2", "title": "再加一层 CDN", "decision": "edit", "finalTitle": "先评估 CDN 成本", "finalDetail": "现在的量还不值得" }
  ]
}

字段	含义
decision	accept / reject / edit / pending（未处理，只在中断时出现）。
finalTitle	仅 edit，用户改写后的条目文本。
finalDetail	仅 edit，用户附的改写说明（可选）。
annotation	用户给这一条留的批注（可选）。
released	true 表示用户在给出决定之前中断了这次审批，此时所有条目都是 pending。

模型看到的文本是同一份结果的逐行渲染；presentationMeta 把结构化结果原样交给卡片，页面刷新后卡片直接从它重建，不需要重新解析文本。

行为约定

• 整批裁定：用户必须给每一条一个决定才能提交，选了「改为」还必须写下自己的版本。半成品提交不会被接受。
• 提交是原子的：服务端会校验 callId、条目是否属于本次审批、有没有重复、决定是否合法、有没有漏项。任何一项不合格，整批拒绝，且这次审批仍然留在原地等用户重试。
• 一次结算：同一条审批settle一次；重复提交会得到 no-pending-review。
• 可中断：工具调用被中断时立即返回，所有条目为 pending。
• 并发安全：多条审批可以同时在等，按 callId 分开结算。
• 刷新不丢：卡片从记录下来的工具参数和所在行重建，页面刷新不会丢掉待处理的清单。

前提与限制

• 需要带 Web 前端的 profile；纯 headless 组合只能得到「没有可用的 Web 审批界面」。
• 客户端需要 react（由 Web 外壳提供，不是本包的依赖）。
• 插件走的是自己注册的 Web 路由（/dsh-review-panel），用框架的 Connection RPC 信封通信。为什么不走 connection.rpc.handle()，见 index.js 顶部注释。
• 包本身零运行时依赖。

开发

npm test              # node:test，零依赖
npm run test:coverage
npm run pack:check    # npm pack --dry-run，确认发布的文件清单

测试分三层：

文件	覆盖
test/host.test.mjs	宿主半边：工具注册、参数与输出契约、decide 端点的全部校验分支、RPC 信封的拒绝路径、阻塞/中断/并发语义、结果渲染。全部经由 apply() 注册的真实工具定义与真实路由驱动。
test/client.test.mjs	客户端半边：通过 window.__ModuleLoader__ 桩件按浏览器的方式加载打包产物，用无 DOM 的 React 桩件渲染并真实点按卡片，断言看到的文案、按钮可用性和最终提交的 payload。
test/package.test.mjs	发布契约：包名与 loader id、exports/files/cordis.patch.yml 互相一致、两半边的 channel 与决定集合一致、许可证与 README 齐备。

改动包名时注意：package.json 的 name、client.js 里的 __ModuleLoader__.load({ id })、cordis.patch.yml 的 name，以及 profile 的 dependencies/bundles 必须一起改。Loader 校验「注册的 id == 包的 name」，不一致时客户端半边会静默不加载（test/package.test.mjs 会挡住这种漂移）。

License

MIT