前言¶

做知識管理時，常見做法是：人在 IMA 裏收藏資料，對話卻在 Cursor、OpenClaw 等 Agent 裏進行，兩邊數據不通，Agent 只能憑上下文「猜」你記過什麼。若希望對話裏直接搜索知識庫、新建或追加筆記、把本地文件入庫，就需要一套對接 IMA OpenAPI 的 Skill。下面介紹 SkillHub 企業源上的 @tencent-adm/ima-skills（當前 v1.1.9），它把筆記與知識庫能力封裝成 Agent 可執行的流程，並聲明接入 OpenClaw 生態。

這是什麼¶

ima-skills 是騰訊 IMA 團隊（發佈者 tencent-ima）在 SkillHub 上架的企業類 Skill，座標 @tencent-adm/ima-skills，分類爲 knowledge-management。官方簡介說明：支持對筆記、知識庫的讀取、寫入和檢索等操作，便於在對話中記錄與調用 IMA 側內容，並面向 OpenClaw 等 Agent 環境使用。

SkillHub 頁面標註 requires_api_key=true：使用前需配置 IMA OpenAPI 的 Client ID 與 API Key，請求發往官方域名 https://ima.qq.com；文件上傳流程還會使用 IMA 返回的臨時憑證訪問騰訊雲 COS（*.myqcloud.com），憑證本身不發往 COS。

核心功能¶

技能包內統一入口爲 ima-skill，當前覆蓋兩個子模塊（以已安裝包內 SKILL.md 爲準）：

筆記（notes）¶

API 路徑前綴：openapi/note/v1。能力包括：

• 讀取：search_note（按標題或正文）、list_notebook、list_note、get_doc_content
• 寫入：import_doc（新建筆記）、append_doc（向已有筆記追加，屬敏感操作，需明確目標筆記）

寫入內容格式爲 Markdown（content_format=1）；筆記正文讀取推薦純文本（target_content_format=0）。本地圖片路徑不能通過接口寫入，需過濾並提示用戶改用網絡鏈接。

知識庫（knowledge-base）¶

API 路徑前綴：openapi/wiki/v1。能力包括：

• 檢索與瀏覽：search_knowledge、search_knowledge_base、get_knowledge_list、get_knowledge_base、get_media_info
• 寫入：網頁/微信鏈接 import_urls；文件經 check_repeated_names → create_media → COS 上傳 → add_knowledge；已有筆記關聯入庫 add_knowledge（media_type=11）
• 選型輔助：未指定目標庫時可用 get_addable_knowledge_base_list 列出可寫入的知識庫

文件上傳前有類型預檢（preflight-check.cjs），不支持的視頻、B 站/YouTube 鏈接、file:// 等需引導用戶使用 IMA 桌面客戶端。

路由與跨模塊¶

根 SKILL.md 提供「筆記 vs 知識庫」決策表：改筆記內容走 notes；上傳文件、加鏈接、把筆記掛到知識庫走 knowledge-base。若要先搜知識庫再記筆記，或查看知識庫中筆記型媒體的原文，需按文檔順序讀取兩個子模塊再執行。

運行時依賴 Node.js ≥ 18（執行 ima_api.cjs 及上傳相關腳本）。技能內置每日首次 API 調用時的版本檢查；缺憑證或需升級時，腳本會在 stderr 返回結構化錯誤碼（如 -100、-200）。

安裝與啓用¶

安裝 SkillHub CLI¶

若尚未安裝，可先執行：

command -v skillhub && skillhub --version

未安裝時可用官方腳本（僅 CLI）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

安裝 ima-skills¶

安裝時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 且可能不被識別。官方頁面與 CLI 給出的安裝方式爲：

skillhub install ima-skills --namespace tencent-adm --dir <你的 skills 目錄>

常見路徑（來自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

也可讓 Agent 按 https://skillhub.cn/install/skillhub.md 指引安裝 @tencent-adm/ima-skills。

配置 IMA OpenAPI 憑證¶

1. 在 https://ima.qq.com/agent-interface 獲取 Client ID 與 API Key。
2. 二選一存儲（Agent 優先讀環境變量，再讀配置文件）：

方式 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"

OpenClaw 元數據中也聲明瞭上述環境變量名。缺少憑證時，調用 node ima_api.cjs 會以 code: -100 退出並在 stderr 說明原因。

典型用法¶

以下示例來自技能包文檔，實際調用時需把 ima_api 替換爲技能目錄下的 node ima_api.cjs 及憑證參數（見根 SKILL.md 的 API 調用模板）。

搜索並閱讀筆記：

# 1. 按標題搜索
ima_api "openapi/note/v1/search_note" '{"search_type": 0, "query_info": {"title": "會議紀要"}, "start": 0, "end": 20}'
# 2. 讀取正文
ima_api "openapi/note/v1/get_doc_content" '{"note_id": "目標note_id", "target_content_format": 0}'

新建筆記：

ima_api "openapi/note/v1/import_doc" '{"content_format": 1, "content": "# 標題\n\n正文內容"}'

在知識庫中搜索：

ima_api "openapi/wiki/v1/search_knowledge" '{"query": "關鍵詞", "knowledge_base_id": "<kb_id>", "cursor": ""}'

添加網頁到知識庫：

ima_api "openapi/wiki/v1/import_urls" '{
  "knowledge_base_id": "<kb_id>",
  "urls": ["https://example.com/article"]
}'

文件上傳到知識庫需完整走預檢、重名檢查、COS 上傳等步驟，詳見包內 knowledge-base/SKILL.md。

在對話中的觸發意圖包括：提到知識庫、筆記、備忘錄、「幫我記一下」、「搜一下知識庫裏有沒有 XX」、上傳文件或收藏網頁等；模糊表述（未說明新建還是追加）時，技能要求 Agent 先向用戶確認，避免誤改已有筆記。

適用場景與注意¶

適合誰： 已在使用騰訊 IMA 做個人或團隊知識沉澱，並在 Cursor、OpenClaw 等支持 Skill 的 Agent 裏希望直接操作筆記與知識庫的用戶；也可作爲其他 Skill（例如依賴 ima 連接器的工作流）的基礎能力。

限制與坑：

• 必須自備 IMA OpenAPI 密鑰；鑑權失敗常見錯誤碼包括 20004（apikey 鑑權失敗）。
• 筆記寫入前須保證字符串爲合法 UTF-8；在 PowerShell 5.1 下向 API 發 JSON 需用 UTF-8 字節數組，否則中文易亂碼。
• 知識庫側不提供「新建知識庫」接口，庫需先在 IMA 客戶端創建；API 限頻超限可能返回 20002。
• 企業源 Skill，安裝與更新以 SkillHub / skillhub CLI 爲準；SkillHub 統計（截至頁面抓取）：評分 100000，下載約 638284，安裝約 11831。

結尾¶

ima-skills 把 IMA 的筆記讀寫與知識庫檢索、入庫流程收斂到一套 OpenAPI 驅動的 Agent Skill，減少「人在 IMA、Agent 在外」的割裂。若你要在對話裏直接管理第二大腦裏的內容，可從官方 Skill 頁與安裝指引入手：

• SkillHub：https://www.skillhub.cn/skills/tencent-adm/ima-skills
• 技能 API 入口：https://api.skillhub.cn/tencent-adm/ima-skills
• IMA 主頁：https://ima.qq.com