tomevault-io Git 项目深度分析技能
深度分析开源项目并生成专业架构报告。报告是有深度洞察的技术研究，读完后读者能理解业务问题、掌握架构设计、产生自己的思考。
When to Use
- 分析开源项目的架构和设计
- 对比两个同类项目的设计差异
- 深入研究一个框架或库的实现思路
When NOT to Use
- 简单的代码问题或调试
- 单文件分析或代码审查
- 不涉及架构层面的代码修改
输出语言
默认中文。如果用户使用其他语言提问，则跟随用户语言。
核心原则
1. 业务视角优先
从"这个项目解决什么问题"出发，不是"这个文件里有什么函数"。
| 不要 | 要 |
|---|---|
handleRequest(ctx) 函数接收一个 Context 参数... |
请求进来后，系统会经过鉴权、限流、路由分发三个阶段... |
interface MessageQueue { push(); pop() } |
模块间通过消息队列解耦，生产者只管投递，消费者按优先级拉取 |
2. 抽象层次把控：不贴代码，讲设计
默认在设计模式和架构层面描述，非必要情况下不贴原始代码。重点突出流程、逻辑、设计思想，用架构图（Mermaid）、流程图、表格来表达，而非代码片段。只有设计特别精妙、项目自创独特概念、或实现是核心卖点时才展示代码，且必须先用自然语言解释。
3. 全局关联
每个局部分析都必须连接到项目整体设计哲学——这是区分"代码说明书"和"架构分析"的关键。详见 analysis-guide.md 的全局关联章节。
4. 启发性写作
目标是让读者学到东西、产生思考，而不是获得一份代码说明书。像资深工程师在白板前讲解——有观点、有推理、有对比。详见 analysis-guide.md 的启发性写作章节。
5. 深度洞察：Why > What（强制）
每个设计决策必须解释动机、权衡、替代方案代价。描述"是什么"只是起点，解释"为什么"才是分析的价值所在。每个核心模块和整体架构都要回答：
- 为什么这样设计？ 不只是"用了什么模式"，而是"为什么适合这个场景"
- 如果不这样会怎样？ 替代方案的代价
- 与业界最佳实践的差距？ 领先之处和改进空间
- 如果让你重新设计？ 展示更深层理解
- 系统性设计哲学？ 贯穿整个项目的风格（如"约定优于配置"、"零成本抽象"）
示例：
❌ 路由系统采用了中间件模式，支持链式调用。
✅ 路由系统选择了洋葱模型而非线性管道。线性管道实现更简单，但洋葱模型让每个中间件都能同时处理请求和响应阶段——这对日志、计时、错误恢复至关重要。Express 当年选择线性模型，后来不得不用各种 hack 处理响应后逻辑，Koa 吸取教训才转向洋葱模型。如果让我重新设计，我会考虑加入中间件依赖声明，让框架自动排序——这是 Fastify 的做法，能避免顺序导致的隐蔽 bug。
补充要求
- 代码为准 — 一切结论有代码依据，标注
文件路径或文件路径:行号范围，禁止模糊表述 - 有温度 — 像资深工程师给新同事做 onboarding，加入主观评价和建议，避免 AI 味套话
- 重点深入次要简略 — 核心创新点深入分析，通用工具函数一句话带过
- 批判性思考 — 与业界实践对比，指出真实问题，不回避缺陷。参考 analysis-guide.md
- 行文流畅易懂 — 整体行文需要流畅自然，让入门的工程师也能看懂并学习到东西。避免过于学术化或堆砌术语
- 拒绝流水账 — 每个模块要体现深度细节，不能一句带过或泛泛而谈。每个模块如果合适要加上对应的 Mermaid 架构图，让读者看完有启发、能学到设计精髓
分析工作流
灵活性原则：以下所有阶段和章节都是建议性的指引，不是必须严格执行的清单。agent 应根据当前分析的项目特性动态决策——如果某个阶段或环节对当前项目没有意义，可以跳过或简化。一切以最终报告的质量为准。
阶段 1: 项目获取与初始化
- 解析用户输入（支持
owner/repo、GitHub/GitLab/Gitee URL、本地路径、项目名称） - 创建工作区：在用户主目录下创建
repo-analyses/${REPO_NAME}-{YYYYMMDD}目录作为$WORK_DIR（跨平台：macOS/Linux 使用$HOME，Windows 使用$USERPROFILE或$HOME） - 如果用户提供本地路径则跳过 clone，否则
git clone --depth=1克隆仓库 - 获取基本元数据（Star、Fork、贡献者、代码统计）
阶段 2: 项目规模评估与分析模式选择
- 统计有效代码行数（排除可跳过代码），按模块列出分布
- 可跳过代码定义：测试代码、构建/部署配置（Dockerfile、CI yaml 等）、自动生成代码（protobuf 生成、lock 文件等）、示例/文档代码
- 使用
find+wc -l或cloc等工具统计，按顶层目录分组
- 向用户报告代码规模，使用 AskUserQuestion 让用户选择分析模式：
| 模式 | 核心模块覆盖率 | 次要模块覆盖率 | 适用场景 |
|---|---|---|---|
| 快速分析 | ≥30% | ≥10% | 快速了解项目全貌 |
| 标准分析（推荐） | ≥60% | ≥30% | 常规架构分析 |
| 深度分析 | ≥90% | ≥60% | 深入研究每个设计决策 |
- 将代码规模统计和用户选择的分析模式写入
drafts/03-plan.md，后续阶段据此控制分析深度
覆盖率计算规则：
- 覆盖率 = 通过 Read 工具实际请求过的行范围之并集 / 文件总行数
- 对于大文件（>500 行），必须分段读取，确保以下关键段落被覆盖：
- 文件头部的类型定义和导入（前 100 行）
- 核心业务逻辑函数（通过目录结构或函数名定位）
- 文件尾部的测试代码（如有）
- 只读了文件的一小部分（<30%）不计入覆盖率，视为「未读」
- 自动生成代码（proto 生成、lock 文件等）可降低覆盖率要求：扫描结构即可，不需要逐行阅读
阶段 3: 外部调研 + 项目文档研读（先搜再读）
- WebSearch 搜索项目评价、对比、架构讨论（至少 3-5 次搜索）
- 遍历项目官网（如果存在）：
- 从 README 或 GitHub 页面提取官网 URL
- 使用 WebFetch/tavily_crawl 遍历官网关键页面（首页、Features、Use Cases、Comparison、Blog 等）
- 重点提取：产品定位语（tagline）、典型使用场景、官方竞品对比、用户案例/testimonial
- 官网内容往往是理解"为什么需要这个产品"的最佳来源，比代码和技术文档更直接
- 通读项目自带文档：
- 架构文档（
architecture/、docs/、design/等目录） - CONTRIBUTING.md、AGENTS.md 等开发者指引
- RFC、ADR（Architecture Decision Records）、设计提案等
- 这些文档往往包含开发者的设计思路、权衡取舍、历史决策背景，是理解"为什么这样设计"的第一手资料
- 将文档中的关键设计决策和思路摘录到调研笔记中
- 架构文档（
- 整理调研发现写入
drafts/03-research.md，必须包含以下结构化段落（信息不足则标注"未找到"）：- 项目解决的核心问题：用 1-3 个具体场景描述痛点（谁、在什么情况下、遇到什么问题、现有方案为什么不够）
- 竞品/同类项目对比：列出 3-5 个最相关的竞品，说明各自定位差异和技术路线差异
- 为什么需要单独做这个项目：不能用现有方案组合解决吗？这个项目的独特价值主张是什么？
- 项目背后的组织动机（如适用）：商业公司的战略考量、开源社区的生态定位
- 生成分析规划写入
drafts/03-plan.md
阶段 4: 项目特征识别 + 自适应提问
这是核心阶段。不使用固定问题列表，而是根据项目特征生成针对性问题。
步骤：
快速扫描：扫描入口文件、目录结构、依赖声明、项目文档、README
识别项目核心特征：
- 项目类型与定位（库/框架/应用/工具）
- 规模与成熟度
- 设计风格信号（类型体操、极简 API、配置驱动等）
- 技术栈特点（新兴技术、多语言、特定运行时）
- 社区定位（核心基础设施、应用层工具、教学项目等）
从特征中提炼问题：根据观察到的项目特征生成针对性问题。问题应该帮助聚焦分析方向，而不是走流程
思维过程——每个观察都可能暗示一个值得问用户的问题：
- 观察到的技术选择 → 问动机（不常见的技术组合？自己实现了通常用第三方库解决的功能？）
- 观察到的架构特征 → 问优先级（性能优化痕迹？复杂的插件/扩展系统？）
- 观察到的设计张力 → 问取舍（简单性 vs 灵活性？向后兼容的包袱？）
- 观察到的项目定位 → 问受众（目标用户是谁？在生态中是替代还是填补空白？）
维度启发——什么样的项目特征暗示什么样的分析角度：
- 小而精的库 → API 设计哲学、边界划定；大型框架 → 模块化策略、向后兼容、生态治理
- 使用新兴技术 → 为什么选择它、迁移成本；多语言/多范式 → 语言边界设计
- 大量泛型/类型体操 → 类型安全 vs 复杂度权衡；极简 API → 简单性如何实现、牺牲了什么
好问题的特征：具体（基于代码中观察到的现象）、有分析价值（答案会影响分析方向）、用户能答（问关注点和偏好，不问需要深入代码才能回答的技术细节）、不重复（不问通过代码就能回答的问题）
向用户提问：使用 AskUserQuestion 工具向用户提问，每次不超过 3 个问题
- 其中一个问题应确认报告开头的详略程度：对于知名项目，用户可能不需要冗长的产品介绍和竞品对比，只想直接进入代码分析。询问用户是否需要场景化引入和竞品定位章节，还是直接从项目全景和代码分析开始
不限轮次：可多轮提问直到方向明确，分析过程中发现新的关键分歧点可以再追问
关键原则：问题完全由项目特征驱动，不预设类别。不同项目应该产生完全不同的问题。
阶段 5: 动态报告结构设计
根据用户回答 + 项目特征，设计本次报告的章节结构。
步骤：
- 综合信息：结合阶段 3 的调研、阶段 4 的项目特征和用户回答
- 设计章节结构：不使用固定模板，但必须满足骨架约束（见下方）
- 输出报告大纲：将设计好的报告大纲输出给用户确认后再继续
- 识别模块：追踪核心数据流，识别 N 个逻辑模块（按业务功能划分），分为核心模块和次要模块
- 设计模块叙事线：确定模块在报告中的呈现顺序和过渡逻辑，不按目录结构排列，而是按读者理解的最佳路径组织：
- 选择叙事主线：数据流驱动（请求从进入到离开经过哪些模块）、分层驱动（从底层到上层）、或问题驱动（从核心问题到解决方案逐层展开）
- 每两个相邻模块之间写明过渡逻辑：上一个模块的输出/问题/局限 → 引出下一个模块的必要性
- 将叙事线写入
drafts/05-modules-plan.md，格式示例：模块 A →[A 的输出需要 B 来消费]→ 模块 B →[B 解决了 X 但引出 Y 问题]→ 模块 C
- 写入计划：输出模块清单和报告大纲写入
drafts/05-modules-plan.md
骨架约束（报告不规定具体章节，但必须满足）：
- 有场景化问题引入（用具体场景讲清楚项目解决什么问题、现有方案的不足、为什么需要这个项目——素材来自阶段 3 调研笔记）。注意：如果用户在阶段 4 表示不需要冗长介绍（如项目已经很知名），可以精简或跳过此章节，直接从项目全景开始
- 有竞品定位（与同类项目的关键差异，不是功能清单对比，而是设计哲学和技术路线的差异）。注意：同上，用户可选择跳过
- 有项目全景（让读者快速理解项目是什么、解决什么问题）
- 有深度分析（核心设计的 Why、权衡、与业界对比）
- 有评价与启发（诚实的优缺点、读者能从中学到什么）
- 有架构可视化（Mermaid 图表）
- 所有结论有代码依据
阶段 6: 并行深度分析（subagent 团队）
必须使用 Agent 工具并行启动 subagent。参考 module-analysis-guide.md 中的 prompt 模板和协作规范。
每个 subagent 的 prompt 中必须包含项目整体设计哲学和全局视角要求，确保模块分析不是孤立的。
每个 subagent 的 prompt 中还必须包含该模块的叙事上下文（来自阶段 5 的叙事线设计）：前一个模块讲了什么、读者带着什么问题进入本模块、本模块需要为下一个模块铺垫什么。subagent 应在草稿开头用 1-2 句衔接前一模块，草稿结尾用 1 句铺垫下一模块。
每个 subagent 的 prompt 末尾必须附加覆盖率要求（参考 module-analysis-guide.md 中的覆盖率要求段落），告知当前分析模式和最低覆盖率目标，要求草稿末尾附覆盖率明细表。
subagent 写入策略： 对于大模块（文件总行数 > 5000 行），必须在 subagent prompt 中要求增量写入草稿：
- 每完成一个子系统/子模块的分析后，立即将该部分写入草稿文件
- 第一个子系统用 Write 创建文件，后续子系统用 Edit 追加
- 不要等全部文件读完再一次性写入
- 覆盖率明细表在最后追加
主 agent 等待纪律：
- subagent 启动后，主 agent 不得阅读 subagent 负责的源码文件
- 主 agent 在等待期间应专注于：阅读项目文档（architecture/、docs/）、外部调研、设计报告骨架、准备阶段 8 的融合框架
- 判断 subagent 是否卡住的标准：output 文件超过 5 分钟无新增行。只有确认卡住后，主 agent 才可以接管该模块的分析
- 严禁提前合并：必须等所有 subagent 全部完成后，再开始阶段 7 和阶段 8 的合并工作。不要在部分 subagent 还在运行时就开始写最终报告
阶段 7: 交叉验证 + 质量管控（主 agent）
7.1 覆盖率门控：
- 读取每个
drafts/06-module-*.md末尾的覆盖率明细表 - 快速检查：每个草稿末尾是否有覆盖率表、合计行是否标注达标（✅/❌）
- 只有标注 ❌ 或缺少覆盖率表的模块才需要深入检查
- 不达标模块 → 主 agent 自动补充阅读未覆盖的关键文件，将补充发现追加到对应草稿
- 补充后仍不达标 → 向用户报告哪些模块未达标及原因（如文件过大、二进制文件等）
7.2 抽查验证：
- 从每个核心模块草稿中选取 2-3 个关键结论
- 回到源码逐行验证结论准确性
- 发现偏差则修正草稿中的对应内容
7.3 交叉验证：
- 交叉验证【待主 agent 验证】标注的跨模块结论
- 综合回答探索问题，识别跨模块设计模式
- 验证全局关联：每个模块的分析是否都连接到了项目整体设计哲学
- 写入
drafts/07-cross-validation.md
阶段 8: 多源融合与最终报告（主 agent）
- 提炼架构洞察和系统性设计哲学
- 基于阶段 3 调研结果深化竞品对比（仅在阶段 3 信息不足时补充搜索）
- 提出"如果重新设计"的改进建议
- 写入
drafts/08-insights.md - 多源融合：以阶段 5 设计的报告章节结构为骨架，从各草稿中抽取内容填充。同一概念在多个草稿中出现时，取最详细版本并补充其他版本独有信息。融合后消除所有"见草稿 X"、"详见附录"等跳转指示
- 叙事连贯：按阶段 5 设计的叙事线组织模块章节。每个模块章节的开头必须有 1-2 句过渡，连接上一个模块的结论或问题。避免"接下来我们分析 X 模块"这种生硬转折，改用自然过渡（如"Gateway 完成了请求的认证和路由，但它只负责'谁可以进来'，不负责'进来之后能做什么'。这个行为控制的职责，由策略引擎承担。"）
- 分段写入：最终报告通常超过 500 行，先 Write 前几个章节（200-300 行），后续用 Edit 追加，每次追加前 Read 确认末尾位置
- 覆盖率汇总：将覆盖率数据汇总写入
drafts/08-coverage.md（不放入最终报告）- 数据直接从各 subagent 草稿末尾的覆盖率明细表中提取，不需要主 agent 重新计算
- 如果主 agent 在阶段 7 补充了阅读，将补充的行数加到对应模块的「已读行数」中
- 汇总表格式：
| 模块 | 类型 | 文件数 | 有效代码行 | 已读行数 | 覆盖率 | 达标 |
|---|---|---|---|---|---|---|
| ... | 核心/次要 | ... | ... | ... | ...% | ✅/❌ |
- 汇总生成最终报告（不包含覆盖率章节）
草稿文件清单
所有中间过程保存到 $WORK_DIR/drafts/：
| 阶段 | 文件 |
|---|---|
| 3 | 03-research.md, 03-plan.md |
| 5 | 05-modules-plan.md |
| 6 | 06-module-{name}.md（subagent 生成） |
| 7 | 07-cross-validation.md |
| 8 | 08-insights.md, 08-coverage.md |
文件写入分块，单次不超过 300 行或 15KB。
特殊场景
- 超大型项目（>50000 行）：优先分析核心模块，使用 Agent 并行分析
- 对比分析模式：两个项目分别完成阶段 1-4，然后在阶段 5 设计对比式报告结构，骨架约束中增加"设计决策对比"和"选型建议"
输出要求
- 最终报告为单一 markdown 文件：
$WORK_DIR/ANALYSIS_REPORT.md - 大量使用 Mermaid 图表展示架构、流程、数据流
- 面向需要理解业务架构的开发者
- 亮点和问题的评价思维框架参考 analysis-guide.md
- 分析哲学和深度标准参考 analysis-guide.md
Source: yzddmr6/repo-analyzer — distributed by TomeVault.