znas-photos

znas photos

ユーザーが NAS フォトについて質問した場合に使用します：写真や動画の検索、タイムライン/マップデータの参照、アルバム管理、アルバムのダウンロード、類似写真の検索、AI 認識された人物/ペットのアルバム調査など。

このスキルの目的

• フォト設定パスの読み取りと更新。
• インデックス化された写真/動画の検索、タイムラインバケットの読み取り。
• ユーザーアルバムの作成、一覧表示、更新、削除、ダウンロード。
• 類似写真スキャンタスクの開始/一覧表示/削除とグループの調査。
• フォトマップのクラスター、位置情報、マップスイッチ状態の読み取り。
• AI 認識された特徴アルバム（人物やペットなど）の読み取りと管理。

発見ルール

1. 推測ではなく、段階的な CLI 発見を優先します：
   • znas photos --help
   • znas photos <feature> --help
   • znas photos <feature> <command> --help
2. ルート一覧、ペイロードタイプ、例、バイナリ/書き込みフラグを JSON で確認する必要がある場合は、znas schema photos を使用します。
3. バックエンドのフィールド名は、help や schema に表示される通りに正確に保持します。例：fileIds、taskId、groupId、albumId、album_id、fIds、eaHash。
4. すべての ID を盲目的に文字列に変換しないでください。以前の API 読み取りで返されたフィールド名と値の形状を保持します。

安全ルール

1. 書き込みまたは削除の前に、現在の状態を読み取ります。
2. 書き込み/削除が成功した後、最終的な成功を報告する前に、対応する読み取りコマンドを再実行します。
3. znas photos ... でルートが利用可能な場合、ホストネイティブツールや内部の curl をフォトコントロールプレーン作業に使用しないでください。
4. フォトバックエンドは普遍的なドライランモードを公開していません。破壊的なアクションについては、最初に正確なターゲットを調査し、変更を狭い範囲に保ちます。
5. 非同期の類似写真スキャンの場合、タスク作成は作業をキューに入れるだけです。ステータス確認には similar task-list とグループ読み取りを使用します。
6. 通常のアルバムルートと AI 特徴アルバムルートは異なる表面です。album_id と albumId を混在させないでください。

バイナリ出力ルール

バイナリとしてマークされたルートでは、標準出力を解析可能に保つために -o <file> が必要です：

• znas photos album download ... -o album.zip
• znas photos photo stream ... -o live.mov
• znas photos feature avatar ... -o avatar.jpg

コマンドが失敗した場合、CLI はファイルを書き込む前に JSON エラーレスポンスを検証します。

一般的なワークフロー

フォト状態の読み取り

znas photos setting config
znas photos photo search --json '{"index":0,"size":20}'
znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'

アルバムワークフロー

znas photos album list --params '{"index":0,"size":20}'
znas photos album create --json '{"name":"Trip"}'
znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
znas photos album get --params '{"album_id":123}'
znas photos album download --json '{"album_id":123,"download_name_prefix":"Trip"}' -o trip.zip

類似写真

znas photos similar task-list --params '{"index":0,"size":20,"imgSize":20,"groupSize":4}'
znas photos similar task-create --json '{"dirPath":["/personal/Photos"]}'
znas photos similar group-list --params '{"taskId":123,"index":0,"size":20,"imgSize":20}'
znas photos similar group-detail --params '{"taskId":123,"groupId":456,"offset":0,"size":50}'

マップと AI 特徴アルバム

znas photos map last-location
znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
znas photos feature progress --params '{"taskType":1}'
znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'

機能

album

• POST download -> /downloadFiles (auth)
  • フラグ: binary
  • 正規コマンド: photos album download
  • ペイロード: --json
  • 例: znas photos album download --json '{"album_id":123,"download_name_prefix":"album"}' -o album.zip
  • 注意点: ダウンロードは album_id または str_paths を使用できます。バイナリ zip データを返すため -o <file> が必要です。
• POST create -> /album/createAlbum (auth)
  • フラグ: write
  • ペイロード: --json; 必須: name
  • 例: znas photos album create --json '{"name":"Trip","description":"2026 trip"}'
  • 注意点: 最初にアルバムを作成し、その後 album add-photos で写真を追加します。
• PUT update -> /album/updateAlbum (auth)
  • フラグ: write
  • ペイロード: --json; 必須: id
  • 例: znas photos album update --json '{"id":123,"name":"Trip edited"}'
  • 注意点: 通常のアルバム更新では、バックエンドフィールド id を使用し、album_id は使用しません。
• DELETE delete -> /album/deleteAlbum (auth)
  • フラグ: destructive
  • ペイロード: --json; 必須: id
  • 例: znas photos album delete --json '{"id":123}'
  • 注意点: 読み取り後にのみアルバムを削除します。バックエンドの動作が変更されない限り、元のファイルが削除されるわけではありません。
• GET list -> /album/listAlbum (auth)
  • ペイロード: --params; 必須: size
  • 例: znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}'
  • 注意点: List は GET クエリです。JSON ボディではなく index と size を使用します。
• POST add-photos -> /album/addPhotoToAlbum (auth)
  • フラグ: write
  • ペイロード: --json; 必須: album_id
  • 例: znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
  • 注意点: バックエンドフィールドは大文字の I を持つ fileIds です。正確な NAS パスがある場合は paths もサポートされています。
• DELETE remove-photos -> /album/removeAlubmPhotos (auth)
  • フラグ: destructive
  • 正規コマンド: photos album remove-photos
  • ペイロード: --json; 必須: album_id
  • 例: znas photos album remove-photos --json '{"album_id":123,"fileIds":["456"]}'
  • 注意点: CLI は上流のタイポ removeAlubmPhotos を隠蔽します。意味論的なコマンド remove-photos を使用します。
• GET get -> /album/getAlbum (auth)
  • ペイロード: --params; 必須: album_id
  • 例: znas photos album get --params '{"album_id":123}'
  • 注意点: アルバム詳細は GET クエリです。--params 経由で album_id を渡します。

feature

• GET progress -> /feature/process (auth)
  • ペイロード: --params
  • 例: znas photos feature progress --params '{"taskType":1}'
  • 注意点: taskType を省略すると、バックエンドのデフォルト進捗が読み取られます。ユーザーが顔やペットについて具体的に尋ねた場合に渡します。
• DELETE clear -> /feature/clear (auth)
  • フラグ: destructive
  • ペイロード: --json; 必須: taskType
  • 例: znas photos feature clear --json '{"taskType":1}'
  • 注意点: これにより、タスクタイプの発見された特徴アルバムデータがリセットされます。最初に進捗/リストを読み取ります。
• GET switch -> /feature/switch (auth)
  • ペイロード: --params; 必須: type
  • 例: znas photos feature switch --params '{"type":1}'
  • 注意点: Switch 読み取りはフィールド type を使用します。タスクアルバムフィルターは taskType を使用します。
• PUT set-switch -> /feature/switch (auth)
  • フラグ: write
  • ペイロード: --json; 必須: type, switch
  • 例: znas photos feature set-switch --json '{"type":1,"switch":1}'
  • 注意点: 切り替え後、最終状態を報告する前に feature switch を再読み取りします。
• PUT set-config -> /feature/switch/config (auth)
  • フラグ: write
  • ペイロード: --json; 必須: type, hideNum
  • 例: znas photos feature set-config --json '{"type":1,"hideNum":5}'
  • 注意点: hideNum を正確に使用します。このバックエンドではスネークケースは受け入れられません。
• GET album-list -> /feature/album/list (auth)
  • ペイロード: --params; 必須: index, size
  • 例: znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
  • 注意点: 認識された特徴アルバムは、taskType や isHide などのキャメルケースフィールドを使用します。
• GET album-count -> /feature/album/count (auth)
  • ペイロード: --params
  • 例: znas photos feature album-count --params '{"taskType":1,"isHide":false}'
  • 注意点: カウントだけでなくアルバム ID が必要な場合は、album-list を使用します。
• GET relation -> /feature/relation (auth)
  • ペイロード: --params
  • 例: znas photos feature relation --params '{"taskType":1}'
  • 注意点: リレーションは認識されたアルバムのオプションです。リレーションテキストを更新する前に読み取ります。
• GET album-get -> /feature/album (auth)
  • ペイロード: --params; 必須: albumId
  • 例: znas photos feature album-get --params '{"albumId":123}'
  • 注意点: 特徴アルバム ID はフィールド albumId を使用します。通常のアルバム詳細で使用される album_id とは異なります。
• PUT album-update -> /feature/album (auth)
  • フラグ: write
  • ペイロード: --json; 必須: albumId
  • 例: znas photos feature album-update --json '{"albumId":123,"name":"Alice"}'
  • 注意点: 以前の読み取りからの値がある場合のみ、coverId、coverPath、relation を使用します。
• POST album-hide -> /feature/album/hide (auth)
  • フラグ: write
  • ペイロード: --json; 必須: albumIds, isHide
  • 例: znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}'
  • 注意点: isHide を変更した後、非表示リストと表示リストを確認します。
• POST album-merge -> /feature/album/merge (auth)
  • フラグ: destructive
  • ペイロード: --json; 必須: albumIds, targetId
  • 例: znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}'
  • 注意点: 最初にすべてのソースアルバムを読み取ります。targetId は残るアルバムである必要があります。
• GET album-photos -> /feature/album/photos (auth)
  • ペイロード: --params; 必須: albumId, index, size
  • 例: znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'
  • 注意点: 認識されたアルバムにはこれを使用します。通常のユーザーアルバムには album get を使用します。
• PUT album-photo-update -> /feature/album/photo (auth)
  • フラグ: write
  • ペイロード: --json; 必須: albumId, fIds
  • 例: znas photos feature album-photo-update --json '{"albumId":123,"fIds":[456]}'
  • 注意点: これは認識された特徴写真の行を移動します。fIds は album-photos からの特徴行 ID です。
• DELETE album-photo-delete -> /feature/album/photo (auth)
  • フラグ: destructive
  • ペイロード: --json; 必須: fIds
  • 例: znas photos feature album-photo-delete --json '{"fIds":[456]}'
  • 注意点: 最初に album-photos を読み取り、返された特徴行 ID を再利用します。
• GET avatar -> /feature/avatar (auth)
  • フラグ: binary
  • ペイロード: --params; 必須: eaHash
  • 例: znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg
  • 注意点: このルートは画像ファイルを返します。常に -o <file> を渡します。

map

• GET forward -> /map/forward (auth)
  • ペイロード: --params; 必須: coords, model
  • 例: znas photos map forward --params '{"coords":"116.3,39.9","model":1}'
  • 注意点: 複数の座標は coords 内でセミコロン区切りです。
• GET switch -> /map/switch (auth)
  • ペイロード: --params; 必須: type
  • 例: znas photos map switch --params '{"type":2}'
  • 注意点: マップスイッチは特徴リクエストフィールド type を使用します。現在のマップスイッチタイプは通常 2 です。
• PUT set-switch -> /map/switch (auth)
  • フラグ: write
  • ペイロード: --json; 必須: type, switch
  • 例: znas photos map set-switch --json '{"type":2,"switch":1}'
  • 注意点: 書き込み後、最終状態を報告する前に map switch を再読み取りします。
• GET last-location -> /map/lastLocation (auth)
  • ペイロード: none
  • 例: znas photos map last-location
  • 注意点: 結果が空の場合、インデックス化された写真に使用可能な GPS データがない可能性があります。
• GET bounds -> /map/bounds (auth)
  • ペイロード: --params; 必須: minLat, maxLat, minLon, maxLon, zoomLevel
  • 例: znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
  • 注意点: Bounds はキャメルケースの緯度/経度フィールドを使用します。最小値は最大値より小さい必要があります。
• GET geohash -> /map/geohash (auth)
  • ペイロード: --params; 必須: geohash, index, size
  • 例: znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}'
  • 注意点: 複数のジオハッシュは単一の geohash 文字列内でセミコロン区切りです。
• GET countries -> /map/location/country (auth)
  • ペイロード: --params; 必須: index, size, viewType, citySize
  • 例: znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}'
  • 注意点: グループ化された位置情報の概要にはこのルートを使用します。国を選択した後、cities を使用します。
• GET cities -> /map/location/city (auth)
  • ペイロード: --params; 必須: country, offset, size
  • 例: znas photos map cities --params '{"country":"China","offset":0,"size":20}'
  • 注意点: 都市検索には、countries によって返された正確な country 文字列が必要です。
• GET city-photos -> /map/location/city/photo (auth)
  • ペイロード: --params; 必須: addressId, index, size
  • 例: znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}'
  • 注意点: 表示される都市名ではなく、都市レスポンスからの addressId を使用します。

photo

• POST search -> /photos/search (auth)
  • ペイロード: --json; 必須: index, size
  • 例: znas photos photo search --json '{"index":0,"size":20,"keyword_search":"beach"}'
  • 注意点: 写真検索は POST JSON です。keyword_search、album_ids、city_ids などのバックエンドフィールド名を保持します。
• GET timeline -> /photos/getTimeBuckets (auth)
  • ペイロード: --params
  • 例: znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'
  • 注意点: Timeline は GET ルートです。--json ではなく --params でフィルターを渡します。
• GET stream -> /photos/stream (auth)
  • フラグ: binary
  • ペイロード: --params; 必須: id
  • 例: znas photos photo stream --params '{"id":123456}' -o live.mov
  • 注意点: このルートはバイナリのライブフォトデータを返します。常に -o <file> を渡します。

setting

• POST init -> /setting/init (auth)
  • フラグ: write
  • ペイロード: --json; 必須: init_path
  • 例: znas photos setting init --json '{"init_path":"/personal/Photos"}'
  • 注意点: 初期化は写真ライブラリのルートパスを設定します。このパスは、写真のインデックス作成とスキャンの開始点として機能します。
• GET config -> /setting/config (auth)
  • ペイロード: none
  • 例: znas photos setting config
  • 注意点: 設定は現在の写真ライブラリのパスと構成を返します。書き込み操作の前に現在の状態を確認するために使用します。