ima-copilot

IMA Copilot

用于安装、排障和个性化官方 Tencent IMA 技能的一键工具。

概览

官方 Tencent IMA 技能（ima-skill）提供了功能强大的 OpenAPI，可用于笔记和知识库操作，但其安装流程针对特定专有 Agent 设计，且近期发布的版本附带的子模块文件无法通过严格的 SKILL.md 加载器检查。IMA Copilot 解决了这两个问题：

1. 通过 vercel-labs/skills 开源安装器，只需一条命令即可将 ima-skill 安装到 Claude Code、Codex 和 OpenClaw。
2. 引导用户设置 API 密钥，并通过实时验证调用进行检查。
3. 检测已知的上游问题，并在征得用户明确同意后就地修复，绝不分叉、内置或镜像上游包的任何部分。
4. 提供扇出搜索策略，遵循用户配置的知识库优先级和权重，并考虑每个知识库最多截断至 100 条结果的限制。

架构原则（不得违反）

此技能是 ima-skill 的包装层。包装层契约不可妥协：

• 绝不内置上游文件。 此技能目录不包含 ima-skill 自身内容的任何副本、分叉或摘录。ima-skill 发布新版本时，用户可以不受此包装层干扰地获取新版本。
• 在运行时修复，而非发布时修复。 如果需要修补上游 Bug，此技能只携带修补说明，不携带修补后的文件。修复操作具有幂等性：上游更新后重新运行，会再次检测并修复所有复现的问题。
• 修改上游文件前务必征求同意。 修改 ~/.claude/skills/ima-skill/**、~/.agents/skills/ima-skill/** 或任何其他上游安装目录，都必须通过 AskUserQuestion 征得用户明确同意。不得静默修补。
• 重在讲解，而非隐藏。 应用修复后，准确告知用户修改了什么以及备份保存在哪里。这样用户才能学会维护自己的安装。

此技能的功能

功能	入口点	详情
1. 将上游 ima-skill 安装到 3 个 Agent	scripts/install_ima_skill.sh	参见 references/installation_flow.md
2. 配置 API 凭据（XDG 风格）	下方的内联工作流	参见 references/api_key_setup.md
3. 诊断并修复已知上游问题	scripts/diagnose.sh + 下方的工作流	参见 references/known_issues.md
4. 使用优先级加权进行扇出搜索	scripts/search_fanout.py	参见 references/search_best_practices.md
5. 导入 URL 并将页面内容提取为结构化文本	OpenAPI import_urls + 笔记 API	参见 references/import_and_extract.md

路由

触发此技能时，根据用户意图进行分类，并跳转到相应功能：

用户可能会这样说……	前往
“装 ima”、“install ima-skill”、“把 ima 装一下”、“我想用 ima”	功能 1
“配 ima 的 key”、“configure ima credentials”、“ima API key”	功能 2
“ima 报错”、“SKILL.md warning”、“frontmatter 错误”、“ima 加载失败”	功能 3
“搜 X”、“在 ima 里搜 X”、“跨知识库搜索”、“扇出搜 X”	功能 4
“把这批链接导进 ima 并整理成结构化内容”、“import URLs into a knowledge base”、“让 ima 读这些页面”	功能 5
“帮我从头跑一遍 ima”	依次执行 1 → 2 → 3 → 4

不确定时，从功能 3（诊断）开始——它会准确指出哪些功能受阻以及应按什么顺序处理。

能力 1：安装上游 ima-skill

安装程序会从 https://app-dl.ima.qq.com/skills/ 下载最新官方版本，将其暂存到临时目录，然后交由 npx skills add <local-path> 在 Claude Code、Codex 和 OpenClaw 中分发。

运行方式：

bash scripts/install_ima_skill.sh

脚本会自动检测用户设备上安装了上述三个目标 Agent 中的哪些。对于未安装的 Agent，脚本会静默跳过，不会安装到用户未选择使用的任何位置。对于已安装的 Agent，脚本会使用 vercel skills 的默认符号链接模式进行全局安装（-g）：第一个检测到的 Agent 目录会成为规范副本，其余 Agent 则通过符号链接指向该副本。这意味着只需应用一次修复或升级，就会自动同步到所有 Agent；diagnose.sh 会检测到这种共享，并在报告中去重，避免同一问题重复出现。

如需了解版本覆盖、检测逻辑、故障排查，以及安装程序生成的完整逐文件布局，请阅读 references/installation_flow.md。

能力 2：配置 API 凭据

凭据以 XDG 风格存储，与任何 Agent 的技能目录分离：

• ~/.config/ima/client_id（模式 600）
• ~/.config/ima/api_key（模式 600）
• ~/.config/ima/（模式 700）

环境变量 IMA_OPENAPI_CLIENTID 和 IMA_OPENAPI_APIKEY 可作为备用覆盖值——封装脚本会优先读取环境变量，然后再读取配置文件。

引导用户完成设置：

1. 打开 https://ima.qq.com/agent-interface，创建新的 Client ID 和 API Key。
2. 将两个值写入 XDG 配置路径（或导出环境变量）。
3. 使用 {"query": "", "cursor": "", "limit": 1} 向 https://ima.qq.com/openapi/wiki/v1/search_knowledge_base 发起一次存活性调用，确认凭据已被接受——若返回 code: 0, msg: success，则表示已就绪。

完整脚本以及确切的请求／响应架构见 references/api_key_setup.md。

能力 3：诊断并修复已知问题

这正是此技能存在的原因。上游软件包存在真实缺陷，会导致某些 Agent 无法加载；虽然修复方案已明确，但应用修复前必须征得用户同意。诊断／修复工作流是此技能的核心约定。

步骤 1 — 运行只读诊断

bash scripts/diagnose.sh

diagnose.sh 绝不会修改任何文件。它会为每项检查打印一行结构化报告：

✅ upstream ima-skill installed (claude-code)
✅ upstream ima-skill installed (codex)
❌ upstream ima-skill NOT installed (openclaw)
✅ API credentials valid (search_knowledge_base returned 12 KBs)
⚠️ ISSUE-001: notes/SKILL.md missing YAML frontmatter (claude-code)
⚠️ ISSUE-001: knowledge-base/SKILL.md missing YAML frontmatter (claude-code)
⚠️ ISSUE-001: notes/SKILL.md missing YAML frontmatter (codex)
⚠️ ISSUE-001: knowledge-base/SKILL.md missing YAML frontmatter (codex)

步骤 2 — 解析报告并询问用户

对于每一行 ⚠️ 或 ❌，请在 references/known_issues.md 中查找相应问题。该文件是以下信息的权威来源：

• 问题的具体情况（症状、根本原因）
• 可用的修复策略（A、B、skip）
• 每种策略对应的确切 shell 命令
• 每种策略会改动哪些文件
• 上游维护者可能尚未修复该问题的原因

步骤 3 — 修改上游文件前征求明确同意

对于每个有多种修复策略的问题，都要使用 AskUserQuestion。表述要直白——用户可能不知道“YAML frontmatter”是什么意思。用用户能理解的说法描述该缺陷会造成什么影响（“加载器会静默跳过两个文件，因此笔记搜索和知识库搜索实际上无法使用”），然后从结果而非实现机制的角度介绍每种策略。

如果存在多种策略，绝不要只提供一个“直接修复”的选项。用户的选择可能确实会因技能无法获知的因素而不同——例如，如果用户计划手动与上游版本对比，他们可能更倾向于策略 B（最小差异）。

第 4 步 — 执行选定的策略

references/known_issues.md 中的每条修复命令都遵循以下设计：

• 幂等 — 修复已应用后再次运行不会造成任何损害，并会清楚地显示“已修复”消息。
• 有备份 — 修改任何内容前，修复命令会将原始文件复制到 /tmp/ima-copilot-backups/<timestamp>/<relative-path>，然后告知用户备份位置。
• 可撤销 — 用户可以使用末尾显示的单条 cp 命令从备份中还原。

第 5 步 — 重新运行 diagnose 进行确认

修复后，再次运行 diagnose.sh 并向用户展示差异。问题应从 ⚠️ 变为 ✅。如果没有变化，请停止，并向用户展示原始的前后内容，不要静默重试——此处的意外失败通常意味着上游发布了未预料到的变更。

关于上游更新的重要说明

每次修复都是临时的，因为 ima-skill 升级会替换所有内容。这是有意为之：该技能不会与上游争夺持久状态。用户通过 Capability 1 升级 ima-skill 后，diagnose 的第 4 步会再次标记已修复的问题，用户可以重新运行修复。这是特性，不是缺陷——如果上游最终修复了该问题，修复就不再需要，diagnose.sh 会报告 ✅，且不显示提示。

Capability 4：个性化扇出搜索

IMA 的 OpenAPI 有三项硬性限制，任何可靠的搜索工作流都必须考虑：

1. 没有跨知识库端点。 search_knowledge 每次调用都需要一个 knowledge_base_id。跨知识库搜索是在客户端进行扇出，而不是 API 功能。
2. 结果中没有相关性分数。 info_list 项只包含 media_id、title、parent_folder_id 和 highlight_content。任何超出插入顺序的排序都必须在客户端完成。
3. 静默截断为 100 条结果。 search_knowledge 每个知识库最多返回 100 条结果，响应中没有 is_end 或 next_cursor 字段。高频查询会被静默截断。

scripts/search_fanout.py 实现了完整的变通方案：

python3 scripts/search_fanout.py "<query>"

该脚本会读取 ~/.config/ima/copilot.json 获取个性化设置（优先知识库、跳过列表、策略），调用 search_knowledge_base 枚举知识库，并行扇出调用 search_knowledge，通过结果数量恰好为 100 检测截断情况，然后按知识库分组呈现结果，并将优先组置于顶部。

个性化设置文件是每位用户独有且私有的。此技能仅提供模板——请参阅 config-template/copilot.json.example。没有配置文件的用户会获得中性默认设置：扇出搜索所有可访问的知识库，按命中数对分组排序，不进行加权。

有关完整算法、截断处理策略、呈现格式，以及允许“跳过知识库子集”的循证决策说明（例如，经过整理的知识库是主知识库的严格子集，因此可以安全跳过以减少重复结果），请阅读 references/search_best_practices.md。

Capability 5：导入 URL 并提取内容

如果要读取的页面无法由本地计算机获取，但 IMA 服务器可以获取，请使用 wiki/v1/import_urls 导入页面，让 IMA 将其转换为 JSON，保存为笔记，再通过 API 读回。导入会写入用户账户，且没有文档记录的删除端点，因此请先与用户确认目标知识库和 URL 列表。开始前请阅读 references/import_and_extract.md：该文档列出了上游 ima-skill 文档中未提及的功能（删除、读取完整条目正文）及原因、为何要通过桌面应用进行提取、条目如何异步解析、提取协议及其已测量的失败模式（未转义的引号、截断轮次、空占位对象），以及桌面应用自动化的陷阱。

本技能拒绝做的事

• 绝不打包上游内容。 此目录不包含，也绝不会包含 ima-skill/SKILL.md、ima-skill/notes/**、ima-skill/knowledge-base/** 或任何其他上游文件的副本。任何人试图将此类文件添加到本技能中，都应予以拒绝。
• 绝不在 SKILL.md 中固定上游版本。 安装脚本会携带一个默认版本以备回退，但 SKILL.md 本身与版本无关，以便上游发布新版本时无需更新技能。
• 绝不静默修补上游文件。 每条修改路径都必须明确提出 AskUserQuestion，并由用户主动选择。
• 绝不硬编码用户的知识库名称。 copilot.json 中的 priority_kbs 和 skip_kbs 字段完全由用户配置。config-template/copilot.json.example 中的示例值仅供说明。
• 执行修复时绝不跳过备份步骤，无论差异多么微小。

文件布局

ima-copilot/
├── SKILL.md                         # This file — entry and routing
├── scripts/
│   ├── install_ima_skill.sh         # Download → stage → npx skills add to 3 agents
│   ├── diagnose.sh                  # Read-only health report
│   └── search_fanout.py             # Fan-out search with priority grouping
├── references/
│   ├── installation_flow.md         # Capability 1 deep dive
│   ├── api_key_setup.md             # Capability 2 deep dive
│   ├── known_issues.md              # Issue registry — source of truth for repairs
│   ├── search_best_practices.md     # Capability 4 deep dive
│   └── import_and_extract.md        # Capability 5 deep dive
└── config-template/
    └── copilot.json.example         # Template for ~/.config/ima/copilot.json