企业官网建设流程全解析

你的微信 AI 助手，能不能不等你开口，就主动给你发来一份日报、一条定时提醒、甚至一张图片？答案是：可以。weixin-agent-sdk 是一个把任意 AI Agent 接入微信的桥接 SDK，除了"你问它答"，它还提供了bot.sendMessage()接口，让机器人能主动向当前用户推送文本、图片、视频和文件。本文带你完整跑通 weixin-agent-sdk 主动发送消息的流程，包括 context_token 机制、媒体推送和常见坑位，几十行代码即可上手。

为什么微信 Bot 需要"主动发消息"

大多数微信机器人都是"被动应答"模式：你说一句话，AI 回一句话。但很多真实场景恰恰需要反方向的推送：

• ⏰ 定时提醒：每天早上 9 点推送今日日程
• 📊 任务通知：后台任务跑完后，把结果文件直接推到你微信
• 📈 数据日报：AI 生成报表后主动发给你，而不是等你来问
• 💬 主动问候：服务启动时先发一句"我已上线"

weixin-agent-sdk 中，start(agent)会立即返回一个Bot实例，它自带sendMessage()方法，随时可以把消息"推"到微信里（见 packages/sdk/src/bot.ts）。

三步实现主动发消息：登录、启动、发送

整体流程只有三步，核心代码结构如下：

1. login()—— 终端显示二维码，微信扫码登录
2. start(agent)—— 启动消息循环，立即返回Bot实例
3. bot.sendMessage(...)—— 在任意时机主动发消息

先看最小可用的文本推送示例：

import { login, start, type Agent } from "weixin-agent-sdk"; const agent: Agent = { async chat(req) { return { text: `收到：${req.text}` }; }, }; await login(); // 1. 扫码登录 const bot = start(agent); // 2. 启动，拿到 Bot // 3. 随时主动发消息 bot.sendMessage("你好，我是你的 AI 助手，现在已上线 ✅");

Agent接口只需要实现一个chat()方法来响应入站消息，定义见 packages/sdk/src/agent/interface.ts。如果你已经有 OpenAI 等后端，packages/example-openai/main.ts 提供了可直接运行的完整示例，参考 packages/example-openai/src/openai-agent.ts。

用 bot.sendMessage 主动发文本

sendMessage()支持两种入参（源码见 packages/sdk/src/bot.ts）：

一个细节值得注意：文本在发送前会经过markdownToPlainText()处理，AI 返回的 markdown 格式（加粗、代码块、链接等）会被自动转成微信里可读的纯文本，见 packages/sdk/src/messaging/send.ts。

主动推送图片、视频和文件

想主动发文件？把ChatResponse对象传进去即可：

await bot.sendMessage({ text: "这是最新报表", media: { type: "file", // 或 "image" / "video" url: "./reports/daily.pdf", fileName: "daily.pdf", }, });

media.url支持两种形式：

• 本地路径：直接上传到微信 CDN 后发送
• HTTPS 链接：SDK 自动下载后上传（逻辑见 packages/sdk/src/bot.ts）

文本和媒体可以同时发送，text会作为附件的说明文字一起推过去。

理解 context_token：主动发送的隐藏钥匙

这是主动发消息最关键的一点：bot.sendMessage()依赖微信下发的context_token。它的工作方式：

1. 每当你收到一条入站消息时，微信会随消息附带一个context_token
2. SDK 会自动把它缓存起来（缓存逻辑见 packages/sdk/src/messaging/inbound.ts）
3. 每次发消息（包括主动发送）都要回传这个 token，用于关联会话

因此有两条硬性前提（源码见 packages/sdk/src/messaging/process-message.ts）：

• ✅ 必须在start()运行期间，至少收到过一条微信消息，才能主动发
• ⚠️context_token有时效（约 24 小时），过期后需要再收到一条新消息才能继续推送

如果条件不满足就调用sendMessage()，会抛出这个错误：

Error: 没有找到 context_token，需要在 start() 运行期间至少收到过一条消息

看到这条报错别慌，去微信里给机器人随便发句话，再试一次即可。

实战案例：定时提醒主动推送到微信

把主动发消息和定时器结合，就是一个标准的"微信推送机器人"：

await login(); const bot = start(agent); setInterval(() => { void bot.sendMessage("定时提醒：记得查看最新状态"); }, 60_000); await bot.wait(); // 等待消息循环结束

bot.wait()会让 CLI/脚本程序一直阻塞到 bot 停止（见 packages/sdk/src/bot.ts），避免主进程提前退出。类似的玩法还有很多：任务完成回调里推一条结果通知、定时拉取数据后生成文件再sendMessage推出去，都可以完全复用这一套模式。

主动发消息常见问题

Q：机器人启动后立刻发消息失败？A：还没有收到过任何入站消息，context_token缓存是空的。先在微信里发一句话"激活"一下。

Q：隔了两天没互动，推送突然失败了？A：context_token已过期。SDK 不做持久化缓存（token 只在进程内存里），重新收到一条消息即可恢复。

Q：主动发的 markdown 表格能正常显示吗？A：不能，微信端只会收到转换后的纯文本。重要信息建议直接用media发文件，例如让 AI 生成 PDF 后主动推送。

Q：需要公网服务器吗？A：不需要。SDK 用长轮询（getUpdates）接收消息，本地终端跑起来就行。

总结：从被动应答到主动触达

weixin-agent-sdk 的主动发送能力非常"轻"——start()返回Bot，bot.sendMessage()一行搞定，媒体、markdown 转换、token 管理都藏在 SDK 里。记住三条要点，你就能把 AI 从"等问才答"升级为"主动找你说句话"：

1. start(agent)立即返回Bot实例，随时可调用sendMessage()
2. 先收到一条消息，context_token才会生效；它约 24 小时过期
3. 字符串发文本，ChatResponse发图片/视频/文件，text 与 media 可组合

配合packages/example-openai/里的现成 Agent 实现，几十行代码就能拥有一个会主动推送消息的微信 AI 助手。