ketch

Ketch

すべてのライブソースに関する質問を、Ketch の5つのリサーチサーフェス（search、code、docs、scrape、crawl）のいずれかに、オペレーターから指定されたトランスポート経由でルーティングします。すべての取得にトークン予算を設定し、すべての主張にソース URL を付けます。Ketch はステートレスな単一バイナリで、呼び出し、結果の返却、終了という動作をします。ウェブ検索、オープンソースコードの grep、厳選されたライブラリドキュメント、ページやサイトの抽出をまとめて提供するため、完全なリサーチパイプラインにほかのツールやデーモンは必要ありません。

トランスポート：デフォルトはステートレス CLI、オペレーターが設定した場合は MCP

CLI は Ketch の基本です。呼び出し → 結果の返却 → 終了という動作で、毎回の呼び出しに --json を指定し、終了コードを制御フローとして使用します。デーモンはゼロです。これがデフォルトのトランスポートであり、インフラ不要の方法です。MCP サーバーは、必要とするオペレーター向けにサポートされている代替手段であり、必須ではありません。

最初の呼び出しの前に、セッションごとに一度だけ決定してください。

1. which ketch が成功する → CLI がトランスポートです。毎回の呼び出しに --json を指定し、終了コードを制御フローとして使用します。
2. ツール一覧に Ketch のツールがあるかも確認してください。サーバー名 ketch の MCP ツール search、code、docs、scrape、crawl、tag（Claude Code の場合は mcp__ketch__search、…）、または pi の ketch_search、ketch_code、ketch_docs、ketch_scrape、ketch_crawl、ketch_tag です。存在する場合 → オペレーターが意図的に設定しているため、リサーチの呼び出しに使うのが正しく、推奨されます。構造化された出力、URL ごとのエラー、MCP と同じオプションおよびエラープレフィックスが利用できます。オペレーターが設定したツールを避けて、シェルコマンドを実行してはいけません。（pi のツールは CLI を代わりに実行するため、手順3のページキャッシュに関するトレードオフは該当しません。）
3. どちらも利用可能 → どちらのトランスポートでもリサーチの呼び出しができます。ただし、トレードオフに注意してください。MCP サーバーの実行中は、単一プロセスのページキャッシュロックが保持されるため、並行して実行する CLI のスクレイピングではキャッシュが無効になっても、そのことが通知されません。
4. CLI も MCP ツールもない → Ketch がインストールされていません。brew install ketch、npm i -g ketch-cli、または go install github.com/1broseidon/ketch@latest を提案してください。これはオペレーターが行う操作です。提案したら、確認を待ってください。

ルール：オペレーターが用意したトランスポートを使用してください。両方が利用可能な場合、リサーチの呼び出しにはどちらを使ってもかまいません。オペレーターが行う操作には、常に CLI を使用します。

tag は、以下のオペレーター操作に関するルールの唯一の例外です。ローカル状態を変更しますが、エージェントが書き込み側と読み取り側の両方であるため、CLI だけでなく MCP 経由でも公開されています。

設定の検出には、トランスポートにかかわらず CLI を使用します。ketch config は有効な設定と利用可能なバックエンドを JSON で出力します。MCP 経由の設定ツールはありません。オペレーターが行う操作である config set、cache、browser install、crawl --background／status／stop、doctor は、意図的に MCP には含めていません。これらには常に CLI を使用します。

用語集

ketch の出力では、以下の用語のみを使用してください。

用語	意味
surface	5 つの調査操作のいずれかです：search、code、docs、scrape、crawl
tag	各 surface にまたがって記録されるラベルです：検索結果、コード検索結果、ドキュメントのチャンク、スクレイピングしたページ、クロールしたページ。調査用 surface ではなく、「何があるか」ではなく「すでに何を見つけたか」に答えるものです
transport	surface の呼び出し方法です：CLI バイナリ（デフォルト）、任意の MCP ツール、または pi パッケージの ketch_* ツール（CLI を実行します）
backend	surface の背後にあるプロバイダーです：auto（デフォルト。プロバイダーではなくフォールバックチェーンです）/brave/ddg/searxng/exa/firecrawl/keenable/tavily/tinyfish/parallel/serpbase/degoog/serply/youcom（検索）、grepapp/sourcegraph/github（コード）、context7（ドキュメント）
operator action	システム管理または診断用のコマンドです — config set、cache、browser install、バックグラウンドクロール、doctor — 設計上、CLI 専用です
error prefix	すべての ketch エラーに付く安定した分類です：CLI の終了コード 2–6 に対応し、すべての MCP ツールエラーの先頭に角括弧付きのプレフィックスとして表示されます — [validation]、[not_found]、[upstream]、[precondition]、[cancelled]
fan-out	1 つのプランで検索するクエリ数とスクレイピングする URL 数です
token budget	呼び出しごとの出力上限です：スクレイピングでは max_chars/trim、ドキュメントでは tokens、リストでは limit/--minimal を使用します
probe	surface が設定済みで到達可能かをテストする、低コストの読み取り専用呼び出しです

このスキルの使い方

• デフォルト：1 つまたは 2 つのルーティング済み呼び出しで 1 つの質問に答えます。以下の surface ルーティング表、トークン予算、エラー制御フローを使用してください。
• ketch research <question>：複数ソースを使った詳細な調査です — 検索の fan-out → 上位の結果をスクレイピング → 必要に応じてコード／ドキュメントで裏付け → 引用付きの回答を統合します。references/verbs/ketch-research.md を読んでください。
• ketch setup：オペレーターと連携してバックエンドを設定します — 現在の状態を probe し、正確なコマンドを提案し、確認後にのみ変更します。いずれかの呼び出しが [precondition]／終了コード 5 を返した場合は、この verb に移行してください。references/verbs/setup.md を読んでください。

質問 1 つにつきプランは 1 つです。最初の検索で回答に異論がある、複数の要素がある、または裏付けが必要だとわかった場合は、デフォルトの実行から ketch research に切り替えます。

必ず守ること

1. オペレーターが指定した transport を使用してください。 デフォルトは CLI です。利用可能なツールに MCP ツールがある場合、オペレーターが使用を選択しています — シェルを使って回避せず、調査には MCP ツールを使用してください。両方が利用可能な場合、調査の呼び出しにはどちらを使ってもかまいません（実行中の MCP サーバーがページキャッシュのロックを保持するため、CLI のスクレイピングを同時に行うとキャッシュが使われません）。設定、キャッシュ、ブラウザー、バックグラウンドクロール、doctor などのオペレーター操作には、必ず CLI を使用してください。
2. すべての取得に上限を設けてください。 未確認のページをスクレイピングする際は、max_chars を 4000～8000 に設定し、trim も指定してください。上限を設けないページ取得では、約 25k トークンを消費する可能性があります。上限を省略する場合は、理由を 1 行で明記してください（例：「約 200 語のページだとわかっているため」）。
3. すべての主張に引用を付けてください。 出典 URL のない調査結果の統合は、成果物として認められません。
4. エラープレフィックスは制御フローです。 対処する前に分類してください。[validation] または [not_found] は、変更せずに再試行しないでください。
5. 提案してから変更してください。 config set、browser install、docker の実行、インストールなどは、オペレーターが正確なコマンドを確認してから実行してください。設定済みで正常に動作している値には、決して手を加えないでください。
6. このファイルよりバイナリを優先してください。 ketch config と --help が正しい情報源です。ここにある表と食い違う場合はバイナリを信頼し、このスキルにずれがあることを報告してください。

理想的な判断の流れ

Request: "ketch research — do people actually use Go's iter.Seq in real projects, and what are the gotchas?"

Transport: operator wired mcp__ketch__* into this session → honor it; research calls go over MCP.
Plan: 2 queries · scrape top 3 · max_chars 6000 + trim · ≤8 calls

search {query: "Go iter.Seq real-world experience gotchas", limit: 5}
  → "[upstream] ddg rate limited" → an explicit backend failed; rotate to another
    usable provider from available_backends, retry once:
    search {query: ..., backend: "brave", limit: 5} → ok
search {query: "Go range-over-func adoption production", backend: "brave", limit: 5}
  → 10 results, 8 unique hosts → picked 3: official blog post, one experience
    report, one issue thread (primary sources over aggregators)

scrape {urls: [u1, u2, u3], max_chars: 6000, trim: true}
  → isError=false; checked results[] one by one: u1, u2 ok;
    u3.error = "[upstream] … 503" → dropped, will be named in synthesis

code {query: "iter.Seq", lang: "go", limit: 3}      # corroborate real usage
  → 3 repos with file/line URLs

Synthesis: five claims, each cited to its URL; u3 listed as unretrieved;
one conflict between u1 and u2 stated and attributed, not averaged.
Budget: 5 of 8 calls (the rate-limited attempt counts).

サーフェスのルーティング

最初に一致したものを使用します。

質問に必要なもの	サーフェス	使用しないもの
現在のウェブページ、意見、ニュース、比較	search	docs — 厳選されたライブラリのドキュメントのみが対象です
実際のプロジェクトでの API の呼び出し方	code	search — ブログはコードについて語るものであり、code は grep.app 経由で公開 OSS リポジトリを検索します
ライブラリ独自の、バージョンに対応したドキュメント	docs	ドキュメントサイトの scrape — docs はすでに抽出され、トークン予算が設定されています
すでに把握している URL のコンテンツ	scrape	search — 既知の URL を再検索してはいけません
1 つのサイトから取得する複数のページ	crawl	scrape のループ — crawl は重複を除去し、範囲を制限してストリーミングします
このプロジェクト内ですでに以前に見つけたもの	tag（operation: show）	再度の search — これらはすでに一度取得しています

逆に言えば、search は URL を見つけ、scrape は URL の内容を読み取り、crawl はサイトを読み取り、code は公開ソースを読み取り、docs はライブラリのドキュメントを読み取ります。すべての検索結果の完全なコンテンツが必要な場合は、scrape: true を指定した search で最初の 2 つを組み合わせられます。その場合は scrape と同様に予算を見積もってください。

tag で作業セットを保持する

複数のセッション、または少数のソースを超えて作業する場合は、再利用したい呼び出しに --tag <name>（CLI）または tag（MCP）を渡し、results-3 ではなく remote-access のように、プロジェクト名や作業範囲を付けます。

これはどのサーフェスでも機能し、1 つのタグにすべてをまとめられます。対象は search、code、docs、scrape、crawl です。そのため、プロジェクトのタグには、ベンダーのドキュメント、それを呼び出すコード、未文書化のフラグを説明した記事が、1 つのリストにまとまります。後から tag show を実行すると、タイトル、URL、説明を含む llms.txt 形式のインデックスが返されます。インデックスは新しい順に最大 50 件に制限されており、検索を再実行せずにソースを 1 つ読み直せます。すべての検索結果ではなく、実際に使用したソースにタグを付けてください。

表示件数を減らすには --limit N / MCP limit を使用します。0 はすべてを明示的に要求します。entries はタグ全体の件数、shown は返されたページ数です。再度検索する前にインデックスを確認してください。ただし、デフォルトで大きなタグの全件を要求しないでください。

インデックスは永続的で、キャッシュされたページ本文の有効期間を過ぎても残るため、数日後でも利用できます。cached: false は新しい本文が確認されていないことを示すもので、リンク切れを意味するものではありません。cache_status が unavailable の場合、ページキャッシュを確認できませんでした。ブックマークは引き続き機能し、ソースも取得できます。code、docs、および未スクレイピングの search 結果のエントリは、取得したページではなくスニペットを返す呼び出しであるため、最初からこの状態になります。全体を確認したい場合は、URL を scrape してください。まずインデックスを読み、必要なものだけを取得してください。タグ全体を組み立てると、目的に反します。

ブックマークの診断情報は、リサーチの成功とは別に確認してください。CLI の警告は stderr に出力され（--json では構造化されます）、MCP は warnings を返します。書き込みに失敗しても、有用なリサーチ結果は破棄されません。永続ブックマークは別ファイルを使用するため、テスト環境ではページキャッシュを分離するとともに KETCH_TAGS_PATH も設定してください。

トークン予算

呼び出し	上限の設定方法	測定コスト
search、limit 5	limit	約 1.4 KB
code、limit 3	limit	約 0.7 KB
docs、デフォルト予算	tokens（デフォルト 4000）	約 3.3 KB
scrape、不明なページ	max_chars 4000～8000 + trim	上限なし：最大約 100 KB（約 25k トークン）
crawl（MCP）	max_pages + ページごとの max_chars	デフォルト 30 ページ、上限 100 ページ、実行時間 3 分
tag show / MCP tag show	limit（デフォルト 50、0 はすべて）	ソースメタデータに上限あり。ページ本文は含まれません
CLI の各種リスト	--minimal	出力をおよそ半分に削減

エラー制御フロー

終了コード（CLI）	プレフィックス（MCP）	意味	対応
2	[validation]	入力が不正です	呼び出しを修正してください。変更せずに再試行しても成功しません
3	[not_found]	一致するものがありません	クエリまたはセレクターを変更してください。障害ではありません
4	[upstream]	バックエンドまたはネットワークの障害です	バックエンドを明示している場合は、別のプロバイダーに切り替えてください（ketch config の available_backends を参照）。または1回だけ再試行してください。auto は使用可能なすべてのプロバイダーをすでに試しています。1回だけ再試行してから、障害を報告してください
5	[precondition]	オペレーターの設定がありません	調査を中止し、ketch setup を実行してください
6	[cancelled]	キャンセルまたはタイムアウトしました	範囲を小さくして再実行してください

状況 → 分類：不明なバックエンド、github での regexp → [validation]。セレクターに一致するものがない、コードバックエンドにない repo → [not_found]（repo の場合はバックエンドを変更してください）。ddg のレート制限（並列実行時はすぐに制限されます）、DNS 障害、grepapp の断続的な 504 → [upstream]。別のプロバイダーに切り替えるか、1回だけ再試行してください。API キーがない、ドキュメントバックエンドが local（予定されていますが未実装）、設定済みのブラウザーがない状態での force_browser → [precondition]。非対称な点が1つあります。CLI の crawl は SIGINT によって中断されると、仕様上、部分的な結果を返して 0 で終了します。

注意点

各項目の詳細は references/surfaces.md にあります。

• ドメインのみをスクレイピングすると、/llms.txt が自動的に検出され、ホームページの代わりにそれが返されることがあります。title フィールドで置き換わりを確認できます。no_llms_txt を指定すると無効になります。
• docs は2段階の処理です。名前を resolve し → 一致結果を確認してから → library ID を指定して取得します。Resolve は空の結果を返しません。無関係な入力にも自信満々なあいまい一致を返すため、信頼スコアだけでなく名前を確認してください。
• バッチスクレイピングでは、成功した呼び出しの中でURLごとのエラーが報告されます。isError=false でも results[].error が設定されることがあります。すべての項目を確認してください。
• regexp が使えるのは grepapp と sourcegraph のみです。github では拒否され、これらのバックエンドを使うよう案内されます。
• バックグラウンドクロール（--background、status、stop）は CLI 専用です。MCP の crawl は同期実行で、上限があります。
• ページキャッシュ（bbolt、デフォルトの TTL は72時間）は単一プロセスで動作します。長時間稼働する MCP サーバーがロックを保持するため、CLI のスクレイピングを同時に実行すると、キャッシュが無効になったまま気づかずに動作します。ketch doctor は、別プロセスによってキャッシュがロックされていると報告します。サーバーの実行は CLI のパフォーマンスを低下させます。両方を長時間稼働させる場合は、CLI のみを使ってください。

BAD/GOOD の対比

BAD: scrape {url: "https://docs.example.com"} — 上限がありません。llms.txt または約25kトークンのうち、より都合の悪い方が返されます。 GOOD: scrape {url: "https://docs.example.com/quickstart", max_chars: 6000, trim: true} — ページ自体を取得し、サイトの llms.txt は取得しない場合は、no_llms_txt: true も指定してください。

BAD: ketch をエージェントで使うには MCP サーバーを実行する必要があるとユーザーに伝えること。CLI とプロンプトブロックを使えば、インフラ不要で利用できます。また、長時間稼働するサーバーはページキャッシュをロックし、すべての CLI 呼び出しに影響します。 GOOD: デフォルトでは CLI を使い、オペレーターが MCP を設定している場合は MCP を使ってください。mcp__ketch__* ツールが一覧にある場合は、オペレーターの設定を迂回してシェルを使うのではなく、それらを調査に利用してください。

BAD: [upstream] ddg rate limited → 同じ呼び出しを3回再試行する。 GOOD: プロバイダーを切り替えてください。backend: "brave"（または available_backends にある別のプロバイダー。auto はプロバイダーの連鎖であり、切り替え先ではありません）を指定して1回だけ再試行し、切り替えたことを記録してください。auto 自体が失敗した場合は、使用可能なすべてのプロバイダーをすでに試しています。1回だけ再試行してから、障害を報告してください。

BAD: 信頼スコアが高いため、名前が依頼されたライブラリと異なっていても、resolve の最初の一致結果からドキュメントを取得する。 GOOD: 名前、スニペット数、信頼度を確認してください。目的のライブラリ名を含む一致結果がなければ、無関係なドキュメントを取得せず、その旨を伝えてください。

リファレンスの読み込み

• ketch research … → 開始前に references/verbs/ketch-research.md を読んでください。
• ketch setup、[precondition]／終了コード5、またはインストール → references/verbs/setup.md を読んでください。
• フラグ／パラメーターの全テーブル、CLI↔MCP の名前の対応、バックエンド／キーの対応表、または挙動がおかしいサーフェス → references/surfaces.md を読んでください。

対象範囲

対象：両方のトランスポートにおける5つのリサーチ対象、リサーチとセットアップの動詞、トークン予算、エラープレフィックスの制御フロー、バックエンド設定。対象外：ローカルまたは非公開のコードベースの検索（リポジトリツールを使用してください）、認証またはペイウォールの背後にあるページ、上限を超える一括アーカイブのクロール、ketch のヘッドレスレンダリングへのフォールバックを超えるブラウザー自動化。

すべてのフェッチに上限を設け、すべての主張に出典を示してください。