{"_id":"@aluria/wechat-ai-api","_rev":"2-46f44667600e067900674d5c44e59b3f","name":"@aluria/wechat-ai-api","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@aluria/wechat-ai-api","version":"1.0.0","keywords":["wechat","bot","sdk","openclaw-wechat","api","notification"],"author":{"name":"Aluria"},"license":"MIT","_id":"@aluria/wechat-ai-api@1.0.0","maintainers":[{"name":"aluria","email":"wuyijun21@mails.ucas.ac.cn"}],"homepage":"https://github.com/你的用户名/wechat-ai-api#readme","bugs":{"url":"https://github.com/你的用户名/wechat-ai-api/issues"},"dist":{"shasum":"f61abbebb902c752e65d7d80b09d5cdbbd5218d2","tarball":"https://registry.npmjs.org/@aluria/wechat-ai-api/-/wechat-ai-api-1.0.0.tgz","fileCount":6,"integrity":"sha512-aCSZQzYxMg52DseAGWdyA2mKZ1zSmJ7PSb64R+xlhrOmUWGadbfVwzp9lIawenU0ppxxU82Okead3I2QlkgyNA==","signatures":[{"sig":"MEUCIQDYJy9QpvBS6wfQZFYcL3B1Q+u8XorIU9o0aMIdAYVePAIgYMy4jywCeU3QfVLLNmYVLu/4ebV3jSizQjL2hc7QyBI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114870},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","gitHead":"b64e9cc6a81a8ad1a9310db09869a8c377ae5e4a","scripts":{"dev":"tsup --watch","test":"echo \"Error: no test specified\" && exit 1","build":"tsup","prepare":"npm run build"},"_npmUser":{"name":"aluria","email":"wuyijun21@mails.ucas.ac.cn"},"repository":{"url":"git+https://github.com/你的用户名/wechat-ai-api.git","type":"git"},"_npmVersion":"11.10.1","description":"一个优雅、轻量、开箱即用的个人微信通知/机器人 SDK","directories":{},"_nodeVersion":"25.7.0","dependencies":{"silk-wasm":"^3.7.1"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/wechat-ai-api_1.0.0_1774763348449_0.07968223597284263","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aluria/wechat-ai-api","version":"1.0.1","description":"一个优雅、轻量、开箱即用的个人微信通知/机器人 SDK","keywords":["wechat","bot","sdk","openclaw-wechat","api","notification"],"repository":{"type":"git","url":"git+https://github.com/Wu-Yijun/wechat-ai-api.git"},"license":"MIT","author":{"name":"Aluria"},"type":"module","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"dev":"tsup --watch","build":"tsup","prepare":"npm run build","test":"echo \"Error: no test specified\" && exit 1"},"dependencies":{"silk-wasm":"^3.7.1"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.5.1","typescript":"^5.9.3"},"gitHead":"b64e9cc6a81a8ad1a9310db09869a8c377ae5e4a","_id":"@aluria/wechat-ai-api@1.0.1","bugs":{"url":"https://github.com/Wu-Yijun/wechat-ai-api/issues"},"homepage":"https://github.com/Wu-Yijun/wechat-ai-api#readme","_nodeVersion":"25.7.0","_npmVersion":"11.10.1","dist":{"integrity":"sha512-FwXlKb929CHzZSmvyCHGhBPmu2CvSfm/Ulss+NADL/fa7zCYgjn9RUsMchAa7zdmLQrRxtTQTbrMxdQPZH7fEA==","shasum":"2f6892cbd17143d33fd2d6ab24f9300d17a08265","tarball":"https://registry.npmjs.org/@aluria/wechat-ai-api/-/wechat-ai-api-1.0.1.tgz","fileCount":6,"unpackedSize":134658,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGha/oLY/VfG8lsgW7s75aAXM9P0pUsBh71M9HO2yFN3AiEAwgUL0PLh9BR+/pep3IODBNpZxqxbDbnlhkD1hsiqNeQ="}]},"_npmUser":{"name":"aluria","email":"wuyijun21@mails.ucas.ac.cn"},"directories":{},"maintainers":[{"name":"aluria","email":"wuyijun21@mails.ucas.ac.cn"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wechat-ai-api_1.0.1_1774763510941_0.5813908980747309"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T05:49:08.316Z","modified":"2026-03-29T05:51:51.215Z","1.0.0":"2026-03-29T05:49:08.626Z","1.0.1":"2026-03-29T05:51:51.115Z"},"bugs":{"url":"https://github.com/Wu-Yijun/wechat-ai-api/issues"},"author":{"name":"Aluria"},"license":"MIT","homepage":"https://github.com/Wu-Yijun/wechat-ai-api#readme","keywords":["wechat","bot","sdk","openclaw-wechat","api","notification"],"repository":{"type":"git","url":"git+https://github.com/Wu-Yijun/wechat-ai-api.git"},"description":"一个优雅、轻量、开箱即用的个人微信通知/机器人 SDK","maintainers":[{"name":"aluria","email":"wuyijun21@mails.ucas.ac.cn"}],"readme":"# @aluria/wechat-ai-api\r\n\r\n[![npm version](https://badge.fury.io/js/%40aluria%2Fwechat-ai-api.svg)](https://www.npmjs.com/package/@aluria/wechat-ai-api)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)\r\n\r\n基于微信 OpenClaw 开放接口规范封装的 Node.js SDK。为开发者提供标准化的 API，用于快速接入微信扫码鉴权、长轮询消息监听、以及富媒体（文本、图片、文件、视频、语音）的自动化收发。\r\n\r\n🔗 **GitHub 仓库**: [https://github.com/Wu-Yijun/wechat-ai-api](https://github.com/Wu-Yijun/wechat-ai-api)\r\n\r\n## 核心特性\r\n\r\n- **完整的生命周期管理**：封装了完整的扫码鉴权、凭证持久化及长轮询（Long-Polling）保活机制。\r\n- **富媒体透明处理**：内置 `CdnManager`，在发送媒体文件时自动完成 AES-128-ECB 加密与微信 CDN 上传；接收时自动获取凭据并完成解密。\r\n- **按需加载机制**：支持将收到的媒体资源暂存于内存中（惰性求值），支持随时转存为本地文件或直接提取为 Buffer。\r\n- **类型安全**：基于 TypeScript 编写，提供严格的接口约束与完整的类型定义（`.d.ts`）。\r\n\r\n## 📦 安装\r\n\r\n```bash\r\nnpm install @aluria/wechat-ai-api\r\n```\r\n\r\n*注：本项目使用了纯 ESM 规范发布，请确保您的 Node.js 项目 (`package.json`) 中已配置 `\"type\": \"module\"`。*\r\n\r\n## 基础使用\r\n\r\n### 1\\. 鉴权与会话恢复\r\n\r\nSDK 支持将登录成功后的凭据（Token、账户 ID 等）导出，以便在 Node.js 进程重启时免扫码恢复连接。\r\n\r\n```typescript\r\nimport { WeChatApi } from \"@aluria/wechat-ai-api\";\r\nimport fs from \"node:fs\";\r\n\r\nconst bot = new WeChatApi();\r\n\r\nasync function init() {\r\n  const sessionPath = \"./session.json\";\r\n\r\n  if (fs.existsSync(sessionPath)) {\r\n    // 恢复历史会话\r\n    const credentials = JSON.parse(fs.readFileSync(sessionPath, \"utf-8\"));\r\n    bot.loadCredentials(credentials);\r\n    console.log(\"已恢复历史会话\");\r\n  } else {\r\n    // 首次扫码登录\r\n    const credentials = await bot.login();\r\n    fs.writeFileSync(sessionPath, JSON.stringify(credentials));\r\n    console.log(\"登录成功，凭据已保存\");\r\n  }\r\n\r\n  // 启动消息监听守护进程\r\n  bot.startPolling();\r\n}\r\n\r\ninit();\r\n```\r\n\r\n### 2\\. 消息监听与处理\r\n\r\n通过继承 `EventEmitter` 的事件系统，您可以对不同类型的消息进行精确路由。\r\n\r\n```typescript\r\n// 监听纯文本消息\r\nbot.on(\"text\", async (msg) => {\r\n  console.log(`[Text] 收到来自 ${msg.fromUserId} 的消息: ${msg.text}`);\r\n  \r\n  if (msg.text === \"ping\") {\r\n    // 使用 contextToken 触发引用回复\r\n    await bot.messages.sendText(\"pong\", { contextToken: msg.contextToken });\r\n  }\r\n});\r\n\r\n// 监听图片消息\r\nbot.on(\"image\", async (msg) => {\r\n  console.log(`[Image] 收到图片消息，ID: ${msg.messageId}`);\r\n  \r\n  // 方式 A：直接保存到本地磁盘\r\n  const savedPath = await msg.saveToFile!(`./downloads/${msg.messageId}.jpg`);\r\n  console.log(`图片已落盘: ${savedPath}`);\r\n\r\n  // 方式 B：获取 Buffer 传递给第三方 AI 服务（如图像识别）\r\n  // const imageBuffer = await msg.getBuffer!();\r\n  // await externalVisionService.analyze(imageBuffer);\r\n});\r\n\r\n// 监听文件接收\r\nbot.on(\"file\", async (msg) => {\r\n  console.log(`[File] 收到文件: ${msg.fileName}`);\r\n  await msg.saveToFile!(`./downloads/${msg.fileName}`);\r\n});\r\n```\r\n\r\n### 3\\. 主动发送消息\r\n\r\n`bot.messages` 命名空间提供了各种媒体的快捷下发接口。\r\n\r\n```typescript\r\n// 发送带标题的文件\r\nawait bot.messages.sendFile(\"./reports/weekly.pdf\", {\r\n  caption: \"本周的数据报表已生成\",\r\n});\r\n\r\n// 发送视频\r\nawait bot.messages.sendVideo(\"./assets/demo.mp4\");\r\n\r\n// 向指定用户发送图文消息\r\nawait bot.messages.sendImage(\"./assets/alert.png\", {\r\n  caption: \"系统触发了阈值警报\"\r\n});\r\n```\r\n\r\n## ⚙️ 高级配置 (Configuration)\r\n\r\n在实例化 `WeChatApi` 时，可传入自定义配置以覆盖默认行为：\r\n\r\n```typescript\r\nconst bot = new WeChatApi({\r\n  // 是否在接收到图片/文件时自动在后台静默下载并解密缓存到内存中\r\n  // 设为 false 可大幅降低带宽消耗，后续可以手动触发下载\r\n  autoDownloadMedia: true, \r\n\r\n  // 可指定特定的网关地址\r\n  baseUrl: \"https://ilinkai.weixin.qq.com\", \r\n});\r\n```\r\n\r\n### 自定义登录交互\r\n\r\n默认的 `login()` 方法会在控制台打印纯文本的二维码 URL。如果您需要将二维码渲染到 Web 页面或通过其他渠道推送，可传入自定义的回调函数：\r\n\r\n```typescript\r\nawait bot.login({\r\n  onQrCode: (qrInfo) => {\r\n    // qrcodeUrl 为二维码解析后的文本内容\r\n    // 您可以使用 qrcode 库将其渲染为 base64 图片或在终端输出点阵图\r\n    console.log(\"获取到授权二维码:\", qrInfo.qrcodeUrl);\r\n  },\r\n  onStatusChange: (payload) => {\r\n    // 状态流转：wait -> scanned -> confirmed\r\n    console.log(`授权状态更新: ${payload.status}`);\r\n  }\r\n});\r\n```\r\n\r\n## 🛠️ 技术细节与实现约束\r\n\r\n1.  **CDN 加解密规范**：微信媒体文件传输采用 `AES-128-ECB` 算法。本项目已完整实现了该加密规范，包括密钥的 Base64 与 Hex 双重编码容错处理。\r\n2.  **长轮询机制**：消息接收依赖 HTTP Long-Polling，默认连接维持时间为 `35,000` 毫秒。SDK 内部维护了 `sync_buf` 游标，有效防止了消息丢失与重复拉取。\r\n3.  **音频编码**：微信语音消息采用私有的 SILK 格式。已集成 `silk-wasm` 进行音频格式的转换。\r\n\r\n## 📖 API 参考\r\n\r\n详细的类型定义与接口描述，请参阅源码中的 `types.ts`。主要模块包括：\r\n\r\n  - `WeChatApi`: 核心实例，统筹鉴权与轮询。\r\n  - `WeChatApi.messages`: 提供 `sendText`, `sendImage`, `sendVideo`, `sendFile` 等方法。\r\n  - `WeChatIncomingMessage`: 暴露于事件回调中的消息体，提供 `saveToFile()` 和 `getBuffer()`。\r\n\r\n更多详细示例代码请查阅代码库中的 [`example/`](https://github.com/Wu-Yijun/wechat-ai-api/tree/main/example) 目录。\r\n\r\n## 📄 免责声明与协议\r\n\r\n本项目基于 **MIT** 协议开源。\r\n\r\n**声明：** 本 SDK 仅供技术研究、个人日常学习与自动化辅助使用。请严格遵守《腾讯微信软件许可及服务协议》。使用本 SDK 造成的任何账号封禁、数据丢失或法律纠纷，开发者概不负责。严禁用于批量营销、黑灰产及任何侵犯用户隐私的商业行为。\r\n","readmeFilename":"readme.md"}