前言¶

在 Cursor、Claude Code 等环境里，用户常会随口说「把这份 PDF 放进知识库」「搜一下笔记里有没有某段话」。若没有成体系的 Skill，Agent 要么无法调用腾讯 IMA 的 OpenAPI，要么把「往笔记追加内容」和「把笔记挂到知识库」混成一类操作，容易误改已有笔记或走错上传链路。

下面介绍 SkillHub 上的 IMA小龙虾API对接技能 | 星核总链路互联（坐标 @user_32bcb989/ima-lobster-link）。技能包内的 SKILL.md 将其定位为统一的 IMA OpenAPI 对接能力，当前覆盖 笔记（notes） 与 知识库（knowledge-base） 两大模块；商店页简介则补充了与本地四合一面板、星核总调度、MCP 等链路的集成背景。按官方安装方式装入 Agent 的 skills 目录后，可在对话中按意图路由到对应子模块，并通过 ima_api.cjs 调用 https://ima.qq.com 官方接口。

这是什么¶

• 一句话定位：面向 Agent 的 IMA OpenAPI Skill，用 Client ID + API Key 鉴权，通过脚本封装 HTTP POST 调用，完成笔记读写与知识库检索、上传、收藏等操作。
• 来源与版本：SkillHub 社区技能，发布者 user_32bcb989，分类 dev-programming；商店页标注版本 1.0.0（截至 2026-10-22 页面信息）。技能包内 meta.json 还带有运行时元数据（如内置 API 封装版本 1.1.7、依赖 Node.js ≥ 18.0.0），与商店展示版本号可能不一致，以实际安装包为准。
• 商店数据（已抓取资料）：评分 100000，下载 1513 次；标签含 requires_api_key=false（指 SkillHub 安装本身不要求商店 API Key，不等于无需 IMA 开放平台凭证）。
• 官方入口：SkillHub 技能页、api.skillhub.cn 坐标页。

核心功能¶

以下能力均来自技能包 SKILL.md 及子模块说明，可与 IMA 官网 对照。

笔记模块（notes/）¶

• 读取：搜索笔记（search_note）、列笔记本/笔记（list_notebook、list_note）、获取正文（get_doc_content）。
• 写入：新建笔记（import_doc）、向指定笔记追加（append_doc）。
• 约束：写入前须保证 content、title 等为合法 UTF-8；append_doc 会修改已有笔记，意图不明确时 Skill 要求先向用户确认目标笔记。

知识库模块（knowledge-base/）¶

• 上传本地文件到知识库（check_repeated_names → create_media → COS 上传 → add_knowledge），title 必须与原始 file_name（含扩展名）一致。
• 添加网页/链接（import_urls）、将已有笔记关联到知识库（add_knowledge，media_type=11）。
• 浏览与搜索：知识库列表与详情、目录内条目、关键词搜索（search_knowledge、search_knowledge_base、get_knowledge_list 等）。
• 上传前经 preflight-check.cjs 做类型校验；不支持的视频、B 站/YouTube 链接、file:// 等需提示用户使用 IMA 桌面客户端。

Agent 侧触发与路由¶

技能 description 约定：当用户提到知识库、资料库、笔记、备忘录，或意图为上传文件、收藏网页、搜索知识库、个人文档存取（如「帮我记一下」「搜一下知识库里有没有 XX」）时，应启用本 Skill。根 SKILL.md 中的模块决策表区分 notes 与 knowledge-base，并列出易混淆场景（例如「往知识库里的某篇笔记追加内容」应走 notes 的 append_doc，而非知识库上传流程）。

安全与依赖说明¶

• 凭证仅作为 HTTP 头发往 ima.qq.com；文件上传流程会使用 IMA 返回的临时凭证访问 *.myqcloud.com，Client ID / API Key 不发往 COS。
• 运行依赖 Node.js 18+（执行 ima_api.cjs、COS 上传与预检脚本）。

安装与启用¶

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

command -v skillhub && skillhub --version

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

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

2、安装本技能到当前 Agent 的 skills 目录¶

安装时必须使用 --dir 指向 Agent 实际读取的目录，否则默认落在 ./skills/ 可能无法被识别。

skillhub install @user_32bcb989/ima-lobster-link --dir ~/.cursor/skills/

其他常见路径（同一文档摘录）：Claude Code 为 ~/.claude/skills/；Codex 为 ~/.codex/skills/ 或项目下 .agents/skills/。装好后按所用客户端要求重启或刷新 Agent。

也可将下列提示交给 AI，让其按官方指引安装：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_32bcb989/ima-lobster-link`。

3、配置 IMA OpenAPI 凭证¶

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

方式 A — 配置文件（Skill 推荐）：

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 按环境变量优先、其次配置文件的顺序读取；缺失时 node ima_api.cjs ... 会以错误码 -100 退出并在 stderr 给出说明。

典型用法¶

凭证自检¶

技能根目录提供检查逻辑，安装后 Agent 可先确认凭证是否就绪（对应 SKILL.md 中的 Credential Check）。

调用 OpenAPI 的通用模板¶

所有请求为 HTTP POST + JSON，经 ./ima_api.cjs 发往 https://ima.qq.com。下面示例列出笔记（openapi/list_docs），并演示 stderr 上的 -100 / -200 与 stdout 业务 code 的分层处理思路：

SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
OPTS=$(printf '{"clientId":"%s","apiKey":"%s"}' "$IMA_OPENAPI_CLIENTID" "$IMA_OPENAPI_APIKEY")

if ! resp=$(node "$SKILL_DIR/ima_api.cjs" "openapi/list_docs" '{"limit":10}' "$OPTS" 2>/tmp/ima_err); then
  err_json=$(cat /tmp/ima_err)
  err_code=$(echo "$err_json" | jq -r '.code // empty' 2>/dev/null)
  err_msg=$(echo "$err_json" | jq -r '.msg // empty' 2>/dev/null)

  if [ "$err_code" = "-200" ]; then
    echo "[update] $err_msg" >&2
  else
    echo "[error] $err_msg" >&2
  fi
  exit 1
fi

echo "$resp"

具体接口路径与参数以子模块为准：笔记见 notes/SKILL.md（基路径 openapi/note/v1），知识库见 knowledge-base/SKILL.md（基路径 openapi/wiki/v1）。跨模块任务（例如「把知识库内容记到笔记」）要求先读两个子模块再按顺序调用。

对话侧示例意图¶

适用场景与注意¶

适合谁

• 已在使用腾讯 IMA，希望在 Coding Agent 里用自然语言管理个人笔记与知识库的团队或个人。
• 需要把 OpenAPI 调用、UTF-8 校验、文件上传门禁、错误码分层等规则固化在 Skill 里，减少每次手写脚本的维护成本。

限制与坑

1. 编码：笔记写入必须 UTF-8；在 PowerShell 5.1 下所有 API 请求需将 Body 转为 UTF-8 字节数组，否则中文可能静默乱码（根 SKILL.md 有检测模板）。
2. 文件与链接：不支持类型须直接拒绝，不要建议用户「强行上传」；大文件与 COS 上传失败时不得继续调用 add_knowledge。
3. 版本：ima_api.cjs 默认每天首次调用检查 Skill 更新；返回 -200 时原请求未发送，需按 stdout 中的 instruction 引导更新后重试。可设置 export IMA_FORCE_UPDATE_CHECK=1 主动触发检查。
4. 商店简介与包内定位：SkillHub 页强调星核链路、WebSocket 运维等集成叙事；日常 Agent 开发以包内 IMA OpenAPI 笔记/知识库 文档为准，避免按商店一句话误解能力边界。
5. 隐私：笔记正文属隐私数据；Skill 要求群聊场景只展示标题与摘要。

结尾¶

IMA小龙虾API对接技能 | 星核总链路互联 把 IMA OpenAPI 的笔记与知识库能力收敛成一套可安装的 Agent Skill：凭证走官方域名，调用经 ima_api.cjs 统一出口，子模块文档覆盖搜索、读写、上传与易混淆意图的路由规则。若你的对话里经常出现知识库上传、网页收藏或笔记检索，可按上文安装到对应 skills 目录并配置 Client ID / API Key 后启用。

官方地址：https://www.skillhub.cn/skills/user_32bcb989/ima-lobster-link