ima-copilot

IMA Copilot

Tencent IMA 公式スキル向けの、ワンコマンドインストーラー、トラブルシューティングツール、パーソナライズレイヤーです。

概要

Tencent IMA 公式スキル（ima-skill）は、ノートやナレッジベースを操作する強力な OpenAPI を提供していますが、インストールフローは特定のプロプライエタリエージェント向けに設計されており、最近のリリースでは、厳格な SKILL.md ローダーでエラーになるサブモジュールファイルが含まれています。IMA Copilot は、次の方法でこの両方の問題を解決します。

1. オープンインストーラー vercel-labs/skills を使い、1 つのコマンドで Claude Code、Codex、OpenClaw に ima-skill をインストールします。
2. ライブ検証呼び出しを行いながら、API キーの設定手順を案内します。
3. 既知の上流の問題を検出し、ユーザーの明示的な同意を得たうえで、インプレースで修正します。上流パッケージのフォーク、ベンダー化、ミラーリングは一切行いません。
4. ユーザーが設定したナレッジベースの優先順位とブーストを尊重し、ナレッジベースごとの検索結果が 100 件で切り詰められる制限を考慮した、ファンアウト検索戦略を提供します。

アーキテクチャの原則（遵守してください）

このスキルは ima-skill のラッパーレイヤーです。ラッパーの契約は厳守してください。

• 上流のファイルをベンダー化しないでください。 このスキルのディレクトリには、ima-skill 自体のコンテンツのコピー、フォーク、抜粋は含まれていません。ima-skill の新しいリリースが公開されると、ユーザーはこのラッパーに妨げられることなく新しいリリースを利用できます。
• 修復は出荷時ではなく実行時に行います。 上流のバグにパッチが必要な場合、このスキルに含めるのはパッチ適用の手順であり、パッチ済みファイルではありません。修復処理は冪等です。上流が更新された後に再実行すると、再発した問題を再検出して修正します。
• 上流のファイルに手を加える前に、必ずユーザーに確認してください。 ~/.claude/skills/ima-skill/**、~/.agents/skills/ima-skill/**、またはその他の上流インストールディレクトリを変更するには、AskUserQuestion を通じたユーザーの明示的な同意が必要です。無断でパッチを適用してはいけません。
• 隠すのではなく、使い方を伝えてください。 修正を適用した場合は、何をどこで変更したか、バックアップをどこに保存したかをユーザーに正確に示します。これにより、ユーザーは自分でインストールを管理できるようになります。

このスキルでできること

機能	エントリーポイント	詳細
1. 3 つのエージェントに上流の ima-skill をインストール	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 + notes API	references/import_and_extract.md を参照

ルーティング

このスキルが呼び出されたら、ユーザーの意図を分類し、該当する機能に進んでください。

ユーザーの発言例	移動先
「ima をインストールして」、「install ima-skill」、「ima をインストールして」、「ima を使いたい」	機能 1
「ima のキーを設定して」、「configure ima credentials」、「ima API key」	機能 2
「ima でエラーが出る」、「SKILL.md の警告」、「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

スクリプトは、ユーザーのマシンにインストールされている 3 つの対象エージェントを自動検出します。存在しないエージェントには、ユーザーが許可していない場所へのインストールを避けるため、何も通知せずにスキップします。存在するエージェントには、vercel skills のデフォルトのシンボリックリンクモードでグローバルにインストールします（-g）。最初に検出されたエージェントのディレクトリが正本となり、残りのエージェントはそのディレクトリへのシンボリックリンクになります。これにより、修復やアップグレードを一度適用するだけで、すべてのエージェントに自動的に反映されます。diagnose.sh はこの共有状態を検出し、レポートを重複排除するため、同じ問題が複数回表示されることはありません。

バージョンの指定、検出ロジック、トラブルシューティング、インストーラーが生成するファイルごとの完全な構成については、references/installation_flow.md を参照してください。

機能 2：API 認証情報を設定する

認証情報は XDG 形式で保存され、各エージェントのスキルディレクトリから独立しています。

• ~/.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. 2 つの値を XDG 設定パスに書き込むか、環境変数としてエクスポートします。
3. {"query": "", "cursor": "", "limit": 1} を指定し、https://ima.qq.com/openapi/wiki/v1/search_knowledge_base に対して生存確認用の呼び出しを 1 回実行して、認証情報が受け付けられることを確認します。code: 0, msg: success という応答が返れば準備完了です。

スクリプトの全内容と、リクエスト／レスポンスの正確なスキーマについては、references/api_key_setup.md を参照してください。

機能 3：既知の問題を診断して修正する

このスキルが存在する理由はここにあります。上流パッケージには、特定のエージェントで読み込みを妨げる実際のバグがあります。修正方法は十分に把握されていますが、適用にはユーザーの同意が必要です。診断／修復のワークフローは、このスキルの中核となる契約です。

ステップ 1 — 読み取り専用の診断を実行する

bash scripts/diagnose.sh

diagnose.sh はファイルを一切変更しません。各チェックの結果を 1 行ずつ記した構造化レポートを出力します。

✅ 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）
• 各方法で実行する正確なシェルコマンド
• 各方法が変更するファイル
• 上流のメンテナーがまだ修正していないと考えられる理由

ステップ 3 — 上流ファイルに手を加える前に、明示的な同意を得る

修復方法が複数ある問題については、必ず AskUserQuestion を使用します。ユーザーが「YAML frontmatter」の意味を知らない可能性を踏まえ、平易な言葉で説明してください。バグがユーザーにどのような影響を与えるか（「ローダーが 2 つのファイルを通知なしにスキップするため、ノート検索とナレッジベース検索が実際には機能しません」など）を説明し、各方法について、仕組みではなく結果を説明してください。

修復方法が複数ある場合に、「とにかく修正する」という選択肢だけを提示してはいけません。ユーザーが選ぶ方法は、このスキルでは把握できない事情によって正当に異なることがあります。たとえば、上流の変更と手動で比較する予定がある場合、最小限の差分で済む方法 B を希望するかもしれません。

ステップ 4 — 選択した戦略を実行する

references/known_issues.md 内のすべての修復コマンドは、次のように書かれています。

• 冪等 — 修正がすでに適用された後に再実行しても害はなく、明確な「already fixed」メッセージを出力します。
• バックアップ済み — 修復は、何かを変更する前に元のファイルを /tmp/ima-copilot-backups/<timestamp>/<relative-path> にコピーし、その後ユーザーにバックアップの場所を伝えます。
• 可逆 — ユーザーは、最後に示される 1 つの cp コマンドでバックアップから復元できます。

ステップ 5 — 診断を再実行して確認する

修復後、diagnose.sh をもう一度実行し、ユーザーに差分を表示します。問題は ⚠️ から ✅ に変わるはずです。変わらない場合は、黙って再試行するのではなく、停止して生の before/after をユーザーに提示してください。ここでの予期しない失敗は、通常、上流が想定外の変更を出荷したことを意味します。

上流の更新に関する重要な注意

すべての修復は、ima-skill のアップグレードですべてが置き換わるという意味で一時的です。これは設計によるものです。このスキルは、永続的な状態をめぐって上流と争いません。ユーザーが Capability 1 で ima-skill をアップグレードすると、diagnose のステップ 4 が再び修正済みの問題をフラグし、ユーザーは修復を再実行できます。これはバグではなく機能です。上流が最終的に問題を修正すれば、修復は不要になり、diagnose.sh はプロンプトなしで ✅ を報告します。

Capability 4: パーソナライズされたファンアウト検索

IMA の OpenAPI には、本格的な検索ワークフローが必ず考慮しなければならない 3 つの厳しい制約があります。

1. ナレッジベース横断のエンドポイントがない。 search_knowledge は呼び出しごとに単一の knowledge_base_id を必要とします。KB をまたぐ検索は、API の機能ではなくクライアント側のファンアウトです。
2. 結果に関連度スコアがない。 info_list の項目が持つのは media_id、title、parent_folder_id、highlight_content のみです。挿入順を超えるあらゆるランキングはクライアント側で行う必要があります。
3. 100 件での無言の切り捨て。 search_knowledge は KB ごとに最大 100 件のヒットを返し、レスポンスに is_end や next_cursor フィールドはありません。高頻度のクエリは無言で上限に達します。

scripts/search_fanout.py は完全な回避策を実装しています。

python3 scripts/search_fanout.py "<query>"

このスクリプトは、パーソナライズ（優先 KB、スキップリスト、戦略）のために ~/.config/ima/copilot.json を読み込み、search_knowledge_base を呼び出して KB を列挙し、search_knowledge 呼び出しを並列にファンアウトし、長さが正確に 100 と一致することで切り捨てを検出し、優先グループを先頭にして KB ごとにグループ化した結果をレンダリングします。

パーソナライズファイルはユーザーごとでプライベートです。このスキルはテンプレートのみを同梱しています — config-template/copilot.json.example を参照してください。設定ファイルがないユーザーには中立のデフォルトが適用されます。アクセス可能なすべての KB をファンアウトし、ヒット数でグループを並べ替え、ブーストは行いません。

完全なアルゴリズム、切り捨て処理戦略、レンダリング形式、および「サブセット KB スキップ」を許可するという証拠に基づく決定（例: マスター KB の厳密なサブセットであるキュレーションされた KB は、重複ヒットを減らすために安全にスキップできる）のウォークスルーについては、references/search_best_practices.md をお読みください。

Capability 5: URL をインポートしてコンテンツを抽出する

読み取る対象のページが、ローカルマシンではフェッチできないが IMA のサーバーならフェッチできるものである場合、wiki/v1/import_urls でそれらをインポートし、IMA にそれらを JSON に変換させます。その 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