olares-knowledge

knowledge

共通の入口： スイート内のルーティング、アクティブなプロファイルの選択、プラットフォームのエントリーポイント、認証の続行／停止ゲートについては、../olares-shared/SKILL.md を読み込んでください。ログイン、プロファイルの切り替え、トークンの保存、認証の復旧が実際に必要な場合に限り、その認証リファレンスを読み込んでください。

構文については olares-cli knowledge download <verb> --help を使用してください。

使用する場面

• URL、yt-dlp、aria2、torrent、HuggingFace、Wise のダウンロードサーバーのタスクを作成・管理する場合。
• プロバイダーや品質を確認する、タスクの変更を同期する、torrent の状態を管理する、またはダウンロード済みのリソースを調べる／削除する場合。
• ダウンロード設定やダウンロードサーバーの設定を読み取る／変更する場合。

トップレベルの download（インストーラーパッケージ用：download component／wizard／check）ではありません。files download（Drive／Sync ファイルの取得）でもありません。こちらは olares-files にあります。

バージョン要件

設定のダウンロード用エッジとプロバイダーの両方が必要なため、すべての動詞で Olares 1.12.7 以降が必要です。バージョンを確認できない場合は、アップグレードが必要だと判断する前に、共通のプロファイル／認証ゲートに従ってください。

すぐに使える手順

タスク	参照先	最初のコマンド
URL をダウンロードし、完了したら確認する	タスクの作成	olares-cli knowledge download create <url> -o json を実行し、続けて download wait <id>
現在ダウンロード中のものを確認する	このファイル	olares-cli knowledge download list -o json
リンクから取得できる品質を、選択する前に確認する	プロバイダー／品質の確認	olares-cli knowledge download inspect <url> -o json
すでにディスク上にあるか確認する	URL とリソースパスの使い分け	olares-cli knowledge download file exists <path> -o json

動詞一覧

分類	動詞	該当する場合の参照先
1 件を開始する	create、info、wait	タスクの作成と追跡
既存のタスクを管理する	list、pause、resume、cancel、remove	タスクの一覧表示、一時停止、終了
検査と設定	inspect、prefs get、prefs set	プロバイダー／品質の確認
同期	unfinished、sync	カーソルと処理完了のセマンティクス
torrent	torrent inspect、stats、peers、files、seed stop/resume、torrent create	torrent の選択とシード
ファイルツール	file exists、file remove	URL とリソースパスの使い分け
設定	settings get、settings set	ダウンロードサーバーのグローバル設定

タスクと非同期処理のセマンティクス

• Create はサーバー側のタスク ID を返します。コマンドが成功しても、バイトのダウンロードや移動が完了したとは限りません。ID を取得して、数秒ごとに info <id> をポーリングしてください。1 回の呼び出しで済ませたいスクリプト向けの create --wait で、ターンをブロックしないでください。いずれの場合も、終端状態を判断する基準はステータスのみです。waiting_to_move／moving はまだ処理中であり、will_auto_retry によってサーバーの一括処理で再度対象になる可能性が示されていても、error は失敗です。
• Create は、URL の検査時に取得したタイトルをもとにタスク自体の名前を付けます。ユーザーから特定のファイル名を指定された場合を除き、--name は付けないでください。また、URL のパスから名前を作成しないでください。create で送信した名前は、その後ずっと行に固定されます。マグネットリンク、--torrent によるアップロード、HuggingFace リポジトリでは、このフラグ自体が拒否されます。これらの名前は、トレントのメタデータまたはリポジトリ ID から取得されます。
• 同じ URL を再送信すると、毎回新しいタスクが作成されます（同一性による重複排除はありません）。保存先の名前が重複する場合は (n) の接尾辞で解決され、既存の行が再利用されたり、作成がブロックされたりすることはありません。Create は、1 回の試行における通信の再試行をまとめる目的でのみ Idempotency-Key を送信します。URL の重複排除には使われません。
• Pause は waiting または downloading の場合にのみ適用されます（それ以外は 400）。タスクが yt-dlp の移動フェーズ（waiting_to_move／moving）にある間は、Resume、cancel、remove は 409 を返します。待ってから再試行してください。Pause も同様だとは扱わないでください。
• タスクの所有権は、アクティブなプロファイルに従います。ID から別のユーザーのタスクだと推測したり、別の認証情報を試したりしないでください。
• inspect の結果は参考情報です。プロバイダーや品質の確認に失敗しても、create が成功する場合があります。URL をダウンロードできないと断定せず、その不確実性を伝えてください。
• 同期カーソルが示すのは変更の観測であり、タスクの完了ではありません。差分同期を続ける場合はカーソルを保持してください。

安全性とエスカレーション

• Create、cancel、remove、seed の停止／再開、ファイルの削除、設定値の書き込み、グローバル設定値の書き込みは確認を求めてください。
• Create の前に、保存先／アプリ、プロバイダーの意図、トレントファイルの選択、既存の同等タスクを再利用するかどうかを確認してください。list／info で確認してください。この CLI は重複を検出もブロックもしません。
• file remove が受け取るのはダウンロードサーバー上のリソースパスであり、任意のローカルファイルシステムパスではありません。
• ログイン情報が不足して URL の処理に失敗しても、そこで終了ではありません。Cookie は olares-settings の settings integration cookie にあります。ただし、この引き継ぎにはユーザーの対応が必要です。cookies.txt はユーザー自身がブラウザーからエクスポートしたものなので、ファイルを探すのではなく、ユーザーに提供を依頼してください。シグナルと手順の全体については、プロバイダー／品質の検査を参照してください。
• URL／リソースパス、タスクの所有者、重複タスクに関する意図、トレントの選択、または Cookie の受け渡しで対応できない認証情報の要求が曖昧な場合は、そこで止めてください。