ima-notes

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":["IMA_OPENAPI_CLIENTID","IMA_OPENAPI_APIKEY"]},"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"]}}

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. 打开 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 可以被修复。