ima skills

ima-skill 是腾讯IMA（ima.qq.com）官方OpenAPI的统一封装技能，提供笔记管理和知识库两大核心能力。该skill通过标准化的HTTP POST+JSON方式与官方API通信，所有请求仅发送至ima.qq.com域名，文件上传流程使用IMA API返回的短期临时凭证对接COS（*.myqcloud.com），用户的主凭证（Client ID/API Key）不会直接传输至COS端点。

核心用法：用户需先在 https://ima.qq.com/agent-interface 获取Client ID和API Key，通过环境变量或配置文件（~/.config/ima/）配置后，即可调用notes模块（搜索/创建/编辑/追加笔记）和knowledge-base模块（上传文件、添加网页、搜索知识库内容、关联笔记到知识库）。技能内置ima_api.cjs脚本统一处理API调用、错误分层处理（程序错误-100/更新检查-200/业务错误）及自动更新检测机制。

显著优点：官方原生API封装，功能完整覆盖IMA核心场景；凭证隔离设计明确，主凭证仅用于身份认证不进入文件上传链路；内置UTF-8编码强制校验（notes写入）和PowerShell 5.1环境检测，避免常见中文乱码陷阱；错误处理分层清晰，-200更新状态与业务错误分离。

潜在缺点/局限：需用户自行申请和管理API凭证，有一定使用门槛；不支持视频文件、Bilibili/YouTube链接、file://协议URL，需引导用户使用桌面客户端；PowerShell 5.1环境必须显式处理UTF-8字节数组，否则中文内容必乱码；涉及notes与knowledge-base交叉场景（如"查看知识库中的笔记原文"）需先后读取两个子模块SKILL.md，路由判断逻辑较复杂。

适合人群：已拥有IMA账号、需要自动化笔记/知识库管理的技术用户或效率工具集成者；需在AI Agent工作流中嵌入个人知识管理的开发者；熟悉API凭证配置、能接受命令行/脚本交互的中高级用户。

常规风险：凭证配置错误导致API调用失败（code -100）；非UTF-8内容写入notes导致不可逆乱码；PowerShell 5.1未做环境检测导致内容损坏；混淆"笔记内容操作"与"知识库条目操作"的模块边界导致路由错误。

核心用法

ima-skill 是基于腾讯 IMA 官方 OpenAPI 开发的统一技能，旨在让 AI 助手能够直接操作用户的 IMA 个人知识库和笔记系统。其核心定位是解决个人知识管理的最后一公里问题——用户无需手动打开 IMA 客户端，即可通过自然语言指令完成知识库的增删改查。

该技能包含两大核心模块：

• 知识库模块：支持上传文件（PDF、Word、图片等）至知识库、添加网页链接、搜索知识库内容、将已有笔记关联到知识库等操作。文件上传流程安全完善，先通过 IMA API 获取腾讯云 COS 临时凭证，再直传文件至对象存储。
• 笔记模块：支持创建新笔记、搜索/浏览笔记、获取笔记内容、向已有笔记追加内容。所有写入操作均强制要求 UTF-8 编码校验，避免因编码不一致导致的乱码问题。

显著优点

强大的官方技术背书：技能直接调用腾讯 IMA 官方 API（ima.qq.com），数据传输依托腾讯云 COS 对象存储，具备企业级的服务可用性和数据可靠性保障。

极致的安全设计：六维深度安全扫描全部通过，无后门、无数据外泄、无 Agent 注入行为。所有网络通信强制 HTTPS/TLS 加密，用户凭证仅作为 HTTP Header 发往官方 API，绝不发送至第三方域名。零外部依赖的架构彻底规避了供应链攻击风险。

细致入微的工程规范性：内置 PowerShell 5.1 环境检测与 UTF-8 字节数组适配方案，有效规避 Windows 环境下中文乱码这一著名技术缺陷；提供多平台（Python/Node.js/Unix/Windows）的编码转换最佳实践，确保跨平台操控的一致性。

透明的自动化机制：具备每日自动更新检查能力，可同步官方最新功能与安全修复，更新行为完整文档化且用户可控，兼顾易用性与自主权。

潜在缺点或局限性

功能完全受限于后端 API：笔记删除、知识库彻底删除等功能依赖后端 API 是否开放，技能本身未直接暴露这些操作，当前可能存在删除不便的问题。

不支持特定媒体类型：视频文件、Bilibili/YouTube 等在线视频链接、本地 file:// 协议文件不被支持，需告知用户使用 IMA 桌面客户端处理。

L1 远程指令加载风险：内置的自动更新机制会从服务端拉取 instruction 指引文本并由 Agent 遵循执行。虽然来源为腾讯官方可信域名且已文档化，但安全审计指出这是某种程度上的远程动态指令加载，服务端若被入侵理论上存在下发恶意指引的极小概率。

适合的目标群体

• 重度个人知识管理者：习惯使用 IMA 存储文档、网页、笔记，且希望通过 AI 助手以自然语言快速检索和操作知识的用户。
• 开发者和技术爱好者：愿意通过配置 API 凭证将 AI 助手接入个人知识体系的用户。
• 追求数据主权和隐私的用户：认同 IMA 本地存储与云端同步相结合的模式，且注重数据仅通过官方 API 流转的安全层级。

常规使用风险

凭证管理风险：技能需要用户自行从 ima.qq.com 获取 Client ID 和 API Key，若用户将凭证存储在安全性不足的环境变量或配置文件中，存在泄露风险。建议严格遵循技能指引，将凭证存储于 ~/.config/ima/ 目录下。

内容乱码风险：若 Agent 未严格遵循技能强制要求的 UTF-8 编码检查步骤，在 Windows 环境或从 GBK 编码网页抓取内容时写入笔记，可能出现永久性乱码，需人工删除重建。

版本兼容性风险：虽然自动更新机制能保障功能更新，但若用户需要长期稳定的行为模式，缺乏版本锁定能力可能导致偶尔的兼容变化。