技能介绍

要解决的问题

面对一个陌生仓库，工程师常见的困境是：直接开读，读到一半才发现某个模块其实是另一个模块的同步副本；或者先写了文档大纲，落笔时才发现漏掉了核心配置。repo-doc-miner 要解决的就是文档顺序与仓库结构脱节的问题——尤其是大仓库里文件数量达到数百上千、人工梳理依赖关系成本过高时，先拿到结构图再动笔能显著降低返工率。

另一个常被忽视的坑是副本误判。很多仓库存在单一事实来源（single source of truth）加上多份同步副本的结构，平铺扫描容易把副本当成独立实现来写，导致文档重复且互相矛盾。

工作方式：先拓扑，再深挖

该技能采用两阶段方法：

阶段一：拓扑生成（核心交付物）。先用 scripts/gen_topology.py 自动扫描仓库，识别实体类型（模块、skill、agent、command、connector、配置文件、脚本等）并提取实体间的依赖边。关键是把每条边分类为 source → copy 或 use/depend，前者标记出单一事实来源及其副本——这正是平铺扫描会误判的地方。脚本产出的 topology.md（Mermaid 结构图 + 依赖边图 + 实体清单表）是首要交付物，也是后续所有写作的结构骨架。
阶段二：沿边深挖。模块按复杂度/价值排序阅读，且沿着拓扑边走：先读单一事实来源，再读它的副本与依赖方。配合 references/evidence_checklist.md 按仓库类型（Python DL 库、CLI、Node 应用、Rust crate、Go 服务）选择要收集的证据，证据缺失时以 > TODO(doc-miner): ... 显式标注，而不是编造。

之后按固定模板产出五份文档：topology.md、developer_guide.md、user_guide.md、tutorial.md 和导航用的 README.md，全部交叉链接，且每条技术断言都标注代码内的文件路径。

适用边界与注意点

不适用：单文件 API 文档、仅刷新 README、翻译任务，或已有 Sphinx/MkDocs 站点框架的场景——技能默认写入独立的 docs/guides/ 子目录，避免覆盖现有文档。
脚本只是草稿：gen_topology.py 是启发式的，关键的 2–3 条依赖边必须人工对照真实 manifest 确认后才能定稿。
防幻觉机制：代码片段压缩到 30 行以内且只取自 examples/ 或 tests/，禁止虚构 API；写完后要抽查代码片段与原文一致。
topology.md 支持增量更新，仓库演进后重跑脚本即可 diff 结构变化。