ima-copilot

IMA Copilot 是腾讯官方 IMA 技能（ima-skill）的封装层，定位为一键安装器、故障排查器与个性化层。官方 ima-skill 提供笔记与知识库操作的 OpenAPI，但其安装流程面向特定专有智能体，且近期版本附带的子模块文件会无法通过严格的 SKILL.md 加载器。IMA Copilot 针对这两点提供解决方案。

一、核心能力

1. 安装：一条命令经 vercel-labs/skills 开放安装器把 ima-skill 安装到 Claude Code、Codex、OpenClaw。
2. 配置：引导完成 API 密钥设置并做实时校验调用。
3. 诊断与修复：检测上游已知问题，在用户明确同意后原位修复，不 fork、不改写、不镜像上游包任何部分。
4. 扇出搜索：遵循用户配置的知识库优先级与加权，并识别每个知识库 100 条结果的截断上限。
5. 导入与提取：通过 OpenAPI 导入 URL，并把页面内容提取为结构化文本。

二、架构原则（强制遵守）

• 不复制上游文件：本技能目录不含 ima-skill 自身内容的任何拷贝、fork 或摘录，上游发布新版时用户直接获得新版，封装层不干扰。
• 修复发生在运行时而非发布时：如需修补上游缺陷，本技能携带“如何修补”的说明，而非已修补的文件；修复可重复执行，上游更新后重跑会重新检测并重新修复。
• 触碰上游文件前必须询问：修改 ~/.claude/skills/ima-skill/、~/.agents/skills/ima-skill/ 或其他上游安装目录，需经 AskUserQuestion 获得明确同意，无静默修补。
• 教学而非隐藏：应用修复时展示具体改动内容与备份位置，帮助用户学会自行维护安装。

三、主要能力与入口

1. 安装上游 ima-skill 到 3 个智能体 —— scripts/install_ima_skill.sh（详见 references/installation_flow.md）。安装器从 https://app-dl.ima.qq.com/skills/ 下载最新官方版本，暂存到临时目录，再交给 npx skills add <local-path> 分发。脚本自动检测已安装的目标智能体，未安装的静默跳过；已安装的以全局（-g）模式安装，首个检测到的智能体目录作为规范副本，其余以符号链接指向它，因此一次修复或升级会自动传播到所有智能体，diagnose.sh 会检测这种共享并去重报告。
2. 配置 API 凭据（XDG 风格）—— 凭据存储为 ~/.config/ima/client_id（权限 600）、~/.config/ima/api_key（权限 600）、~/.config/ima/（权限 700）。环境变量 IMA_OPENAPI_CLIENTID 与 IMA_OPENAPI_APIKEY 作为回退覆盖，封装层先读环境再读配置文件。流程：打开 https://ima.qq.com/agent-interface 创建 Client ID 与 API Key；写入 XDG 配置路径或导出环境变量；调用 https://ima.qq.com/openapi/wiki/v1/search_knowledge_base，参数 {"query": "", "cursor": "", "limit": 1} 做存活校验，返回 code: 0, msg: success 即为就绪。详见 references/api_key_setup.md。
3. 诊断与修复已知问题 —— scripts/diagnose.sh + 工作流（详见 references/known_issues.md）。这是本技能存在的根本原因。步骤一：运行只读诊断 bash scripts/diagnose.sh，它不修改任何文件，逐项打印结构化报告（安装状态、凭据有效性、ISSUE-001 等警告）。步骤二：解析报告中对每个 ⚠️ 或 ❌ 行，在 references/known_issues.md 中查找该问题（症状、根因、修复策略 A/B/跳过、每条策略的确切 shell 命令、涉及文件、上游尚未修复的可能原因）。步骤三：对存在多种修复策略的问题，使用 AskUserQuestion 征得明确同意，用用户能理解的语言描述缺陷影响与各策略的结果。步骤四：执行所选策略，所有修复命令均为幂等（重复执行无副作用并提示“已修复”）、先备份（复制原始文件到 /tmp/ima-copilot-backups/<timestamp>/<relative-path> 并告知位置）、可回滚（末尾给出单条 cp 恢复命令）。步骤五：重跑 diagnose 确认问题由 ⚠️ 变为 ✅；若未变，停止并向用户展示原始前后对比，而非静默重试。 关于上游更新：每次修复都是临时的，因为 ima-skill 升级会替换全部内容。这是有意设计——本技能不向上游争夺持久状态。用户升级后，诊断会再次标记该问题，可重跑修复；若上游最终修复该问题，修复不再必要，diagnose.sh 将直接报告 ✅ 且不再提示。
4. 个性化扇出搜索 —— scripts/search_fanout.py（详见 references/search_best_practices.md）。IMA OpenAPI 有三个硬性约束：无跨知识库端点（search_knowledge 单次调用需指定单个 knowledge_base_id，跨库搜索只能客户端扇出）；结果无相关度评分（info_list 项仅含 media_id、title、parent_folder_id、highlight_content，任何超出插入顺序的排序必须在客户端完成）；静默 100 条截断（search_knowledge 每库最多返回 100 条，且响应无 is_end 或 next_cursor 字段）。脚本读取 ~/.config/ima/copilot.json 做个性化（优先知识库、跳过列表、策略），调用 search_knowledge_base 枚举知识库，并行扇出 search_knowledge 调用，通过精确等于 100 的长度匹配检测截断，并按知识库分组渲染、优先组置顶。配置模板见 config-template/copilot.json.example；无配置文件的用户获得中立默认：扇出所有可访问知识库、按命中数排序分组、不加权。
5. 导入 URL 并提取内容 —— OpenAPI import_urls + notes API（详见 references/import_and_extract.md）。当需读取的页面本地机器无法抓取但 IMA 服务器可以时，用 wiki/v1/import_urls 导入，让 IMA 转为 JSON 保存为笔记并通过 API 读回。由于导入会写入用户账户且未有文档化的删除端点，操作前需与用户确认目标知识库与 URL 列表。

四、路由 触发本技能时按用户意图分类：说“装 ima / install ima-skill / 我想用 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”走能力 5；“帮我从头跑一遍 ima”按 1→2→3→4 顺序。不确定时从能力 3（诊断）开始，它可暴露哪些能力受阻及其顺序。

五、明确拒绝的行为

• 不复制上游内容：本目录不含且永不含 ima-skill/SKILL.md、ima-skill/notes/、ima-skill/knowledge-base/ 或其他上游文件。
• 不在 SKILL.md 中锁定上游版本：安装脚本为回退目的携带默认版本，但 SKILL.md 本身版本无关，以便在上游发布时不需提升本技能版本。
• 不静默修补上游文件：每条修改路径都需 AskUserQuestion 与用户主动选择。
• 不硬编码用户知识库名称：copilot.json 中 priority_kbs 与 skip_kbs 完全由用户配置，示例值仅作说明。
• 执行修复时绝不跳过备份步骤，无论差异多小。

六、文件布局 ima-copilot/ 下含 SKILL.md（入口与路由）；scripts/（install_ima_skill.sh、diagnose.sh、search_fanout.py）；references/（installation_flow.md、api_key_setup.md、known_issues.md、search_best_practices.md、import_and_extract.md）；config-template/（copilot.json.example，用于 ~/.config/ima/copilot.json 的模板）。