znas-photos

znas photos

Utilisez cette compétence lorsque l'utilisateur pose des questions sur NAS Photos : rechercher des photos ou des vidéos, parcourir les données de la chronologie ou de la carte, gérer les albums, télécharger des albums, trouver des photos similaires ou inspecter les albums de personnes/animaux reconnus par IA.

À quoi sert cette compétence

• Lire et mettre à jour les chemins de configuration Photos.
• Rechercher des photos/vidéos indexées et lire les buckets chronologiques.
• Créer, lister, mettre à jour, supprimer et télécharger des albums utilisateur.
• Démarrer/lister/supprimer des tâches de numérisation de photos similaires et inspecter les groupes.
• Lire les clusters de la carte photo, les emplacements et l'état du commutateur de carte.
• Lire et gérer les albums de fonctionnalités reconnues par IA, tels que les personnes ou les animaux.

Règles de découverte

1. Privilégiez la découverte progressive en ligne de commande plutôt que de deviner :
   • znas photos --help
   • znas photos <feature> --help
   • znas photos <feature> <command> --help
2. Utilisez znas schema photos lorsque vous avez besoin de l'inventaire des routes, du type de charge utile, des exemples et des indicateurs binaires/écriture en JSON.
3. Conservez les noms des champs backend exactement comme indiqués dans l'aide/schéma : exemples : fileIds, taskId, groupId, albumId, album_id, fIds et eaHash.
4. Ne traduisez pas aveuglément tous les ID en chaînes. Préservez les noms des champs et les formes des valeurs renvoyées par les lectures API précédentes.

Règles de sécurité

1. Lisez l'état actuel avant chaque écriture ou suppression.
2. Après la réussite d'une écriture/suppression, réexécutez la commande de lecture correspondante avant de signaler le succès final.
3. N'utilisez pas d'outils natifs de l'hôte ou de curl interne direct pour le plan de contrôle Photos lorsque znas photos ... dispose de la route.
4. Le backend Photos n'expose pas de mode dry-run universel. Pour les actions destructrices, inspectez d'abord la cible exacte et maintenez la mutation limitée.
5. Pour les numérisations asynchrones de photos similaires, la création de tâche ne fait que mettre en file d'attente le travail. Utilisez similar task-list et les lectures de groupes pour l'état.
6. Les routes d'album normales et les routes d'album de fonctionnalités IA sont des surfaces différentes ; ne mélangez pas album_id avec albumId.

Règles de sortie binaire

Les routes marquées comme binaires nécessitent -o <fichier> pour que la sortie standard reste analysable :

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

Si la commande échoue, la CLI valide les réponses d'erreur JSON avant d'écrire un fichier.

Flux de travail courants

Lecture de l'état Photos

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

Flux de travail des albums

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

Photos similaires

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

Albums de carte et de fonctionnalités 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}'

Fonctionnalités

album

• POST download -> /downloadFiles (auth)
  • flags: binary
  • canonical: photos album download
  • payload: --json
  • example: znas photos album download --json '{"album_id":123,"download_name_prefix":"album"}' -o album.zip
  • pitfall: Le téléchargement peut utiliser album_id ou str_paths ; il renvoie des données zip binaires et nécessite -o <fichier>.
• POST create -> /album/createAlbum (auth)
  • flags: write
  • payload: --json ; obligatoire : name
  • example: znas photos album create --json '{"name":"Voyage","description":"Voyage 2026"}'
  • pitfall: Créez d'abord l'album, puis ajoutez des photos avec album add-photos.
• PUT update -> /album/updateAlbum (auth)
  • flags: write
  • payload: --json ; obligatoire : id
  • example: znas photos album update --json '{"id":123,"name":"Voyage modifié"}'
  • pitfall: Utilisez le champ backend id, pas album_id, pour la mise à jour d'un album normal.
• DELETE delete -> /album/deleteAlbum (auth)
  • flags: destructive
  • payload: --json ; obligatoire : id
  • example: znas photos album delete --json '{"id":123}'
  • pitfall: Supprimez l'album uniquement après l'avoir lu ; cela ne signifie pas la suppression des fichiers d'origine, sauf si le comportement du backend change.
• GET list -> /album/listAlbum (auth)
  • payload: --params ; obligatoire : size
  • example: znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}'
  • pitfall: List est une requête GET ; utilisez index et size, pas un corps JSON.
• POST add-photos -> /album/addPhotoToAlbum (auth)
  • flags: write
  • payload: --json ; obligatoire : album_id
  • example: znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
  • pitfall: Le champ backend est fileIds avec un I majuscule ; paths est également pris en charge lorsque vous avez des chemins NAS exacts.
• DELETE remove-photos -> /album/removeAlubmPhotos (auth)
  • flags: destructive
  • canonical: photos album remove-photos
  • payload: --json ; obligatoire : album_id
  • example: znas photos album remove-photos --json '{"album_id":123,"fileIds":["456"]}'
  • pitfall: La CLI masque la faute de frappe en amont removeAlubmPhotos ; utilisez la commande sémantique remove-photos.
• GET get -> /album/getAlbum (auth)
  • payload: --params ; obligatoire : album_id
  • example: znas photos album get --params '{"album_id":123}'
  • pitfall: Le détail de l'album est une requête GET ; passez album_id via --params.

feature

• GET progress -> /feature/process (auth)
  • payload: --params
  • example: znas photos feature progress --params '{"taskType":1}'
  • pitfall: Omettre taskType lit la progression par défaut du backend ; passez-le lorsque l'utilisateur demande spécifiquement des visages ou des animaux.
• DELETE clear -> /feature/clear (auth)
  • flags: destructive
  • payload: --json ; obligatoire : taskType
  • example: znas photos feature clear --json '{"taskType":1}'
  • pitfall: Cela réinitialise les données d'album de fonctionnalité découvertes pour le type de tâche ; lisez d'abord la progression/la liste.
• GET switch -> /feature/switch (auth)
  • payload: --params ; obligatoire : type
  • example: znas photos feature switch --params '{"type":1}'
  • pitfall: Les lectures du commutateur utilisent le champ type ; les filtres d'album de tâche utilisent taskType.
• PUT set-switch -> /feature/switch (auth)
  • flags: write
  • payload: --json ; obligatoire : type, switch
  • example: znas photos feature set-switch --json '{"type":1,"switch":1}'
  • pitfall: Après avoir basculé, relisez feature switch avant de signaler l'état final.
• PUT set-config -> /feature/switch/config (auth)
  • flags: write
  • payload: --json ; obligatoire : type, hideNum
  • example: znas photos feature set-config --json '{"type":1,"hideNum":5}'
  • pitfall: Utilisez hideNum exactement ; snake_case n'est pas accepté par ce backend.
• GET album-list -> /feature/album/list (auth)
  • payload: --params ; obligatoire : index, size
  • example: znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
  • pitfall: Les albums de fonctionnalités reconnues utilisent des champs en camelCase tels que taskType et isHide.
• GET album-count -> /feature/album/count (auth)
  • payload: --params
  • example: znas photos feature album-count --params '{"taskType":1,"isHide":false}'
  • pitfall: Utilisez album-list lorsque vous avez besoin des identités des albums, pas seulement des comptages.
• GET relation -> /feature/relation (auth)
  • payload: --params
  • example: znas photos feature relation --params '{"taskType":1}'
  • pitfall: Les relations sont des options pour les albums reconnus ; lisez-les avant de mettre à jour le texte de la relation.
• GET album-get -> /feature/album (auth)
  • payload: --params ; obligatoire : albumId
  • example: znas photos feature album-get --params '{"albumId":123}'
  • pitfall: Les ID d'album de fonctionnalité utilisent le champ albumId, contrairement au détail d'album normal qui utilise album_id.
• PUT album-update -> /feature/album (auth)
  • flags: write
  • payload: --json ; obligatoire : albumId
  • example: znas photos feature album-update --json '{"albumId":123,"name":"Alice"}'
  • pitfall: Utilisez coverId, coverPath ou relation uniquement lorsque vous avez des valeurs issues de lectures précédentes.
• POST album-hide -> /feature/album/hide (auth)
  • flags: write
  • payload: --json ; obligatoire : albumIds, isHide
  • example: znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}'
  • pitfall: Vérifiez les listes masquées et visibles après avoir modifié isHide.
• POST album-merge -> /feature/album/merge (auth)
  • flags: destructive
  • payload: --json ; obligatoire : albumIds, targetId
  • example: znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}'
  • pitfall: Lisez d'abord tous les albums source ; targetId doit être l'album qui reste.
• GET album-photos -> /feature/album/photos (auth)
  • payload: --params ; obligatoire : albumId, index, size
  • example: znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'
  • pitfall: Utilisez ceci pour les albums reconnus ; utilisez album get pour les albums utilisateur normaux.
• PUT album-photo-update -> /feature/album/photo (auth)
  • flags: write
  • payload: --json ; obligatoire : albumId, fIds
  • example: znas photos feature album-photo-update --json '{"albumId":123,"fIds":[456]}'
  • pitfall: Cela déplace les lignes de photo de fonctionnalité reconnue ; fIds sont les ID de ligne de fonctionnalité provenant de album-photos.
• DELETE album-photo-delete -> /feature/album/photo (auth)
  • flags: destructive
  • payload: --json ; obligatoire : fIds
  • example: znas photos feature album-photo-delete --json '{"fIds":[456]}'
  • pitfall: Lisez d'abord album-photos et réutilisez les ID de ligne de fonctionnalité retournés.
• GET avatar -> /feature/avatar (auth)
  • flags: binary
  • payload: --params ; obligatoire : eaHash
  • example: znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg
  • pitfall: Cette route renvoie un fichier image ; passez toujours -o <fichier>.

map

• GET forward -> /map/forward (auth)
  • payload: --params ; obligatoire : coords, model
  • example: znas photos map forward --params '{"coords":"116.3,39.9","model":1}'
  • pitfall: Plusieurs coordonnées sont séparées par des points-virgules à l'intérieur de coords.
• GET switch -> /map/switch (auth)
  • payload: --params ; obligatoire : type
  • example: znas photos map switch --params '{"type":2}'
  • pitfall: Le commutateur de carte utilise le champ de requête de fonctionnalité type ; le type de commutateur de carte actuel est généralement 2.
• PUT set-switch -> /map/switch (auth)
  • flags: write
  • payload: --json ; obligatoire : type, switch
  • example: znas photos map set-switch --json '{"type":2,"switch":1}'
  • pitfall: Écrivez, puis relisez map switch avant de signaler l'état final.
• GET last-location -> /map/lastLocation (auth)
  • payload: none
  • example: znas photos map last-location
  • pitfall: Un résultat vide peut signifier qu'aucune photo indexée ne contient de données GPS utilisables.
• GET bounds -> /map/bounds (auth)
  • payload: --params ; obligatoire : minLat, maxLat, minLon, maxLon, zoomLevel
  • example: znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
  • pitfall: Les limites utilisent des champs de latitude/longitude en camelCase ; les valeurs min doivent être inférieures aux valeurs max.
• GET geohash -> /map/geohash (auth)
  • payload: --params ; obligatoire : geohash, index, size
  • example: znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}'
  • pitfall: Plusieurs geohashes sont séparés par des points-virgules dans une seule chaîne geohash.
• GET countries -> /map/location/country (auth)
  • payload: --params ; obligatoire : index, size, viewType, citySize
  • example: znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}'
  • pitfall: Utilisez cette route pour une vue d'ensemble groupée des emplacements ; utilisez cities après avoir choisi un pays.
• GET cities -> /map/location/city (auth)
  • payload: --params ; obligatoire : country, offset, size
  • example: znas photos map cities --params '{"country":"Chine","offset":0,"size":20}'
  • pitfall: La recherche de ville nécessite la chaîne country exacte renvoyée par countries.
• GET city-photos -> /map/location/city/photo (auth)
  • payload: --params ; obligatoire : addressId, index, size
  • example: znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}'
  • pitfall: Utilisez addressId de la réponse de la ville, pas le nom de la ville affiché.

photo

• POST search -> /photos/search (auth)
  • payload: --json ; obligatoire : index, size
  • example: znas photos photo search --json '{"index":0,"size":20,"keyword_search":"plage"}'
  • pitfall: La recherche de photos est un POST JSON ; conservez les noms de champs backend tels que keyword_search, album_ids et city_ids.
• GET timeline -> /photos/getTimeBuckets (auth)
  • payload: --params
  • example: znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'
  • pitfall: La chronologie est une route GET ; passez les filtres avec --params, pas --json.
• GET stream -> /photos/stream (auth)
  • flags: binary
  • payload: --params ; obligatoire : id
  • example: znas photos photo stream --params '{"id":123456}' -o live.mov
  • pitfall: Cette route renvoie des données binaires de live-photo ; passez toujours -o <fichier>.

setting

• POST init -> /setting/init (auth)
  • flags: write
  • payload: --json ; obligatoire : init_path
  • example: `znas photos setting init --json '{"init_path":"/personal/Photos"}'

…

[Le contenu a été tronqué pour la traduction]