把 QQPilot 的 QQ 消息接入 DeepSeek Harness(DSH)的桥接插件: 对 QQPilot 暴露一个 OpenAI Chat Completion 兼容端点,由 DSH 里配置的模型通过智能体工具决定 「回复什么 / 不回复 / 附带图片」;提供 工具 / 兼容 / 静默 三种运行模式,并在设置页内置 可视化聊天动态(实时看到收到的 QQ 消息、AI 的决定、回复内容、耗时与 token)。
QQPilot 原本只会把聊天记录 POST 给一个 OpenAI 兼容的 /chat/completions 并取回文本。
本插件接管这个端点后,把请求转成一次 DSH 模型调用,再把模型的决定收敛回 OpenAI 响应:
这是QQPilot官方认定的正确插件编写方式。
QQPilot ──POST /qqpilot/v1/chat/completions──▶ 本插件(DSH Host)
│
┌──────────────┴───────────────┐
│ 工具模式(默认) │ 兼容模式 / 静默模式
│ 给模型 2 个工具: │ 兼容:不给工具,直接返回文本
│ qqpilot_reply(text, images) │ 静默:不调用模型,只记录消息
│ qqpilot_do_not_reply │
└──────────────┬───────────────┘
▼
DSH llm.stream(使用 DSH 当前默认模型)
│
◀── choices[0].message.content(字符串)+ 可选 message.images[] ──┘
- OpenAI 兼容端点:
POST /qqpilot/v1/chat/completions(非流式),另提供GET /qqpilot/v1/models。 - 三种运行模式(设置页可切换)
- 工具模式(默认,agent):模型通过
qqpilot_reply/qqpilot_do_not_reply决定是否回复、回什么。 - 兼容模式(compat):不给工具,直接把模型输出作为回复返回,适合不支持 tool calling 的模型。
- 静默模式(silent):不调用模型、不消耗 token,只把收到的消息记录到聊天动态里(观察/挂机用)。
- 工具模式(默认,agent):模型通过
- 智能体工具(工具模式)
qqpilot_reply:模型决定回复时调用;参数text(正文,字符串或字符串数组)与images(图片路径 / http(s) URL / data URL)。- 一次回复多条消息:
text传字符串数组时,数组每一项会作为一条独立的 QQ 消息,插件用[[NEXT]]拼接后返回给 QQPilot(QQPilot 会逐条发送);字符串里的[[NEXT]]也会被展开成多条。 qqpilot_do_not_reply:模型决定保持沉默时调用,插件返回空content,QQPilot 跳过发送。- 模型没有调用工具而是直接输出文本时,文本仍然会作为回复返回(不会因模型“忘记调工具”而丢消息)。
- 多轮工具循环上限可配置;工具调用失败时可自动回退到兼容输出。
- 可视化聊天状态(两种入口,均已内置)
- DSH 聊天窗口内:聊天输入框上方常驻一条可折叠的「QQPilot」状态条,显示当前模式、最新一条 QQ 消息与 AI 决策;展开后可看最近 6 条收/发记录(含 DSH 工具调用),每 2 秒自动刷新。
- 设置页 → 聊天动态:完整记录视图,支持暂停刷新、查看耗时/token/工具调用与错误。
- 可调用 DSH 工具:工具模式下可把 DSH 的工具(默认只读 + 联网:
read/glob/grep/read_image/web_search/web_fetch)一并提供给桥接后的 AI;AI 可先查资料/读文件,再用qqpilot_reply回复。可在设置页选择「关闭 / 安全 / 全部」策略,危险工具(pwsh/bash/write/edit/subagent/workflow/plugin_manager)默认拒绝。 - QQPilot Windows 辅助程序(DLC,默认关闭):可启用两个由工作空间内程序提供的工具 ——
qqpilot_get_chat_name(调用get_chat_name.exe用 Windows OCR 读取当前群名)和qqpilot_upload_files(调用UploadFiles.exe上传并立即发送文件)。启用前需确认工作空间指向 QQPilot 程序目录(含 exe/config.ini/file.png),设置页会先弹出确认提醒;两者都要求 AI 在最终回复/沉默前调用。 - 多用户上下文(QQPilot 的一次请求可能包含多个用户/多条消息):默认「完整上下文」会把请求里的所有用户消息交给模型, 并在系统提示里列出本次参与用户与尚未回复的消息(可一次回复多条并 @ 对方);聊天动态会显示「用户 N 位 / 输入 N 条」。 可在设置里切到「旧版单条」只把最后一条用户消息交给模型。
- 模型选择:默认跟随 DSH 全局默认模型;设置页「模型」卡片可改为仅 QQPilot 指定的 provider/model(下拉框,保存后下一轮生效),也可在
cordis.patch.yml固定。 - 工具与工作区设置:设置页可直接修改「工具轮数上限」(1-32)和桥接 AI 的「工作空间」目录;工作空间用于 DSH 工具(read/写文件等)、相对路径与本地图片路径。
- 返回图片:回复图片会被规范化成
data:image/...;base64,...放进choices[0].message.images[].image_url.url(QQPilot 唯一稳妥的图片返回形式);仅有图片没有文本时会自动 补一个短 caption,避免 QQPilot 把整条回复当作空内容跳过。 - 接收图片:QQPilot 的 vision 请求(
content分段数组中的image_url)会通过 DSHattachments服务转成模型可读的图片块;没有附件服务时退化为文字占位,不会让请求失败。 - 设置页:DSH 设置 →「QQPilot 接入」,含「概览 / 聊天动态 / 设置」三个页签:端点地址、运行模式、 附加指令、请求统计、测试连接与实时聊天状态。
- 运行时状态:设置页的修改持久化在
~/.dsh/qqpilot-dsh-plugin.json(mode、compatibilityMode、extraInstructions),重启 DSH 后仍生效。
本仓库就是一个 DSH bundle 包(package.json 里 dsh.bundle.patch 指向 cordis.patch.yml),无需构建步骤。
方式二:在 DSH 当前 profile 里安装本目录(推荐,开发时本地链接):
plugin_manager → install_bundle → target = <本目录绝对路径>
或命令行:
dsh plugin --profile <profile> add C:\path\to\qqpilot-dsh-plugin
dsh --profile <profile>方式二:已安装后直接启用/停用 bundle(插件会热加载,无需改代码):
plugin_manager → set_bundle / set_plugin
安装成功后宿主日志会出现:
[qqpilot] QQPilot 接入已就绪 endpoint=http://127.0.0.1:<端口>/qqpilot/v1 模型=<provider>/<model> 兼容模式=false
编辑 QQPilot 的 config.ini([general] 段):
# 指向本插件暴露的地址;末尾不要带 /,QQPilot 会直接拼 "/chat/completions"
server_url = http://127.0.0.1:55068/qqpilot/v1
# QQPilot 对 127.0.0.1 / localhost 不会发送 Authorization,这里留空即可
api_key =
# 本插件使用 DSH 当前默认模型;QQPilot 里的 modelname 不会被用于路由
modelname = deepseek-flash
# 需要把 QQ 里的图片也交给模型时开启(插件会把 image_url 转成 DSH 图片块)
isvisionmodel = true
remote_server_timeout = 300端口以 DSH Web 实际监听为准(设置页里会显示完整端点)。如果 DSH 换了端口,QQPilot 的
server_url也要同步改。 QQPilot 的 Ollama / builtin 后端不会走本插件,请保持forceollamaapi = false。
| 工具模式(默认,agent) | 兼容模式(compat) | 静默模式(silent) | |
|---|---|---|---|
| 是否调用模型 | 是 | 是 | 否(不消耗 token) |
| 模型收到的工具 | qqpilot_reply / qqpilot_do_not_reply |
无 | 无 |
| 决定回复 | 模型调用 qqpilot_reply |
模型直接输出文本 | 永不回复 |
| 决定沉默 | 模型调用 qqpilot_do_not_reply(返回空 content) |
模型输出空文本 | 总是返回空 content |
| 图片 | qqpilot_reply.images 支持本地路径 / URL / data URL |
不支持(只返回文本) | 不支持 |
| 聊天动态 | 记录完整决策 | 记录完整决策 | 只记录收到的消息(观察用) |
| 适合 | 支持 tool calling 的模型;希望“该不该插话”由模型自己判断 | 不支持工具的模型;或希望完全沿用 QQPilot system.txt 的直接输出 | 挂机观察 / 临时静音,不花钱 |
在 DSH 设置 → QQPilot 接入 → 概览(或设置) 里切换运行模式,立即生效并持久化; 也可以在该页「聊天动态」页签实时查看收到的消息与 AI 的回复/沉默/错误。
- 插件设置页 →「模型」卡片(推荐):默认「跟随 DSH 默认模型」;关掉开关后可从下拉框选择
provider 与 model(例如
deepseek-official/deepseek-flash、llamacpp/MiniCPM5-1B-F16.gguf、xiaomi/mimo-v2.6-flash),点「保存模型」后下一轮请求生效,持久化到~/.dsh/qqpilot-dsh-plugin.json。 - DSH 全局默认模型:未指定时插件实时读取 DSH 当前的默认模型,随 DSH 底部模型选择器 / Settings → Models 变化。
cordis.patch.yml的provider/model:给默认值用;设置页的显式指定会覆盖它。
模型列表通过 DSH
llm服务的listProviders()/listModels()实时读取;某个 provider 读取失败会在设置页提示。 不同模型能力差异较大:工具调用建议使用支持 tool calling 的模型(如 DeepSeek 系列);本地小模型(1B 级)在 多工具场景下可能很慢甚至超时,可把 DSH 工具策略设为「关闭」或改用更大模型。 「一次多条消息」依赖模型愿意按数组输出;DeepSeek 系列实测可稳定遵循,小模型可能只回单条(仍可正常发送)。 若使用本地小模型(如 MiniCPM5-1B)并希望多条消息,建议切到兼容模式,在system.txt/ 附加指令里要求 用[[NEXT]]或换行分隔——QQPilot 会把它们逐条发送。
QQPilot 不是标准的一问一答 Chat Completion 客户端:它每次把当前聊天窗口的记录整体发过来,所以一个请求的
messages 里可能包含多个用户(群聊)或同一用户的多条消息,格式为:
[time] <时间>
[username] <用户名>
[content] <内容>
本插件处理方式:
- 窗口语义:QQPilot 抓取的是 QQ 聊天窗口本身,所以每个请求是滑动窗口快照——新消息追加到末尾, 旧消息会随着窗口滚动被挤出;同一批历史消息可能出现在多次请求里。插件不保存跨请求的对话状态 (避免不同群/私聊串线),每次都按当前窗口重建上下文。
- 待回复识别:以窗口里最后一条 assistant 回复为界,其后的用户消息视为“尚未回复(pending)”, 更早的用户消息只作为历史上下文;窗口整体滑动导致旧 assistant 消失时,这条规则仍然成立 (被保留的用户消息后面一定有对应的 assistant 回复)。
- 完整上下文(
contextMode: all,默认)- 请求里的所有 user/assistant 消息都会传给模型(受
historyLimit限制,默认 40 条); - 系统提示会追加一段“本次请求是 QQ 聊天窗口快照(滑动窗口)…其中 M 条尚未回复”的说明, 并只把 pending 消息单独列出;已经处理过的消息明确标为历史上下文,避免模型把旧消息误当新消息;
- 聊天动态/状态条会显示本次请求的窗口用户数、窗口消息数与待回复条数;聊天动态里多条输入会逐条列出 「用户名:内容」,并用「新 / 历史」标签区分。
- 请求里的所有 user/assistant 消息都会传给模型(受
- 旧版单条(
contextMode: latest)- 只把最后一条 user 消息 + system prompt 交给模型,忽略同一请求里更早的用户/历史消息;
- 适合省 token 或想完全复刻旧版行为的场景。
在 设置 → QQPilot 接入 → 设置 → 工具与工作区 → 上下文模式 切换,或 POST /qqpilot/api/config {"contextMode":"all"|"latest"}。
Windows 版 QQPilot 的 data 目录里带有两个「DLC」程序;本插件可以把它们包装成 AI 工具(仅工具模式可用,
默认关闭):
| 工具 | 实际程序 | 作用 | 风险 |
|---|---|---|---|
qqpilot_get_chat_name |
get_chat_name.exe |
截图 + Windows OCR 读取当前 QQ 聊天窗口顶部群名/联系人名,帮 AI 确认在哪个会话 | 会截屏、需要 QQ 窗口在前台 |
qqpilot_upload_files |
UploadFiles.exe |
把工作空间内文件上传到当前 QQ 聊天 | 会立即发送文件(可能早于文字回复),会模拟点击 QQ 窗口 |
启用要求:
- 工作空间必须指向 QQPilot 程序目录,例如
C:\Users\Develop\QQPilots\QQPilot\releaseBuild\1.5.20 x64 - Copy\data,目录里要有get_chat_name.exe/UploadFiles.exe/config.ini/file.png; - QQ 已登录,并停留在目标聊天窗口(两个程序都依赖窗口坐标和截图);
- 在 设置 → 工具与工作区 → 工作空间 里设置上述目录;
- 在 设置 → QQPilot 辅助程序(DLC) 里打开开关;启用前会二次确认,宿主也会再次校验程序是否存在, 缺程序会拒绝启用并提示路径。
调用约定:
- AI 必须在
qqpilot_reply/qqpilot_do_not_reply之前调用这些辅助工具;调用结果会作为工具结果回给模型, 模型再决定最终回复或沉默; qqpilot_get_chat_name优先用zh-Hans-CNOCR,语言包不可用时回退到系统默认语言;qqpilot_upload_files只接受位于工作空间或imageRoots内的文件,单次最多 8 个;- 两个工具都有超时(默认 90s),失败会把原因作为工具错误返回给模型,不会中断整轮。
在 DSH 设置 → QQPilot 接入 → 设置 →「工具与工作区」:
- 工具轮数上限(1-32):模型一次回复里最多进行几轮工具调用。默认 4;调大可以让 AI 多查几轮资料, 但更慢、更费 token。保存后下一轮请求生效。
- 工作空间路径:桥接 AI 使用的目录(
workspaceRoot)。- 留空 = 跟随 DSH 当前工作区;
- 填绝对路径(相对路径按 DSH 进程目录解析),保存时会校验/自动创建目录;
- 也可点「选择目录…」直接调起系统目录选择器(DSH Client
uiWorkspace.pickDirectory),选完点「保存工作空间」生效; - 生效范围:
qqpilot-bridgeAgent 的工作目录(read/write/glob 等相对路径)、本地图片路径的允许根目录; - 保存后立即应用到已存在的 bridge Agent(
workingDirectory.set),无需重启。
cordis.patch.yml 中 config: 支持以下字段(设置页暴露运行模式与附加指令):
| 字段 | 默认 | 说明 |
|---|---|---|
mode |
agent |
运行模式:agent(工具)/ compat(兼容)/ silent(静默) |
compatibilityMode |
false |
旧版兼容字段;true 等价于 mode: compat(仍可用,会被 mode 覆盖) |
provider / model |
空 | 空 = 跟随 DSH 默认模型;也可在这里给默认值(设置页「模型」卡片可覆盖) |
reasoningEffort |
空 | 推理强度,空 = 跟随服务商默认 |
extraInstructions |
空 | 追加到系统指令里的额外要求(三种模式都生效) |
maxToolRounds |
4 |
工具循环最大轮数(1-32,设置页「工具与工作区」可改) |
workspaceRoot |
空 | 桥接 AI 的工作空间目录;空 = 跟随 DSH 当前工作区;设置页可改,目录不存在会自动创建 |
contextMode |
all |
all = 完整上下文(参考请求里所有用户/消息);latest = 旧版单条(只把最后一条用户消息交给模型) |
enableGetChatName |
false |
启用 qqpilot_get_chat_name(OCR 群名,需工作空间含 get_chat_name.exe) |
enableUploadFiles |
false |
启用 qqpilot_upload_files(上传文件,需工作空间含 UploadFiles.exe) |
dshTools |
safe |
是否向桥接后的 AI 提供 DSH 工具:off / safe(只读+联网)/ all(除危险工具外全部) |
dshToolDeny |
["pwsh","bash","write","edit","subagent","workflow","plugin_manager"] |
始终拒绝的 DSH 工具名 |
maxDshToolCalls |
6 |
单次请求内最多执行多少次 DSH 工具 |
historyLimit |
40 |
最多转发的历史消息条数 |
requestTimeoutMs |
180000 |
单次请求的模型调用超时(毫秒) |
fallbackToCompat |
true |
工具模式调用报错时是否回退为兼容输出 |
temperature |
0 |
>0 时发送;0 表示不发送该参数 |
maxTokens |
0 |
>0 时发送;0 表示使用服务商默认 |
maxInboundImages |
8 |
单次请求最多读取几张入站图片 |
maxReplyImages |
4 |
单次回复最多附带几张图片 |
maxReplyChars |
500 |
回复长度上限(Unicode 字符),按 [[NEXT]] / 换行边界优雅截断;0 = 不截断(QQPilot 自身仍会硬截断到 500) |
maxImageBytes |
8388608 |
单张图片大小上限(8 MiB) |
imageRoots |
[] |
允许读取本地图片的根目录;默认允许 DSH 工作区 / cwd |
imageOnlyCaption |
🖼️ |
只有图片没有文本时的占位 caption |
logRequests |
false |
是否打印每次请求的摘要到宿主日志 |
| 方法 & 路径 | 用途 |
|---|---|
POST /qqpilot/v1/chat/completions |
QQPilot 使用的 OpenAI 兼容端点 |
GET /qqpilot/v1/models |
模型目录(返回 DSH 当前模型) |
GET /qqpilot/api/config |
设置页读取配置 / 端点 / 统计 / 运行时长 / 可用 DSH 工具列表 |
POST /qqpilot/api/config |
设置页写入 {mode?, compatibilityMode?, extraInstructions?, dshTools?, provider?, model?, maxToolRounds?, workspaceRoot?, contextMode?, enableGetChatName?, enableUploadFiles?} |
GET /qqpilot/api/activity?since=&limit= |
设置页「聊天动态」轮询:最近的消息 + AI 决策 |
POST /qqpilot/api/test |
设置页“测试连接”:走一遍完整回复流程 |
GET /qqpilot/api/status |
统计信息 |
GET /qqpilot/api/tools |
DSH 工具桥诊断:策略、可见工具、专用 bridge agent、全局/作用域工具 |
POST /qqpilot/api/tools/test |
通过真实工具管线执行一次 read(读插件自身 package.json),验证 DSH 工具调用链路 |
GET /qqpilot/api/models |
模型目录:DSH provider/model 列表、当前默认选择、生效模型 |
POST /qqpilot/api/client-error |
浏览器端渲染/未捕获错误上报(写入宿主日志) |
GET /qqpilot/api/client-errors |
最近 20 条浏览器端错误(排查设置页空白用) |
choices[0].message.content必须是字符串;空字符串表示这次不回复(QQPilot 会静默跳过)。- 多条消息:
qqpilot_reply.text可以是字符串数组,插件会按顺序用[[NEXT]]拼接;QQPilot 对[[NEXT]]分段后每段单独按一次Ctrl+Enter发送,所以数组里每一项就是一条 QQ 消息(gui_operation.rs的send_text)。 - QQPilot 还会把回复里的
\n逐行发送(段内换行也会变成多条消息),因此单条消息内部不要用换行; 想发多条消息请用数组或[[NEXT]],不要依赖换行。 - 回复文本会被 QQPilot 硬截断到 500 字符(按 Unicode 字符计),图片会在文本之后上传。
- 图片放在非标准扩展字段
choices[0].message.images[],值必须是data:image/<ext>;base64,...data URL; 文本为空时 QQPilot 不会上传图片,因此插件会在“只有图片”时补 caption。 - 更精确的协议依据(源码行号、字段硬性要求、失败时的静默行为)见 PROTOCOL.md。
# 离线:用假 ctx / 假 llm 直接跑路由与工具循环(无需安装)
node test/host-unit.mjs
# 离线:用假 React 渲染设置页三个页签,捕获 props/变量拼写错误
node test/client-render.mjs
# 一键运行全部离线测试
pnpm test
# 在线:模拟 QQPilot 发真实请求并严格校验响应形状
node test/mock-qqpilot.mjs --url http://127.0.0.1:55068/qqpilot/v1
# 在线:多场景验收(回复 / 文本路径 / 模式探测 / 图片)
node test/verify.mjs --url http://127.0.0.1:55068/qqpilot/v1| 现象 | 可能原因 |
|---|---|
| 设置页显示“加载失败” | 插件未加载 / 路由未注册;看宿主日志有无 [qqpilot] 报错 |
| 设置页空白 / 页签消失 | 插件热更新后旧组件实例与新版 hooks 不一致(或渲染异常)。**刷新 DSH 页面(F5 / Ctrl+R)**即可重新挂载;新版已加错误边界,异常时会显示提示而不空白。若仍异常,打开 http://127.0.0.1:<端口>/qqpilot/api/client-errors 查看上报的客户端错误 |
| QQPilot 端“机器人不理人” | server_url 写错(多了 /、端口不对);模型调用报错被记为 500;看宿主日志 [qqpilot] 请求处理失败 |
| 模型总是沉默 | 工具模式提示词让模型判断“不必插话”;可换成兼容性模式,或在 extraInstructions 里要求更积极回复 |
| 图片没发出去 | 图片路径不在 imageRoots / 工作区内;图片超过 maxImageBytes;模型只给了文本 |
| 模型调用报 401 / 无可用模型 | DSH 里没有可用的默认模型或凭据;先在 DSH 设置里选好模型 |
- 端点注册在 DSH 的
webServer上,默认仅本机可访问;QQPilot 走回环地址,不需要 API key。 如需从其它机器接入,请在网络层限制访问,并自行评估server_url使用非回环地址时 QQPilot 会发送Authorization: Bearer <api_key>的行为。 - 目标环境:DSH
0.2.1/0.2.2系列(使用公开服务webServer/llm/attachments/agentDefaultModel/agents/tools/workingDirectory;工具执行同时兼容 0.2.1 的单调用 API 与 0.2.2 的批量 executor API), Node.js>=22.13.0。无第三方运行时依赖。 - 插件卸载/热重载时自动注销所有路由与资源(
ctx.effect管理)。
已通过 plugin_manager install_bundle 安装进 desktop profile 并热加载(application: applied):
| 检查 | 结果 |
|---|---|
GET /qqpilot/api/config |
200,endpoint=http://127.0.0.1:55068/qqpilot/v1,模型 deepseek-official/deepseek-flash |
POST /qqpilot/api/test(工具模式) |
{"ok":true,"mode":"tool","reply":{"text":"连接正常,测试通过。"}},约 1s |
| 兼容性模式切换 + 持久化 | POST 开关生效;~/.dsh/qqpilot-dsh-plugin.json 写入 {"compatibilityMode":true},切回 false 正常 |
test/mock-qqpilot.mjs |
PASS:HTTP 200,content="等于2",响应形状符合 QQPilot 契约 |
test/verify.mjs |
PASS:硬场景 2/2;基础回复 / 文本路径 / 模式探测 / 图片返回全部通过 |
| 返回图片 | 模型调用 qqpilot_reply(images=[data:image/png;...]) 后响应带 1 张 message.images[] data URL(是否发图由模型决定:另一次运行模型选择只发文字,属模型行为,不算协议失败) |
| 接收图片 | 入站 image_url data URL 经 attachments 转成图片块,模型正确回答了图片内容 |
| 静默 | 模型调用 qqpilot_do_not_reply 时返回空 content(统计 silences≥1) |
| 设置页 | Web Client settings.section 已出现 qqpilot(order 62,label「QQPilot 接入」),active=true |
| 离线单测 | node test/host-unit.mjs 全部 PASS(路由、系统消息合并、工具循环、图片、三种模式、聊天动态、旧配置升级、[[NEXT]] 清洗、400 校验) |
端口和模型取决于当前 DSH 会话,重启后以设置页显示的 endpoint 为准。
| 检查 | 结果 |
|---|---|
| 运行模式切换 | POST /qqpilot/api/config {mode} 在 silent / compat / agent 间即时切换并持久化到 ~/.dsh/qqpilot-dsh-plugin.json |
| 静默模式 | 请求 1ms 返回空 content,usage=0,不调用模型;聊天动态记录 mode=silent, kind=silence |
| 兼容模式 | 返回模型直出文本;聊天动态记录 mode=compat, kind=reply |
| 工具模式 | 模型经工具决定回复;聊天动态记录 mode=agent, kind=reply、耗时与 tokens |
| 聊天动态接口 | GET /qqpilot/api/activity?since=0&limit=10 返回 3 条(静默/兼容/工具),含 sender(从 [username] 解析)、入站文本、回复、图片数、elapsedMs、usage;增量 since=latestId 正常 |
| 设置页 | 设置页出现「概览 / 聊天动态 / 设置」页签与运行模式选择器;Web Client Slot 仍为 active(HMR 重载后) |
| 深色模式按钮 | 主按钮文字与开启态开关圆点改用 --dsw-alias-label-primary-foreground(浅色=白、深色=近黑),不再出现白字白底 |
可视化聊天状态为浏览器渲染;Slot 注册与接口数据已验证,实际视觉效果请在 DSH 设置页确认(必要时刷新页面加载最新客户端代码)。
| 检查 | 结果 |
|---|---|
| 聊天窗口状态条 | Web Client conversation.input.dock 中已注册 qqpilot-status(order 70,active);输入框上方显示 QQPilot 模式与最新消息,展开看最近 6 条,2 秒自动刷新 |
| 设置页并存 | settings.section 的 qqpilot 仍 active(两个入口同时保留) |
| DSH 工具可见 | GET /qqpilot/api/config 的 availableDshTools 返回 read, glob, grep, web_search, web_fetch, read_image(安全策略) |
| DSH 工具作用域 | 插件自动创建专用 qqpilot-bridge Agent(挂载当前默认 preset),工具在该 Agent 作用域内执行,不污染用户会话;GET /qqpilot/api/tools 可看到 35 个可见工具与过滤结果 |
| DSH 工具真实调用 | POST /qqpilot/api/tools/test → ok:true,read 读取插件 package.json,9ms 返回内容(真实 ctx.tools.execute 管线) |
| 危险工具拒绝 | pwsh / bash / write / edit / subagent / workflow / plugin_manager 默认在 dshToolDeny,不会提供给模型 |
| 离线单测 | 新增“安全工具可见并可执行”“关闭策略不提供工具”“未知工具不执行”场景,全部 PASS |
工具调用发生在工具模式下;兼容模式与静默模式不会向模型提供任何工具。首次进入聊天窗口若看不到状态条,刷新一次页面即可加载新的客户端代码。
| 检查 | 结果 |
|---|---|
| 模型目录接口 | GET /qqpilot/api/models 返回 7 个 provider(deepseek-official / deepseek-account / xiaomi / llamacpp / spark-x2 / qwen35 / deepseek-r1-0528-qwen3-8b)及各自模型 |
| 设置页模型卡片 | 设置 → QQPilot 接入 → 设置 → 模型:跟随 DSH 默认模型开关 + provider/model 下拉 + 保存模型 |
| 指定模型生效 | POST {provider:"deepseek-official",model:"deepseek-flash"} 后,config.modelSource=override,QQPilot 模拟请求 954ms 返回 "等于2" |
| 恢复默认 | POST {provider:"",model:""} 后 modelSource=default,当前默认 llamacpp/MiniCPM5-1B-F16.gguf |
| 持久化 | provider / model / reasoningEffort 写入 ~/.dsh/qqpilot-dsh-plugin.json |
| 离线单测 | 新增模型目录 + 指定/恢复模型场景,全部 PASS |
| 检查 | 结果 |
|---|---|
| 工具参数 | qqpilot_reply.text 支持 string | string[](JSON Schema oneOf) |
| 落库/返回 | 数组按顺序转成 [[NEXT]] 拼接的 choices[0].message.content;空字符串/空白项被丢弃;数组与 [[NEXT]] 混用会被展开 |
| 联机实测(默认模型) | 使用默认模型 deepseek-account/deepseek-flash,要求“一次回复三条独立消息”:返回 3 段 [[NEXT]](打招呼 / 时间 / 卖萌),1.2s,活动记录 messages=3 |
| 弱模型兼容 | 免费 llamacpp/MiniCPM5-1B 在工具模式下不能稳定调用工具(会把调用意图当普通文本输出);但把运行模式切到兼容模式并提示“用 [[NEXT]] 分隔”,即可得到多段回复(实测 3 条:[[NEXT]] + 换行都会被 QQPilot 拆成独立消息) |
| 容错解析 | 如果弱模型把数组当字符串传('["a","b"]' 或嵌套 '[["a","b"]]'),插件会尝试 JSON 解析并展开成多条消息 |
| 图片组合 | 数组文本 + images 同一回复时,文本多段 + 图片数组均正常返回(单测覆盖) |
| 兼容性 | 旧的单字符串写法、[[NEXT]] 写法、图片回复、工具调用全部回归通过 |
| 离线单测 | 数组、数组+[[NEXT]]、数组+图片 三个新场景 PASS |
| 检查 | 结果 |
|---|---|
| 设置页 | 「设置 → 工具与工作区」新增:工具轮数上限(1-32)输入 + 保存、工作空间路径 + 保存、当前生效路径显示 |
| 工具轮数 | POST {maxToolRounds:8} → config 立即为 8 并持久化;99 / abc 被拒绝并提示 1-32 |
| 工作空间 | POST 自定义目录 → 自动创建、workspaceRoot/effectiveWorkspace 更新;workingDirectory.set 应用到 qqpilot-bridge Agent(诊断 appliedAgentWorkspace 一致) |
| 非法路径 | 指向普通文件 → ok:false「工作空间路径不是目录」;清空 → 恢复跟随 DSH 工作区 |
| 工具调用回归 | DSH 0.2.2 的批量 executor API 适配后,read 自测 2ms 成功(兼容 0.2.1 单调用 API) |
| 持久化 | maxToolRounds / workspaceRoot 写入 ~/.dsh/qqpilot-dsh-plugin.json,重启后保留 |
| 设置页修复 | 修复「工具与工作区」卡片引用未定义的 roundsDraft / workspaceDraft / workspaceNotice(应为 props.*),并加 ErrorBoundary:以后渲染异常显示提示而不是整页空白 |
| 目录选择器 | 工作空间路径旁新增「选择目录…」按钮,调用 DSH uiWorkspace.pickDirectory() 打开系统目录选择器,回填路径后保存 |
| 检查 | 结果 |
|---|---|
| 识别多用户请求 | 用真实 dest.json(绿叶 / baiyan / 123 三位用户 + 2 条历史 assistant)验证,解析出 userCount=3、participants=[绿叶,baiyan,123]、pendingCount=1 |
| 完整上下文(默认 all) | 模型收到全部 6 条消息;system 追加“本次请求包含 3 条用户消息…”与未回复消息列表;活动记录 userCount=3/participants=3/pendingCount=1/contextMode=all;实测回复 收到,不乞讨! |
| 旧版单条(latest) | 模型只收到 system + 最后一条(123)消息;活动记录 userCount=1/participants=[123]/contextMode=latest;实测回复正常 |
| 设置页 | 「工具与工作区 → 上下文模式」新增 完整上下文 / 旧版单条 两个选项,切换即持久化 |
| 聊天动态 | 多条用户输入时元信息显示「用户 N 位:… / 输入 N 条」 |
| 离线单测 | 新增 all/latest 两个多用户场景,全部 PASS |
| 检查 | 结果 |
|---|---|
| 窗口识别 | 系统提示改为“QQ 聊天窗口快照(滑动窗口)”,只把最后一条 assistant 之后的用户消息列为待回复(pending),更早消息明确标为历史 |
| 待回复标记 | 活动记录新增 pendingStart/incoming[].pending;聊天动态逐条显示「新 / 历史」标签,元信息显示「窗口消息 N 条 / 待回复 M 条」 |
| 实测 dest.json | userCount=3 / pendingCount=1;绿叶、baiyan 标为“历史”,123 标为“新”;模型正常回复 |
| 全已回复窗口 | 窗口以 assistant 结尾时 pending=0,系统提示“窗口里的用户消息都已经有回复;除非仍有必要补充,否则保持沉默” |
| 设计取舍 | 不做跨请求状态缓存(QQPilot 无会话 ID,缓存会串群/私聊);滑动窗口本身已提供必要的近期上下文,超出窗口的历史按设计丢弃 |
| 离线单测 | 新增 pending 标记、全已回复窗口断言,全部 PASS |
| 检查 | 结果 |
|---|---|
| 启用校验 | 工作空间没有 get_chat_name.exe / UploadFiles.exe 时,POST 启用返回 ok:false 并提示 QQPilot data 目录示例 |
| 设置确认 | 设置页新增「QQPilot 辅助程序(DLC)」卡片:两个开关 + 程序是否存在提示 + 启用二次确认 + 风险说明 |
| 程序探测 | 工作空间切到 releaseBuild\1.5.20 x64 - Copy\data 后,helperPrograms 显示两个程序均 found,启用成功 |
| 工具注入 | 启用后工具模式模型可见 qqpilot_get_chat_name / qqpilot_upload_files;关闭/缺程序时不注入 |
| 调用顺序 | 辅助工具不结束回合,模型调用后继续循环,最后必须用 qqpilot_reply/qqpilot_do_not_reply 收尾;单轮辅助工具上限 4 次 |
| 参数校验 | UploadFiles 仅允许工作空间/imageRoots 内文件,最多 8 个;OCR 群名失败会返回明确错误文本 |
| 离线单测 | 启用拒绝、启用成功、两个工具执行、工具结果回喂模型、活动记录 helpers,全部 PASS |
| 设置页修复 | 修复 DLC 卡片引用未定义的 helperPrograms(应为 props.helperPrograms);新增 test/client-render.mjs,用假 React 渲染概览/聊天动态/设置三个页签,专门捕获这类 props 拼写错误 |
若插件热更新时设置页一片空白:这是旧页面里 React 组件实例与新版 hooks 不匹配导致的,刷新页面即可恢复; 新版客户端已加 ErrorBoundary(异常会显示红色提示而不是空白)并把未捕获错误上报到
/qqpilot/api/client-errors。
MIT

