Ima Skill

统一的 IMA OpenAPI 技能，支持笔记管理和知识库操作。 当用户提到知识库、资料库、笔记、备忘录、记事，或者想要上传文件、添加网页到知识库、 搜索知识库内容、搜索/浏览/创建/编辑笔记时，使用此 skill。 即使用户没有明确说"知识库"或"笔记"，只要意图涉及文件上传到知识库、网页收藏、 知识搜索、个人...

Security Scan

The skill's code and runtime instructions largely match its stated purpose (IMA notes and knowledge‑base operations), but there are a few small inconsistencies you should review before installing.

Purpose & Capability

The skill requests only the IMA OpenAPI credentials (IMA_OPENAPI_CLIENTID and IMA_OPENAPI_APIKEY), which matches its described purpose. Included helper scripts (preflight-check.cjs and cos-upload.cjs) are appropriate for file-type checks and uploading to Tencent COS as described. One minor mismatch: the skill manifest lists no required config paths or binaries, yet SKILL.md recommends storing credentials under ~/.config/ima and the runtime examples call node and curl.

Instruction Scope

SKILL.md instructs the agent to read credentials from either environment variables or a local config (~/.config/ima/*). The manifest did not declare that config path. The top-level security statement says credentials are only sent to ima.qq.com, but the upload workflow legitimately obtains temporary COS credentials from the IMA API and then uses them to PUT objects to a COS endpoint (bucket.cos.<region>.myqcloud.com). That is expected for the described upload flow, but the claim that 'credentials are ONLY sent to ima.qq.com' is slightly misleading unless clarified (user's static API key is sent to ima.qq.com; temporary COS credentials are used to upload to COS). The instructions also run local Node scripts and call curl; those local operations access user-specified files (intended) but the manifest didn't declare required binaries.

Install Mechanism

This is instruction-only (no external downloads), which is low risk. However, the skill includes Node scripts that the SKILL.md invokes (node .claude/skills/.../preflight-check.cjs and node cos-upload.cjs) and shell examples using curl. The manifest lists no required binaries; the runtime implicitly requires node (and curl). The absence of declared required binaries is an inconsistency you may want to correct or confirm.

Credentials

Only two credentials are requested (IMA_OPENAPI_CLIENTID and IMA_OPENAPI_APIKEY), which are proportional to a service-integration skill. The skill also suggests storing credentials in ~/.config/ima; that file path was not declared as a required config path. Additionally, the cos-upload helper expects temporary COS credentials (secret-id/secret-key/token) to be passed as arguments — these are returned by IMA's create_media call and are expected for uploading, but they are sensitive and will be used to authenticate to the COS domain during upload.

Persistence & Privilege

The skill does not request always:true and does not attempt to alter other skills or global agent settings. It is user-invocable and can be autonomously invoked by the agent (default), which is expected for skills. It does suggest storing credentials in a local config file if the user chooses that option (user-managed persistence).

Assessment

What to consider before installing: - The skill appears to implement exactly what it claims (notes and knowledge-base operations) and needs only IMA API credentials. However the documentation and manifest disagree in a few places — verify these before use. - Verify required local tools: SKILL.md uses curl and Node.js to run included scripts (preflight-check.cjs and cos-upload.cjs). The manifest didn't list required binaries; ensure your environment has node and curl if you plan to run the scripts. - Credential handling: prefer environment variables over storing plaintext keys in ~/.config/ima. If you do use the config file, ensure its permissions restrict access (e.g., 600). The skill's statement that credentials are only sent to ima.qq.com refers to the user's API key — note that the upload flow obtains temporary COS credentials from the IMA API and uses them to upload directly to a COS (myqcloud) domain; this is expected but means temporary credentials will be used on a different host during uploads. - Review the included scripts yourself (preflight-check.cjs and cos-upload.cjs). They read local files and perform network operations; that's required for uploads but you should confirm you are comfortable with those behaviors. - Privacy: notes are user-private; follow the SKILL.md guidance about not broadcasting note bodies in group contexts. If you have sensitive files, double-check the preflight rules and size/type limits before uploading. - If anything is unclear (e.g., where credentials may be logged, or why config paths/binaries aren't declared), ask the skill author or vendor for clarification before granting access.

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. 打开 https://ima.qq.com/agent-interface 获取 Client ID 和 API Key
2. 存储凭证（二选一）：

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

mkdir -p ~/.config/ima
echo "your_client_id" > ~/.config/ima/client_id
echo "your_api_key" > ~/.config/ima/api_key

方式 B — 环境变量：

export IMA_OPENAPI_CLIENTID="your_client_id"
export IMA_OPENAPI_APIKEY="your_api_key"

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

凭证预检

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

# Load user-provisioned IMA credentials (used ONLY for ima.qq.com API authentication)
IMA_CLIENT_ID="${IMA_OPENAPI_CLIENTID:-$(cat ~/.config/ima/client_id 2>/dev/null)}"
IMA_API_KEY="${IMA_OPENAPI_APIKEY:-$(cat ~/.config/ima/api_key 2>/dev/null)}"
if [ -z "$IMA_CLIENT_ID" ] || [ -z "$IMA_API_KEY" ]; then
  echo "缺少 IMA 凭证，请按 Setup 步骤配置 Client ID 和 API Key"
  exit 1
fi

API 调用模板

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

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

# All requests go ONLY to the official IMA API (ima.qq.com)
ima_api() {
  local path="$1" body="$2"
  curl -s -X POST "https://ima.qq.com/$path" \
    -H "ima-openapi-clientid: $IMA_CLIENT_ID" \
    -H "ima-openapi-apikey: $IMA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$body"
}

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	notes/SKILL.md
上传文件、添加网页链接、搜索知识库、浏览知识库内容、获取知识库信息、获取可添加的知识库列表	knowledge-base	knowledge-base/SKILL.md

⚠️ 易混淆场景

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

用户说的	实际意图	正确路由
"把这段内容添加到知识库XX里的笔记YY"	往已有笔记追加内容	notes — 先搜索笔记获取 doc_id，再用 append_doc
"把这个写到XX笔记里"、"记到XX笔记"	往已有笔记追加内容	notes — append_doc
"把这篇笔记添加到知识库"	将笔记关联到知识库	knowledge-base — add_knowledge with media_type=11
"上传文件到知识库"	上传文件到知识库	knowledge-base — create_media → COS → add_knowledge
"新建一篇笔记记录这些内容"	创建新笔记	notes — import_doc
"帮我记一下"、"记录一下"、"保存为笔记"（未指定已有笔记）	意图不明确，需要确认	notes — 先询问用户是创建新笔记还是追加到哪篇已有笔记，再决定接口
"添加到笔记里"（未指定具体哪篇）	意图不明确，需要确认	notes — 先询问用户是创建新笔记还是追加到哪篇已有笔记，再决定接口
"把知识库里的XX内容记到笔记"	先从知识库读取，再写入笔记	多模块 — knowledge-base 搜索/读取 → notes 创建/追加

核心判断规则：

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

各环境转码方法

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

# 读取文件，自动检测编码并转为 UTF-8
content=$(python3 -c "
import sys
data = open('tmpfile', 'rb').read()
for enc in ['utf-8', 'gbk', 'gb2312', 'big5', 'latin-1']:
    try:
        sys.stdout.write(data.decode(enc))
        break
    except (UnicodeDecodeError, LookupError):
        continue
" 2>/dev/null)

# 如果内容已在变量中，清洗非法 UTF-8 字节
content=$(printf '%s' "$content" | python3 -c "import sys; sys.stdout.write(sys.stdin.buffer.read().decode('utf-8','ignore'))")

Node.js：

content=$(node -e "const fs=require('fs');const buf=fs.readFileSync('tmpfile');process.stdout.write(buf.toString('utf8'))")
# 已知编码（如 GBK）：
content=$(node -e "const fs=require('fs');process.stdout.write(new TextDecoder('gbk').decode(fs.readFileSync('tmpfile')))")

Unix (macOS/Linux)：

content=$(iconv -f "$(file -b --mime-encoding tmpfile)" -t UTF-8 tmpfile 2>/dev/null || cat tmpfile)

Windows PowerShell：

# 读取非 UTF-8 文件并转码
$content = [System.IO.File]::ReadAllText('tmpfile', [System.Text.Encoding]::Default)
[System.IO.File]::WriteAllText('tmpfile.utf8', $content, [System.Text.Encoding]::UTF8)

⚠️ 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 调用前检测版本：

# 检测 PowerShell 版本 — 在任何 API 调用之前执行（notes 和 knowledge-base 都需要）
if ($PSVersionTable.PSVersion.Major -le 5) {
    Write-Host "⚠️ 检测到 PowerShell 5.1，将使用 UTF-8 字节数组模式发送请求"
    $useUtf8Bytes = $true
} else {
    Write-Host "✅ PowerShell 7+，默认 UTF-8，无需额外处理"
    $useUtf8Bytes = $false
}

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

# PowerShell 5.1 安全请求模板（适用于所有模块的所有 API 调用）
$body = @{ title = "标题"; content = $content; content_format = 1 } | ConvertTo-Json -Depth 10
if ($useUtf8Bytes) {
    # CRITICAL: 必须转为字节数组，否则中文/非ASCII内容会变成乱码
    $utf8Bytes = [System.Text.Encoding]::UTF8.GetBytes($body)
    Invoke-RestMethod -Uri $url -Method Post -Body $utf8Bytes -ContentType "application/json; charset=utf-8" -Headers $headers
} else {
    # PowerShell 7+ 可直接传字符串
    Invoke-RestMethod -Uri $url -Method Post -Body $body -ContentType "application/json; charset=utf-8" -Headers $headers
}

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