@yuxiaoyu8192/dsh-qqbot

基于 deepseek-harness (dsh) 的 QQ Bot IM 插件，将 QQ 消息平台作为 dsh agent 的前端协议驱动。

中文 | English

架构

QQ 用户 → QQ WebSocket → dsh-im-qqbot → ctx.agents → dsh agent loop → LLM
                                 ↑                           │
                                 └── session/event ──────────┘
                                       (assistant reply → QQ sendMarkdown)

主要功能

• 支持 C2C 私聊 / 群聊消息接入
• Markdown 文本回复与 C2C 流式输出
• 图片、视频、语音、文件发送
• 语音消息自动转码（mp3 / flac 等常见音频）
• 卡片消息：Markdown / Ark / Embed / 自定义模板 + 按钮
• 按钮点击事件回传 Agent
• 引用文件自动下载并传给 Agent
• 会话管理、模型切换、访问控制、闲置回收
• 出站消息自动排队，降低触发 QQ 频控的概率

安装

方式一：手动执行

# 安装到 profile
npx @deepseek-ai/dsh plugin --profile qqbot add @yuxiaoyu8192/dsh-qqbot

# 启动
npx @deepseek-ai/dsh --profile qqbot

首次启动时，插件检测到凭据未配置会自动进入扫码引导：终端输出二维码 → 手机 QQ 扫码绑定 → 凭据自动保存到 profile，后续启动无需再次扫码。

提示：建议升级至 0.4.0 以上版本扫码，支持点击链接在浏览器打开，避免部分终端二维码渲染错位的问题。

方式二：本地路径安装

# 构建
cd /path/to/dsh-qqbot
pnpm install && pnpm build

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

# 启动
export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh --profile qqbot

方式三：--patch 开发模式

export QQBOT_APPID="你的AppID" QQBOT_SECRET="你的AppSecret"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

配置项

| 配置 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appId | string | 必填 | QQ Bot AppID（或通过 QQBOT_APPID 环境变量） | | appSecret | string | 必填 | QQ Bot AppSecret（或通过 QQBOT_SECRET 环境变量） | | provider | string | deepseek-official | LLM 提供商名称 | | model | string | deepseek-chat | 模型名称 | | preset | string | - | Agent preset id | | cwd | string | process.cwd() | Agent 工作目录 | | requireMention | boolean | true | 群聊是否需要 @bot 才触发 | | groupPrompt | string | - | 群聊额外 system prompt | | directPrompt | string | - | 私聊额外 system prompt | | textChunkLimit | number | 4500 | 单条消息最大字符数 | | sessionIdleTimeout | number | 1800000 | 会话闲置超时(ms)，默认 30 分钟 | | debug | boolean | false | 调试模式 |

内置命令

| 命令 | 说明 | |------|------| | /new（别名 /reset /clear） | 开始新会话（清空上下文） | | /compact | 压缩会话历史（摘要替换旧记录，保留上下文） | | /model | 查看或切换模型 | | /stop | 中止当前生成 | | /bot-ping | 连通性测试 | | /bot-version | 查看版本信息 | | /bot-status | 查看当前会话状态 | | /bot-help | 查看所有指令 |

Agent 工具

插件会向 dsh Agent 注入以下工具：

qq_send_media

发送图片、视频、语音或文件。

{
  "tool": "qq_send_media",
  "media_type": "image",
  "source": "/tmp/cat.png"
}

语音消息支持自动转码：

{
  "tool": "qq_send_media",
  "media_type": "voice",
  "source": "/tmp/voice.mp3"
}

qq_send_card

发送卡片消息，支持 Markdown / Ark / Embed / 自定义模板，可选图片和按钮。

{
  "tool": "qq_send_card",
  "mode": "markdown",
  "text": "这是一张卡片",
  "image": "/tmp/card.png",
  "buttons": [
    { "label": "确认", "data": "confirm" }
  ]
}

按钮点击后会自动回传 Agent 处理。

核心模块

src/
├── index.ts                    # Cordis 插件入口（async apply）
├── config.ts                   # 配置 Schema
├── types.ts                    # 全局类型定义
├── setup.ts                    # 凭据绑定（扫码）
├── transport/                  # 传输层
│   ├── inbound.ts              # QQ 入站消息 → agent.followup()
│   ├── outbound.ts             # session/event → QQ sendMarkdown
│   ├── outbound-buffer.ts      # 流式缓冲
│   └── chunker.ts              # Markdown 文本切分
├── session/                    # 会话管理层
│   ├── session-manager.ts      # QQ peer → Agent 映射
│   └── idle-evictor.ts         # 闲置回收
├── model/                      # 模型路由层
│   ├── model-resolver.ts       # 路由解析
│   ├── prefs-store.ts          # per-peer 偏好持久化
│   └── settings-reader.ts      # settings.yaml 只读
├── shared/                     # 共享工具
│   ├── utils.ts                # 通用函数
│   ├── scope.ts                # scope/peer 提取
│   └── send-helper.ts          # 分块发送
├── tools/                      # Agent 工具
│   ├── qq-media.ts             # 媒体发送工具
│   └── qq-card.ts              # 卡片消息工具
├── gateway/
│   ├── bootstrap.ts            # 网关组装
│   ├── interaction.ts          # 按钮交互事件
│   └── middleware-setup.ts     # 中间件编排
├── commands/                   # 斜杠命令
└── typings/                    # 外部模块声明

会话路由

sessionKey: qqbot:${appId}:${scope}:${peerId}，由 SHA-256 确定性派生 SessionId，重启后可恢复。

解析策略：进程内复用 → 持久化恢复 → 全新创建。

设计原则

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

本地开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 开发模式（watch）
pnpm dev

# 用 --patch 方式调试
export QQBOT_APPID="xxx" QQBOT_SECRET="xxx"
npx @deepseek-ai/dsh web --patch /path/to/dsh-qqbot/cordis.dev.yml

License

MIT