前言¶

做知识管理时，常见做法是：人在 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