---
date: 2026-05-15
type: process
tags: [research, open-source, version-drift]
---

# 研究开源项目必须 clone 上游，不能用本地已有的 fork/旧 checkout

## 背景
要给 agent 模块产出 `openclaw-reference.md`（对标 `claude-code-reference.md`）。本机 `~/Code/openclaw` 已经存在一份代码，第一反应是直接拿来扫。

## 踩到的坑
派出 4 个并行 Explore agent 扫了一半，准备复检结构时发现：
- 本地副本 remote = `ssh://git@43.130.59.228:2222/FFAIWorkspace/openclaw.git`（内部 Gitea 镜像，**不是上游**）
- 最新提交 2026-05-03，版本号 `2026.3.13`
- 上游 GitHub `openclaw/openclaw` 当天最新版本 `2026.5.14`，提交 `2026-05-15`
- **结构差异 = 重大重构**：`src/` 从 53 子目录涨到 **104**，所有渠道实现（whatsapp/telegram/slack/discord/imessage/line/signal）已从 `src/` **下沉到 `extensions/`**；providers/ 拆成 `model-catalog` + `provider-runtime`；新增 `chat/flows/trajectory/tasks/status/talk/mcp/tools/web-search/web-fetch/image-generation/music-generation/video-generation/memory-host-sdk/...` 一大批模块

如果按旧版输出，整份参考文档会**完全错位**——架构图、可借鉴点、接口契约都对不上。

## 教训
研究开源项目时，第一步永远是：
```bash
git remote -v                       # 是不是 upstream？
git log -1 --format="%ai %h %s"     # 最近提交多久了？
grep version package.json | head -1 # 当前 version
```
然后对照上游：
```bash
curl -s https://api.github.com/repos/<org>/<repo>/releases/latest | jq -r '.tag_name, .published_at'
# 或简单看 GitHub commit page
```

**任意一项触发就 clone 最新**：
- remote 不是上游
- 上次拉取 ≥ 1 个月前
- 上游已发新 major/minor 版本

`git clone --depth=1 https://github.com/<org>/<repo>.git /tmp/<repo>-fresh` 几十秒的事，省得后面整份分析推倒重来。

## 应用范围
- 研究业界参考实现写文档时
- 评估是否要升级依赖库前
- 写 "vs xxx 对比" 类文档时
- 任何 "扫开源代码产文档" 的场景

## 与现有规则的关系
项目 `CLAUDE.md` "memory 可能过期需要验证" 是讲 memory；本条补充**代码副本也会过期**，且本地存在副本反而是陷阱——它降低了"先确认新鲜度"的警觉。

## 副产物：本次产出的文档
`docs/modules/agent/openclaw-reference.md`（2760 行，基于 v2026.5.14）