Menu
统一的 IMA OpenAPI 技能，支持笔记管理和知识库操作。当用户提到知识库、资料库、笔记、备忘录、记事，或者想要上传文件、添加网页到知识库、搜索知识库内容、搜索/浏览/创建/编辑笔记时，使用此技能。
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ruiyongwang/dlh --skill ima-notesThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Based on SOC occupation classification
Showing SKILL.md
| name | ima-notes |
| name_en | ima-notes |
| description | 统一的 IMA OpenAPI 技能，支持笔记管理和知识库操作。当用户提到知识库、资料库、笔记、备忘录、记事，或者想要上传文件、添加网页到知识库、搜索知识库内容、搜索/浏览/创建/编辑笔记时，使用此技能。 |
| description_en | Unified IMA OpenAPI skill for notes and knowledge base management. Supports creating notes, searching content, uploading files to knowledge base, and web clipping. Ideal for personal knowledge management and information organization. |
| version | 1.1.2 |
| homepage | https://ima.qq.com |
| author | 度量衡智库 |
| author_en | Duliangheng Think Tank |
| metadata | {"openclaw":{"emoji":"🔧","requires":{"env":"[Truncated]"},"primaryEnv":"IMA_OPENAPI_CLIENTID"},"security":{"credentials_usage":"This skill requires user-provisioned IMA OpenAPI credentials (Client ID and API Key)\nto authenticate with the official IMA API at https://ima.qq.com.\nCredentials are ONLY sent to the official IMA API endpoint (ima.qq.com) as HTTP headers.\nNo credentials are logged, stored in files, or transmitted to any other destination.\n","allowed_domains":["ima.qq.com"]}} |
Unified IMA OpenAPI skill. Currently supports: notes, knowledge-base.
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 toima.qq.comand never to any other domain, file, or log.
方式 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
所有请求统一为 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 创建/追加 |
核心判断规则：
多模块任务：当用户意图涉及多个模块时（如"从知识库搜索内容并记到笔记"），按意图顺序依次读取对应的模块文档并逐步执行。先完成前一个模块的操作，再进入下一个模块。
此规则为强制性要求，不可跳过。 非法编码会导致内容在 IMA 中显示为乱码，且无法修复，必须重新写入。
适用范围：notes 模块（
import_doc、append_doc等文本写入 API）。不适用于 knowledge-base 模块的文件上传：上传文件时必须保持文件原始内容，不得转码。文件以二进制方式上传，服务端自行处理。
每次调用 notes 写入类 API（import_doc/append_doc）之前，必须对 content、title 等所有字符串字段执行 UTF-8 编码校验/转换。 无论内容来源如何——用户直接输入、从文件读取、WebFetch 抓取、剪贴板粘贴、外部 API 返回——都不能假设已经是合法 UTF-8，必须显式确认。
在构造 notes 写入请求的 body 之前，完成以下步骤：
\xff\xfe 等）title 也必须为合法 UTF-8Python（推荐，几乎所有环境都有）：
# 读取文件，自动检测编码并转为 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)
此问题影响所有 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 可以被修复。