ima知识库助手

要解决的问题

笔记散落在本地文件、网页摘录和聊天窗口里，知识库又挂在另一个入口，脚本同时操作两者时往往得写两套胶水代码。这个技能把 IMA OpenAPI 收敛成一套调用模板：统一使用 HTTP POST + JSON Body 发往 ima.qq.com，Agent 不必再关心两套接口的差异。

核心能力

双模块路由。 能力拆成 notes 和 knowledge-base 两个子模块，按用户意图选择：搜索笔记、创建笔记、追加内容走 notes；上传文件、添加网页链接、检索知识库走 knowledge-base。SKILL.md 提供了意图决策表，专门处理"把这段内容添加到知识库XX里的笔记YY"这类歧义表达——操作对象其实是笔记，而非知识库本身。

跨模块任务。 当一个请求同时涉及笔记与知识库（如把知识库内容记到笔记、把笔记关联进知识库），技能要求先读完两个子模块的 SKILL.md 再按顺序执行，避免凭直觉选错模块导致 API 报错或数据写错位置。

统一的凭证与调用封装。 所有请求通过 ./ima_api.cjs 发起，凭证按环境变量优先、配置文件兜底的顺序读取，只作为 HTTP 头发往 ima.qq.com，不落入日志或其他域名。

两层错误处理。 脚本层区分 -100（缺凭证、参数非法等程序错误）和 -200（skill 需要更新，原请求未发送）；业务层检查返回 JSON 的 code，code≠0 时把后端 msg 直接呈现给用户。

适用边界与注意点

• 编码是硬约束。 notes 写入前所有字符串字段必须校验为合法 UTF-8，否则产生不可逆乱码；但知识库文件上传必须保持原样，禁止对 PDF、图片、Excel 等二进制文件转码。
• 文件类型有限制。 视频文件、Bilibili/YouTube 链接和 file:// URL 一律拒绝，需改用 IMA 桌面客户端。
• 文件名不可改。 上传时 title 必须与文件名（含扩展名）完全一致，不得重命名或翻译。
• PowerShell 5.1 陷阱。 该版本会把请求 Body 静默转成 GBK，首次调用前必须检测版本，并以 UTF-8 字节数组方式发送，否则中文内容必乱码。
• 凭证需提前配置。 首次调用前用 test -f ~/.config/ima/client_id 检查，缺失时引导用户从 IMA 开放平台获取 Client ID 与 API Key。