note-test1-limingzhi

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

Security Scan

The skill's requirements and runtime instructions are coherent with a note-management API: it only needs the IMA client ID and API key, uses those to call ima.qq.com endpoints, and has no install step or unrelated privileges.

Purpose & Capability

Name/description describe an IMA personal-notes integration and the skill only requests IMA_OPENAPI_CLIENTID and IMA_OPENAPI_APIKEY, which are exactly the credentials needed to call the documented IMA OpenAPI endpoints.

Instruction Scope

SKILL.md contains concrete curl-based API call templates and credential-check logic. It instructs reading credentials from environment variables or ~/.config/ima/* files (the SKILL.md provides example commands that create those files). This file I/O is limited to the credential files described and to network calls only to the stated base URL (https://ima.qq.com). No unrelated files, shell history, or external endpoints are referenced.

Install Mechanism

No install spec or downloaded code; instruction-only skill (no archive downloads, published packages, or binary installs). This is the lowest-risk install profile.

Credentials

Only two environment variables are required (IMA_OPENAPI_CLIENTID, IMA_OPENAPI_APIKEY), which match the documented API authentication. The primaryEnv is set appropriately. No unrelated secrets or system credentials are requested.

Persistence & Privilege

always is false and the skill does not request persistent presence or system-wide configuration changes. Autonomous invocation is allowed (platform default) but not combined with other concerning privileges.

Assessment

This skill appears to do exactly what it says: call the IMA note API using an IMA client ID and API key. Before installing, confirm you trust the IMA service (ima.qq.com) and the source of this skill. Decide whether to provide credentials via environment variables or via the local config files (~/.config/ima/client_id and api_key) — both are supported; storing keys on disk has usual local-file risks, so protect those files (restrict permissions) and rotate keys if exposed. Be aware that the agent, when invoking this skill, will have access to the provided IMA credentials and can read/write your notes via the documented endpoints; avoid enabling it for untrusted agents or in public/group contexts where sensitive note content could be exposed. If you want stronger assurance, request more details about how the skill is distributed/published or prefer a skill from a known maintainer.

ima-note

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

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

Setup

1. 请打开 https://ima.qq.com/agent-interface 获取 Client ID 和 App Key
2. 存储凭证：

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

也可以通过环境变量配置（agent 会按优先级依次尝试：环境变量 → 配置文件）：

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

凭证预检

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

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 和 App Key"
  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_CLIENT_ID" \
    -H "ima-openapi-apikey: $IMA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$body"
}

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

接口决策表

用户意图	调用接口	关键参数
搜索/查找笔记	search_note_book	query_info（QueryInfo 对象）+ start(必填) + end(必填)
查看笔记本列表	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.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 和 doc_info，后续可用于 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.basic_info 下，关键字段：docid、title、summary、tags、folder_name、create_time（Unix 毫秒）、modify_time。额外包含 highlight_info（高亮匹配）和 share_flag。

笔记本条目（NoteBookFolder）：信息在 folder.basic_info.basic_info 下，关键字段：folder_id、name、note_number、folder_type（0=用户自建，1=全部笔记根目录，2=未分类）。

笔记列表条目（NoteBookInfo）：信息在 basic_info.basic_info 下，额外包含 knowledge_exist_info（知识库状态）和 security_status（安审状态）。

写入结果（import_doc/append_doc）：返回 doc_id 和完整的 doc_info（DocInfo 对象）。

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

分页

• 游标分页 — 笔记本列表（list_note_folder_by_cursor）：首次 cursor: "0"，后续用 next_cursor，is_end=true 时停止。支持 version/next_version 增量同步，need_update 判断是否有变化。
• 游标分页 — 笔记列表（list_note_by_folder_id）：首次 cursor: ""，后续用 next_cursor，is_end=true 时停止。同样支持 version 增量同步。
• 偏移量分页（search_note_book）：首次 start: 0, end: 20，翻页时递增，query_id 原样透传，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 毫秒时间戳，展示时转为可读格式
• 新协议返回的数据是嵌套结构（如 doc.basic_info.basic_info.docid），注意按层级解析

错误处理

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