ingest

技能：ingest

WHAT

目的和上下文

• **目的：**处理 raw/ 中的新文件，将知识提炼到 wiki 中。每次 ingest 会涉及 10–15 个 wiki 文件。
• **触发条件（何时调用）：**当 raw/ 中出现新文件时自动调用。
• **非目标：**不修改 raw/ 中的文件，不为来源未实际介绍的内容创建页面，不根据来源内容编写代码或实施（这属于 /propose → /plan）。

思维模型

raw/<file>（不可变）→ takeaways（事实 · 决策 · 实体 · 概念）→ docs-impact-plan → 概念/实体页面（规范归属页）+ 来源页面 → wikilinks → 索引 + 日志 → 草稿输出报告。

输入和输出约定

	字段	必填？	含义
In	raw/ 中的文件路径	是	完整读取来源，仅供读取
Out	wiki/concepts/ · wiki/entities/ 页面	视来源而定	新建或进行精准更新，包含 OKF frontmatter + ## Origin
Out	wiki/sources/<...>.md 页面	是	总结来源，并链接回 raw/
Out	wiki/index.md + wiki/log.md	是	每个新建/修改的文件都要在索引中添加一行；日志格式为 ## YYYY-MM-DD — ingest — <filename>
Out	wiki/sources/draft/DDMMYY-<ten>.md	是（除非没有任何产出）	输出报告

规则和能力

• RULE-01 (MUST)：**OKF v0.1 (R9)：**每个 wiki 页面都以 YAML frontmatter 块（---）开头，其中包含非空的 type（例如 concept、entity、source）以及可选的 title/tags/timestamp/resource。复制匹配的 _template.md。保留 ## Origin 正文部分（R2）。
• RULE-02 (MUST)：绝不修改 raw/ 中的文件。仅供读取。
• RULE-03 (MUST)：除非来源实际介绍了某个实体或概念，否则不创建 wiki 页面。
• RULE-04 (MUST)：优先更新现有页面，而不是创建重复页面。
• RULE-05 (MUST)：规范归属页：每个概念都应有一个主页面——详细内容放在那里，其他页面只简短提及并添加 [[wikilink]]；不要在多个页面重复相同的解释。
• RULE-06 (MUST)：精准更新现有页面：更新时只替换过时的句子，不重写仍然正确的部分；禁止仅为格式而编辑（在内容无误时重新排版表格、调整空行或改写措辞）。
• 能力：读取 raw/；写入 wiki/（concepts · entities · sources · draft）+ 索引 + 日志。不得写入 raw/，不得联网。

失败边界

• 无法读取来源文件 / 文件为空 → blocked，报告路径，不创建页面。
• 来源未介绍任何新概念/实体 → 仅创建来源页面 + 索引 + 日志（范围有限的 succeeded），不创建多余页面。
• 来源与现有 wiki 页面内容矛盾 → 在来源页面记录矛盾，并在替换当前正确的句子前先向用户澄清。

HOW

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	效果	文件 raw/	完整读取来源，不要过早总结	完整内容	读取错误 → 阻塞
W02	判断	内容	提炼要点 + 制定 docs-impact-plan	受影响页面列表，每个页面都能追溯到一个来源要点	无法追溯的页面 → 跳过
W03	效果	impact-plan	更新现有页面 / 创建新的概念·实体	wiki 页面	—
W04	效果	来源	在 wiki/sources/ 中创建来源页面，链接回 raw/	来源页面	—
W05	效果	已处理页面	Wikilinks + wiki/index.md + wiki/log.md	index/log 一致	缺少 index 条目 → 修复后重试
W06	效果	结果	输出报告草稿（Delivery 部分）	草稿 + index + log	0 个工件 → 跳过

各步骤详情（W01–W06 的事实来源）：

1. 完整读取 raw/ 中的源文件。不要过早总结。
2. 提取关键要点：来源中的事实、决策、实体和概念。 然后在写入前制定 docs-impact-plan（提炼自 openwiki 060726）：điểm mới trong nguồn → trang bị ảnh hưởng → sửa/tạo gì → vì sao。无法追溯到来源中特定要点的页面，一律不要动。
3. 对于每个实体或概念：
   • 已有 wiki 页面：打开页面，添加/修改相关信息。
   • 没有页面：在 wiki/concepts/ 或 wiki/entities/ 中创建页面。
4. 在 wiki/sources/ 中为来源创建或更新摘要页面（链接回 raw/ 文件）。
5. 在所有新建/更新的页面之间添加 [[wikilinks]]。
6. 在 wiki/index.md 中更新每个新建或修改的文件。
7. 在 wiki/log.md 中追加：## YYYY-MM-DD — ingest — <filename>，并以项目符号列出所有处理过的页面。

分支

ID	类型	条件	行为	跳过 / 失败	汇合
B01	必需条件	entity/concept 已有页面	打开页面，精准添加/修改相关语句（surgical）	—	W04
B02	必需条件	entity/concept 没有页面	使用 _template.md 在 wiki/concepts/ 或 wiki/entities/ 中创建页面	来源并未真正介绍该实体/概念 → 不创建	W04

验证与停止

每个新页面都有非空的 frontmatter type + ## Origin（由 hook 检查 R2/R9）；每个新建/修改的文件都在 wiki/index.md 中有对应条目（R3）。当 impact-plan 中的所有条目都已处理或有理由排除时，停止。

示例

• **正面示例：**添加 raw/prd/X-PRD.md 介绍新标准 → 创建 wiki/concepts/<标准>.md + wiki/sources/DDMMYY-x-prd.md，修改相关概念中的 1 个句子，并更新 index + log + 报告草稿。
• **边界/失败：**raw 文件只有无法读取文字的屏幕截图 → 阻塞，通知用户，不创建空页面。

交付 — 输出报告

完成所有主要技能任务后，向 wiki 写入一份建议草稿。

步骤

1. 构建文件名：

• 格式：DDMMYY-<ten>.md
• DDMMYY = 今天的日期（例如，2026 年 6 月 2 日为 020626）
• <ten> = 用 2–4 个 kebab-case 单词概括完成的工作（例如，landing-page-coteccons、brand-kit-fintech、ingest-auth-spec）

2. 写入 llmwiki/wiki/sources/draft/DDMMYY-<ten>.md：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** <skill-name>, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what this skill invocation produced or decided>

## Output
<Key artefacts, files created/modified, or decisions made>

## Files
| File | Action |
|------|--------|
| `path/to/file` | created / modified |

## Notes
- Invoked via: `/<skill-name>` skill

## Origin
- **Draft:** `wiki/sources/draft/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. 更新 wiki 索引和日志：

• llmwiki/wiki/index.md — 追加一行：| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |
• llmwiki/wiki/log.md — 追加：## YYYY-MM-DD — <skill-name> — <ten>

仅当该技能未生成任何工件且没有任何决策时才跳过（例如，像 /caveman-stats 这样的纯显示模式）。