znas photos
當使用者詢問 NAS Photos：搜尋照片或影片、瀏覽時間軸／地圖資料、管理相簿、下載相簿、尋找相似照片或檢視 AI 辨識的人像／寵物相簿時，請使用此技能。
此技能的用途
- 讀取與更新 Photos 設定路徑。
- 搜尋已索引的照片／影片並讀取時間軸區段。
- 建立、列出、更新、刪除與下載使用者相簿。
- 啟動／列出／刪除相似照片掃描任務並檢視群組。
- 讀取照片地圖叢集、位置與地圖開關狀態。
- 讀取與管理 AI 辨識的功能相簿（例如人像或寵物）。
探索規則
- 優先使用漸進式 CLI 探索，而非猜測：
znas photos --helpznas photos <feature> --helpznas photos <feature> <command> --help
- 當需要路由清單、負載類型、範例以及二進位／寫入旗標的 JSON 資料時，使用
znas schema photos。 - 完全保留 help/schema 中顯示的後端欄位名稱：例如
fileIds、taskId、groupId、albumId、album_id、fIds與eaHash。 - 不要盲目將所有 ID 轉為字串。保留先前 API 讀取回傳的欄位名稱與值格式。
安全規則
- 在每次寫入或刪除操作前，先讀取當前狀態。
- 寫入／刪除成功後，在回報最終成功前，重新執行對應的讀取命令。
- 當
znas photos ...提供路由時，不要使用主機原生工具或直接內部curl進行 Photos 控制平面工作。 - Photos 後端沒有通用的乾執行（dry-run）模式。對於破壞性操作，請先檢查確切目標並保持變動範圍狹小。
- 對於非同步的相似照片掃描，任務建立僅將工作排入佇列。使用
similar task-list與群組讀取檢查狀態。 - 一般相簿路由與 AI 功能相簿路由是不同的表面；不要混淆
album_id與albumId。
二進位輸出規則
標記為二進位的路由需要 -o <file> 以保持 stdout 可解析：
znas photos album download ... -o album.zipznas photos photo stream ... -o live.movznas 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
POSTdownload->/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>。
- 旗標：
POSTcreate->/album/createAlbum(auth)- 旗標：
write - 負載：
--json；必填：name - 範例：
znas photos album create --json '{"name":"Trip","description":"2026 trip"}' - 陷阱：先建立相簿，再用
album add-photos加入照片。
- 旗標：
PUTupdate->/album/updateAlbum(auth)- 旗標：
write - 負載：
--json；必填：id - 範例：
znas photos album update --json '{"id":123,"name":"Trip edited"}' - 陷阱：一般相簿更新使用後端欄位
id，而非album_id。
- 旗標：
DELETEdelete->/album/deleteAlbum(auth)- 旗標：
destructive - 負載：
--json；必填：id - 範例：
znas photos album delete --json '{"id":123}' - 陷阱：僅在讀取相簿後才刪除；除非後端行為變更，否則這不代表刪除原始檔案。
- 旗標：
GETlist->/album/listAlbum(auth)- 負載：
--params；必填：size - 範例：
znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}' - 陷阱：列表為 GET 查詢；使用
index與size，而非 JSON 主體。
- 負載：
POSTadd-photos->/album/addPhotoToAlbum(auth)- 旗標：
write - 負載：
--json；必填：album_id - 範例：
znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}' - 陷阱：後端欄位為大寫 I 的
fileIds；當你有確切 NAS 路徑時也支援paths。
- 旗標：
DELETEremove-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。
- 旗標：
GETget->/album/getAlbum(auth)- 負載：
--params；必填：album_id - 範例：
znas photos album get --params '{"album_id":123}' - 陷阱：相簿詳細資訊為 GET 查詢；透過
--params傳遞album_id。
- 負載：
feature
GETprogress->/feature/process(auth)- 負載：
--params - 範例：
znas photos feature progress --params '{"taskType":1}' - 陷阱：省略
taskType會讀取後端預設進度；當使用者特別詢問臉部或寵物時請傳遞。
- 負載：
DELETEclear->/feature/clear(auth)- 旗標：
destructive - 負載：
--json；必填：taskType - 範例：
znas photos feature clear --json '{"taskType":1}' - 陷阱：這會重設該任務類型的已發現功能相簿資料；先讀取進度/列表。
- 旗標：
GETswitch->/feature/switch(auth)- 負載：
--params；必填：type - 範例：
znas photos feature switch --params '{"type":1}' - 陷阱：開關讀取使用欄位
type；任務相簿篩選使用taskType。
- 負載：
PUTset-switch->/feature/switch(auth)- 旗標：
write - 負載：
--json；必填：type、switch - 範例：
znas photos feature set-switch --json '{"type":1,"switch":1}' - 陷阱：切換後，在回報最終狀態前重新讀取
feature switch。
- 旗標：
PUTset-config->/feature/switch/config(auth)- 旗標：
write - 負載：
--json；必填：type、hideNum - 範例：
znas photos feature set-config --json '{"type":1,"hideNum":5}' - 陷阱：使用確切的
hideNum；此後端不接受蛇形命名（snake_case）。
- 旗標：
GETalbum-list->/feature/album/list(auth)- 負載：
--params；必填：index、size - 範例：
znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}' - 陷阱：已辨識的功能相簿使用駝峰命名（camelCase）欄位，例如
taskType與isHide。
- 負載：
GETalbum-count->/feature/album/count(auth)- 負載：
--params - 範例：
znas photos feature album-count --params '{"taskType":1,"isHide":false}' - 陷阱：當你需要相簿身分識別而非僅計數時，請使用
album-list。
- 負載：
GETrelation->/feature/relation(auth)- 負載：
--params - 範例：
znas photos feature relation --params '{"taskType":1}' - 陷阱：關係是已辨識相簿的選項；在更新關係文字前先讀取。
- 負載：
GETalbum-get->/feature/album(auth)- 負載：
--params；必填：albumId - 範例：
znas photos feature album-get --params '{"albumId":123}' - 陷阱：功能相簿 ID 使用欄位
albumId，不同於一般相簿詳細資訊使用的album_id。
- 負載：
PUTalbum-update->/feature/album(auth)- 旗標：
write - 負載：
--json；必填：albumId - 範例：
znas photos feature album-update --json '{"albumId":123,"name":"Alice"}' - 陷阱：僅從先前的讀取取得數值時才使用
coverId、coverPath或relation。
- 旗標：
POSTalbum-hide->/feature/album/hide(auth)- 旗標：
write - 負載：
--json；必填：albumIds、isHide - 範例：
znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}' - 陷阱：變更
isHide後，驗證隱藏與可見列表。
- 旗標：
POSTalbum-merge->/feature/album/merge(auth)- 旗標：
destructive - 負載：
--json；必填：albumIds、targetId - 範例：
znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}' - 陷阱：先讀取所有來源相簿；
targetId必須是保留下來的相簿。
- 旗標：
GETalbum-photos->/feature/album/photos(auth)- 負載：
--params；必填：albumId、index、size - 範例：
znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}' - 陷阱：對已辨識相簿使用此功能；對一般使用者相簿使用
album get。
- 負載：
PUTalbum-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。
- 旗標：
DELETEalbum-photo-delete->/feature/album/photo(auth)- 旗標：
destructive - 負載：
--json；必填：fIds - 範例：
znas photos feature album-photo-delete --json '{"fIds":[456]}' - 陷阱：先讀取
album-photos並重複使用回傳的功能列 ID。
- 旗標：
GETavatar->/feature/avatar(auth)- 旗標：
binary - 負載：
--params；必填：eaHash - 範例：
znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg - 陷阱：此路由回傳圖片檔案；務必傳遞
-o <file>。
- 旗標：
map
GETforward->/map/forward(auth)- 負載：
--params；必填：coords、model - 範例：
znas photos map forward --params '{"coords":"116.3,39.9","model":1}' - 陷阱：多個座標在
coords內以分號分隔。
- 負載：
GETswitch->/map/switch(auth)- 負載：
--params；必填：type - 範例：
znas photos map switch --params '{"type":2}' - 陷阱：地圖開關使用功能請求欄位
type；當前地圖開關類型通常為 2。
- 負載：
PUTset-switch->/map/switch(auth)- 旗標：
write - 負載：
--json；必填：type、switch - 範例：
znas photos map set-switch --json '{"type":2,"switch":1}' - 陷阱：寫入後在回報最終狀態前重新讀取
map switch。
- 旗標：
GETlast-location->/map/lastLocation(auth)- 負載：
none - 範例：
znas photos map last-location - 陷阱：空結果可能表示沒有已索引的照片包含可用的 GPS 資料。
- 負載：
GETbounds->/map/bounds(auth)- 負載：
--params；必填：minLat、maxLat、minLon、maxLon、zoomLevel - 範例：
znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}' - 陷阱：邊界使用駝峰命名的經緯度欄位；最小值必須小於最大值。
- 負載：
GETgeohash->/map/geohash(auth)- 負載：
--params；必填：geohash、index、size - 範例：
znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}' - 陷阱：多個 geohash 在單一
geohash字串內以分號分隔。
- 負載：
GETcountries->/map/location/country(auth)- 負載：
--params；必填：index、size、viewType、citySize - 範例：
znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}' - 陷阱：使用此路由進行分組位置概覽；選擇國家後使用
cities。
- 負載：
GETcities->/map/location/city(auth)- 負載：
--params；必填：country、offset、size - 範例：
znas photos map cities --params '{"country":"China","offset":0,"size":20}' - 陷阱：城市查詢需要
countries回傳的確切country字串。
- 負載：
GETcity-photos->/map/location/city/photo(auth)- 負載：
--params；必填：addressId、index、size - 範例：
znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}' - 陷阱：使用城市回應中的
addressId，而非顯示的城市名稱。
- 負載：
photo
POSTsearch->/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。
- 負載：
GETtimeline->/photos/getTimeBuckets(auth)- 負載：
--params - 範例：
znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}' - 陷阱：時間軸為 GET 路由；使用
--params傳遞篩選條件，而非--json。
- 負載：
GETstream->/photos/stream(auth)- 旗標：
binary - 負載：
--params；必填：id - 範例：
znas photos photo stream --params '{"id":123456}' -o live.mov - 陷阱：此路由回傳二進位即時照片資料；務必傳遞
-o <file>。
- 旗標：
setting
POSTinit->/setting/init(auth)- 旗標：
write - 負載：
--json；必填：init_path - 範例：`znas photos setting init --json '{"init_path":"/personal/Photos"}'
- 旗標：
… [為翻譯而截斷]