repo-wiki-skill

仓库 Wiki

概述

为大型代码仓库创建准确、详尽的多页面 Markdown Wiki 包。此技能针对规模足以给维护者带来压力的代码库进行了优化：单体仓库、框架、编译器、平台、服务，或拥有数十万行代码的产品。优先依据文件而非猜测，按实用的粒度覆盖整个仓库，并通过专门的页面解释核心代码、设计决策、算法和权衡。

操作原则

• 创建独立的 Wiki 包目录，而不是一个巨大的 Markdown 文件，除非用户明确要求单文件。
• 默认包目录：wiki/。如果 wiki/ 已存在，请选择清晰且不冲突的名称，例如 maintainer-wiki/。
• 让生成的 Wiki 独立于现有文档产品。不要将它混入或并列放在现有的 docs/、website/、site/ 或产品文档应用中。
• 将仓库视为一个系统来阅读，而不是孤立的文件集合。
• 面向需要在庞大、复杂的代码库中进行导航的维护者和代码学习者。
• 覆盖要全面，深度要有选择：深入解释重要、出人意料或风险较高的代码路径；简要概述样板代码和生成代码。
• 以具体的文件路径、符号、配置名称、脚本、测试和观察到的行为为依据。
• 证据不完整时，明确标注不确定性。
• 在有助于说明架构、数据流、状态机、依赖关系图或算法时，使用 Mermaid 和 KaTeX。对于纯 Wiki 输出，优先使用 Mermaid 绘图。只有在用户明确要求文档站点时才使用 Graphviz（DOT），因为渲染需要构建时插件。
• 将数字规模目标视为最低要求，而非最终目标。通过质量检查器是必要条件，但绝非充分条件；不要撰写重复、充斥模板、以文件索引为主或受字数驱动的内容。
• 不要仅凭文件名批量生成 Wiki。使用脚本进行清单盘点和质量检查，但架构、子系统、算法和维护指南必须基于实际源码阅读和设计推理来撰写。
• 脚本可以搭建导航和清单，但不得编写核心说明性内容。在生成大量辅助页面前，先依据源码证据手动综合撰写架构页面。
• 文档站点部署是可选项。只有用户要求将 Wiki 发布为 Rspress/docs 站点时，才阅读 references/rspress_docs_site.md；否则不要将站点设置纳入主要工作流。

标准工作流

1. 明确范围和输出目标

确认或推断：

• 仓库根目录及任何子目录范围。
• 输出包目录。如果未指定，创建 wiki/；如果该路径已存在，则创建 maintainer-wiki/ 或其他清晰且不冲突的 Wiki 包目录。
• 用户指定时，确认目标语言和受众。

如果未指定，则生成面向仓库学习者和新维护者的多页面 Wiki 包。

Wiki 必须作为独立的包存在。如果目标仓库已有 docs/、website/ 或其他文档应用，请保持其原样，并创建单独的 wiki/ 包。如果仓库已有 wiki/，请使用 maintainer-wiki/、repo-wiki/ 或类似明确的包名称，以避免冲突。

2. 创建仓库地图

先快速检查本地仓库，再进行详细阅读。优先使用 rg --files、find 和语言原生的元数据命令。必要时使用 Node 运行 scripts/repo_snapshot.cjs，生成结构化清单，而无需将每个文件都加载到上下文中。

建议的第一轮检查：

node <skill_dir>/scripts/repo_snapshot.cjs <repo_root> --output /tmp/repo-snapshot.md

至少检查：

• 根目录文档：README*、CONTRIBUTING*、CHANGELOG*、LICENSE*、docs/、wiki/。
• 包和构建元数据：package.json、pnpm-workspace.yaml、Cargo.toml、go.mod、pyproject.toml、requirements*.txt、pom.xml、build.gradle、Makefile、CI 配置。
• 源码根目录：src/、lib/、app/、packages/、crates/、cmd/、internal/、pkg/、tests/、examples/。
• 配置：打包工具、代码检查工具、格式化工具、测试运行器、代码生成、部署、Docker、环境示例。
• 生成、供应商、锁定、构建和缓存目录；识别这些目录，但除非与任务相关，否则不要深入阅读。

3. 制定 Wiki 计划

编写页面前，先为 Wiki 包制定简短计划：

• index.md：导航中心、目标读者、阅读顺序、执行摘要。
• repository-map.md：顶层目录和包概览。
• architecture/：架构概览和主要运行时流程。
• modules/：模块、包或目录的深入介绍；简单模块使用单个文件，复杂模块使用包含多个页面的子目录。
• subsystems/：核心领域、算法、状态、持久化、网络、安全、插件或编译器子系统；简单子系统使用单个文件，复杂子系统使用包含多个页面的子目录。
• development/：设置、构建、测试、代码检查、调试、发布、CI 和运维。
• maintainer-playbook.md：常见变更方案、安全的修改位置、风险、故障排查。
• reference/：术语表、文件索引、符号索引、未决问题。

根据仓库实际情况调整此结构，但最终内容应包含多个页面、便于导航，并放在独立的 Wiki 包中。

批量编写前，先找出仓库实际的设计核心：主要运行时路径、核心数据模型、边界接口、配置模型、持久化／缓存／网络层、扩展点，以及用于定义行为的测试。优先将这些内容整理成具名的架构或子系统页面。文件索引和模块目录放在后面，且不应成为 Wiki 的主体。

工作期间创建并维护一份简短的 analysis-plan.md 或同等的临时提纲。提纲应列出设计核心、各核心已阅读的源文件、主要假设，以及将解释这些内容的 Wiki 页面。除非用户需要过程记录，否则在最终 Wiki 中删除或省略此临时文件。

4. 按重要性深入阅读

按以下顺序优先进行详细阅读：

1. 公共 API、入口点、CLI 命令、服务端路由、插件钩子、导出的包。
2. 核心领域模块和编排代码。
3. 算法、解析器、编译器、调度器、状态机、缓存、并发、安全、持久化、网络边界和错误处理。
4. 能揭示预期行为和边缘情况的测试。
5. 构建、CI、发布和开发者工具。
6. 示例、测试夹具、迁移、生成产物和遗留代码。

针对每个重要子系统，识别：

• 关键文件和符号。
• 职责和边界。
• 输入、输出、副作用和不变量。
• 正常路径和失败路径。
• 设计权衡，以及代码采用当前结构的可能原因。
• 测试或测试缺失之处。
• 维护风险和安全的修改位置。

每个深入介绍页面都应充分阅读实现和测试，以支持以下所有设计质量要点：设计／架构、控制流或数据流、权衡或决策、不变量或契约、失败模式、测试依据和维护风险。如果无法通过源码支持大多数要点，应将该页面的覆盖级别降为中等，而不是用冗余内容填充。

5. 编写 Wiki 目录

默认目录框架请使用 references/wiki_structure.md 中的大纲。根据仓库调整文件名和标题，不要强行加入不相关的部分。

请按以下顺序撰写初稿：

1. index.md、repository-map.md、架构概览和维护者手册。
2. 端到端运行时流程和最复杂的 5-15 个子系统。
3. 复杂模块目录的独立设计、流程、测试和维护者页面。
4. 辅助模块页面、开发页面、术语表和索引。

不要一开始就生成数百个几乎相同的文件页面。只有在概念页面已经有用之后，才可以将文件索引作为导航辅助。

不要将页面标记为自动生成，不要包含重复的编号维护章节，也不要用“需要维护者确认”之类的泛泛措辞代替分析。只有在说明代码确实能证明什么之后，才提出范围明确的开放问题。

Wiki 文档包通常应包括：

• 根目录下的 index.md，其中包含完整的页面索引和推荐阅读路径。
• 仓库地图和目录概览。
• 本地开发快速入门。
• 带图表的架构概览。
• 端到端执行路径页面。
• 模块／包／目录的深入介绍页面或子目录。
• 核心子系统页面或子目录。
• 重要算法、数据结构和不变量。
• 配置、构建、测试、发布和运维页面。
• 包含常见更改方案的维护者手册。
• 故障排查、术语表、文件索引、符号索引和开放问题。

最低规模与结构目标

不要只写简短概述。这项技能面向需要完善文档的代码库。质量检查器支持两种模式：

动态模式（推荐）： 使用 --loc 传入项目的代码行数，让脚本计算比例阈值。这样可以避免知识库相对于项目规模过大或过小：

node <skill_dir>/scripts/wiki_quality_check.cjs <wiki_dir> --loc <project_loc>

该公式会按比例计算字数（约为 LOC 的 4 倍）、文件数（每 2000 LOC 约 1 个文件）、文件引用数（LOC 的约 7%）以及深度解析页面数。防灌水检查仍采用固定阈值。

语言说明（中文、日文、韩文及其他非英语知识库）： 字数和非空行目标是按英文文本校准的，因为英文通常一个词对应一个词元。中文、日文和韩文的单位字符信息密度要高得多，因此，用中文充分说明同一套架构时，字数会低得多。检查器会自动检测中日韩文字比例，并相应降低字数和行数目标（纯中日韩文字知识库的英文目标字数大约减半）；结构、文件引用、深度解析和防灌水阈值与语言无关，不会降低。即便降低目标后，中日韩文字知识库仍可能无法通过字数检查——只要防灌水检查项都合格，且内容确有设计深度，这就是可以接受的。绝不要为了达到字数而灌水；这会牺牲质量，去追求这项技能明确禁止的指标。

配置档案模式（超大型项目的参考基准）：

配置档案	常见适用条件	最低目标
Large	大型应用或库，代码量达数万 LOC	30+ 个 Markdown 文件、250,000+ 字、15,000+ 个非空行、1,200+ 个标题、1,800+ 个唯一反引号文件引用
Huge	数十万 LOC，单体仓库、平台或框架	80+ 个 Markdown 文件、600,000+ 字、35,000+ 个非空行、2,600+ 个标题、4,500+ 个唯一反引号文件引用
Massive	超大型单体仓库或多产品系统	150+ 个 Markdown 文件、1,200,000+ 字、70,000+ 个非空行、5,200+ 个标题、9,000+ 个唯一反引号文件引用

这些配置档案是超大型项目的参考基准。对于大多数代码仓库，建议优先使用 --loc 模式来获得符合比例的预期。检查器是辅助工具，而非硬性门槛——真正的质量标准是设计深度、架构清晰度，以及对维护者的实用性。

对于未知代码仓库，可快速估算 LOC（例如，使用 find src -name '*.rs' | xargs wc -l），然后使用 --loc。对于每个重要的顶层目录，都应创建或纳入一个专门的章节或页面。对于每个复杂模块或核心子系统，优先采用包含多个主题明确页面的子目录，而不是一篇过长的页面。应涵盖关键文件和符号、工作原理、测试、故障模式以及维护者须知。优先补充缺失页面和有依据的说明，而非灌入泛泛而谈的内容。

6. 验证覆盖范围和准确性

定稿前，请检查：

• 存在一个 wiki 包，而不只是一个 Markdown 文件。
• index.md 链接到每个主要 wiki 页面。
• 每个顶层目录都有说明，或明确标记为生成文件、供应商文件、缓存或无关内容。
• 每个主要包/模块至少有一条简短的用途说明。
• 端到端追踪核心入口点和执行路径。
• 关于行为的论断都有代码、测试、配置或文档作为依据。
• 图表与文字说明一致。
• Mermaid/Graphviz/KaTeX 代码块在语法上合理。
• wiki 区分事实与推断。
• 核心概念页面不可由表格或文件列表替代；它们应说明设计、数据/控制流、权衡、不变量、故障模式、测试和安全的修改点。
• 重复的样板内容、通用编号章节或复制的段落不算深入分析。请将其改写为针对仓库的分析，或直接删除。

对 wiki 包运行 Node 质量门禁；如果未通过，请扩充 wiki：

node <skill_dir>/scripts/wiki_quality_check.cjs <wiki_dir> --loc <project_loc>

仅将 --profile large|huge|massive 用作超大型项目的参考基准。比例预期优先使用 --loc。检查器会强制要求最低 Markdown 文件数、字数、非空行数、标题数、H2 章节数、唯一的反引号文件引用数、围栏代码块数、表格数、深入分析页面数，并限制重复内容、禁止的填充短语和索引页占比。

页面只有在字数、文件引用和不同的设计质量信号都足够时，才会被视为合格的深入分析页面。这是有意为之：一个名为 architecture.md、内容泛泛的页面应该无法通过门禁。

如果检查器通过了，但人工或后续审查认为 wiki 流于表面，请将其视为实际失败。停止优化数量，重新阅读核心源代码路径，围绕架构和维护工作重新设计 wiki，并替换薄弱页面，而不是为指标辩护。

图表和数学公式

谨慎而具体地使用图表。

Mermaid

使用 Mermaid 绘制架构、时序、流程、状态和依赖关系图：

```mermaid
flowchart TD
  CLI["CLI entrypoint"] --> Core["Core orchestration"]
  Core --> Adapter["Platform adapter"]
  Core --> Tests["Behavior covered by tests"]

### Graphviz

Use Graphviz DOT only when the user has requested a documentation site (Rspress), since it requires `rspress-plugin-viz` to render. Prefer Mermaid for plain Markdown wiki output. Graphviz is useful when clustered subgraph layout or complex dependency visualization is clearer than Mermaid:

```markdown
```dot
digraph G {
  rankdir=LR;
  subgraph cluster_core { label="core"; parser; planner; executor; }
  parser -> planner -> executor;
}

### KaTeX

Use KaTeX for formulas, complexity, scoring, or algorithmic invariants:

```markdown
The cache hit ratio is $H = \frac{hits}{hits + misses}$, and the lookup path is expected $O(1)$ under normal hash distribution.

输出质量标准

优质的仓库 wiki 包应：

• 让新手阅读 index.md 和架构概述后，能够说明该仓库的用途。
• 让维护者无需通读一篇巨型文档，就能找到常见修改所对应的页面。
• 说明重要代码为何采用当前结构，而不仅仅列出有哪些文件。
• 指出不明显的耦合关系、不变量和边界情况。
• 包含足够的文件/符号引用，便于导航。
• 达到或超过适用的最低篇幅和结构目标，不掺水。
• 避免不加解读地罗列原始文件树。
• 避免用生成的文件索引、重复的维护建议或通用页面模板代替设计分析。
• 避免臆造架构：如果不确定，应说明现有证据表明什么，以及哪些问题仍未明确。

使用捆绑资源

• 使用 Node 运行 scripts/repo_snapshot.cjs，生成仓库清单、语言/配置摘要和候选阅读计划。
• 使用 Node 运行 scripts/wiki_quality_check.cjs，验证生成的 wiki 包没有过于简短或结构不足。
• 起草或审查最终 wiki 包大纲时，请阅读 references/wiki_structure.md。
• 只有当用户明确要求将 wiki 转换为 Rspress 或静态文档网站时，才阅读 references/rspress_docs_site.md。