IMA Copilot 是腾讯 IMA 官方技能（ima-skill）的安装器、故障排查与个性化配套层。官方 ima-skill 提供笔记与知识库操作的 OpenAPI，但安装流程面向特定专有智能体，且近期版本包含会导致严格 SKILL.md 加载器失败的子模块文件，本工具即用于解决这两类问题。
【用途】将官方 ima-skill 安装到 Claude Code、Codex 与 OpenClaw；引导配置 API 凭据；检测并修复已知上游问题；提供带优先级加权的跨知识库扇出搜索。
【主要能力】
- 安装：运行 bash scripts/install_ima_skill.sh，脚本从 https://app-dl.ima.qq.com/skills/ 下载最新官方版本，暂存于临时目录，再交给 npx skills add <local-path> 分发。脚本自动检测三个目标智能体是否已安装，未安装者静默跳过；已安装者以全局（-g）默认符号链接模式安装，首个检测到的智能体目录为规范副本，其余智能体符号链接到它，使一次修复或升级自动传播到所有智能体。
- 凭据配置：凭据按 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，写入配置路径或导出环境变量，再向 https://ima.qq.com/openapi/wiki/v1/search_knowledge_base 发起一次带 {"query": "", "cursor": "", "limit": 1} 的存活性调用，返回 code: 0, msg: success 即表示就绪。
- 诊断与修复：运行 bash scripts/diagnose.sh 生成只读结构化报告，每项检查一行，例如上游技能是否安装、凭据是否有效、是否存在 ISSUE-001（notes/SKILL.md 或 knowledge-base/SKILL.md 缺失 YAML frontmatter）等。每个问题在 references/known_issues.md 中记录症状、根因、可选修复策略（A、B、跳过）、精确命令、涉及文件与上游未修复原因。存在多种策略时须通过 AskUserQuestion 征得用户明确同意，不允许静默修补。修复命令保证幂等（重复执行无副作用并提示已修复）、执行前备份原文件到 /tmp/ima-copilot-backups/<timestamp>/<relative-path>、并可用一条 cp 命令回滚。修复后再次运行 diagnose.sh 确认问题由 ⚠️ 变为 ✅；若未变化则停止并向用户展示前后原始信息。上游升级会覆盖修复，升级后可重新运行修复；若上游自行修复，诊断将直接显示 ✅ 且不再提示。
- 扇出搜索：python3 scripts/search_fanout.py "<query>"，读取 ~/.config/ima/copilot.json 中的个性化配置（优先知识库、跳过列表、策略），调用 search_knowledge_base 枚举知识库，并行调用 search_knowledge，按结果长度恰为 100 判定截断，并按知识库分组呈现，优先组置顶。无配置文件时使用中性默认：扇出所有可访问知识库、按命中数排序、不加权。 【路由】用户说“装 ima”“install ima-skill”等进入安装；“配 key”“ima API key”进入凭据配置；“ima 报错”“SKILL.md warning”“加载失败”进入诊断修复；“搜 X”“跨知识库搜索”进入扇出搜索；要求“从头跑一遍”则按 1→2→3→4 顺序执行；不确定时从诊断开始，因为它会显示哪些能力受阻及顺序。
【限制与约束】IMA OpenAPI 无跨知识库接口，每次 search_knowledge 只能指定单个 knowledge_base_id；结果不含相关性评分，仅含 media_id、title、parent_folder_id、highlight_content，排序需在客户端完成；每库最多返回 100 条且无 is_end 或 next_cursor 字段，高频查询会被静默截断。此外，本工具不内置、分叉或镜像任何上游文件；不在 SKILL.md 中固定上游版本；不静默修改上游文件；不硬编码用户知识库名称；任何修复都不跳过备份步骤。