我是副驾驶
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
`diagnose.sh`从不修改任何文件。它打印一份结构化报告,每张支票一行:
对于每个`⚠️`或`❌`行,查找问题`references/known_issues.md`。该文件是以下内容的真相来源: 问题是什么(症状、根本原因) 存在哪些修复策略(`A`,`B`,`skip`) 每个策略的确切 shell 命令 每个策略涉及哪些文件
对具有多个修复策略的每个问题使用 AskUserQuestion。简单地描述它——用户可能不知道“YAML frontmatter”是什么意思。用用户术语描述错误对他们的影响(“加载程序默默地跳过两个文件,因此笔记搜索和知识库搜索实际上不起作用”),然后根据结果而不是机制描述每个策略。当存在多种策略时,切勿提供单一的“修复它”选项。用户的选择可能会根据技能无法观察到的因素而有所不同——例如,如果他们计划手动与上游进行比较,他们可能更喜欢策略 B(最小差异)。
每个修复命令`references/known_issues.md`被写为:幂等 - 在应用修复后重新运行不会产生任何有害影响,并打印清晰的“已修复”消息。已备份 — 修复将原始文件复制到`/tmp/ima-copilot-backups/<timestamp>/<relative-path>`在修改任何内容之前,然后告诉用户备份位置。可逆 — 用户可以通过一次操作从备份中恢复`cp`命令显示在最后。
修复后运行`diagnose.sh`第二次并向用户展示差异。问题应该从`⚠️`到`✅`。如果没有,请停止并向用户显示原始的之前/之后的内容,而不是默默地重试 - 这里的意外失败通常意味着上游发布了不可预见的更改。
# IMA Copilot
One-command installer, troubleshooter, and personalization layer for the official Tencent 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:
1. Installs ima-skill to Claude Code, Codex, and OpenClaw in a single command via the [vercel-labs/skills](https://github.com/vercel-labs/skills) open installer.
2. Walks the user through API key setup with a live validation call.
3. 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.
4. 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.
## 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.
## What this skill does
| 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` |
## 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.
## Capability 1: Install upstream 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`.
## Capability 2: Configure API credentials
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:
1. Open `https://ima.qq.com/agent-interface` and create a new Client ID and API Key.
2. Write both values into the XDG config path (or export the environment variables).
3. 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`.
## Capability 3: Diagnose and fix known issues
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.
### Step 1 — Run the read-only diagnosis
```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)
```
### Step 2 — Parse the report and ask the user
For each `⚠️` or `❌` 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
### Step 3 — Ask for explicit consent before touching upstream files
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.
### Step 4 — Execute the chosen strategy
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.
### Step 5 — Re-run diagnose to confirm
After the repair, run `diagnose.sh` a second time and show the user the diff. The issue should flip from `⚠️` to `✅`. 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.
### 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.
## Capability 4: Personalized fan-out search
IMA's OpenAPI has three hard constraints that any serious search workflow must account for:
1. **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.
2. **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.
3. **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`.
## What this skill refuses to do
- **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.
## 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
```
按说明文件中的顺序排列。
概述
架构原则(请勿违反)
这个技能有什么作用
路由
功能 1:安装上游 ima-skill
文件/命令 -> ~/.claude/skills/ima-skill/** · ~/.agents/skills/ima-skill/** · scripts/install_ima_skill.sh · references/installation_flow.md · references/api_key_setup.md · scripts/diagnose.sh · references/known_issues.md · scripts/search_fanout.py
内容校验值 -> 7eb91fe6c524
当前原文的自动摘译,尚未人工审校。
概述
官方的腾讯 IMA 技能 (ima-skill) 公开了一个用于注释和知识库操作的强大 OpenAPI,但其安装流程是为特定的专有代理设计的,并且最近的版本已经提供了无法严格 SKILL.md 加载程序的子模块文件。 IMA Copilot 解决了这两个问题:通过 vercel-labs/skills 打开安装程序,使用单个命令将 ima-skill 安装到 Claude Code、Codex 和 OpenClaw。
架构原则(请勿违反)
该技能是 ima-skill 的包装层。包装合同是不可协商的:绝不供应商上游文件。此技能目录不包含 ima-skill 自身内容的任何副本、分支或摘录。当 ima-skill 发布新版本时,用户可以获得新版本,而不会受到此包装器的任何干扰。维修发生在运行时,而不是发货时。如果上游错误需要修补,则该技能携带如何修补的说明,而不是修补的文件。运行修复是幂等的:在上游更新后重新运行会重新检测并重新修复返回的任何内容。
这个技能有什么作用
能力 · 入口点 · 详细信息 将上游 ima-skill 安装到 3 个代理 ·
scripts/install_ima_skill.sh· 见references/installation_flow.md配置 API 凭证(XDG 样式) · 下面的内联工作流程 · 请参阅references/api_key_setup.md诊断并修复已知的上游问题 ·scripts/diagnose.sh+ 下面的工作流程 · 请参阅references/known_issues.md具有优先级提升的扇出搜索·scripts/search_fanout.py· 见references/search_best_practices.md路由
当该技能被触发时,对用户的意图进行分类并跳转到相应的能力: 用户说类似... · 转到“装ima”、“install ima-skill”、“把ima装一下”、“我想用ima” · 能力1“配ima的密钥”、“配置ima凭证”、“ima API密钥” · 能力2“ima报错”、“SKILL.md警告”、“frontmatter错误”、“ima加载失败》·能力3
功能 1:安装上游 ima-skill
安装程序从以下位置下载最新的官方版本
https://app-dl.ima.qq.com/skills/,将其暂存在临时目录中,然后交给npx skills add <local-path>将其分发到 Claude Code、Codex 和 OpenClaw。 运行它: 该脚本自动检测用户计算机上安装了三个目标代理中的哪一个。