wiki-ingest

摄取 — 将来源内容处理到 wiki 中

遵循 wiki/CONVENTIONS.md 中的格式约定、frontmatter、命名和语言要求。

语言

使用用户的语言编写产物。确保语法正确，并使用任何必需的变音符号或特定文字系统字符。如果无法确定用户使用的语言，请先询问，再生成输出。

项目根目录

此技能会在相对于项目根目录（执行工作的仓库）的路径下写入产物，而不是相对于 Agent 当前的工作目录。

• 如果从项目内部调用，请使用此技能中显示的相对路径。
• 如果从其他目录调用（例如，从同级仓库调用，或项目位于其他位置），请在每个产物路径前加上 <project-root>/。
• 如果项目根目录不明确，请通过 harness 的提问工具向用户确认，然后再写入。

提示

遵循 CLAUDE.md / AGENTS.md 中的全项目约定（“Skill Prompting Conventions”）。对于以下决策点，请使用 harness 的结构化提问工具：AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。

决策点	使用结构化提问的原因	建议选项
吸收新内容的现有页面（或创建新页面）	会影响 wiki 布局	匹配列表 · 创建新页面
将来源拆分到哪些受众文件夹（多选）	保持内容分区	business · apps · ops · data
强调或跳过哪些具体要点（多选）	会影响最终收录内容	从找到的要点中选择

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

• 页面标题
• 摘要文本
• 标签值

无暂停模式：如果用户已明确禁用技能执行过程中的澄清提问，请将每个结构化提示转换为“待确认问题”（或类似部分）中的条目，并继续执行，不要暂停。

查询语言对齐

将来源与现有 wiki 页面匹配时，请使用 wiki 语言进行搜索，该语言不一定与用户或来源所用语言相同。首先从 .wiki-guardrails.yml 中确定 wiki 语言（query_language 或 language）；若不存在 guardrails，则从 wiki frontmatter 或索引中确定。产品名称、文件名、API、schema 名称和代码标识符保持不变。

• 将 QMD 的 intent:、vec: 和 hyde: 翻译为 wiki 语言。
• 如果来源中的确切术语可能会以未翻译的形式出现，请在 lex: 中保留这些术语。
• 除非目标页面明显使用其他语言，否则请使用 wiki 语言编写或更新 wiki 产物。
• 使用用户的语言向用户传达进度和问题。

检索 — 有 QMD 时优先使用

搜索应吸收新来源内容的现有页面时，如果 wiki 已设置 QMD，请使用 QMD（本地混合搜索）。每个仓库只需设置一次，详见 docs/wiki/qmd-setup.md。

• 如有可用选项，请使用 mcp__qmd__query（MCP）或 qmd query --json --files（CLI），而不是 grep/glob。
• 始终向 QMD 传入一行 intent:，描述新来源的主题——这能显著提升与现有页面的匹配效果。
• 只有在未配置 QMD 时，才回退到 grep/Glob。

摄取完成后，提醒项目负责人运行 qmd update（如果新增了集合，则运行 qmd embed），以便索引反映新增页面；切勿自动运行这些命令。

步骤

1. 确定用户要求处理的来源（来自对话上下文或提供的路径）。

2. 通过查看 raw/index.md 检查来源是否已录入：

   • 如果已录入（wiki/sources/ 中已有摘要）→ 按照下面的重新录入流程处理。
   • 如果尚未录入 → 继续正常录入。

3. 完整阅读 raw/ 中的来源（如有上下文长度限制，可分段阅读）。

   • .txt 或 .md 转录文本 → 直接阅读。
   • 如果 MCP video-whisper 可用 → 直接转录视频/音频。
   • 如果 MCP pdf-docling 可用 → 将 PDF 转换为 Markdown。

4. 并行提取并呈现：

   • 提取来源中最重要的 3-5 个要点。
   • 对每个要点，运行 QMD 查询（或使用 grep 作为备选方案）以查找相关的现有页面——将要点本身用作 intent:，将简短释义用作 vec:。
   • 将要点及匹配到的页面一并呈现给用户。
   • 询问用户是否希望重点强调或跳过任何内容。
   • 等待确认后再继续。

5. **确定每条规则应归入的位置。**遵守受众划分：

   • wiki/business/ — 所有业务/产品规则（受众：业务人员）。定价、用户旅程、政策、变现、隐私/合规规则，以及任何面向客户或具有合同性质的内容。
   • wiki/apps/ — 应用层技术文档（受众：开发人员）。技术栈、注意事项、部署细节。此处不得包含业务规则——如有相关内容，请链接到 wiki/business/。
   • wiki/ops/ — 运维流程（受众：运维人员）。
   • wiki/data/ — 数据模型和架构（受众：开发人员）。
   • 如果来源同时包含业务和技术内容，请拆分到相应目录，不要混写在同一个页面中。

6. 根据确认创建/更新 wiki 页面：

   • 如果页面已存在 → 更新（在 sources: 中添加来源，修订内容，并标记冲突）。
   • 如果页面不存在 → 按照 wiki/CONVENTIONS.md 创建新页面。
   • 使用标准 Markdown 链接：[text](./path.md)（不要使用 wikilinks）。
   • 不要在多个页面重复相同内容——请使用交叉引用。
   • 同级仓库请使用相对于 wiki 的路径 ../<repo>/ 引用，不要使用绝对路径。首次提及仓库时，添加 GitHub 远程链接 [github.com/<org>/<repo>](https://github.com/<org>/<repo>)。

7. 在 wiki/sources/<slug>.md 中创建来源摘要：

   ---
   title: "Summary — <Source Title>"
   audience: mixed
   sources:
     - raw/<subdir>/<filename>
   updated: YYYY-MM-DD
   tags: [source, <relevant-tags>]
   status: stable
   ---
   

   摘要内容：

   • 元数据（日期、参与者、时长，如适用）
   • 要点摘要
   • 创建/更新的 wiki 页面及其链接
   • 未在其他页面中记录的见解（如有）
   • 待定决策——如果来源提出了需要负责人回答的问题，请明确指出，不要擅自做出选择。

8. 并行更新索引：

   • raw/index.md — 将来源标记为 ✅ 已录入，并链接到摘要。
   • wiki/index.md — 在相应表格中添加新页面，并更新已修改页面的描述。
   • wiki/log.md — 在顶部（标题之后、现有条目之前）记录操作：

     ## [YYYY-MM-DD] ingest | <Source Title>
     - Pages created: ...
     - Pages updated: ...
     - Summary: wiki/sources/<slug>.md
     

9. 针对性地进行录入后检查：

   • 验证新建/更新页面的交叉引用（链接是否指向真实目标？）。
   • 与引用的页面进行比较——如有冲突，请添加明确的章节标记。
   • 不要运行完整检查（孤立页面、全局 frontmatter 等）——这些检查由 /wiki-lint 执行。

10. 告知负责人刷新 QMD 索引（仅当此 wiki 配置了 QMD 时）：

    qmd update         # 纳入已更改/新增的页面
    qmd embed          # 仅在添加/删除了集合时需要
    

    不要替负责人运行这些命令——请在最终报告中说明。

重新摄取（来源已编入目录）

如果来源已有 wiki/sources/<slug>.md：

1. 阅读来源和现有摘要。
2. 比较并找出缺漏：
   • 来源中有、知识库中没有的概念／信息（将每个候选缺漏设为 intent:，使用 QMD 确认其是否缺失）
   • 可以扩展的页面
   • 与现有内容相矛盾之处
3. 向人工审核者呈现诊断结果：

   ## Re-ingest: <Title>
   ### Identified gaps
   - ...
   ### Pages that can be expanded
   - ...
   

4. 等待批准后再执行。
5. 更新摘要、raw/index.md 和 wiki/log.md。

规则

• 绝不修改 raw/ 中的文件。
• 一次处理一个来源（除非用户明确要求批量处理）。
• 始终使用完整的 YAML frontmatter（参见 wiki/CONVENTIONS.md）。
• 如果发现与现有页面矛盾，必须明确指出。
• 始终更新 raw/index.md、wiki/index.md 和 wiki/log.md。
• 业务规则应放在 wiki/business/ 中，绝不可放在产品／代码仓库中。如果某条规则目前位于产品仓库中（例如 ../<product>/docs/ 下），摄取时应将其迁移到 wiki/business/，并在适当情况下于产品仓库的 CLAUDE.md / AGENTS.md 中留下交叉引用。
• 绝不自动运行 qmd embed / qmd update / qmd collection add——这些命令由所有者运行。