@yachangchang/dsh-qq-bridge

配置

推荐在 DSH Web 左下角“设置”里的 QQ bridge 页面修改配置并保存。通过设置页保存时，NapCat 模式会写入本机 OneBot 配置，当前 DSH Web 进程会按新配置启动或重启 bridge。

如果要手动排查，bundle 配置会进入 DSH profile 的 bundles 配置；旧版 setup 仍会写这个文件：

~/.dsh/profiles/web/cordis.patch.yml

改完后重启 dsh web。重启 DSH web 时不需要再导出 DSH_QQ_TOKEN 或 DSH_PERMISSION_MODE；setup 或设置页已经把必要配置写入本机配置。

选择 QQ 接入方式

NapCat / OneBot

默认推荐走 NapCat / OneBot，适合个人本机使用。setup 会检查 napcat 命令、启动状态和登录日志，自动配置 OneBot 正向 WebSocket 到 127.0.0.1:3001，并创建或复用 OneBot access token。

支持两种用法：

• 双号模式：一个 QQ 号登录 DSH，监听消息；另一个 QQ 号给 DSH 发送指令。推荐新用户直接用这个。
• 单号模式：同一个 QQ 登录 NapCat，并从手机 QQ 给自己发消息。

双号模式下，登录 DSH 的账号不建议用不常用小号，因为不常用的号登录可能会被腾讯服务端 kill 掉。

单号模式下，可以收到 Agent 完成自动提醒，但可能无法收到消息提示。

配置示例：

platform: napcat
napcat:
  wsUrl: ws://127.0.0.1:3001
  token: ""

已移除自发消息保活及相关设置，旧版 selfKeepAlive 配置不再生效。设置页和重启恢复检测只查询 OneBot 的账号信息和在线状态，不发送 QQ 探测消息；接口返回在线不等同于已经验证消息投递。

每条保活消息都会附带唯一 uid。Bridge 最多等待 OneBot 动作响应 2 秒；连续 3 次超时会在 DSH 日志中将 NapCat 登录状态标记为 logged-out，任意一次成功则立即标记或恢复为 logged-in。

腾讯官方 QQ Bot

官方路径适合想用开放平台机器人账号的用户。需要先到 QQ 开放平台机器人控制台 创建机器人，然后输入 AppID、AppSecret 和沙箱开关。

第一次配置时不需要手动找 adminOpenId：setup 会临时连接 QQBot 网关，生成一次性 pair ，你用管理员 QQ 发给机器人后，插件会自动读取 sender openid、回复“配对成功”，并写入 official.adminOpenId。

由于腾讯开放平台规则限制，当前插件若走 QQ Bot 路径，则不支持 Agent 完成自动提醒 功能。

官方 QQ Bot 的主动提醒有额度限制。插件在官方模式下默认关闭 notifications.agentReply.enabled，避免触发 40034122 / 召回消息已达区间上限。

切到腾讯官方 QQ Bot 时，推荐重新运行 setup。手动配置示例：

platform: official
official:
  appId: ""
  appSecret: ""
  adminOpenId: ""
  allowlistOpenIds: []
  sandbox: false
access:
  adminQq: 0
  allowlist: []
  commandPrefix: ""
  mode: whitelist
notifications:
  agentReply:
    enabled: false

adminOpenId 是“你的 QQ 用户在这个机器人应用下的 openid”，不是 QQ 号，也不是 AppID。第一次不知道它时，用 setup 自动配对最稳。

更改模型

修改 agent.provider 和 agent.model：

agent:
  provider: deepseek-official
  model: deepseek-v4-pro
  cwd: "~"
  preset: dsh-qq-bridge
  ackMessage: 收到，正在处理...

• provider：DSH 里已配置好的模型提供方。
• model：该 provider 下的模型 id。
• cwd：QQ Agent 默认工作目录，默认是 ~；/dir 会覆盖当前 QQ 会话的后续 session 目录。
• preset：QQ 会话使用的 DSH agent preset。setup 会安装 dsh-qq-bridge 专用 preset；普通 Web 会话不选它就不会看到 QQ 回复风格 skill。

更改确认消息和超时

收到有效 QQ 指令后，插件会先回复 agent.ackMessage。设为空字符串 "" 可以关闭确认消息：

agent:
  ackMessage: 收到，正在处理...

默认情况下，QQ 对话不会限制 Agent 等待时间，会一直等到本轮 DSH Agent 完成。需要保留超时保护时，可手动设置 timeoutMs 和 timeoutMessage：

agent:
  timeoutMs: 120000
  timeoutMessage: agent 无响应，请稍后重试。

手动 YAML 中的 timeoutMs 是内部毫秒字段。设置 timeoutMs 后，超时会回复 timeoutMessage。

QQ 回复风格 Skill

setup 会同步一个 QQ 专用 preset 到：

~/.dsh/.agent-presets/dsh-qq-bridge

这个 preset 挂载随附的回复风格 skill：

~/.dsh/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/SKILL.md
~/.dsh/.agent-presets/dsh-qq-bridge/skills/qq-session-reply-style/references/reply-style.md

默认规则：

• 先给结论。
• 回复尽量简明扼要。
• 不用 Markdown 风格，用纯文本，可以多用 emoji。

插件只会在 QQ 会话的第 1、30、60... 个 Agent 回合主动发送 /qq-session-reply-style，让 DSH 的 skill 工具加载入口文件并按模块读取回复风格；其它 QQ 回合只附加一句很短的临时风格标记，避免每轮塞入大段 prompt。

如果你要改 QQ 回复风格，优先改上面的 references/reply-style.md；SKILL.md 只作为入口和模块索引。注意保留“只适用于 dsh-qq-bridge QQ 会话、不要写入记忆、不要影响普通 DSH Web 会话”的限制。

如果不想要 QQ 专属回复风格，改成：

agent:
  qqReplyStyleSkill:
    enabled: false

更改指令前缀

修改 access.commandPrefix：

access:
  commandPrefix: /dsh

例如改成 /ai 后，QQ 里就要发送：

/ai ping

更改允许使用的人

NapCat 模式使用 QQ 号鉴权。只允许自己使用：

access:
  adminQq: 
  allowlist: []
  mode: whitelist

允许额外 QQ：

access:
  adminQq: 
  allowlist: [10001, 10002]
  mode: whitelist

官方 QQ Bot 模式使用 openid 鉴权：

platform: official
official:
  adminOpenId: ""
  allowlistOpenIds: [""]
access:
  adminQq: 0
  allowlist: []
  mode: whitelist

不建议把 mode 改成 open，除非你明确知道风险。

单号模式日志

单号模式会读取 NapCat 日志，把“自己给自己”的消息转成内部消息：

selfLogInput:
  enabled: true
  logPath: /home//Napcat/log/napcat_.log
  pollIntervalMs: 1000
  replayOnStart: false

如果你是“主号发给机器人小号”，通常可以关闭：

selfLogInput:
  enabled: false

Agent 回复提醒

notifications.agentReply.enabled 控制“非 QQ 会话中 Agent 完成一轮回复后，主动给管理员发提醒”：

notifications:
  agentReply:
    enabled: true

NapCat 模式默认开启；官方 QQ Bot 模式默认关闭。QQ 自身发起的对话不会再额外发送“主人，您收到一条 Agent 回复...”提醒，只保留实际 Agent 回复。

DSH 默认权限

setup 可选修改 ~/.dsh/settings.yaml：

permission:
  defaultPreset: workspace-write

可选项：

• workspace-write：较安全。Agent 只能写工作区和允许的临时目录，越权操作需要网页端审批。
• danger-full-access：最省心但风险最高。Agent 可直接访问本机进程权限能访问的路径，且不会弹出审批。

这里配置的是 DSH 后续新会话的默认权限；QQ 里发送 /permission 会通过 DSH 原生命令切换当前 QQ live session 的权限，不会改写 settings.yaml。

• 保持现有 settings：setup 不修改 DSH 全局默认权限。

这个默认值只影响之后新建的 Web 会话，不改变已经打开的会话。

本地回显测试

只想测试 QQ 链路、不接 DSH Agent 时，可以用本地回显模式：

DSH_QQ_ADMIN= \
DSH_QQ_TOKEN= \
DSH_QQ_SELF_LOG=true \
bash scripts/start-local-echo.sh

发送 ping，预期回复：

echo: ping

正式使用 pnpm dsh web 时，以 cordis.patch.yml 为准，不需要这些环境变量。

更改允许使用的人

NapCat 模式使用 QQ 号鉴权。只允许自己使用：

access:
  adminQq: 
  allowlist: []
  mode: whitelist

允许额外 QQ：

access:
  adminQq: 
  allowlist: [10001, 10002]
  mode: whitelist

官方 QQ Bot 模式使用 openid 鉴权：

platform: official
official:
  adminOpenId: ""
  allowlistOpenIds: [""]
access:
  adminQq: 0
  allowlist: []
  mode: whitelist

不建议把 mode 改成 open，除非你明确知道风险。