分支问卷svgop/dsh-rich-questions

dsh-rich-questions

面向 DeepSeek Harness 的分支式问卷——由你的 agent 现场编写，在你的聊天中作答。

你的 agent 不只是发送一份问卷——它会根据对话上下文编写一份：一个问题的有向图，每个答案决定接下来问什么，每个选项都带有自己的推理，而整个内容就渲染在你此刻正看着的同一个输入框位置。一次工具调用。无需表单产品，无需账号，无需复制粘贴。

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

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 进程，刷新标签页——完成。现在每个 agent 预设都能看到 ask_survey 工具。（从 fork 安装：dsh plugin --profile web add file:/path/to/dsh-rich-questions。）

你能得到什么

| | |
|---|---|
| 分支路径 | 每个选项都声明其后续内容（next）。选择 C，得到的问题范围与 A 不同。多选会以深度优先方式展开；跳过/自由文本会干净地落入后续；宿主会独立重新推导路径，因此所声称的路径始终可验证。 |
| 逐选项智能 | 洞察（约 6 行，以三元组呈现：Promise——选择它会带来什么 / Price——它的成本或风险 / Present——当前状况，并附有具体抓手）、来源与引用，以及紧凑的 Mermaid 图表——全部藏在一个点击展开的折叠区后面（文本用 ?，图表用分支图标）；绝无悬停突袭。 |
| 说明理由 | 被选中的选项会获得一个铅笔图标：用一行说明你为什么选择这个选项（内联输入，勾选或回车提交，提交前可随时重新编辑）。理由会作为 justifications 随答案一起传递——agent 在推导后续问题时会读取你陈述的意图。 |
| 快速模式 | 在“开始”旁边最多有六个整份问卷的决策模板（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 细线分隔（无浮动标签）；自由文本行以自身分隔线出血，页脚是出血工具栏——操作按钮作为全高段右浮动，由垂直细线分隔，返回箭头和进度保持在左侧
- 每个操作按钮都由延迟工具提示解释——开始/下一步/提交（上下文相关）、跳过、暂存、快速、重掷、推送、讨论、返回、最小化、取消
- 键盘可操作行，aria-labelled 控件；UI 界面本地化（英语 / 简体中文，其他语言优雅回退）
- 主机权威的待处理状态，环回围栏路由，SSE + 轮询再水合

声明是一列，而不是接管

待处理调查仅替换输入卡片。该声明以编辑器堆栈自身的节奏在向导卡片上方重新渲染环境输入坞（待办胶囊、跟踪板、目标栏），因此编辑器区域保持其形状——聊天记录在上方保持可见，上下文在下方保持停靠，输入区域中没有其他内容被隐藏。

最小化（向导标题中的 V 形图标）完全释放编辑器：真实聊天输入返回，并且一个圆形重新打开按钮出现在编辑器卡片下方的环境坞中（附件圆形语法），以重新打开调查——进行中的答案通过覆盖重新加载的同一持久化在往返中存活。当调查结束时，该标志会自行清除，因此新的询问总是以展开状态开始。

中止的启动永远不会使草稿陷入死胡同。 当已启动的运行被中止（代理挂钟时间、操作员停止）时，向导结算为 cancelled——并且草稿重新打开（reopened 状态，发出帧），因此构建器循环可以修补并重新启动，而不是盯着卡住的卡片。对称地，客户端在每次待处理表变更（请求 / 已解决 / 草稿帧）时重新运行编辑器选举，因此即使在没有聊天记录流量的会话中，席位也能迅速声明和释放。

编写指南

一个规范，涵盖所有能力：

{
"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": "最高标准：Vercel/Railway 级别", "recommended": true,
"insight": "承诺：此模板会搭建什么。代价：它的取舍。适用：它今天适合谁。",
"answers": { "q1": { "selected": ["a"] }, "q2a": { "selected": ["b"] }, "q3": { "selected": ["a", "c"] } } },
{ "key": "b", "label": "精简内部工具", "answers": { "q1": { "selected": ["b"] } } }
]
}
}

边语义 —— 严格强制执行：

| 情况 | 后续 |
|---|---|
| 单选，选项有 next | 该选项的 next（id、列表或 null = 结束） |
| 单选，选项没有 next | 问题级别的 next |
| 多选 | 每个已选选项的分支，深度优先，按选项顺序 |
| 跳过 / 仅自由文本 | 问题级别的 next |
| 没有剩余 / next: null | 调查结束 |

验证是自我修复的。 每条规则都会在编写时于宿主侧检查：entry 存在，每个 next 都指向真实的问题（问题级别的 null = 无后续），无循环，选项键唯一，快速模板只引用可达的问题且使用真实的选项键，每个带选项的问题都包含至少 5 个选项（键 a–e，目标 5–8 个——真正不同的立场；自由文本行是单独的且不计入），大小上限成立（150 个问题 / 40 个选项 / 1500 字符的 insight / 1200 字符的图表 / 8 个来源 / 6 个模板 / 500 字符的说明）。被拒绝的规格会得到确切的违规位置、悬空引用的最近已定义 id，以及完整 id 清单——重试一次即可修复。

当调用失败时：“survey must be an object”

测试框架会宽松地解析工具调用参数：有效的 JSON 会作为已解析对象到达，格式错误的 JSON 会作为原始文本字符串到达，而空载荷会作为 {} 到达。输出预算较小的模型（本地 27B、高度量化的构建）可能会在 JSON 中途截断较大的 ask_survey 载荷——规格永远不会作为对象到达，而较旧的插件构建只能回答 survey must be an object，这读起来像是“修复规格”，并会招致一次完全相同且注定失败的重试。

该工具现在会尽可能恢复，否则会指出真正的原因：

- 本身是 JSON 字符串的 survey 字段会被正常解析和验证。
- 作为原始文本到达的参数，如果是有效 JSON，会被整体解析。
- 其他任何情况都会得到一份诊断信息，其中包含 JSON 语法错误和修复方法：重新发送更小的载荷（精简 insight/detail 字符串，将选项削减到五个，去掉快速模板）或将调查拆分为两次连续调用——绝不要重新发送完全相同的载荷，因为失败原因是大小，而不是内容。
快速模板可达性错误现在也会列出模板选项实际可达的路径（reaches only: q1, q2a, q3），因此错误的分支只需一行修复，而无需猜测。

问题构建器

对于大型、基于研究的调查，一个巨大的 ask_survey 载荷是错误的形态：生成缓慢、在小型本地模型上容易截断，并且它迫使所有研究在写下第一个字之前完成。构建器运行一个研究优先循环——在锁定结构之前研究 9–12 个可比系统，然后在草稿增长的同时继续研究：

research first                 研究 9–12 个可比系统；发现 → .docs/research/，
摘要 → .docs/digest/，竞品 UI/API 拆解 → .docs/research/rips/，
竞品源码 → .refs/ —— 没有写下来的研究等于没发生
survey_draft_set op=begin      锁定一个全框架骨架（ids、≥5 个选项键、分支接线；提示/标签可以是 "TODO:" 占位符）
↕  用你自己的工具继续研究
survey_draft_set op=patch      每次调用 ≤3 个问题，按字段合并。现有 ids：正文 + 选项字段以及分支接线（question/option .next：id、id 数组或 null）。新 ids：作为草稿级占位符添加——增量扩展图，无需重发整个结构。同一操作设置草稿级 intro 和 quick（模板最后编写，立即进行覆盖检查）
survey_draft_get               必填字段清单（每个选项：label、description、insight、≥1 个 source）——启动门槛
survey_draft_launch            拒绝任何 TODO:，然后启动向导；reroll/push/discuss 会重新打开草稿

任何操作都可以指向一个工作区 JSON 文件（file:），而不是内联其载荷——用你的文件工具写一次图，针对该路径迭代操作，出错后重新运行同一调用（内联字段优先）。专为 Push 规模的图而构建，在这种图中，每次尝试都重新发出 200 个选项的载荷正是失败模式。

这个循环是被命令执行的，而不是建议的：研究 → 补丁 → 获取，直到门槛干净，然后启动。结果带有一个 handling 契约——用一行回映用户的立场，将决策追溯到答案，绝不重新询问调查已经回答过的问题。

值得了解的规则：

- 草稿就是文件。 会话工作区中的 .dsh/survey-drafts/.json（可 git diff；旧草稿保留作为参考），并在 ~/.dsh/rich-questions/drafts/index.json 下有一个机器本地清单（状态，每个对话一个活动草稿）。没有工作区？草稿回退到机器本地。
- 软结构锁。 当传入图低于 structureQuestionCap（cordis 配置，默认 150——与 ask_survey 相同的上限，因此从任何可启动调查出发的 Push 强制要求的 2× 深度计算始终能容纳）时，允许 op=structure（整图替换）；每次使用都会增加一个修订计数器，并在传入图省略草稿标题时保留草稿标题。补丁添加和内容补丁在任何规模下都继续可用。
- 必需，而非阻塞。 每个选项的标签/描述/洞察/来源以及每个提示都是必填字段——get 会持续列出所有缺口；启动是唯一的强制执行点。
- 草稿卡片占用输入框的空间。 一张追踪器风格的进度卡片在构建期间占据撰写器席位——与已启动的向导具有相同的空间内契约（进度条、计数、修订）。关闭它会将其折叠为席位中的一行条带（绝不会是空席位，也绝不会是输入框下方的停靠行），而过期的关闭——任何修订或状态变化——都会重新展开完整卡片。启动时，向导接管席位；卡片关闭并融入其中。
- 无过期。 待处理的调查会无限期等待——TTL 清理器已移除。唯一的结算路径是用户自己的操作（回答/取消/预检）或回合中止。
- 没有任何事情会无声结束。 每次结算都会将完整记录——规格、已存入的答案、结果——以追踪器风格持久化到 ~/.dsh/rich-questions/surveys/.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/.md … re-author at GUARANTEED DOUBLE DEPTH … re-enter the builder loop …"
}

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

架构

src/host.js            Node 部分——ask_survey 工具、带预写式存入的待处理调查注册表、
/api/rich-questions/{state,action,events} 路由、
双语系统提示公告。仅使用 Node 内置模块。
src/survey-engine.js   纯引擎——分支路径计算 + 自修复的
规格/答案验证。由宿主导入，并逐字内联
到客户端 bundle 中（保持两者同步）。
src/client.bundle.js   浏览器部分——撰写器席位向导（草稿自动保存、
存入、快速模式、图表、工具提示）以及
席位内构建器草稿卡片及其错误边界。
仅使用 React + 客户端原语。
skills/                作为可加载技能的创作准则（循环、带
完整示例的标准、感觉、升级保证）——
复制到工作区 .agents/skills/ 以供
catalog 进行拾取。
cordis.patch.yml       插入插件行的捆绑补丁。

Mermaid 引擎在首次展开图表时从 CDN 延迟加载，之后进行缓存——其他所有内容均完全离线。

许可证

MIT