Guia de Skill do CLI
Visão geral do NadouPro CLI
Este guia é para usuários e Agents que usam o NadouPro CLI. Cobre instalação, login, descoberta de modelos, geração de conteúdo, entrega de tarefas, gestão de espaços, processamento local de mídia e operações do Canvas. As capacidades do CLI variam por versão, conta e cenário. Trate nadou capability list --json, os resultados dos comandos e as saídas reais como a fonte da verdade.
Recomendação
Depois da instalação ou da atualização, execute primeiro nadou version --json e nadou capability list --json para confirmar a versão atual e as capacidades disponíveis.
Observação
Para operações de escrita, geração, exclusão ou sobrescrita, siga “envie uma vez, não tente de novo automaticamente e consulte a tarefa original quando o resultado for incerto.” Não compartilhe nem registre cookies, tokens, cabeçalhos Authorization ou outras credenciais de login.
1. Começo rápido
1.1 Instalar
Requer Node.js 16 ou posterior. Instalar a partir do registro público npm é recomendado:
Instrução de instalação em uma linha: Instale o NadouPro CLI: npm install -g @iqiyi-intl-nadoupro/nadou-cli. Depois da instalação, execute nadou version --json para verificar.
npm exec --yes --registry=https://registry.npmjs.org/ --package=@iqiyi-intl-nadoupro/nadou-cli@latest -- nadou-install
nadou version --json
nadou skill install --json
nadou skill read --jsonVocê também pode instalar globalmente:
npm install -g @iqiyi-intl-nadoupro/nadou-cli
nadou version --jsonSuporte atual: Windows x64, Linux x64/arm64 e macOS x64/arm64. O npm seleciona automaticamente a dependência de plataforma correspondente. Se dependências opcionais foram desabilitadas durante a instalação, reinstale com uma instalação normal.
1.2 Checar atualizações e atualizar
nadou version --check --json
nadou update --json --no-interactive
nadou version --jsonDepois de atualizar, execute nadou skill install --json de novo para o Skill local permanecer alinhado com a versão do CLI.
1.3 Configurar e entrar
O login abre a página de login internacional no navegador do sistema. Clique em “Continue to international sign in” e conclua o login da conta do site internacional usando o método mostrado na página. Profiles armazenam configurações não sensíveis, como espaço e timeouts. Sessões de login são armazenadas no armazenamento de credenciais do sistema local. A configuração local internacional e as sessões de login são armazenadas em separado; depois de instalar a edição internacional, cheque o status de login internacional.
nadou auth login --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --jsonSubstitua <profile> pelo nome do Profile realmente usado nesta máquina. Se você usa o Profile padrão, pode omitir este parâmetro conforme o CLI indicar. Não copie, cole ou registre manualmente cookies, tokens ou valores Authorization.
Login no modo de servidor
Servidores, contêineres ou ambientes sem interface gráfica podem não conseguir abrir um navegador local ou acessar o armazenamento de credenciais do sistema operacional. Nesses ambientes, use o fluxo separado de login no modo de servidor:
nadou auth login --server --profile <profile>
nadou auth status --profile <profile> --json
nadou auth whoami --profile <profile> --jsonO CLI exibe uma URL de login e um código de verificação no terminal e aguarda 10 minutos por padrão. O usuário pode inserir o código em um navegador de qualquer dispositivo, fazer login e confirmar a conta. A página de login também permite trocar de conta.
Esse modo salva as credenciais em um arquivo privado do CLI, permitindo que diferentes processos do CLI compartilhem o estado de login. Se o diretório de estado não for persistido, será necessário fazer login novamente após a destruição do contêiner. Esse comportamento se aplica apenas ao login com --server explícito; os outros métodos de login continuam usando o armazenamento de credenciais do sistema.
1.4 Checagens antes do uso pelo Agent
Uma sessão de Agent pode usar um PATH, um diretório de configuração ou um armazenamento de credenciais do sistema diferentes de um terminal comum. Se você vir “command not found”, “config unreadable” ou “identity verification failed”, reinicie o Agent primeiro e então execute:
nadou version --jsonnadou auth status --profile <profile> --jsonnadou auth whoami --profile <profile> --json
Entre de novo só depois de confirmar que o estado de login realmente está inválido.
Se o CLI retornar CREDENTIAL_STORE_UNAVAILABLE e o servidor ou contêiner atual não puder fornecer um armazenamento de credenciais do sistema, não repita o login padrão. Use este comando:
nadou auth login --server --profile <profile>2. Visão geral de capacidades e convenções compartilhadas
2.1 Superfície de comandos
| Domínio | Comandos principais | Finalidade |
|---|---|---|
| Sistema e Skill | version, update, config, doctor, skill, capability | Versão, configuração, diagnósticos, sincronização de Skill e descoberta de capacidades |
| Identidade e espaços | auth, points, space | Login, pontos, espaços, diretórios e destinos de entrega |
| Modelos e geração | model, text, image, video, material | Descoberta de modelos, tarefas de texto/imagem/vídeo e gestão de ativos |
| Tarefas e entrega | task, schedule, evidence | Estimar, enviar, observar, baixar, agendamento, relatórios e evidência de aceite |
| Canvas | canvas | Canvas, Graph, nós, arestas, Timeline e exportação de corte final |
| Mídia local | media | Processar arquivos locais; isso não substitui tarefas de geração no servidor |
Trate nadou capability list --json como a fonte da verdade para o conjunto completo de comandos e o intervalo atualmente aberto. Para uma única capacidade, use nadou capability describe <command> --json para inspecionar finalidade, limites, comportamento assíncrono e comandos de exemplo.
2.2 Saída e flags globais
Todos os comandos suportam saída estável --json. Observação de longa duração, fluxos de eventos e conteúdos recursivos de diretório podem usar --jsonl. Flags globais comuns incluem --profile, --timeout, --trace-id, --no-interactive e --yes.
--json: Devolve resultados estruturados adequados para tratamento programático.--jsonl: Emite eventos ou resultados recursivos linha a linha, o que é útil para observação contínua.--no-interactive: Desativa prompts interativos. Não significa confirmação de custo.--yes: Confirma operações destrutivas como exclusão ou sobrescrita. Não significa autorização de custo.--trace-id: Usado para correlacionar informações de troubleshooting de um fluxo. Não é um ID de tarefa nem uma chave de idempotência.
2.3 Profile, espaço e limites de projeto
Um Profile armazena configurações não sensíveis, como ambiente, endereço do gateway, timeouts, modo de autenticação, espaço padrão e modelos padrão. Contextos de espaço, modelo e Canvas devem ser descobertos e selecionados em separado. Trocar de espaço não cria nem restaura implicitamente outros vínculos de projeto.
2.4 Roteamento de cenário
| Cenário | Portador recomendado | Notas de execução |
|---|---|---|
| Um único texto, imagem, vídeo ou outra capacidade atômica | Tarefa atômica | Confirme parâmetros, espaço de destino, permissões e custo estimado antes do envio. |
| Vários ativos, várias etapas, consistência de personagem, MV, anúncios ou curtas | Espaço/diretório de destino + Canvas | Confirme conta, espaço e diretório primeiro. Finalize o roteiro ou o storyboard antes de entrar em etapas de alto custo. |
| Modificar um Canvas existente | Ler e modificar o Canvas original | Leia o canvas ao vivo antes de escrever, depois leia de novo depois de escrever. Confirme primeiro ao sobrescrever, excluir ou encontrar um conflito. |
| Geração agendada | Os modos de agendamento atualmente abertos pelo CLI | Confirme hora, fuso, conta, espaço e custo estimado antes de criar. |
Quando o usuário menciona claramente NadouPro, texto, imagem, vídeo, ativos, espaços, canvas, nós, imagens de referência, primeiro/último quadro e cenários semelhantes, prefira o Nadou Skill. Se o CLI atual não oferecer uma capacidade, diga isso com clareza. Não substitua por uma capacidade semelhante.
3. Descoberta de modelos e geração de conteúdo
3.1 Descubra modelos e cenários primeiro
nadou model list --type image --json
nadou model list --type video --json
nadou model family "<model display name>" --json
nadou model scenarios "<model-id>" --json
nadou model get <model-id> --json
nadou model schema <model-id> --json
nadou model use image <image-model> --profile <profile>
nadou model use video <video-model> --profile <profile>Nomes de exibição de modelo, parâmetros e cenários disponíveis vêm do catálogo do servidor. Não adivinhe nomes de modelo em um Agent ou script. Leia o cenário ou o schema primeiro e então envie parâmetros correspondentes.
3.2 Capacidades de geração e cenários
| Comando | Cenários comuns | Entradas-chave |
|---|---|---|
nadou text | text2text, image_to_text | Prompt, imagem de referência HTTPS opcional |
nadou image | text2img, image_ref, panorama, three_view, inpaint | Prompt, imagens de referência, máscara, proporção, resolução, quantidade |
nadou video | text2video, first_last_frame, multi_reference, video_edit, motion_control | Prompt, duração, proporção, resolução, vídeo/imagem/áudio de referência |
Prompts podem ser fornecidos com --prompt, --prompt-file ou --stdin. O tamanho máximo é 1 MiB e o conteúdo deve ser UTF-8 válido. Quando um Agent usa --json, --jsonl ou --no-interactive, deve especificar a origem do prompt explicitamente. Depois da pré-visualização e da confirmação de custo, a geração oficial exige --submit. Se argumentos posicionais se aplicam depende da ajuda do comando. --dry-run só constrói e valida a requisição; não envia uma tarefa. Comandos de imagem e vídeo enviam sem esperar por padrão. Use --wait para observar a conclusão no mesmo comando.
O CLI atual não tem um comando independente de geração de áudio com IA. Tarefas de vídeo podem usar áudio de referência, configurações de áudio ou parâmetros de manter o áudio original por cenário, mas isso não é o mesmo que geração independente de áudio.
3.3 Custo, confirmação e entrega
Confirmação de custo
Para tarefas que podem gerar custo, siga “dry-run → consultar pontos → estimar → explicar o consumo estimado e confirmar → envio oficial.” Se o saldo estiver vazio, ilimitado ou temporariamente indisponível, você ainda não deve pular estimativa, explicação de orçamento e confirmação final.
Os comandos correspondentes costumam ser nadou points summary, nadou task estimate e nadou task submit. Uma estimativa não trava o preço final. Confirme de novo contra o resultado realmente devolvido antes do envio.
Geração independente de imagem/vídeo e entrega de artefatos são duas etapas. O destino padrão de entrega é o diretório raiz pessoal. Espaços de equipe, diretórios e políticas de cópia/transferência devem ser especificados explicitamente. O CLI não baixa artefatos por padrão e não executa processamento local de mídia por padrão.
4. Tarefas, agendamentos, entrega e evidência
4.1 Ciclo de vida da tarefa
Comandos comuns incluem task estimate, task submit, task status, task wait, task events, task outputs, task report, task history, task download, task download-batch e task terminate.
task events pode ser usado para observação contínua. O download em lote usa um manifesto retomável, adequado para tarefas longas ou entrega de vários artefatos. Envios de escrita não são tentados de novo automaticamente. Se o processo for interrompido, a rede der timeout ou a resposta não puder ser analisada, consulte primeiro a tarefa, a requisição ou o registro de status original. Não crie um novo envio para tentar de novo.
4.2 Tarefas agendadas
| Modo | Uso típico | Limites principais |
|---|---|---|
server | Geração de imagem/vídeo ou de alguns nós do Canvas | Não promete agendamento geral de texto, gestão de plano ou orquestração DAG. |
local | Geração comum de imagem/vídeo e texto independente | Não inclui Canvas, contexto de projeto ou URLs de referência externas. |
O agendamento exige uma escolha explícita de disabled, local ou server, e um fuso IANA. Confirme hora, fuso, conta, espaço e custo estimado antes de criar, e então escolha o modo conforme a capacidade atual.
Exemplo: nadou schedule create --body-file request.json --scheduled-at <time> --timezone <iana-timezone> --max-points <confirmed points cap>. O intervalo suportado depende do resultado do comando.
4.3 Espaços, diretórios e materiais
space current/list/use: Ver e trocar espaços.space directory create/list/contents: Gerenciar diretórios e ver conteúdos. Conteúdos recursivos podem usar--recursive --jsonl.space file rename: Renomear um arquivo explicitamente.space artifact deliver: Copiar ou transferir artefatos confiáveis de tarefa para um espaço ou diretório de destino.material upload: Enviar materiais locais, com upload em partes e parâmetros opcionais de marca d'água.material delete: Excluir materiais. A exclusão permanente exige--permanentexplícito e confirmação.
Enviar um material não é o mesmo que entregar um artefato de tarefa, e não cria automaticamente um nó do Canvas.
4.4 Evidência de aceite
evidence generation pode gerar evidência local versionada a partir de um ID de tarefa conhecido. evidence delivery pode combinar um manifesto de download, arquivos de mídia, resultados de validação técnica e confirmação humana em evidência de entrega. evidence validate só valida estrutura da evidência, caminhos, hashes e referências. Não dispara nova tentativa, download, entrega ou escritas no Canvas.
Passar na validação técnica não é o mesmo que revisão de qualidade criativa. Para entrega oficial, mantenha versões, IDs de tarefa, IDs de requisição redigidos, hashes de artefato, resultados de checagem de mídia e a confirmação humana necessária. Não armazene tokens, cookies ou valores Authorization completos.
4.5 Interação do Agent, apresentação de artefatos e recuperação
Antes do envio, se a conta, o espaço, o diretório ou o Canvas não for único, explique primeiro as opções e o local esperado de salvamento. Se parâmetros de modelo, papéis de primeiro/último quadro ou a escala do lote estiverem pouco claros, complete essa informação primeiro. Para operações em lote, de alto custo, exclusão, sobrescrita, movimentação ou conflito de colaboração, explique o impacto e obtenha confirmação primeiro.
Imagens: Declare a quantidade real e devolva cada artefato real e seu caminho no espaço.
Vídeo ou outra mídia: Devolva a entrada real de reprodução/download e o caminho no espaço. Uma página de tarefa ou uma miniatura não pode substituir o artefato final.
Texto: Apresente o corpo diretamente. Se não foi salvo em um espaço, explique o motivo.
Canvas complexo: Apresente os artefatos finais, caminhos no espaço, nome do Canvas e pontos reais de entrada, e distinga etapas concluídas das inacabadas.
Sucesso parcial: Entregue primeiro os itens bem-sucedidos, depois liste os itens com falha e as opções de refazer em separado. Não disfarce o pedido inteiro como um sucesso completo ou uma falha completa.
Observações de entrega
Caminhos no espaço e pontos reais de entrada dos artefatos fazem parte da informação de entrega. Se não houver um valor real devolvido pelo servidor, ou o download ainda não tiver terminado, não chame um caminho local, uma página de tarefa ou um estado intermediário de artefato final.
Cada etapa de escrita ou envio roda só uma vez. Em timeout, erros de rede ou respostas não analisáveis, consulte a tarefa original ou o status da operação original. Não mude a chave de idempotência, envie de novo ou regenere só porque um resultado ainda não está visível. Se a geração falhar, uma restrição de direitos autorais se aplicar ou o modelo recusar, pare as etapas seguintes. Se o usuário cancelar, execute o cancelamento uma vez e verifique o status final.
5. Processamento local de mídia
nadou media só processa arquivos locais. Não chama serviços de geração em rede, não modifica arquivos de entrada e recusa sobrescrever saídas existentes por padrão. Oferece inspect, normalize, concatenate, compose, extração de quadros, validação técnica, processamento de legendas e muxing de áudio/vídeo.
Predefinições padrão comuns incluem landscape, portrait e square 1080p. A saída típica é MP4/H.264, yuv420p, 30 fps, AAC-LC, 48 kHz, estéreo. verify é uma checagem técnica. creative_review_required no relatório ainda significa que uma revisão humana é necessária.
Processamento local de mídia e Timeline do Canvas/exportação de corte final são duas capacidades separadas: o primeiro processa arquivos locais; o segundo lê e escreve a timeline associada a um Graph do Canvas e executa tarefas de corte final no servidor.
6. Gestão do Canvas e Graph
6.1 Princípios de operação
Leia o estado mais recente do canvas de destino com
canvas get.Construa uma escrita com base nos nós, arestas e layout atuais.
Depois de escrever, leia de novo para confirmar o status de nós, arestas e artefatos.
Se encontrar um lock, conflito de colaboração, problema de permissão ou resultado pouco claro, pare escritas posteriores. Cheque primeiro o status da operação original e explique o impacto.
O CLI valida campos graváveis por tipo de nó. Os usuários só precisam focar em comandos, entradas, saídas, status e tratamento de erros. Você não precisa montar endereços de serviço, URLs de recurso ou status de tarefa você mesmo.
6.2 Comandos comuns
| Categoria | Comandos |
|---|---|
| Ciclo de vida | canvas list/create/get/rename/move/delete/restore |
| Leitura | canvas get, canvas node list, canvas assets list |
| Graph | canvas graph mutate |
| Nós | canvas node list/create/patch/delete/estimate/generate/wait |
| Arestas | canvas edge connect/patch/delete |
| Timeline | canvas media timeline validate/write/read |
| Corte final | canvas media export prepare/submit/observe |
6.3 Canvas, nós e ativos
Use canvas list para descobrir os canvases atualmente acessíveis, canvas get para ler o Graph ao vivo, canvas node list para inspecionar nós por tipo e canvas assets list para inspecionar materiais históricos ou projeções de artefato. Resultados de lista não devem ser tratados como um snapshot ao vivo antes de escrever.
Nós de mídia personalizados devem usar comandos públicos de nó do Canvas, com campos suportados como IDs de material como entrada. Não forje URLs, metadados, callbacks ou status de tarefa fora do CLI. Trate conflitos de canvas, locks e falhas parciais conforme o erro real. Não crie nós substitutos para esconder o problema original.
6.4 Timeline e corte final
Valide arquivos de Timeline offline primeiro, depois escolha o fluxo de corte final conforme a capacidade atual. Escrita de Timeline, preparação de exportação, envio e observação são operações independentes, e cada etapa roda só uma vez. Se uma consulta de status devolver em andamento, não encontrado ou desconhecido, continue consultando a operação original. Não troque de caminho nem envie de novo.
Se um corte final real pode ser concluído depende de nós válidos do Canvas, Timeline, status da tarefa e capacidades atualmente abertas. Para publicação ou entrega, trate os retornos reais dos comandos e os artefatos finais como a fonte da verdade.
7. Limites atuais de capacidade do CLI
A superfície do CLI pode mudar por versão, conta e cenário.
Um fluxo completo na página do produto não necessariamente está aberto pelo CLI, como o Palco do diretor, a edição e anotação completas de imagem, a gestão de arquivos da mesa de trabalho, o conjunto de edição, a edição de faixa de áudio e o assistente de roteiro. O CLI já oferece alguns comandos de processamento de imagem, como image-tool upscale. Trate a ajuda atual dos comandos e os retornos reais como a fonte da verdade. Quando precisar dessas capacidades, use as entradas do produto diretamente e siga tanto a página do produto quanto a capacidade atual do CLI.
8. Troubleshooting e feedback
8.1 Problemas comuns
O nó do Canvas não pode ser encontrado: Use
canvas getpara buscar o Graph ao vivo primeiro, depois confirme se o ID do canvas, o tipo de nó, o status do nó e a tarefa associada ainda são válidos.Um comando de geração sai antes de produzir um ID de tarefa: A tarefa não foi enviada. Não descreva isso como “a geração falhou” e não envie de novo.
Timeout depois que um ID de tarefa já foi obtido: Continue consultando a tarefa original. Não regenere.
O resultado da escrita no Canvas está pouco claro: Consulte o status da operação original, confirme o estado final do canvas e então decida o próximo passo.
O Agent não vê o estado de login do terminal: Reinicie o Agent primeiro, cheque PATH, o diretório de configuração e o armazenamento de credenciais do sistema, depois execute as checagens da seção 1.4.
8.2 Modelo de feedback
O feedback deve incluir pelo menos: o comando executado, a versão do CLI, o sistema operacional e a arquitetura, o modelo usado, o ID do Canvas ou da tarefa, o ID de requisição/trace ID redigido, o código de erro, o status final e o URL real do artefato.
Não anexe cookies, tokens, valores Authorization, cabeçalhos de requisição completos, credenciais locais ou outras informações sensíveis sem redação.
8.3 Perguntas frequentes
Por que ainda preciso de estimativa e confirmação depois do dry-run?
dry-run só valida a estrutura e os parâmetros da requisição. Não significa uma estimativa no servidor, checagem de saldo ou envio final. Tarefas relacionadas a custo ainda exigem consultar pontos, estimar, explicar o orçamento, obter confirmação e realizar um envio oficial.
Como manter o Skill alinhado com o CLI?
Depois de atualizar o CLI, execute nadou skill install --json e use nadou capability list --json para julgar se o comando atual realmente está aberto. Em tempo de execução, o Agent deve preferir o Skill oficial sincronizado nesta máquina.
Por que não estou vendo o artefato final?
Consulte primeiro o status e as saídas da tarefa original, depois confirme o espaço e o diretório de entrega. Não envie de novo só porque um ponto de entrada está atrasado, uma miniatura está temporariamente ausente ou uma consulta falhou.