znas-photos

znas photos

Use esta skill quando o usuário perguntar sobre NAS Photos: pesquisar fotos ou vídeos, navegar por dados de linha do tempo/mapa, gerenciar álbuns, baixar álbuns, encontrar fotos semelhantes ou inspecionar álbuns de pessoas/animais de estimação reconhecidos por IA.

Para Que Serve Esta Skill

• Ler e atualizar caminhos de configuração do Photos.
• Pesquisar fotos/vídeos indexados e ler buckets de linha do tempo.
• Criar, listar, atualizar, excluir e baixar álbuns de usuário.
• Iniciar/listar/excluir tarefas de escaneamento de fotos semelhantes e inspecionar grupos.
• Ler clusters do mapa de fotos, localizações e estado do interruptor do mapa.
• Ler e gerenciar álbuns de recursos reconhecidos por IA, como pessoas ou animais de estimação.

Regras de Descoberta

1. Prefira descoberta progressiva pela CLI em vez de adivinhar:
   • znas photos --help
   • znas photos <feature> --help
   • znas photos <feature> <command> --help
2. Use znas schema photos quando precisar do inventário de rotas, tipo de payload, exemplos e flags de binário/escrita em JSON.
3. Mantenha os nomes de campos do backend exatamente como mostrados no help/schema: exemplos incluem fileIds, taskId, groupId, albumId, album_id, fIds e eaHash.
4. Não traduza todos os IDs para strings cegamente. Preserve os nomes de campos e formas de valores retornados por leituras de API anteriores.

Regras de Segurança

1. Leia o estado atual antes de cada escrita ou exclusão.
2. Após uma escrita/exclusão bem-sucedida, execute novamente o comando de leitura correspondente antes de relatar o sucesso final.
3. Não use ferramentas nativas do host ou curl interno direto para trabalho de plano de controle do Photos quando znas photos ... tiver a rota.
4. O backend do Photos não expõe um modo dry-run universal. Para ações destrutivas, inspecione o alvo exato primeiro e mantenha a mutação restrita.
5. Para escaneamentos assíncronos de fotos semelhantes, a criação de tarefa apenas enfileira o trabalho. Use similar task-list e leituras de grupo para status.
6. Rotas de álbum normais e rotas de álbum de recurso de IA são superfícies diferentes; não misture album_id com albumId.

Regras de Saída Binária

Rotas marcadas como binárias exigem -o <file> para que a saída padrão permaneça analisável:

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

Se o comando falhar, a CLI valida respostas de erro JSON antes de escrever um arquivo.

Fluxos de Trabalho Comuns

Ler Estado das 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}'

Fluxo de Trabalho de Álbum

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

Fotos Semelhantes

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 e Álbuns de Recurso 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}'

Recursos

album

• POST download -> /downloadFiles (auth)
  • flags: binary
  • canônico: photos album download
  • payload: --json
  • exemplo: znas photos album download --json '{"album_id":123,"download_name_prefix":"album"}' -o album.zip
  • armadilha: Download pode usar album_id ou str_paths; retorna dados zip binários e precisa de -o <file>.
• POST create -> /album/createAlbum (auth)
  • flags: write
  • payload: --json; obrigatório: name
  • exemplo: znas photos album create --json '{"name":"Viagem","description":"Viagem 2026"}'
  • armadilha: Crie o álbum primeiro, depois adicione fotos com album add-photos.
• PUT update -> /album/updateAlbum (auth)
  • flags: write
  • payload: --json; obrigatório: id
  • exemplo: znas photos album update --json '{"id":123,"name":"Viagem editada"}'
  • armadilha: Use o campo do backend id, não album_id, para atualização de álbum normal.
• DELETE delete -> /album/deleteAlbum (auth)
  • flags: destructive
  • payload: --json; obrigatório: id
  • exemplo: znas photos album delete --json '{"id":123}'
  • armadilha: Exclua o álbum somente após lê-lo; isso não significa excluir arquivos originais, a menos que o comportamento do backend mude.
• GET list -> /album/listAlbum (auth)
  • payload: --params; obrigatório: size
  • exemplo: znas photos album list --params '{"index":0,"size":20,"sort_type":2,"sort_order":1}'
  • armadilha: List é uma consulta GET; use index e size, não um corpo JSON.
• POST add-photos -> /album/addPhotoToAlbum (auth)
  • flags: write
  • payload: --json; obrigatório: album_id
  • exemplo: znas photos album add-photos --json '{"album_id":123,"fileIds":["456"]}'
  • armadilha: O campo do backend é fileIds com I maiúsculo; paths também é suportado quando você tem caminhos NAS exatos.
• DELETE remove-photos -> /album/removeAlubmPhotos (auth)
  • flags: destructive
  • canônico: photos album remove-photos
  • payload: --json; obrigatório: album_id
  • exemplo: znas photos album remove-photos --json '{"album_id":123,"fileIds":["456"]}'
  • armadilha: CLI esconde o erro de digitação upstream removeAlubmPhotos; use o comando semântico remove-photos.
• GET get -> /album/getAlbum (auth)
  • payload: --params; obrigatório: album_id
  • exemplo: znas photos album get --params '{"album_id":123}'
  • armadilha: Detalhe do álbum é uma consulta GET; passe album_id via --params.

feature

• GET progress -> /feature/process (auth)
  • payload: --params
  • exemplo: znas photos feature progress --params '{"taskType":1}'
  • armadilha: Omitir taskType lê o progresso padrão do backend; passe-o quando o usuário perguntar especificamente sobre rosto ou animal de estimação.
• DELETE clear -> /feature/clear (auth)
  • flags: destructive
  • payload: --json; obrigatório: taskType
  • exemplo: znas photos feature clear --json '{"taskType":1}'
  • armadilha: Isso redefine os dados do álbum de recurso descoberto para o tipo de tarefa; leia progresso/lista primeiro.
• GET switch -> /feature/switch (auth)
  • payload: --params; obrigatório: type
  • exemplo: znas photos feature switch --params '{"type":1}'
  • armadilha: Leituras de interruptor usam o campo type; filtros de álbum de tarefa usam taskType.
• PUT set-switch -> /feature/switch (auth)
  • flags: write
  • payload: --json; obrigatório: type, switch
  • exemplo: znas photos feature set-switch --json '{"type":1,"switch":1}'
  • armadilha: Após alternar, releia feature switch antes de relatar o estado final.
• PUT set-config -> /feature/switch/config (auth)
  • flags: write
  • payload: --json; obrigatório: type, hideNum
  • exemplo: znas photos feature set-config --json '{"type":1,"hideNum":5}'
  • armadilha: Use hideNum exatamente; snake_case não é aceito por este backend.
• GET album-list -> /feature/album/list (auth)
  • payload: --params; obrigatório: index, size
  • exemplo: znas photos feature album-list --params '{"taskType":1,"index":0,"size":20,"isHide":false}'
  • armadilha: Álbuns de recurso reconhecidos usam campos camelCase como taskType e isHide.
• GET album-count -> /feature/album/count (auth)
  • payload: --params
  • exemplo: znas photos feature album-count --params '{"taskType":1,"isHide":false}'
  • armadilha: Use album-list quando precisar de identidades de álbum, não apenas contagens.
• GET relation -> /feature/relation (auth)
  • payload: --params
  • exemplo: znas photos feature relation --params '{"taskType":1}'
  • armadilha: Relations são opções para álbuns reconhecidos; leia-as antes de atualizar o texto da relação.
• GET album-get -> /feature/album (auth)
  • payload: --params; obrigatório: albumId
  • exemplo: znas photos feature album-get --params '{"albumId":123}'
  • armadilha: IDs de álbum de recurso usam o campo albumId, ao contrário do detalhe de álbum normal que usa album_id.
• PUT album-update -> /feature/album (auth)
  • flags: write
  • payload: --json; obrigatório: albumId
  • exemplo: znas photos feature album-update --json '{"albumId":123,"name":"Alice"}'
  • armadilha: Use coverId, coverPath ou relation somente quando tiver valores de leituras anteriores.
• POST album-hide -> /feature/album/hide (auth)
  • flags: write
  • payload: --json; obrigatório: albumIds, isHide
  • exemplo: znas photos feature album-hide --json '{"albumIds":[123],"isHide":true}'
  • armadilha: Verifique listas ocultas vs. visíveis após alterar isHide.
• POST album-merge -> /feature/album/merge (auth)
  • flags: destructive
  • payload: --json; obrigatório: albumIds, targetId
  • exemplo: znas photos feature album-merge --json '{"albumIds":[123,124],"targetId":123}'
  • armadilha: Leia todos os álbuns de origem primeiro; targetId deve ser o álbum que permanece.
• GET album-photos -> /feature/album/photos (auth)
  • payload: --params; obrigatório: albumId, index, size
  • exemplo: znas photos feature album-photos --params '{"albumId":123,"index":0,"size":50}'
  • armadilha: Use isto para álbuns reconhecidos; use album get para álbuns de usuário normais.
• PUT album-photo-update -> /feature/album/photo (auth)
  • flags: write
  • payload: --json; obrigatório: albumId, fIds
  • exemplo: znas photos feature album-photo-update --json '{"albumId":123,"fIds":[456]}'
  • armadilha: Isso move linhas de foto de recurso reconhecido; fIds são IDs de linha de recurso de album-photos.
• DELETE album-photo-delete -> /feature/album/photo (auth)
  • flags: destructive
  • payload: --json; obrigatório: fIds
  • exemplo: znas photos feature album-photo-delete --json '{"fIds":[456]}'
  • armadilha: Leia album-photos primeiro e reutilize os IDs de linha de recurso retornados.
• GET avatar -> /feature/avatar (auth)
  • flags: binary
  • payload: --params; obrigatório: eaHash
  • exemplo: znas photos feature avatar --params '{"eaHash":"<hash>"}' -o avatar.jpg
  • armadilha: Esta rota retorna um arquivo de imagem; sempre passe -o <file>.

map

• GET forward -> /map/forward (auth)
  • payload: --params; obrigatório: coords, model
  • exemplo: znas photos map forward --params '{"coords":"116.3,39.9","model":1}'
  • armadilha: Múltiplas coordenadas são separadas por ponto e vírgula dentro de coords.
• GET switch -> /map/switch (auth)
  • payload: --params; obrigatório: type
  • exemplo: znas photos map switch --params '{"type":2}'
  • armadilha: O interruptor do mapa usa o campo de solicitação de recurso type; o tipo de interruptor do mapa atual geralmente é 2.
• PUT set-switch -> /map/switch (auth)
  • flags: write
  • payload: --json; obrigatório: type, switch
  • exemplo: znas photos map set-switch --json '{"type":2,"switch":1}'
  • armadilha: Escreva e depois releia map switch antes de relatar o estado final.
• GET last-location -> /map/lastLocation (auth)
  • payload: none
  • exemplo: znas photos map last-location
  • armadilha: Um resultado vazio pode significar que nenhuma foto indexada possui dados GPS utilizáveis.
• GET bounds -> /map/bounds (auth)
  • payload: --params; obrigatório: minLat, maxLat, minLon, maxLon, zoomLevel
  • exemplo: znas photos map bounds --params '{"minLat":30,"maxLat":31,"minLon":120,"maxLon":121,"zoomLevel":10}'
  • armadilha: Bounds usam campos de latitude/longitude em camelCase; valores mínimos devem ser menores que valores máximos.
• GET geohash -> /map/geohash (auth)
  • payload: --params; obrigatório: geohash, index, size
  • exemplo: znas photos map geohash --params '{"geohash":"wtw3;wtw6","index":0,"size":20,"sortOrder":1}'
  • armadilha: Múltiplos geohashes são separados por ponto e vírgula em uma única string geohash.
• GET countries -> /map/location/country (auth)
  • payload: --params; obrigatório: index, size, viewType, citySize
  • exemplo: znas photos map countries --params '{"index":0,"size":20,"viewType":1,"citySize":5}'
  • armadilha: Use esta rota para visão geral de localização agrupada; use cities após escolher um país.
• GET cities -> /map/location/city (auth)
  • payload: --params; obrigatório: country, offset, size
  • exemplo: znas photos map cities --params '{"country":"China","offset":0,"size":20}'
  • armadilha: A consulta de cidade requer a string country exata retornada por countries.
• GET city-photos -> /map/location/city/photo (auth)
  • payload: --params; obrigatório: addressId, index, size
  • exemplo: znas photos map city-photos --params '{"addressId":123,"index":0,"size":50}'
  • armadilha: Use addressId da resposta da cidade, não o nome da cidade de exibição.

photo

• POST search -> /photos/search (auth)
  • payload: --json; obrigatório: index, size
  • exemplo: znas photos photo search --json '{"index":0,"size":20,"keyword_search":"praia"}'
  • armadilha: A pesquisa de fotos é POST JSON; mantenha nomes de campos do backend como keyword_search, album_ids e city_ids.
• GET timeline -> /photos/getTimeBuckets (auth)
  • payload: --params
  • exemplo: znas photos photo timeline --params '{"time_tpl":"YYYY-MM","sort_order":1}'
  • armadilha: Timeline é uma rota GET; passe filtros com --params, não --json.
• GET stream -> /photos/stream (auth)
  • flags: binary
  • payload: --params; obrigatório: id
  • exemplo: znas photos photo stream --params '{"id":123456}' -o live.mov
  • armadilha: Esta rota retorna dados binários de live-photo; sempre passe -o <file>.

setting

• POST init -> /setting/init (auth)
  • flags: write
  • payload: --json; obrigatório: init_path
  • exemplo: znas photos setting init --json '{"init_path":"/personal/Photos"}'