结构化表单提问 Zekilou/dsh-ask-form

dsh-ask-form

DeepSeek Harness 的社区插件：让模型把结构化问题当成一份表单来问 —— 带类型的字段、条件与校验、只重问失败项 —— 并拿回带类型的 JSON 答案。

自带的 ask_user_question 是一个扁平选项列表，一页一题。ask_form 补上了字段类型、跨字段约束和"一次提交"，并且在无法渲染它的界面上自动降级为自带问答流程。

能力

- 14 种字段类型 —— confirm、single、multi、text、longtext、number、integer、date、tags、scale、slider、ranking、matrix、budget
- 条件与校验 —— visible_if、validate（白名单表达式语言，绝不用 eval）、pattern、max_length、min/max、sum_to
- 只重问失败项 —— 每轮只补问没答对/没答的字段，上限由 max_rounds 控制
- 类型化结果 —— scale/slider/number → 数字；ranking → 有序数组；matrix → {行: 选择}；budget → {项: 数字}；tags → 字符串数组
- 预设问卷包 —— requirement-intake、design-choice、release-gate、incident-intake，用 pack_args 调参
- 默认带"其他" —— single、multi、tags 默认接受自由文本（allow_other: false 可关闭）
- 逃生舱 —— mode: "script" 可在 Web 端渲染自定义 React 元素；其它界面由 script.fallback 决定行为
- 优雅降级 —— 没有本插件渲染器的界面仍会把每个字段当成普通问题发出，结果里以 renderer: "generic" 如实标注；script 模式则明确报错而不是静默降级

安装

前提：Harness profile 里有 plugin_manager 工具（web profile 自带）。

1. 安装 bundle —— 在 Harness 里让 agent 调用，或直接调用 plugin_manager：

action: install_bundle
target: github:Zekilou/dsh-ask-form

本地克隆的话，把 target 换成该目录的绝对路径：/absolute/path/to/dsh-ask-form。

2. 刷新一次 Harness Web 页面，让客户端 bundle（client.js）注册进来。
3. ask_form 工具就会出现在 ask_user_question 旁边。

用法

一次调用就是一份表单。字段按声明顺序展示；按惯例，列表里的第一个选项是推荐项。

{
"title": "运行时选型", "intro": "选运行时，并给评价维度分配权重。",
"fields": [
{ "name": "runtime", "type": "single", "label": "运行时",
"options": ["Node 22 (Recommended)", "Bun", "Deno"] },
{ "name": "needs_wasm", "type": "confirm", "label": "需要 WASM 吗", "visible_if": "runtime == 'Bun'" }, { "name": "weights", "type": "budget", "label": "维度权重（合计 100）",
"options": ["性能", "生态", "体积"], "sum_to": 100 },
{ "name": "priority", "type": "ranking", "label": "优先级排序",
"options": ["尽快交付", "尽量小", "可移植"] },
{ "name": "scores", "type": "matrix", "label": "逐维打分",
"rows": ["性能", "成本"], "options": ["高", "中", "低"] }
],
"notes": true
}

一行调用一个现成访谈：

{ "pack": "requirement-intake", "pack_args": { "topic": "缓存层" }, "notes": true }

返回的是类型化数值加上来源信息：

{ "status": "answered", "rounds": 1, "renderer": "form",
"values": { "runtime": "Bun", "needs_wasm": true,
"weights": { "性能": 50, "生态": 30, "体积": 20 },
"priority": ["可移植", "尽快交付", "尽量小"],
"scores": { "性能": "高", "成本": "低" } },
"notes": "…" }

status 取值：answered、incomplete、cancelled、aborted、no_answerer、unavailable、script_error。

实现

两个半边，无构建步骤。

Host 半边（index.js） 在既有的 ctx.userQuestions seam 上注册 ask_form 工具：把类型化表单编译成普通的 AskUserQuestionItem[]（所以任何应答面都还能作答），并把完整规格通过标记题的 intent 带给自己的渲染器；随后既解码渲染器的 JSON 信封，也解码普通选项/标签答案，在 Host 侧校验，并只补问失败项。

Client 半边（client.js） 在 conversation.composer chain 里注册一个低优先级条目：只有当某个问题带着本插件的 intent.kind 时才接管，把整份表单渲染成居中的浮层（react-dom portal + 原生 Modal 几何），并以 JSON 信封作答。其它任何待答请求（包括 plan review）都返回 null，仍由自带 composer 处理 —— 所以装上这个 bundle 不会改变自带流程。

几个值得一提的行为：

- wire 必须是无损 JSON —— 规格要能原样通过 JSON 往返；一个"值为 undefined"的属性会让 Remote event 网关拒收整个请求。
- 自证探针 —— 标题为 DSH_ASK_FORM_PROBE 的表单会被自动作答，回传一份 DOM 报告（卡片矩形、计算样式、elementFromPoint 命中测试）。这个插件就是靠它在没有浏览器自动化的情况下定位问题的，以后诊断坏掉的渲染面也仍然有用。
- 提交看门狗 —— 答案 10 秒内没送达（连接被挂起或替换）就自动解开按钮并写明原因，而不是永远卡在"提交中…"。
- bfcache 提示 —— 从后退/前进缓存恢复的页面已经失去了承载该请求的 socket，卡片会直接说明，而不是让点击无声失效。

自验

两套独立脚本，不需要装 monorepo，也不需要浏览器：

node tests/host.test.mjs # 编译 -> 解码 -> 校验 -> 多轮 -> 取消
node tests/client.test.mjs # 渲染树、标记选择器、提交信封

它们用桩 React（真实 React 由页面提供）驱动真实组件树，因此断言的是结构与协议，不是像素。tests/client.test.mjs 从 package.json 读取 bundle id，所以改名不会再让它们失配。

兼容性

- Host 半边需要 ctx.tools 与 ctx.userQuestions。
- Client 半边需要 conversation.composer chain，以及作为 shell seed word 的 react-dom（Web 端都有）。
- 针对 0.2.0-rc.2 时代的 pre-stable @deepseek-ai/dsh-* 包编写，这些 API 可能变动。

有意偏离自带问答卡的地方

- 浮层是带遮罩的居中模态，不是 composer 接管位。
- 点遮罩不关闭、Esc 也不取消 —— 避免一次误点毁掉填了一半的表单。

归属

客户端样式改写自 MIT 许可的 Harness 客户端包，类名统一改到本插件前缀下：

- @deepseek-ai/dsh-client-ui-primitives —— Button、Input、Tag、SegmentedControl、Modal 几何
- @deepseek-ai/dsh-client-ui-user-questions —— 问答卡结构、选项行、推荐标记

详见 THIRD_PARTY_NOTICES.md。

许可

MIT —— 见 LICENSE。