前言¶

在 QQ 群或私聊里跑机器人，常见做法是让 QQPilot 把聊天记录 POST 给一个 OpenAI 兼容的 /chat/completions，再按返回文本发消息。模型、工具链和权限若仍绑在外部 API 或单一后端上，就很难和 DeepSeek Harness（DSH）里已经配好的 provider、默认模型、只读/联网工具共用同一套环境。下面介绍社区插件 qqpilot-dsh-plugin（维护者 QQPilotOrganization，分类：工作流）：它在 DSH 进程内接管 QQPilot 期望的兼容端点，把一次聊天请求转成 DSH 的模型调用，并由模型（或配置）决定回复、沉默或附带图片。

这是什么¶

qqpilot-dsh-plugin 是 QQPilot 与 DSH 之间的桥接 bundle：对 QQPilot 暴露 POST /qqpilot/v1/chat/completions（非流式）和 GET /qqpilot/v1/models，内部使用 DSH 当前默认模型（或设置页单独指定的 provider/model）通过 llm.stream 处理消息。QQPilot 仍只需改 config.ini 里的 server_url 指向本插件；路由与模型选择由 DSH 侧完成。

仓库：https://github.com/QQPilotOrganization/qqpilot-dsh-plugin
目录页：https://www.skillhub.cn/plugins/QQPilotOrganization/qqpilot-dsh-plugin

请求怎么走¶

QQPilot 原本只会向 OpenAI 兼容地址 POST 并取回文本。安装本插件后，数据流如下：

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[] ──┘

返回给 QQPilot 时，choices[0].message.content 必须是字符串；空字符串表示本次不发送。图片放在 choices[0].message.images[]，URL 需为 data:image/...;base64,... 形式；仅有图片无文本时插件会补短 caption，避免 QQPilot 把整条当作空内容跳过。

三种运行模式¶

在 DSH 设置 → QQPilot 接入 可切换模式，写入 ~/.dsh/qqpilot-dsh-plugin.json（mode、compatibilityMode、extraInstructions），重启 DSH 后仍生效。

工具模式下，模型未调用工具而直接输出文本时，文本仍会作为回复返回。多轮工具上限、失败时是否回退兼容输出可在 cordis.patch.yml 配置（如 maxToolRounds 默认 4，fallbackToCompat 默认 true）。

静默模式适合挂机观察：只把收到的消息记进聊天动态，不调用模型。

智能体工具与 DSH 工具¶

工具模式专用：

• qqpilot_reply：参数 text 与 images（本地路径、http(s) URL 或 data URL）。
• qqpilot_do_not_reply：返回空 content，QQPilot 跳过发送。

此外可把 DSH 工具一并提供给桥接后的 AI（设置页或 dshTools：off / safe / all）。safe 默认可用只读与联网类工具（如 read、glob、grep、read_image、web_search、web_fetch）；pwsh、bash、write、edit、subagent、workflow、plugin_manager 等在默认拒绝列表中。

入站 QQ 图片（vision 请求的 image_url）经 DSH attachments 转成模型可读块；无附件服务时退化为文字占位，请求不会因此失败。

可视化与设置¶

两种内置入口：

1. DSH 聊天窗口：输入框上方可折叠「QQPilot」状态条，约每 2 秒刷新，展开可看最近 6 条收/发与工具调用摘要。
2. 设置页 → 聊天动态：完整记录，可暂停刷新，查看耗时、token、工具调用与错误。

设置页 QQPilot 接入 含概览、聊天动态、设置：端点地址、运行模式、附加指令、请求统计、测试连接。安装成功时宿主日志会出现类似：

[qqpilot] QQPilot 接入已就绪 endpoint=http://127.0.0.1:<端口>/qqpilot/v1 模型=<provider>/<model> 兼容模式=false

端口以 DSH Web 实际监听为准，设置页会显示完整端点。

安装与启用¶

本仓库为 DSH bundle（package.json 中 dsh.bundle.patch 指向 cordis.patch.yml），无需构建。要求 Node >=22.13.0（见 package.json engines）。

README 给出的方式包括：通过 DSH 界面安装 bundle（截图说明），或在当前 profile 安装本地目录：

plugin_manager → install_bundle → target = <本目录绝对路径>

命令行示例（路径按本机替换）：

dsh plugin --profile <profile> add C:\path\to\qqpilot-dsh-plugin
dsh --profile <profile>

已安装后可用 plugin_manager → set_bundle / set_plugin 启用或停用，插件热加载，无需改代码。

配置 QQPilot¶

编辑 QQPilot 的 config.ini [general] 段，将 server_url 指向插件根路径（末尾不要 /，QQPilot 会拼 /chat/completions）：

server_url = http://127.0.0.1:55068/qqpilot/v1
api_key =
modelname = deepseek-flash
isvisionmodel = true
remote_server_timeout = 300

说明：

• 对 127.0.0.1 / localhost QQPilot 不发送 Authorization，api_key 可留空。
• 本插件使用 DSH 侧模型；QQPilot 的 modelname 不用于路由。
• DSH 换端口时需同步改 server_url。
• 请保持 forceollamaapi = false，Ollama / builtin 后端不会走本插件。

模型选择优先级¶

1. 设置页「模型」卡片：可固定 provider/model，保存后下一轮生效；默认跟随 DSH 全局默认。
2. 未指定时实时读取 DSH 默认模型。
3. cordis.patch.yml 的 provider / model 作默认值；设置页显式指定会覆盖。

工具调用建议使用支持 tool calling 的模型；本地极小模型在多工具场景可能慢或超时，可将 dshTools 设为 off 或换更大模型。

常用配置字段（cordis.patch.yml）¶

设置页已暴露运行模式与附加指令；其余可在 patch 中调整，例如：

完整字段表见仓库 README「配置项」一节。

验证（可选）¶

仓库提供离线单元测试与在线模拟 QQPilot 请求脚本，例如：

node test/host-unit.mjs
node test/mock-qqpilot.mjs --url http://127.0.0.1:55068/qqpilot/v1

运行前需已启动 DSH 并安装本 bundle；URL 端口与当前 DSH 一致。

适用场景与注意¶

适合已在用 QQPilot、希望 QQ 侧消息由 DSH 里同一套模型与（可选）只读/联网工具处理的工作流场景。兼容模式便于不支持 tool calling 的本地小模型；静默模式便于只观察群消息、暂不消耗 token。

插件以 当前 DSH 进程权限 运行，桥接 AI 在 dshTools: all 等配置下可能触发较强能力；安装前应阅读源码与 MIT 许可证，按群规与数据合规自行评估 extraInstructions、工具策略与图片路径（imageRoots）范围。

DSH 社区插件目录（如 skillhub.cn）为独立站点，与 DeepSeek / 幻方无官方从属关系；本介绍事实来源为上述 GitHub README 与 package.json（当前版本 0.1.0）。

结尾¶

qqpilot-dsh-plugin 把 QQPilot 固定的 OpenAI 兼容调用方式接到 DSH，用工具模式区分「回复 / 不回复 / 带图」，用设置页与聊天动态把 QQ 侧行为可视化。需要细节与 HTTP 管理接口时，直接查阅仓库 README 与 docs/PROTOCOL.md。

• 目录页：https://www.skillhub.cn/plugins/QQPilotOrganization/qqpilot-dsh-plugin
• GitHub：https://github.com/QQPilotOrganization/qqpilot-dsh-plugin