ima wiki 编译器

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

Audits

Pass

ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install ima-wiki-compiler

知识库 Wiki 编译器

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

整体流程

需求理解与资料收集 — 明确主题边界
检查旧版本 — 判断是否已有知识导览，决定增量更新还是新建
编译生成 — 5步法构建Wiki知识体系（新建或增量更新）
主动维护与迭代

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

判断用户状态：

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

明确知识库边界：

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

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

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

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

第二步：检查旧版本

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

检查方式

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

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": "<kb_id>", "folder_id": "<folder_id>", "count": 50}' | \
  python3 -c "import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('list',[])])"

如果找到"主题导览：xxx"笔记，记录其 note_id 和版本信息
如果没找到，则进入新建流程

判断逻辑

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

增量更新流程

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

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

第三步：编译生成（新建模式）

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

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

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

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

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

对每个核心概念，提取：

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

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

建立概念之间的连接：

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

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

将关系转化为：

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

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

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

第四步：增量更新模式

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

4.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":"<旧版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'))"

4.2 提取版本信息

从 YAML front matter 提取：

version: 1.0
created: 2026-05-08
updated: 2026-05-08
changelog:
  - v1.0: 初始版本

4.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": "<kb_id>", "folder_id": "<folder_id>", "count": 100}' | \
  python3 -c "import sys,json; data=json.load(sys.stdin); print([f['title'] for f in data.get('data',{}).get('list',[])])"

4.4 识别增量内容

类型	判断方式	更新方式
新增文章	旧版本"四、知识卡片"中不存在	补充到对应核心概念的关键要素中
删除文章	旧版本提及但知识库中已不存在	从列表中移除
概念变化	知识库中出现新的核心概念分类	新增核心概念卡片

4.5 更新导览内容

更新原则：

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

4.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

第五步：写入笔记

导览笔记撰写规范

结构模板

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

---
version: 1.0
created: YYYY-MM-DD
updated: YYYY-MM-DD
changelog:
  - v1.0: 初始版本，基于知识库资料编译
---

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

> **版本**：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-3条路径，不必固定为两条）

**路径A：入门路径（最易上手）**

| 步骤 | 核心知识 | 知识网络连接 |
|------|---------|-------------|
| 步骤1：XX | XX | → 需要XX概念 → 需要XX基础 |
| 步骤2：XX | XX | → XX |
| 步骤3：XX | XX | → XX |

**路径B：系统学习路径（按知识依赖）**

| 步骤 | 核心知识 | 知识网络连接 |
|------|---------|-------------|
| 步骤1：XX | XX | 是所有后续XX的基础 |
| 步骤2：XX | XX | 提供XX，是后续XX的前提 |
| ... | ... | ... |

**最终整合**：结合所有步骤，形成完整的闭环：XX → XX → XX → XX。这一流程体现了XX的前沿可能性。

## 四、相关主题

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

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

4章节结构规范

章节	内容详略	内容要求	写作要点
一、主题定位	略写一段话（约100字）	定义 + 解决问题 + 核心逻辑 + 依赖链条	用"是...的XX层，位于XX与XX之间"句式；依赖链条用箭头链展示
二、核心概念与关键要素	详写每概念约200-300字	核心思想 + 关键要素（引用文章） + 实践建议	每个关键要素都要引用知识库文章；实践建议要具体可操作
三、学习路径（融合知识网络）	中等表格+一段话	两条路径 + 表格形式 + 最终整合	表格内容精简，最终整合一段话点明闭环逻辑
四、相关主题	略写表格形式	主题 + 关系 + 连接点	说明每个关联主题的具体连接点，无需展开

关键要素写作规范

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

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

要点：

冒号前是要素名称（简洁短语）
冒号后是详细说明（1-2句话）
末尾用"相关文章《标题》指出/进一步说明/提供了..."格式引用
引用来源必须是知识库中的实际文章

实践建议写作规范

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

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

要点：

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

学习路径表格规范

表格列定义：

列名	内容
步骤	第X步：具体步骤名称
核心知识	需要掌握的核心概念
知识网络连接	与其他主题的关联（用→表示递进，用→ 需要表示依赖）

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

版本控制机制

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

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

版本更新规则：

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

版本记录位置： 在笔记正文开头用 YAML front matter 标注。

链接处理规则

引用文章时必须提供链接，不同类型的文件有不同的链接策略：

media_type	类型	链接策略
2	网页链接	✅ 获取真实URL，格式：`[《标题》](URL)`
6	公众号文章	✅ 获取真实URL，格式：`[《标题》](URL)`
7	Markdown	⚠️ 标注"请在知识库中查看"
11	笔记	⚠️ 标注"请在知识库中查看"
1	PDF	⚠️ 标注"请在知识库中查看"
3	Word	⚠️ 标注"请在知识库中查看"
4	PPT	⚠️ 标注"请在知识库中查看"
5	Excel	⚠️ 标注"请在知识库中查看"

引用格式示例：

# 可链接的类型（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": "<文件media_id>"}'

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

特殊字符处理

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

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

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

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

编译质量标准

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

第六步：主动维护与迭代

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

6.1 健康检查（"体检"）

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

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

6.2 知识补充

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

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

6.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": "<kb_id>", "folder_id": "<folder_id>", "count": 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":"<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'))
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_notes" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"notebook_id": "<notebook_id>", "count": 100}' | python3 -c "
import sys,json
d=json.load(sys.stdin)
for note in d.get('data',{}).get('notes',[]):
    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/delete_note" \
  -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
  -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
  -H "Content-Type: application/json" \
  -d '{"note_id": "<旧note_id>"}' | python3 -m json.tool

# 重新创建（推荐方式，保留新的note_id）