技能介绍

要解决什么问题

在 Agent 里直接帮用户「记笔记」「往知识库丢文件」「搜知识库里的材料」时，很容易把 笔记内容操作 和 知识库条目管理 混在一起：例如用户说「写到知识库 XX 里的笔记 YY」，实际应走 notes 的 append_doc，而不是把整段文字当成知识库上传。另一类坑是 写入乱码：import_doc / append_doc 要求 content、title 为合法 UTF-8，非法字节会在 IMA 侧变成不可恢复的乱码；在 PowerShell 5.1 下即设了 charset=utf-8，请求体仍可能被静默转成 GBK。

技能如何工作

本技能是 统一的 IMA OpenAPI 入口，当前覆盖两块子能力，由意图路由到对应子模块说明（notes / knowledge-base）：

notes：搜索与浏览笔记本、读笔记、import_doc 新建、append_doc 追加
knowledge-base：文件上传（create_media → COS → add_knowledge）、网页链接、知识库搜索与浏览、add_knowledge 把已有笔记关联进库；需要 media_id 时的「查看/分析/导出原文」也走此模块（笔记型媒体会再跨到 notes 取正文）

调用前会检查 ~/.config/ima/ 下的 Client ID 与 API Key（或环境变量），缺失则引导去 ima.qq.com 代理接口配置。实际请求经 ima_api.cjs 以 HTTP POST + JSON 发往 https://ima.qq.com；错误分两层：进程非零（如 -100 凭证/参数、-200 需更新技能）看 stderr，业务结果看 stdout 里 code / msg。

跨模块任务（如「把知识库内容记到笔记」「把笔记加到知识库」「查看知识库里笔记型媒体的原文」）要求 先读两个子模块 SKILL 再按顺序执行，避免只加载一半 API 就动手。

适用边界与注意点

文件上传：title 必须与 file_name（含扩展名）一致，二进制文件不得转码；视频、B 站/YouTube 链接、file:// 等 不支持，应提示用 IMA 桌面客户端。
意图不清时（「帮我记一下」但未说明新建还是追加到哪篇）应先向用户确认，而不是默认创建或追加。
凭证仅作为 HTTP 头发往 ima.qq.com；运行时依赖见技能 meta.json 中的 required_binaries。