10分钟读懂陌生源码:用 Claude & OpenClaw Skill实现项目架构分析工作流

arch-analyzer/
└── SKILL.md          ← 就这一个文件

---
name: arch-analyzer
description: >
  Analyze open-source project architecture and generate a detailed Chinese technical report.
  深度分析开源项目技术架构，生成中文架构拆解报告。
  Triggers: "分析架构" "拆解项目" "analyze architecture" "dissect repo"
  "帮我看看这个项目怎么实现的" "分析一下这个 repo" "analyze this codebase"
  "项目架构分析" "源码分析" "code walkthrough" "technical deep dive"
  Supports: TypeScript/JavaScript, Python, Go, Rust, Java, C/C++, Swift,
  Kotlin, Bash/Shell, HTML/CSS, and config-only projects (Markdown/JSON/YAML/XML).
  Output: structured Chinese Markdown report covering architecture overview,
  core subsystem analysis, design pattern identification, and data flow.
version: "1.1"
# —— OpenClaw-compatible metadata ——
tools:
  - read
  - write
  - exec
env: {}
---

# 开源项目架构深度分析 Skill

> **一句话定位**：对任意语言的开源项目做系统性源码级架构分析，产出一份聚焦
> **HOW（怎么实现）** 而非 WHAT（有什么功能）的中文技术拆解报告。

---

## 总览：五阶段分析流水线

```
阶段 1        阶段 2          阶段 3            阶段 4          阶段 5
获取代码 ──→ 目录扫描 ──→ 子系统深度阅读 ──→ 模式识别 ──→ 报告生成
 clone       建地图        逐模块源码阅读      架构风格        Markdown
 环境感知     入口识别       七问清单           数据流          中文输出
```

---

## 阶段 1：项目获取与环境感知

### 1.1 获取代码

```bash
# 远程仓库
git clone --depth 1  /tmp/target-repo && cd /tmp/target-repo

# 本地项目——直接 cd 进去即可
```

### 1.2 环境感知矩阵

依次检查下表中的文件，**命中即标记该语言/框架**。一个项目可能命中多行（多语言混合项目）。

| 探针文件 | 语言 / 生态 | 重点关注 |
|---------|------------|---------|
| `package.json` | **TypeScript / JavaScript** | dependencies · scripts · `"type":"module"` |
| `tsconfig.json` | TypeScript | target · paths · composite |
| `pyproject.toml` / `setup.py` / `requirements.txt` | **Python** | 依赖 · 入口 · build-backend |
| `go.mod` | **Go** | module path · Go 版本 · 依赖 |
| `Cargo.toml` | **Rust** | workspace members · features · edition |
| `pom.xml` / `build.gradle` / `build.gradle.kts` | **Java / Kotlin** | 多模块 · plugins · Spring/Ktor |
| `CMakeLists.txt` / `Makefile` (含 `.c`/`.cpp`/`.h`) | **C / C++** | 编译目标 · 库链接 · 子目录 |
| `Package.swift` / `*.xcodeproj` | **Swift** | targets · dependencies · platforms |
| `*.sh` / `justfile` / `Taskfile.yml` | **Bash / Shell** | 入口脚本 · 构建流程 |
| `index.html` / `vite.config.*` / `next.config.*` | **HTML / 前端** | 框架 · 路由 · 构建 |
| 仅 `*.md` / `*.json` / `*.yaml` / `*.xml` | **纯配置项目** | schema · 用途 · 关联工具 |
| `Dockerfile` / `docker-compose.yml` | 容器化 | 服务拓扑 · 端口映射 · volume |
| `.github/workflows/` / `.gitlab-ci.yml` | CI/CD | 构建步骤 · 测试 · 部署目标 |

```bash
# 快速探针（一行命令判断语言）
ls package.json tsconfig.json pyproject.toml go.mod Cargo.toml \
   pom.xml build.gradle CMakeLists.txt Package.swift 2>/dev/null
```

---

## 阶段 2：目录结构扫描

**目标：建立项目的"地图"，识别入口和模块边界。**

```bash
# 通用目录树（排除噪音目录）
find . -type f \
  -not -path '*/node_modules/*' \
  -not -path '*/.git/*' \
  -not -path '*/dist/*' -not -path '*/build/*' \
  -not -path '*/__pycache__/*' \
  -not -path '*/vendor/*' -not -path '*/.next/*' \
  -not -path '*/target/*' -not -path '*/.build/*' \
  -not -path '*/Pods/*' -not -path '*/.gradle/*' \
  -not -name '*.lock' -not -name '*.map' \
  -not -name '*.o' -not -name '*.a' -not -name '*.so' \
  -not -name '*.class' -not -name '*.jar' \
  | head -300

# 按扩展名统计文件数量
find . -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20

# 代码行数概览（需要 cloc 或 wc 替代）
find . -name '*.ts' -o -name '*.py' -o -name '*.go' -o -name '*.rs' \
  -o -name '*.java' -o -name '*.kt' -o -name '*.c' -o -name '*.cpp' \
  -o -name '*.swift' -o -name '*.sh' | xargs wc -l 2>/dev/null | tail -1
```

**从目录树中识别（通用清单）：**

| 要素 | 常见路径 |
|------|---------|
| 入口点 | `main.*` · `index.*` · `cmd/` · `bin/` · `src/main.*` · `app/` |
| 核心模块 | `src/` · `lib/` · `pkg/` · `internal/` · `core/` · `modules/` |
| 配置 | `config/` · `.env*` · `settings/` · `resources/` |
| 测试 | `tests/` · `__tests__/` · `*_test.*` · `spec/` · `test/` |
| 文档 | `docs/` · `ARCHITECTURE.md` · `DESIGN.md` · `ADR/` |

> **优先阅读**：如果存在 `ARCHITECTURE.md`、`DESIGN.md` 或 `docs/architecture/`，先读它们——作者自己写的架构说明比 AI 猜的准。

---

## 阶段 3：核心子系统深度阅读

### 3.1 入口点追踪（所有语言通用）

```
读入口文件 → 找 import / require / use / include → 追踪核心模块 → 理解初始化顺序
```

### 3.2 按语言选择分析命令

根据阶段 1 识别的语言，选择对应的 grep 策略。**混合语言项目需要组合使用多组命令。**

#### TypeScript / JavaScript
```bash
grep -rn "export " src/ --include="*.ts" --include="*.tsx" --include="*.js" | head -50
grep -rn "class \|interface \|type " src/ --include="*.ts" | head -50
grep -rn "emit\|\.on(\|subscribe\|addEventListener" src/ --include="*.ts" | head -30
grep -rn "async \|await \|Promise" src/ --include="*.ts" | head -30
```

#### Python
```bash
grep -rn "^class " --include="*.py" | grep -v __pycache__ | head -50
grep -rn "^def \|^async def " --include="*.py" | head -50
grep -rn "@.*\ndef \|@.*\nclass " --include="*.py" | head -30
grep -rn "if __name__" --include="*.py" | head -10
grep -rn "app\.\|router\.\|blueprint" --include="*.py" | head -20  # Web 框架
```

#### Go
```bash
grep -rn "type.*interface {" --include="*.go" | head -50
grep -rn "type.*struct {" --include="*.go" | head -50
grep -rn "func main\|func init" --include="*.go" | head -20
grep -rn "go func\|make(chan\|<-\|select {" --include="*.go" | head -30
grep -rn "http\.Handle\|grpc\.\|mux\." --include="*.go" | head -20
```

#### Rust
```bash
grep -rn "^pub struct \|^pub enum \|^pub trait " --include="*.rs" | head -50
grep -rn "^pub fn \|^pub async fn " --include="*.rs" | head -50
grep -rn "impl " --include="*.rs" | head -50
grep -rn "tokio\|async_std\|#\[tokio::main\]" --include="*.rs" | head -20
grep -rn "mod \|use " src/ --include="*.rs" | head -30
```

#### Java / Kotlin
```bash
grep -rn "^public class \|^public interface \|^abstract class " --include="*.java" | head -50
grep -rn "@RestController\|@Service\|@Repository\|@Component" --include="*.java" | head -30
grep -rn "^class \|^interface \|^object \|^data class " --include="*.kt" | head -50
grep -rn "@Route\|@Get\|@Post\|fun main" --include="*.kt" | head -20
```

#### C / C++
```bash
grep -rn "^struct \|^class \|^typedef " --include="*.h" --include="*.hpp" | head -50
grep -rn "^int main\|^void main" --include="*.c" --include="*.cpp" | head -10
grep -rn "#include " --include="*.c" --include="*.cpp" | sort -u | head -30
grep -rn "pthread_\|std::thread\|std::async\|fork(" --include="*.c" --include="*.cpp" | head -20
```

#### Swift
```bash
grep -rn "^class \|^struct \|^protocol \|^enum " --include="*.swift" | head -50
grep -rn "^func \|^@main\|@objc " --include="*.swift" | head -30
grep -rn "async \|await \|Task {" --include="*.swift" | head -20
```

#### Kotlin (Android / Multiplatform)
```bash
grep -rn "^class \|^data class \|^sealed \|^interface " --include="*.kt" | head -50
grep -rn "@Composable\|@AndroidEntryPoint\|@HiltViewModel" --include="*.kt" | head -20
```

#### Bash / Shell
```bash
find . -name "*.sh" -exec head -5 {} \; | head -40      # 查看 shebang 和说明
grep -rn "function \|^[a-z_]*() " --include="*.sh" | head -30
```

#### HTML / 前端 (React / Vue / Svelte 等)
```bash
grep -rn "export default\|export function\|defineComponent" --include="*.vue" --include="*.svelte" --include="*.jsx" --include="*.tsx" | head -30
grep -rn "createRouter\|createApp\|ReactDOM.render\|hydrateRoot" --include="*.ts" --include="*.js" | head -10
```

#### 纯配置项目 (Markdown / JSON / YAML / XML)
```bash
# 统计文件类型分布
find . -name '*.md' -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.xml' | wc -l
# 查看 JSON/YAML schema
find . -name '*.schema.json' -o -name '*.json' | head -10 | xargs head -20 2>/dev/null
# 查看核心 Markdown 文件结构
find . -name '*.md' | head -20
```

### 3.3 每个子系统的"七问清单"

对每个识别出的子系统，回答以下 7 个问题：

| # | 问题 | 回答要点 |
|---|------|---------|
| 1 | **它解决什么问题？** | 一句话概括 |
| 2 | **核心数据结构？** | 关键 type / interface / struct / class |
| 3 | **控制流？** | 入口 → 中间处理 → 输出，画箭头 |
| 4 | **并发模型？** | 单线程 / 线程池 / goroutine / async-await / Actor |
| 5 | **状态存储？** | 内存 / 磁盘文件 / SQLite / PostgreSQL / Redis |
| 6 | **错误处理？** | 重试 / 降级 / 熔断 / panic-recover / Result |
| 7 | **精巧设计？** | 值得专门讲的亮点或创新 |

---

## 阶段 4：关系与模式识别

阅读完各子系统后，从全局视角识别以下模式：

**架构风格清单：**
- 整体风格：单体 / 微服务 / Monorepo 多包 / 插件式 / Hub-and-Spoke / 管道-过滤器 / 分层
- 通信方式：同步 RPC / REST / gRPC / 事件驱动 / WebSocket / 消息队列 / Channel
- 数据流：单向 / 双向 / 发布-订阅 / CQRS / Event Sourcing
- 持久化：文件系统 / SQLite / PostgreSQL / MySQL / Redis / S3 / 自定义
- 扩展机制：插件 / Hook / 中间件 / 装饰器 / SPI / Protocol Extension
- 安全边界：沙箱 / 权限层 / OAuth / RBAC / 加密通道

**模块关系速写格式（ASCII 即可）：**
```
模块A ──→ 模块B ──→ 模块C
  │                   ↑
  └──→ 模块D ────────┘
```

---

## 阶段 5：报告生成

### 报告模板

```markdown
# [项目名] 技术架构深度拆解：[N] 个核心子系统源码解析

[作者名]
[日期]

## 关于本文
这篇文章由 AI 自动分析 [项目名] 开源代码库后生成，聚焦 HOW（实现细节）
而非 WHAT（功能介绍）。[作者名] 对结构和关键判断做了审校，
但主体内容来自 AI 的源码阅读。
这本身就是"AI 辅助深度研究"的一个实际案例。

## 1. 整体架构概览
[一段话：项目是什么、语言/框架/运行时、核心设计模式]
[ASCII 架构图]

## 2. [子系统A]：[一句话定位]
### 2.1 [子模块]
[实现细节 + 源码路径引用]
### 2.2 [子模块]
...

## 3. [子系统B]
...

（按重要性排序，逐个拆解所有核心子系统）

## N. 关键设计理念总结
### N.1 [理念/模式名]
[解释设计选择的原因、权衡和效果]
### N.2 [理念/模式名]
...
```

### 报告质量标准（6 条红线）

| # | 标准 | 说明 |
|---|------|------|
| 1 | **源码路径** | 关键实现必须引用文件路径，如 `src/gateway/router.ts:42` |
| 2 | **具体数字** | 端口、超时、队列深度、默认值——不说"一个数字"，要给出实际值 |
| 3 | **类比解释** | 用已知系统做类比，如"类似 Nginx upstream" |
| 4 | **ASCII 图表** | 架构关系用文字图表，不依赖外部绘图工具 |
| 5 | **设计权衡** | 解释"为什么选 A 不选 B"，不只描述 A |
| 6 | **中文 + 术语** | 正文用通俗中文，技术术语保留英文原文 |

### 注意事项

- **不要猜测**——源码里看不到的就写"未在源码中发现"
- **区分意图和实现**——README 写的功能可能尚未实现，以源码为准
- **关注注释**——TODO / FIXME / HACK / XXX 揭示技术债务
- **聚焦关键路径**——大型项目不必分析每个文件
- **优先读架构文档**——ARCHITECTURE.md / DESIGN.md / ADR/ 比猜测可靠
- **注意 monorepo**——先理清包的边界和依赖关系，再逐包分析

---
name: arch-analyzer
description: >
  Analyze open-source project architecture and generate a detailed Chinese
  technical report.
  深度分析开源项目技术架构，生成中文架构拆解报告。
  Triggers: "分析架构" "拆解项目" "analyze architecture" "dissect repo"
  "帮我看看这个项目怎么实现的" "分析一下这个 repo" ...
version: "1.1"
tools:
  - read
  - write
  - exec
env: {}
---

第 1 步"这是什么？" → 第 2 步"有哪些东西？" → 第 3 步"每块怎么实现？"
→ 第 4 步"它们之间什么关系？" → 第 5 步"写成文档"

看到 package.json   → 标记为 TypeScript/JavaScript
看到 go.mod         → 标记为 Go
看到 Cargo.toml     → 标记为 Rust
看到 CMakeLists.txt → 标记为 C/C++
...

ls package.json tsconfig.json pyproject.toml go.mod Cargo.toml \
   pom.xml build.gradle CMakeLists.txt Package.swift 2>/dev/null

# 项目级安装（仅当前项目可用）
mkdir -p .claude/skills/arch-analyzer
cp SKILL.md .claude/skills/arch-analyzer/SKILL.md

# 全局安装（macOS / Linux）
mkdir -p ~/.claude/skills/arch-analyzer
cp SKILL.md ~/.claude/skills/arch-analyzer/SKILL.md

分析一下 https://github.com/openclaw/openclaw 这个项目的架构

Analyze the architecture of https://github.com/openclaw/openclaw

🔍 阶段 1/5：获取代码 & 环境感知

> git clone --depth 1 https://github.com/openclaw/openclaw /tmp/target-repo
Cloning into '/tmp/target-repo'... done.

> ls /tmp/target-repo/package.json /tmp/target-repo/tsconfig.json ...
package.json   tsconfig.json
→ 识别为 TypeScript ESM 项目

> cat /tmp/target-repo/package.json | head -20
→ Node.js 22+, pnpm 构建, 可选 Bun

────────────────────────────────────────

🗺️ 阶段 2/5：目录结构扫描

> find /tmp/target-repo -type f -not -path '*/node_modules/*' ...
→ 发现 247 个源文件
→ 识别到 14 个核心模块目录

────────────────────────────────────────

📖 阶段 3/5：子系统深度阅读（最耗时，约 8-10 分钟）

  正在分析 [1/14] Gateway (src/gateway/)...
    ✓ WebSocket 服务器，默认端口 18789
    ✓ 事件驱动，非轮询
    ✓ JSON Schema 验证所有 frame

  正在分析 [2/14] Session Router (src/session/)...
    ✓ 层级化 session key：agent:main:whatsapp:direct:+155...
    ...

  正在分析 [3/14] Lane Queue (src/queue/)...
    ✓ 纯 TypeScript + Promises，无外部依赖
    ✓ per-session lane 保证并发安全
    ...

  （继续分析其余 11 个子系统）

────────────────────────────────────────

🧩 阶段 4/5：架构模式识别

→ Hub-and-Spoke 模式
→ 事件驱动 + WebSocket 通信
→ 文件系统 + SQLite 持久化
→ 插件 Hook 扩展机制
→ 容器沙箱安全边界

────────────────────────────────────────

📝 阶段 5/5：生成报告

✅ 报告已保存到 openclaw-architecture-report.md
   覆盖 14 个子系统，8,200 字

分析 openclaw 项目中 memory 子系统的实现，重点看混合搜索是怎么做的

分析 openclaw 的 Channel Adapter 设计，和 Matrix 的 bridge 架构做对比

分析我当前目录下的项目架构

分析 openclaw 最近 30 天的 commit，找出架构上的重大变更

# 方式一：工作区 skills（最高优先级）
mkdir -p ~/your-workspace/skills/arch-analyzer
cp SKILL.md ~/your-workspace/skills/arch-analyzer/SKILL.md

# 方式二：managed skills（全局可用）
mkdir -p ~/.openclaw/skills/arch-analyzer
cp SKILL.md ~/.openclaw/skills/arch-analyzer/SKILL.md

# 方式三：bundled skills（npm 包自带，最低优先级）
# 这个位置通常是项目维护者打包的，用户不需要手动操作

帮我分析一下 openclaw 这个项目的技术架构

@mybot 拆解一下 https://github.com/openclaw/openclaw 的源码

analyze the architecture of openclaw

openclaw chat "分析 openclaw 项目架构"

Profile Policy → Provider-Profile Policy → Global Policy
→ Global-by-Provider Policy → Agent Policy
→ Agent-by-Provider Policy → Group Policy
→ 再叠加 Sandbox 限制

每周一早上 9 点，分析 openclaw 项目的最新提交，和上次分析对比，
告诉我架构上有什么变化

第一轮：分析 openclaw 的 Gateway、Session Router、Lane Queue
第二轮：分析 Agent Runtime 和 Model Failover
第三轮：分析 Memory 系统和 Skills 系统
第四轮：分析 Channel Adapters 和安全体系