前言¶
在 Cursor、Claude Code 等环境里，用户常说「帮我把这份 PDF 放进资料库」「搜一下笔记里有没有上次会议纪要」「记一下这段话」。若没有成体系的 Skill，Agent 要么无法对接腾讯 IMA，要么在「笔记写入」和「知识库上传」之间路由错误。酷斗斗是 SkillHub 上的社区 Skill（坐标 @user_034dd33d/ludouxi159），把 IMA OpenAPI 的笔记与知识库能力收进一套 SKILL.md 工作流，由 Agent 按意图选子模块并调用封装脚本。
这是什么¶
酷斗斗在 SkillHub 展示名称为「酷斗斗」，包内 Skill 标识为 ima-skill，版本 1.0.0（社区来源 community，分类 knowledge-management）。官方一句话简介是「这是我的外脑」；完整说明写明：统一的 IMA OpenAPI 技能，支持笔记管理和知识库操作。关联产品主页为 https://ima.qq.com。
发布者为 user_034dd33d。SkillHub 页面统计（截至资料抓取）：评分 100000，下载 930 次；标签 requires_api_key=false 指 SkillHub 安装本身不要求商店 API Key，不等于无需 IMA 凭证——实际调用仍须配置 IMA OpenAPI 的 Client ID 与 API Key。
核心功能¶
下面只列 Skill 文档中已写明的能力划分。
笔记（notes 子模块）¶
- 读取：按标题或正文搜索（
search_note）、列出笔记本（list_notebook）、列出笔记（list_note）、获取正文（get_doc_content）。 - 写入：新建笔记（
import_doc）、向已有笔记追加（append_doc）。 - 规则：写入前字符串须为合法 UTF-8；
append_doc会修改已有笔记，目标不明确时要先向用户确认；笔记正文不支持本地图片路径，仅保留http(s)图片链接。
知识库（knowledge-base 子模块）¶
- 上传文件到知识库：
check_repeated_names→create_media→ COS 上传 →add_knowledge（含preflight-check.cjs、cos-upload.cjs辅助脚本）。 - 导入网页/微信文章：
import_urls。 - 将笔记关联到知识库：
add_knowledge（media_type=11）。 - 浏览与检索：知识库列表/搜索（
search_knowledge_base、get_knowledge_list、search_knowledge等）、获取媒体信息（get_media_info）。 - 限制：不支持视频、Bilibili/YouTube 链接、
file://等；不支持的类型应直接拒绝，不要建议「强行试传」。
路由与跨模块¶
主 SKILL.md 提供「模块决策表」：操作笔记内容走 notes；上传文件、加链接、把笔记挂到知识库走 knowledge-base。若用户意图同时涉及两边（例如「把知识库里的内容记到笔记」），须先读两个子模块文档再按顺序调用。所有 HTTP 请求经 ./ima_api.cjs 发往 https://ima.qq.com；文件上传还会使用 IMA 返回的临时 COS 凭证（*.myqcloud.com）。
运行时依赖见包内 meta.json：Node.js ≥ 18.0.0（用于 .cjs 脚本与 JSON 处理）。
安装与启用¶
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 路径，否则默认落在 ./skills/ 可能不会被加载。
skillhub install ludouxi159 --namespace user_034dd33d --dir <你的 skills 目录>
常见路径（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
SkillHub 页面亦提示：可根据 https://skillhub.cn/install/skillhub.md 安装 @user_034dd33d/ludouxi159。安装后按所用客户端要求重启或刷新 Agent。
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 给出说明。凭证仅作为请求头发往 ima.qq.com，Skill 安全说明中写明不会写入日志或发往其他域名。
典型用法¶
下列示例摘自 Skill 自带的笔记子模块文档；实际执行时需将 ima_api 替换为包目录下的 node ima_api.cjs 调用方式（主 SKILL.md 中有带 OPTS 的完整 bash 模板）。
搜索并阅读笔记：
# 1. 按标题搜索
ima_api "openapi/note/v1/search_note" '{"search_type": 0, "query_info": {"title": "会议纪要"}, "start": 0, "end": 20}'
# 2. 读取正文（target_content_format: 0 为纯文本）
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正文内容"}'
上传文件到知识库（概念流程）： 先对本地文件运行 knowledge-base/scripts/preflight-check.cjs 做类型检查，再 check_repeated_names → create_media → cos-upload.cjs → add_knowledge；title 必须与原始 file_name（含扩展名）一致。大文件上传可为 cos-upload.cjs 显式设置更长 --timeout。
用户在对话中的自然语言触发范围（Skill 描述原文）：提到知识库、资料库、笔记、备忘录、上传文件、网页收藏、知识搜索，或「帮我记一下」「搜一下知识库里有没有 XX」等意图时，应启用本 Skill。
适用场景与注意¶
适合谁： 已在使用腾讯 IMA 存资料与个人笔记，并希望 Cursor / Claude Code / Codex 等 Agent 通过 OpenAPI 完成搜索、读写、上传，而不是手动打开客户端操作的用户。
需要注意：
- 凭证与合规：须自行申请并保管 IMA OpenAPI 密钥；群聊场景下笔记正文属隐私，Skill 要求只展示标题与摘要。
- 编码与环境：Windows PowerShell 5.1 向 API 发 JSON 时可能静默转码导致中文乱码，Skill 要求检测版本并用 UTF-8 字节数组发 Body；笔记写入前必须校验 UTF-8。
- 版本与更新：
ima_api.cjs内置每日首次调用的更新检查；返回-200时表示需先按指引更新 Skill 再重试原请求。包内meta.json记录的脚本元数据版本可能与 SkillHub 展示的 1.0.0 并存，以安装后的文件为准。 - 能力边界：视频、部分外链、本地图片插入笔记等场景需改用 IMA 桌面端或调整内容形式。
结尾¶
酷斗斗把 IMA 的笔记与知识库 API 收敛成可安装的 Agent Skill：安装到正确的 skills 目录、配置 IMA 凭证后，Agent 可按文档中的决策表路由请求，并用 ima_api.cjs 与辅助脚本完成常见读写与上传流程。
