ima skills

IMA 个人笔记服务 API skill，用于管理用户的 IMA 笔记。支持搜索笔记、浏览笔记本、获取笔记内容、新建笔记和追加内容。 当用户提到笔记、备忘录、记事、知识库，或者想要查找、阅读、创建、编辑笔记内容时，使用此 skill。 即使用户没有明确说"笔记"，只要意图涉及个人文档的存取（如"帮我记一下"、"我...

Security Scan

The skill's requests and instructions line up with a note-management integration for ima.qq.com: it only needs the service's client ID and API key and its SKILL.md describes straightforward API calls via curl—no unrelated permissions or installs were found.

Purpose & Capability

Name/description, declared env vars (IMA_OPENAPI_CLIENTID, IMA_OPENAPI_APIKEY), and the documented endpoints all correspond to IMA note management. Nothing requested (no extra credentials, binaries, or config paths) is unrelated to the stated purpose.

Instruction Scope

SKILL.md contains explicit curl-based POST templates to ima.qq.com and clear guidance (search/list/get/import/append). It does not instruct reading other files, secrets, or sending data to external endpoints beyond the documented API. It also includes reasonable credential presence checks and a privacy note about not exposing note bodies in group chats.

Install Mechanism

This is instruction-only with no install spec or code files to write or execute. No download/installation steps are present, so there is minimal install-related risk.

Credentials

Requires exactly two environment variables (client id and apikey) that map to the service's headers used in every request. The number and naming of env vars are proportionate and justified by the API usage.

Persistence & Privilege

always:false (default) and no instructions to modify other skills or system-wide configs. The skill does suggest storing creds in shell rc files (typical), but it does not request elevated or persistent platform privileges.

Assessment

This skill appears to be a straightforward connector to IMA (ima.qq.com) and only needs your IMA client ID and API key. Before installing: 1) Verify the keys you provide are from the correct IMA account and have minimal scope/permissions where possible. 2) Beware that adding the credentials to shell rc files makes them persistent on that machine—store secrets in a secure place if you prefer (e.g., secret manager). 3) Consider whether you want the agent to be allowed to autonomously invoke a notes skill (default behavior) because it could access your personal notes when triggered; if not, restrict invocation or keep the skill disabled until explicitly invoked. 4) If you share your environment or machine, do not put sensitive keys in plain shell rc files. 5) If anything looks suspicious in actual API responses or behavior, revoke the API key and rotate credentials.

ima-note

通过 IMA OpenAPI 管理用户个人笔记，支持读取（搜索、列表、获取内容）和写入（新建、追加）。

完整的数据结构和接口参数详见 references/api.md。

Setup

1. 请打开 https://ima.qq.com/agent-interface 获取 Client ID 和 Api Key
2. 配置环境变量：

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

建议将上述 export 语句写入 ~/.zshrc 或 ~/.bashrc，避免每次重开终端失效。

凭证预检

每次调用 API 前，先确认凭证可用。如果环境变量未设置，停止操作并提示用户按 Setup 步骤配置。

if [ -z "$IMA_OPENAPI_CLIENTID" ] || [ -z "$IMA_OPENAPI_APIKEY" ]; then
  echo "缺少 IMA 凭证，请按 Setup 步骤配置环境变量 IMA_OPENAPI_CLIENTID 和 IMA_OPENAPI_APIKEY"
  exit 1
fi

API 调用模板

所有请求统一为 HTTP POST + JSON Body，Base URL 为 https://ima.qq.com/openapi/note/v1。

定义辅助函数避免重复 header：

ima_api() {
  local endpoint="$1" body="$2"
  curl -s -X POST "https://ima.qq.com/openapi/note/v1/$endpoint" \
    -H "ima-openapi-clientid: $IMA_OPENAPI_CLIENTID" \
    -H "ima-openapi-apikey: $IMA_OPENAPI_APIKEY" \
    -H "Content-Type: application/json" \
    -d "$body"
}

隐私规则： 笔记内容属于用户隐私，在群聊场景中只展示标题和摘要，禁止展示笔记正文。

接口决策表

用户意图	调用接口	关键参数
搜索/查找笔记	search_note_book	query_info（QueryInfo 对象）
查看笔记本列表	list_note_folder_by_cursor	cursor(必填，首页传"0") + limit(必填)
浏览某笔记本里的笔记,当用户表述"最新"、"最近"之类的通用限定，没有指明笔记本时，都应该直接在全部笔记里去拉	list_note_by_folder_id	folder_id(选填,空为全部笔记本) + cursor(必填，首次传"") + limit(必填)
读取笔记正文	get_doc_content	doc_id + target_content_format(必填，推荐0纯文本)
新建一篇笔记	import_doc	content + content_format(必填，固定1) + 可选 folder_id
往已有笔记追加内容	append_doc	doc_id + content + content_format(必填，固定1)

常用工作流

查找并阅读笔记

先搜索获取 docid，再用 get_doc_content 读取正文：

# 1. 按标题搜索
ima_api "search_note_book" '{"search_type": 0, "query_info": {"title": "会议纪要"}, "start": 0, "end": 20}'
# 从返回的 docs[].doc.basic_info.docid 中取目标笔记 ID

# 2. 读取正文（纯文本格式，Markdown 格式目前不支持）
ima_api "get_doc_content" '{"doc_id": "目标docid", "target_content_format": 0}'

浏览笔记本里的笔记

先拉笔记本列表获取 folder_id，再拉该笔记本下的笔记：

# 1. 列出笔记本（首页 cursor 传 "0"）
ima_api "list_note_folder_by_cursor" '{"cursor": "0", "limit": 20}'

# 2. 拉取指定笔记本的笔记（首页 cursor 传 ""）
ima_api "list_note_by_folder_id" '{"folder_id": "user_list_xxx", "cursor": "", "limit": 20}'

新建笔记

# 新建到默认位置
ima_api "import_doc" '{"content_format": 1, "content": "# 标题\n\n正文内容"}'

# 新建到指定笔记本
ima_api "import_doc" '{"content_format": 1, "content": "# 标题\n\n正文内容", "folder_id": "笔记本ID"}'
# 返回 doc_id，后续可用于 append_doc

追加内容到已有笔记

ima_api "append_doc" '{"doc_id": "笔记ID", "content_format": 1, "content": "\n## 补充内容\n\n追加的文本"}'

按正文搜索

ima_api "search_note_book" '{"search_type": 1, "query_info": {"content": "项目排期"}, "start": 0, "end": 20}'

核心响应字段

搜索结果（SearchedDoc）：笔记信息路径为 doc.basic_info（DocBasic），关键字段：docid、title、summary、folder_id、folder_name、create_time（Unix 毫秒）、modify_time、status。额外包含 highlight_info（高亮匹配，key 为 doc_title，value 含 <em>高亮词</em>）。

笔记本条目（NoteBookFolder）：信息路径为 folder.basic_info（NoteBookFolderBasic），关键字段：folder_id、name、note_number、create_time、modify_time、folder_type（0=用户自建，1=全部笔记，2=未分类）、status。

笔记列表条目（NoteBookInfo）：信息路径为 basic_info.basic_info（DocBasicInfo → DocBasic），关键字段：docid、title、summary、folder_id、folder_name、create_time、modify_time、status。

写入结果（import_doc/append_doc）：返回 doc_id（新建或目标笔记的唯一 ID）。

完整字段定义见 references/api.md。

分页

• 游标分页 — 笔记本列表（list_note_folder_by_cursor）：首次 cursor: "0"，后续用 next_cursor，is_end=true 时停止。
• 游标分页 — 笔记列表（list_note_by_folder_id）：首次 cursor: ""，后续用 next_cursor，is_end=true 时停止。
• 偏移量分页（search_note_book）：首次 start: 0, end: 20，翻页时递增，is_end=true 时停止。

枚举值

• content_format： 0=纯文本，1=Markdown，2=JSON。写入（import_doc/append_doc）目前仅支持 1（Markdown）。读取（get_doc_content）推荐 0（纯文本），Markdown 格式不支持。
• search_type： 0=标题检索（默认），1=正文检索
• sort_type： 0=更新时间（默认），1=创建时间，2=标题，3=大小（仅 search_note_book 使用）
• folder_type： 0=用户自建，1=全部笔记（根目录），2=未分类

注意事项

• folder_id 不可为 "0"，根目录 ID 格式为 user_list_{userid}（从 folder_type=1 的笔记本条目获取）
• 笔记内容有大小上限，超过时返回 100009，可拆分为多次 append_doc 写入
• 展示笔记列表时只展示标题、摘要和修改时间，不要主动展示正文
• 时间字段是 Unix 毫秒时间戳，展示时转为可读格式
• 返回数据为嵌套结构：搜索结果取 docs[].doc.basic_info.docid，笔记本取 note_book_folders[].folder.basic_info.folder_id，笔记列表取 note_book_list[].basic_info.basic_info.docid，注意按层级解析

错误处理

错误码	含义	建议处理
0	成功	—
100001	参数错误	检查请求参数格式和必填字段
100002	无效 ID	检查凭证配置
100003	服务器内部错误	等待后重试
100004	size 不合法 / 空间不够	检查参数范围
100005	无权限	确认操作的是用户自己的笔记
100006	笔记已删除	告知用户该笔记不存在
100008	版本冲突	重新获取内容后再操作
100009	超过大小限制	拆分为多次 append_doc 写入
310001	笔记本不存在	检查 folder_id 是否正确
20002	apiKey超过最大限频
20004	apikey 鉴权失败	检查凭证配置是否正确