znas-photos

znas photos

Verwende diesen Skill, wenn der Benutzer nach NAS-Fotos fragt: Fotos oder Videos suchen, Zeitachsen- oder Kartendaten durchsuchen, Alben verwalten, Alben herunterladen, ähnliche Fotos finden oder KI-erkannte Personen-/Haustieralben inspizieren.

Wofür dieser Skill gedacht ist

• Fotokonfigurationspfade lesen und aktualisieren.
• Indizierte Fotos/Videos durchsuchen und Zeitachsenabschnitte lesen.
• Benutzeralben erstellen, auflisten, aktualisieren, löschen und herunterladen.
• Aufgaben zur Suche ähnlicher Fotos starten/auflisten/löschen und Gruppen inspizieren.
• Fotokartencluster, Standorte und den Karten-Schalter-Zustand lesen.
• KI-erkannte Feature-Alben wie Personen oder Haustiere lesen und verwalten.

Entdeckungsregeln

1. Bevorzuge progressive CLI-Entdeckung statt Raten:
   • znas photos --help
   • znas photos <feature> --help
   • znas photos <feature> <command> --help
2. Verwende znas schema photos, wenn du die Routenübersicht, Payload-Typen, Beispiele und Binär-/Schreib-Flags als JSON benötigst.
3. Behalte die Backend-Feldnamen exakt so bei, wie sie in Hilfe/Schema angezeigt werden: Beispiele sind fileIds, taskId, groupId, albumId, album_id, fIds und eaHash.
4. Übersetze nicht blind alle IDs in Zeichenketten. Bewahre die Feldnamen und Werteformen, die von vorherigen API-Lesevorgängen zurückgegeben wurden.

Sicherheitsregeln

1. Lies den aktuellen Zustand vor jedem Schreib- oder Löschvorgang.
2. Führe nach einem erfolgreichen Schreib-/Löschvorgang den passenden Lesebefehl erneut aus, bevor der endgültige Erfolg gemeldet wird.
3. Verwende keine host-eigenen Tools oder direkten internen curl für Photos-Kontrollebenen-Arbeiten, wenn znas photos ... die Route bereitstellt.
4. Das Photos-Backend bietet keinen universellen Trockenlaufmodus. Für zerstörerische Aktionen überprüfe zunächst das genaue Ziel und halte die Änderung eng.
5. Für asynchrone Scans ähnlicher Fotos wird durch die Aufgabenerstellung nur die Arbeit in die Warteschlange gestellt. Verwende similar task-list und Gruppen-Lesevorgänge für den Status.
6. Normale Alben-Routen und KI-Feature-Alben-Routen sind unterschiedliche Oberflächen; mische album_id nicht mit albumId.

Binärausgaberegeln

Als binär markierte Routen erfordern -o <datei>, damit stdout analysierbar bleibt:

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

Wenn der Befehl fehlschlägt, validiert die CLI JSON-Fehlerantworten, bevor eine Datei geschrieben wird.

Häufige Arbeitsabläufe

Fotos-Status lesen

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

Album-Workflow

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

Ähnliche Fotos

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

Karte und KI-Feature-Alben

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

Funktionen

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: Der Download kann album_id oder str_paths verwenden; er gibt binäre ZIP-Daten zurück und benötigt -o <datei>.
• POST create -> /album/createAlbum (auth)
  • flags: write
  • payload: --json; erforderlich: name
  • example: znas photos album create --json '{"name":"Reise","description":"Reise 2026"}'
  • pitfall: Erstelle zuerst das Album, dann füge Fotos mit album add-photos hinzu.
• PUT update -> /album/updateAlbum (auth)
  • flags: write
  • payload: --json; erforderlich: id
  • example: znas photos album update --json '{"id":123,"name":"Reise bearbeitet"}'
  • pitfall: Verwende das Backend-Feld id, nicht album_id, für normale Album-Aktualisierungen.
• DELETE delete -> /album/deleteAlbum (auth)
  • flags: destructive
  • payload: --json; erforderlich: id
  • example: znas photos album delete --json '{"id":123}'
  • pitfall: Lösche das Album erst, nachdem du es gelesen hast; dies bedeutet nicht, die Originaldateien zu löschen, es sei denn, das Backend-Verhalten ändert sich.
• GET list -> /album/listAlbum (auth)
  • payload: --params; erforderlich: size
  • example: znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}'
  • pitfall: Auflisten ist eine GET-Abfrage; verwende index und size, keinen JSON-Body.
• POST add-photos -> /album/addPhotoToAlbum (auth)
  • flags: write
  • payload: --json; erforderlich: album_id
  • example: znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
  • pitfall: Das Backend-Feld ist fileIds mit einem großen I; paths wird ebenfalls unterstützt, wenn du genaue NAS-Pfade hast.
• DELETE remove-photos -> /album/removeAlubmPhotos (auth)
  • flags: destructive
  • canonical: photos album remove-photos
  • payload: --json; erforderlich: album_id
  • example: znas photos album remove-photos --json '{"album_id":123,"fileIds":["456"]}'
  • pitfall: Die CLI verbirgt den upstream-Tippfehler removeAlubmPhotos; verwende den semantischen Befehl remove-photos.
• GET get -> /album/getAlbum (auth)
  • payload: --params; erforderlich: album_id
  • example: znas photos album get --params '{"album_id":123}'
  • pitfall: Albendetail ist eine GET-Abfrage; übergib album_id über --params.

feature

• GET progress -> /feature/process (auth)
  • payload: --params
  • example: znas photos feature progress --params '{"taskType":1}'
  • pitfall: Das Weglassen von taskType liest den Standardfortschritt des Backends; übergib es, wenn der Benutzer speziell nach Gesichtern oder Haustieren fragt.
• DELETE clear -> /feature/clear (auth)
  • flags: destructive
  • payload: --json; erforderlich: taskType
  • example: znas photos feature clear --json '{"taskType":1}'
  • pitfall: Dies setzt die erkannten Feature-Albumdaten für den Aufgabentyp zurück; lies zuerst Fortschritt/Liste.
• GET switch -> /feature/switch (auth)
  • payload: --params; erforderlich: type
  • example: znas photos feature switch --params '{"type":1}'
  • pitfall: Switch-Lesevorgänge verwenden das Feld type; Aufgaben-Album-Filter verwenden taskType.
• PUT set-switch -> /feature/switch (auth)
  • flags: write
  • payload: --json; erforderlich: type, switch
  • example: znas photos feature set-switch --json '{"type":1,"switch":1}'
  • pitfall: Lies nach dem Umschalten erneut feature switch, bevor der endgültige Zustand gemeldet wird.
• PUT set-config -> /feature/switch/config (auth)
  • flags: write
  • payload: --json; erforderlich: type, hideNum
  • example: znas photos feature set-config --json '{"type":1,"hideNum":5}'
  • pitfall: Verwende genau hideNum; snake_case wird von diesem Backend nicht akzeptiert.
• GET album-list -> /feature/album/list (auth)
  • payload: --params; erforderlich: index, size
  • example: znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
  • pitfall: Erkannte Feature-Alben verwenden camelCase-Felder wie taskType und isHide.
• GET album-count -> /feature/album/count (auth)
  • payload: --params
  • example: znas photos feature album-count --params '{"taskType":1,"isHide":false}'
  • pitfall: Verwende album-list, wenn du Album-Identitäten benötigst, nicht nur Anzahlen.
• GET relation -> /feature/relation (auth)
  • payload: --params
  • example: znas photos feature relation --params '{"taskType":1}'
  • pitfall: Beziehungen sind Optionen für erkannte Alben; lies sie, bevor du den Beziehungstext aktualisierst.
• GET album-get -> /feature/album (auth)
  • payload: --params; erforderlich: albumId
  • example: znas photos feature album-get --params '{"albumId":123}'
  • pitfall: Feature-Album-IDs verwenden das Feld albumId, anders als normale Album-Details, die album_id verwenden.
• PUT album-update -> /feature/album (auth)
  • flags: write
  • payload: --json; erforderlich: albumId
  • example: znas photos feature album-update --json '{"albumId":123,"name":"Alice"}'
  • pitfall: Verwende coverId, coverPath oder relation nur, wenn du Werte aus vorherigen Lesevorgängen hast.
• POST album-hide -> /feature/album/hide (auth)
  • flags: write
  • payload: --json; erforderlich: albumIds, isHide
  • example: znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}'
  • pitfall: Überprüfe versteckte vs. sichtbare Listen nach dem Ändern von isHide.
• POST album-merge -> /feature/album/merge (auth)
  • flags: destructive
  • payload: --json; erforderlich: albumIds, targetId
  • example: znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}'
  • pitfall: Lese zuerst alle Quellalben; targetId muss das Album sein, das erhalten bleibt.
• GET album-photos -> /feature/album/photos (auth)
  • payload: --params; erforderlich: albumId, index, size
  • example: znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'
  • pitfall: Verwende dies für erkannte Alben; verwende album get für normale Benutzeralben.
• PUT album-photo-update -> /feature/album/photo (auth)
  • flags: write
  • payload: --json; erforderlich: albumId, fIds
  • example: znas photos feature album-photo-update --json '{"albumId":123,"fIds":[456]}'
  • pitfall: Dies verschiebt erkannte Feature-Fotoreihen; fIds sind Feature-Reihen-IDs aus album-photos.
• DELETE album-photo-delete -> /feature/album/photo (auth)
  • flags: destructive
  • payload: --json; erforderlich: fIds
  • example: znas photos feature album-photo-delete --json '{"fIds":[456]}'
  • pitfall: Lese zuerst album-photos und verwende die zurückgegebenen Feature-Reihen-IDs.
• GET avatar -> /feature/avatar (auth)
  • flags: binary
  • payload: --params; erforderlich: eaHash
  • example: znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg
  • pitfall: Diese Route gibt eine Bilddatei zurück; übergib immer -o <datei>.

map

• GET forward -> /map/forward (auth)
  • payload: --params; erforderlich: coords, model
  • example: znas photos map forward --params '{"coords":"116.3,39.9","model":1}'
  • pitfall: Mehrere Koordinaten werden innerhalb von coords durch Semikolon getrennt.
• GET switch -> /map/switch (auth)
  • payload: --params; erforderlich: type
  • example: znas photos map switch --params '{"type":2}'
  • pitfall: Karten-Schalter verwendet das Feature-Anforderungsfeld type; der aktuelle Karten-Schalter-Typ ist normalerweise 2.
• PUT set-switch -> /map/switch (auth)
  • flags: write
  • payload: --json; erforderlich: type, switch
  • example: znas photos map set-switch --json '{"type":2,"switch":1}'
  • pitfall: Schreibe, dann lies erneut map switch, bevor der endgültige Zustand gemeldet wird.
• GET last-location -> /map/lastLocation (auth)
  • payload: none
  • example: znas photos map last-location
  • pitfall: Ein leeres Ergebnis kann bedeuten, dass kein indiziertes Foto verwertbare GPS-Daten hat.
• GET bounds -> /map/bounds (auth)
  • payload: --params; erforderlich: minLat, maxLat, minLon, maxLon, zoomLevel
  • example: znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
  • pitfall: Grenzen verwenden camelCase-Breiten-/Längengrad-Felder; Mindestwerte müssen kleiner als Höchstwerte sein.
• GET geohash -> /map/geohash (auth)
  • payload: --params; erforderlich: geohash, index, size
  • example: znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}'
  • pitfall: Mehrere Geohashes werden in einem einzigen geohash-String durch Semikolon getrennt.
• GET countries -> /map/location/country (auth)
  • payload: --params; erforderlich: index, size, viewType, citySize
  • example: znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}'
  • pitfall: Verwende diese Route für eine gruppierte Standortübersicht; verwende cities nach der Auswahl eines Landes.
• GET cities -> /map/location/city (auth)
  • payload: --params; erforderlich: country, offset, size
  • example: znas photos map cities --params '{"country":"China","offset":0,"size":20}'
  • pitfall: Die Stadtsuche erfordert die genaue country-Zeichenkette, die von countries zurückgegeben wird.
• GET city-photos -> /map/location/city/photo (auth)
  • payload: --params; erforderlich: addressId, index, size
  • example: znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}'
  • pitfall: Verwende addressId aus der Stadtantwort, nicht den Anzeigenamen der Stadt.

photo

• POST search -> /photos/search (auth)
  • payload: --json; erforderlich: index, size
  • example: znas photos photo search --json '{"index":0,"size":20,"keyword_search":"strand"}'
  • pitfall: Fotosuche ist POST JSON; behalte Backend-Feldnamen wie keyword_search, album_ids und city_ids bei.
• GET timeline -> /photos/getTimeBuckets (auth)
  • payload: --params
  • example: znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'
  • pitfall: Zeitleiste ist eine GET-Route; übergib Filter mit --params, nicht --json.
• GET stream -> /photos/stream (auth)
  • flags: binary
  • payload: --params; erforderlich: id
  • example: znas photos photo stream --params '{"id":123456}' -o live.mov
  • pitfall: Diese Route gibt binäre Live-Foto-Daten zurück; übergib immer -o <datei>.

setting

• POST init -> /setting/init (auth)
  • flags: write
  • payload: --json; erforderlich: init_path
  • example: `znas photos setting init --json '{"init_path":"/personal/Photos"}'
  • pitfall: Dies richtet den anfänglichen Scankatalog ein; lies die Konfiguration, bevor du einen bereits indizierten Pfad erneut initialisierst.
• GET config -> /setting/config (auth)
  • payload: none
  • example: znas photos setting config
  • pitfall: Ruft einfach den aktuellen Einstellungs-JSON ab, einschließlich Status des initialisierten Pfads.
• POST update -> /setting/update (auth)
  • flags: write
  • payload: --json; erforderlich: path
  • example: znas photos setting update --json '{"path":"/new/Path"}'
  • pitfall: Aktualisiert den Startpfad; dies stoppt den laufenden Dienst nicht neu, bis die Änderung festgeschrieben ist.