Edit: WeClaw 架构全景与 Free Router 工程美学深度解析

编辑文章

标题 *

URL 别名 *

内容 * (支持 Markdown 格式)

# 深度解构 WeClaw：个人数字生命操作系统的架构哲学与工程奇观

## 一、项目全景：从微信机器人到“多智能体操作系统”

WeClaw 表面上是一个基于 Go 语言实现的微信机器人，但深入源码（约两万行）后可以发现，它本质上是一个：

> **以微信为交互前端、以文件系统为共享状态、以多种大语言模型为异构计算单元的多智能体微型操作系统（Multi-Agent OS）**。

### 核心架构特征

1. **彻底解耦的 Agent 抽象层**
   - `agent/` 目录统一抽象为 `agent.Agent` 接口
   - 支持三种执行形态：HTTP 模式、CLI 子进程模式、ACP 常驻进程模式
   - 微信前端完全无感后端实现

2. **文件系统即数据库（Unix 哲学）**
   - `hub/` 使用 Markdown + YAML Frontmatter 存储状态
   - 不依赖 Redis
   - 状态可读、可被外部工具直接编辑

3. **微信内 DSL 工作流引擎**
   - 支持 `@N`、`parallel` 等语法
   - 实现 DAG 任务编排

4. **极简主义与防御性工程**
   - 零 CGO
   - 单二进制交付
   - `go:embed` 嵌入完整后台
   - 逆向微信 CDN AES-128-ECB 加解密

---

# 二、核心亮点：Free Router 的工程奇观

路径：`/api/free/chat`
函数：`handleFreeChat`

目标：

> 将多个免费 LLM API 池化，对外暴露统一 OpenAI 兼容端点，实现高可用 + 自动降级。

该实现包含 5 个极具工程价值的技巧。

---

## 技巧一：Fisher-Yates 洗牌实现无状态负载均衡

```go
rand.Shuffle(len(names), func(i, j int) { names[i], names[j] = names[j], names[i] })
```

### 设计思想

- 不使用轮询
- 不维护权重
- 不使用锁
- 不记录全局状态

### 优势

| 特性 | 说明 |
|------|------|
| 防止雪崩 | 首选 Provider 均匀分布 |
| 时间复杂度 | O(N)，极低开销 |
| 无锁 | 每个请求独立洗牌 |
| 无状态 | 不需要全局计数器 |

这是一种极其优雅的“随机负载均衡”。

---

## 技巧二：map[string]any 实现透明网关

```go
var body map[string]any
json.NewDecoder(r.Body).Decode(&body)
body["model"] = ag.Model
body["stream"] = true
```

### 核心思想

- 不定义强类型 Struct
- 不丢弃未知字段
- 手术式覆写关键字段

### 优势

1. 保留所有厂商私有参数
2. 动态替换模型名
3. 强制开启流式
4. 保持 OpenAI 协议兼容

这是典型的“透明代理（Transparent Relay）”设计。

---

## 技巧三：串行优雅降级

```go
for _, name := range names {
    resp, err := client.Do(req)
    if err != nil || resp.StatusCode != 200 {
        continue
    }
}
```

### 为什么不用并发 First-Win？

因为：

- 免费 API 有配额限制
- 并发请求会指数级消耗 Key

### 优势

- 节省 API Key
- 逻辑简单
- 提升成功率
- 提高 SLA

这是典型的 **Design for Failure** 思路。

---

## 技巧四：SSE 流式前缀注入（最精彩部分）

```go
w.Write([]byte("data: ...\n\n"))
flusher.Flush()
```

### 背景

希望客户端看到：

```
[deepseek] 你好
```

但不想解析 SSE。

### 解决方案

伪造一个合法 OpenAI chunk：

```json
{"choices":[{"delta":{"content":"[deepseek] "}}]}
```

然后：

1. 先写入该 chunk
2. Flush
3. 再 `io.Copy` 上游流

客户端拼接逻辑：

```
前缀 + 后续 token
```

### 优势

| 特性 | 说明 |
|------|------|
| 零解析 | 不处理上游 JSON |
| 极速 TTFT | 立即显示前缀 |
| 无额外 CPU 开销 | 不做 JSON 重写 |
| 极简实现 | 数十行代码 |

这是对 SSE 协议的“协议级利用”。

---

## 技巧五：io.Copy 零拷贝透传

```go
io.Copy(w, resp.Body)
```

### 优势

- 常驻 buffer ~32KB
- 极低 GC
- 高吞吐
- 无扫描解析

这是 Go 代理实现的性能天花板写法。

---

## Free Router 的代价与隐患

1. **协议盲注风险**
   - 未发送 role
   - 严格客户端可能报错

2. **半路断流无法重试**
   - 只要写入响应头
   - 连接断开即失败
   - 无法重新路由

这是性能与可控性的权衡。

---

# 三、三大核心模块分析

## 3.1 Agent 抽象层

统一接口：

```go
type Agent interface {
    Chat(...)
    ChatWithMedia(...)
}
```

### 三种实现

| 类型 | 特点 |
|------|------|
| HTTP | 云原生无状态 |
| CLI | 每次 exec 子进程 |
| ACP | JSON-RPC 常驻双工通信 |

### ACP 亮点

- `pending map[int64]chan *rpcResponse`
- 自动 permission allow
- 双向异步 RPC

---

## 3.2 工作流 DSL 引擎

示例：

```
step1 @claude 分析代码
save analysis
step2 parallel
branch @gemini @1 找漏洞
branch @qwen @1 写测试
```

### 特性

- 正则解析依赖引用
- WaitGroup 控制并发
- 主 goroutine 独写结果
- 分支只读快照

并发模型设计清晰严谨。

---

## 3.3 iLink 与微信协议逆向

### 长轮询

- 35 秒挂起
- 指数退避
- Cursor 持久化

### CDN 解密

- AES-128-ECB
- PKCS7
- Base64 -> Hex -> 解密

体现扎实的二进制处理能力。

---

# 四、工程之光与技术债

## 4.1 光芒

### ✅ PATH 环境探测

使用：

```bash
zsh -lic which claude
```

解决 daemon 环境无 PATH 问题。

### ✅ sync.Map 原子去重

```go
LoadOrStore
```

### ✅ go:embed 单文件后台

零运维成本。

---

## 4.2 技术债

### ❌ God Object：Handler

- 数百行 HandleMessage
- 无 Middleware
- 扩展困难

### ❌ 正则处理 Markdown

- 容易 ReDoS
- 不处理嵌套结构
- 应改用 AST 解析器

### ❌ Hub 文件锁粒度过粗

- 全局 RWMutex
- 大文件写入会阻塞
- 应改为文件级锁

---

# 五、未来演进方向

## 1️⃣ 引入中间件 Pipeline

```
Sanitize -> Dedup -> Auth -> Dispatch
```

## 2️⃣ 使用 SQLite 替代 JSON 文件