dsh-qqbot

Readme

# dsh-qqbot

开源的 DeepSeek Harness (dsh) QQ Bot IM 插件。

把 QQ 消息平台作为 dsh agent 的前端协议驱动：用户在 QQ 私聊/群聊中与 dsh agent 对话、执行工具、切换模型、管理会话/工作区，并通过 QQ 消息完成审批。

> 本仓库是从零重写的可开源版本，不包含腾讯内部插件代码，也不依赖 `UNLICENSED` 的 `@tencent-connect/qqbot-connector`。
> 底层协议使用 MIT 许可的 [`@tencent-connect/qqbot-nodejs`](https://www.npmjs.com/package/@tencent-connect/qqbot-nodejs)。

## 功能

- QQ 私聊（C2C）/群聊消息接入
- 流式回复、Markdown 分块发送
- 会话隔离、空闲回收、重启恢复
- 模型路由：per-peer 偏好 / `settings.yaml` / 宿主默认
- 群聊历史上下文、引用消息、文件附件下载
- 内置命令：`/bot-model`、`/bot-reset`、`/bot-status`、`/bot-workspace`、`/goal`、`/dsh` 等
- 工作区隔离与跨会话切换
- dsh 审批桥：QQ 按钮/文字审批，WebUI 同时提示
- goal 长任务完成通知

## 安装

要求：Node.js >= 18，dsh 环境已可用。

```bash
# 在 dsh-qqbot 项目目录构建
corepack pnpm install
corepack pnpm build

# 安装到 dsh profile（本地路径）
dsh plugin --profile qqbot add /path/to/dsh-qqbot

# 启动
export QQBOT_APPID="你的AppID"
export QQBOT_SECRET="你的AppSecret"
dsh --profile qqbot
```

也可通过 `cordis.patch.yml` 以 `--patch` 方式加载。

## 配置

在 profile 的 `cordis.patch.yml` 中：

```yaml
- id: im-qqbot
  config:
    appId: __FROM_ENV__
    appSecret: __FROM_ENV__
    requireMention: true
    textChunkLimit: 4500
    sessionIdleTimeout: 1800000
    maxQueue: 20
    processingTimeoutMs: 120000
    historyLimit: 10
    access:
      c2cMode: open
      c2cAllow: []
      groupMode: open
      groupAllow: []
    debug: false
```

主要配置：

| 配置 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `appId` / `appSecret` | string | 必填 | QQ Bot 凭据，也可用 `QQBOT_APPID` / `QQBOT_SECRET` |
| `provider` / `model` | string | 继承宿主 | 默认模型路由 |
| `requireMention` | boolean | `true` | 群聊是否需要 @bot |
| `streaming` | boolean | `true` | C2C 流式回复 |
| `sessionIdleTimeout` | number | 1800000 | 会话闲置回收时间 |
| `approvalTimeoutMs` | number | 300000 | QQ 审批等待超时 |
| `approvalNotifyTarget` | object | - | 固定审批通知目标 |
| `access` | object | open | 访问控制 |

## 开发

```bash
corepack pnpm install
corepack pnpm build     # 构建 dist
corepack pnpm typecheck
corepack pnpm test      # 运行测试
```

## 架构

```
QQ 用户 → QQ WebSocket → @tencent-connect/qqbot-nodejs → 中间件链
                                                              ↓
                                                     handleInbound
                                                              ↓
                                                     SessionManager → dsh agent
                                                              ↓
                                              session/event → outbound → QQ Markdown
```

## License

[MIT](./LICENSE)