{"_id":"@agentor/chat-qq","_rev":"6-5c9b29f81de2df4e25899cdf7496744f","name":"@agentor/chat-qq","dist-tags":{"edge":"0.1.1","latest":"0.1.1"},"versions":{"0.0.1":{"name":"@agentor/chat-qq","version":"0.0.1","keywords":["QQ机器人","agentor","bot","chat-adapter","qq","qqbot","websocket"],"author":{"url":"https://www.demomacro.com/","name":"Demo Macro","email":"abc@imst.xyz"},"license":"MIT","_id":"@agentor/chat-qq@0.0.1","maintainers":[{"name":"demomacro","email":"abc@imst.xyz"}],"homepage":"https://github.com/DemoMacro/agentor#readme","bugs":{"url":"https://github.com/DemoMacro/agentor/issues"},"dist":{"shasum":"9909429e51f9cc94e4b2495380b723c13d0aae44","tarball":"https://registry.npmjs.org/@agentor/chat-qq/-/chat-qq-0.0.1.tgz","fileCount":5,"integrity":"sha512-RWZXhlKwnAf59fYNf40NEEUoX5Edg1lOhSeRum+X0FX32cAx+s5t3SOm0ngcZ03Zp+c+6bDEW8BV8Rye2TkYcw==","signatures":[{"sig":"MEUCIQCDtyL2jxL798YT4aSC6gwc4BCJ6My1A4aPmKlY+lvOugIgV8YPu4HkbjuplzFwc30dRJpM1wf3oKF5+SPOZsCPFeM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":294664},"main":"dist/index.mjs","type":"module","_from":"file:agentor-chat-qq-0.0.1.tgz","types":"dist/index.d.mts","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"dev":"basis build --stub","build":"vp pack"},"_npmUser":{"name":"demomacro","email":"abc@imst.xyz"},"_resolved":"C:\\Users\\abc\\AppData\\Local\\Temp\\b46d13e0d4f18bd1ada7d72de5d51f31\\agentor-chat-qq-0.0.1.tgz","_integrity":"sha512-RWZXhlKwnAf59fYNf40NEEUoX5Edg1lOhSeRum+X0FX32cAx+s5t3SOm0ngcZ03Zp+c+6bDEW8BV8Rye2TkYcw==","repository":{"url":"git+https://github.com/DemoMacro/agentor.git","type":"git"},"_npmVersion":"11.6.2","description":"QQ Bot 官方 API 适配器，支持 WebSocket 长连接和 Webhook 回调两种模式","directories":{},"_nodeVersion":"24.11.1","dependencies":{"@chat-adapter/shared":"4.29.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/chat-qq_0.0.1_1779267798601_0.4265052771263431","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@agentor/chat-qq","version":"0.1.0","keywords":["QQ机器人","agentor","bot","chat-adapter","chat-sdk","qq","qqbot","websocket"],"author":{"url":"https://www.demomacro.com/","name":"Demo Macro","email":"abc@imst.xyz"},"license":"MIT","_id":"@agentor/chat-qq@0.1.0","maintainers":[{"name":"demomacro","email":"abc@imst.xyz"}],"homepage":"https://github.com/DemoMacro/agentor#readme","bugs":{"url":"https://github.com/DemoMacro/agentor/issues"},"dist":{"shasum":"84ef0684e10ea698181d1428f09f50c272d190e4","tarball":"https://registry.npmjs.org/@agentor/chat-qq/-/chat-qq-0.1.0.tgz","fileCount":6,"integrity":"sha512-6kWV9YqkhagYlLjMeMcI+jpBRsN5ltJJU/tNf8JEOjpQztuFfDqzBBvgxywmtjctW4T+Pa5aE5unUXHywysmHw==","signatures":[{"sig":"MEYCIQCJRjt4LeO4yl8wBTcddJF+c1RB2Eno1Mltmmb94hMfEQIhAO8gqwAYdr2cJmAC7bWqZWXDkbMyTEhz2ORy8iLEI1yC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38908},"main":"dist/index.mjs","type":"module","_from":"file:agentor-chat-qq-0.1.0.tgz","types":"dist/index.d.mts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"dev":"basis build --stub","test":"vp test run","build":"vp pack","test:watch":"vp test","test:coverage":"vp test run --coverage"},"_npmUser":{"name":"demomacro","email":"abc@imst.xyz"},"_resolved":"C:\\Users\\abc\\AppData\\Local\\Temp\\875e9863068a179f8f139c3a6000b0cb\\agentor-chat-qq-0.1.0.tgz","_integrity":"sha512-6kWV9YqkhagYlLjMeMcI+jpBRsN5ltJJU/tNf8JEOjpQztuFfDqzBBvgxywmtjctW4T+Pa5aE5unUXHywysmHw==","repository":{"url":"git+https://github.com/DemoMacro/agentor.git","type":"git"},"_npmVersion":"11.9.0","description":"QQ Bot 官方 API 适配器，支持 WebSocket 长连接和 Webhook 回调两种模式","directories":{},"_nodeVersion":"24.14.0","dependencies":{"@chat-adapter/shared":"4.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"peerDependencies":{"chat":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/chat-qq_0.1.0_1779386912164_0.18556790865532324","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentor/chat-qq","version":"0.1.1","keywords":["QQ机器人","agentor","bot","chat-adapter","chat-sdk","qq","qqbot","websocket"],"author":{"url":"https://www.demomacro.com/","name":"Demo Macro","email":"abc@imst.xyz"},"license":"MIT","_id":"@agentor/chat-qq@0.1.1","maintainers":[{"name":"demomacro","email":"abc@imst.xyz"}],"homepage":"https://github.com/DemoMacro/agentor#readme","bugs":{"url":"https://github.com/DemoMacro/agentor/issues"},"dist":{"shasum":"f3329572df270447fe316660d2c5dd22c964bc64","tarball":"https://registry.npmjs.org/@agentor/chat-qq/-/chat-qq-0.1.1.tgz","fileCount":6,"integrity":"sha512-hFthIvH7wP2eU+yal2QpqA3LOEbSL/wacm05pOqlPmzexoe+FJBr4LwjpNiOmmMbr74BFgG+RYZflDOA04T+Cw==","signatures":[{"sig":"MEUCIQCMOYVHVVAZbhulwNLXAgwjILYhs6EyAjxQQTTvZpKhjgIgMsfXzW9+45StjxCugIfzxBgDJr/J8ab9ar1ID6YHQK4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39345},"main":"dist/index.mjs","type":"module","_from":"file:agentor-chat-qq-0.1.1.tgz","types":"dist/index.d.mts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.mts","import":"./dist/index.mjs"}},"scripts":{"dev":"basis build --stub","test":"vp test run","build":"vp pack","test:watch":"vp test","test:coverage":"vp test run --coverage"},"_npmUser":{"name":"demomacro","email":"abc@imst.xyz"},"_resolved":"C:\\Users\\abc\\AppData\\Local\\Temp\\05bf44643a1ca0df27093ec99642d7fa\\agentor-chat-qq-0.1.1.tgz","_integrity":"sha512-hFthIvH7wP2eU+yal2QpqA3LOEbSL/wacm05pOqlPmzexoe+FJBr4LwjpNiOmmMbr74BFgG+RYZflDOA04T+Cw==","repository":{"url":"git+https://github.com/DemoMacro/agentor.git","type":"git"},"_npmVersion":"11.16.0","description":"QQ Bot 官方 API 适配器，支持 WebSocket 长连接和 Webhook 回调两种模式","directories":{},"_nodeVersion":"24.18.0","dependencies":{"@chat-adapter/shared":"4.35.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"chat":"4.35.0"},"peerDependencies":{"chat":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/chat-qq_0.1.1_1785202814002_0.2720156954389952","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-20T09:03:18.473Z","modified":"2026-07-28T01:40:18.750Z","0.0.1":"2026-05-20T09:03:18.754Z","0.1.0":"2026-05-21T18:08:32.322Z","0.1.1":"2026-07-28T01:40:14.163Z"},"bugs":{"url":"https://github.com/DemoMacro/agentor/issues"},"author":{"url":"https://www.demomacro.com/","name":"Demo Macro","email":"abc@imst.xyz"},"license":"MIT","homepage":"https://github.com/DemoMacro/agentor#readme","keywords":["QQ机器人","agentor","bot","chat-adapter","chat-sdk","qq","qqbot","websocket"],"repository":{"url":"git+https://github.com/DemoMacro/agentor.git","type":"git"},"description":"QQ Bot 官方 API 适配器，支持 WebSocket 长连接和 Webhook 回调两种模式","maintainers":[{"name":"demomacro","email":"abc@imst.xyz"}],"readme":"# @agentor/chat-qq\r\n\r\n[![npm version](https://img.shields.io/npm/v/@agentor/chat-qq)](https://www.npmjs.com/package/@agentor/chat-qq)\r\n[![npm downloads](https://img.shields.io/npm/dm/@agentor/chat-qq)](https://www.npmjs.com/package/@agentor/chat-qq)\r\n[![npm license](https://img.shields.io/npm/l/@agentor/chat-qq)](https://www.npmjs.com/package/@agentor/chat-qq)\r\n\r\n[English](./README.md) | **[中文](./README.zh-CN.md)**\r\n\r\n> [Chat SDK](https://github.com/DemoMacro/agentor) 适配器，用于 [QQ Bot (QQ机器人)](https://bot.q.qq.com/) 消息集成。\r\n\r\n## 功能特性\r\n\r\n- **WebSocket 长连接** — 直连 QQ Bot Gateway，无需公网端点\r\n- **Webhook (回调 URL)** — 通过 HTTP 回调接收事件，支持 Ed25519 签名验证\r\n- **多场景支持** — QQ 单聊 (C2C)、QQ 群聊、文字子频道、频道私信\r\n- **富媒体支持** — 图片、视频、语音、文件的上传与发送\r\n- **自动重连** — 指数退避重连 + Session 恢复 (Resume)\r\n\r\n> **注意：** 成功配置 HTTPS 回调地址之后，WebSocket 长连接模式将不再支持，两者互斥。\r\n\r\n## 安装\r\n\r\n```bash\r\n# Install with npm\r\nnpm install chat @agentor/chat-qq\r\n\r\n# Install with yarn\r\nyarn add chat @agentor/chat-qq\r\n\r\n# Install with pnpm\r\npnpm add chat @agentor/chat-qq\r\n```\r\n\r\n## 快速开始\r\n\r\n### WebSocket 长连接模式\r\n\r\n通过 WebSocket 直连 QQ Bot 服务，无需公网端点：\r\n\r\n```typescript\r\nimport { createQQBotAdapter } from \"@agentor/chat-qq\";\r\n\r\nconst adapter = createQQBotAdapter({\r\n  appId: process.env.QQ_BOT_APP_ID!,\r\n  clientSecret: process.env.QQ_BOT_CLIENT_SECRET!,\r\n});\r\n\r\nawait adapter.initialize({\r\n  processMessage: async (_adapter, threadId, factory) => {\r\n    const message = await factory();\r\n    await adapter.postMessage(threadId, message.text);\r\n  },\r\n});\r\n\r\n// 断开连接\r\nawait adapter.disconnect();\r\n```\r\n\r\n### Webhook 回调模式\r\n\r\n通过 HTTP 回调接收和回复消息，需要公网可达的端点：\r\n\r\n```typescript\r\nimport { createQQBotAdapter } from \"@agentor/chat-qq\";\r\nimport { H3, fromWebHandler, serve } from \"h3\";\r\n\r\nconst adapter = createQQBotAdapter({\r\n  mode: \"callback\",\r\n  appId: process.env.QQ_BOT_APP_ID!,\r\n  clientSecret: process.env.QQ_BOT_CLIENT_SECRET!,\r\n});\r\n\r\nawait adapter.initialize({\r\n  processMessage: async (_adapter, threadId, factory) => {\r\n    const message = await factory();\r\n    await adapter.postMessage(threadId, message.text);\r\n  },\r\n});\r\n\r\n// 在 HTTP 服务器中处理回调\r\nconst app = new H3();\r\napp.all(\r\n  \"/webhook\",\r\n  fromWebHandler((req) => adapter.handleWebhook(req)),\r\n);\r\nserve(app, { port: 3000 });\r\n```\r\n\r\n## 环境变量\r\n\r\n| 变量名                 | 必填 | 说明              |\r\n| ---------------------- | ---- | ----------------- |\r\n| `QQ_BOT_APP_ID`        | 是   | QQ Bot 应用 ID    |\r\n| `QQ_BOT_CLIENT_SECRET` | 是   | QQ Bot 客户端密钥 |\r\n\r\n## 配置项\r\n\r\n| 选项           | 类型                        | 默认值                                         | 说明                              |\r\n| -------------- | --------------------------- | ---------------------------------------------- | --------------------------------- |\r\n| `mode`         | `\"callback\" \\| \"websocket\"` | `\"websocket\"`                                  | 连接模式                          |\r\n| `appId`        | `string`                    | —                                              | 应用 ID (必填)                    |\r\n| `clientSecret` | `string`                    | —                                              | 客户端密钥 (必填)                 |\r\n| `intents`      | `number`                    | `PUBLIC_GUILD_MESSAGES \\| GROUP_AND_C2C_EVENT` | 订阅的事件 Intent 位掩码          |\r\n| `sandbox`      | `boolean`                   | `false`                                        | 是否使用沙箱环境 (websocket 模式) |\r\n| `userName`     | `string`                    | `\"QQ Bot\"`                                     | 机器人显示名称                    |\r\n| `wsUrl`        | `string`                    | QQ Bot 默认                                    | WebSocket 网关地址                |\r\n| `WebSocket`    | `typeof WebSocket`          | `globalThis.WebSocket`                         | 自定义 WebSocket 类               |\r\n| `fetch`        | `typeof fetch`              | `globalThis.fetch`                             | 自定义 fetch 函数                 |\r\n\r\n## 平台配置\r\n\r\n1. 登录 [QQ 开放平台](https://q.qq.com/)\r\n2. 创建机器人应用，获取 App ID 和 Client Secret\r\n3. WebSocket 模式：无需额外配置，直接连接\r\n4. Webhook 模式：在应用详情中配置 HTTPS 回调地址\r\n   - 配置回调地址后，WebSocket 模式将不再可用（两者互斥）\r\n\r\n## 消息类型支持\r\n\r\n### 接收消息\r\n\r\n| 消息类型 | WebSocket | Webhook |\r\n| -------- | --------- | ------- |\r\n| 文本     | ✅        | ✅      |\r\n| 图片     | ✅        | ✅      |\r\n| 视频     | ✅        | ✅      |\r\n| 语音     | ✅        | ✅      |\r\n| 文件     | ✅        | ✅      |\r\n\r\n### 发送消息\r\n\r\n| 消息类型     | C2C 单聊 | 群聊 | 文字子频道 | 频道私信 |\r\n| ------------ | -------- | ---- | ---------- | -------- |\r\n| 文本         | ✅       | ✅   | ✅         | ✅       |\r\n| 图片         | ✅       | ✅   | ✅         | ✅       |\r\n| 视频         | ✅       | ✅   | ✅         | ✅       |\r\n| 语音         | ✅       | ✅   | —          | —        |\r\n| 文件         | ✅       | —    | —          | —        |\r\n| Markdown     | ✅       | ✅   | ✅         | ✅       |\r\n| 富媒体 (URL) | ✅       | ✅   | ✅         | ✅       |\r\n\r\n> 群聊场景的文件上传 (file_type=4) 暂不开放。文字子频道和频道私信无独立的上传接口，但支持通过 `msg_type: 7` + `media` 发送图片和视频。\r\n\r\n## 媒体文件处理\r\n\r\n`postMessage` 会自动处理媒体上传流程：\r\n\r\n- **本地文件** (`FileUpload`)：先转 base64 上传获取 `file_info`，再发送富媒体消息\r\n- **URL 附件** (`Attachment` with URL)：先通过 URL 上传获取 `file_info`，再发送富媒体消息\r\n- 不支持的场景会自动降级为文本消息\r\n\r\n```typescript\r\n// 发送本地文件\r\nawait adapter.postMessage(threadId, {\r\n  text: \"文档\",\r\n  files: [{ data: buffer, filename: \"report.xlsx\", mimeType: \"application/vnd.ms-excel\" }],\r\n});\r\n\r\n// 转发收到的图片\r\nawait adapter.postMessage(threadId, {\r\n  markdown: message.text || \" \",\r\n  attachments: message.attachments,\r\n});\r\n```\r\n\r\n## 安全\r\n\r\nWebhook 模式使用 Ed25519 签名验证：\r\n\r\n- **回调地址验证** (OpCode 13)：用私钥签名 `event_ts + plain_token`\r\n- **事件推送验证** (OpCode 0)：用公钥验证 `X-Signature-Ed25519` 请求头\r\n\r\n```typescript\r\nimport { signCallbackValidation, verifyEventSignature } from \"@agentor/chat-qq\";\r\n\r\n// 回调地址验证\r\nconst signature = signCallbackValidation(clientSecret, plainToken, eventTs);\r\n\r\n// 事件签名验证\r\nconst valid = verifyEventSignature(clientSecret, signatureHex, timestamp, body);\r\n```\r\n\r\n## 不支持的操作\r\n\r\n以下操作会抛出 `NotImplementedError`：\r\n\r\n- `editMessage` — 不支持\r\n- `deleteMessage` — 不支持\r\n- `fetchMessages` / `fetchThread` — 不支持\r\n- `addReaction` / `removeReaction` — 不支持\r\n\r\n## License\r\n\r\nMIT © [Demo Macro](https://www.demomacro.com/)\r\n","readmeFilename":"README.zh-CN.md"}