ae-kb

ae-kb

スキル間の連携

残りの作業がこのスキルの範囲外の場合や、必要な前提条件に別の機能が必要な場合は、連携プロトコルに従ってください。この実行で利用可能なスキルから、機能に基づいて選択し、確認済みのコンテキストを保持して、残りの作業を続けてください。このプロトコルがすでに読み込まれている場合は、再利用してください。

AE CLI（ae-cli）のナレッジベースコマンドは、次のように実行します。

ae-cli kb +<command> [options]
ae-cli kb source <create-text|read-text|replace|restore|preview|commit|cancel|check-updates|check-url-updates> [options]

全般的なルール

• AE ナレッジベースに関するタスクでは、このスキルを使用してください。ナレッジベースの作成、コンパイル済みスナップショットのインポート、クエリ、LLM を使った質問、アクセス可能なナレッジベースとそのソースの一覧表示、インデックスの確認、ページの grep、ページの読み取り、ステータスの確認、ソースのアップロード、URL ソースの追加、スキーマの生成、コンパイル、ソースファイルの削除、ナレッジベースの削除が含まれます。
• ナレッジベースを検索して回答を得ることが、最も一般的なタスクです。その場合は、ナレッジベースのページを調べるに進み、まず references/query-workflow.md を読んでください。これは情報検索の手順です。以下のその他のコマンドは、ナレッジベースを管理するためのものであり、ナレッジベースから回答を得るためのものではありません。
• 取得したページをプロジェクト固有の業務データ分析に利用する場合は、データクエリを実行する前に references/analysis-workflow.md を読んで従ってください。KB の検索結果からアセット、定義、パラメーター、時間ルール、競合、または判断境界が特定された場合は、必ずこの手順に従ってください。実行前に意味的な網羅性を検証してください。関連ページの存在や KB の制限をもって、タスクが完了したと判断してはいけません。未網羅の要件については、未検証の場当たり的な分析や SQL に直接進まず、通常の分析を続けてください。
• 必要な入力がそろっていれば、読み取り操作はそのまま実行できます。書き込み操作には、ユーザーの明示的な意図が必要です。CLI の確認プロンプトが必要なのは high-risk-write コマンドのみです。明示的な許可を得た後に --yes を使用してください。
• ユーザーが対象をすでに検証していない場合は、破壊的な操作や広範囲に及ぶ書き込みの前に、--dry-run を優先して使用してください。
• ナレッジベース名、スコープ、ソース ID、ソース表示名、JSON ペイロードを作り出してはいけません。値が不足している場合は、ユーザーに尋ねるか、既知のコンテキストを照会してください。
• --sources の参照（または +read --source）を作成する場合は、+list の出力から scope と name を正確にコピーしてください。名前が分かっているナレッジベースのスコープが不明な場合は、まず ae-cli kb +list を実行してください。
• JSON フラグには有効な JSON 文字列を指定してください。通常、シェルコマンドではシングルクォートで囲みます。
• コマンドは通常、成功すると JSON を返します。人が確認しやすい場合に限り、--format table を使用してください。エンベロープには、省略可能な _notice.host_compat が含まれる場合があります。
• --host <url> は、アクティブな AE ホストを上書きします。すべてのコマンドで使用でき、サブコマンドの後に指定できます。例：ae-cli kb +<command> --host <url>。
• 重要 — ホスト互換性（最初に実行）： ae-cli を実行するたびに、stderr と _notice.host_compat を確認してください。どちらかに表示されている場合は、ユーザーへの返信を短い ⚠️ バージョン警告で始め、npm i -g / npx skills add（または update-cluster）の行を一字一句そのまま引用してから、業務上の結果を提示してください。これは参考情報です。ok: true の場合でも通知が含まれることがあります。
• 情報検索（+index / +grep / +read）は決定論的で、サーバー側の LLM 処理を必要としません。単純な事実確認にはこちらを使用してください。複数ページをまたぐ統合や複数段階の推論が必要な質問には、+ask を使用してください。

コマンド

コマンド	リスク	目的
source create-text	write	テキスト、UTF-8 ファイル、または明示的な stdin から通常の Markdown ソースを 1 つ作成します。コンパイルせずに保存します。
source read-text	read	対応するリビジョンとともに通常のテキスト全体を読み取ります。必要に応じて、元の UTF-8 バイト列を新しいファイルに保存します。
source check-url-updates	write	コンパイル済みのカスタム URL ソース 1 つに対する非同期チェックを送信します。成功は受け付けられたことのみを意味します。
source check-updates	write	スケジュール済み検出機能を使用して、コンパイル済みの Feishu ソース 1 つをチェックします。変更をマークしますが、コンパイルはしません。
+ask	read	ナレッジベースを対象とした LLM による Q&A です。複数ページの統合や複数段階の質問に適しています。
+ask-status	read	--execution-id を指定して、ポーリングせずに ask 実行の現在のステータスを照会します。
+list	read	buildStatus で絞り込んで（既定値：compiled）、アクセス可能なナレッジベースを一覧表示します。
+list-sources	read	ナレッジベース 1 つのソースメタデータを一覧表示し、正確なソース識別子を安全に特定できるようにします。
+index	read	アクセス可能なナレッジベースと、その index.md ナビゲーションマップを一覧表示します。
+grep	read	ナレッジベースのページをキーワード検索します。ページ単位の結果配列（hitCount / pageKind / sections previews）を返します。
+read	read	ナレッジベースのページ全体、行範囲、または（--outline を指定した場合）ページの見出しツリーのみを読み取ります。
+new	write	個人用または会社用の新しいナレッジベースを作成します。
+import	write	コンパイル済みの Markdown ZIP を、個人用または会社用の読み取り専用スナップショットとしてインポートします。--scope の既定値は personal です。
+import-status	read	--request-id を指定して、ポーリングせずにスナップショットのインポートタスクを 1 つ照会します。出力には永続化された scope が含まれます。
+add	write	ローカルファイル（ZIP ディレクトリソースを含む）、再帰しないディレクトリ、または Markdown に変換した HTTP(S) ページをアップロードします。
+url	write	任意の表示名と解析指示を指定して、URL ソースを直接アップロードします。
+schema	write	ナレッジベースのコンパイルスキーマを生成します。
+compile	write	増分モードまたは全体モードでナレッジベースをコンパイルします。
+status	read	ナレッジベースの現在のステータスを照会します。
usage list	read	経過時間をミリ秒単位で含む、コンパイル使用状況ログの 1 ページを一覧表示します。
+rm-source	high-risk-write	安定 ID を使用して、ナレッジベースからソースを 1 つ削除します。正確な表示名の指定は、レガシー互換性のためにのみ使用されます。
+remove	write	ナレッジベース全体を削除します。

コンパイル使用状況ログ

ae-cli kb usage list --name handbook --scope personal --page 1 --page-size 20
ae-cli kb usage list --name handbook --jq '.items | map({createdAt, taskType, status, durationMs})' --format table

• { items, total, page, pageSize } を返します。--page の既定値は 1、--page-size の既定値は 20 で、1～100 を指定できます。各ページを明示的に取得してください。
• durationMs は使用状況ログの finishedAt - startedAt をミリ秒単位で示します。タイムスタンプがないか無効な場合は null になり、ゼロはゼロのままです。usageAvailable が false でも、失敗したレコードに所要時間が記録されている場合があります。
• 過去の所要時間はコンパイル実行記録から再構成されません。startedAt と finishedAt は ISO タイムスタンプ、または null です。
• Web のコンパイル使用状況一覧と同じ Schema 読み取り権限が必要です。インポートされたスナップショットでは使用状況を参照できません。--scope は個人用または会社用のいずれかを厳密に指定します。省略すると、従来どおり個人用から会社用の順に検索します。
• --dry-run を指定すると、リクエストを送信せずに読み取り内容をプレビューします。既定の出力では数値／null 値が保持されます。コンパクトな表を表示するには、既存の --jq および --format table オプションを使用してください。

移行ステータス：移行期間中 担当モジュール：te-claude External Knowledge Base Usage API 現在のトランスポート：kbApi 経由の認証済み External REST ゲートウェイの移行先：未定（コンパイル使用状況一覧） レビュー期限：2026-12-14 完了条件：型付きページネーションと所要時間／null のセマンティクスを維持しながら、利用可能になった時点で Gateway 相当の機能に移行します。

公開済みバージョン履歴

不変の公開済み履歴を調べ、ソースの変更を比較し、以前のバージョンを新たな公開として明示的にロールバックするには、references/versions.md に記載されている9つのバージョンコマンドを使用します。これらのコマンドは履歴を管理します。+index/+grep/+read/+ask は引き続き現在の公開済みコンテンツを使用します。

コマンド	リスク	目的
+versions	read	公開済みバージョンと latestVersionId を一覧表示します。
+version-show	read	1つのバージョンの概要を表示します。
+version-sources	read	履歴内のソース ID を確認します。
+version-diff	read	2つのバージョンを比較します。
+version-tree	read	履歴内の ZIP／URL ソースディレクトリを一覧表示します。
+version-read	read	履歴内のディレクトリ内にあるファイルをプレビューします。
+version-download	read	通常の履歴ファイルソースを1つ保存します。ディレクトリのダウンロードはできません。
+rollback	high-risk-write	以前のバージョンを復元し、新しいバージョンを作成します。
+rollback-status	read	ポーリングせずに、永続化されたロールバック Operation の状態を確認します。

ソース下書きの置換と復元

ファイル／ZIP ソースの置換と復元には、references/source-mutations.md を使用します。これらの新しいコマンドは kb source <action> を使用します。+rollback は引き続き、ナレッジベース全体の公開操作です。

コマンド	リスク	目的
source replace	write	通常のファイル下書きを置換するか、ZIP アーカイブの置換プレビューを準備します。
source restore	write	公開済みバージョンからファイル下書きを復元するか、ZIP ソース／子項目の復元プレビューを準備します。
source preview	read	確認前に、ZIP の変更候補をページごとに読み取ります。
source commit	high-risk-write	削除を含め、レビュー済みの ZIP 候補を確定します。
source cancel	high-risk-write	未確定の ZIP 候補を破棄します。

変更には、正確な --name、--scope、現在の --id、および現在の --expected-revision が必要です。ファイルの置換では元の形式を維持しますが、ファイル名は変更できます。ZIP には .zip が必要です。URL／Feishu と削除済みの親ソースはサポートされていません。更新は下書きのみに適用されます。公開には引き続きコンパイルが必要です。ZIP のプレビューを自動的に確定してはいけません。結果が不確かな書き込みを再試行しないでください。

ZIP ディレクトリソース

+add --files '["./sources.zip"]' を使用すると、内部階層を維持したまま、ZIP を 1 つの編集可能な親ソースとしてアップロードできます。アーカイブの検証と上限はサーバーによって適用されます。これは、読み取り専用のコンパイル済みスナップショットを作成する +import とは異なります。ローカルディレクトリを +add に渡した場合も、サポートされている直下のファイルのみがアップロードされ、ディレクトリが再帰的にパッケージ化されることはありません。

+list-sources で正確な親 ID を確認します。ZIP の行には fileCount、sizeBytes、contentRevision、updateStatus が含まれます。

コマンド	リスク	目的
+source-ls	読み取り	1 ページ分のディレクトリを一覧表示し、リビジョン、現在の子要素、成功したベースライン以降に削除されたパスを表示します。
+source-read	読み取り	子ソースファイルを UTF-8／base64 で読み取るか、元のバイト列を保存します。
+source-put	書き込み	ローカルファイルを 1 つ追加するか、ZIP 内の正確な相対パスを明示的に置き換えます。
+source-rm	高リスクの書き込み	子ファイルを 1 つ削除するか、子ディレクトリを再帰的に削除します。

ae-cli kb +source-ls --name handbook --id <source-id> --path "" --limit 100
ae-cli kb +source-ls --name handbook --id <source-id> --path "guides" --cursor <nextCursor>
ae-cli kb +source-read --name handbook --id <source-id> --path "guides/intro.md"
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --output ./chart.png
ae-cli kb +source-read --name handbook --id <source-id> --path "images/chart.png" --encoding base64
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7 --dry-run
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./new.md --action add --expected-revision 7
ae-cli kb +source-put --name handbook --id <source-id> --path "guides/new.md" --file ./revised.md --action replace --expected-revision 8
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/new.md" --expected-revision 9
ae-cli kb +source-rm --name handbook --id <source-id> --path "guides/obsolete" --recursive --expected-revision 10
ae-cli kb +compile --name handbook --mode incremental

• 現在の検出結果からソース ID、パス、リビジョンをコピーします。名前の解決には既存の External API に従って個人用、次に会社用の順で使用されます。これらのコマンドではスコープを上書きできません。
• --path は ZIP のルートからの相対パスであり、ローカルファイルシステムのパスや raw/zip/... のパスではありません。ルートを一覧表示する場合は空のパスを指定します。空でないパスを絶対パスにしたり、空、ドット、親、バックスラッシュを含むセグメントを含めたりすることはできません。
• 一覧表示では 1 ページのみが返されます。nextCursor と同じパスを使って続行してください。リビジョンが変わった場合は、書き込みの前に検出をやり直してください。
• +source-read はソースのバイト列を読み取ります。+read はコンパイル済み Wiki ページを読み取ります。既定の UTF-8 出力では、無効な UTF-8 があると失敗します。base64 はバイナリデータを保持します。--output は新しいローカルファイルを作成し、既存ファイルの上書きを拒否します。
• +source-put は最大 50 MB のファイルを 1 つ受け付けます。既定の --action add は既存のパスを拒否します。--action replace は、既存の子要素の上書きを明示的に許可します。サイレントなアップサートはありません。ドライランではメタデータが表示され、ファイルの内容は伏せられます。
• 書き込みには --expected-revision が必須です。409 の競合が発生した場合は、サーバーのエラーコードとともに返されます。このコマンドがリビジョンを更新して書き込みを自動的に再試行することはありません。
• +source-rm は親ソースを保持します。空でないディレクトリを削除するには --recursive が必要です。削除には CLI の確認ゲートが適用されます。対象を正確に指定した自動削除がすでに承認されている場合に限り、--yes を使用してください。+rm-source --id は親ソース全体を削除します。
• 変更を行うと親ソースは変更済みとしてマークされますが、コンパイルの開始や Schema の再生成は行われません。増分コンパイルを明示的に実行し、次のテスト段階に進む前に公開が成功するまで待ってください。
• +status は既存の集約ステータスクエリです。実行ごとのイベントや ZIP Diff を読み取るものではありません。コンパイルの送信応答を公開の成功と解釈しないでください。
• 現在の KB 実装には、対応する Gateway は登録されていません。これらのコマンドは、型付きの External ソース API を再利用します。

移行ステータス：移行中
担当モジュール：te-claude External Knowledge Base Sources API
現在のトランスポート：kbApi とマルチパート kbUpload を介した認証済み External REST
Gateway の移行先：未定（ZIP ソースディレクトリと raw ファイルの機能）
次回レビュー：2026-12-06
移行完了条件：同等の型付き Gateway ファイル、ディレクトリ、リビジョン対応の変更機能が利用可能になった時点で移行します。CLI のファイル処理と明示的な変更のセマンティクスは維持します。

一般的なワークフロー

ナレッジベースを作成する

名前を指定して +new を使用します。--scope は省略可能で、既定値は company です。有効なスコープは personal と company です。

ae-cli kb +new \
  --scope company \
  --name engineering-handbook \
  --description "Engineering handbook" \
  --tags '["engineering","handbook"]'

省略可能なフィールド：

• --scope：スコープ。既定値は company です。
• --description：説明。最大 200 文字です。
• --tags：JSON 配列。タグは最大 2 つで、それぞれ最大 15 文字です。
• --project-id：紐付けるプロジェクト ID（省略可能）。
• --project-name：プロジェクトの表示名（省略可能）。

コンパイル済みスナップショットをインポートする

+import は、ルートに index.md と少なくとも 1 つの wiki/**/*.md ページが含まれる ZIP にのみ使用してください。サーバーはすべてのアーカイブパス、制限、UTF-8 テキスト、Wiki リンクを検証します。

ae-cli kb +import \
  --file ./knowledge-base.zip \
  --name "Imported handbook" \
  --description "Compiled documentation snapshot" \
  --tags '["docs","handbook"]'

# The submission returns requestId + queued. Query one snapshot later:
ae-cli kb +import-status --request-id <requestId>

• 結果は常に読み取り専用の personal スナップショットです。--scope、--force、置き換えオプションはありません。

• インポートしたスナップショットでは、一覧表示、Index／Wiki の読み取り、grep／読み取り、Ask、削除が可能です。ソース、Schema、使用状況、コンパイル、メンバー、設定、所有権の譲渡、会社への公開に関する操作は利用できません。

• ZIP の上限は 50 MB で、Markdown テキストのみをサポートします。ローカル画像、添付ファイル、その他のバイナリ、リンク切れの Wiki リンク、曖昧な Wiki リンクはサーバーによって拒否されます。

• 送信すると、ZIP の検証や公開を待たずに {requestId, status: "queued"} が直ちに返されます。

• +import-status は queued、running、succeeded、failed のいずれかを返します。成功時には knowledgeBaseId が、失敗時には固定のエラーコード／メッセージが含まれます。

• requestId が返された場合は、再試行する前にその ID を照会してください。リクエスト ID を受け取れなかった場合は、同じ名前で再試行する前に ae-cli kb +list を実行してください。同じ名前でのインポートを繰り返すと拒否されます。

• 移行ステータス：移行中

• 所有モジュール：te-claude External Knowledge Base Import API

• 現在のトランスポート：送信には kbUpload、ステータス照会には kbApi を使用する、認証済み KB 外部 REST。

• Gateway の移行先：未定（kb.snapshot.import を提案）

• 再確認日：2026-12-01

• 完了条件：同等のマルチパートインポート機能が利用可能になったら、型付き Gateway 機能に移行します。または、動的な Gateway 実行で同じファイル処理と出力仕様が提供される場合は、このコマンドを削除します。

ファイルまたはディレクトリをアップロードする

ローカルファイル、ローカルディレクトリ、またはアップロード前に取得して Markdown に変換するページをソースとする場合は、+add を使用してください。

ae-cli kb +add \
  --name engineering-handbook \
  --scope company \
  --files '["./README.md","./docs","https://example.com/guide"]'

入力ルール：

• --files は文字列の JSON 配列でなければなりません。
• ローカルディレクトリの読み取りは再帰的ではありません。
• URL のエントリは http:// または https:// で始まる必要があります。
• サポート対象の拡張子には、Markdown／テキスト、オフィス文書、PDF、スプレッドシート、プレゼンテーション、一般的な画像形式が含まれます。ローカルファイルはマルチパートのファイルブロブとしてアップロードされ、HTTP(S) ページは取得後、アップロード前に Markdown に変換されます。
• ファイル名が重複する場合は、name-1.ext、name-2.ext などのサフィックスが自動的に付加されます。

URL ソースを追加する

URL ソースを 1 つ追加し、必要に応じて表示名または解析指示を渡す場合は、+url を使用してください。

ae-cli kb +url \
  --name engineering-handbook \
  --scope company \
  --url https://example.com/guide \
  --display-name guide \
  --parse-instruction "Keep headings and code blocks"

--url は http(s) でなければなりません。サーバーは URL からプラットフォームを自動的に検出します。*.feishu.cn または *.larksuite.com サブドメインの URL は、Feishu パイプラインで解析されます（サブドキュメントを含み、サーバー独自の Feishu 解析指示を使用します。これらの URL では --parse-instruction は無視されます）。それ以外の URL は通常の Web ページとして取得されます。

スキーマの生成とコンパイル

ナレッジベースにコンパイル用スキーマが必要な場合は、まずスキーマを生成します。

ae-cli kb +schema --name engineering-handbook --scope company

+status が schema_generating を報告し、ユーザーが現在の生成の試行を置き換えることを明示的に希望している場合に限り、--force を使用してください。置き換えにより、追加のトークンを消費する可能性があります。

Schema と Compile では、同じ任意のモデル参照を指定できます。ae-cli agent +list-models で返されるモデルレコードの id（Model.id）を使用してください。過去の modelId と、曖昧さのない modelId::scope 形式も引き続き使用できます。モデルの displayName は表示用のテキストであり、安定した参照ではありません。

保存済みのナレッジベースのメタデータを変更せず、この生成に限ってガイダンスを追加するには、--custom-instructions を渡します。サーバーは値の前後の空白を削除し、空白文字だけの入力は未指定として扱い、最大10,000個の Unicode 文字を受け付けます。シークレットや認証情報は含めないでください。

ae-cli kb +schema \
  --name engineering-handbook \
  --scope company \
  --model <model-ref> \
  --custom-instructions "Prioritize troubleshooting workflows and preserve command examples"

リクエスト本文を送信前に確認するには、--dry-run を使用します。生成の実行中に --force を指定せずにリクエストする場合、新しいモデルも有効なカスタム指示も指定しないときに限り、冪等になります。それ以外の場合は KB_SCHEMA_GENERATION_IN_PROGRESS エラーになります。--force を指定すると、選択したモデルとカスタム指示が置き換え後の試行に適用されます。無効なテキストを指定すると、KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID エラーになります。

ソースとスキーマの準備ができたら、コンパイルします。

ae-cli kb +compile --name engineering-handbook --scope company --mode incremental --model <model-ref>

有効なコンパイルモードは incremental と full で、デフォルトは incremental です。

ナレッジベースのステータスを確認する

+status を使用して、ナレッジベースの現在のステータスを確認します。

ae-cli kb +status --name engineering-handbook --scope company

ナレッジへの質問（LLM）

複数のページを横断した統合やマルチホップ推論が必要な質問には +ask を使用します。サーバー側のエージェントが検索ループ全体を実行し、ソースのパスとともに統合した回答を返します。決定論的な検索で十分な場合は、+index -> +grep -> +read を優先してください。

+ask コマンドは非同期の送信／ポーリング方式を使用します。デフォルトでは完了まで自動的にポーリングし（5秒ごと、最大10分間）、実行 ID、ソース、モデル使用状況、ツール呼び出し回数、モデル ID とともに最終回答を出力します。

# Default: submit and poll for completion
ae-cli kb +ask \
  --question "How do we troubleshoot payment alerts?" \
  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
  --model-id claude-sonnet-4-6 \
  --locale zh

# Submit only, return executionId immediately (for batch processing)
ae-cli kb +ask --question "..." --no-wait

# Query execution status later
ae-cli kb +ask-status --execution-id <id>

• --question、別名 -q：必須の自然言語の質問（1～2000文字）。
• --sources：ナレッジベース参照の任意の JSON 配列。省略すると、アクセス可能なすべてのナレッジベースを検索します。
• --model-id：任意の LLM モデル ID。省略すると、プラットフォームのデフォルトを使用します。
• --locale：任意のロケール：zh、en、ja、ko。
• --no-wait：任意のブール値フラグ。ポーリングせず、送信直後に {executionId, status} を返します。
• エラー処理：実行に失敗すると、コマンドはゼロ以外の終了コードで終了し、標準エラー出力に統一 JSON エラーエンベロープ {"ok":false,"error":{"type":"api","code":"<server-code>","message":"..."}} を出力します。安定したサーバーコードは model_unavailable、sandbox_unavailable、agent_skill_unavailable、dispatch_auth_unavailable、provider_failed、retrieval_error、timeout、process_restart です。

アクセス可能なナレッジベースを一覧表示する

index.md のナビゲーションマップを読み込まずに、アクセス可能なナレッジベースのメタデータのみを取得する場合は +list を使用します。デフォルトを compiled にするには --build-status を省略します。特定のステータスで絞り込むには、idle／pending／compiling／compiled／failed を渡します（システムナレッジベースはステータスに関係なく常に一覧表示されます）。

ae-cli kb +list
ae-cli kb +list --locale zh
ae-cli kb +list --build-status compiled

ナレッジベースのページを調べる

エージェントがコードリポジトリのようなナレッジベースのコンテンツを調べる場合は、決定論的な取得プリミティブを使用します。これらのエンドポイントは、サーバー側で LLM を呼び出しません。

実際のクエリを実行する前に、references/query-workflow.md をお読みください — クロールせずに、次に有用な取得ステップを選択できます。候補のインデックス作成、コピーしたパスの grep、リンク先の短いページの範囲を限定した直接読み取り、同一ページ内の読み取り範囲、必要に応じたリンク先ページの再 grep、任意のアウトライン由来の範囲、網羅性の評価について説明しています。以下のセクションは、このワークフローで参照するコマンドごとのガイドです。

アクセス可能なナレッジベースを見つけるには、まず +list または +index を実行します。ナビゲーションマップも必要な場合は、+index を使用します。

ae-cli kb +list

ae-cli kb +index \
  --sources '[{"scope":"company","name":"engineering-handbook"}]'

次に +grep を使用して、該当する可能性のあるページを見つけます。

ae-cli kb +grep \
  --query "sandbox configuration" \
  --sources '[{"scope":"company","name":"engineering-handbook"}]' \
  --paths '["wiki/sandbox.md"]' \
  --top-k 10

レスポンスはページ単位の results 配列です。各エントリは 1 つのページを表し、完全な hitCount、pageKind（content または catalog）、最大 4 件の sections プレビュー（パンくずリスト、sectionStartLine／sectionEndLine、テキストプレビュー）、および moreSections を含みます。hitCount とプレビューを参考に、読み取るページを決めてください。pageKind: "catalog" はモジュールのディレクトリページを示します。そこにある項目は詳細ページへのナビゲーションとして扱い、回答の情報源にはしないでください。--offset sectionStartLine／--limit sectionEndLine - sectionStartLine + 1 を指定してセクションの範囲を読み取ります。moreSections > 0 で、プレビューに回答がない場合は、そのページだけを再度 grep し、すべてのヒットを確認します。

現在の対象ページに信頼できる grep の範囲がなく、セクションを選ぶために見出しが必要な場合は、+read --outline を使用します。

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --outline

次に +read を使用して、ページグループ内のセクション境界、または隣り合う 2 つのアウトライン見出しを指定し、選択した範囲を開きます。

ae-cli kb +read \
  --source '{"scope":"company","name":"engineering-handbook"}' \
  --path "wiki/sandbox.md" \
  --offset 42 \
  --limit 60 \
  --expand block

テキストソースの作成、読み取り、編集

テキストの収集、編集可能なソース全体の読み取り、または通常の .md、.markdown、.txt ソースの更新を行う場合は、テキストソースのワークフローをお読みください。明示的なスコープ、UTF-8／BOM／改行の保持、ローカル出力の排他性、リビジョンの競合、機密情報を伏せたドライラン、手動コンパイルについて説明しています。Web と CLI では同じソース ID を使用します。

ソースの一覧表示

対象のソースの安定した識別子を確認するため、まずソースを一覧表示します。

ae-cli kb +list-sources --name engineering-handbook --scope company

レスポンスの id をそのまま +rm-source にコピーしてください。ローカルのファイル名、URL、表示名、以前のアップロードレスポンスからソース ID を推測しないでください。

• 移行ステータス：移行中
• 所有モジュール：te-claude ナレッジベースのソース管理
• 現在のトランスポート：External Knowledge Base REST API
• ゲートウェイの移行先：未定
• 再確認日：2026-11-12
• 終了条件：同等のソース一覧表示機能を備えた型付き Gateway 機能が利用可能になったら移行するか、動的な Gateway 実行で同等の検出可能性と安全な出力契約が提供される場合は、このコマンドを削除します。

1 つのソースを削除する

現在の +list-sources のレスポンスで返された正確な ID を指定して、+rm-source --id を使用します。これは high-risk-write です。ユーザーが --yes を明示的に許可していない限り、対話式の確認を維持してください。

ae-cli kb +rm-source \
  --name engineering-handbook \
  --scope company \
  --id cm-source-id

--display-name は、安定したソース ID を利用できない場合に限り、レガシー互換性のために保持されています。

ae-cli kb +rm-source \
  --name engineering-handbook \
  --display-name kb-1780046712-guide.md

ユーザーから大まかなソース名だけが示された場合は、ソース ID を推測しないでください。+list-sources を実行し、返されたメタデータから対象の行を特定します。複数の行が残り、判別できない場合にのみ質問してください。

ナレッジベースを削除する

ナレッジベース全体を削除するには +remove を使用します。対象の名前に少しでも曖昧さがある場合は、ユーザーに確認してください。

ae-cli kb +remove --name engineering-handbook --scope company

コマンドリファレンス

+ask

ae-cli kb +ask --question "<question>" [--sources '[{"scope":"company","name":"kb-name"}]'] [--model-id claude-sonnet-4-6] [--locale zh|en|ja|ko] [--no-wait]

• --question、別名 -q：必須。自然言語での質問（1～2000 文字）。
• --sources：任意。ナレッジベース参照の JSON 配列です。省略すると、アクセス可能なすべてのナレッジベースを検索します。
• --model-id：任意。LLM モデル ID です。省略すると、プラットフォームのデフォルトが使用されます。
• --locale：任意のロケールです。zh、en、ja、ko のいずれかを指定します。
• --no-wait：任意。ポーリングせず、{executionId, status} をすぐに返します。
• 使用する場面：複数ページの統合や、複数段階の質問に使用します。単純な事実確認には、+index / +grep / +read を優先してください。
• 出力：デフォルトでは、ポーリングして {executionId, answer, sources, modelUsage, toolCallCount, modelId} を返します。--no-wait を指定すると、すぐに {executionId, status} を返します。失敗時は、error.type="api"、サーバーの error.code（model_unavailable、sandbox_unavailable、agent_skill_unavailable、dispatch_auth_unavailable、provider_failed、retrieval_error、timeout、または process_restart）、および error.message を含む統一された stderr エンベロープを出力し、ゼロ以外の終了コードで終了します。

+ask-status

ae-cli kb +ask-status --execution-id <id>

• --execution-id：必須。+ask の送信時に返された実行 ID です。
• 出力：成功した CLI エンベロープのスナップショットを 1 つ返します。実行が失敗した場合、安定したサーバーコードは data.error.code に保持されます：{"ok":true,"data":{"executionId":"...","status":"failed","error":{"code":"retrieval_error","message":"..."}}}。ポーリングは行いません。

+list

ae-cli kb +list [--build-status compiled] [--locale zh|en|ja|ko]

• --build-status：任意。idle / pending / compiling / compiled / failed のいずれかです。省略すると compiled がデフォルトになります（システムのナレッジベースはステータスにかかわらず常に一覧に表示されます）。
• --locale：任意のロケールです。zh、en、ja、ko のいずれかを指定します。
• 応答項目には buildStatus が含まれます。

+index

ae-cli kb +index [--sources '[{"scope":"company","name":"kb-name"}]'] [--locale zh|en|ja|ko]

• --sources：任意。ナレッジベース参照の JSON 配列です。省略すると、アクセス可能なすべてのナレッジベースを一覧表示します。
• --locale：任意のロケールです。zh、en、ja、ko のいずれかを指定します。

+grep

ae-cli kb +grep --query "<keywords>" --sources '[{"scope":"company","name":"kb-name"}]' --paths '["wiki/page.md"]' [--top-k 10] [--locale zh|en|ja|ko]

• --query、別名 -q：必須。検索するキーワードです。
• --sources：必須。ナレッジベース参照の JSON 配列です。
• --paths：必須。現在の +index、+grep、または +read のナビゲーションリンクからコピーした Wiki ページまたはサブディレクトリの JSON 配列です。パスを推測して指定しないでください。単一のページでも配列で指定します（例：["wiki/sandbox.md"]）。+read --path（文字列 1 つ）とは異なります。
• --top-k：任意。ヒットの最大件数です。1～50 を指定でき、デフォルトは 10 です。
• --locale：任意のロケールです。zh、en、ja、ko のいずれかを指定します。
• 結果の各ページ項目には、hitCount（一致した総数）、pageKind、および sectionStartLine / sectionEndLine を含む sections のプレビューが含まれます。セクションの範囲を +read のウィンドウとして使用してください。

+read

ae-cli kb +read --source '{"scope":"company","name":"kb-name"}' --path "index.md" [--offset 1] [--limit 200] [--expand block|none] [--outline] [--locale zh|en|ja|ko]

• --source：必須。ナレッジベースを 1 つだけ指定する JSON オブジェクトです。
• --path：必須。ナレッジベースのルートからの相対ページパスです（例：index.md または wiki/concepts/data-model.md）。
• --offset：任意。1 始まりの整数で指定する開始行です。
• --limit：任意。最大行数です。1～2000 を指定できます。
• --expand：任意。Markdown ブロックの展開モードです。block を指定すると、要求した行ウィンドウの外にある完全な Markdown ブロックをサーバーが含めることができます。none を指定すると、offset/limit で指定した範囲を厳密に維持します。省略すると、サーバーのデフォルトである block が使用されます。
• --outline：任意。ページ全体の見出しツリー（{level, heading, line}）のみを返し、本文は空になります。--offset / --limit とは無関係です。長いページで、読むセクションを選ぶ際に使用します。
• --locale：任意のロケールです。zh、en、ja、ko のいずれかを指定します。

+new

ae-cli kb +new --name "<name>" [--scope personal|company] [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."] [--project-name "..."]

+add

ae-cli kb +add --name "<name>" --files '["./a.md","./docs","https://example.com/page"]' [--scope personal|company]

+import

ae-cli kb +import --file "./knowledge-base.zip" --name "<name>" [--description "..."] [--tags '["t1","t2"]'] [--project-id "..."]

• --file：必須。ローカルの .zip ファイルです。
• --name：必須。個人用ナレッジベースの名前です。最大 30 文字です。
• --description：任意。最大 200 文字です。
• --tags：任意。タグが重複しない JSON 配列で、最大 2 個、各タグは最大 15 文字です。
• --project-id：任意。プロジェクトとの関連付けです。
• スコープと最終的なビルド状態はサーバーが生成するため、クライアントから指定できません。
• 出力：{requestId, status: "queued"}。+import-status を使用してください。このコマンドはポーリングを行いません。

+import-status

ae-cli kb +import-status --request-id <requestId>

• --request-id：+import から返された必須の ID です。
• 出力：{requestId, status, knowledgeBaseId?, errorCode?, errorMessage?}。
• 単一のスナップショットを返し、ポーリングは行いません。インポートが失敗した場合は、安定したエラーコードとメッセージを含む status: "failed" が返されます。不明なリクエスト、またはアクセスできないリクエストの場合は、ゼロ以外の終了コードで終了します。

+url

ae-cli kb +url --name "<name>" --url "https://example.com/page" [--scope personal|company] [--display-name "..."] [--parse-instruction "..."]

+schema

ae-cli kb +schema --name "<name>" [--scope personal|company] [--force] [--model <model-ref>] [--custom-instructions "<one-time guidance>"]

• --custom-instructions：実行ごとに指定できる、スキーマ生成のための任意のガイダンスです。保存されません。空白のみの入力は省略されます。サーバーは最大10,000 Unicode文字を許可し、使用不可の制御文字を拒否します。シークレットや認証情報を含めないでください。
• --force：スキーマ生成がすでに実行中で、ユーザーが明示的に置き換えを要求した場合にのみ、現在の試行を置き換えます。選択したモデルとカスタム指示が新しい試行に適用され、追加のトークンを消費する場合があります。
• --dry-run：実行時に送信されるものと同じ customInstructions リクエストフィールドを表示します。
• --model：任意の安定したモデル参照です。ae-cli agent +list-models の Model.id を推奨します。従来の modelId および modelId::scope も引き続き使用できます。
• --scope：任意の、ナレッジベースの完全一致スコープです。省略すると、従来の個人用から会社用の順で検索されます。
• エラー：KB_SCHEMA_CUSTOM_INSTRUCTIONS_INVALID は、フィールドの検証に失敗したことを示します。KB_SCHEMA_GENERATION_IN_PROGRESS は、生成が実行中で、--force を指定せずに新しいモデルまたは実質的に異なるカスタム指示を指定したことを示します。

+compile

ae-cli kb +compile --name "<name>" [--scope personal|company] [--mode incremental|full] [--model <model-ref>]

+status

ae-cli kb +status --name "<name>" [--scope personal|company]

+list-sources

ae-cli kb +list-sources --name "<name>" [--scope personal|company] [--content-type all|text]

• --name：必須のナレッジベース名です。
• --content-type：デフォルトは all です。text は、URL ソースと ZIP ソースを除く通常の .md、.markdown、.txt ソースを選択します（大文字と小文字は区別されません）。このリストコマンドではスコープは任意です。
• 出力：items には、安定した id を持つ有効なソースが含まれます。pendingDeletions には、現在の成功バージョンにまだ含まれている、ソフト削除済みのソースが含まれます。deletionMaintenance は別項目で、すでに公開された削除がクリーンアップ待ちであることを示す場合があります。パス、ハッシュ、認証情報、ソースの内容は返されません。
• 削除リストを解釈する前に、deletionProjection.state とその baseline を確認してください。pendingDeletions: [] と ready が示されている場合、そのベースラインでは保留中の削除はありません。pendingDeletions: null と changing、review_required、または unavailable が示されている場合は未確定です。reasonCode を表示し、null を空のリストとして扱わないでください。検証可能な完全な公開マニフェストがない従来のライブラリは、実際のバージョンが公開されるまで unavailable を返します。
• ロールバックによって、新しい現行バージョンが作成されます。古い削除レシートで、そのバージョンへの所属を上書きすることはできません。以降のソース削除には、再度公開が必要です。
• ソースを削除する前に、現在のレスポンスから正確な id をコピーしてください。推測してはいけません。

+rm-source

ae-cli kb +rm-source --name "<name>" --id "<source-id>" [--scope personal|company]

• --id：+list-sources からコピーした、推奨される安定したソース識別子です。
• --display-name：ID を使用できない場合にのみ使う、従来互換のセレクターです。
• 両方を指定した場合は、--id が優先されます。このコマンドはソースを1つだけ削除します。

+remove

ae-cli kb +remove --name "<name>" [--scope personal|company]

インポートと置換のコンパイルルール

Markdown のコンパイルルール候補をアップロード、検証、編集、修復、レビュー、適用するには、スキーマインポートコマンドを使用してください。これらの操作では、ソースからルールを生成したり、コンパイル済みのスナップショットをインポートしたりすることはありません。

Feishu ソースの更新を確認する

ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-updates --name "Engineering Handbook" --id "<source-id>" --scope company

kb +list-sources から ID をコピーします。ソースへの書き込み権限が必要です。コンパイル済みで、削除されていない Feishu URL ソースのみが対象です。API はスケジュールタスクと同じ検出機能を使用し、既存の保留中変更のスキップと、ソース所有者のサンドボックス認証情報も適用されます。コンパイルを開始したり、保留中の変更をクリアしたりすることはありません。

同期レスポンスには sourceId、scanned、updated、failed、urlChangeState、updateStatus が含まれます。scanned は候補の数であり、コンテンツ比較の完了数ではありません。updated は新たに変更済みとしてマークされたソースの数です。更新が 0 件の場合、コンテンツに変更がない、すでに変更が保留中である、以前の raw データを利用できない、または状態が同時に変更された可能性があります。すべてのコンテンツが同一である証拠として報告してはいけません。確認に失敗すると、non-2xx レスポンスと CLI エラーが返されます。タイムアウトしても、処理の完了やキャンセルが確認されたことにはなりません。再試行するかどうかを決める前に、kb +list-sources を参照してください。

トランスポート：POST /agent/api/external/knowledge-bases/sources/check-updates、本文 {name, sourceId, scope?}。--dry-run はリクエストのプレビューのみを行い、認証もリモート権限の確認も行いません。

審査記録：source check-updates

• 分類：移行期間中（この新しい検出トリガーに相当する Gateway 機能はありません）。
• 担当モジュール：te-claude ナレッジベースのソース管理。
• 現在のトランスポート：kbApi と CLI トークンを介した KB 外部 REST。
• Gateway の移行先：未定。利用可能になったら、同等のソース更新確認機能を再利用します。
• 再審査日：2026-10-16 以降。
• 終了条件：Gateway が同等の認可と検出のセマンティクスを提供したら、型付きコマンドを L2 に移行するか、価値を追加しない場合は L3 を使用します。

通常の URL 更新確認を送信する

ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company --dry-run
ae-cli kb source check-url-updates --name "Engineering Handbook" --id "<source-id>" --scope company

既存の sourceType=url、platform=custom で、コンパイル済みかつ更新が保留中でないソースのみが対象です。Wiki／Schema のコンパイルまたは入力の準備が進行中の場合、リクエストは拒否されます。成功レスポンス {accepted:true,sourceId} が示すのは、リクエストが受け付けられたことだけです。最終件数、タスク ID、確認中の状態、待機モード、完了状況の照会機能はありません。更新マーカーを確認するには kb +list-sources を参照してください。状態に変化がない場合、処理が実行されたか、変更がなかったか、失敗したか、結果が破棄されたかを判別できません。変更済みとしてマークされたら、既存の増分コンパイルを明示的に実行してください。Feishu では引き続き同期型の source check-updates を使用します。

トランスポート：POST /agent/api/external/knowledge-bases/sources/check-url-updates、本文 {name,sourceId,scope?}。ドライランでは、リクエストを送信せずにプレビューします。送信エラーでは、サーバーのエラーコード、詳細、およびゼロ以外の終了コードが保持されます。

審査記録：source check-url-updates

• 移行状況：移行期間中（この新しい KB 外部機能に相当する Gateway 機能はありません）。
• 担当モジュール：te-claude ナレッジベースのソース管理。
• 現在のトランスポート：kbApi と CLI トークンを介した KB 外部 REST。
• Gateway の移行先：未定。同等の非同期通常 URL ソース確認機能を再利用します。
• 再審査日：2026-10-24 以降。
• 終了条件：Gateway が同等の認可と非同期送信のセマンティクスを提供したら、型付きフラグに価値がある場合は L2 に移行し、そうでない場合は L3 を使用します。