Knowledge Base (知识库)

Prerequisites: see root

../SKILL.md

for setup, credentials, and

ima_api()

helper.

API base path:

openapi/wiki/v1

通过 IMA Wiki OpenAPI 管理用户知识库，支持上传文件、添加网页链接、搜索知识库内容、浏览知识库列表和获取知识库详情。

完整的数据结构和接口参数详见

references/api.md

接口决策表

check_repeated_names

create_media

add_knowledge

media_type

knowledge_base_id

file_name

file_size

folder_id

import_urls

urls

knowledge_base_id

folder_id

add_knowledge

media_type=11

note_info.content_id=<doc_id>

knowledge_base_id

check_repeated_names

check_repeated_names

params[].name

params[].media_type

knowledge_base_id

folder_id

get_knowledge_base

ids

get_knowledge_list

knowledge_base_id

cursor

limit

folder_id

search_knowledge

query

knowledge_base_id

cursor

search_knowledge_base

query

cursor

limit

search_knowledge_base

query

query: ""

cursor

limit

get_addable_knowledge_base_list

cursor

limit

search_knowledge_base

vs

get_addable_knowledge_base_list

选择指南

这两个接口容易混淆，选择规则：

search_knowledge_base

search_knowledge_base

get_knowledge_base

search_knowledge_base

query: ""

get_addable_knowledge_base_list

get_addable_knowledge_base_list

绝不要在用户已明确指定知识库名称时调用

get_addable_knowledge_base_list

search_knowledge_base

文件类型检测

使用

scripts/preflight-check.cjs

1. --content-type

   已提供且可识别 → content-type 优先，直接使用

2. --content-type

   不可识别 → 回退到扩展名
3. 未提供

   --content-type

   → 使用扩展名
4. 两者都无法识别 → 拒绝处理

# 有扩展名（自动推断）
node .claude/skills/ima-skill/knowledge-base/scripts/preflight-check.cjs --file report.pdf

# 无扩展名或扩展名不可识别（需传入 content-type，如从 HTTP HEAD 获取）
node .claude/skills/ima-skill/knowledge-base/scripts/preflight-check.cjs --file downloaded_file --content-type application/pdf

扩展名与类型的对应关系：

.pdf

application/pdf

.doc

application/msword

.docx

application/vnd.openxmlformats-officedocument.wordprocessingml.document

.ppt

application/vnd.ms-powerpoint

.pptx

application/vnd.openxmlformats-officedocument.presentationml.presentation

.xls

application/vnd.ms-excel

.xlsx

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

.csv

text/csv

.md

.markdown

text/markdown

.png

image/png

.jpg

.jpeg

image/jpeg

.webp

image/webp

.txt

text/plain

.xmind

application/x-xmind

application/vnd.xmind.workbook

application/zip

.mp3

audio/mpeg

.m4a

audio/x-m4a

.wav

audio/wav

.aac

audio/aac

未识别的扩展名或无扩展名：直接告知用户该文件类型不被支持，立即终止操作。不要猜测或默认为某个类型，不要询问用户是否仍要上传。

不支持的类型：视频文件（

.mp4

、

.avi

、

.mov

等）、Bilibili（

bilibili.com/video/

）和 YouTube（

youtube.com/watch

）链接、本地 HTML 文件（

file://

）无法通过 skill 添加到知识库。直接告知用户「该文件类型不支持，仅支持在 ima 桌面端内添加进知识库」，不要提供上传选项或询问是否继续。

URL 类型检测

添加 URL 到知识库时，需要根据 URL 模式和 Content-Type 判断类型。检测按以下优先级进行：

1. Content-Type 为

text/html

mp.weixin.qq.com/s/

mp.weixin.qq.com/s?

import_urls

https://www.bilibili.com/video/

https://www.youtube.com/watch

file://

text/html

import_urls

2. Content-Type 为文件类型时： 按文件类型检测表处理（PDF、Word、Excel 等）。

3. 其他： 告知用户该类型不被支持。

添加前置检查（Pre-flight Check）

在执行任何添加知识到知识库的操作前（

add_knowledge

import_urls

1. 类型支持检查

.mp4

.avi

.mov

https://www.bilibili.com/video/

https://www.youtube.com/watch

file://

2. 文件大小检查

上传前必须校验文件大小，超限文件应在上传前拦截，不要发起请求：

3. 音频时长检查

音频文件（media_type=15）额外限制：最长 2 小时。超过时告知用户。

4. 文件名重复检查

仅适用于文件类型（media_type 1/3/4/5/7/9/13/14/15），不适用于网页（2/6）、笔记（11）等：

• 调用

  check_repeated_names

  检查

• is_repeated=true

  ：询问用户是否保留两者（追加时间戳）或取消
• 不支持"替换"操作

检查顺序很重要：先做类型和大小检查（本地即可判断），通过后再调用远程接口检查重名。避免对不支持或超限的文件发起不必要的网络请求。

常用工作流

上传文件到知识库

完成「添加前置检查」后，执行以下步骤：创建媒体 → 上传 COS → 添加知识。

前置检查（类型检测、大小校验、重名检查）见「添加前置检查」章节。

# 1. 前置检查 — 类型、大小一步完成
#    有扩展名时：自动从扩展名推断 media_type 和 content_type
#    无扩展名时：需通过 --content-type 传入（如从 HTTP HEAD 获取）
PREFLIGHT=$(node .claude/skills/ima-skill/knowledge-base/scripts/preflight-check.cjs \
  --file "/path/to/report.pdf")
echo "$PREFLIGHT"
# pass=false 时直接终止，将 reason 展示给用户

# 2. 从 preflight 结果提取字段（用于后续 API 调用）
FILE_NAME=$(echo "$PREFLIGHT" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.file_name)")
FILE_EXT=$(echo "$PREFLIGHT" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.file_ext)")
FILE_SIZE=$(echo "$PREFLIGHT" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(String(d.file_size))")
MEDIA_TYPE=$(echo "$PREFLIGHT" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(String(d.media_type))")
CONTENT_TYPE=$(echo "$PREFLIGHT" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8'));process.stdout.write(d.content_type)")

# 3. 重名检查（仅文件类型，见「添加前置检查」第 4 步）

# 4. create_media — 获取 media_id 和 COS 上传凭证
ima_api "openapi/wiki/v1/create_media" "{
  \"file_name\": \"$FILE_NAME\",
  \"file_size\": $FILE_SIZE,
  \"content_type\": \"$CONTENT_TYPE\",
  \"knowledge_base_id\": \"<kb_id>\",
  \"file_ext\": \"$FILE_EXT\"
}"
# 从返回值提取 media_id 和 cos_credential 各字段

# 5. 上传文件到 COS
node .claude/skills/ima-skill/knowledge-base/scripts/cos-upload.cjs \
  --file "/path/to/report.pdf" \
  --secret-id "<cos_credential.secret_id>" \
  --secret-key "<cos_credential.secret_key>" \
  --token "<cos_credential.token>" \
  --bucket "<cos_credential.bucket_name>" \
  --region "<cos_credential.region>" \
  --cos-key "<cos_credential.cos_key>" \
  --content-type "$CONTENT_TYPE" \
  --start-time "<cos_credential.start_time>" \
  --expired-time "<cos_credential.expired_time>"

# 6. add_knowledge — 将已上传的文件关联到知识库
ima_api "openapi/wiki/v1/add_knowledge" "{
  \"media_type\": $MEDIA_TYPE,
  \"media_id\": \"<media_id>\",
  \"title\": \"$FILE_NAME\",
  \"knowledge_base_id\": \"<kb_id>\",
  \"file_info\": {
    \"cos_key\": \"<cos_credential.cos_key>\",
    \"file_size\": $FILE_SIZE,
    \"file_name\": \"$FILE_NAME\"
  }
}"

批量上传时的重复处理

当上传多个文件时，可一次性检查所有文件名（最多 2000 个）：

# 批量检查
ima_api "openapi/wiki/v1/check_repeated_names" '{
  "params": [
    {"name": "report.pdf", "media_type": 1},
    {"name": "slides.pptx", "media_type": 4},
    {"name": "data.xlsx", "media_type": 5}
  ],
  "knowledge_base_id": "<kb_id>",
  "folder_id": "<folder_id>"
}'
# 注意：如果是根目录，省略 folder_id 字段
# 遍历 results，对 is_repeated=true 的文件询问用户：
# - "以下文件在知识库中已存在同名文件：report.pdf、data.xlsx。是否保留两者？（不支持替换）"
# - 用户选择"保留两者"的文件：追加时间戳后继续上传
# - 用户选择"取消"的文件：从上传列表中移除

时间戳命名规则：在文件名（不含扩展名）末尾追加

_YYYYMMDDHHmmss

report_20260317153000.pdf

添加网页/微信文章到知识库

使用

import_urls

# 添加到根目录（不传 folder_id）
ima_api "openapi/wiki/v1/import_urls" '{
  "knowledge_base_id": "<kb_id>",
  "urls": [
    "https://example.com/article",
    "https://mp.weixin.qq.com/s/xxxxx"
  ]
}'

# 添加到指定文件夹（传 folder_id，以 folder_ 开头）
ima_api "openapi/wiki/v1/import_urls" '{
  "knowledge_base_id": "<kb_id>",
  "folder_id": "<folder_id>",
  "urls": [
    "https://example.com/article"
  ]
}'
# 返回 results 映射：{ "<url>": { url, ret_code, media_id } }
# ret_code=0 表示成功，非 0 查看 errmsg

添加笔记到知识库

将已有笔记（通过

doc_id

ima_api "openapi/wiki/v1/add_knowledge" '{
  "media_type": 11,
  "note_info": { "content_id": "<doc_id>" },
  "title": "笔记标题",
  "knowledge_base_id": "<kb_id>"
}'

添加 URL 到知识库（自动检测文件型 URL）

当用户提供 URL 时，需先判断该 URL 指向的是网页还是可下载文件（PDF、Word、PPT 等）。

判断规则（按优先级）：

1. URL 路径包含文件扩展名：如

   https://arxiv.org/pdf/2603.12268

   以

   /pdf/

   开头，或

   https://example.com/report.pdf

   以

   .pdf

   结尾 → 文件型
2. 发送 HEAD 请求检查 Content-Type：

   curl -sI -L <url>

   查看响应头

   • application/pdf

     → PDF 文件

   • application/msword

     或

     application/vnd.openxmlformats-*

     → Word/PPT/Excel 文件

   • text/html

     → 网页
3. 已知文件型 URL 模式：

   • arxiv.org/pdf/*

     → PDF

   • *.pdf

     、

     *.docx

     、

     *.pptx

     、

     *.xlsx

     结尾 → 对应文件类型
   • GitHub raw 文件链接 → 按扩展名判断

文件型 URL 处理流程：

# 1. 探测 URL 类型
CONTENT_TYPE=$(curl -sI -L "https://arxiv.org/pdf/2603.12268" | grep -i "^content-type:" | tail -1 | awk '{print $2}' | tr -d '\r')
# 结果如 application/pdf → 文件型

# 2. 下载文件到临时目录
TEMP_DIR=$(mktemp -d)
# 根据 Content-Type 或 URL 推断文件名和扩展名
curl -sL -o "$TEMP_DIR/paper.pdf" "https://arxiv.org/pdf/2603.12268"

# 3. 前置检查（传入 content-type 作为备用，文件名有扩展名时会优先用扩展名）
PREFLIGHT=$(node .claude/skills/ima-skill/knowledge-base/scripts/preflight-check.cjs \
  --file "$TEMP_DIR/paper.pdf" --content-type "$CONTENT_TYPE")
echo "$PREFLIGHT"
# pass=false 时直接终止

# 4. 按"上传文件到知识库"流程处理：create_media → COS Upload → add_knowledge
# （参见上方"上传文件到知识库"工作流）

# 5. 清理临时文件
rm -rf "$TEMP_DIR"

文件名推断：

• 优先从

  Content-Disposition

  响应头提取文件名
• 其次从 URL 路径中提取（如

  /pdf/2603.12268

  →

  2603.12268.pdf

  ）
• 最后使用 URL 的最后一段路径 + 根据 Content-Type 补充扩展名

文件夹操作

知识库内容以文件夹结构组织。文件夹本身也是一种知识条目，在

get_knowledge_list

search_knowledge

核心概念

• folder_id

  ：文件夹的唯一标识，始终以

  folder_

  前缀开头（如

  folder_abc123

  ），在

  add_knowledge

  、

  import_urls

  、

  get_knowledge_list

  、

  check_repeated_names

  等接口中用于指定目标文件夹
• 操作根目录时，不要传

  folder_id

  参数（直接省略该字段），不要将

  knowledge_base_id

  作为

  folder_id

  传入

• get_knowledge_list

  返回的

  current_path

  （

  FolderInfo[]

  ）表示当前浏览位置的完整路径（面包屑）

定位文件夹（用户提到文件夹名时）

当用户说「添加到 XX 文件夹」但只给了文件夹名称时，需要先找到

folder_id

# 方法 1：搜索知识库内容（推荐，可直接按名称搜索文件夹）
ima_api "openapi/wiki/v1/search_knowledge" '{
  "query": "文件夹名称",
  "knowledge_base_id": "<kb_id>",
  "cursor": ""
}'
# 从返回的 info_list 中找到匹配的文件夹条目，取其 media_id 作为 folder_id

# 方法 2：浏览根目录列表逐级查找
ima_api "openapi/wiki/v1/get_knowledge_list" '{
  "knowledge_base_id": "<kb_id>",
  "cursor": "",
  "limit": 50
}'
# 从返回的 knowledge_list 中找到目标文件夹，取其 media_id 作为 folder_id
# 如果文件夹在子目录中，需要用返回的 folder_id 逐级深入

添加内容到指定文件夹

所有写入接口（

add_knowledge

import_urls

check_repeated_names

folder_id

# 上传文件到指定文件夹
ima_api "openapi/wiki/v1/add_knowledge" '{
  "media_type": 1,
  "media_id": "<media_id>",
  "title": "report.pdf",
  "knowledge_base_id": "<kb_id>",
  "folder_id": "<folder_id>",
  "file_info": { "cos_key": "...", "file_size": 12345, "file_name": "report.pdf" }
}'

# 导入网页到指定文件夹
ima_api "openapi/wiki/v1/import_urls" '{
  "knowledge_base_id": "<kb_id>",
  "folder_id": "<folder_id>",
  "urls": ["https://example.com/article"]
}'

# 添加到根目录时，直接省略 folder_id
ima_api "openapi/wiki/v1/add_knowledge" '{
  "media_type": 1,
  "media_id": "<media_id>",
  "title": "report.pdf",
  "knowledge_base_id": "<kb_id>",
  "file_info": { "cos_key": "...", "file_size": 12345, "file_name": "report.pdf" }
}'

获取知识库信息

ima_api "openapi/wiki/v1/get_knowledge_base" '{"ids": ["<kb_id>"]}'
# 返回 infos 映射：{ "<kb_id>": { id, name, cover_url, description, recommended_questions } }

浏览知识库内容

# 浏览根目录
ima_api "openapi/wiki/v1/get_knowledge_list" '{"knowledge_base_id": "<kb_id>", "cursor": "", "limit": 20}'

# 浏览指定文件夹
ima_api "openapi/wiki/v1/get_knowledge_list" '{"knowledge_base_id": "<kb_id>", "folder_id": "<folder_id>", "cursor": "", "limit": 20}'
# 翻页：用 next_cursor，is_end=true 时停止

在知识库中搜索

ima_api "openapi/wiki/v1/search_knowledge" '{"query": "搜索关键词", "knowledge_base_id": "<kb_id>", "cursor": ""}'

搜索知识库列表

# 按关键词搜索
ima_api "openapi/wiki/v1/search_knowledge_base" '{"query": "搜索关键词", "cursor": "", "limit": 20}'

# 查看所有知识库（空 query）
ima_api "openapi/wiki/v1/search_knowledge_base" '{"query": "", "cursor": "", "limit": 20}'

获取可添加的知识库列表

仅当用户要添加内容但未指定目标知识库时使用。如果用户已给出知识库名称，应使用

search_knowledge_base

# 首次请求
ima_api "openapi/wiki/v1/get_addable_knowledge_base_list" '{"cursor": "", "limit": 20}'
# 翻页：用 next_cursor，is_end=true 时停止

核心响应字段

知识条目（

KnowledgeInfo

media_id

title

parent_folder_id

搜索到的知识条目（

SearchedKnowledgeInfo

media_id

title

parent_folder_id

highlight_content

知识库信息（

KnowledgeBaseInfo

id

name

cover_url

description

recommended_questions

文件夹条目（

FolderInfo

folder_id

name

file_number

folder_number

parent_folder_id

is_top

完整字段定义见

references/api.md

分页

所有列表和搜索接口使用游标分页：

1. 首次请求：

   cursor: ""

2. 检查返回的

   is_end

   ：

   false

   表示还有更多数据
3. 将返回的

   next_cursor

   作为下次请求的

   cursor

4. is_end = true

   时停止翻页

响应处理

所有 API 返回统一结构

{ "retcode": 0, "errmsg": "...", "data": { ... } }

• retcode=0

  ：成功，从

  data

  提取业务字段

• retcode≠0

  ：失败，直接将

  errmsg

  展示给用户即可，不需要自行翻译错误码

用户体验

• 隐藏内部 ID：面向用户的展示中永远不要暴露

  knowledge_base_id

  、

  media_id

  、

  folder_id

  等内部 ID。始终使用知识库名称、文件标题、文件夹名称等用户可读信息。ID 仅用于后续 API 调用，不展示给用户。
  • ✅

    "已添加到知识库「产品文档库」✓"

  • ❌

    "已添加到知识库 abc123def456 ✓"

  • 需要引用知识库时，先通过

    get_knowledge_base

    获取名称，再展示

• 精简进度：不要逐步暴露内部操作（如"正在创建媒体…正在上传 COS…"）。只报告用户关心的信息：

  • 上传文件：

    "正在上传 report.pdf…"

    →

    "已添加到知识库「产品文档库」✓"

  • 添加网页：

    "正在添加…"

    →

    "已添加到「产品文档库」✓"

  • 失败时展示

    errmsg

    即可

• 批量操作：汇总结果，如

  "3 个文件已添加到「产品文档库」，1 个失败（data.xlsx: 文件大小超限）"

• 格式化展示：读取类操作的结果应以结构化格式展示给用户，而非原始 JSON：

  知识库列表（

  search_knowledge_base

  /

  get_addable_knowledge_base_list

  ）：

  搜索知识库后，用返回的 ID 列表调用

  get_knowledge_base

  获取描述信息，一并展示。

  📚 搜索结果（共 3 个知识库）：
  1. **产品文档库** — 存放产品相关的所有文档资料
  2. **技术方案库** — 各项目技术方案汇总
  3. **竞品分析库**
  

  知识库内容列表（

  get_knowledge_list

  ）：

  📂 知识库「产品文档库」内容：
  📁 设计文档/          (3 个文件, 1 个子文件夹)
  📁 会议纪要/          (12 个文件)
  📄 产品需求文档.pdf
  📄 技术方案.docx
  📄 数据分析.xlsx
  --- 第 1 页，还有更多内容 ---
  

  搜索结果（

  search_knowledge

  ）：

  search_knowledge

  返回的条目包含

  media_id

  、

  title

  、

  parent_folder_id

  、

  highlight_content

  （内容匹配时返回高亮片段），

  🔍 在知识库「产品文档库」中搜索「排期」的结果：
  
  1. 📄 Q1排期表.xlsx (文件夹: 项目管理/)
     > ...包含**排期**计划的详细信息...
  2. 📄 开发排期讨论.pdf (文件夹: 会议纪要/)
  3. 📁 排期模板/ (文件夹: 根目录)
  

  知识库详情（

  get_knowledge_base

  ）：

  📚 产品文档库
  📝 描述：存放产品相关的所有文档资料
  💡 推荐问题：
     - 最新的产品需求是什么？
     - 技术方案有哪些？
  

注意事项

• get_knowledge_base

  接受 1-20 个 ID；单个 ID 也需包装为数组

• get_knowledge_list

  的

  limit

  范围为 1~50
• 文件夹是知识条目的一种：

  get_knowledge_list

  和

  search_knowledge

  的返回结果中同时包含文件和文件夹，需通过字段区分（文件夹有

  folder_id

  /

  name

  /

  file_number

  /

  folder_number

  ，文件有

  media_id

  /

  title

  ）
• 用户提到文件夹时：如果用户只给了文件夹名称（而非 ID），必须先通过

  search_knowledge

  或

  get_knowledge_list

  找到对应的

  folder_id

  ，再执行后续操作

• folder_id

  在

  add_knowledge

  、

  import_urls

  、

  get_knowledge_list

  、

  check_repeated_names

  中均为可选字段，操作根目录时直接省略

  folder_id

  ，不要传该参数。

  folder_id

  的值始终以

  folder_

  前缀开头（如

  folder_abc123

  ），不要将

  knowledge_base_id

  作为

  folder_id

  传入
• 文件上传时

  title

  必须等于

  file_name

  ：调用

  add_knowledge

  添加文件时，

  title

  字段必须使用文件的原始完整文件名（含扩展名），不要自行拟定标题。

  file_name

  和

  title

  传同一个值。禁止缩短、翻译、重命名或省略任何部分。例如文件名为

  音频.mp3

  ，则

  file_name

  和

  title

  都必须传

  音频.mp3

• 文件扩展名必须正确提取，用于

  media_type

  检测和

  file_ext

  字段（无点号，如

  pdf

  ）
• COS 上传脚本失败（非零退出码）时，不要继续调用

  add_knowledge

• COS 上传时

  --content-type

  应传入文件的实际 MIME 类型（如

  application/pdf

  ），而非通用的

  application/octet-stream

• 当用户提供 URL 添加到知识库时，必须先检测 URL 是否指向文件（通过 URL 路径扩展名 + HEAD 请求 Content-Type），文件型 URL 需下载后走上传流程；网页/微信文章型 URL 使用

  import_urls