GitHub Repo Teardown — 产品 × 工程深度拆解报告

来源本 Skill 移植自 ClawHub 平台 @jjliu6 的 github-repo-teardown，MIT-0 许可证（可自由使用、修改、再分发，无需署名）。迁入时添加了 context: fork、disable-model-invocation、allowed-tools frontmatter 字段，并调整了输出路径和文件命名规则，核心内容与原 Skill 保持一致。

将任意 GitHub 开源项目拆解为一份排版精美的 HTML 报告，产品人和工程师都能读懂。

Step -1: 确定输出文件名

从 URL 中提取项目名：PROJECT_NAME（如 https://github.com/Foo/hermes-agent → hermes-agent）
获取时间戳：date +"%Y-%m-%d-%H%M"
确定输出路径：{当前工作目录}/{PROJECT_NAME}-teardown-{yyyy-mm-dd-HHmm}.html
写入前 Glob 确认路径不存在，确认后再调 Write

Phase 1: 调研（6 步，可并行执行 2-5 步）

Step 1: Repo 概览

获取 README、目录结构、stars 数、主语言占比、License、最近 commit 日期
查找 ARCHITECTURE.md、DESIGN.md、CONTRIBUTING.md 等架构文档

Step 2: 深度信息源（可与 Step 3-5 并行）

WebSearch 搜索该项目的架构设计讨论、内部实现解析
检索 DeepWiki（如有）、官方博客、作者访谈
抓取 HackerNews / Reddit 的发布帖（搜索 site:news.ycombinator.com {项目名}）

Step 3: 源码侦察（可与 Step 2、4、5 并行）

识别 3-5 个最核心的源文件（通过 GitHub raw URL 获取）
重点关注文件间关系和核心抽象
检查依赖文件（package.json、Cargo.toml、go.mod、requirements.txt 等）

Step 4: 社区信号（可与 Step 2、3、5 并行）

扫描 Issues tab 高赞 issue，识别用户痛点和未满足需求
检查 Discussions 和 Release Notes（最近 3 个版本）
记录贡献者数量和 commit 频率

Step 5: 竞品调研（可与 Step 2、3、4 并行）

WebSearch 搜索替代方案和竞争项目
抓取 2-4 个竞品的 GitHub 页面（stars、语言、定位、差异点）
参考 README 中的 "Compared to" / "Why not X" 章节

Step 6: 综合提炼（依赖前 5 步结果）

确定一句话定义（用于整个报告的核心锚点）
选定贯穿主线的核心类比（类比必须服务于理解，而非装饰）
识别 3 个最重要的设计决策

Phase 2: 输出（10 章 HTML 报告）

CH.1 — 问题定义

解决前 vs. 解决后的场景对比
一个现实世界类比，让非技术读者秒懂
产品洞察：这个项目的存在解锁了什么以前做不到的事

CH.2 — 核心机制

贯穿类比：用一句话解释系统如何运作（CH.1 引入，CH.2-4 延伸使用）
用户视角 vs. 系统内部视角对比
关键文件/函数引用（带技术细节层）

CH.3 — 架构 & 设计决策

架构图（ASCII 或结构化描述），并标注类比对应关系
3-5 个"为什么选 A 而不是 B"的决策卡片，每张含产品层面的理由

CH.4 — 单次操作全链路追踪

选取一个典型用户操作，从触发到响应完整追踪
时间线格式：每步含技术上下文
包含文件路径和函数名

CH.5 — 产品设计亮点

3-5 个设计亮点，每个附产品层洞察
标注可复用的设计模式

CH.6 — 竞品对比 & 市场定位

2-4 个替代方案（含 GitHub 链接、stars、语言、核心差异）
"何时用哪个"的决策指南
定位矩阵或对比表

CH.7 — 风险 & 取舍

2-3 个关键局限性
为获得当前优势，牺牲了什么

CH.8 — 技术快速参考

带注释的源码目录树
技术栈表格
关键依赖说明

CH.9 — 应用场景（三层）

Tier A — 直接使用（2-3 张卡片）用该项目开箱即用能解决的具体问题：谁 / 在什么情况下 / 怎么用

Tier B — 组合使用（1-2 张卡片）将此项目与其他工具结合，产生单独使用时不具备的新能力

Tier C — 借鉴模式（1-2 张卡片）不依赖此库，只移植其设计思想到其他语言/场景

CH.10 — 可迁移心智模型

3-5 条跨项目可用的设计原则
编号，每条 1-2 句
是真正可带走的洞察，不是项目摘要

写作规范

贯穿类比（Throughline Analogy）

CH.1 引入，CH.2-4 持续延伸
类比服务于理解，不是装饰
整份报告始终使用同一个类比框架

双层叙事（Dual-Layer Narrative）

表层（PM 可读）：业务语言，无需技术深度即可理解 80% 内容
深层（工程师可用）：文件路径、函数名、协议细节
两层通过代码字体、灰色背景、标注框做视觉区分

洞察标注（颜色编码）

🔵 蓝色：产品洞察 / 设计原则
🟠 橙色：技术设计教训
🟢 绿色：可复用模式
🟣 紫色：增长 / 商业策略

语气

像高级顾问在做私人简报——直接、在标注的地方发表意见、精炼。

质量检查清单（写入前逐项确认）

一句话定义明确且准确
类比在 CH.1-4 保持一致
各章之间无内容重复
表层叙事 PM 可读
深层叙事工程师可用
CH.6 包含真实 GitHub 链接和"何时用哪个"决策指南
CH.9 每张卡片明确了谁 / 做什么 / 怎么做
CH.10 是真正可迁移的洞察（不是项目总结的复述）
全文洞察均来自该项目的具体特点（无通用套话）

HTML 视觉规范

<!-- 字体 -->
Newsreader（serif，标题）/ Inter（sans-serif，正文）/ JetBrains Mono（代码）
通过 Google Fonts CDN 加载

<!-- 布局 -->
背景色：#faf9f6（温暖白）
最大宽度：820px，居中，充裕留白

<!-- 洞察标注样式 -->
.insight-blue   { border-left: 4px solid #3b82f6; background: #eff6ff; }
.insight-orange { border-left: 4px solid #f97316; background: #fff7ed; }
.insight-green  { border-left: 4px solid #22c55e; background: #f0fdf4; }
.insight-purple { border-left: 4px solid #a855f7; background: #faf5ff; }

<!-- 组件类型 -->
- 类比卡片（analogy-card）
- 竞品对比面板（comparison-panel）
- 流程图（flow-diagram，用 CSS flexbox）
- 决策卡片（decision-card，含"问题/结论/原因/代价"四字段）
- 时间线（timeline）
- 场景卡片（scenario-card，含 Tier 标签）
- 技术参考块（tech-reference）

完整 HTML 须为单文件（inline CSS），不依赖外部资源（字体除外）。

teardown-github