dsh-prd-canvas
Manifest validPRD Canvas for DeepSeek Harness: Image/Requirements/Existing PRD → Right-side draggable, gate-passing PRD board, export to md/json/docx
dsh-prd-canvas · 图解 PRD 画布
给 DSH 加一块右侧 PRD 画布:你把一张图(原型 / 截图 / 流程图 / 手绘)发给模型,模型把它拆成需求条目打到画布上;你在画布上拖、改、确认,最后导出 markdown + JSON。
设计依据是本工作区 2026-11 的 PRD agent 工具调研(见 REQUIREMENTS.md):
- 不做一键长文:PRD 是条目集合,不是一篇文章。
- 每条需求必须有依据(evidence),无依据的条目不允许导出。
- 每条需求必须有可验收标准(GIVEN/WHEN/THEN 或 EARS),不可验收的阻断导出,不是警告。
- NFR 八项三态(有 / 明确不做 / 未指定),未指定必须进「待确认」。
- 变更走 delta 记录,不重写全文。
安装
桌面版(Electron)的 profile 由应用独占,CLI 的 dsh plugin --profile desktop add 会被拒(profile "desktop" is managed exclusively by the Electron application)。用内置的插件管理器装本地链接:
plugin_manager action=install_bundle target="link:<插件目录绝对路径>"
它会做三件事:pnpm add 到 ~/.dsh/profiles/desktop、写进 dsh.profile.bundles、当场 enable。
- host 半侧当场生效(
/dsh-prd-canvas/api/health返回 403 = 路由已挂上,403 是ctx.connection.requestRejection在拦外部请求,不是没装)。 - client 半侧要刷新页面(右侧栏出现「图解 PRD」)。改完 client 代码再刷新即可;改 host 代码用
plugin_manager set_plugin target="include:dsh-prd-canvas"先 disable 再 enable(模块从磁盘重新导入)。
图解是一条固定流水线(不靠人提醒)
插件把「图解」拆成五步,写工具一律返回 stage(当前步)与 next(下一步动作),画布顶上有一条进度条:
| 步 | 判据 | 未达成时工具返回的 next |
|---|---|---|
| ① 输入 | source.images / source.briefs / source.note 任一非空 | 补输入 |
| ② 结构 | 至少一条功能需求 | prd_canvas_apply 拆条目 |
| ③ 门禁 | 无阻断(依据齐、验收标准可测) | prd_canvas_lint 先修阻断项 |
| ④ 契约 | 有数据或接口条目 | 补表结构 / 请求响应契约 |
| ⑤ 交付 | lastExport 已打戳(任一格式导出成功) | prd_canvas_export |
画布上的「下一步」按钮不只是提示:它 POST /advance,由 host 把当前阶段写成一条明确指令(含 stage、next、
「不要停下来问我」)推进会话,模型收到就接着干;走到 ⑤ 之后按钮变成「导出交付」。
插件还自带一个 Skill(skills/prd-canvas/SKILL.md,随插件注册进 host 技能表):新会话里只要话题是
「图解这个页面 / 按这张图出 PRD / 把这段需求变成 PRD」,模型会自动拿到这份五步契约——先 open、看 stage/next、
分析结论(配色 token、字段、契约)必须落成条目、导出前过门禁。装插件即得规则,卸插件即带走。
画布会自己出来
PRD 一产生,画布就应当出现——不管它是谁写的:
- 工具调用:
prd_canvas_*的工具卡会打开并聚焦画布; - 任何其它进程写入(导入脚本、编辑器、别的 agent):host 对
.prd-canvas递归fs.watch,prd.json一变就广播给该会话的画布; - 页面刚打开:插件在
apply()里订阅可见会话的session/events,并主动问一次/session——已有板子就直接打开,不用等事件; - 画布开着时每 5 秒兜底问一次
/session,有更新的板子就跟过去;从「画布 ▾」手动选过的板子会暂停自动跟随(刷新恢复)。
两种入口(图 / 文字)
| 入口 | 怎么用 | 依据长什么样 |
|---|---|---|
| 图 | 会话里发图 → 模型看图 → prd_canvas_apply | 图1 · 区域 A |
| 文字 | 画布空态里写一段描述 → 「用这段描述建 PRD」,或把一段话「作为需求描述」发上去 | 需求描述 B-1 |
| 已有 PRD | 工具栏「导入 PRD」选一个 .md/.txt | 导入:old-prd.md |
PRD 内容范围(不只是图解)
需求条目有 7 种类型、9 个章节:功能 / 非功能 / 约束 / 数据 / 接口 / 风险 / 里程碑。 质量门除了看「有没有依据、验收标准可不可测」,还会提醒 PRD 缺章:
prd-missing-contract:有功能需求但没有数据/接口条目prd-missing-constraint:没有非功能/约束条目prd-missing-milestone/prd-missing-scope:没有里程碑、没写「不做什么」
导入保真度
导入本插件自己导出的 markdown 是往返保真的(回归测试覆盖):条目 id、类型([功能]/[风险]/[非功能·x])、
章节、AC-01: GIVEN … · WHEN … · THEN …、- 待确认: 都会原样回到画布;- 依据: 及其子项、
NFR 三态表、`## 画布操作(不需要工具调用)
| 按钮 | 作用 |
|---|---|
| + 条目 | 直接加一张空白需求卡(draft,无依据、无 AC,所以门禁会立刻标红) |
| 按章节整理 | 把散落的卡片按 9 个章节排成列,并把坐标落盘 |
| 分组视图 / 自由画布 | 分组视图只读排列(拖拽锁定),切回自由画布即可拖 |
| 画布 ▾ | 列出本工作区所有板子,点一下切过去 |
| 编辑态下拉 | 改类型(功能/非功能/约束/数据/接口/风险/里程碑)会连带改到对应章节 |
质量门` 章节会被识别为元数据而不变成条目。
导入外部 PRD 依赖 ## 标题 + - 列表项 结构;没有验收标准的条目会被质量门标红——那是这份 PRD 的真实缺口,
不是解析错误。
用法
- 在会话里发一张图,问一句「按这张图出 PRD」。
- 模型会调
prd_canvas_open→prd_canvas_apply,右侧画布自动打开并画出卡片。 - 在画布上:拖卡片 / 双击改正文 / 改 GIVEN-WHEN-THEN / 切换确认态 / 删卡片。
- 底部输入框写「R-003 少了超时分支」→ 点「发回会话」,消息回到会话,模型据此
prd_canvas_patch。 - 顶部「导出 MD / 导出 JSON」→ 过质量门才放行,同时下载到浏览器并落到工作区。
也可以先点空画布上的「先建一块空画布」,再把图片拖进画布存成源图。
8 个工具
| 工具 | 作用 |
|---|---|
prd_canvas_open | 开/续一块画布,返回 prdId |
prd_canvas_apply | 图→PRD 主入口,写入 requirements / nfr / openQuestions;分块写(每次 ≤6 条,其余 mode:"merge"),超限回 document-too-large |
prd_canvas_patch | 改一条需求(正文 / 类型 / AC / 依据 / 状态) |
prd_canvas_lint | 跑质量门,返回逐条问题与统计 |
prd_canvas_read | 读回完整模型(改之前先读) |
prd_canvas_brief | 记下用户的一段文字描述(source.briefs),条目可用 {kind:"brief",ref:"B-1"} 当依据 |
prd_canvas_import | 导入已有 PRD(markdown/纯文本):标题分层、列表项拆条目、GIVEN/WHEN/THEN 识别、表字段进 detail |
prd_canvas_export | 导出 md / json / docx,过不了门禁会拒绝(可 force) |
画布操作(不需要工具调用)
| 按钮 | 作用 |
|---|---|
| + 条目 | 直接加一张空白需求卡(draft,无依据、无 AC,所以门禁会立刻标红) |
| 按章节整理 | 把散落的卡片按 9 个章节排成列,并把坐标落盘 |
| 分组视图 / 自由画布 | 分组视图只读排列(拖拽锁定),切回自由画布即可拖 |
| 画布 ▾ | 列出本工作区所有板子,点一下切过去 |
| 编辑态下拉 | 改类型(功能/非功能/约束/数据/接口/风险/里程碑)会连带改到对应章节 |
质量门
| 规则 | 级别 | 含义 |
|---|---|---|
evidence-missing | block | 没有依据 |
ac-missing | block | 没有验收标准 |
ac-untestable | block | 缺 GIVEN/WHEN/THEN、含模糊措辞、THEN 无可观测结果 |
statement-multi-shall | warn | 一句话里多个「应/须」 |
duplicate | warn | 两条表述重复(bigram Jaccard ≥ 0.8) |
nfr-unspecified | warn | 某项 NFR 未指定且没有对应条目 |
落盘
<session cwd>/.prd-canvas/<prdId>/
prd.json 模型(真相源)
prd.md 最近一次 markdown 导出
prd.export.json 最近一次机器可读导出(**不会**覆盖 prd.json)
prd.docx 最近一次 Word 导出(零依赖手写 OPC/ZIP,Word/WPS 可开)
assets/ 源图(文件名 = 内容 sha1 前 12 位,同一张图重复 apply 不会变成两张)
源图缩略图为什么会是占位块
prd_canvas_apply 从模型那里拿到的只是图的指针(附件哈希名、绝对路径、或相对工作区的路径),字节不会自己进画布。所以 host 在 apply / 打开画布 / /asset 命中失败时,会把能解析到的文件真的拷进 assets/ 再服务:
| 模型写什么 | 怎么解析 |
|---|---|
{path: "C:/…/shot.png"} 或 "~/…" | 直接按绝对路径读 |
{path: "assets/shot.png"} | 相对会话工作区解析 |
"3f2a…"(32/64 位哈希,可带扩展名) | 去 $DSH_HOME/attachments/v1/objects/<前两位>/<哈希> 找 |
找不到就写 missing: true,画布画一块占位(文件名 + 「缩略图未落盘」),而不是让 <img> 失败后拿长 caption 当 alt 撑三行;拷成功则把 name 换成内容哈希名 + 魔数判出的扩展名,丢掉原始 path(免得本地绝对路径漏进导出)。
「图片没带过去」是怎么被堵住的
prd_canvas_apply 的 document.sourceImages[] 是模型唯一的带图通道,所以三处都在提醒它:
- 工具 schema:
sourceImages有自己的 items 结构,path的 description 就写着「对话贴图时必须给附件绝对路径,只给 name 会变成占位块」; - 随插件注册的 skill(
skills/prd-canvas/SKILL.md)有一节「图怎么『带过去』」,附可抄的调用样例; - 回执自纠:只要有一张图没落盘,
next第一条就是源图有 N 张没落盘(画布只能显示占位块):把对话附件的绝对路径写进 document.sourceImages[].path,再 apply 一次, 画布进度条 ① 也会显示0/1 张图没落盘——不再把「有 sources.images」当成「图带过来了」。
对话附件是无扩展名的内容寻址对象,所以落盘时按魔数判 png/jpg/webp/gif/svg:一张 JPEG 附件会落成 <哈希12位>.jpg,/asset 回 image/jpeg。
占位块本身是可点的:点它就走「上传图」的文件选择,重新选一张会填进这张占位卡(而不是再加一张),用户自己就能把丢掉的源图补回来。
参数 JSON 断在半路(已堵一半)
2026-11-17 的真实事故:一次 prd_canvas_apply 把 28 条需求压进一行 15KB JSON(1761 个双引号),正文里
一个没转义的 ASCII " 让整轮报 Expected ',' or '}' after property value in JSON at position 1310。
DSH 在流结束时就抛 MALFORMED_RESPONSE,工具函数根本没被调用,模型也拿不到可修正的反馈——这一轮 0 产出。
(resources/app.asar 里的 parseJsonWithRepair 只修控制字符与非法转义,裸引号在语法上无法判定,修不了。)
插件侧能做的是把「一次写完整份文档」这条路收窄:
- 工具 schema + 描述 + skill 三处都说分块:每次 ≤6 条需求 / ≤6000 字符,其余
mode:"merge"追加,同reqId覆盖不重复; - 守卫:超限直接回
document-too-large(带「怎么改」的 message),把「合法但巨大」的调用挡在写盘前,并让模型自己收敛; - 回执提醒:一块写满 6 条时,渲染文本里多一句「还有条目就继续 apply(mode:"merge")」;
- 条目超过 12 条建议走
prd_canvas_import传 markdown 纯文本。
边界要讲清:JSON 已经非法时守卫也无效(参数进不来),分块只是把失败代价从「28 条全丢」降到「补剩下几条」。
开发
npm test # 六套一起跑(87 条断言)
node scripts/dom-smoke.local.mjs # 真 DOM(jsdom + React 18):拖拽 / 双击编辑 / 保存 / 导出 / 源图占位 / 发回会话
node test/model.test.js # 门禁 / 归并 / 导出(20 条)
node test/import.test.js # 导入解析:章节/类型/AC/表字段(13 条)
node test/docx.test.js # Word 包结构(6 条)
node test/skills.test.js # 随插件注册的 skill(8 条)
node test/host.test.js # 真插件装进假 ctx:工具注册 + 路由往返 + 落盘 + 源图带过去 + 分块守卫(34 条)
node test/client.test.js # 假 React 冒烟:注册 + 渲染(6 条)
scripts/dom-smoke.local.mjs 依赖本机别的 checkout 里的 jsdom 与 react 18(路径写死),所以不进 npm test;
它证明的是假 React 证明不了的事:按下→移动→松手真的发出 move(坐标 = 起点 + 位移),双击真的开出 textarea,
保存真的发出 patch,导出真的打到 /export,<img> 报错真的换成占位块。当前 22/22 通过。
改了 host:plugin_manager set_plugin 先 disable 再 enable(include:dsh-prd-canvas)。
改了 client:刷新页面。
没用浏览器控制台时怎么排错
客户端渲染/挂载出错会 POST 到 /dsh-prd-canvas/api/note,host 写成
$DSH_HOME/dsh-prd-canvas/note-<ts>.json(含 message / stack / 文件名)。只看这一个目录就知道画布为什么白屏,
不用猜。只上报 stack 或文件名里带 dsh-prd-canvas 的错误,不会收别人的。
不用开 DSH 也能导出 / 造数据
node scripts/export.mjs "<工作区目录>" <prdId> docx # md | json | docx
造一块示例画布(不用等模型看图)
node scripts/seed-demo.mjs "<工作区目录>" "<sessionId>" "assets/checkout-wireframe.png"
它走的是真的 lib/store + lib/model,写出来的就是 prd_canvas_* 会写的那份文件;刷新页面后画布会通过
GET /session(磁盘兜底)直接恢复这块板。
Comments
Loading…