# IMA知识库 API

## ⚠️ 必读约束

### 🌐 服务信息

- **Base URL **：`https://ima.qq.com`
- **Base Path**：`/openapi/wiki/v1`
- **协议**：HTTP POST，JSON body
- **完整示例**：`POST https://ima.qq.com/openapi/wiki/v1/get_knowledge_base`

### 🔒 认证

所有请求必须携带 Header：

| Header                 | 说明               |
| ---------------------- | ------------------ |
| `ima-openapi-clientid` | Client ID          |
| `ima-openapi-apikey`   | API Key            |
| `Content-Type`         | `application/json` |

---

## 快速决策

| 用户意图                        | 接口                                                                   |
| ------------------------------- | ---------------------------------------------------------------------- |
| 「上传文件到知识库」            | `check_repeated_names` → `create_media` → COS Upload → `add_knowledge` |
| 「上传文件到指定文件夹」        | 先定位文件夹 → 同上（传入 `folder_id`）                                |
| 「添加网页/微信文章到知识库」   | `import_urls`                                                          |
| 「获取知识库信息」              | `get_knowledge_base`                                                   |
| 「浏览知识库内容 / 浏览文件夹」 | `get_knowledge_list`（可传 `folder_id` 进入子文件夹）                  |
| 「在知识库中搜索」              | `search_knowledge`                                                     |
| 「搜索知识库列表」              | `search_knowledge_base`                                                |
| 「获取可添加的知识库列表」      | `get_addable_knowledge_base_list`                                      |
| 「检查文件名是否重复」          | `check_repeated_names`                                                 |

---

## 数据结构

### KnowledgeBaseInfo（知识库信息）

| 字段                    | 类型     | 说明          |
| ----------------------- | -------- | ------------- |
| `id`                    | string   | 知识库唯一 ID |
| `name`                  | string   | 知识库名称    |
| `cover_url`             | string   | 封面图 URL    |
| `description`           | string   | 描述          |
| `recommended_questions` | string[] | 推荐问题列表  |

### KnowledgeInfo（知识条目）

| 字段               | 类型   | 说明          |
| ------------------ | ------ | ------------- |
| `media_id`         | string | 媒体 ID       |
| `title`            | string | 标题          |
| `parent_folder_id` | string | 所属文件夹 ID |

### FolderInfo（文件夹条目）

| 字段               | 类型   | 说明        |
| ------------------ | ------ | ----------- |
| `folder_id`        | string | 文件夹 ID   |
| `name`             | string | 文件夹名称  |
| `file_number`      | int64  | 文件数      |
| `folder_number`    | int64  | 子文件夹数  |
| `parent_folder_id` | string | 父文件夹 ID |
| `is_top`           | bool   | 是否置顶    |

### AddableKnowledgeBaseInfo（可添加的知识库信息）

| 字段   | 类型   | 说明       |
| ------ | ------ | ---------- |
| `id`   | string | 知识库 ID  |
| `name` | string | 知识库名称 |

### SearchedKnowledgeBaseInfo（搜索到的知识库信息）

| 字段        | 类型   | 说明       |
| ----------- | ------ | ---------- |
| `id`        | string | 知识库 ID  |
| `name`      | string | 知识库名称 |
| `cover_url` | string | 封面图 URL |

### SearchedKnowledgeInfo（搜索到的知识条目）

| 字段                | 类型   | 说明                       |
| ------------------- | ------ | -------------------------- |
| `media_id`          | string | 媒体 ID                    |
| `title`             | string | 标题                       |
| `parent_folder_id`  | string | 所属文件夹 ID              |
| `highlight_content` | string | 高亮内容（内容匹配时返回） |

### ContentInfo（内容信息）

| 字段         | 类型   | 说明                    |
| ------------ | ------ | ----------------------- |
| `content_id` | string | 内容 ID（网页时为 URL） |

### ImportURLData（URL 导入结果）

| 字段       | 类型   | 说明                    |
| ---------- | ------ | ----------------------- |
| `url`      | string | 导入的 URL              |
| `ret_code` | int32  | 0=成功，非 0=失败       |
| `media_id` | string | 导入成功后返回的媒体 ID |

### FileInfo（文件信息）

`add_knowledge` 文件上传时使用：

| 字段               | 类型   | 说明                       |
| ------------------ | ------ | -------------------------- |
| `cos_key`          | string | COS 对象 Key               |
| `file_size`        | uint64 | 文件大小（字节）           |
| `last_modify_time` | int64  | 最后修改时间（秒级时间戳） |
| `password`         | string | 文件密码（如有）           |
| `file_name`        | string | 文件名称                   |

### Credential（COS 上传凭证）

`create_media` 返回，用于上传文件到腾讯云 COS：

| 字段            | 类型   | 说明                       |
| --------------- | ------ | -------------------------- |
| `token`         | string | 临时 TOKEN                 |
| `secret_id`     | string | 临时 Secret ID             |
| `secret_key`    | string | 临时 Secret Key            |
| `start_time`    | int64  | 凭证开始时间（秒级时间戳） |
| `expired_time`  | int64  | 凭证过期时间（秒级时间戳） |
| `appid`         | string | COS AppID                  |
| `bucket_name`   | string | COS 桶名称                 |
| `region`        | string | COS 桶所在区域             |
| `custom_domain` | string | 自定义域名                 |
| `cos_key`       | string | COS 对象 Key               |

### MediaType（媒体类型枚举）

| 值  | 名称           | content_type / 说明                                                                                           |
| --- | -------------- | ------------------------------------------------------------------------------------------------------------- |
| 1   | PDF            | `application/pdf`                                                                                             |
| 2   | 网页           | N/A（直接 AddKnowledge，`web_info.content_id=<url>`）                                                         |
| 3   | Word           | `application/msword` / `application/vnd.openxmlformats-officedocument.wordprocessingml.document`              |
| 4   | PPT            | `application/vnd.ms-powerpoint` / `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
| 5   | Excel          | `application/vnd.ms-excel` / `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` / `text/csv` |
| 6   | 微信公众号文章 | N/A（直接 AddKnowledge，`web_info.content_id=<url>`，URL 匹配 `mp.weixin.qq.com/s`）                          |
| 7   | MarkDown       | `text/markdown` / `text/x-markdown` / `application/md` / `application/markdown`                               |
| 9   | 图片           | `image/png`, `image/jpeg`, `image/webp`                                                                       |
| 11  | 笔记           | N/A（直接 AddKnowledge，`note_info.content_id=<doc_id>`）                                                     |
| 12  | AI会话         | N/A（直接 AddKnowledge，`session_info.content_id=<session_id>`）                                              |
| 13  | TXT            | `text/plain`                                                                                                  |
| 14  | Xmind          | `application/x-xmind` / `application/vnd.xmind.workbook` / `application/zip`                                  |
| 15  | 录音           | `audio/mpeg`(mp3), `audio/x-m4a`(m4a), `audio/wav`(wav), `audio/aac`(aac)                                     |
| 16  | 视频解析       | **不支持通过 skill 添加**。Bilibili/YouTube/本地HTML等仅支持在 ima 桌面端内添加进知识库                       |

---

## 接口详情

### 1. 创建媒体

POST /openapi/wiki/v1/create_media

**触发场景**：上传文件到知识库的第一步，获取 COS 上传凭证。

#### 请求参数

| 字段                | 类型   | 必填 | 说明                           |
| ------------------- | ------ | ---- | ------------------------------ |
| `file_name`         | string | 是   | 文件名称（最长 1024 字符）     |
| `file_size`         | uint64 | 是   | 文件大小（字节）               |
| `content_type`      | string | 是   | MIME 类型                      |
| `knowledge_base_id` | string | 是   | 知识库 ID                      |
| `file_ext`          | string | 是   | 文件后缀名（无点号，如 `pdf`） |

#### 返回字段

| 字段             | 类型       | 说明         |
| ---------------- | ---------- | ------------ |
| `media_id`       | string     | 媒体 ID      |
| `cos_credential` | Credential | COS 上传凭证 |

---

### 2. 添加知识

POST /openapi/wiki/v1/add_knowledge

**触发场景**：上传文件到知识库的最后一步，或直接添加网页 URL。

#### 请求参数

| 字段                  | 类型        | 必填     | 说明                                    |
| --------------------- | ----------- | -------- | --------------------------------------- |
| `media_type`          | int32       | 是       | 媒体类型                                |
| `media_id`            | string      | 否       | 文件上传时必填，CreateMedia 返回的 ID   |
| `title`               | string      | 是       | 标题                                    |
| `knowledge_base_id`   | string      | 是       | 知识库 ID                               |
| `folder_id`           | string      | 否       | 文件夹 ID（省略则添加到根目录）         |
| `note_info`           | ContentInfo | 否       | 笔记内容信息                            |
| `web_info`            | ContentInfo | 否       | 网页内容信息（media_type=2 时必填）     |
| `web_info.content_id` | string      | 条件必填 | 网页 URL（media_type=2 时必填）         |
| `session_info`        | ContentInfo | 否       | 会话内容信息                            |
| `file_info`           | FileInfo    | 否       | 文件信息（文件上传时必填，见 FileInfo） |

#### 返回字段

| 字段       | 类型   | 说明    |
| ---------- | ------ | ------- |
| `media_id` | string | 媒体 ID |

---

### 3. 获取知识库信息

POST /openapi/wiki/v1/get_knowledge_base

#### 请求参数

| 字段  | 类型     | 必填 | 说明                              |
| ----- | -------- | ---- | --------------------------------- |
| `ids` | string[] | 是   | 知识库 ID 列表（1-20 个，不重复） |

#### 返回字段

| 字段    | 类型                             | 说明           |
| ------- | -------------------------------- | -------------- |
| `infos` | map\<string, KnowledgeBaseInfo\> | 知识库信息映射 |

---

### 4. 浏览知识库内容

POST /openapi/wiki/v1/get_knowledge_list

#### 请求参数

| 字段                | 类型   | 必填 | 说明                          |
| ------------------- | ------ | ---- | ----------------------------- |
| `cursor`            | string | 是   | 游标，首次传空字符串          |
| `limit`             | uint64 | 是   | 数量限制（1-50）              |
| `knowledge_base_id` | string | 是   | 知识库 ID                     |
| `folder_id`         | string | 否   | 文件夹 ID（省略则列出根目录） |

#### 返回字段

| 字段             | 类型            | 说明             |
| ---------------- | --------------- | ---------------- |
| `knowledge_list` | KnowledgeInfo[] | 知识条目列表     |
| `is_end`         | bool            | 是否到达列表末尾 |
| `next_cursor`    | string          | 下页游标         |
| `current_path`   | FolderInfo[]    | 当前路径         |

---

### 5. 搜索知识库内容

POST /openapi/wiki/v1/search_knowledge

#### 请求参数

| 字段                | 类型   | 必填 | 说明                 |
| ------------------- | ------ | ---- | -------------------- |
| `query`             | string | 是   | 搜索关键词           |
| `cursor`            | string | 是   | 游标，首次传空字符串 |
| `knowledge_base_id` | string | 是   | 知识库 ID            |

#### 返回字段

| 字段          | 类型                    | 说明                                                                     |
| ------------- | ----------------------- | ------------------------------------------------------------------------ |
| `info_list`   | SearchedKnowledgeInfo[] | 搜索结果（`media_id`, `title`, `parent_folder_id`, `highlight_content`） |
| `is_end`      | bool                    | 是否到达列表末尾                                                         |
| `next_cursor` | string                  | 下页游标                                                                 |

---

### 6. 搜索知识库列表

POST /openapi/wiki/v1/search_knowledge_base

#### 请求参数

| 字段     | 类型   | 必填 | 说明                 |
| -------- | ------ | ---- | -------------------- |
| `query`  | string | 是   | 搜索关键词           |
| `cursor` | string | 是   | 游标，首次传空字符串 |
| `limit`  | uint64 | 是   | 数量限制（1-50）     |

#### 返回字段

| 字段          | 类型                        | 说明                                  |
| ------------- | --------------------------- | ------------------------------------- |
| `info_list`   | SearchedKnowledgeBaseInfo[] | 搜索结果（`id`, `name`, `cover_url`） |
| `is_end`      | bool                        | 是否到达列表末尾                      |
| `next_cursor` | string                      | 下页游标                              |

---

### 7. 获取可添加的知识库列表

POST /openapi/wiki/v1/get_addable_knowledge_base_list

**触发场景**：用户想上传文件或添加内容到知识库，但不确定可以添加到哪些知识库时，列出当前用户有权限添加内容的知识库。

#### 请求参数

| 字段     | 类型   | 必填 | 说明                 |
| -------- | ------ | ---- | -------------------- |
| `cursor` | string | 是   | 游标，首次传空字符串 |
| `limit`  | uint64 | 是   | 数量限制（1-50）     |

#### 返回字段

| 字段                          | 类型                       | 说明                   |
| ----------------------------- | -------------------------- | ---------------------- |
| `addable_knowledge_base_list` | AddableKnowledgeBaseInfo[] | 可添加内容的知识库列表 |
| `next_cursor`                 | string                     | 下页游标               |
| `is_end`                      | bool                       | 是否到达列表末尾       |

---

### 8. 检查文件名重复

POST /openapi/wiki/v1/check_repeated_names

**触发场景**：上传文件到知识库前，检查目标知识库（及文件夹）中是否已存在同名文件。仅用于文件类型（media_type 1/3/4/5/7/9/13/14），不用于网页（2/6）、笔记（11）等。

#### 请求参数

| 字段                | 类型                      | 必填 | 说明                          |
| ------------------- | ------------------------- | ---- | ----------------------------- |
| `params`            | CheckRepeatedNamesParam[] | 是   | 待检查的文件列表（1-2000 个） |
| `knowledge_base_id` | string                    | 是   | 知识库 ID                     |
| `folder_id`         | string                    | 否   | 文件夹 ID（省略则检查根目录） |

**CheckRepeatedNamesParam：**

| 字段         | 类型   | 说明                          |
| ------------ | ------ | ----------------------------- |
| `name`       | string | 文件名称                      |
| `media_type` | int32  | 媒体类型（见 MediaType 枚举） |

#### 返回字段

| 字段      | 类型                       | 说明     |
| --------- | -------------------------- | -------- |
| `results` | CheckRepeatedNamesResult[] | 检查结果 |

**CheckRepeatedNamesResult：**

| 字段          | 类型   | 说明                      |
| ------------- | ------ | ------------------------- |
| `name`        | string | 文件名称                  |
| `is_repeated` | bool   | `true` 表示同名文件已存在 |

---

### 9. 导入 URL

POST /openapi/wiki/v1/import_urls

**触发场景**：添加网页或微信公众号文章到知识库。替代 `add_knowledge` 的 `media_type=2/6` 用法，支持批量导入，服务端自动识别 URL 类型。

#### 请求参数

| 字段                | 类型     | 必填 | 说明                                |
| ------------------- | -------- | ---- | ----------------------------------- |
| `knowledge_base_id` | string   | 是   | 知识库 ID                           |
| `folder_id`         | string   | 是   | 文件夹 ID                           |
| `urls`              | string[] | 是   | URL 列表（1-10 个，每个非空字符串） |

#### 返回字段

| 字段      | 类型                         | 说明                                      |
| --------- | ---------------------------- | ----------------------------------------- |
| `results` | map\<string, ImportURLData\> | URL→结果映射（含 `ret_code`、`media_id`） |

---

## 文件夹说明

知识库内容以文件夹层级结构组织。文件夹是一种特殊的知识条目：

- `get_knowledge_list` 返回结果中同时包含 **文件**（`KnowledgeInfo`）和 **文件夹**（`FolderInfo`），通过 `current_path` 字段可获取当前路径的面包屑信息
- `search_knowledge` 搜索结果中也会包含匹配的文件夹
- 所有支持 `folder_id` 参数的接口（`add_knowledge`、`import_urls`、`get_knowledge_list`、`check_repeated_names`），省略 `folder_id` 则操作根目录。**根目录的 folder_id 等于 knowledge_base_id**，当接口要求 `folder_id` 必填时（如 `import_urls`），传 `knowledge_base_id` 的值即可表示根目录
- **定位文件夹**：当用户只提供文件夹名称时，使用 `search_knowledge` 按名称搜索，或用 `get_knowledge_list` 逐级浏览，从返回结果中找到目标文件夹的 ID

---

## 文件大小限制

上传前必须校验文件大小，超限文件应在上传前拦截：

| 文件类型                    | media_type  | 最大大小 |
| --------------------------- | ----------- | -------- |
| Excel、TXT、Xmind、Markdown | 5/13/14/7   | 10 MB    |
| 图片                        | 9           | 30 MB    |
| PDF、Word、PPT、音频及其他  | 1/3/4/15 等 | 200 MB   |

网页（2/6）、笔记（11）等非文件类型无大小限制。音频文件额外限制：最长 2 小时。

---

## 响应格式

所有 API 返回统一结构：

```json
{
  "retcode": 0,
  "errmsg": "成功",
  "data": { ... }
}
```

- `retcode=0`：成功，从 `data` 提取业务字段
- `retcode≠0`：失败，**直接将 `errmsg` 展示给用户**，无需自行翻译错误码

---

## 游标翻页使用规范

1. **首次请求**：`cursor` 传空字符串 `""`
2. 检查返回的 `is_end`：`false` 表示还有更多数据
3. 将返回的 `next_cursor` 作为下次请求的 `cursor`
4. `is_end = true` 时停止翻页

---

## 错误码

| 错误码 | 说明         | 建议处理                    |
| ------ | ------------ | --------------------------- |
| 0      | 成功         | —                           |
| 110001 | 参数非法     | 检查请求参数（详见 errmsg） |
| 110002 | 配置非法     | 检查服务配置                |
| 110010 | 下游网络错误 | 可重试                      |
| 110011 | 下游逻辑错误 | 不可重试，详见 errmsg       |
| 110012 | 接口无效     | 检查接口路径                |
| 110013 | 客户端取消   | 检查请求是否超时            |
| 110020 | 安全打击     | 检查内容是否违规            |
| 110021 | 请求频控     | 降低请求频率后重试          |
| 110030 | 无权限       | 确认操作权限                |