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. 运行可选辅助脚本获取基础信息

   • 可选运行 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 文件中无 >、<、&
   • 确认 >、<、& 都原样保留

2. 目录树格式检查

   • 检查 draft_tree.md 在 ```text 代码块中
   • 检查 final_tree.md 在 ```text 代码块中
   • 检查目录树注释与目录名之间有足够空格
   • 检查注释标签格式统一（【核心基建】、【业务模块】等）

3. 最终报告完整性检查

   • 检查 final_report.md 包含 repo_overview.md 的所有核心内容
   • 检查 final_report.md 包含 architecture.md 的所有 ASCII 架构图
   • 检查 final_report.md 包含 architecture.md 的所有 Mermaid 时序图
   • 检查 final_report.md 包含 architecture.md 的所有接口契约定义
   • 检查 final_report.md 有清晰的章节结构和导航

4. 图表规范检查

   • 检查所有 ASCII 图使用统一字符集（+、-、|、>、v、^）
   • 检查所有 Mermaid 图语法正确且可渲染
   • 检查架构图层次清晰，箭头方向一致

输出：

• 如果检查全部通过：继续阶段 4.5
• 如果发现问题：先修正问题，再继续

阶段4.5：质量 Review 与反思 + 迭代优化（新增）

目标：形成完整的质量检查 → 问题发现 → 计划改良 → 问题解决 → 再次检查的闭环

输入：

• 阶段零到阶段四的所有输出文件
• reports/00-planning/analysis_plan.md

处理步骤：

第一部分：质量 Review

1. 完整性检查

   • 检查所有应生成的文件是否存在（对照 analysis_plan.md）
   • 检查报告格式是否符合模板要求
   • 检查关键内容是否缺失（对照 analysis_plan.md 的验收标准）

2. 一致性检查

   • repo_overview.md 与 architecture.md 的业务描述是否一致
   • draft_tree.md 与 final_tree.md 的演变是否合理
   • 注释与业务场景是否对齐
   • 各子模块的注释风格是否统一

3. 质量反思

   • 架构图是否清晰易读
   • 注释是否准确有用
   • 报告是否有遗漏的重要模块
   • 生成 reports/04-quality/quality_review.md，包含：
     • 问题清单（严重程度：高/中/低）
     • 根本原因分析
     • 改进建议

第二部分：迭代决策与执行

4. 问题评估与优先级排序

   • 评估每个问题的影响范围和严重程度
   • 确定哪些问题必须解决，哪些可以延后
   • 更新 reports/00-planning/analysis_plan.md（添加迭代任务）

5. 决定迭代策略

   • 轻量级修正（问题较少且局部）：
     • 直接修改相关报告文件
     • 跳过完整阶段重跑
   • 部分阶段重跑（问题影响某个阶段）：
     • 确定需要重跑的阶段（如阶段二、阶段三）
     • 更新该阶段的输入
     • 重新执行该阶段
   • 完整迭代（问题严重且广泛）：
     • 回到阶段零，重新制定分析计划
     • 完整执行所有阶段

6. 执行修正与优化

   • 按照迭代策略执行修正
   • 记录所有修改内容到 reports/04-quality/iteration_log.md

7. 再次 Review（递归）

   • 修正完成后，回到"质量 Review"步骤
   • 检查问题是否解决
   • 是否引入新问题
   • 直到满足质量标准或达到最大迭代次数（默认最多2-3次）

迭代终止条件：

• ✅ 所有严重问题已解决
• ✅ 中等问题已解决或达成共识
• ✅ 达到质量标准
• ⚠️ 或达到最大迭代次数（避免无限循环）

输出：

• reports/04-quality/quality_review.md - 质量审查报告
• reports/00-planning/analysis_plan.md - 更新后的分析计划（包含迭代任务）
• reports/04-quality/iteration_log.md - 迭代日志（记录所有修改）
• 优化后的各报告文件

阶段五：交付与总结（增强）

输入：

• 阶段零到阶段4.5的所有输出文件
• 全新代码库（带注释）

处理步骤：

1. 生成最终总结

   • 整合所有阶段的输出
   • 生成 reports/execution_summary.md
   • 包含：
     • 时间统计（各阶段耗时）
     • 迭代次数和修改记录
     • 文件清单
     • 关键发现
     • 未解决的问题（如有）
     • 未来优化建议

2. 生成快速预览

   • 创建 reports/QUICKSTART.md
   • 帮助用户快速浏览分析结果
   • 包含：仓库概览、核心架构、关键文件列表

3. 交付展示

   • 生成文件树展示所有输出
   • 提供使用建议
   • 说明如何阅读各报告

输出：

• reports/execution_summary.md - 执行总结
• reports/QUICKSTART.md - 快速浏览指南
• reports/04-quality/iteration_log.md - 迭代日志（如进行了迭代）

并行处理策略

可并行的环节

阶段一内并行：

• 读取 README.md 和 package.json 等配置文件（并行读取）
• 目录树生成 + 技术栈初步识别（可并行）

阶段二内并行：

• 架构梳理 + 实体识别（部分可并行）
• 数据流分析 + 接口契约提取（可并行）

阶段三完全并行：

• 多个高复杂度模块的深度阅读（完全并行）

阶段4.5内并行（如有多个独立问题）：

• 不同模块的问题修正（可并行）

不可并行（有依赖）的环节

• 阶段零 → 阶段一 → 阶段二 → 阶段三 → 阶段四 必须顺序执行
• Review 环节必须在阶段四之后
• 迭代修正后必须再次 Review

执行指南

开始分析

当用户请求分析仓库时：

1. 确定分析模式

   • 如果用户提供了 GitHub URL → URL 模式
   • 如果用户说"分析当前目录" → 当前目录模式

2. URL 模式处理

   • 克隆仓库到 ~/github-sources/ 目录
   • 切换到仓库目录

3. 当前目录模式处理

   • 确认当前目录是 git 仓库或代码目录
   • 在当前目录下工作

4. 创建 reports 目录

   • mkdir -p reports

5. 按顺序执行所有阶段（从零开始）

关键工具使用

• Glob: 用于文件搜索和目录扫描
• Read: 用于读取代码文件和文档
• Grep: 用于代码搜索和模式匹配
• Write: 用于生成报告文件
• Edit: 用于注入代码注释
• Bash: 用于 git 操作和目录管理
• Agent: 用于并行处理子任务（阶段三）

可选辅助脚本

技能包含以下可选的 Python 辅助脚本（在 scripts/ 目录下），可用于快速获取统计信息：

• scripts/file_counter.py - 统计文件数量和代码行数

  • 用法: python3 scripts/file_counter.py <仓库路径>
  • 输出: JSON 格式的统计信息

• scripts/complexity_scanner.py - 找出 TOP 10 最复杂文件（基于行数）

  • 用法: python3 scripts/complexity_scanner.py <仓库路径>
  • 输出: JSON 格式的复杂文件列表

这些脚本是可选工具，可以根据需要使用，输出结果可作为分析参考。

注意事项

1. 全自动执行 - 调用后无需中间交互，直接完成所有分析工作
2. 保持原有代码 - 注释注入时不要破坏原有代码结构
3. 不覆盖原文件 - 翻译文档时生成新文件（如 README-CN.md）
4. 使用 ASCII 图表 - 架构图必须使用 plainText ASCII 字符画
5. 参考模板文件 - 始终使用 references/ 目录下的模板作为输出格式参考
6. 质量优先 - Review 环节发现问题后，按照迭代策略进行优化
7. 避免无限循环 - 最多迭代 2-3 次，或达到质量标准即可停止

参考模板

技能包含以下参考模板文件（在 references/ 目录下）：

• repo_overview_tpl_guide.md - 产品与业务上下文解析报告模板
• architecture_tpl_guide.md - 架构与拓扑梳理文档模板（含图表绘制规范）
• tree_tpl_guide.md - 目录树模板（含格式规范）
• final_report_tpl_guide.md - 最终报告整合模板（新增）

在生成对应报告时，请务必参考这些模板的格式和内容要求。特别是 final_report.md 必须严格按照 final_report_tpl_guide.md 的结构来整合所有阶段的内容。