wiki-ingest

Files (1)

• SKILL.md

SKILL.md (first lines)

# Wiki Ingest 技能

将外部源文档或对话发现的知识 ingest 到 wiki 中。

收到值得归档的源材料时加载此技能，统一委派 kiwi 蒸馏后执行写入。

---

## Phase 0 — 分类源材料

根据源材料的性质确定页面类型：

| 类型 | 特征 | 页面类型 |
|------|------|---------|
| 架构决策记录 | ADR、设计文档、RFC | source(adr) |
| 外部规范 | 第三方 API 文档、标准、指南 | source(rfc) |
| 会议记录 | 讨论总结、决策会议笔记 | source(notes) |
| 概念知识 | 关于某机制或原理的说明 | concept |
| 实体行为 | 某工具、agent、模块的行为 | entity |
| 分析对比 | 多个选项的权衡、经验总结 | analysis |

如果源材料无法明确归入以上类型 → 归类为 concept 类型。

该分类仅用于准入决策（确认材料值得摄入）。不传递给 kiwi，包括域分类也不传递。kiwi 会在其流程中基于源材料特征和 wiki 现状独立完成所有分类决策（归属域、页面类型、页面路径），传递任何分类结果会造成锚定效应，剥夺 kiwi 结合 wiki 全貌做决策的机会。

---

## Phase 1 — 委派 kiwi

### 1.1 准备源材料

根据输入形式执行对应的获取步骤：

| 输入形式 | 操作 |
|---------|------|
| 文件路径 | 用 `read` 工具读取完整内容 |
| URL | 直接将 URL 传递给 kiwi（kiwi 自己 webfetch 获取内容） |
| 文字描述 | 直接使用，整理为结构化格式 |
| 对话历史引用 | 从对话中提取相关段落 |

将源内容整理为 kiwi 可以直接消费的格式：
- 保留原文结构（标题、列表、代码块）
- 附上元信息：来源路径/URL、获取时间、内容长度
- 如果是 URL 输入，直接将 URL 放入 CONTEXT，kiwi 自行 webfetch 获取内容

### 1.2 构造三段式 Prompt

构造包含 SUMMARY / CONTEXT / ACCEPTANCE 三段的 prompt：

```
> 加载 `kiwi-distill` 技能后执行以下知识蒸馏任务。

**SUMMARY:** 将 [源材料简要描述] 蒸馏到 wiki 中

**CONTEXT:**
[源内容摘要，如果是 URL 输入则放入原始 URL 而非嵌入全文]
[调用方掌握的额外上下文：相关页面变动、约束条件、用户偏好]

**源材料特征（Source Profile，可选，仅当长度可能误导 kiwi 时添加）：**
简要描述源材料的知识密度特征，帮助 kiwi 区分核心知识和论证包装：
- 文档类型？（调研报告 / 会议记录 / API 文档 / 博客 / 设计文档 / ...）
- 知识密度？（简洁直接 / 论证链路长 / 知识混在大量执行细节中）
- 如果知识密度低，哪些部分可能是包装而非核心知识？（例：风险矩阵、时间线估算、逐接口分析——这些是论证支撑材料，不是可复用的结构知识）

**ACCEPTANCE:**
返回一份结构化分析，描述：
  - 要创建/更新的页面路径、完整 frontmatter、完整页面内容（遵循 SCHEMA.md 规范）
   - 需要更新的交叉引用（在哪些已有页面的正文中添加指回新页面的内联链接；页面关联即正文内联链接；反向链接由 `zwiki check` 自动派生，kiwi 无需处理）
   - 关于 `overview.md` 是否需要更新的建议
```

将三段式 prompt 传给 kiwi subagent，不要对 kiwi 做额外约束 — 所有要求已在 ACCEPTANCE 中表达。

---

## Phase 2 — 通用写入步骤

kiwi 返回分析后，执行写入命令。写命令必须显式传 `--root`，填该 bundle 的源目录（含 `bundle.toml` 的目录，不知道位置时问用户）。

**创建新页面时：**
1. **创建骨架** — 使用 `zwiki page create`：
    ```bash
    zwiki --root <bundle源目录> page create --domain <域名> \
        --type <concept|entity|analysis|synthesis> \
        --title "<页面标题>"
    ```
    域由 kiwi 的分析结果决定（kiwi 返回的页面路径含域前缀）。合法域由 bundle 源根目录下实际存在的子目录决定；团队可通过新建子目录扩展域。对于 source 类型追加 `--source-type <adr|rfc|notes>`；中文标题需加 `--slug <english-slug>`
2. **填充内容** — 使用 `write` / `edit` 将 kiwi 提供的页面内容写入

**更新已有页面时：**
1. 无需创建新页面
2. **编辑页面** — 使用 `edit` 工具按照 kiwi 的建议修改已有页面的指定节

**以下步骤创建和更新共用：**
3. **保存原始材料** — 如果输入为 URL 或文件，保存原文副本到 bundle 源的 `raw/$(date +%F)-<slug>.md`
4. **更新 overview.md** — 如果 kiwi 的分析建议更新，则执行
5. **更新交叉引用** — 按照 kiwi 的建议，在已有页面正文中添加指回新页面的内联链接（使用域前缀路径，如 `<domain>/concepts/<file>.md`）。页面关联即正文内联链接，反向链接与各级索引均由 zwiki 自动派生，无需手工维护；`page create`/`page set` 会自动记录日志，需要说明时加 `--note`

---

## Phase 3 — Supersede 确认与写入

如果 kiwi 没有返回 Supersede Proposals，或列表为空 → 跳过此 Phase。

否则，对每个取代提议执行以下步骤：

1. 向用户列出每个取代提议：
   - 被取代的页面路径
   - 旧声明（kiwi 摘录的原文）
   - 新声明（新源中的原文）
   - 取代理由

2. 询问用户是否确认每个提议。用户可以：
   - 全部确认
   - 部分确认（指定哪些接受，哪些拒绝）
   - 全部拒绝

3. 只对用户确认的提议执行写入。kiwi 会在每个取代提议中标明哪个页面取代哪个页面。对每对取代关系，使用 `zwiki supersede` 一次性更新两侧 frontmatter：

From 418-teapot/ZooKeeper, MIT.

More from 418-teapot/ZooKeeper