WeChatBot Java SDK

微信 iLink Bot 的 Java 多模块 SDK（Spring Boot 友好）

会话/凭证默认持久化路径：~/.wechatbot/java-session-state.json（Windows 对应 %USERPROFILE%\.wechatbot\java-session-state.json）

5 分钟接入

1) 引入依赖（推荐 BOM）

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.agent4j.wechatbot</groupId>
      <artifactId>wechatbot-bom</artifactId>
      <version>0.1.0-SNAPSHOT</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.agent4j.wechatbot</groupId>
    <artifactId>wechatbot-spring-boot-starter</artifactId>
  </dependency>
</dependencies>

2) 添加基础配置

wechatbot:
  base-url: https://ilinkai.weixin.qq.com
  cdn-base-url: https://novac2c.cdn.weixin.qq.com/c2c
  auto-start: false

3) 注册消息处理并启动

@Component
public class BotRunner implements CommandLineRunner {
    private final WeChatBotClient client;

    public BotRunner(WeChatBotClient client) {
        this.client = client;
    }

    @Override
    public void run(String... args) {
        client.onMessage(msg -> client.reply(msg, "Echo: " + msg.text()));
        client.login(); // 扫码登录或恢复会话
        client.start(); // 开始长轮询
    }
}

Java 原生最小示例（非 Spring）

import com.agent4j.wechatbot.auth.AuthService;
import com.agent4j.wechatbot.core.WeChatBotClient;
import com.agent4j.wechatbot.protocol.HttpWeChatBotApi;
import com.agent4j.wechatbot.store.file.FileSessionStore;

public class Demo {
  public static void main(String[] args) {
    var api = new HttpWeChatBotApi("https://ilinkai.weixin.qq.com");
    var store = new FileSessionStore();
    var auth = new AuthService(store);
    var bot = new WeChatBotClient(api, auth);

    bot.login();
    bot.onMessage(msg -> bot.reply(msg, "Echo: " + msg.text()));
    bot.start();
  }
}

核心能力

• 扫码登录与会话恢复（过期自动处理）
• 长轮询消息接收与自动游标管理
• 文本/图片/文件等媒体发送
• 入站媒体下载与 CDN AES-128-ECB 解密
• typing ticket 管理与输入态支持
• Spring Boot 自动装配与扩展点

模块一览

• wechatbot-bom：依赖版本管理
• wechatbot-core：Bot 客户端、轮询与消息处理主流程
• wechatbot-protocol：协议 API 抽象与 HTTP 适配
• wechatbot-auth：登录、会话恢复、context token 管理
• wechatbot-store-spi：会话存储扩展 SPI
• wechatbot-store-file：默认文件存储实现
• wechatbot-media：媒体上传/下载与解密辅助
• wechatbot-typing：typing ticket 缓存与发送
• wechatbot-spring-boot-starter：Spring Boot 自动配置
• wechatbot-examples-springboot：可运行示例

架构概览

graph TD
    A["业务代码 / Agent"] --> B["WeChatBotClient"]
    B --> C["Poller（收消息）"]
    B --> D["Sender（发消息）"]
    B --> E["Media（媒体）"]
    B --> F["Typing（输入态）"]
    C --> G["Auth / Context Token"]
    D --> G
    E --> G
    F --> G
    G --> H["iLink HTTP API"]
    G --> I["Session Store"]

Loading

TradingAgents-Ashare 接入方案（已落地）

D:\AI\trandingAgents-ashare 已完成微信接入，建议按以下方式复用：

接入目标

• 用户在微信发自然语言指令（例如：600519.SH 今天）
• 服务端解析出 symbol + tradeDate
• 调用交易编排服务（TradingGraphService）
• 将最终决策结果回复回微信

关键依赖（pom.xml）

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.agent4j.wechatbot</groupId>
      <artifactId>wechatbot-bom</artifactId>
      <version>0.1.0-SNAPSHOT</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.agent4j.wechatbot</groupId>
    <artifactId>wechatbot-spring-boot-starter</artifactId>
  </dependency>
</dependencies>

推荐配置（application.yml）

wechatbot:
  base-url: https://ilinkai.weixin.qq.com
  cdn-base-url: https://novac2c.cdn.weixin.qq.com/c2c
  auto-start: false
  force-relogin: false

消息处理链路（实战）

1. 在启动类中注册 client.onMessage(...)
2. client.login(forceRelogin) 获取扫码或恢复会话
3. client.start() 进入轮询
4. 收到文本后先走 WeChatCommandParser（正则规则）
5. 失败时回退到 LlmWeChatCommandExtractor（LLM 抽取）
6. 调用 tradingGraphService.propagate(symbol, tradeDate)
7. 将决策文本 client.reply(...) 回复给用户

可直接参考的类

• src/main/java/com/example/tradingagents/wechat/WeChatBotRunner.java
• src/main/java/com/example/tradingagents/wechat/WeChatCommandParser.java
• src/main/java/com/example/tradingagents/wechat/LlmWeChatCommandExtractor.java
• src/main/java/com/example/tradingagents/wechat/WeChatBotWiringConfig.java

媒体能力示例

发送图片：

@Component
public class MediaRunner implements CommandLineRunner {
    private final WeChatBotOperations ops;

    public MediaRunner(WeChatBotOperations ops) {
        this.ops = ops;
    }

    @Override
    public void run(String... args) throws Exception {
        ops.sendImage("user_id_here", Files.readAllBytes(Path.of("demo.png")), "demo.png");
    }
}

下载并解密入站媒体：

byte[] plain = ops.downloadAndDecrypt(message.items().get(0));

常见问题

• **BotException: QR code expired**：二维码过期后 SDK 会自动重新拉取并继续轮询；若长时间未确认会抛出 Login timeout。
• 启动时没看到二维码：可能命中会话恢复，这是正常行为。需要强制扫码时，设置 wechatbot.force-relogin=true 或删除本地会话文件。
• **auto-start=true 时无法立即看到登录状态**：可通过 GET /wechatbot/qrcode 或 POST /wechatbot/login/start 主动触发并查看二维码 URL。

构建

mvn -DskipTests=false verify

发布说明

项目已按 Maven Central 发布结构组织（sources/javadocs/GPG/staging）。
发布细节见：docs/publish-maven-central.md