DSH Plugins Marketplace

DSH Plugins

Plugins

/

dsh-prd-canvas

d

dsh-prd-canvas

Manifest valid

PRD Canvas for DeepSeek Harness: Image/Requirements/Existing PRD → Right-side draggable, gate-passing PRD board, export to md/json/docx

UI (client)hasBundlePatch

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 的真实缺口, 不是解析错误。

用法

  1. 在会话里发一张图,问一句「按这张图出 PRD」。
  2. 模型会调 prd_canvas_open → prd_canvas_apply,右侧画布自动打开并画出卡片。
  3. 在画布上:拖卡片 / 双击改正文 / 改 GIVEN-WHEN-THEN / 切换确认态 / 删卡片。
  4. 底部输入框写「R-003 少了超时分支」→ 点「发回会话」,消息回到会话,模型据此 prd_canvas_patch。
  5. 顶部「导出 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-missingblock没有依据
ac-missingblock没有验收标准
ac-untestableblock缺 GIVEN/WHEN/THEN、含模糊措辞、THEN 无可观测结果
statement-multi-shallwarn一句话里多个「应/须」
duplicatewarn两条表述重复(bigram Jaccard ≥ 0.8)
nfr-unspecifiedwarn某项 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[] 是模型唯一的带图通道,所以三处都在提醒它:

  1. 工具 schema:sourceImages 有自己的 items 结构,path 的 description 就写着「对话贴图时必须给附件绝对路径,只给 name 会变成占位块」;
  2. 随插件注册的 skill(skills/prd-canvas/SKILL.md)有一节「图怎么『带过去』」,附可抄的调用样例;
  3. 回执自纠:只要有一张图没落盘,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 只修控制字符与非法转义,裸引号在语法上无法判定,修不了。)

插件侧能做的是把「一次写完整份文档」这条路收窄:

  1. 工具 schema + 描述 + skill 三处都说分块:每次 ≤6 条需求 / ≤6000 字符,其余 mode:"merge" 追加,同 reqId 覆盖不重复;
  2. 守卫:超限直接回 document-too-large(带「怎么改」的 message),把「合法但巨大」的调用挡在写盘前,并让模型自己收敛;
  3. 回执提醒:一块写满 6 条时,渲染文本里多一句「还有条目就继续 apply(mode:"merge")」;
  4. 条目超过 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…