[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75022":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},75022,"weixin-agent-sdk","wong2\u002Fweixin-agent-sdk","wong2","微信Clawbot接入任意Agent","",null,"TypeScript",1186,129,6,5,0,4,9,56,12,19.34,"MIT License",false,"main",true,[],"2026-06-12 02:03:31","# weixin-agent-sdk\n\n> 本项目非微信官方项目，代码由 [@tencent-weixin\u002Fopenclaw-weixin](https:\u002F\u002Fnpmx.dev\u002Fpackage\u002F@tencent-weixin\u002Fopenclaw-weixin) 改造而来，仅供学习交流使用。\n\n微信 AI Agent 桥接框架 —— 通过简单的 Agent 接口，将任意 AI 后端接入微信。\n\n## 项目结构\n\n```\npackages\u002F\n  sdk\u002F                  weixin-agent-sdk —— 微信桥接 SDK\n  weixin-acp\u002F           ACP (Agent Client Protocol) 适配器\n  example-openai\u002F       基于 OpenAI 的示例\n```\n\n## 通过 ACP 接入 Claude Code, Codex, kimi-cli 等 Agent\n\n[ACP (Agent Client Protocol)](https:\u002F\u002Fagentclientprotocol.com\u002F) 是一个开放的 Agent 通信协议。如果你已有兼容 ACP 的 agent，可以直接通过 [`weixin-acp`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fweixin-acp) 接入微信，无需编写任何代码。\n\n\n### Claude Code\n\n```bash\nnpx weixin-acp claude-code\n```\n\n### Codex\n\n```bash\nnpx weixin-acp codex\n```\n\n### 其它 ACP Agent\n\n比如 kimi-cli：\n\n```bash\nnpx weixin-acp start -- kimi acp\n```\n\n`--` 后面的部分就是你的 ACP agent 启动命令，`weixin-acp` 会自动以子进程方式启动它，通过 JSON-RPC over stdio 进行通信。\n\n更多 ACP 兼容 agent 请参考 [ACP agent 列表](https:\u002F\u002Fagentclientprotocol.com\u002Fget-started\u002Fagents)。\n\n## 自定义 Agent\n\nSDK 主要导出三样东西：\n\n- **`Agent`** 接口 —— 实现它就能接入微信\n- **`login()`** —— 扫码登录\n- **`start(agent)`** —— 启动消息循环，立即返回可主动发消息的 `Bot`\n\n### Agent 接口\n\n```typescript\ninterface Agent {\n  chat(request: ChatRequest): Promise\u003CChatResponse>;\n}\n\ninterface ChatRequest {\n  conversationId: string;         \u002F\u002F 用户标识，可用于维护多轮对话\n  text: string;                   \u002F\u002F 文本内容\n  media?: {                       \u002F\u002F 附件（图片\u002F语音\u002F视频\u002F文件）\n    type: \"image\" | \"audio\" | \"video\" | \"file\";\n    filePath: string;             \u002F\u002F 本地文件路径（已下载解密）\n    mimeType: string;\n    fileName?: string;\n  };\n}\n\ninterface ChatResponse {\n  text?: string;                  \u002F\u002F 回复文本（支持 markdown，发送前自动转纯文本）\n  media?: {                       \u002F\u002F 回复媒体\n    type: \"image\" | \"video\" | \"file\";\n    url: string;                  \u002F\u002F 本地路径或 HTTPS URL\n    fileName?: string;\n  };\n}\n```\n\n### 最简示例\n\n```typescript\nimport { login, start, type Agent } from \"weixin-agent-sdk\";\n\nconst echo: Agent = {\n  async chat(req) {\n    return { text: `你说了: ${req.text}` };\n  },\n};\n\nawait login();\nconst bot = start(echo);\nawait bot.wait();\n```\n\n### 完整示例（自己管理对话历史）\n\n```typescript\nimport { login, start, type Agent } from \"weixin-agent-sdk\";\n\nconst conversations = new Map\u003Cstring, string[]>();\n\nconst myAgent: Agent = {\n  async chat(req) {\n    const history = conversations.get(req.conversationId) ?? [];\n    history.push(req.text);\n\n    \u002F\u002F 调用你的 AI 服务...\n    const reply = await callMyAI(history);\n\n    history.push(reply);\n    conversations.set(req.conversationId, history);\n    return { text: reply };\n  },\n};\n\nawait login();\nconst bot = start(myAgent);\nawait bot.wait();\n```\n\n### 主动发送消息\n\n`start()` 会立即返回 `Bot` 实例。`Bot` 提供了 `sendMessage()`，可以在收到微信消息之外，主动给当前登录用户发送内容；如果是 CLI\u002F脚本程序，可以用 `bot.wait()` 等待消息循环结束。\n\n```typescript\nimport { login, start, type Agent } from \"weixin-agent-sdk\";\n\nconst agent: Agent = {\n  async chat(req) {\n    if (req.text === \"ping\") {\n      return { text: \"pong\" };\n    }\n    return { text: `收到：${req.text}` };\n  },\n};\n\nawait login();\nconst bot = start(agent);\n\nsetInterval(() => {\n  void bot.sendMessage(\"定时提醒：记得查看最新状态\");\n}, 60_000);\n\nawait bot.wait();\n```\n\n也可以主动发送完整的 `ChatResponse`，包括图片、视频或文件：\n\n```typescript\nawait bot.sendMessage({\n  text: \"这是最新报表\",\n  media: {\n    type: \"file\",\n    url: \".\u002Freports\u002Fdaily.pdf\",\n    fileName: \"daily.pdf\",\n  },\n});\n```\n\n注意事项：\n\n- 主动发送依赖微信下发的 `context_token`\n- 需要在 `start()` 运行期间，至少先收到过当前账号的一条入站消息\n- `context_token` 有时效，可能是 24 小时；过期后需要再次收到新消息才能继续主动发送\n\n### OpenAI 示例\n\n`packages\u002Fexample-openai\u002F` 是一个完整的 OpenAI Agent 实现，支持多轮对话和图片输入：\n\n```bash\npnpm install\n\n# 扫码登录微信\npnpm run login -w packages\u002Fexample-openai\n\n# 启动 bot\nOPENAI_API_KEY=sk-xxx pnpm run start -w packages\u002Fexample-openai\n```\n\n支持的环境变量：\n\n| 变量 | 必填 | 说明 |\n|------|------|------|\n| `OPENAI_API_KEY` | 是 | OpenAI API Key |\n| `OPENAI_BASE_URL` | 否 | 自定义 API 地址（兼容 OpenAI 接口的第三方服务） |\n| `OPENAI_MODEL` | 否 | 模型名称，默认 `gpt-5.4` |\n| `SYSTEM_PROMPT` | 否 | 系统提示词 |\n\n## 支持的消息类型\n\n### 接收（微信 → Agent）\n\n| 类型 | `media.type` | 说明 |\n|------|-------------|------|\n| 文本 | — | `request.text` 直接拿到文字 |\n| 图片 | `image` | 自动从 CDN 下载解密，`filePath` 指向本地文件 |\n| 语音 | `audio` | SILK 格式自动转 WAV（需安装 `silk-wasm`） |\n| 视频 | `video` | 自动下载解密 |\n| 文件 | `file` | 自动下载解密，保留原始文件名 |\n| 引用消息 | — | 被引用的文本拼入 `request.text`，被引用的媒体作为 `media` 传入 |\n| 语音转文字 | — | 微信侧转写的文字直接作为 `request.text` |\n\n### 发送（Agent → 微信）\n\n| 类型 | 用法 |\n|------|------|\n| 文本 | 返回 `{ text: \"...\" }` |\n| 图片 | 返回 `{ media: { type: \"image\", url: \"\u002Fpath\u002Fto\u002Fimg.png\" } }` |\n| 视频 | 返回 `{ media: { type: \"video\", url: \"\u002Fpath\u002Fto\u002Fvideo.mp4\" } }` |\n| 文件 | 返回 `{ media: { type: \"file\", url: \"\u002Fpath\u002Fto\u002Fdoc.pdf\" } }` |\n| 文本 + 媒体 | `text` 和 `media` 同时返回，文本作为附带说明发送 |\n| 远程图片 | `url` 填 HTTPS 链接，SDK 自动下载后上传到微信 CDN |\n| 主动发送 | 通过 `const bot = start(agent)` 后调用 `bot.sendMessage(...)` |\n\n## 内置斜杠命令\n\n在微信中发送以下命令：\n\n- `\u002Fecho \u003C消息>` —— 直接回复（不经过 Agent），附带通道耗时统计\n- `\u002Ftoggle-debug` —— 开关 debug 模式，启用后每条回复追加全链路耗时\n\n## 技术细节\n\n- 使用 **长轮询** (`getUpdates`) 接收消息，无需公网服务器\n- 媒体文件通过微信 CDN 中转，**AES-128-ECB** 加密传输\n- 单账号模式：每次 `login` 覆盖之前的账号\n- 断点续传：`get_updates_buf` 持久化到 `~\u002F.openclaw\u002F`，重启后从上次位置继续\n- 会话过期自动重连（errcode -14 触发 1 小时冷却后恢复）\n- Node.js >= 22\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=wong2%2Fweixin-agent-sdk&type=date&legend=top-left\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=wong2\u002Fweixin-agent-sdk&type=date&theme=dark&legend=top-left\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=wong2\u002Fweixin-agent-sdk&type=date&legend=top-left\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=wong2\u002Fweixin-agent-sdk&type=date&legend=top-left\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n","weixin-agent-sdk 是一个用于将任意 AI 后端接入微信的桥接框架。该项目通过提供简洁的 Agent 接口，支持用户快速实现 AI 服务与微信之间的消息交互，且内置了对 ACP (Agent Client Protocol) 的适配器，使得兼容 ACP 的 agent 可以零代码接入微信。技术上，该库使用 TypeScript 开发，保证了良好的类型安全性和开发体验。适用于需要将自定义或第三方 AI 服务（如 Claude Code, Codex 等）集成到微信聊天场景中的开发者，无论是个人学习还是小规模商业应用，都能找到其价值所在。此外，项目还提供了详细的文档和示例代码，便于理解和快速上手。",2,"2026-06-11 03:51:59","high_star"]