repo-insight

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. 运行可选辅助脚本获取基础信息
2. 可选运行 scripts/file_counter.py 获取文件统计
3. 可选运行 scripts/complexity_scanner.py 获取复杂文件列表

1. 快速扫描仓库规模
2. 读取 README.md、package.json、pyproject.toml 等核心配置
3. 使用 Glob 工具快速浏览目录结构

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

1. 创建任务清单
2. 生成 reports/00-planning/analysis_plan.md
3. 包含：任务列表、优先级、依赖关系、质量标准

输出：

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

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

输入：

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

处理步骤：

1. 物理层过滤干扰项
2. 排除第三方依赖包（node_modules/, vendor/, .git/, dist/, build/ 等）
3. 排除构建产物和环境配置文件
4. 使用 Glob 工具获取有效文件清单

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

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

1. 国际化基建 (Doc Translation)
2. 语言嗅探：检测 README 和 docs 等目录下的核心文档语言
3. 本地化生成：若非中文且无中文版本，触发翻译流，在同级目录生成如 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. 靶向寻路与入口解析
2. 读取 reports/01-global-scan/draft_tree.md，提取并解析高价值入口文件（如 package.json、全局 main/index 文件）和打着"待定"标签的神秘目录
3. 重点分析源代码文件，定位系统的全局入口、核心路由分发点、主控中心
4. 结合 reports/01-global-scan/repo_overview.md 的业务场景，带着"业务目的"寻找核心节点

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

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

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

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

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

1. 生成架构文档
2. 参考 references/architecture_tpl_guide.md 模板生成 reports/02-architecture/architecture.md
3. 确保使用 plainText ASCII 字符画绘制结构图（严禁使用 Mermaid 或 Markdown List 代替）
4. 数据流部分必须且仅能使用 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. 分块调度与任务分配
2. 基于 reports/02-architecture/final_tree.md 和 complexity_scanner.py 输出
3. 将高复杂度模块分成独立任务
4. 每个任务包含：文件路径、优先级、预估复杂度、验收标准
5. 生成 reports/03-deep-dive/task_queue.md

1. 并行子Agent处理
2. 可并行的任务类型：
3. 不同核心模块的深度阅读
4. 不同业务实体的注释生成
5. 不同功能模块的业务逻辑分析
6. 子Agent任务格式：

``` 深度阅读任务：

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

```

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

1. 主 Agent 协调
2. 监控任务进度
3. 处理子Agent之间的依赖
4. 质量把关最终合并结果

1. 靶向阅读（如果不使用 subAgent）
2. 从核心入口开始逐级阅读
3. 重点阅读核心业务逻辑、复杂算法、关键设计模式实现

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

1. 知识资产化
2. 在内部工作区按照目标语言的业界标准，生成针对文件、核心类、复杂函数、难理解的核心逻辑的带规范的拟注入注释草案
3. 生成 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. 报告整合
2. 将阶段一、阶段二、阶段三的所有核心内容无缝融合成最终的《全方位深度解读报告》
3. 必须包含 repo_overview.md 的完整内容（项目概览、技术亮点等）
4. 必须包含 architecture.md 的完整内容（所有架构图、模块设计、数据流时序图、接口契约等）
5. 必须包含 comments_draft.md 的注释规范
6. 生成 reports/final_report.md，结构参考 references/final_report_tpl_guide.md
7. **CRITICAL: 不要只保留高层概述，要保留所有技术细节和图表

1. 物理注释融合
2. 将注释精准写入代码文件
3. 创建备份或使用 git 进行版本控制（如果适用）

1. 完整性自检
2. 校验生成的文档是否覆盖了所有需求点
3. 检查注入的注释是否符合预设的注释规范

输出：

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

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

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

检查清单：

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