Repo Insight

专门用于深度分析和解读本地或 GitHub 源代码仓库的 Agent Skill。在 Claude Code 中全自动运行，包含质量 Review、迭代优化闭环、并行处理和 subAgent 支持。

⚠️ 关键输出质量规范（必须遵守）

1. 禁止 HTML 实体转义

CRITICAL: 生成所有 Markdown 文件时，严禁进行任何 HTML 实体转义。

• ❌ 错误：>、<、&
• ✅ 正确：>、<、&

检查方法：在写入文件后，验证输出文件中不包含 >、<、& 这些字符序列。

2. Markdown 代码块规范

所有目录树、ASCII 图、代码示例必须放在正确的 Markdown 代码块中：

# 目录树必须放在 text 代码块中

# Mermaid 图必须放在 mermaid 代码块中

# TypeScript 代码必须放在 typescript 代码块中

3. 目录树格式规范

目录树注释必须：

• 与目录/文件名之间保留 至少 2 个空格
• 使用统一的注释标签：【核心基建】、【业务模块】、【工具集】、【配置】、【⚠️ 待分析】、【废弃】
• 整个目录树必须包裹在 ```text 代码块中

示例：

repo-name/
├── src/                    # 【核心基建】源代码主目录
│   ├── main.ts            # 【核心基建】CLI 入口启动文件
│   └── utils/             # 【工具集】通用工具函数
└── README.md               # 【配置】项目说明文档

技能触发场景

使用此技能当用户：

• 说"帮我分析这个 GitHub 仓库：https://github.com/..."
• 说"分析当前目录的代码"
• 要求深度解读代码库架构和业务逻辑
• 需要代码仓库的中文翻译和注释

工作目录结构

当使用 URL 模式时，代码库克隆到固定的 github-sources 目录：

~/github-sources/
└── repo-name/
    ├── reports/
    │   ├── 00-planning/
    │   │   └── analysis_plan.md      # 阶段零输出
    │   ├── 01-global-scan/
    │   │   ├── repo_overview.md      # 阶段一输出
    │   │   └── draft_tree.md          # 阶段一输出
    │   ├── 02-architecture/
    │   │   ├── architecture.md        # 阶段二输出
    │   │   └── final_tree.md          # 阶段二输出
    │   ├── 03-deep-dive/
    │   │   ├── task_queue.md          # 阶段三输出
    │   │   └── comments_draft.md      # 阶段三输出
    │   ├── 04-quality/
    │   │   ├── quality_review.md      # 阶段4.5输出
    │   │   └── iteration_log.md       # 阶段4.5输出（如迭代）
    │   ├── final_report.md            # 阶段四输出
    │   ├── execution_summary.md       # 阶段五输出
    │   └── QUICKSTART.md             # 阶段五输出
    ├── README-CN.md（如需要）
    └── [源代码文件（带中文注释）]

当使用当前目录模式时：

./
├── reports/
│   ├── 00-planning/
│   │   └── analysis_plan.md
│   ├── 01-global-scan/
│   │   ├── repo_overview.md
│   │   └── draft_tree.md
│   ├── 02-architecture/
│   │   ├── architecture.md
│   │   └── final_tree.md
│   ├── 03-deep-dive/
│   │   ├── task_queue.md
│   │   └── comments_draft.md
│   ├── 04-quality/
│   │   ├── quality_review.md
│   │   └── iteration_log.md
│   ├── final_report.md
│   ├── execution_summary.md
│   └── QUICKSTART.md
├── README-CN.md（如需要）
└── [源代码文件（带中文注释）]

核心工作流

阶段零：准备与任务规划（新增）

目标：在开始分析前，先规划整个任务，确定优先级和并行策略

输入：目标 GitHub 仓库地址 / 原始代码文件集合

处理步骤：

1. 运行可选辅助脚本获取基础信息

   • 可选运行 scripts/file_counter.py 获取文件统计
   • 可选运行 scripts/complexity_scanner.py 获取复杂文件列表

2. 快速扫描仓库规模

   • 读取 README.md、package.json、pyproject.toml 等核心配置
   • 使用 Glob 工具快速浏览目录结构

3. 制定分析计划

   • 评估仓库规模和复杂度
   • 确定哪些模块需要优先分析
   • 规划哪些任务可以并行执行
   • 预估时间和资源需求
   • 定义质量标准和验收条件（如"所有报告必须使用模板格式"）

4. 创建任务清单

   • 生成 reports/00-planning/analysis_plan.md
   • 包含：任务列表、优先级、依赖关系、质量标准

输出：

• reports/00-planning/analysis_plan.md - 分析计划文档

阶段一：全局扫描、输入与信息聚合、产品降维与文档基建

输入：

• 目标 GitHub 仓库地址 / 原始代码文件集合
• reports/00-planning/analysis_plan.md（如存在）

处理步骤：

1. 物理层过滤干扰项

   • 排除第三方依赖包（node_modules/, vendor/, .git/, dist/, build/ 等）
   • 排除构建产物和环境配置文件
   • 使用 Glob 工具获取有效文件清单

2. 结构展平与草稿目录树生成

   • 提取全局文件清单，构建基础的"全局目录层级树"
   • 基于 README 描述或业界通用命名规范，对目录树进行"职责域初步推测标注"
   • 对无法推测的目录打上"待定" Tag
   • 参考 references/tree_tpl_guide.md 模板生成 reports/01-global-scan/draft_tree.md

3. 产品视野的业务心智初始化与选型提取

   • 锁定线索：优先扫描 README.md、docs/ 目录、package.json 等全局信息
   • 语义提炼：分析该仓库的核心定位、解决的具体痛点、适用的业务场景，提取/推导典型的使用 Case
   • 选型反推与对比：初步提取其核心技术方案，分析选择该方案的背景与合理性，强推导"方案选型对比"
   • 参考 references/repo_overview_tpl_guide.md 模板生成 reports/01-global-scan/repo_overview.md

4. 国际化基建 (Doc Translation)

   • 语言嗅探：检测 README 和 docs 等目录下的核心文档语言
   • 本地化生成：若非中文且无中文版本，触发翻译流，在同级目录生成如 README-CN.md 等对应中文文档，不覆盖原文件

输出：

1. 含有新增中文翻译文档的增强版目标源码集合
2. reports/01-global-scan/draft_tree.md - 全局目录树，包含注释草稿，标注职责推测（参考 references/tree_tpl_guide.md）
3. reports/01-global-scan/repo_overview.md - 结构化文档，包含定位/问题/场景/Case/方案初探等（参考 references/repo_overview_tpl_guide.md）

阶段二：宏观视野、架构设计梳理与靶向拓扑

输入：

1. 目标源码仓库集合 (增强版，带翻译文档)
2. reports/01-global-scan/draft_tree.md (全局物理目录与职责推测草稿)
3. reports/01-global-scan/repo_overview.md (产品与业务上下文解析文档)
4. reports/00-planning/analysis_plan.md (如存在)

处理步骤：

1. 靶向寻路与入口解析

   • 读取 reports/01-global-scan/draft_tree.md，提取并解析高价值入口文件（如 package.json、全局 main/index 文件）和打着"待定"标签的神秘目录
   • 重点分析源代码文件，定位系统的全局入口、核心路由分发点、主控中心
   • 结合 reports/01-global-scan/repo_overview.md 的业务场景，带着"业务目的"寻找核心节点

2. 实体识别与拓扑推导

   • 顺藤摸瓜，扫描入口文件引用的核心模块，梳理模块间的 Import/Export 依赖链路
   • 运用领域驱动设计 (DDD) 视角，识别代码中的核心业务实体及其在模块间的流转引用

3. 架构梳理逆向绘制

   • 结合技术栈、源代码分析、模块依赖与上下文文档，逆向推导整体架构设计与核心模块设计
   • 将系统整体架构、路由调用关系、实体依赖、核心模块设计(3~5个)等转化为人类易读的 plainText (ASCII 字符画) 图表及详尽的文字说明

4. 核心数据流转时序提取 (Data Flow Tracing)

   • 追踪核心场景下的数据是如何从入口输入，经过哪些模块/中间件/拦截器/服务等处理，最终落盘或返回的
   • 提取数据流各节点的交互时序与条件分支
   • 转换为 Mermaid sequenceDiagram 格式

5. 规范化契约提取 (Contract Specification)

   • 扫描对外暴露的 Controller/Router 或公共暴露的 API 函数
   • 将提取的参数、返回值、状态码转化为 OpenSpec/OpenAPI 规范标准，内部调用逻辑转化为标准 TypeScript Interface

6. 实体树收敛

   • 根据源码实际验证结果，推测不同目录对应的业务职责（哪些是核心业务，哪些是通用工具）
   • 修正阶段一的目录职责推测，打平未知目录
   • 生成 reports/02-architecture/final_tree.md

7. 生成架构文档

   • 参考 references/architecture_tpl_guide.md 模板生成 reports/02-architecture/architecture.md
   • 确保使用 plainText ASCII 字符画绘制结构图（严禁使用 Mermaid 或 Markdown List 代替）
   • 数据流部分必须且仅能使用 Mermaid 的 sequenceDiagram

输出：

1. reports/02-architecture/architecture.md - 《架构与拓扑梳理文档》（参考 references/architecture_tpl_guide.md）
2. reports/02-architecture/final_tree.md - 经源码验证的最终版目录树

阶段三：微观深度阅读与知识资产化（增强 subAgent 设计）

输入：

1. 阶段一产物: reports/01-global-scan/repo_overview.md
2. 阶段二的所有产物: reports/02-architecture/architecture.md、reports/02-architecture/final_tree.md
3. 目标源码仓库集合 (增强版，带翻译文档)
4. reports/00-planning/analysis_plan.md (如存在)

处理步骤：

1. 分块调度与任务分配

   • 基于 reports/02-architecture/final_tree.md 和 complexity_scanner.py 输出
   • 将高复杂度模块分成独立任务
   • 每个任务包含：文件路径、优先级、预估复杂度、验收标准
   • 生成 reports/03-deep-dive/task_queue.md

2. 并行子Agent处理

   • 可并行的任务类型：
     • 不同核心模块的深度阅读
     • 不同业务实体的注释生成
     • 不同功能模块的业务逻辑分析
   • 子Agent任务格式：

     深度阅读任务：
     - 文件路径：src/core/engine.py
     - 优先级：高
     - 上下文：repo_overview.md + architecture.md
     - 验收标准：[具体质量要求]
     - 输出：comments_draft.engine.md
     

   • 合并策略：
     • 所有子Agent完成后，合并 comments_draft.*.md 到 comments_draft.md
     • 进行一致性检查

3. 主 Agent 协调

   • 监控任务进度
   • 处理子Agent之间的依赖
   • 质量把关最终合并结果

4. 靶向阅读（如果不使用 subAgent）

   • 从核心入口开始逐级阅读
   • 重点阅读核心业务逻辑、复杂算法、关键设计模式实现

5. 逻辑反推与业务对齐

   • 阅读源码时，不仅解释技术逻辑，还要与阶段一中的 reports/01-global-scan/repo_overview.md "业务场景"对齐
   • 推导其"解决什么问题"以及"为什么这么写"
   • 例如添加注释：这里的容错处理是为了应对阶段一提到的高并发场景 Case

6. 知识资产化

   • 在内部工作区按照目标语言的业界标准，生成针对文件、核心类、复杂函数、难理解的核心逻辑的带规范的拟注入注释草案
   • 生成 reports/03-deep-dive/comments_draft.md，包含目标文件路径、目前代码内容的注释范围、注释规范与原则等内容

输出：

• reports/03-deep-dive/task_queue.md - 任务队列（如使用 subAgent）
• reports/03-deep-dive/comments_draft.md - 全量代码注释内容库草案

阶段四：产物组装与实体注入

输入：

• 阶段一的 reports/01-global-scan/repo_overview.md
• 阶段二的 reports/02-architecture/architecture.md 和 reports/02-architecture/final_tree.md
• 阶段三的注释草案
• 增强版源码
• reports/00-planning/analysis_plan.md (如存在)

处理步骤：

1. 报告整合

   • 将阶段一、阶段二、阶段三的所有核心内容无缝融合成最终的《全方位深度解读报告》
   • 必须包含 repo_overview.md 的完整内容（项目概览、技术亮点等）
   • 必须包含 architecture.md 的完整内容（所有架构图、模块设计、数据流时序图、接口契约等）
   • 必须包含 comments_draft.md 的注释规范
   • 生成 reports/final_report.md，结构参考 references/final_report_tpl_guide.md
   • **CRITICAL: 不要只保留高层概述，要保留所有技术细节和图表

2. 物理注释融合

   • 将注释精准写入代码文件
   • 创建备份或使用 git 进行版本控制（如果适用）

3. 完整性自检

   • 校验生成的文档是否覆盖了所有需求点
   • 检查注入的注释是否符合预设的注释规范

输出：

1. reports/final_report.md - 《全方位深度解读报告》(业务价值篇 & 架构设计篇)
2. 注入了详尽规范注释的"全新代码库"

阶段4.2：输出质量检查（新增）

目标：在进行质量 Review 之前，先进行格式和完整性检查，确保输出符合规范。

检查清单：

1. HTML 转义检查
   • 检查所有 Markdown 文件中无 >、<、&