知识库 Wiki 编译器

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

整体流程

1. 第一步：需求理解与资料收集 — 明确主题边界
2. 第二步：检查旧版本 — 判断是否已有知识导览，决定增量更新还是新建
3. 第三步：编译生成 — 包含预获取链接信息、新建模式、增量更新模式三个子步骤
4. 第四步：写入笔记 — 按规范生成导览笔记
5. 第五步：主动维护与迭代 — 定期检查和更新

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

判断用户状态：

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

明确知识库边界：

• 确认主题范围（如"量化投资""大模型应用"）
• 确认目标受众和用途（如"个人研究""团队参考"）
• 这些决定文件夹层级深度和概念粒度

收集原始资料（"源代码"）：

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

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

第二步：检查旧版本

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

检查方式

1. 在目标文件夹中搜索标题包含"主题导览"的笔记：

   curl -s -X POST "https://ima.qq.com/openapi/wiki/v1/get_knowledge_list" \
     -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
     -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{"knowledge_base_id": "\x3Ckb_id>", "limit": 50}' | \
     python3 -c "import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('knowledge_list',[])])"
   

2. 如果找到"主题导览：xxx"笔记，记录其 note_id 和版本信息

3. 如果没找到，则进入新建流程

判断逻辑

增量更新流程

当存在旧版本时，执行以下步骤：

1. 读取旧版本：调用 export_note 获取旧版本完整内容
2. 提取版本信息：从标题下方的版本行获取版本号、更新日志
3. 对比知识库：获取文件夹中最新的文件列表，与旧版本"相关主题"章节进行对比
4. 识别增量内容：
   • 新增的文章（需要添加到对应核心概念的关键要素中）
   • 删除的文章（需要从列表中移除）
   • 概念变化（如有新增核心概念）
5. 更新导览内容：
   • 保留原有结构和核心思想
   • 在关键要素中补充新增文章，移除已删除文章
   • 更新"实践建议"部分
   • 更新学习路径（如有新增依赖）
6. 更新版本号：
   • 仅增删文章 → patch +0.0.1
   • 修改关键要素/实践建议 → minor +0.1
   • 结构变化 → major +1.0
7. 追加 changelog：记录本次更新的内容摘要

第三步A：预获取链接信息（编译前必做）

重要：在编译导览笔记之前，必须先批量获取所有文件的链接特性，避免写完后发现无法链接导致返工。

步骤1：收集文件列表

获取文件夹中的所有文件，提取每个文件的 media_id、media_type、title：

curl -s -X POST "https://ima.qq.com/openapi/wiki/v1/get_knowledge_list" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "\x3Ckb_id>", "limit": 50}' | \
  python3 -c "import sys,json; data=json.load(sys.stdin); [print(f\"{f['media_id']}|{f['media_type']}|{f['title']}\") for f in data.get('data',{}).get('knowledge_list',[])]"

步骤2：批量获取链接特性

对每个文件调用 export_media_for_ima_sandbox：

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": "\x3Cmedia_id>"}'

步骤3：生成链接特性表

根据返回结果，建立如下表格：

步骤4：按类型分类编译

编译导览笔记时，根据链接特性表选择正确的写法：

第三步B：新建模式（首次编译）

适用于：首次编译或结构重大调整

步骤1：明确主题 — 确定核心概念

在阅读所有原始资料后，明确：

• 主题定位：这个知识库要解决什么问题？
• 核心概念：有哪些不可分割的基础概念？
• 边界范围：什么在范围内，什么不在？

步骤2：梳理关键词 — 提取关键要素

对每个核心概念，提取：

• 关键要素：围绕该概念的子主题或相关问题
• 核心思想：每个要素要传达的1-2句话

步骤3：发现关系 — 找出逻辑关联

建立概念之间的连接：

• 层级关系：上下级依赖（如：随机过程 → 伊藤积分）
• 并列关系：同层级互补（如：Alpha因子 || 风险因子）
• 因果关系：先后依赖（如：因子拥挤 → IC衰减）
• 对立关系：互斥选择（如：简约模型 vs 复杂模型）

步骤4：呈现结构 — 可视化知识网络

将关系转化为：

• 知识网络图：用表格形式展示概念关联
• 推荐路径：按难度/应用场景的学习路线

步骤5：美化优化 — 提升可读性

• 标题规范：简洁有力，避免冗长
• 排版美观：合理使用分级标题、列表、空行
• 信息密度：每个章节有明确的信息承载量
• 可读性：避免过长的段落，保持节奏

第三步C：增量更新模式

适用于：知识库已有该主题旧版本导览，需要增量更新

3C.1 读取旧版本

# 导出旧版本笔记内容
curl -s -X POST "https://ima.qq.com/openapi/note/v1/export_note" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"note_id":"\x3C旧版note_id>","target_content_format":1}' | \
  python3 -c "import sys,json,urllib.request; d=json.load(sys.stdin); url=d['data']['content_url']; req=urllib.request.Request(url); resp=urllib.request.urlopen(req); print(resp.read().decode('utf-8'))"

3C.2 提取版本信息

从标题下方的版本行提取：

**版本**：v1.0 | 创建于 2026-05-08 | 更新于 2026-05-08
**更新日志**：v1.0 - 初始版本

3C.3 对比知识库增量

获取文件夹最新文件列表，与旧版本对比：

# 获取文件夹中的文件列表
curl -s -X POST "https://ima.qq.com/openapi/wiki/v1/get_knowledge_list" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "\x3Ckb_id>", "limit": 50}' | \
  python3 -c "import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('knowledge_list',[])])"

3C.4 识别增量内容

3C.5 更新导览内容

更新原则：

• 保留原有结构：不改变核心概念划分方式
• 更新关键要素：补充/移除文章引用
• 更新实践建议：根据新增内容调整实践建议
• 更新学习路径：如有新的依赖关系

链接格式要求（必须严格遵守，引用格式：[《标题》](URL)）：

• 所有引用必须提供可点击的有效链接
• 链接来源参考第三步生成的链接特性表，选择正确的写法：
  • 云文档类：使用相对路径格式 [《标题》](路径)
  • 网页链接：使用完整URL格式 [《标题》](URL)
  • 纯本地文件：使用文件路径格式并标注来源
• 禁止使用裸链接或纯URL文本，必须包装为引用格式

3C.6 版本号更新

---
version: 1.1  # patch+0.0.1 或 minor+0.1 或 major+1.0
created: 2026-05-08
updated: 2026-05-08
changelog:
  - v1.1: 增量更新，补充了X篇新文章，更新了关键要素描述
  - v1.0: 初始版本
---

版本号规则：

• 仅增删文章 → patch +0.0.1
• 修改关键要素描述或实践建议 → minor +0.1
• 核心概念结构变化（新增/删除核心概念） → major +1.0

第四步：写入笔记

4.1 创建IMA笔记

将生成的导览笔记内容通过 IMA OpenAPI 创建为笔记：

# 调用IMA OpenAPI创建笔记
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 "{\"content_format\": 1, \"content\": $(python3 -c "import json; print(json.dumps(open('/sandbox/workspace/outputs/navigation_guide.md').read()))")}}"

返回处理：

result = {
    "code": 0,
    "data": {
        "note_id": "新创建的note_id",
        "note_title": "主题导览：XXX"
    }
}

4.2 移动笔记到目标文件夹

如果笔记创建在根目录，需要移动到导航文件夹：

# 1. 获取根目录笔记列表
curl -s -X POST "https://ima.qq.com/openapi/note/v1/list_note_by_folder_id" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "", "limit": 50}' | \
  python3 -c "import sys,json; data=json.load(sys.stdin); [print(f\"{n['title']}: {n['note_id']}\") for n in data.get('data',{}).get('note_list',[])]"

# 2. 笔记自动归入根目录（Skill 无 move_note 权限，无需移动操作）
# 通过 add_knowledge 导入知识库后，笔记可在对应文件夹中查看

导览笔记撰写规范

结构模板

模板来源：基于"交易策略与系统"主题导览的专业实践版本

# 主题导览：[主题名称]

**版本**：v1.0 | 创建于 YYYY-MM-DD | 更新于 YYYY-MM-DD
**更新日志**：v1.0 - 初始版本，基于知识库资料编译

## 一、主题定位
（主题定义 + 解决问题 + 核心逻辑 + 依赖链条）

本主题是XX的XX层，位于XX与XX之间。它解决的核心问题是：如何XX。
本主题涵盖XX、XX、XX三个关键环节，是XX的桥梁。其核心逻辑遵循清晰的依赖链条：XX → XX → XX → XX。

## 二、核心概念与关键要素

### （一）[核心概念A]
**核心思想**：一句话概括该概念的本质。

**关键要素**：
• 要素1：详细说明。相关文章[《文章标题》](链接)指出，具体内容...
• 要素2：详细说明。相关文章[《文章标题》](链接)进一步说明...
• 要素3：详细说明。

**实践建议**：
• 建议1：具体可操作的实践指导
• 建议2：具体可操作的实践指导

### （二）[核心概念B]
（同上结构）

## 三、学习路径（融合知识网络）

（以下学习路径以主线展示知识网络的连接关系，每个步骤标注了所需的核心知识储备和与之相关的概念。可根据主题实际需要设置1-N条路径，不必固定为两条）

（如有多条路径，在此展示）

## 四、相关主题

以下主题与"本主题名称"紧密关联，构成了更宽广的知识网络：

| 相关主题 | 与本主题的关系 | 关键连接点 |
|---------|--------------|-----------|
| XX | XX | XX |
| XX | XX | XX |

4章节结构规范

关键要素写作规范

每个关键要素的写作采用以下结构：

• 要素名称：详细说明。相关文章[《文章标题》](链接)指出，具体内容...
• 要素名称：详细说明。相关文章[《文章标题》](链接)进一步说明...

要点：

• 冒号前是要素名称（简洁短语）
• 冒号后是详细说明（1-2句话）
• 引用必须使用 [《标题》](链接) 格式，提供可点击的有效链接
• 根据链接特性表选择正确的写法：
  • type 2/6（网页/公众号）：使用 [《标题》](URL) 格式
  • type 7/11（Markdown/笔记）：使用纯文本标题，在文末标注"请在知识库中查看"
  • type 1/3/4/5（本地文件等）：使用纯文本标题，标注来源

实践建议写作规范

每个核心概念卡片末尾，用编号列表展示2-3条具体可操作的实践建议：

**实践建议**：
• 先有逻辑，后有回测：策略设计应先论证底层投资逻辑，回测只是验证工具，不能替代逻辑思考。
• 动态适应：策略参数需随市场环境变化而调整，融入宏观前瞻和状态感知可增强跨周期表现。
• 简单性优先：优先选择参数少、逻辑清晰的简单策略，减少过拟合风险。

要点：

• 建议要具体可操作，不是空泛原则
• 每条建议都有明确的行动指引
• 可以引用具体文章中的实践方法

学习路径表格规范

表格列定义：

最终整合：在表格后用一段话总结闭环流程。

版本控制机制

版本信息格式（放在大标题后）：

> **版本**：v1.0 | 创建于 YYYY-MM-DD | 更新于 YYYY-MM-DD
> **更新日志**：v1.0 - 初始版本，基于知识库资料编译

版本更新规则：

• 增删文章 → patch 版本号 +0.0.1
• 修改关键要素/设计原则 → minor 版本号 +0.1
• 重新编译整个主题 → major 版本号 +1.0

版本记录位置： 在笔记大标题下方用加粗行标注版本号、创建日期、更新日期和更新日志。

链接处理规则

前置要求：链接处理必须在**第三步（预获取链接信息）**中完成，不得在编译阶段临时获取。

根据预获取阶段生成的链接特性表，选择正确的链接策略：

引用格式示例：

# 可链接的类型（type 2/6）
• 多维度指标体系：A股情绪温度计采集12个维度指标...[《A股情绪温度计》](https://...)详细阐述了...

# 不可直接链接的类型（type 7/11/1/3/4/5）
• 系统化执行：（请在知识库中查看）

获取公众号/网页的永久URL

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": "\x3C文件media_id>"}'

返回的 data.media_content_url_info.url 即为永久可跳转链接。

特殊字符处理

文章标题中可能含有干扰Markdown渲染的字符：

• | → 替换为全角 ｜ 或省略
• [ ] _ * → 需转义或省略

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

导览笔记的文章列表必须从 get_knowledge_list 返回的实际文件生成，不能依赖本地缓存文件。

编译质量标准

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

第五步：主动维护与迭代

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

5.1 健康检查（"体检"）

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

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

5.2 知识补充

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

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

5.3 输出与回流

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

重要提醒

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

附录A：API命令模板

1. 检查文件夹中的笔记

curl -s -X POST "https://ima.qq.com/openapi/wiki/v1/get_knowledge_list" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "\x3Ckb_id>", "limit": 50}'

2. 导出笔记内容

curl -s -X POST "https://ima.qq.com/openapi/note/v1/export_note" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"note_id":"\x3Cnote_id>","target_content_format":1}' | python3 -c "
import sys,json,urllib.request
d=json.load(sys.stdin)
if d['code']==0:
    url=d['data']['content_url']
    req=urllib.request.Request(url)
    resp=urllib.request.urlopen(req)
    print(resp.read().decode('utf-8'))
else:
    print(d)
"

3. 构建请求JSON

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)

4. 创建笔记

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"}}

附录B：笔记本管理

获取/创建笔记本

# 列出笔记本
curl -s -X POST "https://ima.qq.com/openapi/note/v1/list_notebooks" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" | python3 -m json.tool

# 创建笔记本
curl -s -X POST "https://ima.qq.com/openapi/note/v1/create_notebook" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "知识导览"}' | python3 -m json.tool

更新旧笔记（增量更新时）

# 获取目标文件夹中的笔记列表
curl -s -X POST "https://ima.qq.com/openapi/note/v1/list_note_by_folder_id" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": "\x3C文件夹ID>", "limit": 50}' | python3 -c "
import sys,json
d=json.load(sys.stdin)
for note in d.get('data',{}).get('note_list',[]):
    if '主题导览' in note.get('title',''):
        print(f\"Found: {note['title']} -> note_id: {note['note_id']}\")
"

# 获取旧笔记内容
curl -s -X POST "https://ima.qq.com/openapi/note/v1/export_note" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"note_id":"\x3C旧note_id>","target_content_format":1}' | python3 -c "
import sys,json,urllib.request
d=json.load(sys.stdin)
if d['code']==0:
    url=d['data']['content_url']
    req=urllib.request.Request(url)
    resp=urllib.request.urlopen(req)
    print(resp.read().decode('utf-8'))
"

# 增量更新旧笔记（推荐方式，保留原note_id和历史）
curl -s -X POST "https://ima.qq.com/openapi/note/v1/update_note" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d "{\"note_id\": \"\x3C旧note_id>\", \"content_format\": 1, \"content\": $(python3 -c "import json; print(json.dumps(open('/sandbox/workspace/outputs/navigation_guide.md').read()))")}" | python3 -m json.tool

附录：IMA OpenAPI 调用方法

环境变量配置

# 必需的环境变量
IMA_OPENAPI_CLIENTID=你的ClientID
IMA_OPENAPI_APIKEY=你的APIKey

# 或使用配置文件
mkdir -p ~/.config/ima
echo "你的ClientID" > ~/.config/ima/client_id
echo "你的APIKey" > ~/.config/ima/api_key
chmod 600 ~/.config/ima/*

通用调用函数（Python）

import urllib.request
import json

def ima_api(path, data=None):
    """IMA OpenAPI 通用调用函数"""
    headers = {
        "ima-openapi-clientid": "你的ClientID",
        "ima-openapi-apikey": "你的APIKey",
        "Content-Type": "application/json"
    }
    url = f"https://ima.qq.com/{path}"
    req = urllib.request.Request(
        url, 
        data=json.dumps(data or {}).encode('utf-8'),
        headers=headers,
        method="POST"
    )
    with urllib.request.urlopen(req, timeout=15) as resp:
        return json.loads(resp.read().decode('utf-8'))

常用 API 端点

常见调用示例

1. 获取知识库内容列表

result = ima_api("openapi/wiki/v1/get_knowledge_list", {
    "knowledge_base_id": "你的知识库ID",
    "limit": 50
})
for item in result.get('data', {}).get('knowledge_list', []):
    print(f"[{item.get('media_type')}] {item.get('title')}")

2. 搜索知识库

result = ima_api("openapi/wiki/v1/search_knowledge_base", {
    "query": "关键词",
    "cursor": "",
    "limit": 20
})

3. 创建笔记

result = ima_api("openapi/note/v1/import_doc", {
    "content_format": 1,
    "content": "# 标题\
\
正文内容"
})
note_id = result.get('data', {}).get('note_id')

错误代码参考