znas-photos

znas photos

Usa esta habilidad cuando el usuario pregunte sobre Fotos NAS: buscar fotos o videos, navegar datos de línea de tiempo/mapa, gestionar álbumes, descargar álbumes, encontrar fotos similares o inspeccionar álbumes de personas/mascotas reconocidos por IA.

Para qué sirve esta habilidad

• Leer y actualizar rutas de configuración de Fotos.
• Buscar fotos/videos indexados y leer buckets de línea de tiempo.
• Crear, listar, actualizar, eliminar y descargar álbumes de usuario.
• Iniciar/listar/eliminar tareas de escaneo de fotos similares e inspeccionar grupos.
• Leer clústeres de mapa de fotos, ubicaciones y estado del interruptor del mapa.
• Leer y gestionar álbumes de características reconocidos por IA, como personas o mascotas.

Reglas de descubrimiento

1. Prefiere el descubrimiento progresivo por CLI en lugar de adivinar:
   • znas photos --help
   • znas photos <característica> --help
   • znas photos <característica> <comando> --help
2. Usa znas schema photos cuando necesites el inventario de rutas, tipo de payload, ejemplos y banderas binarias/de escritura en JSON.
3. Mantén los nombres de campo del backend exactamente como se muestran en la ayuda/esquema: ejemplos incluyen fileIds, taskId, groupId, albumId, album_id, fIds y eaHash.
4. No traduzcas todos los IDs a cadenas a ciegas. Preserva los nombres de campo y las formas de los valores devueltos por lecturas previas de la API.

Reglas de seguridad

1. Lee el estado actual antes de cada escritura o eliminación.
2. Después de que una escritura/eliminación tenga éxito, vuelve a ejecutar el comando de lectura correspondiente antes de informar éxito final.
3. No uses herramientas nativas del host ni curl interno directo para el trabajo del plano de control de Fotos cuando znas photos ... tenga la ruta.
4. El backend de Fotos no expone un modo de prueba en seco universal. Para acciones destructivas, inspecciona el objetivo exacto primero y mantén la mutación limitada.
5. Para escaneos asíncronos de fotos similares, la creación de la tarea solo pone en cola el trabajo. Usa similar task-list y lecturas de grupo para el estado.
6. Las rutas de álbumes normales y las rutas de álbumes de características de IA son superficies diferentes; no mezcles album_id con albumId.

Reglas de salida binaria

Las rutas marcadas como binarias requieren -o <archivo> para que la salida estándar se pueda analizar:

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

Si el comando falla, la CLI valida las respuestas de error JSON antes de escribir un archivo.

Flujos de trabajo comunes

Leer estado de Fotos

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}'

Flujo de trabajo de álbumes

znas photos album list --params '{"index":0,"size":20}'
znas photos album create --json '{"name":"Viaje"}'
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":"Viaje"}' -o viaje.zip

Fotos similares

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}'

Mapa y álbumes de características de IA

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}'

Características

album

• POST download -> /downloadFiles (auth)
  • banderas: binary
  • canónica: photos album download
  • payload: --json
  • ejemplo: znas photos album download --json '{"album_id":123,"download_name_prefix":"album"}' -o album.zip
  • trampa: La descarga puede usar album_id o str_paths; devuelve datos zip binarios y necesita -o <archivo>.
• POST create -> /album/createAlbum (auth)
  • banderas: write
  • payload: --json; requerido: name
  • ejemplo: znas photos album create --json '{"name":"Viaje","description":"Viaje 2026"}'
  • trampa: Crea el álbum primero, luego añade fotos con album add-photos.
• PUT update -> /album/updateAlbum (auth)
  • banderas: write
  • payload: --json; requerido: id
  • ejemplo: znas photos album update --json '{"id":123,"name":"Viaje editado"}'
  • trampa: Usa el campo del backend id, no album_id, para la actualización de álbumes normales.
• DELETE delete -> /album/deleteAlbum (auth)
  • banderas: destructive
  • payload: --json; requerido: id
  • ejemplo: znas photos album delete --json '{"id":123}'
  • trampa: Elimina el álbum solo después de leerlo; esto no significa eliminar los archivos originales a menos que el comportamiento del backend cambie.
• GET list -> /album/listAlbum (auth)
  • payload: --params; requerido: size
  • ejemplo: znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}'
  • trampa: List es una consulta GET; usa index y size, no un cuerpo JSON.
• POST add-photos -> /album/addPhotoToAlbum (auth)
  • banderas: write
  • payload: --json; requerido: album_id
  • ejemplo: znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
  • trampa: El campo del backend es fileIds con una I mayúscula; paths también es compatible cuando tienes rutas NAS exactas.
• DELETE remove-photos -> /album/removeAlubmPhotos (auth)
  • banderas: destructive
  • canónica: photos album remove-photos
  • payload: --json; requerido: album_id
  • ejemplo: znas photos album remove-photos --json '{"album_id":123,"fileIds":["456"]}'
  • trampa: La CLI oculta el error tipográfico ascendente removeAlubmPhotos; usa el comando semántico remove-photos.
• GET get -> /album/getAlbum (auth)
  • payload: --params; requerido: album_id
  • ejemplo: znas photos album get --params '{"album_id":123}'
  • trampa: El detalle del álbum es una consulta GET; pasa album_id a través de --params.

feature

• GET progress -> /feature/process (auth)
  • payload: --params
  • ejemplo: znas photos feature progress --params '{"taskType":1}'
  • trampa: Omitir taskType lee el progreso predeterminado del backend; pásalo cuando el usuario pregunte específicamente por rostros o mascotas.
• DELETE clear -> /feature/clear (auth)
  • banderas: destructive
  • payload: --json; requerido: taskType
  • ejemplo: znas photos feature clear --json '{"taskType":1}'
  • trampa: Esto restablece los datos del álbum de características descubiertas para el tipo de tarea; lee el progreso/lista primero.
• GET switch -> /feature/switch (auth)
  • payload: --params; requerido: type
  • ejemplo: znas photos feature switch --params '{"type":1}'
  • trampa: Las lecturas de switch usan el campo type; los filtros de álbumes de tareas usan taskType.
• PUT set-switch -> /feature/switch (auth)
  • banderas: write
  • payload: --json; requerido: type, switch
  • ejemplo: znas photos feature set-switch --json '{"type":1,"switch":1}'
  • trampa: Después de cambiar, vuelve a leer feature switch antes de informar el estado final.
• PUT set-config -> /feature/switch/config (auth)
  • banderas: write
  • payload: --json; requerido: type, hideNum
  • ejemplo: znas photos feature set-config --json '{"type":1,"hideNum":5}'
  • trampa: Usa hideNum exactamente; snake_case no es aceptado por este backend.
• GET album-list -> /feature/album/list (auth)
  • payload: --params; requerido: index, size
  • ejemplo: znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
  • trampa: Los álbumes de características reconocidas usan campos camelCase como taskType e isHide.
• GET album-count -> /feature/album/count (auth)
  • payload: --params
  • ejemplo: znas photos feature album-count --params '{"taskType":1,"isHide":false}'
  • trampa: Usa album-list cuando necesites identidades de álbumes, no solo recuentos.
• GET relation -> /feature/relation (auth)
  • payload: --params
  • ejemplo: znas photos feature relation --params '{"taskType":1}'
  • trampa: Las relaciones son opciones para álbumes reconocidos; léelas antes de actualizar el texto de la relación.
• GET album-get -> /feature/album (auth)
  • payload: --params; requerido: albumId
  • ejemplo: znas photos feature album-get --params '{"albumId":123}'
  • trampa: Los IDs de álbumes de características usan el campo albumId, a diferencia del detalle de álbumes normales que usa album_id.
• PUT album-update -> /feature/album (auth)
  • banderas: write
  • payload: --json; requerido: albumId
  • ejemplo: znas photos feature album-update --json '{"albumId":123,"name":"Alicia"}'
  • trampa: Usa coverId, coverPath o relation solo cuando tengas valores de lecturas previas.
• POST album-hide -> /feature/album/hide (auth)
  • banderas: write
  • payload: --json; requerido: albumIds, isHide
  • ejemplo: znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}'
  • trampa: Verifica las listas ocultas vs. visibles después de cambiar isHide.
• POST album-merge -> /feature/album/merge (auth)
  • banderas: destructive
  • payload: --json; requerido: albumIds, targetId
  • ejemplo: znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}'
  • trampa: Lee todos los álbumes fuente primero; targetId debe ser el álbum que permanece.
• GET album-photos -> /feature/album/photos (auth)
  • payload: --params; requerido: albumId, index, size
  • ejemplo: znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'
  • trampa: Usa esto para álbumes reconocidos; usa album get para álbumes de usuario normales.
• PUT album-photo-update -> /feature/album/photo (auth)
  • banderas: write
  • payload: --json; requerido: albumId, fIds
  • ejemplo: znas photos feature album-photo-update --json '{"albumId":123,"fIds":[456]}'
  • trampa: Esto mueve filas de fotos de características reconocidas; fIds son IDs de filas de características de album-photos.
• DELETE album-photo-delete -> /feature/album/photo (auth)
  • banderas: destructive
  • payload: --json; requerido: fIds
  • ejemplo: znas photos feature album-photo-delete --json '{"fIds":[456]}'
  • trampa: Lee album-photos primero y reutiliza los IDs de filas de características devueltos.
• GET avatar -> /feature/avatar (auth)
  • banderas: binary
  • payload: --params; requerido: eaHash
  • ejemplo: znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg
  • trampa: Esta ruta devuelve un archivo de imagen; siempre pasa -o <archivo>.

map

• GET forward -> /map/forward (auth)
  • payload: --params; requerido: coords, model
  • ejemplo: znas photos map forward --params '{"coords":"116.3,39.9","model":1}'
  • trampa: Múltiples coordenadas están separadas por punto y coma dentro de coords.
• GET switch -> /map/switch (auth)
  • payload: --params; requerido: type
  • ejemplo: znas photos map switch --params '{"type":2}'
  • trampa: El switch del mapa usa el campo de solicitud de características type; el tipo de switch de mapa actual suele ser 2.
• PUT set-switch -> /map/switch (auth)
  • banderas: write
  • payload: --json; requerido: type, switch
  • ejemplo: znas photos map set-switch --json '{"type":2,"switch":1}'
  • trampa: Escribe y luego vuelve a leer map switch antes de informar el estado final.
• GET last-location -> /map/lastLocation (auth)
  • payload: none
  • ejemplo: znas photos map last-location
  • trampa: Un resultado vacío puede significar que ninguna foto indexada tiene datos GPS utilizables.
• GET bounds -> /map/bounds (auth)
  • payload: --params; requerido: minLat, maxLat, minLon, maxLon, zoomLevel
  • ejemplo: znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
  • trampa: Los límites usan campos de latitud/longitud en camelCase; los valores mínimos deben ser menores que los valores máximos.
• GET geohash -> /map/geohash (auth)
  • payload: --params; requerido: geohash, index, size
  • ejemplo: znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}'
  • trampa: Múltiples geohashes están separados por punto y coma en una sola cadena geohash.
• GET countries -> /map/location/country (auth)
  • payload: --params; requerido: index, size, viewType, citySize
  • ejemplo: znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}'
  • trampa: Usa esta ruta para una visión general de ubicaciones agrupadas; usa cities después de elegir un país.
• GET cities -> /map/location/city (auth)
  • payload: --params; requerido: country, offset, size
  • ejemplo: znas photos map cities --params '{"country":"China","offset":0,"size":20}'
  • trampa: La búsqueda de ciudad requiere la cadena country exacta devuelta por countries.
• GET city-photos -> /map/location/city/photo (auth)
  • payload: --params; requerido: addressId, index, size
  • ejemplo: znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}'
  • trampa: Usa addressId de la respuesta de la ciudad, no el nombre de la ciudad mostrada.

photo

• POST search -> /photos/search (auth)
  • payload: --json; requerido: index, size
  • ejemplo: znas photos photo search --json '{"index":0,"size":20,"keyword_search":"playa"}'
  • trampa: La búsqueda de fotos es JSON POST; mantén los nombres de campo del backend como keyword_search, album_ids y city_ids.
• GET timeline -> /photos/getTimeBuckets (auth)
  • payload: --params
  • ejemplo: znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'
  • trampa: Timeline es una ruta GET; pasa filtros con --params, no con --json.
• GET stream -> /photos/stream (auth)
  • banderas: binary
  • payload: --params; requerido: id
  • ejemplo: znas photos photo stream --params '{"id":123456}' -o live.mov
  • trampa: Esta ruta devuelve datos binarios de foto en vivo; siempre pasa -o <archivo>.

setting

• POST init -> /setting/init (auth)
  • banderas: write
  • payload: --json; requerido: init_path
  • ejemplo: znas photos setting init --json '{"init_path":"/personal/Photos"}'

… [truncado para traducción]