ima-skill

Unified IMA OpenAPI skill. Currently supports: notes, knowledge-base.

Setup

Security note: This skill authenticates with the official IMA API (ima.qq.com) — the same service the user already uses. Credentials are only sent as HTTP headers to ima.qq.com and never to any other domain, file, or log.

1. 1. 打开 https://ima.qq.com/agent-interface 获取 Client ID 和 API Key
2. 存储凭证（二选一）：

方式 A — 配置文件（推荐）：

CODEBLOCK0

方式 B — 环境变量：

CODEBLOCK1

Agent 会按优先级依次尝试：环境变量 → 配置文件。

凭证预检

每次调用 API 前，先确认凭证可用。如果两个值都为空，停止操作并提示用户按 Setup 步骤配置。

CODEBLOCK2

API 调用模板

所有请求统一为 HTTP POST + JSON Body，仅发往官方 Base URL https://ima.qq.com。

定义辅助函数避免重复 header — 每个模块传入完整路径：

CODEBLOCK3

Note: All IMA OpenAPI endpoints currently use HTTP POST. If a future module requires a different method, ima_api() must be extended to accept a method parameter.

模块决策表

⚠️ 易混淆场景

以下场景容易误判模块，需特别注意：

核心判断规则：

• - 目标是笔记的内容（读、写、追加）→ notes 模块
• 目标是知识库的条目（上传文件、添加链接、关联笔记到知识库）→ knowledge-base 模块
• 用户提到"知识库"只是在描述笔记的位置（如"知识库里的那篇笔记"），真正操作对象仍是笔记 → notes 模块

多模块任务：当用户意图涉及多个模块时（如"从知识库搜索内容并记到笔记"），按意图顺序依次读取对应的模块文档并逐步执行。先完成前一个模块的操作，再进入下一个模块。

注意事项

• - UTF-8 编码（仅 notes 模块）：见下方「⚠️ UTF-8 编码强制要求」章节。notes 模块的所有写入操作前必须完成 UTF-8 编码校验，否则会导致内容乱码且无法修复。
• 文件上传保持原样（knowledge-base 模块）：当用户要求上传文件到知识库时，必须保持文件原始内容不变，不得进行任何编码转换。文件以二进制方式上传，服务端会自行处理编码。擅自转码可能破坏文件内容（如 PDF、图片、Excel 等非文本文件，或用户有意使用特定编码的文本文件）。
• PowerShell 5.1 环境（所有模块）：见下方「⚠️ PowerShell 5.1 环境检测」章节。此问题影响所有 API 调用（notes、knowledge-base 等），PowerShell 5.1 会静默将请求 Body 转为 GBK 编码导致乱码。

⚠️ UTF-8 编码强制要求（CRITICAL — 仅适用于 notes 模块）

此规则为强制性要求，不可跳过。 非法编码会导致内容在 IMA 中显示为乱码，且无法修复，必须重新写入。
适用范围：notes 模块（import_doc、append_doc 等文本写入 API）。
不适用于 knowledge-base 模块的文件上传：上传文件时必须保持文件原始内容，不得转码。文件以二进制方式上传，服务端自行处理。

每次调用 notes 写入类 API（import_doc/append_doc）之前，必须对 content、title 等所有字符串字段执行 UTF-8 编码校验/转换。 无论内容来源如何——用户直接输入、从文件读取、WebFetch 抓取、剪贴板粘贴、外部 API 返回——都不能假设已经是合法 UTF-8，必须显式确认。

强制检查清单（notes 模块写入前）

在构造 notes 写入请求的 body 之前，完成以下步骤：

1. 1. 来自文件的内容：先检测文件编码，转为 UTF-8 后再读入变量（注意：这是指读取文件内容作为笔记正文写入，不是上传文件到知识库）
2. 来自 WebFetch / HTTP 请求的内容：响应可能为 GBK/Latin-1 等，必须转码
3. 来自用户输入或变量拼接的内容：清洗非法 UTF-8 字节（\xff\xfe 等）
4. 标题字段同理：title 也必须为合法 UTF-8

各环境转码方法

Python（推荐，几乎所有环境都有）：

CODEBLOCK4

Node.js：

CODEBLOCK5

Unix (macOS/Linux)：

CODEBLOCK6

Windows PowerShell：

CODEBLOCK7

⚠️ PowerShell 5.1 环境检测（CRITICAL — 适用于所有模块）

此问题影响所有 API 调用（notes、knowledge-base 等）
此问题极其隐蔽：PowerShell 5.1 下 Invoke-RestMethod 会静默将请求 Body 从 UTF-8 转为系统 ANSI 编码（中文 Windows 为 GBK），即使设置了 Content-Type: charset=utf-8 也无效。结果是请求看起来发送成功，但服务端收到的内容已经是乱码，且无任何错误提示。

当 agent 运行在 PowerShell 环境时，必须在首次 API 调用前检测版本：

CODEBLOCK8

PowerShell 5.1 下必须使用以下方式发送请求（用 ConvertTo-Json 构建 JSON 以避免手动拼接的转义风险，再显式转为 UTF-8 字节数组）：

CODEBLOCK9

总结： 在 PowerShell 5.1 环境中，所有 API 调用（无论 notes 还是 knowledge-base）都必须将 Body 显式转为 UTF-8 字节数组。不检测版本直接发请求 = 中文内容必乱码。这是 PowerShell 5.1 的已知设计缺陷，不是 bug 可以被修复。