IMA 笔记与知识库 OpenAPI

要解决什么问题

如果你在 Agent 里要操作腾讯 IMA（ima.qq.com）的笔记或知识库，直接拼 HTTP 接口很容易踩坑：笔记写入乱码、PowerShell 5.1 静默把 JSON Body 转成 GBK、把「追加到某篇笔记」和「把笔记挂进知识库」混成一条 API 路径，或者在上传 PDF/图片时误做文本转码。

本技能把 IMA OpenAPI 收敛成统一入口，用模块决策表把用户意图路由到 notes 与 knowledge-base 两套子能力，并在跨场景（例如知识库里的笔记类型媒体要「查看原文」）时强制先读两个子模块再按顺序调用。

技能如何工作

• 凭证：在首次调用前检查 ~/.config/ima/client_id 与 api_key（或环境变量）；缺失则引导用户从 IMA Agent 接口页获取，再调用 ./ima_api.cjs 以 POST + JSON 访问官方 Base URL。
• notes：搜索/浏览笔记本、创建笔记（import_doc）、向已有笔记追加（append_doc）；写入前对所有字符串字段做强制 UTF-8 校验。
• knowledge-base：文件上传（create_media → COS → add_knowledge）、网页链接、搜索与浏览知识库、关联已有笔记（media_type=11 等）；二进制文件保持原样上传，title 必须与原始 file_name（含扩展名）一致。
• 错误处理：区分脚本层（stderr，如 -100 缺凭证、-200 需更新技能）与业务层（stdout 中 code/msg）；业务失败直接把 msg 给用户。

边界与注意点

不支持视频、B 站/YouTube 链接、file:// 等——应提示用 IMA 桌面客户端。不支持的文件类型应明确拒绝，不要让用户「强行试一次」。用户只说「记一下」「添加到笔记」但未指明新建还是追加时，应先确认意图，避免误写。