wang-22-code/dsh-qqbot-bridge

dsh-qqbot-bridge

基于腾讯官方 QQ 机器人开放平台，将 QQ 私聊或群聊安全地接入 DeepSeek Harness（DSH）。给机器人发送消息，就等同于向一个独立的 DSH Agent 会话发送消息。

当前版本：0.1.0。项目仍处于早期阶段，建议先使用专用测试机器人、专用工作目录和私聊白名单。

特性

- 只使用腾讯 QQ 机器人开放平台和腾讯官方 SDK，不使用个人 QQ 逆向协议、Hook、注入或模拟登录。
- 首次启动支持腾讯官方扫码绑定，自动保存 AppID、Secret 和扫码用户 OpenID。
- 私聊默认白名单，群聊默认关闭；空白名单不会退化成开放访问。
- QQ 消息直接驱动 DSH Agent，支持流式回复、发送失败自动重试、会话持久化和模型切换。
- 支持在 QQ 内处理 DSH 的一次性权限申请：/approve CODE 或 /deny CODE。
- AppSecret、OpenID 和 API Key 仅保存在本机 $DSH_HOME/.env，不进入项目配置和日志。
- 内置隐私扫描、单元测试、打包检查和 GitHub Actions CI。

合规说明

本项目仅面向腾讯官方机器人能力。使用前请遵守腾讯 QQ 开放平台规则、机器人运营规范和所在地法律法规。平台审核、接口权限、主动消息窗口和频率限制以腾讯当前规则为准。本项目无法承诺账号绝对不会受到限制，但不会提供绕过风控或协议限制的实现。

快速启动

准备条件

- Windows 10/11、macOS 或 Linux
- Node.js >= 22（唯一需要手动安装的运行时，其余由启动脚本自动处理）
- 必须：DeepSeek API Key（DEEPSEEK_API_KEY）——不设置时机器人无法生成任何回复
- 一个腾讯官方 QQ 机器人（AppSecret 无需手动填写，首次启动扫码自动绑定）
- pnpm 与 DSH CLI 无需手动安装——启动脚本会自动装好（pnpm 走 corepack，DSH 装到 $DSH_HOME\profiles）

⚠️ 必填项：必须设置 DEEPSEEK_API_KEY。DSH 默认使用 DeepSeek 官方接口（provider: deepseek-official），缺少 API Key 时模型调用会在运行时直接失败，机器人只会回复「⚠️ 本轮处理出错，请重试。」，启动日志中也会出现警告。请把 API Key 写入本机 DSH 环境文件，而不是项目目录：

Windows 默认位置：C:\Users\\.dsh\.env
macOS/Linux 默认位置：~/.dsh/.env
DEEPSEEK_API_KEY="你的 API Key"

或者命令行设置：
$key = Read-Host -Prompt "粘贴你的 DeepSeek API Key"
Add-Content "$env:USERPROFILE\.dsh\.env" "DEEPSEEK_API_KEY="$key""

Windows：从源码一键启动（零配置）

唯一需要手动安装的是 Node.js ≥ 22（和 git）。其余全部由脚本自动完成——不要求你手动装 pnpm、DSH CLI 或写 AppSecret。

设计说明：dev-start.ps1（Windows 版）不包含 node 存在性检查（与 Linux/macOS 版不同）。请确保 Node.js ≥ 22 已安装并加入 PATH；若缺失，脚本会在后续调用原生命令时报错。

git clone https://github.com/JHf0912/dsh-qqbot-bridge.git
cd dsh-qqbot-bridge
powershell -ExecutionPolicy Bypass -File .\scripts\dev-start.ps1

脚本自动完成：

1. 环境检查：pnpm 缺失时自动启用 corepack（或创建垫片加入 PATH）；DSH CLI 缺失时自动安装到 $DSH_HOME\profiles（含 pnpm 11 必需的 allowBuilds 配置）；
2. 安装依赖并构建 TypeScript；
3. 注册本地插件并链接到当前源码（后续 pnpm build 重建即可生效）；
4. DEEPSEEK_API_KEY 缺失 → 终端提示输入并写入 $DSH_HOME\.env，已有则跳过；
5. 启动前探测并自动修复 node-pty 原生模块（缺失时自动重建、必要时源码编译，国内网络下常见问题）；
6. 启动前调用腾讯接口预校验 QQ 凭据——无效时当场提供 3 个选项：重新粘贴凭据 / 删除并重新扫码 / 跳过继续，而不是等 DSH 启动后才失败。

首次没有 QQ 凭据时，终端会显示官方绑定二维码。扫码成功后，插件会自动写入：

QQBOT_APPID="..."
QQBOT_SECRET="..."
QQBOT_C2C_ALLOW="..."

这些值保存在 $DSH_HOME/.env，不会写入仓库。扫码用户会自动成为第一个私聊白名单用户。

⚠️ 首次扫码后请停掉并重跑一次：首次扫码写入的 QQBOT_C2C_ALLOW 白名单不会注入本次进程，重启后消息才会被接受。看到 [im-qqbot] Bot ready! appId=... 后即可在 QQ 中发送“你好”。

常用参数：--profile 名称（默认 qqbot-safe-dev）、--skip-install、--build-only、--setup-only（完成全部准备但不启动）。

以后启动可直接执行：

node "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh\lib\bin.js" --profile qqbot-safe-dev

如果设置了自定义 DSH_HOME，请将路径替换为对应目录。

Linux/macOS：从源码一键启动

脚本会自动检查环境：

- node 未安装 → 报错并提示先手动安装 Node.js >= 22（https://nodejs.org）；
- pnpm 缺失 → 自动执行 corepack enable；
- DSH CLI 缺失 → 自动安装 @deepseek-ai/dsh 到 $DSH_HOME/profiles（含 pnpm 11 必需的 allowBuilds 配置，避免原生依赖构建被拦截）；
- node-pty 原生模块缺失 → 自动重建、必要时源码编译（国内网络常见问题）；
- DEEPSEEK_API_KEY 缺失 → 交互式提示输入并写入 $DSH_HOME/.env，无需手动准备。

克隆仓库后，在项目根目录执行：

git clone https://github.com/JHf0912/dsh-qqbot-bridge.git
cd dsh-qqbot-bridge
chmod +x scripts/dev-start.sh
./scripts/dev-start.sh

脚本完成的工作与 Windows 版一致：安装依赖并构建 TypeScript、创建或更新 qqbot-safe-dev profile、将 profile 链接到当前源码、启动前校验 QQ 凭据、最后一步才启动 DSH。常用参数：

- --profile 名称：指定 profile 名（默认 qqbot-safe-dev）
- --skip-install：跳过依赖安装
- --build-only：只安装并构建，不启动
- --setup-only：完成全部准备工作但不启动 DSH（适合先跑一遍确认环境，再手动启动）

启动前脚本会调用腾讯接口预校验 QQBOT_APPID/QQBOT_SECRET，凭据无效（如 invalid appid or secret）时会直接报错并给出平台核对指引，而不是等 DSH 启动后才失败。

首次启动同样需要扫码绑定。看到 Bot ready 后重启一次（首次扫码写入的 QQBOT_C2C_ALLOW 不会注入本次进程，不重启白名单为空）。以后启动可直接执行：

node "$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js" --profile qqbot-safe-dev

WSL 注意事项

- 必须安装 Linux 版 Node ≥ 22（如 nvm install 22）。WSL 的互操作会把 Windows 版 node.exe 暴露进 PATH，脚本检测到 /mnt/... 路径会直接拒绝并给出安装指引——否则会出现「终端无输出、Windows 桌面弹报错框」的静默崩溃。
- 其余流程与 Linux/macOS 完全一致（自动装 pnpm/DSH、提示输入 API Key、启动前校验 QQ 凭据）。

npm 发布后安装

dsh plugin --profile qqbot add dsh-qqbot-bridge
dsh --profile qqbot

如果 dsh 没有加入 PATH，可直接调用 $DSH_HOME/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js。

隐私配置教程

本机私密文件

所有敏感配置统一放在：

$DSH_HOME/.env

默认位置：

- Windows：C:\Users\\.dsh\.env
- macOS/Linux：~/.dsh/.env

示例：

QQBOT_APPID="机器人 AppID"
QQBOT_SECRET="机器人 AppSecret"
QQBOT_C2C_ALLOW="用户OpenID1,用户OpenID2"
DEEPSEEK_API_KEY="DeepSeek API Key"

多个用户 OpenID 使用英文逗号分隔。不要把个人 QQ 号当作 OpenID。

Profile 配置

首次执行 dsh plugin add 时插件自带的 bundle 默认配置已自动生效（provider: deepseek-official、model: deepseek-v4-flash、私聊白名单、cwd: ./qqbot-workspace 等），无需手动创建。本节只用于按需自定义。

Profile 配置位于 $DSH_HOME/profiles//cordis.patch.yml。推荐保持 OpenID 在 .env，YAML 只读取环境变量：

- id: im-qqbot
config:
cwd: 'D:/dsh-workspaces/qqbot'
provider: deepseek-official
model: deepseek-v4-flash
requireMention: true

access:
c2cMode: allowlist
c2cAllow: !!js >-
(process.env.QQBOT_C2C_ALLOW ?? '')
.split(',')
.map((value) => value.trim())
.filter(Boolean)
groupMode: disabled
groupAllow: []

acknowledgeOpenAccess: false
allowUnsafeCwd: false
logMessageContent: false
enableApprovals: true
approvalTimeoutMs: 120000
debug: false

修改 .env 或 profile 后应完整重启 DSH：Ctrl+C 停止，再重新运行启动命令。

哪些内容不能上传

不要提交或粘贴到 Issue、PR、截图和日志中：

- $DSH_HOME/.env 或项目 .env
- QQBOT_SECRET、DEEPSEEK_API_KEY
- 真实用户/群 OpenID、消息 ID、TraceId
- 二维码绑定链接或尚未失效的二维码
- $DSH_HOME/sessions、qqbot-workspace、聊天记录和生成文件

提交前运行：

pnpm privacy:check
pnpm check

.gitignore 已排除常见本地敏感文件，但不能替代人工复核。

QQ 权限审批

当工具需要访问工作区之外的位置时，DSH 会先触发审批。插件向任务发起者发送：

⚠️ DSH 权限申请
工具：pwsh
原因：需要访问工作区外路径
允许本次操作：/approve A1B2C3
拒绝本次操作：/deny A1B2C3

审批具有以下边界：

- 仅任务发起者本人可以处理；
- 验证码一次性使用；
- 只授权当前操作，不永久开放磁盘；
- 默认 120 秒超时自动拒绝；
- Agent 取消或 DSH 退出时自动取消；
- 群聊中其他成员即使看到验证码也不能批准。

主要配置

| 配置                      |                默认值 | 说明                                               |
| ------------------------- | --------------------: | -------------------------------------------------- |
| provider              | deepseek-official | DSH LLM provider                                   |
| model                 | deepseek-v4-flash | DSH 模型；可通过/model 切换                    |
| cwd                   | ./qqbot-workspace | Agent 专用工作目录                                 |
| requireMention        |              true | 群聊是否必须 @机器人                               |
| access.c2cMode        |         allowlist | 私聊访问策略                                       |
| access.c2cAllow       |          来自环境变量 | 允许的用户 OpenID                                  |
| access.groupMode      |          disabled | 群聊访问策略                                       |
| access.groupAllow     |                [] | 允许的群 OpenID                                    |
| acknowledgeOpenAccess |             false | 开放访问的二次风险确认                             |
| allowUnsafeCwd        |             false | 是否允许根目录或用户主目录                         |
| logMessageContent     |             false | 是否记录消息正文                                   |
| enableApprovals       |              true | 是否启用 QQ 一次性审批                             |
| approvalTimeoutMs     |            120000 | 审批超时，超时自动拒绝                             |
| streamFlushIntervalMs |              2000 | 流式增量下发间隔(ms)，0=关闭流式（等整条消息） |
| sendMaxRetries        |                 2 | QQ 回复发送失败最大重试次数                        |
| sendRetryBaseMs       |              1000 | 发送重试指数退避基数(ms)                           |
| debug                 |             false | SDK 诊断日志开关                                   |

不建议使用开放模式。如果确实需要：
yaml
access:
c2cMode: open
acknowledgeOpenAccess: true

开放模式会让任何能找到机器人的用户触发 DSH Agent。

内置命令

- /bot-help：查看帮助
- /bot-status：查看会话、模型和用量状态
- /bot-ping：连接测试
- /bot-version：查看版本
- /bot-reset：清除当前会话上下文
- /bot-new：开始新会话
- /bot-stop：终止当前任务（暂未实现）
- /model：查看或切换模型
- /approve CODE：允许当前一次权限申请
- /deny CODE：拒绝当前一次权限申请

项目结构
text
src/
├─ approval.ts          QQ 一次性审批通道
├─ commands/            斜杠命令
├─ model/               模型发现、路由和用户偏好
├─ session/             QQ peer 与 DSH Session 映射
├─ shared/              通用工具和发送辅助
├─ transport/           入站组装、出站缓冲和分片
├─ config.ts            配置 Schema
├─ security.ts          启动前安全校验
├─ setup.ts             官方扫码与私密凭据落盘
└─ index.ts             Cordis 插件入口和生命周期编排

详细设计见 架构说明。

开发与验证
bash
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm typecheck
pnpm privacy:check
pnpm check

pnpm check 会执行隐私扫描、构建、单元测试、类型检查和 npm 打包预览。

常见问题

- 机器人显示“未连接服务”：确认启动终端仍在运行，并检查是否出现 Bot ready。
- 机器人完全不回复：检查 QQBOT_C2C_ALLOW 是否存在且是用户 OpenID，不是机器人 AppID。
- 收到「⚠️ 本轮处理出错，请重试。」：DSH 本轮生成失败。先确认 DEEPSEEK_API_KEY 已配置且模型可用；若持续出现且日志含 corrupt session log，删除 $DSH_HOME/sessions/ 下对应会话后重启。
- DSH 直接 turn/end：显式配置 provider 和 model，并确认模型凭据可用。
- 权限申请没有出现：确认 enableApprovals: true、审批策略为 ask，且操作确实触发沙箱升级。
- 修改 .env 后无效：完整停止并重启 DSH。
- 启动前校验报 invalid appid or secret（code 100016）：.env 中的 QQ 凭据已过期或被重置。此时脚本会当场提供 3 个选项：1 重新粘贴 AppID/AppSecret（写入后立即重新校验）、2 删除凭据并重新扫码绑定、3 跳过校验继续启动。也可到 q.qq.com 的「开发设置」复制当前 AppSecret 后选 1 粘贴。手动删除命令：Windows PowerShell (Get-Content "$env:USERPROFILE\.dsh\.env") | Where-Object { $_ -notmatch '^QQBOT_APPID=|^QQBOT_SECRET=' } | Set-Content "$env:USERPROFILE\.dsh\.env"；Linux/macOS sed -i '/^QQBOT_APPID=/d; /^QQBOT_SECRET=/d' ~/.dsh/.env。
- 启动报 Failed to load native module: pty.node（或 dsh: plugin tree failed to load）：node-pty 原生模块未装上，国内网络从 GitHub 下载预编译包失败最常见。启动脚本会自动修复（补 allowBuilds 配置 → pnpm rebuild node-pty → npx node-gyp 源码编译）。手动处理：先装编译工具（sudo apt install -y build-essential python3，CentOS 用 yum install -y gcc-c++ make python3），然后在 ~/.dsh/profiles 补上含 node-pty: true 的 pnpm-workspace.yaml allowBuilds 配置（内容见启动脚本），再执行 cd node_modules/.pnpm/node-pty@*/node_modules/node-pty && npx --yes node-gyp@11 rebuild。若 npx 拉包缓慢，先 npm config set registry https://registry.npmmirror.com。
- 启动日志出现 [WARN] The package dsh-qqbot-bridge ... peerDependencies ...：pnpm link 链接开发模式下的正常提示（peer 依赖由 DSH 运行时提供），不影响运行，可忽略。

更多排查步骤见 故障排查。

参与贡献

提交改动前请阅读 CONTRIBUTING.md 和 SECURITY.md。安全问题请通过 GitHub Security Advisory 私下报告，不要公开提交凭据或日志。

作者与交流

- 作者：wang-22-code
- QQ：1722800850

欢迎交流使用体验、问题反馈和改进建议。请勿通过公开 Issue、截图或聊天记录发送 AppSecret、API Key、OpenID 等敏感信息。

来源与许可

本项目派生自腾讯官方 MIT 项目 @tencent-connect/dsh-qqbot，由社区独立维护，并非腾讯官方产品。详见 LICENSE 和 NOTICE。