Repo Analyzer

Git 项目深度分析技能

深度分析开源项目并生成专业架构报告。报告是有深度洞察的技术研究，读完后读者能理解业务问题、掌握架构设计、产生自己的思考。

When to Use

• 分析开源项目的架构和设计
• 对比两个同类项目的设计差异
• 深入研究一个框架或库的实现思路

When NOT to Use

• 简单的代码问题或调试
• 单文件分析或代码审查
• 不涉及架构层面的代码修改

输出语言

默认中文。如果用户使用其他语言提问，则跟随用户语言。

核心原则

1. 业务视角优先

从"这个项目解决什么问题"出发，不是"这个文件里有什么函数"。

| 不要 | 要 | |------|-----| | handleRequest(ctx) 函数接收一个 Context 参数... | 请求进来后，系统会经过鉴权、限流、路由分发三个阶段... | | interface MessageQueue { push(); pop() } | 模块间通过消息队列解耦，生产者只管投递，消费者按优先级拉取 |

2. 抽象层次把控：不贴代码，讲设计

默认在设计模式和架构层面描述，非必要情况下不贴原始代码。重点突出流程、逻辑、设计思想，用架构图（Mermaid）、流程图、表格来表达，而非代码片段。只有设计特别精妙、项目自创独特概念、或实现是核心卖点时才展示代码，且必须先用自然语言解释。

3. 全局关联

每个局部分析都必须连接到项目整体设计哲学——这是区分"代码说明书"和"架构分析"的关键。详见 [analysis-guide.md](references/analysis-guide.md) 的全局关联章节。

4. 启发性写作

目标是让读者学到东西、产生思考，而不是获得一份代码说明书。像资深工程师在白板前讲解——有观点、有推理、有对比。详见 [analysis-guide.md](references/analysis-guide.md) 的启发性写作章节。

5. 深度洞察：Why > What（强制）

每个设计决策必须解释动机、权衡、替代方案代价。描述"是什么"只是起点，解释"为什么"才是分析的价值所在。每个核心模块和整体架构都要回答：

• 为什么这样设计？ 不只是"用了什么模式"，而是"为什么适合这个场景"
• 如果不这样会怎样？ 替代方案的代价
• 与业界最佳实践的差距？ 领先之处和改进空间
• 如果让你重新设计？ 展示更深层理解
• 系统性设计哲学？ 贯穿整个项目的风格（如"约定优于配置"、"零成本抽象"）

示例： > ❌ 路由系统采用了中间件模式，支持链式调用。 > > ✅ 路由系统选择了洋葱模型而非线性管道。线性管道实现更简单，但洋葱模型让每个中间件都能同时处理请求和响应阶段——这对日志、计时、错误恢复至关重要。Express 当年选择线性模型，后来不得不用各种 hack 处理响应后逻辑，Koa 吸取教训才转向洋葱模型。如果让我重新设计，我会考虑加入中间件依赖声明，让框架自动排序——这是 Fastify 的做法，能避免顺序导致的隐蔽 bug。

补充要求

• 代码为准 — 一切结论有代码依据，标注 文件路径 或 文件路径:行号范围，禁止模糊表述
• 有温度 — 像资深工程师给新同事做 onboarding，加入主观评价和建议，避免 AI 味套话
• 重点深入次要简略 — 核心创新点深入分析，通用工具函数一句话带过
• 批判性思考 — 与业界实践对比，指出真实问题，不回避缺陷。参考 [analysis-guide.md](references/analysis-guide.md)
• 行文流畅易懂 — 整体行文需要流畅自然，让入门的工程师也能看懂并学习到东西。避免过于学术化或堆砌术语
• 拒绝流水账 — 每个模块要体现深度细节，不能一句带过或泛泛而谈。每个模块如果合适要加上对应的 Mermaid 架构图，让读者看完有启发、能学到设计精髓

分析工作流

灵活性原则：以下所有阶段和章节都是建议性的指引，不是必须严格执行的清单。agent 应根据当前分析的项目特性动态决策——如果某个阶段或环节对当前项目没有意义，可以跳过或简化。一切以最终报告的质量为准。

阶段 1: 项目获取与初始化

1. 解析用户输入（支持 owner/repo、GitHub/GitLab/Gitee URL、本地路径、项目名称）
2. 创建工作区：在用户主目录下创建 repo-analyses/${REPO_NAME}-{YYYYMMDD} 目录作为 $WORK_DIR（跨平台：macOS/Linux 使用 $HOME，Windows 使用 $USERPROFILE 或 $HOME）
3. 如果用户提供本地路径则跳过 clone，否则 git clone --depth=1 克隆仓库
4. 获取基本元数据（Star、Fork、贡献者、代码统计）

阶段 2: 项目规模评估与分析模式选择

1. 统计有效代码行数（排除可跳过代码），按模块列出分布

• 可跳过代码定义：测试代码、构建/部署配置（Dockerfile、CI yaml 等）、自动生成代码（protobuf 生成、lock 文件等）、示例/文档代码
• 使用 find + wc -l 或 cloc 等工具统计，按顶层目录分组

1. 向用户报告代码规模，使用 AskUserQuestion 让用户选择分析模式：

| 模式 | 核心模块覆盖率 | 次要模块覆盖率 | 适用场景 | |------|-------------|-------------|---------| | 快速分析 | ≥30% | ≥10% | 快速了解项目全貌 | | 标准分析（推荐） | ≥60% | ≥30% | 常规架构分析 | | 深度分析 | ≥90% | ≥60% | 深入研究每个设计决策 |

1. 将代码规模统计和用户选择的分析模式写入 drafts/03-plan.md，后续阶段据此控制分析深度

覆盖率计算规则：

• 覆盖率 = 通过 Read 工具实际请求过的行范围之并集 / 文件总行数
• 对于大文件（>500 行），必须分段读取，确保以下关键段落被覆盖：
• 文件头部的类型定义和导入（前 100 行）
• 核心业务逻辑函数（通过目录结构或函数名定位）
• 文件尾部的测试代码（如有）
• 只读了文件的一小部分（ 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 覆盖率门控：

1. 读取每个 drafts/06-module-*.md 末尾的覆盖率明细表
2. 快速检查：每个草稿末尾是否有覆盖率表、合计行是否标注达标（✅/❌）
3. 只有标注 ❌ 或缺少覆盖率表的模块才需要深入检查
4. 不达标模块 → 主 agent 自动补充阅读未覆盖的关键文件，将补充发现追加到对应草稿
5. 补充后仍不达标 → 向用户报告哪些模块未达标及原因（如文件过大、二进制文件等）

7.2 抽查验证：

1. 从每个核心模块草稿中选取 2-3 个关键结论
2. 回到源码逐行验证结论准确性
3. 发现偏差则修正草稿中的对应内容

7.3 交叉验证：

1. 交叉验证【待主 agent 验证】标注的跨模块结论
2. 综合回答探索问题，识别跨模块设计模式
3. 验证全局关联：每个模块的分析是否都连接到了项目整体设计哲学
4. 写入 drafts/07-cross-validation.md

阶段 8: 多源融合与最终报告（主 agent）

1. 提炼架构洞察和系统性设计哲学
2. 基于阶段 3 调研结果深化竞品对比（仅在阶段 3 信息不足时补充搜索）
3. 提出"如果重新设计"的改进建议
4. 写入 drafts/08-insights.md
5. 多源融合：以阶段 5 设计的报告章节结构为骨架，从各草稿中抽取内容填充。同一概念在多个草稿中出现时，取最详细版本并补充其他版本独有信息。融合后消除所有"见草稿 X"、"详见附录"等跳转指示

• 叙事连贯：按阶段 5 设计的叙事线组织模块章节。每个模块章节的开头必须有 1-2 句过渡，连接上一个模块的结论或问题。避免"接下来我们分析 X 模块"这种生硬转折，改用自然过渡（如"Gateway 完成了请求的认证和路由，但它只负责'谁可以进来'，不负责'进来之后能做什么'。这个行为控制的职责，由策略引擎承担。"）

1. 分段写入：最终报告通常超过 500 行，先 Write 前几个章节（200-300 行），后续用 Edit 追加，每次追加前 Read 确认末尾位置
2. 覆盖率汇总：将覆盖率数据汇总写入 drafts/08-coverage.md（不放入最终报告）

• 数据直接从各 subagent 草稿末尾的覆盖率明细表中提取，不需要主 agent 重新计算
• 如果主 agent 在阶段 7 补充了阅读，将补充的行数加到对应模块的「已读行数」中
• 汇总表格式：

| 模块 | 类型 | 文件数 | 有效代码行 | 已读行数 | 覆盖率 | 达标 | |------|------|--------|-----------|---------|--------|------| | ... | 核心/次要 | ... | ... | ... | ...% | ✅/❌ |

1. 汇总生成最终报告（不包含覆盖率章节）

草稿文件清单

所有中间过程保存到 $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 设计对比式报告结构，骨架约束中增加"设计决策对比"和"选型建议"

输出要求

1. 最终报告为单一 markdown 文件：$WORK_DIR/ANALYSIS_REPORT.md
2. 大量使用 Mermaid 图表展示架构、流程、数据流
3. 面向需要理解业务架构的开发者
4. 亮点和问题的评价思维框架参考 [analysis-guide.md](references/analysis-guide.md)
5. 分析哲学和深度标准参考 [analysis-guide.md](references/analysis-guide.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yzddmr6
• Source: yzddmr6/repo-analyzer
• License: MIT

Install and usage instructions live in the source repository linked above.