znas photos
当用户询问 NAS 照片相关操作时使用此技能：搜索照片或视频、浏览时间线/地图数据、管理相册、下载相册、查找相似照片，或查看 AI 识别的人物/宠物相册。
此技能的用途
- 读取和更新照片配置路径。
- 搜索已索引的照片/视频并读取时间线分桶。
- 创建、列出、更新、删除和下载用户相册。
- 开始/列出/删除相似照片扫描任务并检查组。
- 读取照片地图集群、位置和地图开关状态。
- 读取和管理 AI 识别的特色相册，例如人物或宠物。
发现规则
- 优先使用逐步 CLI 发现，避免猜测：
znas photos --helpznas photos <feature> --helpznas photos <feature> <command> --help
- 当需要路由清单、负载类型、示例以及二进制/写入标志的 JSON 信息时，使用
znas schema photos。 - 保持后端字段名称与帮助/模式中显示的一致：例如
fileIds、taskId、groupId、albumId、album_id、fIds和eaHash。 - 不要盲目将所有 ID 转换为字符串。保留先前 API 读取返回的字段名称和值形状。
安全规则
- 每次写入或删除前，先读取当前状态。
- 写入/删除成功后，在报告最终成功前重新运行匹配的读取命令。
- 当
znas photos ...提供路由时，不要使用主机本地工具或直接的内部curl进行照片控制平面操作。 - 照片后端不提供通用的试运行模式。对于破坏性操作，先精确检查目标并使变更范围保持狭窄。
- 对于异步的相似照片扫描，任务创建仅将工作加入队列。使用
similar task-list和组读取来获取状态。 - 普通相册路由和 AI 特色相册路由是不同的表面；不要混合使用
album_id和albumId。
二进制输出规则
标记为二进制的路由需要 -o <file> 以确保标准输出保持可解析：
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}' - 陷阱：List 是 GET 查询；使用
index和size，而不是 JSON 主体。
- 负载：
POSTadd-photos->/album/addPhotoToAlbum(auth)- 标志：
write - 负载：
--json；必需：album_id - 示例：
znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}' - 陷阱：后端字段是
fileIds（大写 I）；当你有精确的 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；此后端不接受蛇形命名法。
- 标志：
GETalbum-list->/feature/album/list(auth)- 负载：
--params；必需：index,size - 示例：
znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}' - 陷阱：已识别的特色相册使用驼峰式字段，如
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"}'
- 标志：