| name | ima-skill |
| description | 统一的 IMA OpenAPI helper，支持笔记管理和知识库操作。用于上传文件到知识库、添加网页、搜索知识库内容、读取或追加笔记，以及为文献整理流程提供 IMA API wrapper。 |
IMA OpenAPI helper
这是随仓库携带的 IMA helper，供 skills/ima-skill/harness/ 调用。它包含：
ima_api.cjs：统一 API 调用入口；knowledge-base/：知识库上传、搜索、浏览和媒体读取说明；notes/：笔记搜索、读取、新建和追加说明。
强制规则
- 写入笔记前必须校验 UTF-8：调用
import_doc 或 append_doc 前，content、title 等字符串必须是合法 UTF-8。
- 上传文件时不得改名：
add_knowledge 的 title 必须等于 file_name，并包含扩展名。
- 不支持的类型直接拒绝：视频、Bilibili/YouTube URL、
file:// URL 不通过 skill 添加，应提示用户使用 IMA 客户端。
- 文件上传保持二进制原样：PDF、图片、Office 文件等不得做文本编码转换。
- PowerShell 5.1 必须显式 UTF-8 字节发送：不要直接用字符串 body 调
Invoke-RestMethod。
模块路由
| 用户意图 | 读取 |
|---|
| 搜索笔记、浏览笔记本、读取笔记、新建笔记、追加内容 | notes/SKILL.md |
| 上传文件、添加网页、搜索知识库、浏览知识库、获取媒体原文 | knowledge-base/SKILL.md |
| 既涉及知识库又涉及笔记 | 两个子模块都读取 |
常见边界：
- “把这段内容添加到某篇笔记”是笔记追加，走
notes。
- “上传文件到知识库”是文件上传，走
knowledge-base。
- “把这篇笔记添加到知识库”需要先在
notes 中定位笔记，再用 knowledge-base 关联。
- “查看知识库里的笔记原文”先用
knowledge-base 获取媒体信息，若媒体类型是笔记，再用 notes 读取。
凭证
IMA 凭证来自环境变量或本机配置文件：
export IMA_OPENAPI_CLIENTID="your_client_id"
export IMA_OPENAPI_APIKEY="your_api_key"
或：
mkdir -p ~/.config/ima
echo "your_client_id" > ~/.config/ima/client_id
echo "your_api_key" > ~/.config/ima/api_key
缺少凭证时，node ima_api.cjs ... 会以非 0 退出，并在 stderr 输出结构化错误。
API 调用模板
所有请求为 HTTP POST + JSON body，仅发往 https://ima.qq.com。
node vendor/ima-skill/ima_api.cjs "openapi/wiki/v1/get_addable_knowledge_base_list" '{"cursor":"","limit":20}' '{}'
返回有两层错误：
- 进程非 0：脚本层错误，例如缺少凭证、参数非法、网络失败。
- 进程为 0 但响应
code != 0：后端业务错误，直接把 msg 展示给用户。
UTF-8 写入规则
写入笔记前，必须对来自文件、网页、剪贴板、外部 API 或用户输入的正文进行 UTF-8 校验。文件上传不适用该规则，上传文件必须保持二进制原样。
Node.js 示例：
content=$(node -e "const fs=require('fs');const buf=fs.readFileSync('tmpfile');process.stdout.write(buf.toString('utf8'))")
PowerShell 5.1 请求 body 必须转成 UTF-8 字节数组：
$body = @{ title = "标题"; content = $content; content_format = 1 } | ConvertTo-Json -Depth 10
$utf8Bytes = [System.Text.Encoding]::UTF8.GetBytes($body)
Invoke-RestMethod -Uri $url -Method Post -Body $utf8Bytes -ContentType "application/json; charset=utf-8" -Headers $headers
更新检查
ima_api.cjs 内置更新检查。若返回 code=-200，表示发现新版本且原请求未发送；根据 stdout 中的更新说明处理后再重试。若需要强制检查：
export IMA_FORCE_UPDATE_CHECK=1
