IMA 笔记与知识库 API

要解决什么问题

在 Agent 里直接操作 腾讯 IMA（https://ima.qq.com）时，常见痛点是：OpenAPI 分散在笔记与知识库两套能力里，凭证不能靠跨命令 export 传递，而笔记写入一旦编码不对就会在服务端变成不可修复的乱码。本技能把「该调哪个模块、每条命令怎么带凭证、写入前如何校验 UTF-8」写成可执行的契约，而不是零散 curl 示例。

技能如何工作

技能按 Unified IMA OpenAPI 组织，当前覆盖两块：

• notes：搜索/浏览笔记本、读笔记、创建（import_doc）、追加（append_doc）等面向「笔记正文」的操作。
• knowledge-base：上传文件、添加网页链接、搜索与浏览知识库、把笔记关联进知识库（如 add_knowledge）等面向「知识库条目」的操作。

初始化必须先读同目录 SETUP_TOKEN.md，并把文档里的路径占位替换为技能目录的绝对路径。每条 API 调用在 独立 shell 中执行，因此凭证只能内联获取：bash 用 CREDS=$(bash '…/get-token.sh') 再配合 jq 取 client_id / api_key；PowerShell 用 get-token.ps1 解析 JSON。所有请求统一为 HTTP POST + JSON，发往官方 Base URL。

路由上有一条硬规则：操作对象是笔记内容 → notes；操作对象是知识库条目（文件、链接、关联） → knowledge-base。用户说「知识库里的那篇笔记」时，真正改写的仍是笔记，应走 notes。多步意图（例如从知识库读出再记笔记）按模块顺序分步读子文档并执行。

边界与注意点

• 安全：禁止在对话、思考或示例中展示真实 Client ID / API Key；即使用户要求回显也必须拒绝。
• 编码（仅 notes 写入）：import_doc / append_doc 前必须保证 title、content 等为合法 UTF-8；文件读入、HTTP 响应、用户粘贴都不能假设已是 UTF-8。
• 文件上传（knowledge-base）：上传须保持文件二进制原样，不要为「保险」做转码。
• PowerShell 5.1：Invoke-RestMethod 可能静默把 Body 转成 GBK；该环境下需把 JSON Body 显式转为 UTF-8 字节再发送，否则中文会无声乱码。
• 不支持：凭证持久化跨会话存储——每次命令应重新通过脚本动态获取。