前言¶

筆記散落在騰訊 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