IMA 笔记与知识库 OpenAPI

要解决什么问题

在 Agent 里直接操作腾讯 IMA（笔记与知识库）时，常见痛点是：用户说法混用「笔记」「知识库」「上传」「记一下」，容易走错 API；写入笔记若编码或 PowerShell 5.1 请求体处理不当，会在 IMA 端出现不可逆乱码；文件上传还有命名与类型限制，误操作只会浪费一次写入。

本技能把 IMA 开放接口收敛为统一入口，并通过模块决策表把意图路由到 notes 或 knowledge-base 子模块，而不是凭关键词猜一个端点就发请求。

技能如何工作

• 双模块分工：目标是笔记内容（读、写、追加）→ notes；目标是知识库条目（上传文件、加链接、把笔记关联进库）→ knowledge-base；「查看/分析/导出原文」走知识库侧，若媒体类型是笔记则再跨到 notes 取正文。
• 跨模块任务：例如「把知识库里的内容记到笔记」「把笔记添加到知识库」必须先读两个子模块的 SKILL.md，再按固定顺序调用（先搜/读源，再写/关联）。
• 凭证：调用前检查 ~/.config/ima/client_id 与 api_key（或环境变量）；缺失时引导用户从 https://ima.qq.com/agent-interface 配置，凭证仅作为 HTTP 头发往 ima.qq.com。
• 请求与错误：统一经 ./ima_api.cjs 向官方 Base URL 发 POST + JSON；需同时看进程退出码（如 -100 程序错误、-200 需更新技能）与 stdout 里 code 是否为 0。

边界与注意点

• notes 写入：import_doc / append_doc 前必须保证 content、title 等为合法 UTF-8；这是强制规则，非法字节会导致乱码且难以修复。
• 文件上传：title 必须等于含扩展名的 file_name，二进制文件不得转码；视频、B 站/YouTube 链接、file:// 等不支持，应提示用户改用 IMA 桌面客户端。
• 易混淆表述：「写到 XX 笔记里」是追加笔记；「把笔记添加到知识库」是关联操作，不是新建笔记正文。意图不明确时应先问清是新建还是追加到哪篇笔记。