前言¶

在 Agent 里处理「帮我记一下」「把这份 PDF 放进资料库」「搜一下知识库里有没有某篇文档」这类请求时，常见做法是临时写脚本或手工打开 IMA 客户端。笔记写入、知识库上传、COS 分步上传和编码校验都散落在不同接口里，Agent 很难稳定走完整流程。

下面介绍 SkillHub 上的社区 Skill「小艺」（坐标 @user_2d38631d/27585e2da461584da9ba13574571ab56）。它把腾讯 IMA 的 OpenAPI 封装成统一的 SKILL.md 工作流，按用户意图在 notes（笔记） 与 knowledge-base（知识库） 两个子模块之间路由，并附带 ima_api.cjs 与上传前置检查脚本。

这是什么¶

一句话定位： 面向 Agent 的 IMA OpenAPI 技能包，当前覆盖笔记管理与知识库操作；官方主页为 ima.qq.com。

来源与版本： SkillHub 分类为 knowledge-management，来源 community，发布者 user_2d38631d，页面版本 v1.0.0（SkillHub 简介为「我的私人助手」；包内 SKILL.md 的 description 写明统一的 IMA OpenAPI 能力与触发意图）。SkillHub 统计（以页面抓取为准）：评分 100000，下载 1030；标签含 requires_api_key=false（与下文 IMA 凭证配置并存，以技能文档为准）。

解决什么问题： 让支持 Skills 的 Agent 在用户提到知识库、资料库、笔记、备忘录，或意图为上传文件、收藏网页、搜索知识库、读写个人文档时，按文档中的决策表调用对应 API，而不是每次从零拼请求。

核心功能¶

技能根目录将能力拆为两个子模块，Agent 应先读根 SKILL.md 的模块决策表，再进入子文档。

笔记（notes/）¶

通过 openapi/note/v1 支持：

• 读取：按标题或正文搜索（search_note）、列出笔记本（list_notebook）、列出笔记（list_note）、获取正文（get_doc_content）。
• 写入：新建笔记（import_doc）、向已有笔记追加（append_doc）。

文档强调：写入前所有字符串字段须为合法 UTF-8；append_doc 会修改已有笔记，目标不明确时需先向用户确认；笔记正文接口不支持本地图片路径。

知识库（knowledge-base/）¶

通过 openapi/wiki/v1 支持：

• 上传文件到知识库（check_repeated_names → create_media → COS 上传 → add_knowledge），含 preflight-check.cjs、cos-upload.cjs 等步骤。
• 导入网页/微信文章（import_urls）、将已有笔记关联到知识库（add_knowledge，media_type=11）。
• 查询：知识库信息、目录浏览、内容搜索、按名称搜知识库、可添加的知识库列表、媒体原文（get_media_info，笔记类型会跨模块到 notes 读正文）。

限制在文档中写清：不支持的视频、B 站/YouTube、file:// 等需引导用户使用 IMA 桌面客户端；文件上传时 title 必须与 file_name（含扩展名）一致。

统一调用与更新¶

• 请求发往 https://ima.qq.com，由包内 ima_api.cjs 封装；凭证通过环境变量或 ~/.config/ima/ 下的 client_id、api_key 提供。
• 运行时依赖 Node.js ≥ 18.0.0（见包内 meta.json 的 required_binaries）。
• 内置按日的 Skill 更新检查；错误码 -200 表示需先按指引更新后再重试原请求。

安装与启用¶

1、安装 SkillHub CLI（若尚未安装）¶

command -v skillhub && skillhub --version

未安装时可按 SkillHub 安装文档执行完整安装或仅 CLI：

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

2、安装「小艺」到当前 Agent 的 skills 目录¶

SkillHub 页面给出的安装提示为：参照 skillhub.md，安装坐标 @user_2d38631d/27585e2da461584da9ba13574571ab56。命令行示例（--dir 须指向本 Agent 实际识别的 skills 目录）：

skillhub install '@user_2d38631d/27585e2da461584da9ba13574571ab56' --dir ~/.cursor/skills/

常见路径（来自 SkillHub 安装文档，按你所用客户端择一）：

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

安装后通常需重启或刷新 Agent，使其加载新 Skill。

3、配置 IMA OpenAPI 凭证¶

在调用任何 API 前，从 https://ima.qq.com/agent-interface 获取 Client ID 与 API Key。

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

Agent 按环境变量优先、其次配置文件读取；缺失时 ima_api.cjs 会以 code: -100 退出。凭证仅作为 HTTP 头发往 ima.qq.com；文件上传流程还会使用 IMA 返回的 COS 临时凭证访问 *.myqcloud.com。

典型用法¶

以下示例摘自技能包内文档，展示 Agent 或你在终端中复现时的调用形态。实际路径中的 SKILL_DIR 应替换为安装后的技能目录。

列出笔记（节选）¶

SKILL_DIR="/path/to/@user_2d38631d/27585e2da461584da9ba13574571ab56"
OPTS=$(printf '{"clientId":"%s","apiKey":"%s"}' "$IMA_OPENAPI_CLIENTID" "$IMA_OPENAPI_APIKEY")
node "$SKILL_DIR/ima_api.cjs" "openapi/note/v1/list_note" '{"folder_id":"","sort_type":0,"cursor":"","limit":20}' "$OPTS"

在知识库中搜索¶

node "$SKILL_DIR/ima_api.cjs" "openapi/wiki/v1/search_knowledge" '{"query":"关键词","knowledge_base_id":"<kb_id>","cursor":""}' "$OPTS"

上传文件前的类型检查¶

上传 PDF 等文件前，须先跑前置检查（pass=false 则终止并向用户说明原因）：

node "$SKILL_DIR/knowledge-base/scripts/preflight-check.cjs" --file "/path/to/report.pdf"

完整上传链路（重名检查、create_media、COS、add_knowledge）见 knowledge-base/SKILL.md 中的「上传文件到知识库」章节。

触发意图（Agent 侧）¶

包内 description 约定：用户提到知识库、笔记、备忘录，或意图为上传文件、添加网页、搜索资料、个人文档存取（例如「帮我记一下」「搜一下知识库里有没有 XX」）时，应启用本 Skill；笔记与知识库混用时须按根 SKILL.md 的「跨模块任务」表顺序读取两个子模块再执行。

适用场景与注意¶

适合谁： 已在使用腾讯 IMA 存笔记与知识库，并希望 Cursor、Claude Code、Codex 等 Agent 在对话中完成搜索、新建/追加笔记、上传文件或导入链接的开发者。

需要注意：

• 必须有 IMA 账号及 OpenAPI 凭证；SkillHub 页面的 requires_api_key=false 指商店元数据，不等于无需 IMA 密钥。
• Windows 上若在 PowerShell 5.1 中自行发 HTTP 请求，须按根 SKILL.md 使用 UTF-8 字节数组，否则中文易乱码；优先通过 ima_api.cjs 调用。
• 社区来源（community），能力与接口以 IMA 官方 OpenAPI 及包内 references/api.md 为准；包内 ima_api 可能提示版本更新（SkillHub 列表版本与包内 meta.json 的 version 字段可能不一致，以安装包内容为准）。

结尾¶

「小艺」把 IMA 笔记与知识库的 OpenAPI 收敛成可路由的 Agent Skill：先按意图选 notes 或 knowledge-base，再走文档中的门禁（编码、文件类型、重名、COS 上传结果）和统一 ima_api.cjs 调用。

• SkillHub 页面：https://www.skillhub.cn/skills/user_2d38631d/27585e2da461584da9ba13574571ab56
• API 元数据地址：https://api.skillhub.cn/user_2d38631d/27585e2da461584da9ba13574571ab56
• IMA 主页：https://ima.qq.com