wong2/weixin-agent-sdk：weixin-agent-sdk 是一个微信 AI Agent 桥接框架，通过标准 Agent 接口或 ACP 协议将各类 AI 后端（如 Op本页整理它解决什么问题、适用场景、安装方式和使用方法。
weixin-agent-sdk 是一个微信 AI Agent 桥接框架，通过标准 Agent 接口或 ACP 协议将各类 AI 后端（如 OpenAI、Claude、kimi）接入微信，支持多轮对话与媒体消息，实现零代码或低代码集成。
weixin-agent-sdk 定位于微信平台的 AI Agent 桥接框架，旨在为开发者提供一种简便方式将各类 AI 后端服务接入微信。通过定义标准的 Agent 接口，开发者只需实现 chat 方法即可处理微信消息，而无需关心底层微信协议细节。项目同时提供 ACP 协议适配器，支持直接运行兼容 ACP 的第三方 Agent（如 Claude Code、Codex、kimi-cli），实现零代码集成。主要用途包括构建智能客服、个人 AI 助手、自动化群管机器人等，适用于个人开发者、团队及企业的快速原型开发或生产环境部署。
本项目解决了将任意 AI Agent 服务集成到微信平台的技术难题。传统方案需要开发者自行处理微信协议、消息加解密、媒体文件下载等复杂逻辑，且不同 AI 后端接口各异，集成成本高。weixin-agent-sdk 通过统一 Agent 接口抽象 AI 交互，并内置微信协议处理与媒体管理模块，大幅简化开发流程。此外，ACP 适配器允许直接复用现有兼容 Agent，无需编写额外代码，进一步降低门槛，使开发者能聚焦于 AI 逻辑而非平台适配。
适用场景包括：1) 接入兼容 ACP 协议的 Agent，如 Claude Code、Codex、kimi-cli 等，通过命令行工具快速启动；2) 基于 OpenAI、Azure OpenAI 或其他兼容 API 的 AI 服务，自定义 Agent 实现多轮对话与视觉输入；3) 构建支持文本、图片、语音、视频、文件等多种消息类型的智能微信机器人；4) 需要主动推送消息的场景，如定时提醒、状态通知，依赖微信下发的 context_token。项目适合需要微信 AI 助手的各类应用，从个人实验到生产级部署均可覆盖。
安装方式分为两类：作为库引用时，在项目目录执行 npm install weixin-agent-sdk 或 pnpm add weixin-agent-sdk 安装 SDK 包；运行示例或进行开发时，需克隆仓库后在根目录执行 pnpm install 安装所有 monorepo 包依赖。示例包（如 example-openai）通过 workspace:* 协议链接本地 SDK。注意：项目使用 pnpm 作为包管理器，建议确保 pnpm 已安装。仓库中未明确给出 Docker 镜像或全局安装方式，仅提供源码与包管理安装。
使用方式包括自定义 Agent 和 ACP 接入两种路径。自定义 Agent 需实现 Agent 接口的 chat 方法，接收 ChatRequest 并返回 ChatResponse；然后调用 login() 扫码登录微信，再调用 start(agent) 启动消息循环，获取 Bot 实例用于主动发送消息。ACP 接入则直接运行 npx weixin-acp <agent-name>（如 claude-code、codex），或使用 npx weixin-acp start -- <command> 启动任意 ACP agent。OpenAI 示例需设置 OPENAI_API_KEY 环境变量，通过 pnpm run login 和 pnpm run start 运行。详细接口定义、消息类型支持与注意事项见 README。
项目实现特点包括：媒体处理模块自动从微信 CDN 下载并解密媒体文件，以本地路径形式传递给 Agent，回复时支持本地路径或 HTTPS URL；语音消息自动将 SILK 格式转为 WAV（需额外安装 silk-wasm 依赖）；主动发送消息依赖微信下发的 context_token，且需在收到至少一条入站消息后使用，token 有时效性（约 24 小时）；SDK 采用 TypeScript 编写，提供完整类型定义；项目采用 pnpm monorepo 管理，核心包为 sdk，weixin-acp 为独立适配器，example-openai 展示完整集成。仓库中未明确给出性能指标、大规模部署建议或官方支持渠道。
调用 login() 函数会生成二维码，使用微信扫描即可完成登录。示例中可通过 pnpm run login 执行登录流程。
直接运行 npx weixin-acp <agent-name>（如 npx weixin-acp claude-code）；或使用 npx weixin-acp start -- <command> 启动任意 ACP agent，适配器会以子进程方式管理通信。
实现 Agent 接口的 chat 方法，接收 ChatRequest 并返回 ChatResponse；然后调用 start(agent) 启动。详细接口定义与 OpenAI 示例见 packages/example-openai 目录。
接收支持文本、图片、语音（自动转 WAV）、视频、文件、引用消息、语音转文字；发送支持文本、图片、视频、文件，可组合文本与媒体。媒体文件自动下载解密后以本地路径传递。
start() 返回的 Bot 实例提供 sendMessage() 方法，可在收到消息后主动推送。需依赖微信下发的 context_token，且需先收到至少一条入站消息，token 约 24 小时有效。