mirror of https://github.com/chenhg5/cc-connect.git synced 2026-07-03 12:28:10 +08:00

Files

xiaoheicat 53043e84fd fix(qqbot): address code review feedback and add image/doc support

Code review fixes:
1. Fix msgSeqMap memory leak: replace unbounded sync.Map with TTL-based
   map that evicts entries older than 5 minutes
2. Fix @mention not stripped: add stripAtMention() to parse and remove
   the <@!botid> prefix from group message content
3. Filter empty messages: skip handler call when content is empty after
   stripping (e.g. bare @bot with no text)
4. Fix reconnect race condition: add atomic.Bool guard to prevent
   concurrent reconnectLoop goroutines
5. Add shard field to Identify payload per QQ official docs
6. Cap reconnect attempts at 30 to avoid infinite retry on config errors

New features:
7. Support receiving image attachments from group and C2C messages,
   downloaded into core.ImageAttachment for agent consumption
8. Add docs/qqbot.md setup guide (bilingual EN/ZH)
9. Update README.md and README.zh-CN.md with QQ Bot platform entries
   in support matrix, setup guide table, config examples, and project
   structure

2026-03-08 13:09:48 +08:00

5.5 KiB

Raw Blame History

QQ Bot 官方平台接入指南 / QQ Bot Official Platform Setup Guide

cc-connect 通过 QQ 官方机器人 API v2 连接 QQ，无需第三方适配器，无需公网 IP。

cc-connect connects to QQ via the official QQ Bot Platform API v2. No third-party adapter needed, no public IP required.

与 QQ (OneBot) 的区别 / Difference from QQ (OneBot)

	QQ Bot 官方 (`qqbot`)	QQ OneBot (`qq`)
协议 / Protocol	QQ 官方 API v2	OneBot v11 (第三方)
适配器 / Adapter	不需要 / Not needed	需要 NapCat 等 / Requires NapCat etc.
封号风险 / Ban risk	无 / None (腾讯官方)	有 / Possible
公网 IP / Public IP	不需要 (WebSocket)	不需要 (WebSocket)
注册 / Registration	需要开发者认证 / Developer verification required	仅需 QQ 账号 / QQ account only
群消息 / Group messages	仅 @机器人时 / Only when @mentioned	所有消息 / All messages

架构 / Architecture

QQ Open Platform ←WebSocket→ cc-connect ←→ Agent (Claude Code / etc.)

前置条件 / Prerequisites

访问 QQ 开放平台注册开发者账号 Visit QQ Open Platform and register a developer account
创建机器人应用，获取 AppID 和 AppSecret Create a bot application and obtain AppID and AppSecret
在机器人管理页面配置权限和上线 Configure permissions and publish in the bot management page

步骤 / Steps

1. 创建机器人 / Create Bot

登录 QQ 开放平台 Log in to QQ Open Platform
点击 创建机器人 → 填写基本信息 Click Create Bot → fill in basic information
在 开发 → 开发设置 中获取 AppID 和 AppSecret Get AppID and AppSecret from Development → Development Settings

2. 配置 cc-connect / Configure cc-connect

在 config.toml 中添加 QQ Bot 平台 / Add QQ Bot platform to config.toml:

[[projects.platforms]]
type = "qqbot"

[projects.platforms.options]
app_id = "your-app-id"           # 机器人 AppID
app_secret = "your-app-secret"   # 机器人 AppSecret
sandbox = false                  # 使用沙箱环境（测试用）/ Use sandbox (for testing)
allow_from = "*"                 # 允许的用户 openid，"*" 表示所有 / Allowed user openids, "*" for all

配置项说明 / Configuration options:

参数 / Option	必填 / Required	说明 / Description
`app_id`	✅	机器人 AppID / Bot AppID
`app_secret`	✅	机器人 AppSecret / Bot AppSecret
`sandbox`	❌	使用沙箱 API（默认 false）/ Use sandbox API (default false)
`allow_from`	❌	允许的用户 openid 列表或 `""`（默认允许所有）/ Allowed user openids or `""`
`intents`	❌	自定义事件意图位掩码 / Custom intents bitmask (advanced)

3. 启动 / Start

cc-connect

看到如下日志表示连接成功 / You should see:

qqbot: connected to QQ Bot gateway   sandbox=false
qqbot: gateway READY                 session_id=...

现在可以在 QQ 群聊中 @机器人或私聊机器人了！ Now you can @mention the bot in group chats or send private messages!

群聊使用 / Group Chat

在群聊中，机器人仅在被 @提及时收到消息。这是 QQ 官方 API 的限制。

In group chats, the bot only receives messages when @mentioned. This is a limitation of the official QQ Bot API.

每个用户在每个群中拥有独立的会话。 Each user gets an independent session per group.

私聊 / Private Messages (C2C)

支持一对一私聊消息，无需 @提及。 One-on-one private messages are supported without @mention.

支持的消息类型 / Supported Message Types

类型 / Type	接收 / Receive	发送 / Send
文字 / Text	✅	✅
图片 / Image	✅	❌
语音 / Voice	❌	❌
@提及 / @mention	✅ (自动剥离)	—

常见问题 / FAQ

Q: 连接失败？/ Connection failed?

确认 app_id 和 app_secret 是否正确 / Verify app_id and app_secret are correct
检查网络是否能访问 api.sgroup.qq.com / Check network access to api.sgroup.qq.com
如果使用沙箱环境，确认 sandbox = true / If using sandbox, set sandbox = true

Q: 收不到群消息？/ Not receiving group messages?

群消息仅在 @机器人时触发 / Group messages require @mention
确认机器人已被添加到群中 / Verify the bot has been added to the group
检查 allow_from 配置 / Check allow_from configuration

Q: 提示 token 获取失败？/ Token acquisition failed?

确认 app_secret 正确 / Verify app_secret is correct
检查机器人是否已上线（未上线只能使用沙箱）/ Check if the bot is published (unpublished bots can only use sandbox)

Q: 断线重连？/ Reconnection?

cc-connect 内置自动重连机制，断线后会自动尝试恢复（最多 30 次）
cc-connect has built-in automatic reconnection with resume support (up to 30 attempts)

沙箱环境 / Sandbox

开发测试时可以使用沙箱环境，设置 sandbox = true。沙箱环境使用独立的 API 端点 (sandbox.api.sgroup.qq.com)，不影响生产环境。

For development and testing, set sandbox = true. The sandbox uses a separate API endpoint (sandbox.api.sgroup.qq.com) and doesn't affect production.

5.5 KiB Raw Blame History Unescape Escape