前言¶

笔记散落在腾讯 ima（ima.copilot）里，AI 助手却看不到：想让 Agent 帮你记一下会议要点、找回上周写过的排期、把新笔记追加到旧文档后面，都得手动复制粘贴。自己对接 ima OpenAPI 也行，但要处理鉴权、游标分页、嵌套响应结构和中文编码，成本不低。

下面介绍的是一个现成的 Skill：ima_skills_yc，把 ima 笔记的搜索、浏览、读取、新建、追加封装成 AI 助手可直接调用的技能。它兼容 OpenClaw 生态，基于 ima 官方 OpenAPI，凭证在 https://ima.qq.com/agent-interface 申请。

这是什么¶

• 名称：ima_skills_yc，坐标 @clawhub_laineyboy/ima，版本 1.0.0，License MIT-0
• 出品：发布者 laineyboy，托管在 ClawHub（https://clawhub.ai/laineyboy/ima），同时收录在 SkillHub（https://www.skillhub.cn/skills/clawhub_laineyboy/ima，抓取时页面显示评分 100000、下载 14253、安装 401）
• 定位：通过 IMA OpenAPI 管理用户个人笔记，支持读取（搜索、列表、获取内容）和写入（新建、追加）。当用户提到笔记、备忘录、记事、知识库，或意图涉及个人文档存取（”帮我记一下”、”我之前写过关于 XX 的东西”）时触发

注意边界：该 Skill 只覆盖笔记的读写检索，不包含把网页、微信文章、文件收藏进 ima 知识库的能力。需要那部分功能要另行实现。

安装与启用¶

ClawHub / OpenClaw 侧安装命令：

openclaw skills install @laineyboy/ima

SkillHub 侧安装命令：

npx skills add @clawhub_laineyboy/ima

两条命令来源不同，按你所在生态选其一。安装后 Skill 需要 API 凭证才能工作。

凭证配置¶

凭证在 https://ima.qq.com/agent-interface 申请，拿到 Client ID 和 Api Key 后配置环境变量：

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

建议写入 ~/.zshrc 或 ~/.bashrc，避免重开终端失效。每次调用 API 前先做凭证预检，未配置就停止并提示用户：

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

核心能力¶

所有请求统一为 HTTP POST + JSON Body，Base URL 为 https://ima.qq.com/openapi/note/v1，请求头携带 ima-openapi-clientid 和 ima-openapi-apikey。定义一个辅助函数避免重复 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（search_type=0 标题检索，1 正文检索）
• 查看笔记本列表：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，再读正文：

# 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}'

按正文内容搜索：

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

浏览笔记本里的笔记。先拉笔记本列表拿 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}'

新建和追加。新建返回 doc_id，可作为追加的目标：

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

# 新建到指定笔记本
ima_api "import_doc" '{"content_format": 1, "content": "# 标题\n\n正文内容", "folder_id": "笔记本ID"}'

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

响应结构与分页要点¶

返回数据是嵌套结构，解析时按层级取值：

• 搜索结果：笔记信息在 docs[].doc.basic_info，关键字段 docid、title、summary、folder_id、folder_name、create_time、modify_time、status，另有 highlight_info 高亮匹配
• 笔记本条目：在 note_book_folders[].folder.basic_info，关键字段 folder_id、name、note_number、folder_type（0=自建，1=全部笔记，2=未分类）
• 笔记列表条目：在 note_book_list[].basic_info.basic_info，字段同上

分页方式因接口而异：

• 笔记本列表：游标分页，首页 cursor: "0"，后续用 next_cursor，is_end=true 时停止
• 笔记列表：游标分页，首页 cursor: ""
• 搜索：偏移量分页，start: 0, end: 20，翻页递增

时间字段是 Unix 毫秒时间戳，展示时需转成可读格式。

注意与坑¶

• 写入格式受限：import_doc / append_doc 目前仅支持 content_format=1（Markdown）；读取时推荐纯文本（0），Markdown 格式不支持
• 笔记内容有大小上限，超过返回错误码 100009，可拆成多次 append_doc 写入
• folder_id 不可为 "0"，根目录 ID 格式为 user_list_{userid}，从 folder_type=1 的笔记本条目获取
• 隐私规则：笔记正文属于用户隐私，群聊场景只展示标题和摘要，禁止展示正文；展示列表时不主动显示正文
• 中文编码：写入前确保内容为合法 UTF-8，尤其当内容来自临时文件或外部抓取时。SKILL.md 里给了 Python、Node.js、iconv、PowerShell 几种转码方式，按运行环境选
• 鉴权失败常见于凭证问题：错误码 20004（apikey 鉴权失败）、110037（apikey 过期，需到 https://ima.qq.com/agent-interface 重新获取）

适用场景¶

适合已经在使用 ima 记笔记、想让 AI 助手直接读写自己笔记库的个人开发者或 Agent 玩家。它解决的是”笔记入口”问题——把存取笔记变成一条自然语言指令，不需要自己维护一套 API 客户端代码。

不适合想管理 ima 知识库收藏（网页、微信文章、文件）的场景，也不覆盖笔记的删除、移动、重命名等操作，这些接口目前没有封装。

结尾¶

这个 Skill 的价值在于把 ima OpenAPI 的鉴权、分页、嵌套解析和编码坑都封装好，装上配好凭证就能用。需要安装或查看完整接口字段定义（见 SKILL.md 的 references/api.md），可以从官方地址入手：

• SkillHub：https://www.skillhub.cn/skills/clawhub_laineyboy/ima
• ClawHub：https://clawhub.ai/laineyboy/ima
• 凭证申请：https://ima.qq.com/agent-interface