用途
Architecture Research 用于研究一个代码库或系统的架构，帮助用户理解仓库或系统是如何被构建和组织的，并产出结构图、数据流图以及对设计决策的说明。
触发场景
当用户想要：
- 理解某个仓库或系统是如何架构的
- 获取代码库结构或数据流的图示
- 理解项目中的设计决策与取舍
主要能力与工作流程
1. 阅读源码
克隆或浏览仓库，阅读真实代码——模块结构、入口点、关键抽象，而不是仅依赖 README。重点关注：
- 目录结构与模块边界
- 入口点与公开 API
- 数据模型与存储
- 配置与依赖注入模式
- 构建/部署设置
2. 寻找外部背景
搜索官方文档、博客文章、会议演讲、设计文档、ADR 和社区讨论，以解释架构背后的“为什么”。引用找到的内容；如果是在推断理由（没有来源），需明确说明。
3. 从多个角度解释
至少覆盖以下视角：
| 角度 | 展示内容 |
|---|---|
| 系统概览 | 主要组件及其连接方式 |
| 数据/控制流 | 关键操作（如一次请求、构建、部署）中发生了什么 |
| 设计决策 | 他们选择了什么、显而易见的替代方案，以及为什么 |
4. 生成 ELK 图（并渲染为 SVG）
为每个主要视角生成一个 ELK JSON 图（elkjs 格式），再渲染为 SVG，以便在 markdown 中内联显示。
ELK JSON 结构示例：
{
"id": "root",
"layoutOptions": {
"elk.algorithm": "layered",
"elk.direction": "DOWN",
"elk.spacing.nodeNode": "40"
},
"children": [
{ "id": "node1", "width": 150, "height": 60, "labels": [{ "text": "Component A" }] }
],
"edges": [
{ "id": "e1", "sources": ["node1"], "targets": ["node2"], "labels": [{ "text": "calls" }] }
]
}
渲染为 SVG：该技能使用 diagrams 技能进行渲染，如未安装需先安装：
clawhub install diagrams
然后使用 diagrams 技能的渲染器将 ELK JSON 渲染为 SVG：
# 单个文件
node <diagrams-skill-dir>/scripts/render-elk.mjs diagram.json output.svg
# 批量：文件夹中所有 .json 文件 → svg/ 子文件夹
node <diagrams-skill-dir>/scripts/render-elk.mjs --dir <folder>
# 批量 + PNG（仅 macOS）
node <diagrams-skill-dir>/scripts/render-elk.mjs --dir <folder> --png
将 <diagrams-skill-dir> 替换为已安装的 diagrams 技能目录路径。注意：elkjs 必须安装在运行脚本的本地环境中，完整设置见 diagrams 技能的 SKILL.md。
每张图的工作流程：
- 将 ELK JSON 写入研究文件夹中的
.json文件 - 渲染：
node <diagrams-skill-dir>/scripts/render-elk.mjs diagram.json diagram.svg - 在 markdown 文档中嵌入：
 - 在研究文件夹中同时保留
.json（真实来源）和.svg（渲染结果）
技巧：
- 流/依赖图使用
elk.algorithm: "layered" - 对等关系图使用
elk.algorithm: "force" - 使用复合节点（父节点内嵌子节点）对相关节点进行分组
- 用关系为边添加标签（calls、imports、emits、reads 等）
- 每张图节点数控制在约 20 个以内，必要时拆分为多张
5. 输出
创建一个研究文件夹和 markdown 文档：
<output-dir>/<repo-slug>-architecture/
├── prompt.md # 原始问题
├── architecture.md # 交付物
├── *.json # ELK JSON 源文件（可编辑）
└── *.svg # 渲染后的 SVG 图（嵌入 architecture.md）
将输出放在适合工作区的位置（例如 research/ 目录）。
architecture.md 格式：
# [Repo Name] — Architecture
**Repo:** <url>
**Researched:** <date>
## Overview
<1-2 段总结这是什么东西以及它是如何构建的>
## System Diagram
<文字说明>
## Data/Control Flow
<选择一个关键操作，逐步说明>
## Design Decisions
| Decision | Alternative | Rationale | Source |
|----------|------------|-----------|--------|
| ... | ... | ... | link 或 "inferred" |
## Key Abstractions
<让系统运转的核心类型/接口/模式>
## Sources
<上文引用的文档、文章、演讲链接>
6. 交付
在聊天中发送简要总结（L2 — 75-150 词）并附上关键发现，附上或链接完整文档，如需要可提供 PDF 导出。
适用场景
- 用户需要理解某个仓库或系统的整体架构
- 用户需要代码库结构或数据流图
- 用户需要理解项目中的设计决策与取舍
- 大型仓库的架构梳理（建议先聚焦架构骨架，再按需深入特定子系统）
限制与注意事项
- 不要编造内容。如果找不到某个决策的原因，请标注“inferred”或“no source found”。
- Excalidraw：如果用户要求 Excalidraw 输出而非 ELK，可以尝试，但 ELK JSON 是默认格式。
- Mermaid 回退：如果用户的工具链无法渲染 ELK，可提供 Mermaid 作为回退方案。
- 范围控制：对大型仓库，先聚焦架构骨架，可按请求提供深入特定子系统的选项。