计划评审面板 andrewhmir/dsh-plan-review

@andrewhmir/dsh-plan-review — 先读完整个计划，再批准

一个面向 DeepSeek Harness（DSH）的非官方社区插件。仓库：<https://github.com/andrewhmir/dsh-plan-review>。它消除了 superpowers 工作流里一处具体的摩擦：

智能体请你批准计划。问题卡片只显示 path: C:\ws\.superpowers\plans\feature.md 和两个按钮——你只好手动打开 markdown 文件，才能知道自己在批准什么。

装上这个插件后，这个问题会接管输入区，把完整计划直接渲染出来，顶部是 Accept plan / Revise plan，任意段落都能选中 → 评论。你对着屏幕上的计划做决定。

它做什么

| 属性 | 行为 |
| 触发条件 | 收到 ask_user_question 请求，且其中唯一问题的标题以 [plan-review] 开头 |
| 呈现方式 | 接管输入区：吸顶决策栏、完整计划 markdown、可滚动正文、评论栏 |
| 计划来源 | 问题第一行的 path: <absolute .md>，通过插件自己的 host 路由读取；没有路径时，问题文本本身就是计划 |
| 评论 | 在计划里选中文本 → Add comment；每条评论锚定到引用的段落，可编辑、可删除，也能重新定位 |
| 接受 | 用问题自带的接受标签作答；存在评论或总体备注时拒绝接受，反馈不会被悄悄丢掉 |
| 修订 | 把 {decision, comments, note} 放进答案的 custom 字段发回；还没有反馈时在本地拒绝 |
| 草稿 | 评论和总体备注存在当前浏览器标签页的 session storage 里，关掉再打开评审不会丢；作答后清空草稿 |
| 兜底 | 计划读不出来或问题未被接管时，显示自带的卡片 / 内联错误；评审仍可作答 |
| 键盘 | Ctrl/Cmd+Enter 接受；Escape 清除待提交的评论选区 |
| 关闭 | Close 关闭评审但不作答（等同自带卡片的讨论操作） |
| 语言 | 面板界面为英文；包元数据提供 en + zh |

要求

- DSH >= 0.2.1-rc.2，带 Web GUI（dsh web）。
- superpowers 工作流的 superpowers-ui 技能（安装在 $DSH_HOME/skills/ 下）会发出 [plan-review] 协议，本插件负责渲染它。
- 只有测试和客户端构建需要 Node.js 22 或更高版本；插件本身运行在 harness 进程内。

安装

这个包是 DSH 的 bundle：它声明了 dsh.bundle.patch，以及一行 client+host 插件（id: plan-review）。把它装进你运行的配置档，然后重启 dsh web。

从插件市场安装

启用 DSH 的自定义插件市场，添加一个列出本包的社区索引（仓库带有 dsh-plugin GitHub topic，索引可以据此发现它），然后在 Discover 标签页安装 @andrewhmir/dsh-plan-review。

让智能体安装

plugin_manager install_bundle target: @andrewhmir/dsh-plan-review@0.1.0

从本地检出安装

plugin_manager install_bundle target: /absolute/path/to/dsh-plan-review

安装之后

重启 dsh web。 正在运行的进程还持有安装前的模块图；重启后才会加载新的宿主端和客户端 bundle。然后确认组合结果：

dsh --profile web --dump-config

预期：退出码为 0，并且有一行 id: plan-review / name: @andrewhmir/dsh-plan-review，不出现 not found、unknown key 或 cannot resolve。

工作原理

- 认领。 插件的客户端半边注册进 conversation.composer 链槽，priority: -20 —— 排在自带的提问 composer（0）、审批面板（1）和子代理只读 composer（-10）前面。它的选择器只对单个通用问题返回认领，且该问题的 header 以 [plan-review] 开头；其他交互一律返回 null，自带的卡片不受影响。（问题最多只能带两个选项，且不能是多选；其他情况同样回退。）
- 协议。 问题文本第一行是 path: <absolute markdown file>，后面跟评审标题。没有 path: 行时，整段文本就是计划。选项标签是决策按钮的依据；类似接受和类似修改的标签按模式匹配，并原样回传。
- 宿主端。 GET /plan-review/file?path=…（仅限回环地址，只读）以 UTF-8 读取计划。读取范围限于配置档注册的工作区根目录，加上沙箱策略的 workspaceRoot；二进制扩展名、超大文件、以及这些根目录之外的路径一律拒绝，并返回稳定的错误码。GET /plan-review/ping 是存活探测。
- 渲染。 计划 markdown 由插件自带的渲染器（src/client/markdown.mjs）渲染：ATX 标题、段落、围栏代码、行内代码、粗体/斜体/删除线、链接（仅限 http/https/mailto/#/相对路径）、有序和无序列表、引用块、GFM 表格和分隔线。原始 HTML 按文本显示。不从网络拉取任何内容，渲染也不依赖 shell 可能未暴露的模块表原语。
- 评论。 高亮以引用文本加渲染文档上的字符偏移为锚点；偏移会随文档渲染进行修正，所以重新渲染后评论不会指向错误的段落。锚定的评论用浏览器的 CSS Custom Highlight API 绘制，markdown 渲染器的 DOM 从不被改动。引用文本消失的评论标记为 passage not found，但保留其备注。
- 回答。 Accept 发送 { id, selected: [<accept label>] }。Revise 需要至少一条评论或一条整体备注，然后发送 { id, selected: [], custom: "],\"note\":…}" } —— 这正是 superpowers-ui 技能所记录的形态。面板只负责渲染，从不编辑计划文件。

协议（面向智能体） json { "id": "plan-review", "header": "[plan-review]", "question": "path: C:\\ws\\.superpowers\\plans\\feature.md\nReview the plan below.",
"options": [
{ "label": "Accept plan", "description": "Start executing the plan as written." },
{ "label": "Revise plan", "description": "Incorporate my comments and show me the updated plan." }
]
}

答案通过 ask_user_question 的结果返回。纯决策是
selected: ["Accept plan"]。带评论的决策则不同，它的
selected: []，custom 里装着
{"decision": "", "comments": [{"quote": "<passage>", "note": "<what to change>"}], "note": "<overall note>"}。
note 是本插件新增的字段，用来放整体备注（技能文档里只写了 decision + comments）；如果正文为了塞进一条工具结果不得不缩短，还会带上 "truncated": true。在计划文件里找到每段引用的文字，逐条落实每条备注（一条都不能漏），重写计划，然后再次询问。

只要还存在评论或整体备注，插件就拒绝发出接受答案：标签决策没有字段能装下它们，所以它会改为请求 Request changes（或者请求删掉评论）。

配置

插件行接受一个可选值；读取时不经过 Config schema： yaml
- insert:
- id: plan-review
name: '@andrewhmir/dsh-plan-review'
config:
maxPlanBytes: 2000000 # read cap for one plan file (default 2 MB)

已知限制

- 只支持 [plan-review] 协议。 harness 原生的计划模式审查（exit_plan_mode、architect 预设）是另一套已发布的功能面，这里刻意不碰——本插件存在的意义就是渲染 superpowers 计划文件。
- 计划文件必须位于某个工作区根目录下。 不在任何已注册根目录内的计划会被拒绝，这是有意为之（错误信息会给出路径，方便修正）。路由只提供 markdown/text 计划文件（.md、.markdown、 .mdown、.mkd、.mdx、.txt），绝不提供工作区里的任意文件。
- 草稿按浏览器标签页隔离。 在同一标签页里关闭再打开审查，评论仍在（sessionStorage）；它们不会同步到其他标签页或设备，回答审查后即被清除。
- 格式错误的答案会被截断。 编码后的答案保持在配置档的工具结果裁剪预算之内；如果不得不缩短，载荷会带上 "truncated": true，让智能体去追问，而不是悄悄漏掉备注。
- 面板文案为英文。 包元数据是双语的；本版本中面板内的字符串为英文。
- 仅限 Web GUI。 宿主路由是通用的，但接管和评论属于 Web 客户端功能。
- 审查期间输入框被占用。 这和已发布的问题卡片占的是同一个位置；关闭审查后输入框恢复。
- 基于引用的锚定。 评论绑定到用户选中的那段原文；如果评审中途计划被重写（本插件不会这么做），评论会显示 passage not found。
- 未来宿主协议变更可能遮蔽本插件。 认领依赖文档化的 conversation.composer 链和 [plan-review] 头；如果未来的 harness 自带针对该头的渲染器，它的 composer 条目可能胜出。

兼容性

engines.dsh 声明 >=0.2.1-rc.2。composer 链、问题回答的 wire schema、loopback web 路由和预置的 React 模块，都是针对本机上的 0.2.1-rc.2 包实现的，并由单元/集成测试套件覆盖，测试使用 fake React、fake storage 和 fake fetch（测试不驱动真实浏览器）。计划渲染自成一体，不依赖 shell 的 markdown 原语。实际执行后，安装与冒烟测试的证据会记录在 MOUNT.md。

验证

在本目录下执行：

node --test "test/.test.mjs"
node tools/build-client.mjs --check
node --check client.js

在受限的 Windows 沙箱中，测试运行器的子进程 spawn 会被阻止；此时改用 node --test --test-isolation=none "test/.test.mjs"。

开发

node tools/build-client.mjs # regenerate client.js from src/client/.mjs
node tools/build-client.mjs --check # fail when client.js is stale
node --test "test/.test.mjs"

client.js 是生成的 classic script，以包名向 harness 的模块加载器注册自身。src/client/ 下的源模块是纯 ESM，只使用相对 .mjs 导入；宿主部分位于 src/host/，通过 webServer 注入（可选 workspaceRegistry / sandboxPolicy）。

只改客户端部分后，harness 的客户端 HMR 会 stat 轮询构建产物，并在打开的页面中热替换。改宿主部分需要重启 dsh web。

独立性与许可

这是非官方社区插件，与 DeepSeek 无隶属关系。它针对 superpowers 协议独立实现了内联计划评审这一想法；本机上的前身是私有插件 dsh-superpowers-ui（0.1.x API，在 0.2.x 升级中退役）。上游 DSH 目前不接受外部 pull request，因此以独立包分发；仓库带有 dsh-plugin topic，方便社区插件索引发现它。

MIT。见 LICENSE。