知识库 Wiki 编译器 v5.0.0

技能版本：v5.0.0 | 最后更新：2026-09-28 | 上一版：v4.1.0 核心理念：基于 Karpathy 的 LLM Wiki 模式 —— "Human curates, LLM maintains" 三大操作：Ingest（摄取）/ Lint（健康检查）/ Schema（契约） IMA 平台依赖：需配置 IMA_OPENAPI_CLIENTID 和 IMA_OPENAPI_APIKEY 环境变量。获取方式：访问 https://ima.qq.com/agent-interface

---

快速开始

场景 1：建新知识库

用户："建一个关于 XXX 的知识库" → Ingest（完整流水线）

场景 2：导入新资料

用户："导入这个网页" / "上传这个 PDF" → Ingest（自动级联）

场景 3：整理散落文件

用户："按文件夹归类" / "整理散落文件" → Ingest 前置（Folder Pre-Ingest）

场景 4：维护知识库

用户："检查知识库" / "健康检查" → Lint（4 类标准检查）

场景 5：增量更新导览

用户："更新导览" / "导览新增了 N 篇文章" → Ingest（增量模式）

场景 6：标签管理

用户："给知识库打标签" / "审查标签" → Ingest 子任务（Schema 辅助）

---

核心理念

Karpathy 三大操作

Query（查询）由 IMA search/fetch 完成，不归本 skill 管。

为什么这样设计

• Ingest：知识库是"会复利的资产"，不是"可检索的语料库"
• Lint：通过定期检查防止 wiki 衰败（类比代码世界的 eslint）
• Schema：没有 schema，LLM 会天马行空；有了 schema，LLM 才守纪律

"Human curates, LLM maintains" — 人类决定收录什么，LLM 维护导览

---

Ingest（摄取）

子任务流水线

Collect（收集） → Check（检查） → Link（链接特性） → Compile（编译） → Write（写入） → Cascade（级联）
   ↓                ↓                ↓                ↓                ↓              ↓
  阶段 1.1          阶段 1.2          阶段 1.3          阶段 1.4          阶段 1.5       阶段 1.6

关键子任务

详见 references/ingest.md

⚠️ Karpathy 核心机制：知识复利（Cascade）

一次 Ingest 可能触动多个导览（不仅是新文件所在的那个）

IMA 实际可实现方式：每个 Cascade 创建新 note_id（frontmatter 完整可控），旧版笔记保留作为历史。

新文件被上传
   ↓
计算与每个现有导览的相关性（标签 Jaccard + 文件夹归属 + 标题关键词）
   ↓
相关度 > 0.5 的导览 → 加入"待更新列表"
   ↓
用户确认（必选）
   ↓
对每个候选导览：
  1. export_note 读旧版
  2. LLM 生成新版本正文
  3. import_doc 创建新笔记（新 frontmatter：version/updated/changelog）
  4. append_doc 在旧笔记末尾追加"已被替代"标记

示例：上传"遗传算法在量化交易中的应用" → 1 个新导览笔记创建（v1.6）+ 1 个旧版标记追加。

详见 references/ingest.md 第 7 节

---

Lint（健康检查）

4 类标准检查（Karpathy 完整版）

详见 references/lint.md

触发词

• "检查知识库" / "知识库体检" / "健康检查"
• "审查标签" / "整理标签"（仅标签部分）

输出

outputs/lint-YYYY-MM-DD.md —— 包含总体评分、4 类检查详情、修复建议。

---

Schema（契约）

强制 frontmatter（每篇主题导览）

---
title: 📖 主题导览：[主题名称]
type: guide
confidence: high | medium | low
created: YYYY-MM-DD
updated: YYYY-MM-DD
version: 1.0
changelog:
  - v1.0: 初始版本
sources:
  - [《文章1》](URL)
related_guides:
  - [《另一导览》](URL)
---

详见 references/schema.md

核心字段说明

---

安全准则（破坏性操作）

详见 references/security.md

---

API 速查

核心端点

详见 references/api-reference.md 和 references/troubleshooting.md

---

编译质量标准

1. 原子化：每个知识节点围绕单一主题
2. 关联性：知识卡片之间通过超链接形成网状结构
3. 大纲化：每个卡片内部有完整的章节结构
4. 可溯源：每篇文章有来源出处（sources[]）
5. 可读性：结构清晰、信息密度适中
6. confidence 标注：每个论断有可信度（Karpathy 特色）

---

重要提醒

• 预获取链接是编译前的必做步骤（Link 子任务）—— 先建立链接特性表，再基于表编译
• 增量优先——每次 Ingest 前必须 Check 旧版本，优先增量更新而非重新创建
• schema 强制——所有导览必须遵守 references/schema.md
• 级联需确认——Cascade 是 Karpathy 核心机制，但首次使用应告知用户
• 导出笔记是 COS URL——export_note 返回 content_url（3 小时时效），需二次下载
• 删除笔记不支持——IMA 平台当前 API 不支持，请用户在客户端操作

---

变更日志

v5.0.2 (2026-09-28) - Cascade 算法修正

• Cascade 算法改为 IMA 实际可实现版：每次级联 = 创建新 note_id + 旧笔记追加"已被替代"标记
• 移除 LLM 评分依赖（改为纯 API Jaccard 算法）
• 强调"frontmatter 不可修改"的 IMA 限制
• Cascade 用户确认变成必选（不再自动执行）

详见 references/ingest.md 第 7 节

v5.0.1 (2026-09-28) - API 端点对齐 patch

• 修正 5 处错误端点（get_media_info 删除、list_knowledge_bases → search_knowledge_base、list_notebooks → list_notebook、list_notes → list_note、create_notebook → add_notebook）
• 补充 14 个缺失端点
• 更新错误码（220001 → 210001 等）

v5.0.0 (2026-09-28) - Karpathy 重构（major 升级）

架构重组：

• 7 阶段 → Karpathy 三大操作（Ingest / Lint / Schema）
• SKILL.md 精简到 ~450 行（v4.1.0 是 499 行）
• 新增 3 个核心 references：ingest.md / lint.md / schema.md
• 引入 Karpathy 核心机制：知识复利（Cascade 级联更新）

Schema 强制化：

• 主题导览 frontmatter 强化：必填 confidence / sources[] / related_guides[] / changelog
• confidence 字段：每篇导览标注可信度（high/medium/low）
• sources[] 强制：每个论断追到 raw 资料

Ingest 增强：

• Cascade 算法改为 IMA 实际可实现版：每次级联创建新 note_id + 旧笔记追加"已被替代"标记
• 移除 LLM 评分依赖（改为纯 API Jaccard 算法）
• 新增 update_note（按 block 编辑）

Lint 强化：

• 从"基础健康检查"升级到 Karpathy 标准的 4 类检查（结构/矛盾/孤立/过期）
• Lint 报告输出到 outputs/lint-YYYY-MM-DD.md

触发词保持 11 个不变

复杂度反思：

• 之前 v4.2.0 加 14 项功能会让 SKILL.md 增长到 700+ 行
• v5.0.0 重组为三大操作，结构更清晰
• 11 个触发词保持不变，description 不变（向后兼容）

v4.1.0 (2026-09-28) - IMA 原生格式升级

• 顶层 requires: { skills: [ima-skill] } → metadata.openclaw.requires.env 数组
• 删除笔记 API 修正：v4.0.0 附录 B 的 delete_note 安全删除流程已失效

v4.0.0 (2026-07-08) - 完全重构

• 7 阶段法操作流程

v3.0.2 (2026-07-08) - 描述优化

v3.0.1 (2026-07-08) - 安全修复

v3.0.0 (2026-05-13) - 多层结构

v1.0 (2026-05-07) - 初版

---

文档结构

wiki-compiler/
├── SKILL.md                            ← 本文件（操作手册）
└── references/
    ├── reference.md                    ← references/ 索引
    ├── ingest.md                       ← 🆕 Ingest 完整操作 + 级联算法
    ├── lint.md                         ← 🆕 Lint 4 类标准检查
    ├── schema.md                       ← 🆕 强制 frontmatter 契约
    ├── folder-organization.md          ← Ingest 前置：文件夹整理
    ├── tagging.md                      ← Ingest 子任务：标签管理
    ├── security.md                     ← 破坏性操作保护
    ├── api-reference.md                ← API 速查
    ├── guide-template.md               ← 笔记撰写规范（含新 frontmatter）
    ├── versioning.md                   ← 版本控制
    ├── write-and-verify.md             ← 写入与验证
    ├── link-handling.md                ← 链接处理
    ├── troubleshooting.md              ← 故障排查
    └── cases/
        └── quantitative-investing.md   ← 实战案例

⚠️ IMA 平台注意：IMA 平台会周期性向 /sandbox/workspace/skills/<skill>/ 添加软链接 <skill> -> /root/.skills/<skill>/，可能导致打包时混入旧版本。打包前务必用 find ... -type l 检查并清理。 详见 references/troubleshooting.md 第 10 节。