ima-mcp

---
name: ima-mcp
description: ima - 腾讯AI知识管家个人版，用于搜索、读取和写入个人账号下的知识库（含"问我的知识库"、"个人知识库"、"我存过的资料"、"存进 ima"、ima.qq.com），并可搜索和订阅教育、法律、财经、科技等20+行业专业知识。
version: "1.0.0"
author: "Tencent IMA"
homepage: https://ima.qq.com
---

# ima 使用指南

> 本 skill 面向 **ima**（`ima.qq.com`），操作对象是当前用户**个人账号**下可访问的知识库，数据归属个人账号。
> 工具由 `ima-mcp` 连接器的 MCP Server 提供。

## 最高优先级：多连接器时的写操作

只要当前会话**连了多个** IMA 连接器，凡创建、上传、导入、入库、删除等写入 / 修改操作：

- 用户**明确表示**使用「司内版 IMA / ima 司内版 / ima（司内版）」：可直接用 ima（司内版）（`ima-mcp-oa`）写入，不必再问。
- **其余情况**（未指定、只说了 ima、说了个人版等）：**必须先交互式询问用户**选择哪一个已连接的连接器，等用户明确确认后再动手。不得自行猜测、默认某一边，也不得先写再补问。

只说「ima」不算明确指定司内版。只连了一个 IMA 连接器时，写操作直接用这一个，不必再问。这条优先于后文所有选型与编排规则。

## 🚨 工具清单以服务端为准

本 skill **不冻结工具名与参数**。可用工具及其参数 schema 在连接器建连时由 MCP `tools/list` 实时下发，
一律以当前会话中实际可见的 `ima-mcp` 工具为准。

- 本文档只按**能力类别**描述该做什么（查库 / 查内容 / 读内容 / 入库），**不列举工具名**。
  实际有哪些工具、叫什么、收什么参数，全部以 `tools/list` 下发的为准。
- 按工具自带的 `inputSchema` 构造参数，**严禁凭本文档或记忆猜测工具名 / 参数名**。
- 某个类别下没有对应工具时，直接向用户说明该能力暂不支持；不要拿近似工具凑合，更不要臆造调用。
- 本文档只写 `tools/list` 表达不了的部分：**该不该用本 skill、多工具编排顺序、禁令、失败处置**。

## 能力边界

| 能力类别 | 说明 |
|---|---|
| 查库 | 列举当前账号可访问的知识库（可按"我的 / 共享 / 订阅"等类型分别分页）；库多时可按关键词搜库，匹配名称、描述、创建者昵称；写入前另有"可添加（可写入）知识库"的专门列表 |
| 查内容 | 列举某个知识库或文件夹下的条目（支持排序、过滤、分页）；在某个知识库内按 query 检索 |
| 读内容 | 读取单个条目的正文，按分片顺序返回 |
| 入库 | 批量导入网页链接；本地文件走"创建 media → 上传 → 入库"的多步流程 |

**边界之外**：没有对已有条目的修改、重命名、移动、删除工具，也没有知识库本身的创建与管理。
用户提这类需求时如实说明当前连接器不支持，引导其到 ima 客户端或 `ima.qq.com` 操作，不要用别的工具硬凑。

## 用哪个连接器：ima / ima（司内版）

`ima-mcp`（ima）与 `ima-mcp-oa`（ima（司内版））**功能完全相同、工具集一致**，
区别只在账号与数据归属：前者是个人账号，后者是企业账号（含 iOA 账号）且数据受企业管控。
但两者是独立连接器，**授权账号不同，能看到、能写入的知识库就不同，选错等于查了或写进了另一个账号的资料**。

「当前连了几个」以本会话里**实际已连接、工具可见**的 IMA 连接器为准（`ima-mcp`、`ima-mcp-oa`），不要按安装清单臆测。

点名只认「ima / 个人版知识库」与「司内版 IMA / ima 司内版 / ima（司内版） / 司内版」。旧称「ima知识库个人版」「ima知识库企业版 / 企业版知识库」仍分别对应两边。「个人知识库」「团队知识库」「公司知识库」「我的 ima」等**不算**点名，按未指定处理。用户同时提到「ima」和「司内版」时，按 ima（司内版）处理。写操作里，只有明确点了司内版才能直接写；只点「ima」仍要先问。

| 情形 | 怎么做 |
|---|---|
| **连了多个** IMA 连接器，写操作，且用户**明确表示**使用司内版 IMA / ima 司内版 / ima（司内版） | 直接用 `ima-mcp-oa` 写入；若未连接，请用户在 WorkBuddy 设置页先连接 |
| **连了多个** IMA 连接器，写操作，且用户未明确指定司内版 | **必须先交互式询问用户**选择哪一个已连接的连接器，确认后再动手。只说「ima」也要问，不得默认、不得先写再补问 |
| 当前会话**只连了一个** IMA 连接器 | 读、写都直接用这一个，不必再问、也不必去找另一个 |
| **连了多个** IMA 连接器，只读，且用户**明确指定** ima / 个人版知识库 | 只用 `ima-mcp`；若未连接，请用户在 WorkBuddy 设置页先连接 |
| **连了多个** IMA 连接器，只读，且用户**明确指定** ima（司内版） / 司内版 | 只用 `ima-mcp-oa`；若未连接，请用户在 WorkBuddy 设置页先连接 |
| **连了多个** IMA 连接器，只读，且用户未指定 | **每个已连接的 IMA 连接器都查**，汇总结果并标明来自哪一边。不得只查一边就断言"没有" |

> 注意："共享知识库"不是判据——个人账号下也有共享给自己的库（`KBT_SHARED_KB`）。写操作先看连了几个；只读操作再看用户是否点名。

## 前置：鉴权

授权由 WorkBuddy 的 `ima-mcp` 连接器完成，本 skill 不处理登录流程，也不读写任何凭证。

- 工具返回鉴权失败（401 / 票据过期类错误）时，提示用户在 WorkBuddy 设置页重新连接 **ima**，不要反复重试刷屏。
- 连接器未连接时，不要尝试直连 `ima.qq.com` 网页或猜测 HTTP API 绕行。

## 编排：读取链路

工具之间有明确的 ID 依赖，**顺序不能跳**：

1. **查库** → 拿到 `knowledge_base_id`。
   知识库类型枚举：`KBT_MINE_KB`（我的）、`KBT_SHARED_KB`（共享）、
   `KBT_SUBSCRIBED_CREATE_KB`（订阅-我创建的）、`KBT_SUBSCRIBED_JOIN_KB`（订阅-我加入的）。
   用户没指定范围时把相关类型一并带上，别只查"我的"就断言"没有"。
   用户也没点名 ima / ima（司内版）时：只连了一个 IMA 连接器就只查当前这一个；**连了多个则同一套查库步骤要在每个已连接的连接器上都跑一遍**，再汇总。
   用户点名了库名（"我那个读书笔记库"）就用搜库能力直接定位，不要全量翻页硬找。
2. **查内容** → 拿到条目的 `media_id`。
   明确知道要什么就用检索（必传知识库 ID + query）；用户只是想"看看存了什么"就用列举，
   排序推荐 `UPDATE_TS_DESC_SORT_TYPE`（更新时间倒序）。
3. **读内容** → 传上一步的 `media_id` 取正文。
   条目标题、摘要不足以支撑回答时必须读正文，不要只凭标题猜内容。

要点：

- **`knowledge_base_id` 必须来自第 1 步的返回**，不要凭用户口述的库名当 ID，也不要编造。
- **一次只查一个库**：检索与列举都是单库接口。用户要跨库找，就对候选库分别调用后自己汇总，并说明查了哪些库。
- **`media_id` 必须来自第 2 步的返回**，不要跨库复用或拼接。
- **分页靠 `cursor`**：首次传空，后续用上一次返回的游标续拉。用户要"全部 / 一共多少"时才翻页，
  且翻页要有节制，够回答就停，别把整个库拖下来。

## 编排：写入链路

1. **先确认连接器，再定位可写入的库**：多连接器写操作选型详见上文「最高优先级：多连接器时的写操作」与「用哪个连接器」。
   写入前用"可添加知识库"列表确认目标库，**不要拿可访问列表里的库直接写**——能看见不等于能写入。
   用户没指明目标库且可写库不止一个时，先交互式询问用户选择哪个库，不要默认塞进第一个。
2. **网页链接**：批量能力要用足，多个 URL **一次提交**，严禁一条一调循环。
   URL 由服务端抓取，本地不必先下载网页。
3. **本地文件**：走"创建 media → 按返回凭证上传文件 → 入库"的多步流程，**三步缺一步都不算入库成功**。
   只创建了 media 却没走完后续步骤时，不要向用户报告"已存入知识库"。
4. **导入是异步的**：入库成功只代表资料已收下，解析要时间。
   刚导入就检索往往查不到，要么如实告知用户稍后再问，要么先看条目的解析状态。

## 过滤与降噪

列举和检索共用 `filters`，每个 filter 要同时给 `filter_type` 和对应子字段，常用组合：

| 目的 | 怎么写 |
|---|---|
| 只看能读的内容 | `MEDIA_STATE_FILTER_TYPE` + `media_state_filter.media_states: ["MEDIA_PARSE_SUCCESS"]` |
| 不把文件夹混进结果 | `MEDIA_TYPE_FILTER_OUT_TYPE` + `media_type_filter_out.media_type: ["FOLDER"]` |
| 只看某类资料（如只看 PDF） | `MEDIA_TYPE_FILTER_TYPE` + `media_type_filter.media_type: ["PDF"]` |
| 按标签收窄 | `TAGS_FILTER_TYPE` + `tags_filter.tags: [...]` |

- 默认建议叠加前两条：**只要解析成功的、排除文件夹**，否则结果里会混入读不出正文的条目。
- 解析状态取值：`MEDIA_INIT` / `MEDIA_PARSING` / `MEDIA_PARSE_SUCCESS` / `MEDIA_PARSE_ERROR` / `MEDIA_PARSE_TIMEOUT`。
  命中 `MEDIA_PARSING` 说明资料还在解析，如实告知用户"稍后再试"，不要当成不存在。
- 资料类型取值：`PDF` / `WEB` / `WORD` / `PPT` / `EXCEL` / `WECHAT_ARTICLE` / `MARKDOWN` / `IMG` / `NOTE` /
  `SESSION` / `TXT` / `XMIND` / `SOUND_RECORDING` / `WEB_VIDEO` / `PODCAST` / `FOLDER`。
  用户说"我的笔记"对应 `NOTE`，"公众号文章"对应 `WECHAT_ARTICLE`，"网页 / 收藏的链接"对应 `WEB`。
- 想进文件夹就带 `folder_id`（同样来自列举返回），不要把文件夹名当 ID 传。

## 核心规则

- **先检索再回答**：凡涉及"我存过的 / 我的资料 / 我之前看过"类问题，必须先调知识库工具取证，严禁直接用模型知识作答。
- **答案要给来源**：附上命中条目的标题（有链接则给链接），便于用户核实。
- **空结果不补**：检索为空时明确告知"知识库里没有相关内容"，不要用模型知识补足并冒充检索结果；
  可以建议换关键词或换个知识库再试。
- **别过度调用**：先用检索收窄，再对少量高相关条目读正文，不要把列举到的条目逐条拉全文。
- **写操作先选连接器**：多连接器选型详见上文「最高优先级：多连接器时的写操作」与「用哪个连接器」。目标库或导入内容有歧义时同样先确认再动手。
- **入库要复述结果**：告诉用户存进了哪个库、成功几条、失败几条，不要笼统说"已处理"。

## 失败处置

先分清两类错误，处置方式相反：

- **工具执行错误**：结果带 `isError: true`。工具跑了但没成（鉴权过期、无权限、参数语义不合法、后端报错），
  错误文本可读，**据此纠正后可重试一次**。
- **协议错误**：返回 JSON-RPC `error` 而非结果。请求根本没跑起来（未知工具、不符合 schema、服务端故障），
  **重试同样的调用没有意义**。

> 别按数字码硬编码判断分支——各服务端对码值的用法并不统一，以 `message` 文本为准。

| 现象 | 处置 |
|---|---|
| 鉴权失败 / 票据过期 | 引导用户在 WorkBuddy 重新连接 **ima** 连接器，不要反复重试 |
| 无权访问该知识库 | 说明当前账号无权限，不要绕行，也不要换个工具重试同一请求 |
| 无权写入该知识库 | 改从"可添加知识库"列表里选目标库，不要对同一个库反复重试写入 |
| `knowledge_base_id` / `media_id` 无效 | 重新走一遍"查库 → 查内容"拿到有效 ID，不要凭记忆拼 ID |
| 正文为空或读不出 | 检查条目解析状态：仍在解析就告知稍后再试，解析失败则说明该条目无法读取 |
| 批量导入部分失败 | 只对失败项重试一次，不要整批重提造成重复入库；仍失败则把失败清单告诉用户 |
| 参数不合法（错误文本指明了字段） | 按提示修正参数重试一次，不要连续试错 |
| 未知工具 / 方法不存在 | 说明当前连接器未提供该能力，不要换近似工具硬调 |
| 服务端故障 / 超时 / 限频 | 退避后重试一次，仍失败则告知用户稍后再试 |