分支问卷 svgop/dsh-rich-questions

dsh-rich-questions

为 DeepSeek Harness 打造的分支问卷 —— 由你的智能体现场编写，在聊天里作答。

你的智能体不只是发一份问卷 —— 它会根据对话上下文编写一份：一张有向图，每个答案决定下一题问什么，每个选项自带推理，整份问卷渲染在你眼前这个输入框位置。一次工具调用。不用表单产品，不用账号，不用复制粘贴。

富问题/问卷系统 —— 由智能体现场编写的分支问卷：每个答案决定下一题，每个选项自带洞察与流程图，直接在聊天输入框位置作答。

MIT · 零运行时依赖 · DSH ≥ 0.1.2-alpha.1 · Node ≥ 20

flowchart LR
A[Agent composes survey] --> B{Quick mode?}
B -- pick a template --> Q[All answers appliedone click, submitted]
B -- walk it --> C[Question 1]
C -- option a --> D[Branch A]
C -- option b --> E[Branch B]
D --> F[Paths converge]
E --> F
F --> G[Banked along the waysurvives any reload]
G --> R[Structured resultback to the agent]
Q --> R

安装

dsh plugin --profile web add dsh-rich-questions

重启 dsh web 进程，刷新标签页 —— 搞定。现在每个智能体预设都能看到 ask_survey 工具。（从 fork 安装：dsh plugin --profile web add file:/path/to/dsh-rich-questions。）

你会得到什么

| 分支路径 | 每个选项都声明它后面接什么（next）。选 C，问到的题目范围和 A 不同。多选按深度优先展开；跳过和自由文本会干净地落到下一题；宿主会独立重新推导路径，所以声称的路径永远可验证。 |
| 每个选项的洞察 | 洞察（约 6 行，按三段式写：承诺 —— 选它会带来什么 / 代价 —— 它要付出或冒什么风险 / 现状 —— 今天是什么情况，附一个具体抓手）、来源与引用，以及紧凑的 Mermaid 图 —— 全部藏在一个点击展开的折叠区后面（文字用 ?，图用分支图标）；绝不搞悬停突袭。 |
| 说明理由 | 选中的选项会多出一个铅笔图标：用一行话说明为什么选它（行内输入，打勾或回车提交，提交前随时可改）。理由随答案一起作为 justifications 传回 —— 智能体推导后续问题时能读到你的明确意图。 |
| 快速模式 | Start 旁边最多有六个整份问卷的决策模板（a–f）——「像 Vercel/Railway 那样发布：打磨 + DX 优先」对比「精简内部工具：快速上线」。点一下应用一套完整、自洽的答案映射并提交。20 题的对齐练习变成一次决策。 |
| 暂存与继续 | 长问卷按步提交：你继续往下走的同时，已答内容在后台送到宿主。暂存的答案会锁定（此后永远只读），刷新不丢，换浏览器也跟着你。一个 {n} banked 小标签跟踪它们。 |
| 进度持久化 | 每份问卷自动保存草稿——刷新页面、切换标签页、明天再来：还是同一道题、同样的答案、同样的位置。不用按任何键。 |
| 开跑前先掌舵 | 重写（把问卷改得更干净，同时加码：质量线每一处缺口都补齐，深度绝不缩水）、推进（调研结果落成可复用的产物：摘要 → .docs/digest/，发现 → .docs/research/，竞品 UI/API 拆解 → .docs/research/rips/，竞品源码 → .refs/；先研究 12+ 个系统，再以 2× 深度重新撰写，逐条引用证据）、讨论（放下表单，直接聊）——各一键，都在第一道题之前。 |
| 语言跟着你走 | 英文对话 → 英文问卷。中文 → 中文。任何语言 → 就用那种语言，前后一致。 |
| 以宿主为准 | 待答问卷存在宿主上——关掉浏览器、杀掉标签页，工具继续等，重连后向导自动恢复。 |

为什么做这个

ask_user_question 用来问 1–3 道平铺直叙的问题很完美，再多就不行了。真正的工作——摸清期望、定验收标准、把一个构建任务拆到十几个相互影响的维度上——需要路径（一个答案会改变接下来什么重要）、深度（一行标签不足以做出好选择）、速度（有时你早就知道目的地）。ask_survey 就是这套系统，同时不碰简单流程。

对比

对照主流问卷平台和向导式提交模式做过调研：

| 能力 | dsh-rich-questions | Typeform | SurveyMonkey | Google Forms | MS Forms |
| 问卷由对话上下文实时生成 | ✅ | — | — | — | — |
| 图状分支（每个选项带 next） | ✅ 原生 | 逻辑跳转（付费） | ✅ | 仅分节 | 基础 |
| 刷新后恢复进度 | ✅ 自动保存 | 同一浏览器 | 靠恢复链接 | 同一浏览器 + 登录 | ❌ |
| 已提交答案不因浏览器丢失而丢 | ✅ 入库，任意浏览器 | 部分（付费） | ❌ | ❌ | ❌ |
| 提交后答案锁定 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 一键套用整份问卷的决策模板 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 重写 / 深度调研 / 讨论 三种改道 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 每个选项带洞察 + 来源 + 图示 | ✅ | 描述 | 描述 | 描述 | 描述 |
| 协议 | MIT | 商业 | 商业 | 免费（需账号） | 免费（需账号） |

另外还研究了 Qualtrics、Jotform、Tally、Fillout、SurveySparrow 的部分提交行为，以及 Stripe/TurboTax 那种逐步提交的向导——入库沿用向导模式，而上面这些问卷工具没有一个实现它。

向导

渲染在输入框位置，沿实时分支路径一页一题：

- 进度条 + 已答/总数，按当前路径计算；返回时根据已保存答案重新判断分支
- 多选带复选框，other 自由填写行，每题可设 skippable
- 通栏行语法：选项行铺满卡片左右边缘，用 1px 细线分隔（不用浮动小标签）；自由文本行同样通栏，自带分隔线；页脚是通栏工具栏——操作按钮靠右浮动，做成整高分段，段间用竖细线隔开，返回箭头和进度留在左侧
- 每个操作按钮都有延迟提示词说明——Start/Next/Submit（按上下文变化）、Skip、Bank、Quick、Reroll、Push、Discuss、返回、最小化、取消
- 选项行支持键盘操作，控件带 aria 标签；界面文案本地化（EN / 简体中文，其他语言优雅回退）
- 待处理状态由宿主端说了算，路由限制在回环地址内，SSE + 轮询重新水合

占位的是输入列，不是整个输入区

待填问卷只替换输入卡片。占位时，向导卡片上方会按输入区自身的节奏重新渲染常驻输入坞（待办胶囊、追踪板、目标栏），输入区的形状保持不变——上方聊天记录照常可见，下方上下文照常停靠，输入区其他内容一概不隐藏。

最小化（向导标题栏里的折叠箭头）会完全释放输入区：真正的聊天输入框回来，输入卡片下方的常驻坞里出现一个圆形重开按钮（沿用附件圆钮的语法），点它重开问卷——已填的答案经同一套持久化机制在往返中保留，重载也不丢。问卷结束后该标记自动清除，所以每次新提问都从展开状态开始。

启动被中止，草稿不会走进死胡同。 已启动的运行被中止时（智能体超时、操作员停止），向导落定为 cancelled——草稿随即重新打开（reopened 状态，发出 frame），构建循环可以打补丁再重启，而不是对着卡死的卡片干瞪眼。对称地，客户端在每次待处理表变化时（requested / resolved / draft frame）重跑输入区选举，所以即使会话没有聊天记录流量，席位也能及时占用和释放。

编写指南

一份 spec，覆盖全部能力：

{
"survey": {
"title": "Expectation alignment",
"intro": "Short markdown preamble — the first page.", "entry": "q1",
"questions": {
"q1": {
"prompt": "Which direction fits this release?",
"header": "Scope",
"detail": "Optional markdown context.",
"options": [
{
"key": "a",
"label": "Ship the public surface",
"description": "One-line tradeoff, always visible.",
"insight": "Promise — …\nPrice — …\nPresent — …",
"diagram": "flowchart TD; ship-->polish; polish-->latency; latency-->done",
"sources": ["https://example.com/rfc-1"],
"recommended": true,
"next": "q2a"
},
{ "key": "b", "label": "Rework the core first", "next": "q2b" },
{ "key": "other", "label": "Something else" }
],
"next": "q2b"
},
"q2a": { "prompt": "…", "next": "q3" },
"q2b": { "prompt": "…", "next": "q3" },
"q3": { "prompt": "…", "multiSelect": true }
},
"quick": [
{ "key": "a", "label": "Highest standard: Vercel/Railway grade", "recommended": true,
"insight": "Promise: what this template sets up. Price: its tradeoff. Present: who it is for today.",
"answers": { "q1": { "selected": ["a"] }, "q2a": { "selected": ["b"] }, "q3": { "selected": ["a", "c"] } } },
{ "key": "b", "label": "Lean internal tool", "answers": { "q1": { "selected": ["b"] } } }
]
}
}

边界语义 —— 严格照此执行：

| 情况 | 走哪条分支 |
| 单选，选项带 next | 走该选项的 next（id、列表，或 null 表示结束） |
| 单选，选项不带 next | 走问题级的 next |
| 多选 | 每个选中选项的分支都要走，深度优先，按选项顺序 |
| 跳过 / 只填了自由文本 | 走问题级的 next |
| 没有剩余问题 / next: null | 问卷结束 |

校验会自我修复。 每条规则都在编写阶段由宿主侧检查：entry 存在；每个 next 都指向真实问题（问题级 null 表示没有后续）；没有环；选项 key 唯一；快捷模板只引用可达问题，且选项 key 真实存在；每个带选项的问题至少 5 个选项（key 为 a–e，目标 5–8 个 —— 立场要真正不同；自由文本行单独算，不计入数量）；尺寸上限成立（150 个问题 / 40 个选项 / 1500 字符的 insight / 1200 字符的图表 / 8 个来源 / 6 个模板 / 500 字符的理由）。被拒绝的 spec 会拿到确切的出错位置、悬空引用对应的最近已定义 id，以及完整 id 清单 —— 重试一次就能修好。

调用失败时：「survey must be an object」

harness 解析工具调用参数时比较宽松：合法 JSON 会作为解析后的对象到达，格式错误的 JSON 会作为原始文本字符串到达，空载荷则作为 {} 到达。输出预算小的模型（本地 27B、重度量化的构建）可能把很大的 ask_survey 载荷在 JSON 中途截断 —— spec 永远到不了对象形态，旧版插件只能回一句 survey must be an object，读起来像是「去改 spec」，于是模型会原样重试，注定再失败一次。

现在工具会尽量抢救，救不了就点明真正的原因：

- survey 字段本身是 JSON 字符串时，照常解析并校验。
- 参数以原始文本到达、且本身是合法 JSON 时，整体解析。
- 其他情况给出诊断，附上 JSON 语法错误和修法：重发更小的载荷（精简 insight/detail 字符串，选项砍到五个，去掉快捷模板），或者把问卷拆成两次连续调用 —— 千万别原样重发，因为失败原因是尺寸，不是内容。
快速模板的可达性错误现在还会列出模板选项实际能到达的路径（reaches only: q1, q2a, q3），分支出错时改一行就能修好，不用再猜。

问卷构建器

做大型、有调研支撑的问卷时，一个巨大的 ask_survey 载荷是错误的选择：生成慢，在小参数本地模型上容易截断，还逼着所有调研都写完才能动笔。构建器跑的是调研优先循环——先研究 9–12 个同类系统，再锁定结构，然后一边写草稿一边继续调研：

research first study 9–12 comparable systems; findings → .docs/research/,
digests → .docs/digest/, competitor UI/API rips → .docs/research/rips/,
competitor source → .refs/ — research that is not written down did not happen survey_draft_set op=begin lock a full-frame skeleton (ids, ≥5 option keys, branch wiring; prompts/labels may be "TODO:" stubs) ↕ keep researching with your own tools survey_draft_set op=patch ≤3 questions per call, per-field merge. Existing ids: prose + option fields AND branch wiring (question/option .next: id, id array, or null). NEW ids: added as draft-grade stubs — grow the graph incrementally, no whole-structure resend. The same op sets draft-level intro and quick (templates authored LAST, coverage-checked immediately) survey_draft_get the required-field checklist (per option: label, description, insight, ≥1 source) — the launch gate survey_draft_launch refuses any TODO:, then starts the wizard; reroll/push/discuss REOPEN the draft

任何 op 都可以指向工作区 JSON 文件（file:），不必内联载荷——用文件工具把图写一次，之后针对该路径反复迭代 op，出错后重跑同一个调用即可（内联字段优先）。这是为 Push 规模的图准备的：每次尝试都重新输出 200 个选项的载荷，正是失败模式所在。

这个循环是强制执行的，不是建议：调研 → patch → get，直到检查清单全部通过，再 launch。结果带有 handling 约定——用一行话复述用户的立场，把决策追溯到答案，绝不重问问卷已经回答过的问题。

值得了解的规则：

- 草稿就是文件。 会话工作区里的 .dsh/survey-drafts/<slug>.json（可 git diff；旧草稿保留作参考），外加机器本地的清单 ~/.dsh/rich-questions/drafts/index.json（记录状态，每个会话只有一个活跃草稿）。没有工作区？草稿回退到机器本地。
- 软结构锁。 只要传入的图不超过 structureQuestionCap（cordis 配置，默认 150——与 ask_survey 的上限相同，因此从任何可启动问卷出发，Push 要求的 2 倍深度计算总能装下），就允许 op=structure（整图替换）；每次使用都会递增修订计数器，并在传入图省略标题时保留草稿标题。patch 添加和内容补丁在任何规模下都继续可用。
- 必填，不阻塞。 每个选项的 label/description/insight/sources 和每条提示词都是必填字段——get 会持续列出所有缺口；启动是唯一的强制校验点。
- 草稿卡片占用输入区。 构建期间，一张追踪式进度卡片占据输入框位置——与已启动的向导遵循同一套空间约定（进度条、计数、修订）。关闭后，它收拢为输入区内的一行条带（绝不留空输入区，也绝不在输入框下方新增一行），而一旦过期关闭——任何修订或状态变化——就会重新展开完整卡片。启动时，向导接管输入区；卡片收拢进去。
- 不过期。 待处理的问卷无限期等待——TTL 清理器已移除。唯一的结算路径是用户自己的操作（回答 / 取消 / 预检）或回合中止。
- 没有静默结束。 每次结算都会持久化完整记录——spec、已存入的答案、结果——写入 ~/.dsh/rich-questions/surveys/<surveyId>.json，采用追踪式格式。

结果形态

已完成（手动逐题、快速模板或混合——无法区分）：

{
"outcome": "answered",
"path": ["q1", "q2a", "q3"],
"answers": [
{ "id": "q1", "selected": [{ "key": "a", "label": "Ship the public surface" }] },
{ "id": "q3", "selected": [{ "key": "a", "label": "…" }, { "key": "c", "label": "…" }] } ],
"skipped": [],
"handling": "Open your next turn by mirroring the user’s stance in one line before acting on these answers (…). Trace each landed decision back to its answer … Never re-ask what this survey already answered …"
}

预检重定向：

{
"outcome": "push",
"instruction": "The user hit \"Push\" before starting: … study a MINIMUM of 12 competitors … write the digest to .docs/digest/<topic>.md … re-author at GUARANTEED DOUBLE DEPTH … re-enter the builder loop …"
}

存入答案从不改变结果形态——存入的答案就是答案，只是提交得更早，并在过程中锁定。

架构

src/host.js Node half — ask_survey tool, pending-survey registry with write-ahead banking, /api/rich-questions/{state,action,events} routes, bilingual system-prompt announcement. Node builtins only. src/survey-engine.js Pure engine — branch-path computation + self-repairing spec/answer validation. Imported by the host AND inlined verbatim into the client bundle (keep the two in sync). src/client.bundle.js Browser half — the composer-seat wizard (draft autosave, banking, quick mode, diagrams, tooltips) plus the in-seat builder draft card and its error boundary. React + client primitives only. skills/ The authoring doctrine as a loadable skill (loop, bar with a worked example, feel, escalation guarantees) — copy to the workspace .agents/skills/ for the catalog 才能识别。
cordis.patch.yml 插件补丁，用来插入插件行。

Mermaid 引擎在首次展开图表时从 CDN 懒加载，之后会缓存 —— 其余功能完全离线。

许可证

MIT