IMA 统一笔记与知识库 API

解决笔记与知识库管理的复杂性

当开发者集成腾讯 IMA 的笔记和知识库功能时，常面临 API 调用分散、数据编码问题以及跨模块操作的复杂性。例如，笔记写入时 UTF-8 编码处理不当会导致不可逆乱码；文件上传必须严格匹配标题与文件名；笔记和知识库模块间的交互需要准确路由，否则易引发混淆。ima-skills 技能通过统一 OpenAPI 层简化这些操作，减少开发者的重复配置和错误排查。

核心能力与关键步骤

ima-skills 技能支持两个核心模块：notes 和 knowledge-base。核心能力包括：

• 笔记模块操作：通过 import_doc 和 append_doc API 实现笔记的创建、内容追加，支持搜索、浏览和内容获取。
• 知识库模块操作：通过 create_media、add_knowledge 等 API 实现文件上传、网页链接添加、知识库搜索及信息查询。
• 跨模块协调：对于涉及笔记和知识库的任务，如将知识库内容记录到笔记，技能会先读取 knowledge-base/SKILL.md 再读取 notes/SKILL.md，并按流程执行。

关键步骤如下：

1. 凭证检查：首先验证配置文件 ~/.config/ima/client_id 和 api_key 是否存在，若缺失则引导用户设置，避免 API 调用失败。
2. 意图路由：根据用户输入，通过决策表判断使用 notes 或 knowledge-base 模块。例如，用户说“上传文件到知识库”路由到 knowledge-base，“新建笔记”路由到 notes。
3. API 调用：所有请求通过 ima_api.cjs 脚本发送，统一使用 HTTP POST 和 JSON Body，目标地址为 https://ima.qq.com。
4. 错误处理：分两层检查错误——脚本执行错误（如退出码 -100 表示程序错误，-200 表示需更新）和后端业务错误（如 code≠0），直接向用户反馈 msg 内容。
5. 更新检查：默认每天首次调用时自动检查技能更新，确保使用最新版本，更新后重试原请求。

注意事项与适用边界

使用 ima-skills 时，必须遵守以下强制规则以避免操作失败：

• UTF-8 编码校验：在调用 import_doc 或 append_doc 前，所有字符串字段（如 content、title）必须验证为合法 UTF-8，尤其在文件读取、WebFetch 抓取或用户输入场景。
• 文件上传规则：上传时标题必须等于文件名（带扩展名），不得重命名；不支持视频文件、Bilibili/YouTube URL 等，需立即拒绝并建议使用 IMA 桌面客户端。
• PowerShell 兼容性：在 PowerShell 5.1 环境中，请求 Body 会静默转为 GBK 编码，必须检测版本并使用 UTF-8 字节数组模式发送。
• 模块决策清晰：正确区分用户意图，例如“把笔记添加到知识库”实际操作是关联笔记到知识库，走 knowledge-base 模块的 add_knowledge。
• 跨模块任务执行：当用户意图同时涉及笔记和知识库时，必须读取两个子模块的 SKILL.md 文件后再执行，避免遗漏步骤。

这些规则虽增加实现细节，但确保了数据的可靠性和操作的稳定性，适用于需要精细控制 IMA API 集成的开发场景。