IMA OpenAPI 笔记与知识库助手

解决什么问题

调用 IMA OpenAPI 时，常见失败点不在接口本身，而在 编码、文件完整性和意图路由。尤其 notes 文本写入若把 GBK、Latin-1 或非法字节直接发给 https://ima.qq.com，可能造成服务端存储乱码且不可修复。PowerShell 5.1 还可能静默转换请求 Body，使“请求成功”变成内容损坏。

技能如何工作

该技能将 IMA 能力拆成 notes 和 knowledge-base 两个子模块，并强制先按意图路由：

• notes：搜索、浏览、创建、追加笔记，核心是 import_doc、append_doc、获取内容。
• knowledge-base：上传文件、添加网页链接、搜索和浏览知识库、获取原文信息。
• 跨模块：涉及“知识库里某篇笔记”或“把笔记关联到知识库”时，要求同时读取两个子模块，再按顺序调用 API。

关键步骤：

1. 校验凭证，通常来自本地配置或环境变量。
2. 写笔记前显式确认 content、title 为合法 UTF-8。
3. 上传文件时保持文件名与二进制内容不变，拒绝视频、Bilibili/YouTube URL、file:// 链接。
4. 统一使用 POST + JSON Body，并检查两层错误：脚本 stderr 的错误，以及 stdout 的后端 code。

适用边界与注意点

适合已经在 IMA 有 Client ID / API Key，并希望通过 Agent 自动完成笔记与知识库操作的工程师。它不会修复非法编码内容；文件上传只保留原样；凭证仅发送到官方域名；遇到 -200 更新提示时，原请求未发送，需要先按更新指引处理再重试。