ba754ccc31
- Auth module: WeChat OAuth2 scan-to-login flow with terminal QR code - Token persistence to ~/.openclaw/wechat-access-auth.json (chmod 600) - Token resolution: config > saved state > interactive login - Invite code verification (configurable bypass) - Production/test environment support - AGP WebSocket client with heartbeat, reconnect, wake detection - Message handler: Agent dispatch with streaming text and tool calls - Random device GUID generation (persisted, no real machine ID)
139 lines
4.0 KiB
Markdown
139 lines
4.0 KiB
Markdown
# Fuwuhao (微信服务号) 模块
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
src/
|
||
├── types.ts # 类型定义
|
||
├── crypto-utils.ts # 加密解密工具
|
||
├── http-utils.ts # HTTP 请求处理工具
|
||
├── callback-service.ts # 后置回调服务
|
||
├── message-context.ts # 消息上下文构建
|
||
├── message-handler.ts # 消息处理器（核心业务逻辑）
|
||
├── webhook.ts # Webhook 处理器（主入口）
|
||
├── runtime.ts # Runtime 配置
|
||
└── index.ts # 模块导出索引
|
||
```
|
||
|
||
## 📦 模块说明
|
||
|
||
### 1. `types.ts` - 类型定义
|
||
定义所有 TypeScript 类型和接口：
|
||
- `AgentEventPayload` - Agent 事件载荷
|
||
- `FuwuhaoMessage` - 服务号消息格式
|
||
- `SimpleAccount` - 账号配置
|
||
- `CallbackPayload` - 回调数据格式
|
||
- `StreamChunk` - 流式消息块
|
||
- `StreamCallback` - 流式回调函数类型
|
||
|
||
### 2. `crypto-utils.ts` - 加密解密工具
|
||
处理微信服务号的签名验证和消息加密解密：
|
||
- `verifySignature()` - 验证签名
|
||
- `decryptMessage()` - 解密消息
|
||
|
||
### 3. `http-utils.ts` - HTTP 工具
|
||
处理 HTTP 请求相关的工具方法：
|
||
- `parseQuery()` - 解析查询参数
|
||
- `readBody()` - 读取请求体
|
||
- `isFuwuhaoWebhookPath()` - 检查是否是服务号 webhook 路径
|
||
|
||
### 4. `callback-service.ts` - 后置回调服务
|
||
将处理结果发送到外部回调服务：
|
||
- `sendToCallbackService()` - 发送回调数据
|
||
|
||
### 5. `message-context.ts` - 消息上下文构建
|
||
构建消息处理所需的上下文信息：
|
||
- `buildMessageContext()` - 构建消息上下文（路由、会话、格式化等）
|
||
|
||
### 6. `message-handler.ts` - 消息处理器
|
||
核心业务逻辑，处理消息并调用 Agent：
|
||
- `handleMessage()` - 同步处理消息
|
||
- `handleMessageStream()` - 流式处理消息（SSE）
|
||
|
||
### 7. `webhook.ts` - Webhook 处理器
|
||
主入口，处理微信服务号的 webhook 请求：
|
||
- `handleSimpleWecomWebhook()` - 处理 GET/POST 请求，支持同步和流式返回
|
||
|
||
### 8. `runtime.ts` - Runtime 配置
|
||
获取 OpenClaw 运行时实例
|
||
|
||
### 9. `index.ts` - 模块导出
|
||
统一导出所有公共 API
|
||
|
||
## 🔄 数据流
|
||
|
||
```
|
||
微信服务号
|
||
↓
|
||
webhook.ts (入口)
|
||
↓
|
||
http-utils.ts (解析请求)
|
||
↓
|
||
crypto-utils.ts (验证签名/解密)
|
||
↓
|
||
message-context.ts (构建上下文)
|
||
↓
|
||
message-handler.ts (处理消息)
|
||
↓
|
||
OpenClaw Agent (AI 处理)
|
||
↓
|
||
callback-service.ts (后置回调)
|
||
↓
|
||
返回响应
|
||
```
|
||
|
||
## 🚀 使用示例
|
||
|
||
### 基本使用
|
||
```typescript
|
||
import { handleSimpleWecomWebhook } from "./src/webhook.js";
|
||
|
||
// 在 HTTP 服务器中使用
|
||
server.on("request", async (req, res) => {
|
||
const handled = await handleSimpleWecomWebhook(req, res);
|
||
if (!handled) {
|
||
// 处理其他路由
|
||
}
|
||
});
|
||
```
|
||
|
||
### 流式返回（SSE）
|
||
```typescript
|
||
// 客户端请求时添加 stream 参数
|
||
fetch("/fuwuhao?stream=true", {
|
||
headers: {
|
||
"Accept": "text/event-stream"
|
||
}
|
||
});
|
||
```
|
||
|
||
## 🔧 配置
|
||
|
||
### 环境变量
|
||
- `FUWUHAO_CALLBACK_URL` - 后置回调服务 URL（默认：`http://localhost:3001/api/fuwuhao/callback`）
|
||
|
||
### 账号配置
|
||
在 `webhook.ts` 中修改 `mockAccount` 对象：
|
||
```typescript
|
||
const mockAccount: SimpleAccount = {
|
||
token: "your_token_here",
|
||
encodingAESKey: "your_encoding_aes_key_here",
|
||
receiveId: "your_receive_id_here"
|
||
};
|
||
```
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **加密解密**：当前 `crypto-utils.ts` 中的加密解密方法是简化版，生产环境需要实现真实的加密逻辑
|
||
2. **签名验证**：同样需要在生产环境中实现真实的签名验证算法
|
||
3. **错误处理**：所有模块都包含完善的错误处理和日志记录
|
||
4. **类型安全**：所有模块都使用 TypeScript 严格类型检查
|
||
|
||
## 🎯 设计原则
|
||
|
||
- **单一职责**：每个文件只负责一个特定功能
|
||
- **低耦合**：模块之间通过明确的接口通信
|
||
- **高内聚**：相关功能集中在同一模块
|
||
- **可测试**：每个模块都可以独立测试
|
||
- **可扩展**：易于添加新功能或修改现有功能
|