在开发对接腾讯 IMA（ima-skill）的 LLM Agent 时，开发者面临的核心挑战往往不是 API 的调用，而是自然语言的精准路由。

用户的一句“帮我把这个记到知识库里”，底层究竟该对应 notes 模块的 import_doc，还是 knowledge-base 模块的 add_knowledge？面对这种多意图、易混淆、甚至跨模块的复杂长文本请求，如果路由策略设计不当，Agent 就会高频出现“答非所问”或执行报错。

本文将为你深度拆解 ima-skill 对接中的易混淆意图路由表、跨模块级联机制以及终极判定红线。

一、 易混淆场景：用户意图与 API 路由精密对照表

用户在日常对话中的表述往往是模糊或有交叉的，Agent 必须通过“意图槽位填充”和语义分析，将其精准路由到对应的原子 API。以下是标准路由矩阵：

二、 🧠 跨模块任务（Cross-Module）：双子模块级联读取机制

这是 Agent 联网中最容易翻车的地方。某些复合型任务的执行链路横跨 notes 与 knowledge-base。

🛑 铁律：Agent 绝对不能只读取单模块的 SKILL.md 就盲目开始执行。一旦识别到跨模块任务，必须严格按照业务流顺序，级联读取两个模块的 SKILL.md，完成上下文注入后再按序执行。

1. 经典跨模块场景执行流对照

• 场景 A：“把知识库里的 XX 内容记到笔记”

  • 底层逻辑：知识库搜索/读取 $\rightarrow$ 笔记创建/追加

  • 读取顺序：先读 knowledge-base/SKILL.md $\rightarrow$ 再读 notes/SKILL.md

• 场景 B：“查看/分析原文”（且该媒体在知识库中是“笔记”类型）

  • 底层逻辑：知识库获取媒体元数据 $\rightarrow$ 发现是笔记 $\rightarrow$ 转向笔记模块拉取内容

  • 读取顺序：先读 knowledge-base/SKILL.md $\rightarrow$ 再读 notes/SKILL.md（调用 get_doc_content）

• 场景 C：“把这篇笔记添加到知识库”

  • 底层逻辑：笔记模块搜索获取 note_id $\rightarrow$ 知识库模块执行关联

  • 读取顺序：先读 notes/SKILL.md $\rightarrow$ 再读 knowledge-base/SKILL.md

2. 级联触发触发器的判定规则

1. 用户语义显式涉及「笔记」和「知识库」两个实体。

2. 动态触发：API 响应中（例如获取知识库媒体信息时）返回 media_type=11（表示该媒体底层是笔记类型），此时 Agent 必须立刻动态补读 notes/SKILL.md。

三、 Agent 架构师的黄金判定红线（Core Rules）

为了在 Prompt Engineering 中写出坚固的 System Prompt，你可以直接套用以下 4 条核心硬核判定规则：

Plaintext

       [用户自然语言 Prompt 输入]
                  │
                  ▼
         ┌─────────────────┴─────────────────┐
         ▼                                   ▼
   【核心判定：真正操作对象是谁？】        【提取原始内容？】
         │                                   │
         ├─► 读/写/追加笔记内容 ──► notes模块   └─► 查看/分析/导出原文 ──► knowledge-base模块
         │                                                    │ (若media_type=11)
         ├─► 上传/关联知识库条目 ──► KB模块                     ▼
         │                                              跨模块至 notes.get_doc_content
         └─► "知识库里的[那篇笔记]" 
                 (知识库仅作修饰限定)
                     │
                     ▼
                 notes 模块

1. 内容驱动归 notes：只要用户动作的目标是笔记的内容（无论是读、写、还是追加），无脑路由到 notes 模块。

2. 条目驱动归 knowledge-base：只要用户动作的目标是知识库的整体条目资产（如上传新文件、添加外链、将已有笔记挂载进知识库），无脑路由到 knowledge-base 模块。

3. 溯源驱动归 knowledge-base（带级联预警）：只要用户的目标是获取知识库现有条目的原始内容（查看、分析、导出原文），优先进入 knowledge-base 模块。但注意：如果解析出原文底层是笔记（media_type=11），必须走跨模块级联，最终使用 notes.get_doc_content 提取。

4. 排除“限定修饰语”干扰：当用户提到“知识库”仅仅是作为笔记的位置修饰（如：“帮我把知识库里的那篇周报笔记导出来”），真正的操作对象依然是笔记实体，此时应果断路由到 notes 模块，切忌被“知识库”三个字误导。

四、 总结：如何优雅地在代码中实现这个 Router？

在工程落地时，我们可以通过一个简单的轻量级“前置 Router 状态机”来实现这一逻辑，先进行语义实体提取，再决定 SKILL 注入。

通过 “意图清晰看目标，意图模糊提反问，跨模块级联读，修饰语中抓核心” 这四套心法，你的 Agent 将在腾讯 IMA 的开放技能生态中表现出极高的智商与稳定性。