初始化仓库

2026-06-02 23:14:41 +08:00
commit 0bc3f02670
520 changed files with 191097 additions and 0 deletions
@@ -0,0 +1,136 @@
+# QQ Bot 官方平台接入指南 / QQ Bot Official Platform Setup Guide
+
+cc-connect 通过 [QQ 官方机器人 API v2](https://bot.q.qq.com/wiki/) 连接 QQ，无需第三方适配器，无需公网 IP。
+
+cc-connect connects to QQ via the [official QQ Bot Platform API v2](https://bot.q.qq.com/wiki/). 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
+
+1. 访问 [QQ 开放平台](https://q.qq.com) 注册开发者账号
+   Visit [QQ Open Platform](https://q.qq.com) and register a developer account
+
+2. 创建机器人应用，获取 **AppID** 和 **AppSecret**
+   Create a bot application and obtain **AppID** and **AppSecret**
+
+3. 在机器人管理页面配置权限和上线
+   Configure permissions and publish in the bot management page
+
+## 步骤 / Steps
+
+### 1. 创建机器人 / Create Bot
+
+1. 登录 [QQ 开放平台](https://q.qq.com)
+   Log in to [QQ Open Platform](https://q.qq.com)
+
+2. 点击 **创建机器人** → 填写基本信息
+   Click **Create Bot** → fill in basic information
+
+3. 在 **开发 → 开发设置** 中获取 `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`:
+
+```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
+
+```bash
+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.