wiki-init

wiki-init

使用此技能可将代码库初始化或迁移为 wiki + QMD + Agent hook 模式。

用户可能会使用自然语言。按以下方式处理意图：

• “结构是什么样的？”，“需要迁移吗？”，“doctor”，“qmd 正常吗？” -> 运行 doctor。
• “安装”，“准备这个代码库”，“配置 hooks” -> 先以试运行方式运行 install，然后在执行 --write 前询问用户是否确认建议的 wiki 位置和索引。
• “迁移到新格式” -> 先以试运行方式运行 migrate，然后在执行 --write 前询问用户是否确认建议的 wiki 位置和索引。
• “修复 qmd”，“托管的 qmd”，“修补 qmd” -> 运行 doctor，然后在获得明确批准后使用 install --write 或 update-hooks --write，以准备托管的 QMD 检出和包装器。

项目根目录

此技能中的所有路径（wiki/、AGENTS.md、CLAUDE.md、.mcp.json、hook 脚本等）都相对于通过 --project <path> 传入的项目根目录，而不是 Agent 当前的工作目录。

• 始终向脚本传入 --project <absolute-or-relative-path> ——它不会静默回退到 CWD。
• QMD 包装器命令（<wrapper> collection add <wiki-path>）接受绝对路径；如果 Agent 的 CWD 可能与项目根目录不同，请优先使用绝对路径。
• 从同级代码库（例如 meta/skills 代码库，而目标项目位于其他位置）调用时，请在执行 --write 前与用户确认 --project 的值。

工作流

1. 首先运行 scripts/wiki-init.ts doctor --project <path>。
2. 阅读报告：wiki 布局、AGENTS/CLAUDE、harness、hooks、缓存迁移、已安装内容的偏差和 QMD 状态。
3. 如需更改，先在不带 --write 的情况下运行 install 或 migrate，并展示计划执行的文件操作和建议的拓扑结构。
4. 明确询问用户：使用本地 wiki 还是共享 wiki？ 不要默默默认使用同级路径。使用 harness 的结构化提问工具（参见提问）。
   • 本地 ——wiki 位于此代码库内的 wiki/。适用于独立项目和私人实验。
   • 共享 ——wiki 位于此代码库之外（同级目录、中央知识库、monorepo 位置）。用户选择共享时，请用自由文本询问绝对或相对路径；检测到的同级路径（如 ../knowledge-base 等）仅为建议，必须由用户确认或替换。
5. 用自由文本向用户确认 QMD 索引名称。建议一个合理的默认值（本地使用项目基本名称，共享使用组织或产品名称），但允许用户自行指定。
6. 只有在明确传入 --wiki 和 --index 后，才能使用 --write。如果没有这些标志，脚本会阻止写入。
7. 写入后重新运行 doctor。
8. --write 会在技能缓存（~/.local/share/skills/qmd/checkouts/qmd）下准备托管的 QMD 检出，并将项目包装器指向该检出。如果缺少检出，会克隆 https://github.com/tobi/qmd.git 并在其中安装依赖项。
9. 如果目标项目需要索引，请使用生成的包装器初始化 QMD：<wrapper> collection add <wiki-path> --name <index> --mask "**/*.md"，然后运行 <wrapper> update 和 <wrapper> embed。
10. 更改可复用模板或脚本前，运行 scripts/validate-wiki-init.ts。

提示词

遵循项目级约定 CLAUDE.md / AGENTS.md（“Skill 提示词约定”）。对于以下决策点，使用运行环境提供的结构化提问工具——AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。仅在需要路径或标识符时使用自由文本。

决策点	使用结构化提问的原因	建议选项
Wiki 位置	决定整个安装方案：路径、钩子、预设	本地（仓库内的 wiki/）· 共享（单独路径）
检测到旧缓存时的迁移	难以撤销的复制操作	立即复制（保留旧缓存）· 跳过迁移
已安装文件出现偏差时的修复方式	会触发 update-hooks --write	全部更新 · 先显示差异 · 忽略
运行环境选择（多选），检测到多个运行环境时	避免配置用户不需要的 Agent	claude · codex · opencode · antigravity

用户回答后，在运行 --write 之前，用自己的话重述其选择。

自由文本提示（不使用结构化提问工具）：

• 共享 Wiki 路径
• QMD 索引名称
• 任何自定义 QMD 命令（--qmd-command）
• 任何需要用户输入、且技能无法枚举其取值的字段

doctor 报告内容

doctor 是始终安全的入口。它会报告：

• wiki_path、qmd_index、推荐的拓扑结构以及运行环境覆盖情况。
• 规范文件（AGENTS.md、CLAUDE.md、.wiki-guardrails.yml、MCP/Agent 配置）的存在情况。
• Markdown 偏差 — 配置的 Wiki 路径之外受跟踪的 .md 文件。
• 缓存迁移 — 检测旧版 ~/.local/share/essential-skills/qmd 缓存，并报告 --write 是否会将其复制到当前的 ~/.local/share/skills/qmd 位置。为确保安全，会保留旧目录（绝不删除）。
• 已安装文件偏差 — 对最新模板会生成的每个文件，将磁盘上的内容与预期内容进行比较。报告过时路径（例如，对旧缓存的引用）、AGENTS.md / CLAUDE.md 中过时的受管理代码块，以及落后于模板的钩子/配置。建议的修复方式是 wiki-init update-hooks --write。
• QMD 状态 — 受管理的检出位置、版本、补丁报告、索引状态。
• 计划执行的操作 — 下一次运行 install / migrate / update-hooks 时将创建或更新的每个文件。

脚本

主脚本：

bun skills/wiki-init/scripts/wiki-init.ts doctor --project .

侧重 QMD 的别名：

bun skills/wiki-init/scripts/qmd-doctor.ts --project .

该脚本有意默认采用试运行模式。只有使用 --write 才会写入。

常见示例：

bun skills/wiki-init/scripts/wiki-init.ts doctor --project /path/to/project
bun test skills/wiki-init/scripts/wiki-init.test.ts
bun skills/wiki-init/scripts/wiki-init.ts migrate --project /path/to/project --wiki ../knowledge-base --index my-index
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project
bun skills/wiki-init/scripts/wiki-init.ts install --project /path/to/project --wiki ../knowledge-base --index my-project --harness claude,codex,opencode,antigravity --write

预设

使用 references/presets.md 查看受支持的项目结构：本地 Wiki、中央同级 Wiki、多仓库组织 Wiki，以及仅文档迁移。

Wiki 内容脚手架

wiki-init 配置基础设施（配置、钩子、MCP、QMD 包装器），但不会创建 Wiki 内容。执行 install --write 后，Agent 必须创建其他 Wiki 技能所需的最小 Wiki 脚手架：

<project-root>/wiki/
├── index.md          # navigable catalog
├── CONVENTIONS.md    # schema, frontmatter, naming, audience separation
├── log.md            # append-only operation log
├── business/         # business/product rules (audience: business)
├── apps/             # app-level technical docs (audience: dev)
├── ops/              # operational procedures (audience: ops)
├── data/             # data models and schemas (audience: dev)
└── sources/          # ingested source summaries (one per slug)
<project-root>/raw/
└── index.md          # raw source materials inventory

受众区分和 frontmatter 约定定义于 wiki-ingest/SKILL.md。创建脚手架时，应将其视为命名、frontmatter 和内容布局的事实来源。

完成脚手架后，按照工作流第 9 步初始化 QMD 索引。

边界

• 不要自动摄取 Wiki 内容。钩子只负责发出信号；由 Agent 从语义层面作出判断。
• 不要全局修补或安装 QMD。
• 优先使用受管理的项目级 QMD 包装器，而非 shell 别名或 bunx。包装器必须附带来源清单，记录受管理的检出、上游仓库/引用、包装的二进制文件、版本、补丁报告、语言和嵌入模型。
• 可复用的技能文件中不得包含用户专属的绝对路径。只有在安装后生成的每台机器专属包装器/清单/配置中才可以出现本地绝对路径。
• 模板必须保留在此技能目录中。