ima-skill

ima-skills 是什么

ima-skills 是腾讯 IMA OpenAPI 的统一 Skill，包含 notes 和 knowledge-base 两个模块。它可搜索、浏览、创建和追加笔记，也能上传文件、收藏网页、搜索知识库、读取条目及查看原文，适合构建持续积累的个人或团队知识库。

模块路由与跨模块任务

笔记内容的读写走 notes；知识库条目的上传、链接收藏和检索走 knowledge-base。若任务同时涉及两者，例如把知识库内容记到笔记、把笔记加入知识库，必须先读取两个子模块规则再按顺序执行，不能仅凭“知识库”字样选择接口。

凭据、上传与编码

需要 IMA OpenAPI Client ID 与 API Key，可放在环境变量或 ~/.config/ima。主文件声明凭据只作为请求头发送到 ima.qq.com；文件上传会使用 IMA 返回的短期、限定范围 COS 凭据连接 *.myqcloud.com。笔记写入前必须验证 UTF-8；二进制文件则必须保持原样。PowerShell 5.1 还需把 JSON 显式转换为 UTF-8 字节数组。

限制与安全信号

视频、Bilibili/YouTube 链接和 file:// URL 不受支持，应改用 IMA 桌面客户端。文件上传必须保留原文件名和扩展名。SkillHub 的两个安全报告结论不一致：Keen 标为 benign，三步标为 suspicious，因此不能给出统一安全结论；启用前应阅读报告、限制凭据权限并先用非敏感资料测试。

使用建议

首次连接可先创建测试笔记并上传一份非敏感小文件，验证凭据、编码、知识库选择和回滚方式。写入、追加或关联条目前先展示目标笔记或知识库，避免同名内容被误选；批量上传还要保留成功与失败清单，不因单个错误重复创建。

错误处理与恢复

脚本会区分本地程序错误、可用更新和后端业务错误。缺少凭据、网络失败或参数不合法时应读取 stderr；后端返回非零 code 时直接展示 msg。检测到新版本时原请求不会发送，应先按 instruction 更新再重试。批量写入必须为每个对象保留结果，避免更新检查或网络恢复后重复创建。

来源与许可

本条目依据 SkillHub tencent-adm/ima-skills 1.1.9 详情、完整主文件和 ima_api.cjs 整理。发布方显示为已认证的腾讯科技（深圳）有限公司，但条目和包文件未声明开源许可证，故记录为未声明。

常见问题

1. 它能管理什么内容？

可管理 IMA 笔记和知识库，包括读写笔记、上传文件、添加网页、检索与查看原文。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

2. 需要哪些凭据？

需要 IMA OpenAPI Client ID 和 API Key，可使用环境变量或配置文件。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

3. 凭据发送到哪里？

主文件声明用户凭据只发往 ima.qq.com，不发送到 COS 或其他域名。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

4. 文件上传如何处理？

先创建媒体获取短期 COS 凭据，上传原始文件，再把媒体加入知识库。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

5. 为什么必须检查 UTF-8？

笔记写入若编码错误会产生不可逆乱码，标题和正文都需验证。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

6. 哪些内容不支持？

视频、Bilibili/YouTube 链接和 file:// URL 不支持，应使用桌面客户端。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

7. 两个安全报告一致吗？

不一致。Keen 标为 benign，三步标为 suspicious，需要人工查看具体报告。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。

8. PowerShell 5.1 有什么限制？

所有请求体都要显式转为 UTF-8 字节数组，否则中文可能被静默转成 GBK。实际使用时还应结合当前版本、权限、输入数据和运行环境复核结果，并在重要任务中保留人工确认。