sumingwang233/dsh-question-bridge

dsh-question-bridge

给 DSH Agent 用的"提问桥"：Agent 可以在回合中间向人提问，拿到一个批次号后立刻返回；人稍后在原生问题卡片或右下角的待答面板里回答；答案以一条普通的 user/message 回到会话里，Agent 接着干。

它解决的问题很具体：DSH 原生 ask_user_question 是阻塞的——工具不返回，回合就停在那儿，人不在电脑前就等于卡死。这个插件把"提问"和"等待"拆开：

• 工具 ask_interactive_question 立即返回 { status: "pending", batchId }，并明确告诉模型：pending 不是答案、不是授权；
• 批次状态落在插件自己的 JSON 文件里，DSH 重启、页面刷新都不丢；
• 答案落盘后通过 agent.steer() 送进会话，只有日志里真的出现那条 user/message 才算 delivered；
• 没人理它也不会伪造已读，关闭卡片、超时、通知都不等于回答。

安装

目标基线是 DSH Desktop 0.2.0-rc.2（宿主 tag dsh-v0.2.0-rc.2）。最短路径：

1. 从 Releases 下载 dsh-question-bridge.tgz，放进 ~/.dsh/plugins/packages/；
2. 在 ~/.dsh/profiles/desktop/package.json 的 dependencies 和 dsh.profile.bundles 里各加一条 dsh-question-bridge；
3. pnpm install，然后完全退出并重启 DSH。

细节、自检和排错见 docs/installation.md，兼容性与刻意的取舍见 docs/compatibility.md。

用法

装上之后，Agent 会在需要人做决定的地方调用：

{
  "questions": [
    {
      "question": "通知走哪条链路？",
      "header": "通知",
      "detail": "两条都能离线工作，区别在多窗口时谁来弹。",
      "options": [
        { "label": "WebSocket 推送", "recommended": true },
        { "label": "两秒轮询" }
      ]
    }
  ]
}

工具返回 pending 后回合继续。人回答之后，会话里多一条这样的用户消息：

{
  "kind": "answer_to_question_bridge",
  "batchId": "…",
  "revision": 2,
  "questions": [ … ],
  "answers": [{ "questionId": "…:q1", "choiceIds": ["…:q1:c1"], "skipped": false }]
}

模型只需认这个 kind；问题文本、推荐项、自动生成的选项都不是用户的决定。

另外两个入口：

• 原生卡片：插件把批次转成原生 AskUserQuestionItem 调 userQuestions.ask()，但不传 wait.callId，所以卡片只是渲染器，答案由插件自己收。
• 普通文本识别：回合结束时，如果助手最后一段话里明显在向人提问，插件会按规则切出来（跳过代码块、引用、行内代码），生成同一套批次。默认只跑规则；classifier: "model" 才会在规则没命中时调用模型判定，且有每小时 30 次的额度。

配置

放在 profile 的插件配置里（字段都有默认值）：

组成

lib/index.js        宿主端：工具、presenter、批次存储、投递、两条 HTTP 路由、提示词
lib/client.js       浏览器端：shell.overlay 里的待答面板、轮询、系统通知
cordis.patch.yml    把插件插进 DSH 组合
docs/               安装、兼容性、验收
tests/              宿主端纯函数的单元测试（node --test）

状态文件在 ~/.dsh/question-bridge/state/<sessionId>.json，一会话一个文件，原子写。没有待答问题时删掉整个目录是安全的。

已知边界

• 系统通知依赖网页的 Notification 权限，必须由用户点"启用系统通知"触发申请；window.focus() 不保证把窗口从托盘里拉出来——这是浏览器/Electron 的限制，不是插件能补的。
• 每会话同一时刻只有一张插件卡片在展示，其余排在待答面板里，避免多张卡互相抢焦点。
• 规则识别、答案映射、投递与持久化有单元测试和假 ctx 的集成测试（npm test，15 项）；classifier: "model" 那条模型判定路径没有在本机真实调用过模型，默认也是关的。验收清单见 docs/acceptance.md。

English

A non-blocking way for DSH agents to ask the human a question. The ask_interactive_question tool returns { status: "pending", batchId } immediately; the answer comes back later as an ordinary user/message whose payload is {"kind":"answer_to_question_bridge", ...}. Pending is never treated as approval: closing the card, a notification, or a timeout never marks a question answered.

Batch state lives in $DSH_HOME/question-bridge/state/<sessionId>.json, written atomically. Delivery goes through agent.steer(), and a batch is only delivered once that user message is actually in the session log.

Install: grab dsh-question-bridge.tgz from Releases, add it to your profile's dependencies and dsh.profile.bundles, run pnpm install, restart DSH. Requires DSH Desktop 0.2.0-rc.2.

许可证

MIT，见 LICENSE。