dsh-qqbot-ui

DSH（DeepSeek Harness）的 QQ 机器人插件，自带 Web 可视化配置页。

本包 = 腾讯官方 @tencent-connect/dsh-qqbot 0.5.0 的重新打包 ＋ 一处 UI 适配补丁 ＋ 一个新增的设置页 client 半。

一条命令安装

dsh plugin --profile web add dsh-qqbot-ui

装完重启 DSH Web。插件本体在 im-qqbot 条目下运行， 「设置」侧栏会多出一个 QQ 机器人 页面（位于「内置插件」与「Agent 预设」之间）。

⚠️ 要求 DSH ≥ 0.2.0（实测 0.2.0-rc.2 可用）。 本包的 volatile 补丁用了 schemastery 的 .volatile()，那是 DSH 0.2.0 才引入的 API； 在更旧的 DSH 上启动会报 Schema.string(...).default(...).description(...).volatile is not a function。 只用上游原版（不加本包补丁）则无此限制。

它解决什么问题

上游 @tencent-connect/dsh-qqbot 不自带 client 半、也不声明 dsh.client， 所以「设置」里没有任何入口 —— 改配置只能手改 cordis.patch.yml。

而且 DSH 只为「含 volatile 字段」的插件条目生成 GUI 表单： SettingsForms.describe() 对每个 active 条目调 volatileForm(schema)， 返回 undefined 就直接跳过该命名空间。上游的 ConfigSchema 一个 volatile 都没有， 所以即使加了设置页，表单也是空的。

本包做三件事：

1. 宿主侧补丁 —— 把 dist/config.js 的 ConfigSchema 每个叶子字段标 .volatile()， dist/index.js 入口加 plainConfig() 递归解包，让 volatile 生效且配置热更新可用。
2. 新增设置页 —— lib/client.js 向 settings.section 注册一个入口， 渲染 im-qqbot 命名空间的完整表单。
3. 扫码授权搬进设置页（0.6.0）—— 见下节。

🔴 0.6.0 修复：插件装上后是灰的、点不开

症状：装完插件，插件列表里 im-qqbot 那一行显示为灰色、开关点不动。

根因：上游在 apply() 里写了

if (!appId || !appSecret) {
    const credentials = await runQrSetup();   // ← 终端扫码，会阻塞
    ...
}

runQrSetup() 是终端扫码：在控制台打印二维码、然后 await 等待用户扫。 在无头容器 / Web 部署里，既没人看得见控制台二维码，这个 Promise 也永不 resolve ⇒ apply() 一直挂着 ⇒ 插件行停在「启动中」⇒ 前端渲染成灰色不可用。

修法（本包 0.6.0）：

| 位置 | 改动 | |---|---| | dist/index.js | 凭据缺失时立即 return（插件正常激活，只是网关不启动），不再 await runQrSetup() | | dist/qr-routes.js | 新增：向 webServer 注册 /qqbot-ui/qr/{status,start,cancel} 三个路由 | | dist/setup.js | 新增 startQrSession() 后台会话与 renderQrSvg()（复用 qrcode-terminal 的矩阵出 SVG，不打印到控制台） | | lib/client.js | 设置页顶部新增「扫码绑定」卡片：显示二维码、2 秒轮询绑定结果 |

扫码流程：设置页点「获取二维码」→ 手机 QQ 扫码 → 宿主把凭据写进 profile 的 cordis.patch.yml → DSH 热更新自动重启插件 → 网关带凭据启动。

也可以完全跳过扫码，直接在「连接凭据」里手工填 AppID / AppSecret —— 两条路都通，互不依赖。

本包相对上游 0.5.0 的改动

| 文件 | 改动 | |---|---| | dist/config.js | 34 处 .volatile()（每个叶子字段）；appSecret 加 .role('secret')；补全字段描述文案 | | dist/index.js | 新增 plainConfig() 递归解包 volatile 引用；监听 loader/volatile-update，300ms 防抖后 ctx.fiber.restart() 让改动生效；凭据缺失不再阻塞启动（0.6.0） | | dist/qr-routes.js | 新增（0.6.0）：扫码绑定的三个 HTTP 路由 | | dist/setup.js | 新增 startQrSession() / renderQrSvg()；写 profile 时保留原文件头注释（0.6.0） | | lib/client.js | 新增：设置页浏览器半（上游没有） | | cordis.patch.yml | 条目名改为 dsh-qqbot-ui | | package.json | 改名、加 dsh.client 声明与 ./client 导出、去 devDependencies；加 qrcode-terminal 直接依赖（0.6.0） |

除上述之外，dist/ 与上游 0.5.0 编译产物逐字节一致。

为什么标 volatile 就能出表单

.volatile() 把解析值包成 { get(), [Symbol.for('cosmokit.volatile.write')] } 引用对象， 宿主 apply(ctx, config) 拿到的不再是裸值 —— 所以入口必须用 plainConfig() 递归解包， 否则下游拿引用参与 ===、||、.startsWith() 会得到错误结果。

volatile-only 的配置改动不会重跑 apply()（Loader.update() 走 volatileOnly 分支， 只原地 _commitVolatile()），而本插件在 apply() 时就把配置捕获进了各处闭包 （gateway、middleware、session manager）—— 因此补丁里主动监听 loader/volatile-update 并重启一次，否则闭包里的旧值会变陈旧。

⚠️ 不要同时标记父对象和它的子字段：validateVolatileSchema 会抛 volatile fields require a fixed object path without an enclosing volatile field。

设置页能配什么

8 个分组共 34 个字段，控件覆盖 string / number / boolean / enum（分段控件）/ string[]（逗号分隔）/ secret：

• 连接凭据 —— AppID、AppSecret（secret 字段，值永不下发到浏览器）
• 模型路由 —— provider、model、preset、工作目录（带目录选择器）
• 会话行为 —— 空闲超时、处理超时、待答超时、并发队列、历史条数
• 消息 —— 单条最大字符数、流式输出、是否展示工具调用结果
• 触发方式 —— 群聊是否需要 @bot、群聊/私聊额外 system prompt
• 访问控制 —— C2C 与群聊各自的模式（open / allowlist / disabled）与白名单
• 富媒体 —— 图片/视频理解开关、下载上限、视觉模型与提示词
• 调试 —— debug 日志

改动即时生效（补丁里的防抖重启），无需手改 yml。

环境变量

cordis.patch.yml 里 appId / appSecret 写的是 __FROM_ENV__ 占位， 可经环境变量注入：

QQBOT_APPID
QQBOT_SECRET

也可以直接在设置页里填（推荐，省得改环境变量）。

用法

在 QQ 里私聊或群里 @ 机器人即可对话。内置命令见上游 README（README_UPSTREAM.md）：

• /model —— 切换模型
• /preset —— 切换 Agent 预设
• /session —— 会话管理
• /status —— 运行状态
• /help —— 帮助

依赖

运行时依赖 @tencent-connect/qqbot-connector 与 @tencent-connect/qqbot-nodejs （腾讯官方包，自动随本包安装）。

peer 依赖为 DSH 自带的 @deepseek-ai/* 系列，由宿主提供，无需单独安装。

与上游的关系 / 升级

⚠️ 本包是重新打包，不是 fork 的持续跟踪：

• 包名不同 ⇒ npm 不认为它和上游有关系，上游发新版不会自动跟进。
• 想用上游新版，需要重新打一遍上面那两处改动（见「本包相对上游的改动」表格）。
• 上游是 MIT，本包同为 MIT。dist/ 与 README_UPSTREAM.md 的版权归腾讯。

License

MIT。上游代码（dist/、README_UPSTREAM*.md、docs/、CHANGELOG*.md） 版权归腾讯，依 MIT 许可再分发。