ima-copilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

IMA Copilot

One-command installer, troubleshooter, and personalization layer for the official Tencent IMA skill.

官方腾讯IMA skill的一站式命令行安装器、故障排查工具与个性化配置层。

Overview

概述

The official Tencent IMA skill (ima-skill) exposes a powerful OpenAPI for notes and knowledge base operations, but its installation flow is designed for a specific proprietary agent and recent releases have shipped submodule files that fail strict SKILL.md loaders. IMA Copilot solves both problems:

Installs ima-skill to Claude Code, Codex, and OpenClaw in a single command via the vercel-labs/skills open installer.
Walks the user through API key setup with a live validation call.
Detects known upstream issues and — with explicit user consent — fixes them in place, without ever forking, vendoring, or mirroring any part of the upstream package.
Provides a fan-out search strategy that respects user-configured knowledge base priorities and boosts, with awareness of the 100-result per-KB truncation limit.

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

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

Architectural principles (do not violate)

架构原则（不得违反）

This skill is a wrapper layer around ima-skill. The wrapper contract is non-negotiable:

Never vendor upstream files. This skill directory does not contain any copy, fork, or excerpt of ima-skill's own content. When ima-skill ships a new release, users get the new release without any interference from this wrapper.
Repairs happen at runtime, not at ship time. If an upstream bug needs patching, this skill carries the instructions for how to patch, not the patched files. Running a repair is idempotent: rerunning after an upstream update re-detects and re-fixes anything that came back.
Always ask before touching upstream files. Modifying
```
~/.claude/skills/ima-skill/**
```
,
```
~/.agents/skills/ima-skill/**
```
, or any other upstream install directory requires explicit user consent via AskUserQuestion. No silent patching.
Teach rather than hide. When a fix is applied, show the user exactly what changed and where the backup was saved. This is how users learn to maintain their own installs.

本skill是ima-skill的封装层。封装协议不可协商：

绝不托管上游文件：本skill目录不包含ima-skill自身内容的任何副本、分叉或摘录。当ima-skill发布新版本时，用户无需本封装层干预即可获取新版本。
修复仅在运行时进行，而非发布时：如果上游存在需要修补的bug，本skill仅携带修补的操作说明，而非修补后的文件。运行修复操作具有幂等性：上游更新后重新运行，会重新检测并修复任何复发的问题。
修改上游文件前必须征得用户同意：修改
```
~/.claude/skills/ima-skill/**
```
、
```
~/.agents/skills/ima-skill/**
```
或任何其他上游安装目录时，必须通过AskUserQuestion获得用户明确同意。禁止静默修补。
授人以渔而非代劳：应用修复时，向用户展示具体的修改内容以及备份文件的保存位置。这能帮助用户学会自行维护安装。

What this skill does

本skill的功能

Capability	Entry point	Detail
1. Install upstream ima-skill to 3 agents	`scripts/install_ima_skill.sh`	See `references/installation_flow.md`
2. Configure API credentials (XDG style)	Inline workflow below	See `references/api_key_setup.md`
3. Diagnose and fix known upstream issues	`scripts/diagnose.sh` + workflow below	See `references/known_issues.md`
4. Fan-out search with priority boosting	`scripts/search_fanout.py`	See `references/search_best_practices.md`

能力	入口	详情
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`

Routing

路由规则

When this skill is triggered, classify the user's intent and jump to the corresponding capability:

User says something like…	Go to
"装 ima"、"install ima-skill"、"把 ima 装一下"、"我想用 ima"	Capability 1
"配 ima 的 key"、"configure ima credentials"、"ima API key"	Capability 2
"ima 报错"、"SKILL.md warning"、"frontmatter 错误"、"ima 加载失败"	Capability 3
"搜 X"、"在 ima 里搜 X"、"跨知识库搜索"、"扇出搜 X"	Capability 4
"帮我从头跑一遍 ima"	1 → 2 → 3 → 4 in sequence

When in doubt, start with Capability 3 (diagnose) — it surfaces exactly which capabilities are blocked and in what order.

触发本skill时，先分类用户意图，再跳转到对应功能：

用户表述类似…	跳转至
"装 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"	按顺序执行1 → 2 → 3 → 4

若不确定用户意图，先从能力3（诊断）开始——它会明确显示哪些能力受阻以及处理顺序。

Capability 1: Install upstream ima-skill

能力1：安装上游ima-skill

The installer downloads the latest official release from

https://app-dl.ima.qq.com/skills/

, stages it in a temp directory, and hands off to

npx skills add <local-path>

to distribute it across Claude Code, Codex, and OpenClaw.

To run it:

bash

bash scripts/install_ima_skill.sh

The script auto-detects which of the three target agents are installed on the user's machine. For agents that are not present, it skips silently rather than installing anywhere the user hasn't opted in. For agents that are present, it installs globally (

-g

) in vercel skills' default symlink mode: the first detected agent's directory becomes the canonical copy, and the remaining agents are symlinked to it. This means a repair or an upgrade applied once propagates automatically to every agent —

diagnose.sh

detects this sharing and dedupes its reports so you don't see the same issue multiple times.

For a version override, detection logic, troubleshooting, and the full file-by-file layout produced by the installer, read

references/installation_flow.md

安装器从

https://app-dl.ima.qq.com/skills/

下载最新官方版本，暂存到临时目录，然后通过

npx skills add <local-path>

将其分发到Claude Code、Codex和OpenClaw。

运行方式：

bash

bash scripts/install_ima_skill.sh

脚本会自动检测用户机器上已安装的三个目标Agent。对于未安装的Agent，会静默跳过，不会在用户未授权的位置进行安装。对于已安装的Agent，会以全局模式（

-g

）采用vercel skills的默认符号链接方式安装：第一个检测到的Agent目录成为标准副本，其余Agent则通过符号链接指向该目录。这意味着只需执行一次修复或升级，即可自动同步到所有Agent——

diagnose.sh

会检测这种共享机制并去重报告，避免重复显示同一问题。

如需版本覆盖、查看检测逻辑、故障排查或了解安装器生成的完整文件布局，请阅读

references/installation_flow.md

。

Capability 2: Configure API credentials

能力2：配置API凭证

Credentials are stored in XDG style, decoupled from any agent's skill directory:

```
~/.config/ima/client_id
```
(mode
```
600
```
)
```
~/.config/ima/api_key
```
(mode
```
600
```
)
```
~/.config/ima/
```
(mode
```
700
```
)

Environment variables

IMA_OPENAPI_CLIENTID

and

IMA_OPENAPI_APIKEY

act as fall-back overrides — the wrapper reads the environment first, then the config file.

Step through the setup with the user:

Open
```
https://ima.qq.com/agent-interface
```
and create a new Client ID and API Key.
Write both values into the XDG config path (or export the environment variables).

Make a single liveness call against

https://ima.qq.com/openapi/wiki/v1/search_knowledge_base

with

{"query": "", "cursor": "", "limit": 1}

to confirm the credentials are accepted — a

code: 0, msg: success

response means ready.

The full script and the exact request/response schema lives in

references/api_key_setup.md

凭证采用XDG规范存储，与任何Agent的skill目录解耦：

```
~/.config/ima/client_id
```
（权限
```
600
```
）
```
~/.config/ima/api_key
```
（权限
```
600
```
）
```
~/.config/ima/
```
（权限
```
700
```
）

环境变量

IMA_OPENAPI_CLIENTID

和

IMA_OPENAPI_APIKEY

可作为 fallback 覆盖配置——封装层会优先读取环境变量，再读取配置文件。

引导用户完成设置的步骤：

打开
```
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

。

Capability 3: Diagnose and fix known issues

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

This is the reason this skill exists. The upstream package has real bugs that break loading on certain agents, and the fixes are well-understood but need user consent to apply. The diagnose/repair workflow is the core contract of this skill.

这是本skill存在的核心原因。上游包存在会导致部分Agent加载失败的真实bug，修复方案已明确，但需要用户同意才能应用。诊断/修复工作流是本skill的核心协议。

Step 1 — Run the read-only diagnosis

步骤1 — 运行只读诊断

bash

bash scripts/diagnose.sh

diagnose.sh

never modifies any file. It prints a structured report with one line per check:

✅ 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)

bash

bash scripts/diagnose.sh

diagnose.sh

绝不会修改任何文件。它会打印结构化报告，每行对应一项检查：

✅ 已安装上游ima-skill (claude-code)
✅ 已安装上游ima-skill (codex)
❌ 未安装上游ima-skill (openclaw)
✅ API凭证有效（search_knowledge_base返回12个知识库）
⚠️ ISSUE-001: notes/SKILL.md缺少YAML前置元数据 (claude-code)
⚠️ ISSUE-001: knowledge-base/SKILL.md缺少YAML前置元数据 (claude-code)
⚠️ ISSUE-001: notes/SKILL.md缺少YAML前置元数据 (codex)
⚠️ ISSUE-001: knowledge-base/SKILL.md缺少YAML前置元数据 (codex)

Step 2 — Parse the report and ask the user

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

For each

⚠️

❌

line, look up the issue in

references/known_issues.md

. That file is the source of truth for:

What the issue is (symptom, root cause)
Which repair strategies exist (
```
A
```
,
```
B
```
,
```
skip
```
)
The exact shell commands for each strategy
What files each strategy touches
Why the upstream maintainer probably hasn't fixed it yet

对于每条

⚠️

或

❌

记录，请在

references/known_issues.md

中查找对应问题。该文件是以下内容的权威来源：

问题详情（症状、根本原因）
可用修复策略（
```
A
```
、
```
B
```
、跳过）
每种策略的精确shell命令
每种策略会修改哪些文件
上游维护者尚未修复该问题的可能原因

Step 3 — Ask for explicit consent before touching upstream files

步骤3 — 修改上游文件前需获得明确同意

Use AskUserQuestion for every issue that has more than one repair strategy. Frame it plainly — the user may not know what "YAML frontmatter" means. Describe what the bug does to them in user terms ("loader skips two files silently, so note-search and knowledge-base-search don't actually work"), then describe each strategy in terms of the outcome, not the mechanism.

Never offer a single "just fix it" option when multiple strategies exist. The user's pick may legitimately differ based on factors the skill cannot observe — e.g., they might prefer Strategy B (minimal diff) if they plan to manually compare with upstream.

对于存在多种修复策略的每个问题，使用AskUserQuestion询问用户。表述要通俗易懂——用户可能不知道“YAML前置元数据”是什么。用用户能理解的语言描述bug的影响（“加载器会静默跳过两个文件，导致笔记搜索和知识库搜索无法正常工作”），然后用结果而非技术机制来描述每种策略。

当存在多种策略时，绝不能只提供一个“直接修复”选项。用户的选择可能基于skill无法观察到的因素——例如，如果用户计划手动与上游版本对比，可能会偏好策略B（最小化差异）。

Step 4 — Execute the chosen strategy

步骤4 — 执行选定的策略

Every repair command in

references/known_issues.md

is written to be:

Idempotent — rerunning after the fix is already applied does nothing harmful and prints a clear "already fixed" message.
Backed up — the repair copies the original file to
```
/tmp/ima-copilot-backups/<timestamp>/<relative-path>
```
before modifying anything, then tells the user the backup location.
Reversible — the user can restore from the backup with a single
```
cp
```
command shown at the end.

references/known_issues.md

中的每个修复命令都具备以下特性：

幂等性：修复完成后重新运行不会造成任何有害影响，会打印清晰的“已修复”提示。
自动备份：修复前会将原始文件复制到
```
/tmp/ima-copilot-backups/<timestamp>/<relative-path>
```
，然后告知用户备份位置。
可回滚：用户只需使用修复结束时显示的单个
```
cp
```
命令即可从备份恢复。

Step 5 — Re-run diagnose to confirm

步骤5 — 重新运行诊断以确认修复

After the repair, run

diagnose.sh

a second time and show the user the diff. The issue should flip from

⚠️

✅

. If it does not, stop and surface the raw before/after to the user instead of silently retrying — unexpected failures here usually mean upstream shipped an unforeseen change.

修复完成后，再次运行

diagnose.sh

并向用户展示差异。问题应从

⚠️

变为

✅

。如果未改变，应停止操作并向用户展示修复前后的原始报告，而非静默重试——此处的意外失败通常意味着上游发布了未预料到的变更。

An important note about upstream updates

关于上游更新的重要说明

Every repair is temporary in the sense that ima-skill upgrades replace everything. This is by design: the skill does not fight upstream for persistent state. When the user upgrades ima-skill via Capability 1, Step 4 of diagnose will again flag the fixed issue, and the user can rerun the repair. This is a feature, not a bug — if upstream eventually fixes the issue, the repair becomes unnecessary and

diagnose.sh

will report ✅ with no prompt.

每次修复都是临时的，因为ima-skill升级会替换所有文件。这是有意设计的：本skill不会与上游争夺持久状态。当用户通过能力1升级ima-skill时，诊断步骤4会再次标记已修复的问题，用户可重新运行修复。这是一项特性而非bug——如果上游最终修复了该问题，修复操作将不再必要，

diagnose.sh

会报告✅且不会提示用户。

Capability 4: Personalized fan-out search

能力4：个性化扇出搜索

IMA's OpenAPI has three hard constraints that any serious search workflow must account for:

No cross-knowledge-base endpoint.
```
search_knowledge
```
requires a single
```
knowledge_base_id
```
per call. Cross-KB search is a client-side fan-out, not an API feature.
No relevance score in results.
```
info_list
```
items only carry
```
media_id
```
,
```
title
```
,
```
parent_folder_id
```
, and
```
highlight_content
```
. Any ranking beyond insertion order must happen on the client.
Silent 100-result truncation.
```
search_knowledge
```
returns at most 100 hits per KB with no
```
is_end
```
or
```
next_cursor
```
field in the response. High-frequency queries are silently capped.

scripts/search_fanout.py

implements the full workaround:

bash

python3 scripts/search_fanout.py "<query>"

The script reads

~/.config/ima/copilot.json

for personalization (priority KBs, skip list, strategy), calls

search_knowledge_base

to enumerate KBs, fans out

search_knowledge

calls in parallel, detects truncation by exact-100 length match, and renders results grouped by KB with priority groups at the top.

The personalization file is per-user and private. This skill ships only a template — see

config-template/copilot.json.example

. A user with no config file gets a neutral default: fan out all accessible KBs, sort groups by hit count, no boosting.

For the full algorithm, truncation handling strategy, rendering format, and a walkthrough of the evidence-based decision to allow a "subset KB skip" (e.g., a curated KB that is a strict subset of a master KB can be safely skipped to reduce duplicate hits), read

references/search_best_practices.md

IMA的OpenAPI存在三个任何严谨的搜索工作流都必须考虑的硬约束：

无跨知识库端点：
```
search_knowledge
```
每次调用需要指定单个
```
knowledge_base_id
```
。跨知识库搜索是客户端侧的扇出操作，而非API特性。
结果中无相关性评分：
```
info_list
```
项仅包含
```
media_id
```
、
```
title
```
、
```
parent_folder_id
```
和
```
highlight_content
```
。插入顺序之外的任何排序都必须在客户端完成。
静默截断100条结果：
```
search_knowledge
```
每个知识库最多返回100条结果，响应中无
```
is_end
```
或
```
next_cursor
```
字段。高频查询会被静默限制。

scripts/search_fanout.py

实现了完整的解决方案：

bash

python3 scripts/search_fanout.py "<query>"

脚本读取

~/.config/ima/copilot.json

获取个性化配置（优先级知识库、跳过列表、策略），调用

search_knowledge_base

枚举知识库，并行发起

search_knowledge

调用，通过结果数量是否恰好为100来检测截断，并按知识库分组渲染结果，优先级分组显示在顶部。

个性化配置文件是每个用户私有的。本skill仅提供模板——参见

config-template/copilot.json.example

。无配置文件的用户会使用中立默认设置：扇出所有可访问的知识库，按命中数排序分组，无权重提升。

如需了解完整算法、截断处理策略、渲染格式，以及基于证据决定允许“子集知识库跳过”（例如，某个精选知识库是主知识库的严格子集，可安全跳过以减少重复命中）的详细说明，请阅读

references/search_best_practices.md

。

What this skill refuses to do

本skill绝不执行的操作

Never vendor upstream content. This directory does not contain and will never contain a copy of
```
ima-skill/SKILL.md
```
,
```
ima-skill/notes/**
```
,
```
ima-skill/knowledge-base/**
```
, or any other upstream file. Anyone adding such files to this skill should be rejected.
Never pin an upstream version in SKILL.md. The installer script carries a default version for fallback purposes, but SKILL.md itself is version-agnostic to survive upstream releases without requiring a skill bump.
Never silently patch upstream files. Every modification path requires an explicit AskUserQuestion and the user's active choice.
Never hardcode a user's knowledge base names. The
```
priority_kbs
```
and
```
skip_kbs
```
fields in
```
copilot.json
```
are 100% user-configured. Example values in
```
config-template/copilot.json.example
```
are illustrative only.
Never skip the backup step when executing a repair, no matter how trivial the diff.

绝不托管上游内容：本目录不包含且永远不会包含
```
ima-skill/SKILL.md
```
、
```
ima-skill/notes/**
```
、
```
ima-skill/knowledge-base/**
```
或任何其他上游文件。任何向本skill添加此类文件的行为都应被拒绝。
绝不在SKILL.md中固定上游版本：安装器脚本携带默认版本作为 fallback，但SKILL.md本身与版本无关，以便在不更新skill的情况下兼容上游版本发布。
绝不静默修补上游文件：所有修改路径都需要明确的AskUserQuestion和用户的主动选择。
绝不硬编码用户的知识库名称：
```
copilot.json
```
中的
```
priority_kbs
```
和
```
skip_kbs
```
字段完全由用户配置。
```
config-template/copilot.json.example
```
中的示例值仅作演示用。
执行修复时绝不跳过备份步骤，无论差异多么微小。

File layout

文件布局

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
└── config-template/
    └── copilot.json.example         # Template for ~/.config/ima/copilot.json

ima-copilot/
├── SKILL.md                         # 本文件——入口与路由
├── scripts/
│   ├── install_ima_skill.sh         # 下载 → 暂存 → npx skills add 到3个Agent
│   ├── diagnose.sh                  # 只读健康报告
│   └── search_fanout.py             # 带优先级分组的扇出搜索
├── references/
│   ├── installation_flow.md         # 能力1深度解析
│   ├── api_key_setup.md             # 能力2深度解析
│   ├── known_issues.md              # 问题注册表——修复的权威来源
│   └── search_best_practices.md     # 能力4深度解析
└── config-template/
    └── copilot.json.example         # ~/.config/ima/copilot.json 的模板