olares-files

files（ユーザーごとのファイルバックエンド）

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

タスクがユーザースペースのバックエンド、耐久性、uid 1000、またはシステム管理の Home ディレクトリに関係する場合は、共通のプラットフォームモデルを読み込んでください。構文については olares-cli files <verb> --help を使用してください。

使用する場合

• 既知の Olares ファイルパスを指定、読み取り、書き込み、移動、削除、共有、または転送する場合。
• ファイルの圧縮／展開、または非同期タスクキューを管理する場合。
• SMB/NFS サーバーをマウントする場合、または Seafile リポジトリを管理する場合。

名前／内容によるファイル検索（およびインデックスの対象範囲 — すべての場所のファイル名か、/Documents/ 内のみの全文検索か）については、olares-search を参照してください。全文検索の対象となるディレクトリは、olares-settings の settings search dirs で設定します。

すぐに使える方法

タスク	参照先	最初のコマンド
ローカルファイルをユーザーの Drive に置く	名前の衝突時の判断とクラウド転送	olares-cli files upload ./report.pdf drive/Home/Documents/
ディレクトリの内容を確認する	このファイル	olares-cli files ls drive/Home/ -o json
1 つのファイルのバイト列を読み取る	このファイル	olares-cli files cat drive/Home/Documents/report.pdf
drive/Home 以外の場所を指定する	パスの構文と名前空間のルール	olares-cli files ls sync/<repo_id>/

パスと名前空間のサポート

すべてのリソースは fileType/extend[/subPath] という形式です。fileType は drive、cache、sync、external、awss3、dropbox、google、tencent、share、internal のいずれかで、extend はその中にあるボリューム、リポジトリ、またはアカウントです。たとえば、drive/Home、drive/Data、drive/Common、ノード名、Seafile リポジトリ ID、クラウドアカウントキーなどです。通常の Drive パスにはこれで十分です。

対象が drive/ の外にある場合、または実行しようとしている動詞がその名前空間をサポートするか確認する必要がある場合は、パスの構文と名前空間のルールを読み込んでください。サポート状況は動詞ごとに異なり、複数の動詞は、隣接する動詞が受け付ける名前空間を拒否します。

判断に影響するバックエンド固有の挙動

• ディレクトリの作成時、競合エラーを返す代わりに名前が自動変更されることがあります。 アップロードでは、宛先ディレクトリは事前に作成されません。名前を正確に指定する必要がある場合は、親ディレクトリを確認してから明示的に作成してください。
• ファイルリソースへの raw GET は HTTP 500 を返すことがあります。 files cat または files download を使用してください。raw リソース URL への再試行は避けてください。
• external/<node>/ は仮想ボリュームの選択先であり、書き込み先ではありません。書き込むには external/<node>/<volume>/... が必要です。
• drive/Home/ 直下の 11 個の予約名は、システムによって管理されています。rename、rm、および移動元としての mv は、リクエストを送信する前に拒否されます。cp と、その配下にあるすべての項目は編集できます。拒否メッセージには 11 個すべてが列挙されます。これはプラットフォームの不変条件であり、再試行すべき権限エラーではありません。代わりに、その配下の項目を操作してください。名前は完全一致で判定されるため、似ているだけの名前は保護されません。
• cache/<node>/ は有効なストレージですが、共有作成時に具体的なデータセットとしては扱えません。共有する場合は cache/<node>/<sub>/ を指定してください。

非同期タスクキュー（圧縮／展開）

• compress と extract はサーバー側の処理をキューに追加し、待機しない場合はタスク ID を返します。
• Ctrl-C で停止するのはローカルのポーリングだけです。ユーザーがタスクのキャンセルを意図している場合は、サーバーのタスクを明示的にキャンセルしてください。
• タスクはノードごとに管理されます。タスクをキューに追加したときに表示されたノードを記録しておいてください。
• task cancel --all は、そのノード上のすべてのタスクに影響します。別の場所で開始された処理も対象です。

バージョンゲート（Olares >= 1.12.6）

アーカイブ、NFS、drive/Common には Olares 1.12.6 以降が必要です。日次ビルドは major.minor.patch のベースバージョンで判定してください。バックエンドのバージョンを確認できない場合は、共通の認証／バージョンゲートに従ってください。

動詞インデックス

動詞	トリガー時に読む内容
ls	一覧表示とクラウドの形式
cat	stdout への生バイト出力と、ファイルリソースへの直接 GET が 500 を返す場合の、サポートされている読み取り方法
download	再開、上書き、ディレクトリのダウンロード
upload	競合時の判断、再開、並行処理；クラウドを宛先にした場合に追加される第 2 段階
edit	テキスト／サイズの制限と書き戻し
mkdir	親ディレクトリ、自動リネーム、外部パスの深さ
rm	存在確認、ディレクトリの意図、保護されたパス
rename	同じ場所でのリネームと保護されたパス
cp, mv	宛先と上書きのセマンティクス
chown	UID と名前空間に関する判断
compress	形式、競合、パスワード、非同期タスク
extract	宛先、競合、パスワード、非同期タスク
archive	読み取り専用のアーカイブ検査
task	ノードごとのキャンセル／一時停止／再開
share	内部／公開／SMB 共有
smb	検出、マウント、履歴
nfs	エクスポートの検出とマウント
repos	ID で Sync（Seafile）ライブラリを同期します。sync/ パスはリポジトリ ID を基に作られます

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

• ユーザーが依頼したファイル操作と指定したパスは、タスク範囲内の許可として扱います。対象が曖昧な場合、明示的な意図なしにバイト列が上書きされる可能性がある場合、削除対象が指定された対象を超える場合、または操作がその範囲を外れる場合に限り、再確認してください。
• アップロードでは、競合時に上書きするか、失敗させるか、別の名前を作成するかをまず判断してください。バックエンドによる自動リネームを、暗黙の判断として許容してはいけません。
• パスが見つからない場合の事前確認を、安全フラグを弱めて再試行してはいけません。
• task cancel --all はそのノードの無関係な作業にも影響するため、別途確認してください。
• トークンやパスワードは決して開示しないでください。利用可能な場合は、標準入力を使ってシークレットを入力してください。
• フロントエンドのパス、ノード／ボリュームの識別、上書きの意図、または並行削除が曖昧な場合は停止し、親ディレクトリを再度一覧表示してユーザーに確認してください。