SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场git-wiki

git-wiki

写作与研究

查看项目

更新于 10-16 02:02

技能介绍

用途

git-wiki 用于为代码项目构建和维护本地 Wiki。默认在 .wiki 目录下工作，也支持语言特定的根目录，例如 .wiki-cn、.wiki-fr，或用户明确指定的目录名（如 wiki-cn）。

其事实来源始终是当前 git 跟踪的仓库文件（HEAD），包括 .docs/ 和 docs/ 中已跟踪的文档，而不是 Wiki 本身。Wiki 文件本身可能未被 git 跟踪；当工作树中存在所选 Wiki 根目录时，直接读取和更新该目录。

主要能力

  • Ingest（摄取）：根据保存的 last_commit 自动检测变更文件，读取相关仓库文件，在所选 Wiki 根目录下创建或更新页面，并更新 index.md。
  • Export（导出）：将所选 Wiki 根目录下的实时工作树文件打包为单个 Markdown 文件，包含目录、页面分节和文件起止标记，可用于归档或作为 NotebookLM 来源。
  • Query（查询）：回答项目问题时，优先读取所选 Wiki 根目录的页面；若页面缺失或标记为 stale，则直接对照 git 跟踪的仓库源码进行验证。
  • Lint（检查）：检查页面间矛盾、孤立页面、缺失概念页、stale 页面、重大变更模块的覆盖缺失以及损坏的 [[wiki-link]]，并输出报告。

使用方式

触发词包括：ingest、ingest [file]、ingest [folder]、ingest wiki-cn、ingest .wiki-fr、refresh wiki、update wiki、update Chinese wiki；export wiki、bundle wiki、archive wiki、one-page wiki、prepare wiki for notebooklm、send wiki to notebooklm；lint、lint wiki、check wiki、lint .wiki-fr、check Chinese wiki。

导出使用内置零依赖 CLI：

node skills/git-wiki/scripts/export-wiki-bundle.mjs \
  --input-dir <wiki-root>

默认输出为所选 Wiki 根目录下的 index-{simple-timestamp}.md。可通过 --output-file <path> 指定输出路径，通过 --root-name <name> 自定义导出头部标签。

适用场景

  • 为代码项目建立人类可读的本地 Wiki，帮助新成员快速理解项目。
  • 维护多语言 Wiki（如中文、法文），各语言根目录相互独立。
  • 将 Wiki 打包导出，用于归档或作为 NotebookLM 的输入来源。
  • 通过 lint 检查 Wiki 与源码之间的漂移。

限制

  • 仅操作 git 跟踪的文件和 git 历史；忽略已暂存和未暂存的未提交更改，摄取和查询验证仅使用 HEAD 的已提交内容。
  • 每次请求只选择一个 Wiki 根目录。
  • 各 Wiki 根目录相互独立，除非用户明确要求，否则不在语言根目录之间同步、比较、翻译、合并或复制页面。
  • 从基于 git 的源选择中排除所有 Wiki 根目录：.wiki/、.wiki-*/、wiki-*/**。
  • 不假设任何 Wiki 根目录已被 git 跟踪；使用所选根目录当前的 index.md 检查点（如果存在）。
  • 如果 git 元数据不可用，不回退到文件系统扫描；在 git 访问恢复之前，摄取和 lint 不可用。
  • 导出读取所选 Wiki 根目录下的实时工作树文件，而非 HEAD 的 git 跟踪仓库。
  • 导出不是摄取的替代；导出打包当前 Wiki，不重建它。
  • 除非明确要求，否则不自动修复 lint 发现的问题。

Wiki 布局

必需：<wiki-root>/index.md — 人类入口点和主目录（仅跟踪该根目录的最后摄取提交）。

可选（按需创建）：overview/、features/、bug-fixes/、concepts/、entities/、flows/、risks/、reference/、notes/。

index.md 必须按顺序回答以下问题：这是什么？如何开始？为什么存在？运行它时会发生什么？数据保存在哪里？重要的活动部件有哪些？应避免破坏什么？首先看哪里？

页面约定

每个 Wiki 页面必须有 YAML frontmatter。index.md 携带额外字段跟踪摄取状态：title、type、status、language、last_commit、updated_at。其他页面使用：title、type、status、language、source_paths、updated_at。

页面命名使用小写、连字符文件名，如 auth-middleware.md、user-schema.md。页面之间使用 [[page-slug]] 链接。

写作指导

面向聪明的新手而非维护者写作。先用通俗术语，再在有助于理解时补充准确的代码术语。围绕读者的问题组织页面，再以文件为依据。解释文件在产品或工作流中为何重要，再命名实现细节。避免未解释的缩写、框架术语和内部简写。总结而非复制大段代码。使用具体文件路径作为锚点。区分事实与推断。用 [[wiki-links]] 交叉链接相关页面。页面保持在约 500 词以内。

质量门槛

当 index.md 帮助新读者在 2 分钟内导航项目、新成员能回答项目是什么、为何存在、运行时发生什么、数据保存在哪里、什么重要、不应破坏什么以及首先看哪里、答案可从 Wiki 页面开始并在代码中验证、摄取使用保存的 last_commit 自动检测变更文件、lint 在 Wiki 变得误导之前捕获漂移时，Wiki 即成功。