weixin-agent-sdk 框架解析

在微信小程序集成AI插件的实践中，后端服务暴露与前端调用是常见难题。weixin-agent-sdk框架通过Python单体部署提供简洁解决方案，其核心在于Agent类，该类统一请求响应约定，确保业务逻辑与模型调用一致。

Agent类封装业务逻辑，开发者需继承Agent类并实现chat方法。该方法接收ChatRequest对象（包含用户输入text），异步返回ChatResponse对象（包含AI生成的text回复）。示例代码如下：

from weixin_agent import Agent, ChatRequest, ChatResponse, login, start

class MyAIAgent(Agent):
    async def chat(self, request: ChatRequest) -> ChatResponse:
        answer = call_llm(request.text)
        return ChatResponse(text=answer)

login(openai_api_key="sk-xxxx")
start(MyAIAgent())

输入为ChatRequest.text，用户发送的文字；输出为ChatResponse.text，AI生成的回复。这种结构让后端在不同部署环境下保持一致，仅需替换call_llm实现即可。

模型部署与本地打包采用uv虚拟环境完成，无需微服务拆分。创建隔离环境后安装依赖，启动插件服务。pyproject.toml中声明weixin-agent-sdk、wechatpy等库，确保环境可复现。模型调用可替换为本地LLaMA或ChatGLM等，只要返回字符串即可。框架自动处理凭证持久化，保存在用户主目录的~/.openc…

微信小程序调用方面，框架通过wechatpy处理服务器推送消息。开发者创建Flask应用，绑定WeChatClient，路由/wechat/message端点。从微信消息JSON中提取Content字段，通过HTTP POST调用插件的chat接口，获取ai_reply后JSON回传给小程序。小程序端发送POST请求，后端将用户文字转为ChatRequest交给插件处理，将ChatResponse.text展示在聊天窗口。

这种前端-后端-插件的三层结构保持轻量，适合快速迭代验证商业价值。调试时建议使用try/except捕获网络错误，记录status_code与异常信息。加入timeout控制防止长轮询失效，框架使用ilink/bot/getupdates确保443端口通畅，可本地改为poll_interval=2加速测试。消息格式不匹配时需确保JSON包含Content字段。启动服务时用uvicorn或flask run，并通过curl验证HTTP接口响应，打开logging.DEBUG查看weixin_agent与wechatpy的内部日志，包括请求路径和异常堆栈。

遵循统一接口、轻量部署、安全凭证、微信兼容及可观测性的要点，即可数小时内完成AI插件原型，实现从零到一的快速落地。