codebase-onboarding

代码库入门 Wiki 生成器

从任意代码仓库生成层级清晰、链接到源代码且包含丰富图表的 Wiki，格式仿照 DeepWiki。

适用场景

• 用户提供代码仓库（URL、路径或上传的文件），并希望了解其内容
• 用户希望帮助开发者熟悉代码库
• 用户希望根据代码生成架构文档
• 用户询问“这个仓库是如何运作的”或“梳理这个代码库”

工作流概览

Phase 1: Reconnaissance ──→ Phase 2: Architecture Mapping ──→ Phase 3: Deep Docs ──→ Phase 4: Assembly
  (scripts/analyze.py)        (you + diagrams)                  (you + templates)      (final output)

阶段 1 — 初步勘察（自动化）

运行分析脚本，收集代码库的结构化数据：

pip install -r scripts/requirements.txt  # optional, graceful degradation
python scripts/analyze.py <repo_path> --output codebase-analysis.json

执行规范

使用此规范，减少不同模型和运行环境产生的输出差异。

必须

• 有可用的代码仓库路径时，首先运行 scripts/analyze.py。
• 编写任何架构相关的描述前，先阅读 JSON 报告。
• 检查 summary.capabilities_missing，并据此调整输出范围。
• 对每项技术描述标注源文件引用，格式为 path/to/file.ext:L45-L87。
• 将无法验证的描述标记为 [NEEDS INVESTIGATION]。目标是每个内容页面至少 1 处——对于从代码中推断而非直接观察到的架构决策，应予以标记。完全没有 [NEEDS INVESTIGATION] 标记的 Wiki 几乎肯定过于自信。
• 每个内容页面（不包括 00-index.md）均包含全部 7 个必需部分：TL;DR · Relevant Source Files · 架构图 · Key Concepts 表格 · 带引用的详细说明 · Cross-references · Active Development Areas。
• 索引页面（00-index.md）仅用于导航——无需包含 TL;DR、引用或图表。

应该

• 安装可选的 Python 依赖项，以便进行更好的结构分析：pip install -r scripts/requirements.txt。
• 选择优先记录的内容时，优先考虑 key_entities 和 git.hotspots。
• 图表和表格应与实际观察到的代码结构一致，而非基于假设。
• 每个内容页面至少撰写 400 个词。深入追踪一条代码路径，而不是肤浅地罗列许多内容。深度胜过广度。
• 每个主要说明部分至少包含 3 个 file:line 引用。目标是每页总计 ≥10 个引用。

可以

• 无法运行脚本时，继续进行人工勘察。
• 能力有限时，生成范围精简的入门文档。

质量等级

明确使用以下等级设定预期：

• A级（高可信度）： tree_sitter、networkx 和 git 均可用。生成包含实体排名、所有权和热点分析的完整 Wiki。
• B 级（中等可信度）： 缺少 tree_sitter 或 networkx 中至少一项。可以生成完整 Wiki，但需包含局限性说明。
• C 级（基线）： 脚本不可用或主要能力缺失。仅生成结构化概览，并明确说明未知项。

脚本会自动运行 7 个阶段，并报告能够和无法完成的工作：

1. 文件发现 — 遍历时遵循 .gitignore（pathspec）
2. 语言统计 — 按语言准确统计代码行数（tokei/scc）
3. 清单解析 — 从 package.json、pyproject.toml、Cargo.toml、go.mod、.csproj 中提取依赖项（使用适当的解析器，而非正则表达式）
4. 框架检测 — 根据实际依赖项交叉验证，而非仅依据文件名
5. 代码结构 — 通过 tree-sitter AST 解析识别类、函数、接口和类型
6. 重要性排名 — 基于跨文件引用关系图进行 PageRank 排名（networkx）
7. Git 洞察 — 热点文件、主要贡献者和各目录的所有权

继续操作前，请先阅读 JSON 输出。key_entities 字段会指出最重要的代码实体——从这些实体开始编写文档。

如何使用分析报告

JSON 报告中的每个字段都会影响具体的文档编写决策。请遵循以下对应关系： key_entities → 页面结构与优先级 PageRank 评分后的符号会告诉你哪些内容最重要。使用它们来：

• 判断哪些组件值得拥有独立的 wiki 页面（排名前 10–15 的实体几乎总是值得）
• 确定文档编写顺序——优先记录排名最高的实体
• 识别枢纽抽象：排名高的实体会在许多文件中被引用，说明它们是架构中的承重墙
• 根据排名前约 10 项，在 Overview 页面上构建“关键概念”表格

示例：如果 RepomixConfigMerged 排名第 1，它就是代码库的核心内容——应在 Overview 中重点呈现，为它设立专属章节，并在所有涉及配置的页面中交叉引用。

symbols.by_kind → Wiki 深度决策 类、函数和接口的分布能揭示代码库的架构风格：

• 接口／类型较多 → 记录契约和类型层次结构，并使用 ER 图
• 类较多 → 记录继承和组合，并使用类关系图
• 函数较多 → 记录数据流和管道，并使用时序图
• 这会直接决定使用 references/diagram-patterns.md 中的哪些模式

frameworks → 调整路径 将检测到的框架与“按代码库类型调整”表格进行匹配，以决定要包含哪些专属页面。结合 references/language-guides.md 查看框架专属的分析模式（例如，如果检测到 Django，请阅读 Django 部分，了解应优先检查哪些文件）。

git.hotspots →“活跃开发区域”章节 变更最多的文件能表明团队正在积极开发哪些内容。使用这些信息来：

• 在 Overview 页面添加“当前开发区域”提示框
• 优先详细记录热点文件（新开发者最先接触的就是这些文件）
• 标记变更频繁但符号数量较少的文件——它们可能是需要说明的配置或胶水代码

git.ownership →“该联系谁”指引 各目录的主要贡献者直接对应一项重要的入职信息：了解每部分由谁负责。在 Overview 页面中加入此表格，或设立专门的“团队与所有权”章节：

| Area          | Primary Contact    | Commits (12mo) |
|---------------|--------------------|----------------|
| src/core/     | Alice              | 142            |
| src/api/      | Bob                | 87             |

manifests → 依赖与构建章节 解析后的依赖数据用于编写“构建与开发”wiki 页面：

• dependencies → 运行时架构（应用实际使用的内容）
• devDependencies → 工具链（开发者需要了解的内容）
• scripts → 开发工作流页面可用的命令
• engines → 版本要求和限制

languages + languages_source → 范围与可信度 语言分布会告诉你主要语言是什么（这决定了哪些 tree-sitter 查询能生成最好的数据），以及统计数据是准确的（tokei/scc）还是估算的（回退方案）。如果使用了回退统计，请注明这一限制。

capabilities_missing → 报告限制 如果报告显示跳过了 tree-sitter，你需要手动阅读关键文件以提取结构。如果跳过了 networkx，你将无法获得重要性排名——请改为阅读入口文件和 README 来判断哪些内容重要。务必检查此字段，并据此调整方法。

file_tree → 导航与差异检测 扫描完整文件列表，找出自动分析可能遗漏的文件：

• 配置文件（.env.example、nginx.conf、terraform/）→ 基础设施文档
• 迁移文件 → 数据库架构演进
• 种子／固定数据文件 → 理解数据模型
• 位于非常规位置、与主流框架约定不符的文件

如果脚本不可用，或上下文中提供的是仓库文件内容，请手动进行初步侦察：

1. 读取文件树 — 确定项目类型、语言、框架，以及单仓库或多仓库结构
2. 读取基础文件：README、package.json / Cargo.toml / go.mod / pyproject.toml、Dockerfile、CI 配置、docs/ 文件夹
3. 确定入口点：main/index 文件、CLI 命令、服务启动代码、路由定义
4. 检测模式：单体仓库工具（Nx、Turborepo、Lerna）、插件系统、多进程架构、DI 容器

阶段 2 — 架构映射

根据初步分析，定义 wiki 页面树。使用分析报告中的以下输入：

1. key_entities（前 15 项） → 每个排名靠前的实体集群都成为一个主要章节。按目录或领域分组相关实体。
2. frameworks → 从“按代码库类型适配”中选择对应行，添加必需的特殊页面。
3. symbols.by_kind → 选择图表策略：类较多时使用组件图，函数较多时使用时序图，接口较多时使用契约图／ER 图。
4. git.ownership → 使用顶层目录的所有权信息，验证章节划分是否与团队边界一致。

构建带编号的层级结构：

0   - Index (navigation only — no TL;DR, no citations, no diagrams)
0.5 - Getting Started (installation, minimal working example, entry-point pointers)
1   - Overview
2   - [Major System A]
2.1 - [Subsystem A.1]
3   - [Major System B]
...
N   - Build & Development
N+1 - Testing Infrastructure

规则：

• 最大深度：4 层（例如 3.2.1）
• 中型代码库设置 8-15 个顶层章节，大型代码库设置 15-25 个
• 每个顶层章节包含 2-6 个子章节
• 最后两个章节始终为 Build/Dev 和 Testing
• 始终生成 Getting Started 页面（00.5-getting-started.md）— 这是新工程师的入门页面。内容包括：先决条件、安装步骤、最小可运行示例（代码片段），以及优先阅读的 2-3 个重要文件。此页面不需要引用或 [NEEDS INVESTIGATION] 标记。

在编写任何页面之前，先生成顶层架构图（Mermaid graph TD）。

阶段 3 — 深度文档编写

对于每个页面，遵循 references/page-template.md 中的模板。使用分析报告填充结构化章节：

1. 相关源文件 — 从 key_entities 中选取与此页面范围匹配的条目。使用 file 和 line 字段生成精确的源代码链接。
2. TL;DR — 用 2-3 句话说明内容，让开发者判断是否需要继续阅读。
3. 架构图 — 根据 symbols.by_kind 的分布，从 references/diagram-patterns.md 中选择合适的 Mermaid 模式（参见阶段 2 的决策）。
4. 关键概念表 — 从属于此章节的 key_entities 中填充。kind 字段提供类型列，file:line 提供来源列。
5. 组件参考表 — 使用按此页面目录／领域筛选的 symbols.items。包括名称、类型、file:line，以及根据实际代码阅读结果编写的一句话描述。
6. 关联源代码的说明 — 每项技术说明都引用 path/to/file.ts:L42-L87。symbols 数据提供起始位置；阅读实际文件以核实内容并补充行号范围。
7. 活跃领域 — 交叉参考 git.hotspots，标记此页面中正在积极开发的组件。

编写任何页面之前，先阅读 references/page-template.md。 创建任何 Mermaid 图表之前，先阅读 references/diagram-patterns.md。

对于特定语言／框架的分析模式，请阅读 references/language-guides.md。

阶段 4 — 汇编

将页面汇编为最终输出。输出格式取决于用户需求：

用户请求	输出格式
“生成 wiki”	在 wiki/ 目录中生成一组带编号的 .md 文件
“创建入职文档”	将所有页面整合到一个 .md 文件中
“帮我了解这个代码库”	通过对话讲解，并嵌入图表
“制作演示文稿”	将 wiki 内容作为输入，交由 pptx 技能处理

对于基于文件的输出，按以下结构组织：

wiki/
├── 00-index.md               (table of contents with links — no TL;DR/citations/diagrams)
├── 00.5-getting-started.md   (installation, minimal example, entry-point pointers)
├── 01-overview.md
├── 02-system-a.md
├── 02.1-subsystem-a1.md
├── ...
└── assets/
    └── diagrams/             (exported Mermaid if requested)

核心原则 — 请仔细阅读

这些是不可妥协的质量标准：

绝不编造。 每项说法都必须能追溯到真实代码。如果无法验证，请标记为 [NEEDS INVESTIGATION]，并指出需要审查的具体文件。

渐进式披露。 TL;DR → 概览 → 详情。每个部分都以一段摘要开头。

系统思维。 架构 → 子系统 → 组件 → 方法。先梳理各部分的连接关系，再解释内部细节。

表格驱动。 任何包含 3 项或以上内容的结构化信息都应放入表格。务必包含「来源」列。

图示优先。 如果系统包含 3 个或以上相互作用的组件，就必须配有 Mermaid 图。没有例外。

深挖优先于广度。 追踪实际代码路径。绝不要根据文件名猜测——先阅读文件。

按代码库类型调整

代码库类型	需包含的特别页面
Monorepo	「仓库结构」：梳理各个包和服务；按包划分子树
微服务	「服务通信」（协议、契约、服务发现）；按服务划分章节
前端 SPA	路由、状态管理、组件层级、构建／打包
后端 API	路由定义、中间件管线、数据访问层、身份验证流程、常见模式（身份验证流程、请求验证、错误处理）
库／SDK	公共 API 概览、扩展点、使用模式（常见集成模式、配置、扩展库）、使用示例
CLI 工具	命令层级、参数解析、插件系统
移动应用	导航、状态管理、平台专属代码、构建变体

应避免的反模式

• 复述文件树 — 不要只列出文件。应说明它们的作用以及彼此的连接方式。
• 重复 README 内容 — 在现有文档的基础上进行提炼并增加价值。
• 浅层描述 — 「这里处理身份验证」毫无用处。应追踪整个流程。
• 忽略「为什么」 — 从代码中推断架构决策。对未知之处提出问题并标记出来。
• 孤立页面 — 每个页面都应可从概览访问，并与相关页面交叉引用。
• 缺少图示的系统 — 3 个或以上相互作用的组件 = 必须绘制图示。
• 根据名称猜测 — utils/helpers.ts 可能包含任何内容。应先阅读文件。

依赖项与工具

分析器（scripts/analyze.py）采用编排器模式——组合专用工具，而非重新实现解析器。所有依赖项均为可选；脚本会报告使用了哪些依赖项，以及跳过了哪些依赖项。

安装所有依赖项：pip install -r scripts/requirements.txt

Python 包（均为可选，可平稳降级）：

包	可提供的功能	未安装时
tree-sitter-language-pack	AST 提取：涵盖 165 种以上语言中的类、函数、接口、类型	无代码结构数据——仅有文件级统计
pathspec	正确遍历符合 .gitignore 规则的文件	仅使用硬编码的跳过列表
networkx	对代码实体进行 PageRank 重要性排名	不进行排名——所有符号一视同仁
tomli（Python <3.11）	正确解析 pyproject.toml、Cargo.toml 中的 TOML	Python 3.11+ 使用标准库 tomllib

CLI 工具（可选，运行时检测）：

工具	可提供的功能	未安装时
tokei 或 scc	准确统计各语言的代码行数，并正确处理注释	根据文件大小进行粗略估算
git	热点检测、贡献者映射、代码所有权	不生成 Git 洞察章节

不需要：

• Mermaid CLI（mmdc）——图表以 Mermaid 源码形式输出；渲染由查看器负责
• 语言工具链（cargo、npm、pip）——分析器通过适当的解析器（JSON、TOML、XML）直接读取清单文件
• ripgrep、jq、tree——脚本会在内部处理搜索和格式化

可用脚本

• scripts/analyze.py — 自动化代码库侦察。生成 JSON 报告，包含文件发现、语言统计、清单解析、框架检测、基于 AST 的代码结构、PageRank 重要性排名和 Git 洞察。所有依赖项均为可选，缺少依赖时会优雅降级。
• scripts/eval.py — 质量评估器，用于比较多次 LLM/运行框架运行生成的入门文档输出。评估结构、引用覆盖率、图表/表格、完整性和多次运行间的一致性。
• scripts/requirements.txt — analyze.py 的 Python 依赖项。使用 pip install -r scripts/requirements.txt 安装。

文件参考

文件	用途	阅读时机
references/page-template.md	包含所有章节的完整页面模板	编写任何 Wiki 页面之前
references/diagram-patterns.md	按场景分类的 Mermaid 图表模式	创建任何图表之前
references/language-guides.md	特定语言的分析模式	分析不熟悉的语言/框架时
scripts/analyze.py	自动化代码库侦察	阶段 1，仓库位于本地文件系统时
scripts/eval.py	评估多次 LLM/运行框架运行生成的文档质量和一致性	从多次 LLM/运行框架运行生成输出后
scripts/requirements.txt	脚本的 Python 依赖项	设置