Wiki Compiler

SKILL.md

---
name: wiki-compiler
description: 腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的 Wiki 知识体系。当用户说"建知识库""整理资料库""编译知识库""搭建wiki""知识体系化""把资料整理成wiki"，或上传了一批资料希望系统化组织时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。
---

# 知识库 Wiki 编译器

核心理念：用 LLM 作为"知识编译器"，将原始资料一次性编译为结构清晰、内部互联的 Wiki 知识库，而非依赖传统 RAG 的碎片检索拼凑。编译后的 Wiki 是"真理之源"——LLM 直接基于对 Wiki 整体结构的理解进行自检索和回答，知识在系统中持续累积和演化。

## 整体流程

1. 需求理解与资料收集
2. 编译——生成结构化 Wiki
3. 主动维护与迭代

## 第一步：需求理解与资料收集

**判断用户状态：**
- 用户只给了主题？→ 先明确知识库边界和目标
- 用户已有资料（上传了文件 / 指定了知识库）？→ 直接进入编译
- 用户想维护已有 Wiki？→ 跳到第三步

**明确知识库边界：**
- 确认主题范围（如"IT审计""大模型应用"）
- 确认目标受众和用途（如"个人研究""团队参考"）
- 这些决定文件夹层级深度和概念粒度

**收集原始资料（"源代码"）：**
- 来源包括：用户上传的文件、已有知识库中的内容、网页文章、公众号文章
- 此阶段追求完整性，不追求结构——所有资料都是后续编译的"原材料"
- 如果用户指定了知识库（kb_id），用 `get_knowledge_list` 逐级浏览并收集所有文件
- 如果用户资料不足，主动用 `search(source="web")` 补充关键资料，但需告知用户

**确认门：** 向用户展示收集到的资料清单和知识库边界，确认后再进入编译。

## 第二步：编译——生成结构化 Wiki

这是核心步骤。LLM 读取所有原始资料，输出一个结构化的知识体系。

### 2.1 规划 Wiki 结构

阅读所有原始资料后，先规划知识体系骨架：

1. 识别核心概念（每个概念将对应一个主题文件夹或一篇独立文档）
2. 建立概念间的层级和关联关系
3. 设计文件夹结构（主题分类 → 子主题 → 具体文档）

**文件夹设计原则：**
- 主题之间互斥、覆盖完整（MECE），避免"其他"类文件夹
- 层级不超过3层，过深意味着分类需要重新设计
- 每个文件夹名清晰表达其内涵，让用户一看就知道内容归属

**确认门：** 向用户展示 Wiki 结构规划（文件夹树 + 每个文件夹的定位说明），确认后再创建。

### 2.2 创建结构并编译内容

在目标知识库中创建文件夹结构（`create_folder`），然后将原始资料分类归入（`move_knowledge`）。

**对每个主题文件夹，编译一篇导览笔记作为"知识枢纽"：**

导览笔记是 Markdown 格式的笔记，包含：
- 该主题的核心要点摘要
- 关键概念的简要定义
- **与知识库文件的 Markdown 超链接**（见下方"链接获取方法"）

### 导览笔记撰写规范

**1. 用编号列表，不用 Markdown 表格**

文章标题中常含 `|` 字符（如"实务 | 审计抽样实操总结"），`|` 在 Markdown 表格中是列分隔符，会导致表格解析错乱。使用编号列表可彻底避免此问题：

```markdown
## 文章导览

1. **中注协提示规范内控审计程序** — 中注协提示规范内控程序、提升上市公司内控质量
2. **审计抽样实操总结** — 实务、抽样实操总结
3. **详解穿行测试、控制测试** — 穿行测试、控制测试、截止性测试
```

**2. 标题中的特殊字符处理**

在导览笔记正文中引用文章标题时：
- `|` 替换为全角 `｜` 或直接省略（如 "实务｜审计抽样实操总结"）
- 其他可能干扰 Markdown 渲染的字符（`[` `]` `_` `*`）也需注意转义

**3. 内容必须基于知识库实际文件**

导览笔记的文章列表必须从 `get_knowledge_list` 返回的实际文件生成，不能依赖本地缓存文件——本地文件可能已被其他任务覆盖或过时。

**如何获取知识库文件的可链接 URL：**

对每个需要引用的文件，调用 `export_media_for_ima_sandbox` 接口：
```bash
curl -s -X POST "https://ima.qq.com/openapi/wiki/v1/export_media_for_ima_sandbox" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "<文件media_id>"}'
```
返回的 `data.media_content_url_info.url` 即为该文件的可链接 URL。

在笔记正文中用 Markdown 超链接格式嵌入：
```markdown
1. **[文章标题](https://url-from-export-api)** — 关键词摘要
```

**编译质量标准：**
- 每个文件夹都有明确的主题定位，不出现"待分类""其他"等模糊类别
- 每篇导览笔记都包含**指向知识库内文件的真实可点击链接**，形成知识网络而非信息孤岛
- 概念粒度一致——同一层级文件夹覆盖的范围应大致相当

### 导览笔记写入与验证

生成导览笔记内容后，按以下流程写入：

**写入方式选择：**

| 内容规模 | 推荐方式 | 原因 |
|---------|---------|------|
| **< 3KB**（绝大多数导览笔记） | `import_doc` + `curl -d @filepath` | 跳过 COS 中间环节，直接 JSON 请求体写入，最可靠 |
| **≥ 3KB**（超长导览） | `file_write` → `ima_cos_util` 上传 → `push_note` + `content_cos_key` | 长内容需 COS 中转 |

**具体步骤（< 3KB，常用）：**

1. `file_write` 将导览笔记保存为 `.md` 文件
2. `file_write` 将 API 请求体保存为 `.json` 文件（内容通过 `cat` 读取 `.md` 文件填入 `content` 字段）
3. `curl -d @filepath` 调用 `import_doc` 创建笔记
4. **验证**：立即调用 `export_note` 导出笔记内容，比对是否与原始内容一致
5. 验证通过后，调用 `add_knowledge` 将笔记添加到对应知识库文件夹

> 为什么不用 `push_note` + `content_cos_key`？实战中发现 COS 上传路径对内容格式敏感，可能导致笔记创建后被系统自动删除（`export_note` 返回 "doc is delete"）。`import_doc` 直接写入更可靠，且对于 < 3KB 的内容完全够用。

**验证是必选步骤**——未验证的笔记可能在知识库中显示为空内容或被自动清理，用户无法察觉。

### 2.3 编译产出

编译完成后，向用户交付：

- 知识库结构概览（文件夹树 + 每个文件夹的文件数）
- 核心概念索引（列出主要概念及其所在位置）
- 与传统"堆文件"式组织的对比（说明编译后的改进）

## 第三步：主动维护与迭代

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

### 3.1 健康检查（"体检"）

当用户说"检查知识库""知识库体检"时：

1. 扫描整个知识库，检查：
   - 是否有空文件夹（有待补充内容）
   - 是否有文件放错了分类
   - 主题之间是否有信息矛盾或重复
   - 是否有重要概念缺少覆盖
2. 生成健康检查报告，列出发现的问题和修复建议
3. 用户确认后执行修复

### 3.2 知识补充

当用户说"补充知识库""更新知识库"时：

1. 识别知识库中的薄弱环节（空文件夹、内容过时的主题）
2. 通过联网搜索补充最新资料
3. 将新资料编译后归入对应位置
4. 更新相关的交叉引用和索引

### 3.3 输出与回流

用户可基于 Wiki 生成各类产出（研究报告、总结、幻灯片大纲等），这些产出保存回知识库后，实现知识的"增量训练"——系统持续演化，而非一次性消耗。

## 工作流示例

### 示例 1：从零搭建知识库

```
用户: "我收集了一批IT审计的资料，帮我建一个知识库wiki"

步骤 1: 浏览用户上传的资料 / 指定知识库的内容，了解资料覆盖面
步骤 2: 规划 Wiki 结构（如：审计实务方法 | 审计准则与法规 | IT审计实操 | 案例库 | ...）
步骤 3: 用户确认结构后，创建文件夹并分类移入文件
步骤 4: 用 get_knowledge_list 获取每个文件夹的实际文件列表
步骤 5: 为核心主题编译导览笔记（编号列表格式，不用表格），获取文件可链接 URL
步骤 6: import_doc 写入笔记 → export_note 验证内容完整性 → add_knowledge 添加到文件夹
步骤 7: 交付结构概览和概念索引
```

### 示例 2：知识库维护

```
用户: "帮我检查一下IT审计知识库，看看有没有问题"

步骤 1: 逐级浏览知识库结构，统计每个文件夹的文件数
步骤 2: 识别问题：空文件夹、可能错分的文件、缺失的重要主题
步骤 3: 生成健康检查报告
步骤 4: 用户确认后执行修复（移动文件、补充内容等）
```

## 重要提醒

- 编译是增量过程——第一次编译不必完美，后续维护中持续优化
- 核心价值在于"结构化 + 互联"，而非单纯的文件分类
- 知识库规模适中时（数十到数百篇），LLM 内生理解优于向量检索；规模极大时需考虑分区域编译
- 每次编译后保留变更记录（告知用户做了什么），方便追溯和回退