知识库 Wiki 编译器

SKILL.md

---
name: wiki-compiler
version: 4.0.0
description: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说"建知识库""整理资料库""编译知识库""搭建wiki""知识体系化""把资料整理成wiki""给知识库打标签""按标签分类""标签整理""按文件夹归类""整理散落文件"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。
license: MIT-0
author: cookfish
last_updated: 2026-07-08
requires:
  skills:
    - name: ima-skill
      reason: 本技能依赖 ima-skill 提供的笔记管理和知识库操作能力
env:
  IMA_OPENAPI_CLIENTID: ima OpenAPI 客户端ID
  IMA_OPENAPI_APIKEY: ima OpenAPI API密钥
---

# 知识库 Wiki 编译器 v4.0.0

> **技能版本**：v4.0.0 | 最后更新：2026-07-08 | 上一版：v3.0.2
> **核心理念**：用 LLM 作为"知识编译器"，将原始资料一次性编译为结构清晰、内部互联的 Wiki 知识库。编译后的 Wiki 是"真理之源"——LLM 直接基于对 Wiki 整体结构的理解进行自检索和回答，知识在系统中持续累积和演化。

---

## 快速开始

### 场景 1：建新知识库

用户："建一个关于 XXX 的知识库" → 自动启动 [阶段 0 → 阶段 4 完整流程](#阶段-0诊断与归类)

### 场景 2：整理已有散落文件

用户："按文件夹归类" / "整理散落文件" → 仅执行 [阶段 0](#阶段-0诊断与归类)

### 场景 3：维护已有知识库

- 用户："检查知识库" → 启动 [阶段 6 健康检查](#61-健康检查)
- 用户："补充知识库" → 启动 [阶段 6 知识补充](#62-知识补充)
- 用户："审查标签" / "整理标签" → 启动 [阶段 6 标签审查](#64-标签审查)

### 场景 4：增量更新导览

用户："更新导览" / "导览新增了 N 篇文章" → 启动 [阶段 2 → 阶段 4 增量模式](#阶段-2检查旧版本)

### 场景 5：标签管理

- 用户："给知识库打标签" → 启动 [标签体系 → 设计与应用](#标签体系)
- 用户："按标签分类" → 启动 [标签应用](#标签体系)

---

## 整体流程（7 阶段法）

```
阶段 0：诊断与归类   ← 是否需要先整理结构？
   ↓
阶段 1：资料收集     ← 知识库有什么？
   ↓
阶段 2：检查旧版本   ← 是否已编译过？
   ↓
阶段 3：链接特性预获取  ← 文件能链接吗？
   ↓
阶段 4：编译生成     ← 写导览笔记
   ↓
阶段 5：写入与验证   ← 创建/更新笔记
   ↓
阶段 6：维护与迭代   ← 持续演化
```

**核心原则**：
- **每个阶段都有"确认门"**——用户确认后再进入下一阶段
- **预获取链接是阶段 3 的必做步骤**——避免写完后发现无法链接导致返工
- **增量优先**——每次编译前必须检查旧版本（阶段 2），优先增量更新而非重新创建
- **破坏性操作前必读** [references/security.md](references/security.md)

---

## 阶段 0：诊断与归类

> 适用于：知识库刚建好、文件散落在根目录、结构混乱、多层结构不一致

### 何时需要

- 根目录有散落文件（`parent_folder_id` 是根 ID）
- 父文件夹下有应该归入子文件夹的文件
- 多层结构不一致

### 核心判断

**`add_knowledge` ≠ `move_knowledge`**

| 操作 | 效果 | 何时用 |
|------|------|--------|
| `add_knowledge` | 虚拟展示，`parent_folder_id` 不变 | 临时展示 |
| `move_knowledge` | 物理归类，`parent_folder_id` 改变 | 真正整理 |

**仅用 `add_knowledge` 不调用 `move`，文件会永远挂在根目录**——即使它"看起来在文件夹里"。

### 流程

1. 拉根目录（不带 `folder_id`）
2. 检查每个文件的 `parent_folder_id`：
   - 指向根目录 → 真正散落
   - 指向文件夹 ID → 已归类
3. 列出散落文件，按关键词推荐目标文件夹
4. 批量调用 `move_knowledge`（每次最多 10 个）
5. **移动前备份标签**（`move` 会清空标签数组）
6. 验证根目录为空

详见 [references/folder-organization.md](references/folder-organization.md)

### 输出模板

```markdown
## 知识库结构诊断报告

### 顶层文件夹
| 文件夹 | 文件数 | 含子文件夹 |
|--------|:------:|:----------:|
| ... | ... | ... |

### 散落文件
- 共 X 个文件 `parent_folder_id` 是根目录
- 列出每个文件的标题和推荐目标文件夹

### 多层结构
- AI 量化与深度学习/
  - 机器学习理论方法/（Y 个文件）
  - 大模型与智能体/（Y 个文件）

### 处理建议
- 散落文件：调用 `move_knowledge` 归类
- 多层结构：导览放父级，子文件夹不需要各自导览
```

---

## 阶段 1：资料收集

### 资料来源

- 用户上传的文件
- 已有知识库（`kb_id`）的内容
- 联网搜索（用 `search(source="web")`）

### 收集方式

- `get_knowledge_list` 逐级浏览
- 不带 `folder_id` 拉根目录（含散落文件视图）
- 资料完整性优先，结构不急

### 确认门

向用户展示收集到的资料清单和知识库边界，确认后再进入阶段 2。

---

## 阶段 2：检查旧版本

> **重要**：每次编译前必须检查是否已有该主题的知识导览，避免重复创建或丢失历史版本信息。

### 检查方式

1. 在目标文件夹中搜索标题包含"主题导览"的笔记
2. 如果找到"主题导览：xxx"，记录其 `note_id` 和版本信息
3. 如果没找到，则进入新建流程

### 判断逻辑

| 情况 | 处理方式 |
|------|---------|
| 已有该主题的旧版本导览 | **增量更新**：读取旧版本 → 对比增量 → 更新导览 |
| 已有其他主题的导览 | **新建**：按正常流程创建 |
| 没有任何知识导览 | **新建**：按正常流程创建 |

详见 [references/versioning.md](references/versioning.md) 和 [references/incremental-update.md](references/incremental-update.md)

---

## 阶段 3：链接特性预获取（编译前必做）

> **目的**：避免写完后发现无法链接导致返工

### 流程

1. **收集文件列表**：`get_knowledge_list` 提取 `media_id`、`media_type`、`title`
2. **批量获取链接特性**：`export_media_for_ima_sandbox` 获取永久 URL
3. **生成链接特性表**：

| media_id | title | media_type | 链接策略 | URL/备注 |
|---------|-------|-----------|---------|---------|
| xxx | 文章A | 2 (网页) | ✅ 可内嵌 | https://... |
| xxx | 文章C | 7 (Markdown) | ⚠️ 不内嵌 | 请在知识库中查看 |

4. **按类型分类编译**：

| 文件类型 | 编译写法 |
|---------|---------|
| type 2/6 | `[标题](永久URL)` |
| type 7/11 | `标题`（纯文本，不加链接）|
| type 1/3/4/5 | `标题 — 请在知识库中查看` |

详见 [references/link-handling.md](references/link-handling.md)

---

## 阶段 4：编译生成

### 4.1 新建模式（5 步法）

1. **明确主题** — 确定核心概念（主题定位、核心概念、边界范围）
2. **梳理关键词** — 提取关键要素（每概念 3-5 个子主题）
3. **发现关系** — 找出逻辑关联（层级、并列、因果、对立）
4. **呈现结构** — 可视化知识网络（表格 + 学习路径）
5. **美化优化** — 提升可读性（标题规范、排版、信息密度）

### 4.2 增量更新模式

1. 读取旧版本（`export_note`）
2. 提取版本信息
3. 对比知识库增量（新增/删除/概念变化）
4. 更新导览内容（保留结构、更新要素、更新实践建议）
5. 更新版本号（patch +0.0.1 / minor +0.1 / major +1.0）

### 4.3 笔记撰写规范

4 章节结构（详见 [references/guide-template.md](references/guide-template.md)）：

| 章节 | 内容详略 | 重点 |
|------|---------|------|
| 一、主题定位 | 略写（~100 字）| 定义 + 解决问题 + 依赖链条 |
| 二、核心概念与关键要素 | 详写（每概念 200-300 字）| 核心思想 + 引用文章 + 实践建议 |
| 三、学习路径 | 中等（表格 + 一段话）| 两条路径 + 知识网络连接 |
| 四、相关主题 | 略写（表格）| 主题 + 关系 + 连接点 |

**关键要素写作**：冒号前是要素名称，冒号后是详细说明，末尾用 `[《标题》](链接)` 引用。

**链接格式要求**（必须严格遵守）：
- 所有引用必须提供可点击的有效链接
- 链接来源参考阶段 3 生成的链接特性表
- 禁止使用裸链接或纯 URL 文本

---

## 阶段 5：写入与验证

> **重要**：笔记创建接口返回成功不代表内容完整，必须立即验证。

### 写入

```bash
# 1. 构建请求 JSON
python3 -c "
import json
with open('guide_content.md', 'r') as f: content = f.read()
with open('note_request.json', 'w') as f:
    json.dump({
        'content_format': 1,
        'content': content,
        'title': '📖 主题导览：[主题名称]'
    }, f, ensure_ascii=False, indent=2)
"

# 2. 创建笔记
curl -s -X POST "https://ima.qq.com/openapi/note/v1/import_doc" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d @note_request.json | python3 -m json.tool
# 返回: {"code": 0, "data": {"note_id": "xxx"}}
```

**短内容优化**：< 3KB 的内容直接用 `import_doc` + `curl -d @filepath`，跳过 COS 中间环节。

### 验证

- `export_note` 导出内容
- 与原始内容比对
- 失败则删除重建（参考 [references/security.md](references/security.md) 安全删除流程）

详见 [references/write-and-verify.md](references/write-and-verify.md)

---

## 阶段 6：维护与迭代

知识库需要"活"起来，而非一次性建好就搁置。

### 6.1 健康检查

**触发词**："检查知识库"、"知识库体检"

- 空文件夹、错放文件、矛盾信息、缺覆盖
- 生成健康检查报告，列出问题 + 修复建议
- 用户确认后执行修复

### 6.2 知识补充

**触发词**："补充知识库"、"更新知识库"

- 识别薄弱环节（空文件夹、内容过时）
- 联网搜索补充新资料
- 编译后归入对应位置
- **更新知识导览**：触发增量更新流程

### 6.3 输出与回流

用户可基于 Wiki 生成各类产出（研究报告、总结、幻灯片大纲等），保存回笔记本后实现知识的"增量训练"——系统持续演化。

### 6.4 标签审查

**触发词**："审查标签"、"整理标签"

详见 [references/tagging.md](references/tagging.md) 第 7 节。

**检查项**：
- 命名规范（无近似标签）
- 孤儿标签（关联文件数 = 0）
- 弱标签（关联文件数 < 3）
- 热门标签（关联文件数 > 100）

**破坏性操作保护**：详见 [references/security.md](references/security.md)

### 6.5 维护节奏

| 维护类型 | 频率 | 触发条件 |
|---------|------|---------|
| 健康检查 | 每月 1 次 | 时间周期 |
| 知识补充 | 按需 | 用户上传新资料 |
| 标签审查 | 每季度 1 次 | 标签数 > 100 |
| 增量更新导览 | 每周 1 次 | 文件数增加 > 10% |
| 深度重构 | 每半年 1 次 | 主题边界变化 |

详见 [references/maintenance.md](references/maintenance.md)

---

## 标签体系

### 设计原则

- 每篇文章 3-5 个关键词作为主题标签
- 文章级标签（涉及主题） + 文件夹（归属主题）= 协同
- 标签创建前不需要完整词表，可渐进添加

### 分类

| 类型 | 用途 | 示例 |
|------|------|------|
| 主题标签 | 文章涉及的主题 | 风险因子 / 量化策略 |
| 属性标签 | 文章固有属性 | 科普 / 进阶 / 待补充 |
| 状态标签 | 维护状态 | 已编译 / 待审核 / 草稿 |

### ⚠️ 关键 API 规范

- `item_name` 必须严格匹配 `get_knowledge_list` 返回的**完整标题**
- `limit` 范围 `(0, 50]`，超出返回错误
- 调用前必须确认用户对该知识库有写权限

详见 [references/tagging.md](references/tagging.md)

---

## 安全准则

### 破坏性操作清单

| 操作 | 风险 | 保护 |
|------|------|------|
| `delete_note` | 不可逆 | 备份→三重确认→操作日志 |
| `tag_delete` | 关联自动解除 | 列影响文件→用户确认 |
| `tag_rename` | 重名自动合并 | 检查新名→用户确认 |
| `move_knowledge` | 标签可能清空 | 备份标签→移动后恢复 |

### 通用保护原则

1. **备份优先**：所有破坏性操作前必须先备份
2. **三重确认门**：备份完成 + 内容验证 + 用户显式确认
3. **操作日志**：每次破坏性操作后记录到 `/sandbox/workspace/logs/note_operations.log`
4. **优先用可逆方案**：`tag_remove` 优于 `tag_delete`，创建新笔记优于删除旧笔记

### 💡 推荐：保留旧笔记 + 创建新笔记

> 对绝大多数场景，**不要删除旧笔记**，而是：
> 1. 创建内容完全的新笔记
> 2. 在新笔记中标注"替代旧版 v1.X（`note_id=XXX`）"
> 3. 旧笔记保留作为历史版本，用户在 IMA 客户端手动决定是否删除

详见 [references/security.md](references/security.md)

---

## API 速查

### 关键端点

| 功能 | 端点 |
|------|------|
| 获取知识库列表 | `openapi/wiki/v1/get_knowledge_list` |
| 移动文件 | `openapi/wiki/v1/move_knowledge` |
| 添加标签 | `openapi/wiki/v1/tag_add` |
| 列出标签 | `openapi/wiki/v1/tag_list` |
| 创建笔记 | `openapi/note/v1/import_doc` |
| 导出笔记 | `openapi/note/v1/export_note` |

### 错误码速查

| code | 含义 |
|------|------|
| 0 | 成功 |
| 51 | 参数错误（如 `limit` 超出范围）|
| 220001 | 文件名称不匹配（`item_name` 未用完整标题）|
| 220004 | 无效的 `knowledge_base_id` |
| 220030 | 无写权限 |

详见 [references/api-reference.md](references/api-reference.md) 和 [references/troubleshooting.md](references/troubleshooting.md)

---

## 编译质量标准

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

---

## 重要提醒

- **预获取链接是编译前的必做步骤**——先建立链接特性表，再基于表编译
- **增量优先**——每次编译前必须检查旧版本，优先增量更新而非重新创建
- 编译是增量过程——第一次编译不必完美，后续维护中持续优化
- 核心价值在于"结构化 + 互联"而非单纯的文件分类
- 知识库规模适中时（数十到数百篇），LLM 内生理解优于向量检索
- 每次编译后保留变更记录，方便追溯和回退
- **产出是笔记本中的笔记**——使用 `import_doc` 创建笔记，写入笔记本

---

## 变更日志

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

- 重新组织为 7 阶段法（诊断→收集→检查→链接→编译→写入→维护）
- SKILL.md 精简至操作手册，详细内容拆分到 `references/` 子目录
- 元信息完善（`version` / `license` / `author` / `last_updated`）
- 新增快速开始、故障排查、统一安全准则、变更日志
- 解决原版 4 处内容重复、章节编号混乱、量化个案污染通用技能等问题

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

- description 补充"按文件夹层级结构归类"
- 新增 2 个触发词："按文件夹归类"、"整理散落文件"

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

- `delete_note` 流程重写为安全删除（备份→三重确认→操作日志）

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

- 新增 3.0 知识库结构诊断
- 新增 6.5 多层文件夹归类
- 集成 8 条实战经验

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

- 基于 LLM 编译方法论创建

---

## 文档结构

```
wiki-compiler/
├── SKILL.md                            ← 本文件（操作手册）
└── references/
    ├── reference.md                    ← references/ 索引
    ├── folder-organization.md          ← 阶段 0 详细
    ├── tagging.md                      ← 标签体系
    ├── security.md                     ← 安全准则
    ├── api-reference.md                ← API 速查
    ├── guide-template.md               ← 阶段 4 笔记撰写规范
    ├── versioning.md                   ← 阶段 2 版本控制
    ├── incremental-update.md           ← 阶段 4 增量更新
    ├── link-handling.md                ← 阶段 3 链接处理
    ├── write-and-verify.md             ← 阶段 5 写入与验证
    ├── maintenance.md                  ← 阶段 6 维护
    ├── troubleshooting.md              ← 故障排查
    └── cases/
        └── quantitative-investing.md   ← 实战案例
```