本文由本站基于该插件已收录的字段自动派生（wiki / faq / compatibility_json / readme），非 AI 即时创作。每节末尾标源字段。

快速上手

dsh-qqbot

— 源: plugin_wiki.wiki_content

安装与验证

dsh plugin --profile web add @tencent-connect/dsh-qqbot

复制以上命令在 DSH Web Profile 内运行。安装完成后在「插件列表」启用即可。

— 源: plugins.install

关键要点

• 纯 Cordis 插件 — 遵循 dsh "Plugins, not loop changes" 原则
• 声明式依赖 — inject = ['agents']，不直接耦合其他插件
• 会话隔离 — 每个 QQ 私聊用户/群聊各一个独立 Agent
• Preset 支持 — 可通过 agent-presets 服务挂载预设（工具集、prompt 等）
• 闲置回收 — 超时自动 dispose Agent，防止内存泄漏

— 源: plugin_wiki.readme_zh (fallback readme_raw)

常见问题

第一次启动需要做什么？

启动时如果没检测到 AppID/AppSecret，插件会在终端打印二维码，扫码完成绑定；凭据会自动写入当前 profile 的 cordis.patch.yml，下次启动无需再扫。二维码错位时可用 0.4.0+ 版本输出的浏览器链接替代。

群聊里必须 @bot 才会回复吗？

默认开启 requireMention，群聊只在 @bot 时触发回复；设为 false 后任何消息都会触发。私聊不受此开关影响，始终响应。

一个 QQ 群里的对话上下文会串到另一个群吗？

不会。每个 QQ 私聊用户和每个 QQ 群都有独立的 sessionKey，sessionId 由 qqbot:${appId}:${scope}:${peerId} 经 SHA-256 确定性派生，重启后可恢复；但不同群/不同人之间的对话是隔离的。

支持图片、语音、文件吗？

图片会带尺寸描述写入上下文；语音优先使用 ASR 转写后的文字，模型拿不到音频时附原始链接兜底；文件附件会自动下载到 ${cwd}/.qqbot/${messageId}/ 下并提示路径，模型再通过工具读取。文件下载做了 HTTPS + SSRF 防护与 20MB 大小限制。

流式回复怎么开？

私聊默认开启流式（streaming: true），回复会逐段推送；群聊始终不启用流式，因为 QQ 群消息接口限制只能发整段 Markdown。如果关闭全局流式，私聊也会改为一次性发送完整回复。

想切模型怎么操作？

在聊天里直接发 /model 会列出当前可用模型（点击切换），或 /model provider/model 指定具体路由。偏好会按 sessionKey 持久化到 ~/.dsh-qqbot/model-prefs.json，同一个人/群下次启动仍然生效。

怎么彻底重置当前对话？

发 /new（别名 /reset、/clear）会丢弃当前会话并开新会话；要保留上下文但压缩历史可发 /compact（需要 host 装了 compaction 服务）。长会话闲置超过 30 分钟会被自动回收，下次消息到来时再恢复。

报 "凭据未配置" 怎么办？

走扫码会自动写入 profile；如果是开发模式（用 cordis.dev.yml 加载源码），无法定位 profile 目录，插件会在终端打印 export/set 环境变量的指引。手工配置时把 appId 与 appSecret 写到 profile 的 cordis.patch.yml 对应插件条目下即可。

— 源: plugin_wiki.faq_json

兼容性

• DSH: 0.1.0-rc.6+
• Node: 未声明

— 源: plugin_wiki.compatibility_json

踩坑提醒

安装前请审阅上游仓库；本指南基于已收录字段自动派生，可能滞后于最新版本。如发现与官方文档冲突，请以上游为准。

— 来源：通用规则