知识库 Wiki 编译器

腾讯 IMA 知识库 Wiki 编译——将原始资料系统化组织为结构清晰的Wiki知识体系，并支持标签体系管理与按文件夹层级结构归类。当用户说"建知识库""整理资料库""编译知识库""搭建wiki""知识体系化""把资料整理成wiki""给知识库打标签""按标签分类""标签整理""按文件夹归类""整理散落文件"时触发。不适用于单篇摘要、简单问答、或仅搜索已有知识库内容的场景。

知识库 Wiki 编译器 v4.0.0

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

---

快速开始

场景 1：建新知识库

用户："建一个关于 XXX 的知识库" → 自动启动 阶段 0 → 阶段 4 完整流程

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

用户："按文件夹归类" / "整理散落文件" → 仅执行 阶段 0

场景 3：维护已有知识库

• 用户："检查知识库" → 启动 阶段 6 健康检查
• 用户："补充知识库" → 启动 阶段 6 知识补充
• 用户："审查标签" / "整理标签" → 启动 阶段 6 标签审查

场景 4：增量更新导览

用户："更新导览" / "导览新增了 N 篇文章" → 启动 阶段 2 → 阶段 4 增量模式

场景 5：标签管理

• 用户："给知识库打标签" → 启动 标签体系 → 设计与应用
• 用户："按标签分类" → 启动 标签应用

---

整体流程（7 阶段法）

text

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

核心原则：

• 每个阶段都有"确认门"——用户确认后再进入下一阶段
• 预获取链接是阶段 3 的必做步骤——避免写完后发现无法链接导致返工
• 增量优先——每次编译前必须检查旧版本（阶段 2），优先增量更新而非重新创建
• 破坏性操作前必读 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

输出模板

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/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

---

阶段 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）：

章节	内容详略	重点
一、主题定位	略写（~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/write-and-verify.md

---

阶段 6：维护与迭代

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

6.1 健康检查

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

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

6.2 知识补充

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

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

6.3 输出与回流

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

6.4 标签审查

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

详见 references/tagging.md 第 7 节。

检查项：

• 命名规范（无近似标签）
• 孤儿标签（关联文件数 = 0）
• 弱标签（关联文件数 < 3）
• 热门标签（关联文件数 > 100）

破坏性操作保护：详见 references/security.md

6.5 维护节奏

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

详见 references/maintenance.md

---

标签体系

设计原则

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

分类

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

⚠️ 关键 API 规范

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

详见 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

---

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/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 编译方法论创建

---

文档结构

text

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   ← 实战案例