{"_id":"@brycehuang/aibot-node-sdk","_rev":"5-380b68980a064943ea786a7d77e1ad05","name":"@brycehuang/aibot-node-sdk","dist-tags":{"latest":"1.0.9"},"versions":{"1.0.6":{"name":"@brycehuang/aibot-node-sdk","version":"1.0.6","keywords":["wecom","wxwork","bot","aibot","websocket"],"author":"","license":"MIT","_id":"@brycehuang/aibot-node-sdk@1.0.6","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"homepage":"https://github.com/WecomTeam/aibot-node-sdk#readme","bugs":{"url":"https://github.com/WecomTeam/aibot-node-sdk/issues"},"dist":{"shasum":"4ff6b6b7eb5e5a2d3478dafc6697ed1f3e035c05","tarball":"https://registry.npmjs.org/@brycehuang/aibot-node-sdk/-/aibot-node-sdk-1.0.6.tgz","fileCount":20,"integrity":"sha512-Xn4Suuf2kKJB1sTVXmNZFJf10juosn5o3JYwklyF2SCJjb2amV2P3dsvTPervCO32B0FnEFUxtrqE+vqXE0vpQ==","signatures":[{"sig":"MEYCIQCTfWFkFvfVAxhklcM1+3FBTPVSGyHb6Bnki1TlQq2kYgIhAKLI5yX5jK9hyVEqWoX0uaY3SFixkmvmN1QvA8he3EBi","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":762142},"main":"dist/index.cjs.js","types":"dist/index.d.ts","module":"dist/index.esm.js","gitHead":"59a39b94b54a1b0107fc10d556c019baa822db46","scripts":{"dev":"rollup -c -w","test":"vitest run","build":"rollup -c","clean":"rm -rf dist","example":"ts-node examples/basic.ts","release":"node scripts/publish-all.mjs","prebuild":"npm run clean","release:dry":"node scripts/publish-all.mjs --dry-run"},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"repository":{"url":"git+https://github.com/WecomTeam/aibot-node-sdk.git","type":"git"},"_npmVersion":"11.12.1","description":"企业微信智能机器人 Node.js SDK - WebSocket 长连接通道","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","axios":"^1.6.7","eventemitter3":"^5.0.1","proxy-from-env":"^1.1.0","http-proxy-agent":"^7.0.0","https-proxy-agent":"^7.0.2"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.6.2","rollup":"^4.59.0","vitest":"^4.1.2","ts-node":"^10.9.2","@types/ws":"^8.5.10","typescript":"^5.3.3","@types/node":"^20.11.16","rollup-plugin-dts":"^6.1.0","@rollup/plugin-json":"^6.1.0","@types/proxy-from-env":"^1.0.4","@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3"},"_npmOperationalInternal":{"tmp":"tmp/aibot-node-sdk_1.0.6_1777373167246_0.2911673425656536","host":"s3://npm-registry-packages-npm-production"}},"1.0.8":{"name":"@brycehuang/aibot-node-sdk","version":"1.0.8","keywords":["wecom","wxwork","bot","aibot","websocket"],"author":"","license":"MIT","_id":"@brycehuang/aibot-node-sdk@1.0.8","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"homepage":"https://github.com/WecomTeam/aibot-node-sdk#readme","bugs":{"url":"https://github.com/WecomTeam/aibot-node-sdk/issues"},"dist":{"shasum":"17a2370c4dee7fe9b6880ead71fee261c407a646","tarball":"https://registry.npmjs.org/@brycehuang/aibot-node-sdk/-/aibot-node-sdk-1.0.8.tgz","fileCount":20,"integrity":"sha512-r1ZEKqgrFE0UEjclLBDEZexMFBWv6VQBapkqQRhjzWpltvJgI3lWGwUIMDXNLkcdYj+VPByO9Hyq25U4nfvscA==","signatures":[{"sig":"MEYCIQC9ckCs6SQLPommLhwIy9OluF9goCowbMXDCIsJDgv5NwIhAJ6MS7B+o6zJ0O40T6PmkTSZurffzdvQGEk/ie4RDcEd","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":762142},"main":"dist/index.cjs.js","types":"dist/index.d.ts","module":"dist/index.esm.js","gitHead":"59a39b94b54a1b0107fc10d556c019baa822db46","scripts":{"dev":"rollup -c -w","test":"vitest run","build":"rollup -c","clean":"rm -rf dist","example":"ts-node examples/basic.ts","release":"node scripts/publish-all.mjs","prebuild":"npm run clean","release:dry":"node scripts/publish-all.mjs --dry-run"},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"repository":{"url":"git+https://github.com/WecomTeam/aibot-node-sdk.git","type":"git"},"_npmVersion":"11.12.1","description":"企业微信智能机器人 Node.js SDK - WebSocket 长连接通道","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.16.0","axios":"^1.6.7","eventemitter3":"^5.0.1","proxy-from-env":"^1.1.0","http-proxy-agent":"^7.0.0","https-proxy-agent":"^7.0.2"},"_hasShrinkwrap":false,"devDependencies":{"tslib":"^2.6.2","rollup":"^4.59.0","vitest":"^4.1.2","ts-node":"^10.9.2","@types/ws":"^8.5.10","typescript":"^5.3.3","@types/node":"^20.11.16","rollup-plugin-dts":"^6.1.0","@rollup/plugin-json":"^6.1.0","@types/proxy-from-env":"^1.0.4","@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-typescript":"^11.1.6","@rollup/plugin-node-resolve":"^15.2.3"},"_npmOperationalInternal":{"tmp":"tmp/aibot-node-sdk_1.0.8_1777373550926_0.861118198879105","host":"s3://npm-registry-packages-npm-production"}},"1.0.9":{"name":"@brycehuang/aibot-node-sdk","version":"1.0.9","description":"企业微信智能机器人 Node.js SDK - WebSocket 长连接通道","main":"dist/index.cjs.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"rollup -c","dev":"rollup -c -w","clean":"rm -rf dist","prebuild":"npm run clean","release":"node scripts/publish-all.mjs","release:dry":"node scripts/publish-all.mjs --dry-run","example":"ts-node examples/basic.ts","test":"vitest run"},"keywords":["wecom","wxwork","bot","aibot","websocket"],"author":"","license":"MIT","repository":{"type":"git","url":"git+https://github.com/WecomTeam/aibot-node-sdk.git"},"homepage":"https://github.com/WecomTeam/aibot-node-sdk#readme","bugs":{"url":"https://github.com/WecomTeam/aibot-node-sdk/issues"},"dependencies":{"axios":"^1.6.7","eventemitter3":"^5.0.1","http-proxy-agent":"^7.0.0","https-proxy-agent":"^7.0.2","proxy-from-env":"^1.1.0","ws":"^8.16.0"},"devDependencies":{"@types/proxy-from-env":"^1.0.4","@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-json":"^6.1.0","@rollup/plugin-node-resolve":"^15.2.3","@rollup/plugin-typescript":"^11.1.6","@types/node":"^20.11.16","@types/ws":"^8.5.10","rollup":"^4.59.0","rollup-plugin-dts":"^6.1.0","ts-node":"^10.9.2","tslib":"^2.6.2","typescript":"^5.3.3","vitest":"^4.1.2"},"gitHead":"59a39b94b54a1b0107fc10d556c019baa822db46","_id":"@brycehuang/aibot-node-sdk@1.0.9","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-oBEOwZyd9Uyj9oOySTWqsmZrQeGmKZxaDndiwZk521+73qlqXwgaJ1rZ5ozjYukSKVkK1vnhk7t5pspdVxIdJA==","shasum":"16aaca97138082ab2fe357125cd04c898901ecbc","tarball":"https://registry.npmjs.org/@brycehuang/aibot-node-sdk/-/aibot-node-sdk-1.0.9.tgz","fileCount":21,"unpackedSize":840952,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAHHhOzpBwEEIxz/utLYIcidSqvQTPNCLuOe3hAWNX72AiEA4gpq53oA5UY7zNNqTNKWTcvSX9/JaLgIbTh/luEp0FI="}]},"_npmUser":{"name":"brycehuang","email":"cherbini@qq.com"},"directories":{},"maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aibot-node-sdk_1.0.9_1777373866178_0.3722828499939619"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-28T10:46:07.156Z","modified":"2026-04-28T10:57:46.984Z","1.0.6":"2026-04-28T10:46:07.410Z","1.0.7":"2026-04-28T10:50:18.926Z","1.0.8":"2026-04-28T10:52:31.124Z","1.0.9":"2026-04-28T10:57:46.867Z"},"bugs":{"url":"https://github.com/WecomTeam/aibot-node-sdk/issues"},"license":"MIT","homepage":"https://github.com/WecomTeam/aibot-node-sdk#readme","keywords":["wecom","wxwork","bot","aibot","websocket"],"repository":{"type":"git","url":"git+https://github.com/WecomTeam/aibot-node-sdk.git"},"description":"企业微信智能机器人 Node.js SDK - WebSocket 长连接通道","maintainers":[{"name":"brycehuang","email":"cherbini@qq.com"}],"readme":"# @wecom/aibot-node-sdk\n\n企业微信智能机器人 Node.js SDK —— 基于 WebSocket 长连接通道，提供消息收发、流式回复、模板卡片、事件回调、文件下载解密、媒体素材上传等核心能力。\n\n## ✨ 特性\n\n- 🔗 **WebSocket 长连接** — 基于 `wss://openws.work.weixin.qq.com` 内置默认地址，开箱即用【注： 私有部署企业需要在企业管理端查看该长连接地址】\n- 🔐 **自动认证** — 连接建立后自动发送认证帧（botId + secret）\n- 💓 **心跳保活** — 自动维护心跳，连续未收到 ack 时自动判定连接异常\n- 🔄 **断线重连** — 指数退避重连策略（1s → 2s → 4s → ... → 30s 上限），支持自定义最大重连次数\n- 📨 **消息分发** — 自动解析消息类型并触发对应事件（text / image / mixed / voice / file）\n- 🌊 **流式回复** — 内置流式回复方法，支持 Markdown 和图文混排\n- 🃏 **模板卡片** — 支持回复模板卡片消息、流式+卡片组合回复、更新卡片\n- 📤 **主动推送** — 支持向指定会话主动发送 Markdown、模板卡片或媒体消息，无需依赖回调帧\n- 📡 **事件回调** — 支持进入会话、模板卡片按钮点击、用户反馈等事件\n- ⏩ **串行回复队列** — 同一 req_id 的回复消息串行发送，自动等待回执\n- 🔒 **文件下载解密** — 内置 AES-256-CBC 文件解密，每个图片/文件消息自带独立的 aeskey\n- 📎 **媒体素材上传** — 支持分片上传临时素材（file/image/voice/video），自动管理并发与重试\n- 🪵 **可插拔日志** — 支持自定义 Logger，内置带时间戳的 DefaultLogger\n- 📦 **双模块格式** — 同时输出 CJS / ESM，附带完整 TypeScript 类型声明\n\n## 📦 安装\n\n```bash\nnpm install @wecom/aibot-node-sdk\n# 或\nyarn add @wecom/aibot-node-sdk\n```\n\n## 🚀 快速开始\n\n```ts\nimport AiBot from '@wecom/aibot-node-sdk';\nimport type { WsFrame } from '@wecom/aibot-node-sdk';\nimport { generateReqId } from '@wecom/aibot-node-sdk';\n\n// 1. 创建客户端实例\nconst wsClient = new AiBot.WSClient({\n  botId: 'your-bot-id',       // 企业微信后台获取的机器人 ID\n  secret: 'your-bot-secret',  // 企业微信后台获取的机器人 Secret\n});\n\n// 2. 建立连接（支持链式调用）\nwsClient.connect();\n\n// 3. 监听认证成功\nwsClient.on('authenticated', () => {\n  console.log('🔐 认证成功');\n});\n\n// 4. 监听文本消息并进行流式回复\nwsClient.on('message.text', (frame: WsFrame) => {\n  const content = frame.body.text?.content;\n  console.log(`收到文本: ${content}`);\n\n  const streamId = generateReqId('stream');\n\n  // 发送流式中间内容\n  wsClient.replyStream(frame, streamId, '正在思考中...', false);\n\n  // 发送最终结果\n  setTimeout(() => {\n    wsClient.replyStream(frame, streamId, `你好！你说的是: \"${content}\"`, true);\n  }, 1000);\n});\n\n// 5. 监听进入会话事件（发送欢迎语）\nwsClient.on('event.enter_chat', (frame: WsFrame) => {\n  wsClient.replyWelcome(frame, {\n    msgtype: 'text',\n    text: { content: '您好！我是智能助手，有什么可以帮您的吗？' },\n  });\n});\n\n// 6. 优雅退出\nprocess.on('SIGINT', () => {\n  wsClient.disconnect();\n  process.exit(0);\n});\n```\n\n---\n\n## 📖 API 文档\n\n### `WSClient`\n\n核心客户端类，继承自 `EventEmitter`，提供连接管理、消息收发等功能。\n\n#### 构造函数\n\n```ts\nconst wsClient = new WSClient(options: WSClientOptions);\n```\n\n#### 方法一览\n\n| 方法                                                                  | 说明                                                   | 返回值                                           |\n| --------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------ |\n| `connect()`                                                           | 建立 WebSocket 连接，连接后自动认证                    | `this`（支持链式调用）                           |\n| `disconnect()`                                                        | 主动断开连接                                           | `void`                                           |\n| `reply(frame, body, cmd?)`                                            | 通过 WebSocket 通道发送回复消息（通用方法）            | `Promise<WsFrame>`                               |\n| `replyStream(frame, streamId, content, finish?, msgItem?, feedback?)` | 发送流式文本回复（支持 Markdown）                      | `Promise<WsFrame>`                               |\n| `replyWelcome(frame, body)`                                           | 发送欢迎语回复（文本或模板卡片），需 5s 内调用         | `Promise<WsFrame>`                               |\n| `replyTemplateCard(frame, templateCard, feedback?)`                   | 回复模板卡片消息                                       | `Promise<WsFrame>`                               |\n| `replyStreamWithCard(frame, streamId, content, finish?, options?)`    | 流式消息 + 模板卡片组合回复                            | `Promise<WsFrame>`                               |\n| `updateTemplateCard(frame, templateCard, userids?)`                   | 更新模板卡片（响应 template_card_event），需 5s 内调用 | `Promise<WsFrame>`                               |\n| `sendMessage(chatid, body)`                                           | 主动发送消息（Markdown / 模板卡片 / 媒体），无需回调帧 | `Promise<WsFrame>`                               |\n| `uploadMedia(fileBuffer, options)`                                    | 上传临时素材（三步分片上传），返回 `media_id`          | `Promise<UploadMediaFinishResult>`               |\n| `replyMedia(frame, mediaType, mediaId, videoOptions?)`                | 被动回复媒体消息（file/image/voice/video）             | `Promise<WsFrame>`                               |\n| `sendMediaMessage(chatid, mediaType, mediaId, videoOptions?)`         | 主动发送媒体消息                                       | `Promise<WsFrame>`                               |\n| `downloadFile(url, aesKey)`                                           | 下载文件并 AES 解密，返回 Buffer 及文件名              | `Promise<{ buffer: Buffer; filename?: string }>` |\n\n#### 属性\n\n| 属性          | 说明                            | 类型             |\n| ------------- | ------------------------------- | ---------------- |\n| `isConnected` | 当前 WebSocket 连接状态         | `boolean`        |\n| `api`         | 内部 API 客户端实例（高级用途） | `WeComApiClient` |\n\n---\n\n### `replyStream` 详细说明\n\n发送流式文本回复（便捷方法，支持 Markdown）。\n\n```ts\nwsClient.replyStream(\n  frame: WsFrameHeaders, // 收到的原始 WebSocket 帧（透传 req_id），也可直接传完整 WsFrame 对象\n  streamId: string,      // 流式消息 ID（使用 generateReqId('stream') 生成）\n  content: string,       // 回复内容（支持 Markdown），最长 20480 字节\n  finish?: boolean,      // 是否结束流式消息，默认 false\n  msgItem?: ReplyMsgItem[], // 图文混排项（仅 finish=true 时有效，最多 10 个）\n  feedback?: ReplyFeedback, // 反馈信息（仅首次回复时设置）\n);\n```\n\n使用示例：\n\n```ts\nconst streamId = generateReqId('stream');\n\n// 发送流式中间内容\nawait wsClient.replyStream(frame, streamId, '正在处理中...', false);\n\n// 发送最终结果（finish=true 表示结束流）\nawait wsClient.replyStream(frame, streamId, '处理完成！结果是...', true);\n```\n\n---\n\n### `replyWelcome` 详细说明\n\n发送欢迎语回复，需在收到 `event.enter_chat` 事件 **5 秒内**调用，超时将无法发送。\n\n```ts\n// 文本欢迎语\nwsClient.replyWelcome(frame, {\n  msgtype: 'text',\n  text: { content: '欢迎！' },\n});\n\n// 模板卡片欢迎语\nwsClient.replyWelcome(frame, {\n  msgtype: 'template_card',\n  template_card: { card_type: 'text_notice', main_title: { title: '欢迎' } },\n});\n```\n\n---\n\n### `replyTemplateCard` 详细说明\n\n回复模板卡片消息。收到消息回调或进入会话事件后使用。\n\n```ts\nwsClient.replyTemplateCard(\n  frame: WsFrameHeaders,     // 收到的原始 WebSocket 帧\n  templateCard: TemplateCard, // 模板卡片内容\n  feedback?: ReplyFeedback,   // 反馈信息（可选）\n);\n```\n\n---\n\n### `replyStreamWithCard` 详细说明\n\n发送流式消息 + 模板卡片组合回复。首次回复时必须返回 stream 的 id；`template_card` 同一消息只能回复一次。\n\n```ts\nwsClient.replyStreamWithCard(\n  frame: WsFrameHeaders,   // 收到的原始 WebSocket 帧\n  streamId: string,         // 流式消息 ID\n  content: string,          // 回复内容（支持 Markdown）\n  finish?: boolean,         // 是否结束流式消息，默认 false\n  options?: {\n    msgItem?: ReplyMsgItem[];       // 图文混排项（仅 finish=true 时有效）\n    streamFeedback?: ReplyFeedback; // 流式消息反馈信息（首次回复时设置）\n    templateCard?: TemplateCard;    // 模板卡片内容（同一消息只能回复一次）\n    cardFeedback?: ReplyFeedback;   // 模板卡片反馈信息\n  },\n);\n```\n\n使用示例：\n\n```ts\nconst streamId = generateReqId('stream');\n\n// 首次回复：带卡片\nawait wsClient.replyStreamWithCard(frame, streamId, '正在处理...', false, {\n  templateCard: {\n    card_type: 'button_interaction',\n    main_title: { title: '操作面板' },\n    button_list: [{ text: '确认', key: 'confirm' }],\n    task_id: `task_${Date.now()}`,\n  },\n});\n\n// 流式结束\nawait wsClient.replyStreamWithCard(frame, streamId, '处理完成！', true);\n```\n\n---\n\n### `updateTemplateCard` 详细说明\n\n更新模板卡片，需在收到 `event.template_card_event` 事件 **5 秒内**调用。\n\n```ts\nwsClient.updateTemplateCard(\n  frame: WsFrameHeaders,     // 对应事件的 WebSocket 帧（需包含该事件的 req_id）\n  templateCard: TemplateCard, // 模板卡片内容（task_id 需与回调收到的 task_id 一致）\n  userids?: string[],         // 要替换模版卡片消息的 userid 列表，不填则替换所有用户\n);\n```\n\n---\n\n### `sendMessage` 详细说明\n\n主动向指定会话推送消息，无需依赖收到的回调帧。\n\n```ts\nwsClient.sendMessage(\n  chatid: string,  // 会话 ID，单聊填用户的 userid，群聊填对应群聊的 chatid\n  body: SendMarkdownMsgBody | SendTemplateCardMsgBody | SendMediaMsgBody,\n);\n```\n\n使用示例：\n\n```ts\n// 发送 Markdown 消息\nawait wsClient.sendMessage('userid_or_chatid', {\n  msgtype: 'markdown',\n  markdown: { content: '这是一条**主动推送**的消息' },\n});\n\n// 发送模板卡片消息\nawait wsClient.sendMessage('userid_or_chatid', {\n  msgtype: 'template_card',\n  template_card: { card_type: 'text_notice', main_title: { title: '通知' } },\n});\n```\n\n---\n\n### `uploadMedia` 详细说明\n\n通过 WebSocket 长连接执行三步分片上传：`init → chunk × N → finish`。\n\n- 单个分片不超过 **512KB**（Base64 编码前），最多 **100 个**分片（约 50MB 上限）\n- 自动根据分片数调整并发数（1\\~4 分片全并发；5\\~10 分片并发 3；>10 分片并发 2）\n- 单分片上传失败自动重试（最多 2 次）\n\n```ts\nwsClient.uploadMedia(\n  fileBuffer: Buffer,          // 文件 Buffer\n  options: UploadMediaOptions, // { type: WeComMediaType, filename: string }\n): Promise<UploadMediaFinishResult>;  // { type, media_id, created_at }\n```\n\n使用示例：\n\n```ts\nimport fs from 'fs';\n\n// 上传图片\nconst imageBuffer = fs.readFileSync('/path/to/image.png');\nconst result = await wsClient.uploadMedia(imageBuffer, {\n  type: 'image',\n  filename: 'image.png',\n});\nconsole.log(`上传成功，media_id: ${result.media_id}`);\n\n// 使用 media_id 回复图片消息\nawait wsClient.replyMedia(frame, 'image', result.media_id);\n```\n\n---\n\n### `replyMedia` 详细说明\n\n被动回复媒体消息（通过 `aibot_respond_msg` 通道）。\n\n```ts\nwsClient.replyMedia(\n  frame: WsFrameHeaders,    // 收到的原始 WebSocket 帧\n  mediaType: WeComMediaType, // 媒体类型：'file' | 'image' | 'voice' | 'video'\n  mediaId: string,           // 临时素材 media_id（通过 uploadMedia 获取）\n  videoOptions?: {           // 视频消息可选参数（仅 mediaType='video' 时生效）\n    title?: string;\n    description?: string;\n  },\n);\n```\n\n---\n\n### `sendMediaMessage` 详细说明\n\n主动发送媒体消息（通过 `aibot_send_msg` 通道推送）。\n\n```ts\nwsClient.sendMediaMessage(\n  chatid: string,            // 会话 ID\n  mediaType: WeComMediaType, // 媒体类型：'file' | 'image' | 'voice' | 'video'\n  mediaId: string,           // 临时素材 media_id\n  videoOptions?: {           // 视频消息可选参数（仅 mediaType='video' 时生效）\n    title?: string;\n    description?: string;\n  },\n);\n```\n\n---\n\n### `downloadFile` 使用示例\n\n```ts\n// aesKey 取自消息体中的 image.aeskey 或 file.aeskey\nwsClient.on('message.image', async (frame: WsFrame) => {\n  const body = frame.body;\n  const { buffer, filename } = await wsClient.downloadFile(body.image?.url, body.image?.aeskey);\n  console.log(`文件名: ${filename}, 大小: ${buffer.length} bytes`);\n});\n```\n\n---\n\n## ⚙️ 配置选项\n\n`WSClientOptions` 完整配置：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n| --- | --- | --- | --- | --- |\n| `botId` | `string` | ✅ | — | 机器人 ID（企业微信后台获取） |\n| `secret` | `string` | ✅ | — | 机器人 Secret（企业微信后台获取） |\n| `reconnectInterval` | `number` | — | `1000` | 重连基础延迟（毫秒），实际延迟按指数退避递增（1s → 2s → 4s → ... → 30s 上限） |\n| `maxReconnectAttempts` | `number` | — | `10` | 最大重连次数（`-1` 表示无限重连） |\n| `heartbeatInterval` | `number` | — | `30000` | 心跳间隔（毫秒） |\n| `requestTimeout` | `number` | — | `10000` | HTTP 请求超时时间（毫秒） |\n| `wsUrl` | `string` | — | `wss://openws.work.weixin.qq.com` | 自定义 WebSocket 连接地址 |\n| `wsOptions` | `string` | — | `string` | 自签证书地址 |\n| `logger` | `Logger` | — | `DefaultLogger` | 自定义日志实例 |\n\n---\n\n## 📡 事件列表\n\n所有事件均通过 `wsClient.on(event, handler)` 监听：\n\n| 事件                        | 回调参数                       | 说明                                         |\n| --------------------------- | ------------------------------ | -------------------------------------------- |\n| `connected`                 | —                              | WebSocket 连接建立                           |\n| `authenticated`             | —                              | 认证成功                                     |\n| `disconnected`              | `reason: string`               | 连接断开                                     |\n| `reconnecting`              | `attempt: number`              | 正在重连（第 N 次）                          |\n| `error`                     | `error: Error`                 | 发生错误                                     |\n| `message`                   | `frame: WsFrame<BaseMessage>`  | 收到消息（所有类型）                         |\n| `message.text`              | `frame: WsFrame<TextMessage>`  | 收到文本消息                                 |\n| `message.image`             | `frame: WsFrame<ImageMessage>` | 收到图片消息                                 |\n| `message.mixed`             | `frame: WsFrame<MixedMessage>` | 收到图文混排消息                             |\n| `message.voice`             | `frame: WsFrame<VoiceMessage>` | 收到语音消息                                 |\n| `message.file`              | `frame: WsFrame<FileMessage>`  | 收到文件消息                                 |\n| `message.video`             | `frame: WsFrame<VideoMessage>` | 收到视频消息                                 |\n| `event`                     | `frame: WsFrame<EventMessage>` | 收到事件回调（所有事件类型）                 |\n| `event.enter_chat`          | `frame: WsFrame<EventMessage>` | 收到进入会话事件（用户当天首次进入单聊会话） |\n| `event.template_card_event` | `frame: WsFrame<EventMessage>` | 收到模板卡片事件（用户点击卡片按钮）         |\n| `event.feedback_event`      | `frame: WsFrame<EventMessage>` | 收到用户反馈事件                             |\n\n---\n\n## 📋 消息类型\n\nSDK 支持以下消息类型（`MessageType` 枚举）：\n\n| 类型    | 值        | 说明                                                     |\n| ------- | --------- | -------------------------------------------------------- |\n| `Text`  | `'text'`  | 文本消息                                                 |\n| `Image` | `'image'` | 图片消息（URL 已加密，使用消息中的 `image.aeskey` 解密） |\n| `Mixed` | `'mixed'` | 图文混排消息（包含 text / image 子项）                   |\n| `Voice` | `'voice'` | 语音消息（已转文本）                                     |\n| `File`  | `'file'`  | 文件消息（URL 已加密，使用消息中的 `file.aeskey` 解密）  |\n| `Video` | `'video'` | 视频消息（URL 已加密，使用消息中的 `video.aeskey` 解密） |\n\nSDK 支持以下事件类型（`EventType` 枚举）：\n\n| 类型                | 值                      | 说明                                         |\n| ------------------- | ----------------------- | -------------------------------------------- |\n| `EnterChat`         | `'enter_chat'`          | 进入会话事件：用户当天首次进入机器人单聊会话 |\n| `TemplateCardEvent` | `'template_card_event'` | 模板卡片事件：用户点击模板卡片按钮           |\n| `FeedbackEvent`     | `'feedback_event'`      | 用户反馈事件：用户对机器人回复进行反馈       |\n\nSDK 支持以下媒体类型（`WeComMediaType` 类型）：\n\n| 类型 | 值        | 说明 |\n| ---- | --------- | ---- |\n| —    | `'file'`  | 文件 |\n| —    | `'image'` | 图片 |\n| —    | `'voice'` | 语音 |\n| —    | `'video'` | 视频 |\n\n---\n\n## 🃏 模板卡片类型\n\nSDK 支持以下模板卡片类型（`TemplateCardType` 枚举）：\n\n| 类型                  | 值                       | 说明             |\n| --------------------- | ------------------------ | ---------------- |\n| `TextNotice`          | `'text_notice'`          | 文本通知模版卡片 |\n| `NewsNotice`          | `'news_notice'`          | 图文展示模版卡片 |\n| `ButtonInteraction`   | `'button_interaction'`   | 按钮交互模版卡片 |\n| `VoteInteraction`     | `'vote_interaction'`     | 投票选择模版卡片 |\n| `MultipleInteraction` | `'multiple_interaction'` | 多项选择模版卡片 |\n\n---\n\n## 🔀 消息帧结构\n\n### `WsFrame<T>`\n\n```ts\ninterface WsFrame<T = any> {\n  cmd?: string;              // 命令类型\n  headers: {\n    req_id: string;          // 请求 ID（回复时需透传）\n    [key: string]: any;\n  };\n  body?: T;                  // 消息体（泛型，默认 any）\n  errcode?: number;          // 响应错误码\n  errmsg?: string;           // 响应错误信息\n}\n```\n\n### `BaseMessage`（消息体基础结构）\n\n```ts\ninterface BaseMessage {\n  msgid: string;             // 消息唯一标识\n  aibotid: string;           // 机器人 ID\n  chatid?: string;           // 群聊 ID（群聊时返回）\n  chattype: 'single' | 'group';  // 会话类型\n  from: { userid: string };  // 发送者信息\n  create_time?: number;      // 事件产生的时间戳\n  response_url?: string;     // 支持主动回复消息的临时 url\n  msgtype: string;           // 消息类型\n  quote?: QuoteContent;      // 引用消息内容\n}\n```\n\n### `EventMessage`（事件消息结构）\n\n```ts\ninterface EventMessage {\n  msgid: string;             // 本次回调的唯一性标志\n  create_time: number;       // 事件产生的时间戳\n  aibotid: string;           // 智能机器人 ID\n  chatid?: string;           // 会话 ID（仅群聊时返回）\n  chattype?: 'single' | 'group';  // 会话类型\n  from: EventFrom;           // 事件触发者信息（含 userid、corpid?）\n  msgtype: 'event';          // 消息类型，固定为 event\n  event: EventContent;       // 事件内容\n}\n```\n\n---\n\n## 🪵 自定义日志\n\n实现 `Logger` 接口即可自定义日志输出：\n\n```ts\ninterface Logger {\n  debug(message: string, ...args: any[]): void;\n  info(message: string, ...args: any[]): void;\n  warn(message: string, ...args: any[]): void;\n  error(message: string, ...args: any[]): void;\n}\n```\n\n使用示例：\n\n```ts\nconst wsClient = new AiBot.WSClient({\n  botId: 'your-bot-id',\n  secret: 'your-bot-secret',\n  logger: {\n    debug: () => {},  // 静默 debug 日志\n    info: console.log,\n    warn: console.warn,\n    error: console.error,\n  },\n});\n```\n\n私有部署企业使用示例：\n```ts\nconst wsClient = new AiBot.WSClient({\n  botId: 'your-bot-id',\n  secret: 'your-bot-secret',\n  wsUrl: 'your-wsUrl',\n  wsOptions: {\n    ca: fs.readFileSync('your-ca-path'),\n  },\n  logger: {\n    debug: () => {},  // 静默 debug 日志\n    info: console.log,\n    warn: console.warn,\n    error: console.error,\n  },\n});\n```\n\n---\n\n## 🔧 WebSocket 命令协议\n\n以下为 SDK 内部使用的 WebSocket 命令常量（`WsCmd`），了解底层协议有助于高级调试：\n\n| 方向          | 常量                  | 值                          | 说明              |\n| ------------- | --------------------- | --------------------------- | ----------------- |\n| 开发者 → 企微 | `SUBSCRIBE`           | `aibot_subscribe`           | 认证订阅          |\n| 开发者 → 企微 | `HEARTBEAT`           | `ping`                      | 心跳              |\n| 开发者 → 企微 | `RESPONSE`            | `aibot_respond_msg`         | 回复消息          |\n| 开发者 → 企微 | `RESPONSE_WELCOME`    | `aibot_respond_welcome_msg` | 回复欢迎语        |\n| 开发者 → 企微 | `RESPONSE_UPDATE`     | `aibot_respond_update_msg`  | 更新模板卡片      |\n| 开发者 → 企微 | `SEND_MSG`            | `aibot_send_msg`            | 主动发送消息      |\n| 开发者 → 企微 | `UPLOAD_MEDIA_INIT`   | `aibot_upload_media_init`   | 上传素材 - 初始化 |\n| 开发者 → 企微 | `UPLOAD_MEDIA_CHUNK`  | `aibot_upload_media_chunk`  | 上传素材 - 分片   |\n| 开发者 → 企微 | `UPLOAD_MEDIA_FINISH` | `aibot_upload_media_finish` | 上传素材 - 完成   |\n| 企微 → 开发者 | `CALLBACK`            | `aibot_msg_callback`        | 消息推送回调      |\n| 企微 → 开发者 | `EVENT_CALLBACK`      | `aibot_event_callback`      | 事件推送回调      |\n\n---\n\n## 📂 项目结构\n\n```\naibot-node-sdk/\n├── src/\n│   ├── index.ts             # 入口文件，统一导出\n│   ├── client.ts            # WSClient 核心客户端\n│   ├── ws.ts                # WebSocket 长连接管理器\n│   ├── message-handler.ts   # 消息解析与事件分发\n│   ├── api.ts               # HTTP API 客户端（文件下载）\n│   ├── crypto.ts            # AES-256-CBC 文件解密\n│   ├── logger.ts            # 默认日志实现\n│   ├── utils.ts             # 工具方法（generateReqId 等）\n│   └── types/\n│       ├── index.ts          # 类型统一导出\n│       ├── config.ts         # 配置选项类型\n│       ├── event.ts          # 事件映射类型\n│       ├── message.ts        # 消息相关类型\n│       ├── api.ts            # API/WebSocket 帧/模板卡片类型\n│       └── common.ts         # 通用类型（Logger）\n├── examples/\n│   └── basic.ts             # 基础使用示例\n├── package.json\n├── tsconfig.json\n├── rollup.config.mjs        # Rollup 构建配置\n└── yarn.lock\n```\n\n---\n\n## 🧩 完整使用示例\n\n### 流式回复 + 图文混排\n\n```ts\nimport AiBot from '@wecom/aibot-node-sdk';\nimport type { WsFrame, ReplyMsgItem } from '@wecom/aibot-node-sdk';\nimport { generateReqId } from '@wecom/aibot-node-sdk';\nimport { createHash } from 'crypto';\nimport fs from 'fs';\n\nconst wsClient = new AiBot.WSClient({\n  botId: 'your-bot-id',\n  secret: 'your-bot-secret',\n});\n\nwsClient.connect();\n\nwsClient.on('message.text', async (frame: WsFrame) => {\n  const streamId = generateReqId('stream');\n\n  // 流式中间内容\n  await wsClient.replyStream(frame, streamId, '正在生成图文内容...', false);\n\n  // 准备图文混排项（仅 finish=true 时有效）\n  const imageData = fs.readFileSync('/path/to/image.jpg');\n  const base64 = imageData.toString('base64');\n  const md5 = createHash('md5').update(imageData).digest('hex');\n\n  const msgItem: ReplyMsgItem[] = [\n    { msgtype: 'image', image: { base64, md5 } },\n  ];\n\n  // 流式结束，附带图片\n  await wsClient.replyStream(frame, streamId, '这是最终结果', true, msgItem);\n});\n```\n\n### 上传素材 + 回复媒体消息\n\n```ts\nimport AiBot from '@wecom/aibot-node-sdk';\nimport type { WsFrame } from '@wecom/aibot-node-sdk';\nimport fs from 'fs';\n\nconst wsClient = new AiBot.WSClient({\n  botId: 'your-bot-id',\n  secret: 'your-bot-secret',\n});\n\nwsClient.connect();\n\nwsClient.on('message.text', async (frame: WsFrame) => {\n  // 上传文件\n  const fileBuffer = fs.readFileSync('/path/to/document.pdf');\n  const result = await wsClient.uploadMedia(fileBuffer, {\n    type: 'file',\n    filename: 'document.pdf',\n  });\n\n  // 使用 media_id 被动回复文件消息\n  await wsClient.replyMedia(frame, 'file', result.media_id);\n});\n```\n\n### 主动推送消息\n\n```ts\n// 在认证成功后，可以随时主动推送消息\nwsClient.on('authenticated', async () => {\n  // 向指定用户推送 Markdown 消息\n  await wsClient.sendMessage('target_userid', {\n    msgtype: 'markdown',\n    markdown: { content: '# 通知\\n\\n这是一条**主动推送**的消息。' },\n  });\n\n  // 主动推送媒体消息\n  const imageBuffer = fs.readFileSync('/path/to/photo.jpg');\n  const result = await wsClient.uploadMedia(imageBuffer, {\n    type: 'image',\n    filename: 'photo.jpg',\n  });\n  await wsClient.sendMediaMessage('target_userid', 'image', result.media_id);\n});\n```\n\n### 模板卡片交互\n\n```ts\n// 回复带按钮的模板卡片\nwsClient.on('message.text', async (frame: WsFrame) => {\n  await wsClient.replyTemplateCard(frame, {\n    card_type: 'button_interaction',\n    main_title: { title: '请选择操作', desc: '点击下方按钮进行操作' },\n    button_list: [\n      { text: '确认', key: 'btn_confirm', style: 1 },\n      { text: '取消', key: 'btn_cancel', style: 2 },\n    ],\n    task_id: `task_${Date.now()}`,\n  });\n});\n\n// 监听卡片按钮点击事件并更新卡片\nwsClient.on('event.template_card_event', async (frame: WsFrame) => {\n  const eventKey = frame.body.event?.event_key;\n  const taskId = frame.body.event?.task_id;\n\n  await wsClient.updateTemplateCard(frame, {\n    card_type: 'text_notice',\n    main_title: { title: eventKey === 'btn_confirm' ? '已确认 ✅' : '已取消 ❌' },\n    task_id: taskId,\n  });\n});\n```\n\n### 文件下载解密\n\n```ts\nimport fs from 'fs';\nimport path from 'path';\n\n// 处理图片消息\nwsClient.on('message.image', async (frame: WsFrame) => {\n  const body = frame.body;\n  const imageUrl = body.image?.url;\n  if (!imageUrl) return;\n\n  // 使用消息中独立的 aeskey 下载并解密\n  const { buffer, filename } = await wsClient.downloadFile(imageUrl, body.image?.aeskey);\n  const savePath = path.join(__dirname, filename || `image_${Date.now()}.jpg`);\n  fs.writeFileSync(savePath, buffer);\n  console.log(`图片已保存: ${savePath} (${buffer.length} bytes)`);\n});\n\n// 处理文件消息\nwsClient.on('message.file', async (frame: WsFrame) => {\n  const body = frame.body;\n  const fileUrl = body.file?.url;\n  if (!fileUrl) return;\n\n  const { buffer, filename } = await wsClient.downloadFile(fileUrl, body.file?.aeskey);\n  const savePath = path.join(__dirname, filename || `file_${Date.now()}`);\n  fs.writeFileSync(savePath, buffer);\n  console.log(`文件已保存: ${savePath} (${buffer.length} bytes)`);\n});\n```\n\n---\n\n## 🔧 开发\n\n```bash\n# 安装依赖\nyarn install\n\n# 开发模式（监听文件变化）\nyarn dev\n\n# 构建\nyarn build\n\n# 运行示例\nyarn example\n```\n\n---\n\n## 🔗 导出说明\n\nSDK 同时支持默认导出和具名导出：\n\n```ts\n// 默认导出\nimport AiBot from '@wecom/aibot-node-sdk';\nconst wsClient = new AiBot.WSClient({ ... });\n\n// 具名导出\nimport { WSClient, generateReqId } from '@wecom/aibot-node-sdk';\nconst wsClient = new WSClient({ ... });\n\n// 类型导入\nimport type { WsFrame, BaseMessage, TextMessage, TemplateCard } from '@wecom/aibot-node-sdk';\n```\n\n完整导出列表：\n\n| 类别     | 导出项                                                                                                                                                                                                                                                                           |\n| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **类**   | `WSClient`、`WeComApiClient`、`WsConnectionManager`、`MessageHandler`、`DefaultLogger`                                                                                                                                                                                           |\n| **函数** | `generateReqId`、`generateRandomString`、`decryptFile`                                                                                                                                                                                                                           |\n| **枚举** | `MessageType`、`EventType`、`TemplateCardType`、`WsCmd`                                                                                                                                                                                                                          |\n| **类型** | `WSClientOptions`、`WSClientEventMap`、`WsFrame`、`WsFrameHeaders`、`BaseMessage`、`TextMessage`、`ImageMessage`、`MixedMessage`、`VoiceMessage`、`FileMessage`、`VideoMessage`、`EventMessage`、`TemplateCard`、`StreamReplyBody`、`ReplyMsgItem`、`ReplyFeedback`、`Logger` 等 |\n\n---\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md"}