原始内容
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 完整流程
场景 2：整理已有散落文件
用户："按文件夹归类" / "整理散落文件" → 仅执行 阶段 0
场景 3：维护已有知识库
场景 4：增量更新导览
用户："更新导览" / "导览新增了 N 篇文章" → 启动 阶段 2 → 阶段 4 增量模式
场景 5：标签管理
- 用户："给知识库打标签" → 启动 标签体系 → 设计与应用
- 用户："按标签分类" → 启动 标签应用
整体流程（7 阶段法）
阶段 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，文件会永远挂在根目录——即使它"看起来在文件夹里"。
流程
- 拉根目录（不带
folder_id） - 检查每个文件的
parent_folder_id：- 指向根目录 → 真正散落
- 指向文件夹 ID → 已归类
- 列出散落文件，按关键词推荐目标文件夹
- 批量调用
move_knowledge（每次最多 10 个） - 移动前备份标签（
move会清空标签数组） - 验证根目录为空
详见 references/folder-organization.md
输出模板
## 知识库结构诊断报告
### 顶层文件夹
| 文件夹 | 文件数 | 含子文件夹 |
|--------|:------:|:----------:|
| ... | ... | ... |
### 散落文件
- 共 X 个文件 `parent_folder_id` 是根目录
- 列出每个文件的标题和推荐目标文件夹
### 多层结构
- AI 量化与深度学习/
- 机器学习理论方法/（Y 个文件）
- 大模型与智能体/（Y 个文件）
### 处理建议
- 散落文件：调用 `move_knowledge` 归类
- 多层结构：导览放父级，子文件夹不需要各自导览
阶段 1：资料收集
资料来源
- 用户上传的文件
- 已有知识库（
kb_id）的内容 - 联网搜索（用
search(source="web")）
收集方式
get_knowledge_list逐级浏览- 不带
folder_id拉根目录（含散落文件视图） - 资料完整性优先，结构不急
确认门
向用户展示收集到的资料清单和知识库边界，确认后再进入阶段 2。
阶段 2：检查旧版本
重要：每次编译前必须检查是否已有该主题的知识导览，避免重复创建或丢失历史版本信息。
检查方式
- 在目标文件夹中搜索标题包含"主题导览"的笔记
- 如果找到"主题导览：xxx"，记录其
note_id和版本信息 - 如果没找到，则进入新建流程
判断逻辑
| 情况 | 处理方式 |
|---|---|
| 已有该主题的旧版本导览 | 增量更新：读取旧版本 → 对比增量 → 更新导览 |
| 已有其他主题的导览 | 新建：按正常流程创建 |
| 没有任何知识导览 | 新建：按正常流程创建 |
详见 references/versioning.md 和 references/incremental-update.md
阶段 3：链接特性预获取（编译前必做）
目的：避免写完后发现无法链接导致返工
流程
- 收集文件列表：
get_knowledge_list提取media_id、media_type、title - 批量获取链接特性：
export_media_for_ima_sandbox获取永久 URL - 生成链接特性表：
| media_id | title | media_type | 链接策略 | URL/备注 |
|---|---|---|---|---|
| xxx | 文章A | 2 (网页) | ✅ 可内嵌 | https://... |
| xxx | 文章C | 7 (Markdown) | ⚠️ 不内嵌 | 请在知识库中查看 |
- 按类型分类编译：
| 文件类型 | 编译写法 |
|---|---|
| type 2/6 | [标题](永久URL) |
| type 7/11 | 标题（纯文本，不加链接） |
| type 1/3/4/5 | 标题 — 请在知识库中查看 |
详见 references/link-handling.md
阶段 4：编译生成
4.1 新建模式（5 步法）
- 明确主题 — 确定核心概念（主题定位、核心概念、边界范围）
- 梳理关键词 — 提取关键要素（每概念 3-5 个子主题）
- 发现关系 — 找出逻辑关联（层级、并列、因果、对立）
- 呈现结构 — 可视化知识网络（表格 + 学习路径）
- 美化优化 — 提升可读性（标题规范、排版、信息密度）
4.2 增量更新模式
- 读取旧版本（
export_note） - 提取版本信息
- 对比知识库增量（新增/删除/概念变化）
- 更新导览内容（保留结构、更新要素、更新实践建议）
- 更新版本号（patch +0.0.1 / minor +0.1 / major +1.0）
4.3 笔记撰写规范
4 章节结构（详见 references/guide-template.md）：
| 章节 | 内容详略 | 重点 |
|---|---|---|
| 一、主题定位 | 略写（~100 字） | 定义 + 解决问题 + 依赖链条 |
| 二、核心概念与关键要素 | 详写（每概念 200-300 字） | 核心思想 + 引用文章 + 实践建议 |
| 三、学习路径 | 中等（表格 + 一段话） | 两条路径 + 知识网络连接 |
| 四、相关主题 | 略写（表格） | 主题 + 关系 + 连接点 |
关键要素写作：冒号前是要素名称，冒号后是详细说明，末尾用 [《标题》](链接) 引用。
链接格式要求（必须严格遵守）：
- 所有引用必须提供可点击的有效链接
- 链接来源参考阶段 3 生成的链接特性表
- 禁止使用裸链接或纯 URL 文本
阶段 5：写入与验证
重要：笔记创建接口返回成功不代表内容完整，必须立即验证。
写入
# 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 次 | 主题边界变化 |
标签体系
设计原则
- 每篇文章 3-5 个关键词作为主题标签
- 文章级标签（涉及主题） + 文件夹（归属主题）= 协同
- 标签创建前不需要完整词表，可渐进添加
分类
| 类型 | 用途 | 示例 |
|---|---|---|
| 主题标签 | 文章涉及的主题 | 风险因子 / 量化策略 |
| 属性标签 | 文章固有属性 | 科普 / 进阶 / 待补充 |
| 状态标签 | 维护状态 | 已编译 / 待审核 / 草稿 |
⚠️ 关键 API 规范
item_name必须严格匹配get_knowledge_list返回的完整标题limit范围(0, 50]，超出返回错误- 调用前必须确认用户对该知识库有写权限
安全准则
破坏性操作清单
| 操作 | 风险 | 保护 |
|---|---|---|
delete_note |
不可逆 | 备份→三重确认→操作日志 |
tag_delete |
关联自动解除 | 列影响文件→用户确认 |
tag_rename |
重名自动合并 | 检查新名→用户确认 |
move_knowledge |
标签可能清空 | 备份标签→移动后恢复 |
通用保护原则
- 备份优先：所有破坏性操作前必须先备份
- 三重确认门：备份完成 + 内容验证 + 用户显式确认
- 操作日志：每次破坏性操作后记录到
/sandbox/workspace/logs/note_operations.log - 优先用可逆方案：
tag_remove优于tag_delete，创建新笔记优于删除旧笔记
💡 推荐：保留旧笔记 + 创建新笔记
对绝大多数场景，不要删除旧笔记，而是：
- 创建内容完全的新笔记
- 在新笔记中标注"替代旧版 v1.X（
note_id=XXX）"- 旧笔记保留作为历史版本，用户在 IMA 客户端手动决定是否删除
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
编译质量标准
- 原子化：每个知识节点围绕单一主题
- 关联性：知识卡片之间通过超链接形成网状结构
- 大纲化：每个卡片内部有完整的章节结构
- 可溯源：标注每篇文章的来源出处
- 可读性：结构清晰、信息密度适中、美观易读
重要提醒
- 预获取链接是编译前的必做步骤——先建立链接特性表，再基于表编译
- 增量优先——每次编译前必须检查旧版本，优先增量更新而非重新创建
- 编译是增量过程——第一次编译不必完美，后续维护中持续优化
- 核心价值在于"结构化 + 互联"而非单纯的文件分类
- 知识库规模适中时（数十到数百篇），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 ← 实战案例