volcengine-knowledge-search

volcengine-knowledge-search 火山引擎ドキュメント検索

ve docs search で公式ドキュメントを検索し、ve docs fetch で本文を取得します。リクエスト、レスポンスの解析、本文のクリーニング、ページネーションは CLI が処理します。この skill はシナリオの判断、query の書き換え、追加検索、ソースの引用を担当します。

CLI 呼び出しのルール

ve を実行する前に、volcengine-cli の呼び出し元の識別ルールに従います。呼び出しのたびに、プロセス環境で次の変数を設定する必要があります。

• VE_CALLER_TYPE=ai_agent。
• VE_CALLER_NAME：Agent が現在の実際のホスト環境に基づいて決定します。固定のデフォルト値は使用しません。
• VE_SKILL_NAME：現在の操作を実行する skill の frontmatter name を使用します。この skill でドキュメント検索または本文の読み取りを実行する場合、この値は volcengine-knowledge-search です。CLI の呼び出しルールを参照しても、操作を担当する skill は変わりません。

この要件は、--help の確認、初回検索、書き換え後の検索、本文の読み取り、ページネーションによる続きの読み取り、再試行に適用されます。ツール呼び出しのたびに新しい shell が起動する場合があるため、3 つの変数を毎回渡してください。前回の export には依存しないでください。以下の例にある <agent-id> と <current-volcengine-skill> は、Agent が現在の環境と skill のメタデータに基づいて置き換える必要があります。値をそのまま渡してはいけません。これらの変数は呼び出し元の識別にのみ使用し、公開ドキュメントのコマンドではログイン不要というルールは変わりません。

準備

初回使用時に、ローカル環境に次の 2 つのサブコマンドがあることを確認します。

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search --help
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch --help

ve がインストールされていない場合やサブコマンドが不足している場合は、volcengine-cli skill を読み込み、その「Install or upgrade the ve CLI」セクションに従って最新版をインストールしてから、機能を確認してください。ドキュメントコマンドは公開サービスにアクセスするため、ログイン、AK/SK、profile、リージョンの設定は不要です。インストール後すぐに使用でき、リソース管理の ID 初期化手順を実行する必要はありません。

選択フロー

1. ユーザーから具体的な記事のリンクが提供された場合：そのまま fetch を実行し、質問に関連する本文を読み取ります。
2. ユーザーから質問があった場合：製品名と具体的な分野を補ってから search を実行します。初回検索では製品フィルターを指定しません。タイトル、概要、製品コードから関連性を判断します。
3. 結果の範囲が広すぎる場合や関連性が低い場合：query を書き換えます。結果内で対象製品の ServiceCodes が確認できた場合に限り、そのコードを使って 2 回目の検索を行います。無関係な結果に含まれるコードをフィルター条件に使わないでください。
4. 完全な手順、制限事項、正確な料金ルール、または全文の要約が必要な場合：関連する結果の URL に対して fetch を実行し、必要に応じて続きを読みます。ユーザーが全文を求めている場合は、続きの案内がなくなるか、has_more=false になるまで読み取ります。

search：ドキュメントを検索する

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "对象存储 TOS 如何计费" --limit 3 --output text

検索テキストは位置引数です。質問全体を引用符で囲んでください。--output text を指定すると、そのまま読める Markdown が取得できます。各項目には、タイトル、クリーンな URL、ServiceCodes、本文の概要が含まれます。CLI のデフォルト出力は JSON です。プログラムで処理する場合は、--output json を明示的に指定してください。結果は documents 配列に格納され、フィールドは title、url、service_codes、snippet です。

パラメーター	用途
--limit N	返すドキュメント数。正の整数を指定します。通常はまず 3 件取得します
--service-code CODE	製品を限定します。関連性が確認できた結果からコードを取得します。複数の製品を指定する場合は、このオプションを繰り返します
--snippet-length N	各概要の最大 Unicode 文字数です。正の整数を指定します。これを使ってコンテキストのサイズを調整します

query の書き換え

セマンティック検索では、ドキュメント内の表現に近づける必要があります。口語表現、略称、マーケティング名を製品の正式名称 + 機能の説明 + 具体的な質問に補います。たとえば、「Coding Plan はいくらですか」を「火山方舟 Coding Plan AI プログラミングサブスクリプションプランの料金体系」に書き換えます。初回検索の結果がずれている場合は、正式名称、類義表現、または機能の説明を変えて再検索します。

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "火山方舟 Coding Plan AI 编程订阅套餐如何计费" --limit 3 --output text

まず広く検索し、関連する結果の ServiceCodes が tos であることを確認してから、製品を絞り込んで検索します。

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "跨区域复制如何配置" --limit 5 --snippet-length 300 --output text
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs search "对象存储 TOS 跨区域复制如何配置" --limit 3 --service-code tos --output text

複数の製品コードを指定する場合は、--service-code <code-a> --service-code <code-b> のように、コードごとに個別に渡します。

fetch：本文を取得する

https://www.volcengine.com/docs/... と https://docs.volcengine.com/docs/... に対応しています。CLI は URL の query と fragment を削除します。text 出力の順序は、タイトル、クリーンな URL、現在のページの本文、続きの案内です。

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514?lang=zh" --output text

パラメーター	用途
--start-index N	N 番目の Unicode 文字から開始します。インデックスは 0 から始まります
--max-length N	現在のページで返す Unicode 文字数の上限です。正の整数を指定します。デフォルトは 5000 です

長文の末尾には、次のページの --start-index が表示されます。読み漏れや重複を避けるため、同じ URL と返されたインデックスを使って続きを読みます。以下の例では最初に 300 文字を取得し、続きの案内が --start-index 300 の場合、次のページを読み込みます。

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514" --max-length 300 --output text
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
  ve docs fetch "https://www.volcengine.com/docs/6349/162514" --start-index 300 --max-length 300 --output text

プログラムでページネーションを行う場合は、--output json を使用し、content、start_index、next_start_index、remaining_characters、has_more、has_content を読み取ります。has_more=true の場合は、next_start_index を使って続きを読みます。読み取りが終了すると、このフィールドは null になります。

ナビゲーションページと空の本文

• /docs/{製品番号}/{ドキュメントID} は個別の記事のパスです。
• /docs/{製品番号} は製品ドキュメントのナビゲーションページであり、個別記事の本文はありません。この種のリンクだと判定した場合は、製品名とユーザーが関心を持つ分野を使って search を実行し、結果から具体的な記事を特定して fetch します。また、リンクの種類をユーザーに説明します。
• has_content=false は本文を取得できなかったことを示します。この状態から内容を作り出してはいけません。リンクがナビゲーションページ、古いアドレス、または誤ったアドレスではないかを確認し、search で代替ドキュメントを探します。

結果とエラーの処理

• 根拠に基づいて回答する：概要で裏付けられる概念的な質問には、そのまま回答できます。正確なルールや完全な手順については、先に本文を取得します。一部のページしか読んでいない場合は、記事全体を読んだかのように説明してはいけません。
• ソースを引用する：CLI が返すクリーンな URL を使い、[ドキュメントタイトル](URL) の形式で記載します。関連性の高いソースを最大 3 件優先して提示し、各結論が読み取った内容に対応するようにします。
• 出力を調整する：search では --limit と --snippet-length、fetch では --max-length と --start-index を使います。CLI には旧スクリプトの一時ファイルプレビュー機能はありません。続きを読む場合はページネーションパラメーターを使います。
• 正常な空の結果：終了コードが 0 で documents が空の場合は、query を書き換えるか、製品フィルターを緩めます。これはサービス障害を意味するものではありません。
• パラメーターエラー：対応するサブコマンドの --help に従ってパラメーターを修正します。件数と長さには正の数、開始インデックスには 0 以上の数を指定する必要があります。
• リクエストの失敗：終了コードが 0 以外の場合は stderr を確認し、ネットワークの問題と上流の業務エラーを区別します。タイムアウトや DownstreamError などの一時的な障害は、1～2 回再試行できます。失敗が続く場合は、失敗の理由を説明し、失敗を結果なしとして扱わないでください。公開ドキュメントへのリクエストが失敗しても、クラウドアカウントの認証情報を追加する必要はありません。