技能介绍

要解决什么问题

在 Agent 里直接操作腾讯 IMA（ima.qq.com）时，笔记与知识库走的是两套 API 语义：前者关心文档内容的读写与追加，后者关心媒体上传、网页入库和条目检索。用户口语里常把「写到知识库里的某篇笔记」和「把笔记挂进知识库」混在一起，若路由错了就会调错模块或改错资源。

此外，笔记写入对 UTF-8 有硬性要求；在 PowerShell 5.1 下默认会把 JSON Body 静默转成 GBK，中文正文会在服务端变成不可恢复的乱码。知识库侧则要区分「上传二进制文件」与「把已有笔记关联为知识库条目」，文件名与 title 必须一致且不得擅自改名。

技能如何工作

本技能是统一的 IMA OpenAPI 入口，当前覆盖 notes 与 knowledge-base 两个子模块。Agent 先根据用户意图对照决策表：目标是笔记内容 → notes/SKILL.md；目标是知识库条目、上传、链接或需要 media_id 的原文 → knowledge-base/SKILL.md。若意图横跨两域（例如从知识库取内容再记笔记、或把笔记 add_knowledge 入库），必须先读完两个子模块文档再按顺序调用。

所有请求经 ./ima_api.cjs 以 HTTP POST + JSON 发往官方 Base URL。调用前会检查 ~/.config/ima/client_id 与 api_key（或等价环境变量）。错误分两层：进程非零退出时看 stderr（如 -100 凭证/参数问题、-200 需更新 skill）；进程成功时解析 stdout 里 code/msg，code≠0 直接把业务 msg 给用户。

边界与注意点

notes 写入（import_doc / append_doc）：写入前必须校验并转换 content、title 为合法 UTF-8；这不适用于知识库文件上传，二进制须原样上传。
不支持的输入：视频、Bilibili/YouTube 链接、file:// 等应明确拒绝，引导用户使用 IMA 桌面客户端。
易混淆话术：「追加到某篇笔记」走 notes；「上传文件到知识库」走 knowledge-base 的 create_media → COS → add_knowledge；仅说「记一下」且未指定笔记时，应先确认新建还是追加。
凭证仅作为 HTTP 头发往 ima.qq.com，更新检查默认每天首次 API 调用触发一次，-200 时原请求未发送，需按 instruction 更新后重试。