Ima MCP

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、多工具编排顺序、禁令、失败处置。

能力边界

边界之外：没有对已有条目的修改、重命名、移动、删除工具，也没有知识库本身的创建与管理。 用户提这类需求时如实说明当前连接器不支持，引导其到 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」仍要先问。

注意："共享知识库"不是判据——个人账号下也有共享给自己的库（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_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 文本为准。