Pular para o conteúdo principal
J

dsh-visual-option

jinsuperofficial/dsh-visual-option

Renders ask-user-question as a previewable choice dialog: URL, local-path and inline HTML/PHP previews, per-option notes and hints, a quiz mode that only shows right/wrong scores, and six UI locales.

Instalar

dsh plugin --profile web add github:jinsuperofficial/dsh-visual-option

README

DSH Visual Option

DSH Visual Option (可视化选项)

让模型把 ASK-USER-QUESTION 变成看得见的东西

npm version GitHub stars GitHub forks GitHub license GitHub issues npm downloads

一个面向 DeepSeek Harness(下称 DSH)Web GUI 的插件
注册工具 let_user_choose:允许模型传入 HTML 文本 / 网页链接 / 本地路径,向用户提出带预览的选择

安装 · 快速开始 · 工具参数 · 配置 · 安全与限制

v0.2.25 · 自检 44/44 · MIT

汉语 · 汉语(漢語) · English · にほんご · Español · Français


效果对比

▶ 在 YouTube 观看  |  ▶ 在哔哩哔哩观看

visual-option (可视化版本) ask-user-question (普通版本)
Visual Option Preview Normal Text Question

设计灵感

纯文本对话里,模型用 ask_user_question 问「A 还是 B」,用户可能还得追问一遍这是什么意思

let_user_choose 把候选方案原样渲染出来:两个落地页并排 iframe、一份 PHP 模板的源码、一个确认按钮,用户做出选择,可以给任意选项附一句备注,模型拿到的是结构化数据,而不是又一轮对话

整个过程只有三步:

  1. 模型调用 let_user_choose,把问题和候选方案交给插件
  2. 插件在本机起一个临时预览服务,把待选内容推给当前会话的弹窗
  3. 用户点选、写备注、提交,模型拿到 { status, answers[], summary }

特性

五种模式

一个请求可以放多个问题,界面按步骤一次显示一题,底部 ‹ 1 / 2 › 是进度,不同模式可以混在同一个请求里,比如第一题多选、第二题填空

1. 单选 (single)

单选

2. 多选 (multi)

多选

3. 填空 (fill)

填空

4. 确认 (confirm)

确认

5. 测验 (test)

题目状态:
测验题目

提交答案:
测验答案

三种预览

  • url:任意 http(s) 页面,直接 iframe(外部站点使用更严格的 sandbox)
  • path:本地页面 / 静态文件,由 Host 起一个一次性预览服务提供,带路径越界保护
  • html / php:内联 HTML / PHP 源码,按需执行 PHP(可配置)

选项备注

每个选项都可以单独写备注,备注以 answers[].notes = [{ label, note }] 回传

选项备注

提示

选项可以带 hint,界面上是一个小按钮,点开才显示,用户点开过哪些提示会以 answers[].hints 回传,模型因此知道哪些题是靠提示做出来的

提示功能

提问

任意模式、任意一步,用户都可以点「提问」把一句话打回主对话,弹窗随即关闭,工具返回 status: "asked" 与问题正文,模型在对话里回答,需要时再重新发起选择

提问功能

其他与跳过

每个选项题自带一条「其他」输入,用户不想选现成项时可以直接写自己的答案,文字以 answers[].custom 回传,每题也可以跳过,答案里是 skipped: true,必填题同样放行

跳过与其他

原生弹窗

复用 GUI 的主题变量、遮罩、圆角与焦点环,支持 Esc 取消、焦点陷阱、prefers-reduced-motion

多语言支持

内置 6 套文案(简体中文、繁体中文、English、にほんご、Español、Français),支持跟随 GUI 语言自动切换,也可在插件中手动选择

宽度自适应

预览宽度可选 自适应 / 768 / 390,同一份内容可以按桌面或手机宽度检查

提示词引导

插件会往系统提示词里加一段引导:要用户做选择时默认走 let_user_choose 而不是 ask_user_question,只有特殊场景才退回原生提问,并且凡是靠文字讲不清的(布局、配色、报错现场、数据结构、长代码差异)必须给对应选项内联一段 HTML 源码预览,而不是让用户自己想象

转录里的提问行

对话记录里那次调用不再是通用工具卡片,而是和原生提问同一排的一行:左边按模式给图标,右边是 模式:主题

模式图标文案
单选圆圈里的问号提问:<标题>
多选两个勾选框 + 两条横线多选提问:<标题>
确认方框里的对勾确认:<标题>
填空输入框 + 两条内线填空:<标题>
测验两张叠放的卡片测验:<标题>

这一行在提问还挂着的时候可以点,等于把弹窗重新展开

收起与挂起

弹窗右上角的 — 把弹窗收成右下角的小胶囊(图标 + 模式 + 标题),请求仍然挂起,模型拿不到结果就不会继续输出。整颗胶囊都能点开,回到弹窗;胶囊上也有 取消 直接结算

输入栏本身不会被接管:DSH 的 conversation.composer 是会话级 chain 槽,目前只接受内置 UI 的注册,第三方插件注册不进去,所以收起期间仍然可以打字发消息,只是模型卡在那次工具调用上不会继续说话

顶替原生提问(实验)

replaceAskUserQuestion: true 时本插件改用内置名字 ask_user_question 注册工具,这样所有按工具名识别提问的插件(等待气泡、提示音、侧边栏分类、活动文案等)都会照常触发

但它有个前提:内置那一行必须先让位。实测在 0.2.2-rc.3 上,tool-ask-user 这一行写在 agent preset 的 plugins 列表里,profile 的 patch 按 id 打不到它(会报 patch: entry "tool-ask-user" not found),所以常规做法是自定义一份 preset,去掉 tool-ask-user 后再开启这个开关;名字被占时插件会退回 let_user_choose 并在日志里说明

设置页

设置里有两个入口指向同一页:左侧导航的 选择题,以及 设置 → 插件 → 选择题 标签页。里面能当场把每个功能点一遍:

区域内容
发起测试单选 / 多选 / 确认 / 填空 / 测验五个按钮,在你当前打开的会话里真弹一次(没人等结果,答完即收尾)
服务端参数timeoutMs、maxInlineBytes、phpBinary,保存后即时生效,并落到 $DSH_HOME/dsh-visual-option.json,重启后仍然有效
界面偏好默认预览宽度(自适应 / 768 / 390)、是否在对话里显示模式图标,存在浏览器本地

服务端参数只覆盖 patch 里同名配置,patch 仍是基线;删掉那个 json 文件就回到 patch 的值

安装

需要 DSH 0.2.0-rc 及以上,Web profile;0.2.2-rc 起最佳(那里 agents 服务改用 get + session.header.origin 判定主会话)

[!NOTE] 本项目曾用名 dsh-let-user-choose,如果你是从旧版本升级,请注意在 package.json 中将依赖名和 dsh.profile.bundles 里的条目同步修改为 dsh-visual-option,工具名和 API 路径保持不变

Method 1. dsh 插件市场

主界面 -> 插件 -> 添加插件 -> 填入插件链接:

  • GitHub Repo: github:JinSuperOfficial/dsh-visual-option
  • NPM Publish Repo: dsh-visual-option

Method 2. dsh cli

dsh plugin_manager install_bundle link:/path/to/dsh-visual-option

安装后重启;如果装了 hot-reload,等它提示即可

Method 3. 让 AI 装

Help me to install this plugin: dsh-visual-option
GitHub Repo: `github:JinSuperOfficial/dsh-visual-option`
NPM: `dsh-visual-option`
Or you could look up the repo: "https://github.com/JinSuperOfficial/dsh-visual-option"
Thanks.

Method 4. 手动安装

等价于两步:

  1. 在 profile 的 package.json 里加入依赖,并列入 dsh.profile.bundles:

    {
      "dependencies": { "dsh-visual-option": "link:/path/to/dsh-visual-option" },
      "dsh": { "profile": { "bundles": ["dsh-visual-option"] } }
    }
    
  2. 插件自带 cordis.patch.yml,会在加载时插入 visual-option 节点(含默认配置)

快速开始

准备两个简单的 HTML 文件,比如放在会话工作目录的 preview/ 下:

<!-- preview/a.html -->
<!doctype html>
<html>
  <body style="margin:0;background:#f8f2e9;font-family:serif;padding:24px">
    <h1>方案 A</h1>
    <p>暖色编辑风</p>
  </body>
</html>
<!-- preview/b.html -->
<!doctype html>
<html>
  <body style="margin:0;background:#0b1020;color:#fff;font-family:sans-serif;padding:24px">
    <h1>方案 B</h1>
    <p>冷色仪表盘风</p>
  </body>
</html>

最小的一次单选请求:

{
  "title": "选一个落地页方向",
  "detail": "两个方案都在下面,点选一个",
  "timeoutSeconds": 600,
  "questions": [
    {
      "id": "plan",
      "question": "哪个方向更适合继续打磨",
      "mode": "single",
      "required": true,
      "options": [
        {
          "label": "方案 A · 暖色编辑风",
          "description": "大标题 + 暖橙渐变",
          "preview": { "kind": "path", "value": "preview/a.html" }
        },
        {
          "label": "方案 B · 冷色仪表盘风",
          "description": "数据卡片 + 冷蓝渐变",
          "preview": { "kind": "path", "value": "preview/b.html" }
        }
      ]
    }
  ]
}

模型侧拿到的返回值:

{
  "status": "answered",
  "answers": [
    {
      "id": "plan",
      "selected": ["方案 B · 冷色仪表盘风"],
      "notes": [{ "label": "方案 A · 暖色编辑风", "note": "排版更克制,但配色有点重" }]
    }
  ],
  "summary": "plan: 方案 B · 冷色仪表盘风"
}

status 取值:answered / cancelled / timeout / asked,超时返回里会带一句 hint,取消与超时都不带 answers

工具参数

字段类型说明
titlestring弹窗标题,缺省「请选择 / Choose」
detailstring标题下方的一段说明
timeoutSecondsinteger30–3600,缺省用插件配置的 timeoutMs(10 分钟)
questionsarray1–8 个问题,见下
testboolean测验开关,提交后只给对错与得分

question

字段类型说明
idstring答案回传用,唯一
questionstring问题正文
headerstring小标题(可选)
detailstring补充说明(可选)
modeenumsingle / multi / fill / confirm
requiredboolean必填;未填时底部提示、不允许提交
placeholderstring仅 fill 用
optionsarray选项;fill 必须为空或不传

option

字段类型说明
labelstring选项名(备注也以它为键)
descriptionstring选项描述(可选)
previewobject{ kind: "url" | "path" | "html" | "php", value, title? }
correctboolean测验模式下标记正确答案
hintstring可选提示,点「提示」才展开

answers

字段类型说明
idstring对应的问题 id
selectedstring[]选中的选项 label
customstring填空答案,或「其他」里手写的文字
hintsstring[]用户点开过提示的选项 label
skippedboolean整题跳过
notesarray[{ label, note }] 选项备注

[!IMPORTANT] 限制:问题 ≤ 8、选项 ≤ 12、label ≤ 200 字、备注 ≤ 1000 字、填空 ≤ 4000 字,未知字段会被拒绝;fill 的问题不接受选项备注

关于模式的一点约定

  • confirm 只有一个问题时,点选即提交
  • 有多个问题时,confirm 只是一行两选一,仍需点提交
  • 测验模式下每题至少需要一个 correct: true,提交后返回 score: { correct, total }
  • 所有模式的答案都在 answers[] 里按 id 对应

预览细节

kind渲染方式说明
urliframe仅 http(s);外部域名使用不含 allow-same-origin 的 sandbox
pathiframe相对路径按会话 cwd 解析,必须落在 root 内;可指向单文件或目录
htmliframe内联 HTML 源码,直接在弹窗里渲染
phpiframe / 源码配置了 phpBinary 时执行并渲染输出,否则显示源码

PHP 行为

  • phpBinary: ""(默认)——只显示源码,标签为「源码预览(PHP 未执行)」
  • phpBinary: "auto"——探测 PATH 上的 php,找到就执行
  • 其他值——当作可执行文件路径
  • 执行有 8 秒超时、2 MiB 输出上限,错误不回显到页面

预览服务

  • 每个请求起一个独立的 http.createServer,绑定 127.0.0.1:0(随机端口)
  • 内联文档挂在 /<token>.html,静态文件挂在 /,token 随机
  • 回答 / 取消 / 超时后延迟关闭,端口回收

等待与取消

  • 弹窗打开后开始倒计时(剩余 m:ss)
  • 用户第一次移动鼠标、按下、滚轮或键盘输入 → 客户端立即本地隐藏倒计时,并 POST /api/let-user-choose/hold;Host 把计时器换成 1 小时安全兜底
  • Esc、右上角 ×、底部「取消」都会以 cancelled 结束
  • 「提问」以 asked 结束,把问题交回主对话
  • 浏览器标签切到后台时轮询暂停,回到前台立即拉一次
  • 超时以 timeout 结束

配置

写在插件节点(cordis.patch.yml 的 insert 或 profile 的 patch 层):

- id: visual-option
  name: dsh-visual-option
  config:
    timeoutMs: 600000     # 默认等待上限(毫秒),夹在 5s–1h
    maxInlineBytes: 65536 # 单个内联 html/php 内容上限
    phpBinary: ""         # "" | "auto" | 可执行文件路径
    replaceAskUserQuestion: false # true 时改用内置工具名 ask_user_question(需同时禁用内置那一行)

replaceAskUserQuestion 只影响注册的工具名,不改 schema、协议与界面;系统提示词引导默认就开着,不受这个开关影响

HTTP 接口(内部)

客户端弹窗与 Host 之间只走 GUI 自带的 /api 通道:

路径方法作用
/api/let-user-choose/pending?session=GET当前会话是否有待处理的选择
/api/let-user-choose/answerPOST提交答案 / 取消 / 提问
/api/let-user-choose/holdPOST用户已交互,取消限时
/api/let-user-choose/sourceGET源码预览内容
/api/let-user-choose/settingsGET / POST设置页读写服务端参数(POST 需 confirm: true)
/api/let-user-choose/selftestPOST设置页「发起测试」:在该会话造一次真实请求

安全与限制

  • 预览服务只监听回环地址:从别的机器打开 GUI 时,本地预览无法加载(弹窗会提示),外部 url 预览仍然可用
  • 路径预览做 realpath 校验,拒绝 ..、绝对路径逃逸与符号链接逃逸
  • 内联内容有大小上限;超限直接拒绝
  • 参考页面不会上传,预览只在你的机器上打开
  • 仅在当前正在查看的会话里弹窗;后台会话里的调用会一直等到超时

[!WARNING] PHP 执行默认关闭,开启(如 phpBinary: "auto")即意味着允许模型提供的代码在本机运行,存在远程代码执行(RCE)风险,请自行评估并在受控环境下使用

开发

node selfcheck.mjs # 自检

自检覆盖:

args    → 选项/备注/超时边界、未知字段拒绝
preview → MIME、404、目录、越界、符号链接、内联 HTML、PHP 源码与执行
hub     → pending / answer / hold / ask / cancel / timeout / abort / dispose
notes   → 往返、空备注丢弃、fill 拒绝备注
other   → 未选选项时用 custom 作答、必填校验、往返
skip    → 跳过必填题、与选项冲突时拒绝
hint    → 选项提示回传、未知 label 拒绝
test    → 参考答案标记、得分回传

验收视频的工程在 demo/(Electron 离屏渲染 + 真实 client.js + 录帧合成):

cd demo
npm install
python3 -m http.server 4610 --bind 127.0.0.1 &
~/.dsh/electron/electron app      # 录制到 demo/out/frames/
node encode.mjs                   # 合成 demo/out/acceptance.mp4

项目结构

dsh-visual-option/
├── index.js            # Host 插件:注册工具、/api 路由、配置
├── client.js           # 浏览器弹窗:步骤、预览、备注、提示、提问、测验
├── lib/
│   ├── args.mjs        # 参数校验与归一化
│   ├── preview.mjs     # 预览服务(iframe / 源码 / PHP)
│   └── hub.mjs         # 待处理请求、计时器、hold、答案校验
├── cordis.patch.yml    # 插件自带的挂载声明与默认配置
├── selfcheck.mjs       # 自检
├── test/fixtures/      # 预览夹具
├── demo/               # 验收视频工程
├── logo.svg
├── icon.svg
└── assets/             # README 中的截图存放目录

Roadmap

  • 发布到 npm / dsh 插件市场
  • 图片(png/jpg)与 PDF 预览
  • 远程访问时的预览隧道(当前仅限本机)
  • 更细粒度的 PHP 沙箱(超时、禁用函数、只读)
  • 更多语言

License

MIT © JinSuperOfficial

© 金旭 2026 · JinSuper™

Plugins relacionados