open-repo-wiki-skill

English · 中文

一个开源的 Agent Skill：为任意 Git 仓库生成深度结构化 Wiki 文档——项目概览、目录规划（Spec）、带行号级源码引用的内容页、模块知识卡。全程透明、可审计，可在任意支持 SKILL.md 的 agent 环境中运行。

为什么做这个

深度的仓库文档——架构分层、模块细节、行号引用、状态机图——手写通常需要数天的阅读与整理；而直接让 LLM「给这个仓库写文档」往往得到浅薄或幻觉内容。本 Skill 把「深度文档为什么深」拆解为可复现、与模型无关的工程流程：

• 先规划后写作：catalog-plan.json 是写作契约（Spec），批量写作前必须经用户确认。
• 零幻觉纪律：所有行号引用 file://相对路径#Lx-Ly 必须来自真实读取过的代码；写入正文、表格、图中的每个类名/方法名必须验证在仓库中存在。
• 领域不变量贯穿：侦察阶段提炼的系统级约束（依赖方向、状态机、关键分层）写入 wiki_plan.yaml notes，并在所有页面中体现。
• 检查点可恢复：progress.json 跟踪已完成/待写页面，长任务中断后可从断点继续。

产出目录布局

<repo>/.openrepowiki/
├── wiki_plan.yaml                 # 干预配置（不变量 notes + 页面白名单）
├── progress.json                  # 写作检查点
├── generation-report.md           # 收尾报告
└── <lang>/
    ├── meta/
    │   ├── overview.md            # 项目综合概览
    │   └── catalog-plan.json      # 目录规划（Spec）
    ├── content/                   # Wiki 内容页（按 catalog 层级嵌套）
    └── knowledge/<lang>/<模块>/    # 知识卡
        ├── _module.yaml
        └── 概述/架构设计/技术栈/编码规范/特殊配置与命令（5 张卡）

安装

方式 A — npx 安装器（推荐）

npx open-repo-wiki-skill

安装器会自动探测你机器上的 agent skills 目录（如 ~/.qoder/skills、~/.claude/skills、~/.codex/skills）并把 skill 复制进去。常用参数：

npx open-repo-wiki-skill --list           # 列出已知 skills 目录
npx open-repo-wiki-skill --target <目录>   # 安装到自定义目录
npx open-repo-wiki-skill --uninstall      # 卸载

方式 B — git clone

git clone https://github.com/niceforbear/open-repo-wiki-skill.git <你的-agent-skills-目录>/open-repo-wiki

任何识别 SKILL.md 的 agent 运行时均可加载。依赖仅 Python 3.8+（标准库）与 git；符号校验脚本推荐安装 rg（ripgrep）。

使用

对 agent 说：

用 open-repo-wiki 技能为这个仓库生成 wiki。

Skill 从你的消息中提取参数（目标仓库、语言 zh/en、产出目录、范围过滤、深度），执行六阶段流水线：

| 阶段 | 内容 | | --- | --- | | 0 扫描 | scan_scope.py 输出文件数、语言分布、入口/构建/文档文件清单 | | 1 侦察 | 读 README / AGENTS.md / 构建文件 / 主入口，产出 overview.md + 系统不变量 | | 2 目录规划 | 产出 catalog-plan.json + wiki_plan.yaml，等待你确认 | | 3 内容页 | 按模板写作：cite 头、目录、核心组件、≥3 张图、依赖分析、性能考量、故障排查、结论、关键路径附录 | | 4 知识卡 | 每模块 _module.yaml + 5 张卡；命令只取自仓库内真实文件 | | 5 校验收尾 | 双重校验（见下）+ 索引页 + 生成报告 |

使用示例

在任意仓库上的一次完整会话：

# 1. 安装（本机或其他任意电脑，只需一次）
npx open-repo-wiki-skill

# 2. 用支持 SKILL.md 的 agent 打开你的项目，对它说：
> 用 open-repo-wiki 技能为这个仓库生成 wiki，语言用中文。

agent 会交互式地走完流水线：

Agent: 已扫描 1,284 个文件（Python 74% / Go 22%）。侦察完成，
       这是建议的目录规划（12 页），确认后开始写作？
你:    确认。
Agent: 内容页写作完成。校验结果：236 条引用 0 失效，87 个符号 0 幻觉。
       Wiki 已生成。

产出落在你的仓库里：

<你的仓库>/.openrepowiki/
├── zh/content/项目概述.md               # 每个目录项一页
├── zh/content/核心架构.md
├── zh/meta/catalog-plan.json
└── knowledge/zh/<模块>/...              # 每模块 5 张知识卡

可直接浏览这些页面，或 git add .openrepowiki && git commit 分享给团队。代码重构后要更新文档时，让 agent「重写受影响的页面」即可（局部干预模式）。

工具脚本（纯标准库）

| 脚本 | 用途 | | --- | --- | | scan_scope.py | 范围扫描：文件数、语言分布、建议排除项 | | verify_citations.py | 逐条验证 #Lx-Ly 引用的真实性（0 失效才算完成） | | verify_symbols.py | 提取正文/表格/mermaid 图中的标识符并在仓库代码中验证存在性——专抓 LLM 写作最隐蔽的失败模式：幻觉类名/方法名 | | compare_wikis.py | 两份 Wiki 产出的结构化对比（覆盖度、章节覆盖率、引用密度） |

写作契约要点

• 每个事实性论断附行号级引用；区间必须来自实读（禁止 L1-L<文件末尾> 这类整文件引用）。
• 每个二级章节末尾附章节来源列表；每张图后附图表来源。
• 子系统页广度下限：引用文件 ≥6 个——防止系统性遗漏旁支子系统。
• 图中符号先经 grep 验证再写入，不得凭语义推测命名。
• 完整操作指南见 best-practices.md（由真实运行沉淀）。

局限

• 写作质量取决于执行的 agent 模型与上下文预算。
• 不做自动变更检测：指出变更范围后用「局部干预」模式重写受影响页。
• 不依赖任何专有元数据文件：导航索引由 progress.json + 产出内索引页提供。

License

MIT — 见 LICENSE。