Comandos de jobs e Cloud da CLI

Visão geral

Esta página aborda o transporte de jobs, sessões Cloud nativas do DDS e operações de espaço de trabalho, o adaptador explícito de serviço HTTP legado e as 25 ações do manifesto do cliente. Operações Evolve nativas têm contratos separados de solicitação.

Leia primeiro Interface de comandos da CLI para conhecer a regra de roteamento, os dois conjuntos de códigos de saída e os envelopes de comprovantes. Para os namespaces de engines analisados localmente, consulte Comandos de engine da CLI. Para limitações da versão atual, consulte Referência de comandos da CLI e, para entender como interpretar o manifesto, consulte Contrato de ações e capacidades.

O namespace job

job abrange preflight offline do cliente e transporte de jobs para um Job Service. É tratado pelo analisador local, portanto -h funciona e os intervalos de valores são verificados antes de qualquer contato.

Seis dos seus oito subcomandos recebem --runner <local|cloud|private>, com padrão cloud. Essa flag seleciona com qual Job Service se comunicar. Não é a flag de engine-runner de rtl compile e comandos semelhantes. job readiness e job validate não têm --runner e nunca acessam a rede.

<JOB_ID> e --artifact-id podem começar com hífen sem precisar de um separador --; o analisador aceita valores com hífen inicial nesses argumentos.

As duas opções com verificação de intervalo em job wait são impostas pelo analisador, não pelo serviço:

Texto

$ alti job wait --poll-interval-ms 99 job-123
error: invalid value '99' for '--poll-interval-ms <POLL_INTERVAL_MS>': 99 is not in 100..=60000

Isso sai com 2.

job readiness

job readiness responde sem credenciais ou rede. Nesta versão, é uma projeção fixa sem caminhos: todo componente informa configured: false e ready: false, e o array blockers está completo.

{
  "schema": "altifigence.engine-product-host-readiness.v1",
  "product_id": "altifigence-cli",
  "authority": { "configured": false, "ready": false },
  "admission": { "configured": false, "ready": false },
  "dispatcher": { "configured": false, "ready": false },
  "executor": { "configured": false, "ready": false },
  "artifact_readback": { "configured": false, "ready": false },
  "ready": false,
  "blockers": [
    "authority_unavailable",
    "admission_unavailable",
    "dispatcher_unavailable",
    "executor_unavailable",
    "artifact_readback_unavailable"
  ]
}

Sai com 0. Um 0 aqui significa que a pergunta de prontidão foi respondida, não que algo esteja pronto.

job validate

job validate é o preflight offline documentado passo a passo em Primeiro sucesso com a CLI. Ele lê um documento EngineJobV1 de --job (ou stdin quando --job é - ou foi omitido), confere-o em relação ao envelope exato do cliente RTL de CPU no Cloud e calcula o hash de um arquivo de código-fonte local. Não resolve credenciais, não cria um cliente nem contata nada.

Seu esquema de comprovante é altifigence.cli.engine-job-preflight.v1. Em caso de sucesso, status é client_preflight_valid, submitted é false, server_authority_verified é false, job_schema é altifigence.engine.job.v1, execution_placement é cloud, o bloco operation é rtl-engine / analyze / rtl-analysis-request.v1 e o bloco source contém workspace_uri, sha256 e size_bytes.

O documento de job é lido com limite rígido de 8388608 bytes. Acima disso, o comando falha com EngineJobV1 JSON exceeds the CLI limit.

O envio ao Cloud exige adesão explícita para código-fonte

Com --runner cloud, tanto job submit e analyze run exigem as três opções de envio de código-fonte juntas. Não há como enviar um job RTL de CPU ao Cloud sem elas nesta versão:

Texto

$ alti job submit --job job.json
error: Cloud Engine Job source upload is disabled; pass --allow-source-upload explicitly.

Isso sai com 1. Com --allow-source-upload mas sem --workspace-root a mensagem é --workspace-root is required with --allow-source-upload., assim como para --source.

--workspace-root deve ser absoluto. --source é um caminho relativo portátil dentro de <workspace-root>/inputs.

O download de artefatos Cloud exige sua própria adesão

Em job result com --runner cloud, as três opções de artefato formam um grupo. Passar qualquer uma muda o comando para o modo de download, que exige então as três:

• Sem --allow-artifact-download: Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• Sem --artifact-id: --artifact-id is required with --allow-artifact-download.

• Sem --output-dir: --output-dir is required with --allow-artifact-download.

--output-dir deve ser um diretório absoluto. --artifact-id vem da lista de saídas de um EngineResultV1 terminal.

Recusas com escopo de runner

Três grupos de opções têm escopo de runner e são recusados fora dele. Cada decisão ocorre antes de qualquer processo iniciar ou solicitação ser feita:

O caminho local/privado antigo nomeia o adaptador desativado alti-engine-job, que não está no inventário de 24 runners da versão. Sintaxe aceita de runner e variáveis de endpoint não estabelecem um Job Service local/privado entregue. Use o caminho Cloud embutido somente onde o serviço e a conta estejam habilitados ou use um comando direto documentado de engine local.

Erros de job legíveis por máquina

job (seus subcomandos) e analyze run quando invocados com --json emitem um envelope estruturado de erro em caso de falha, em vez de uma mensagem simples:

{
  "schema": "altifigence.cli.error.v1",
  "error": {
    "code": "ENGINE_JOB_JSON_INVALID",
    "message": "The engine job JSON is invalid.",
    "retryable": false
  }
}

O conjunto completo de códigos é:

retryable é false em todos eles nesta versão. Esse envelope é emitido para o namespace job e analyze run. Outras famílias de comandos usam seus próprios contratos de erro/comprovante; consulte Referência de comandos.

analyze run e evolve run

analyze run e os subcomandos nativos explícitos do Evolve chegam ao analisador local. As ações de cliente de uma palavra analyze e evolve são contratos separados.

analyze run recebe o mesmo conjunto de opções de job submit e segue a mesma regra de envio de código-fonte ao Cloud. Difere em um aspecto: aceita --runner mas rejeita qualquer coisa exceto cloud.

Texto

$ alti analyze run --runner local --job job.json
error: Local and Private job service adapters are not available; use --runner cloud.

Isso sai com 1.

evolve run não tem --runner, nem --project, nem repasse. Lê um documento de solicitação — --request - lê stdin — e despacha para a engine empacotada alti-evolve, cujo status de saída é repassado:

Texto

$ echo '' | alti evolve run --request -
alti-evolve: invalid request JSON: EOF while parsing a value at line 1 column 0

Esse 2 é o próprio status de saída de alti-evolve sendo repassado, não um erro de argumento da CLI. Em uma instalação onde a engine não pode ser resolvida, o mesmo comando sai com 127 e um comprovante cujo status é unavailable.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa e evolve artifact também são roteados. Por exemplo, evolve analyze SAVED_RTL --top TOP [--project ABS] analisa código-fonte salvo. Admissão/prontidão/preflight de PPA medido não produz PPA medido.

A operação pública de atividade na GPU é compute rtl-evolve --request FILE_OR_DASH. Ela tem um envelope separado de geração nativa e uma política explícita de referência de CPU/CUDA. Consulte Comandos de engine em vez de encaminhar uma solicitação evolve run para ela.

Digital Design Studio Cloud

Use ide cloud login e depois ide cloud whoami para verificar a identidade da sessão nativa. refresh e logout gerenciam essa sessão; --session-dir seleciona uma alternativa privada ao padrão. Consulte Autenticação da CLI.

ide cloud contract --request FILE_OR_DASH valida offline uma solicitação tipada de projeto/membro/código-fonte/espaço de trabalho. ide cloud run --request FILE_OR_DASH envia essa solicitação pela API nativa usando a sessão salva. Solicitações que contêm código-fonte exigem --allow-source-upload. A validação de contratos nunca concede acesso à organização nem substitui as permissões atuais do serviço.

alti ide cloud search --org "$ORG_ID" --project "$PROJECT_ID" \
  --query 'module' --limit 80
alti ide cloud terminal --org "$ORG_ID" --project "$PROJECT_ID" \
  --name cli --max-seconds 60

Use UUIDs reais de organização/projeto autorizados. A busca recebe --match-case, --whole-word, um --regex conservador de largura fixa, --limit 1..500 e --timeout-seconds 1..120. Ela usa rotas existentes com escopo de files/read e conteúdo salvo, com orçamentos de 500 arquivos, 4 MiB/arquivo, 16 MiB no total e 1 MiB de saída. Alterações no manifesto/cabeçalho/geração invalidam um snapshot misto. O contentHash retornado calcula o hash do texto UTF-8 exato lido e, para o responsável atual do Cloud, deve ser igual a fileVersion. Preserve fileVersion e workspaceRevision como campos CAS separados.

A conexão ao terminal preserva o transporte WebSocket e a autorização atual. Ela transmite bytes de stdout; o estado vai para stderr, mesmo com --json global. Use --cursor para retomar, --cols 2..500, --rows 1..200 e --max-seconds 1..300 para limitar a conexão. Desconectar não é uma solicitação para encerrar o PTY persistente. Isso é execução de projeto Cloud, não um shell local da CLI.

Serviço legado de espaço de trabalho DDS

ide service destina-se a um responsável explicitamente configurado de espaço de trabalho HTTP legado. Defina --endpoint ou ALTI_STUDIO_ENDPOINT e seu ALTI_STUDIO_SERVICE_SECRET existente no ambiente privado do chamador. Nenhuma sessão Cloud nativa, cookie do navegador ou encaminhamento de URL/corpo arbitrário é usado como substituto. Isso descreve o adaptador de serviço legado, não afirma que a UI nativa atual do desktop usa esses endpoints ou que um serviço público de produção está habilitado.

A busca aceita --match-case, --whole-word, um --regex conservador de largura fixa e --limit 1..1000 (padrão 80). A admissão de regex aceita deliberadamente um subconjunto da sintaxe JavaScript do responsável; grupos, alternância e quantificadores são rejeitados. A correspondência no backend continua sendo responsabilidade do serviço.

A substituição recebe um objeto JSON fechado com query, replacement, paths: [one portable path] e expectedHashes: {same path: 64 hex digits} obrigatórios. O options opcional contém somente os booleanos matchCase, regex e wholeWord. O match opcional contém o mesmo path e os inteiros de base um line/column entre 1 e 4194305. Omita match para substituir dentro do arquivo selecionado, não em todo o espaço de trabalho. Obtenha o hash do resultado atual desse mesmo serviço.

As solicitações têm no máximo 64 KiB, incluindo a codificação JSON e o texto de substituição. Campos desconhecidos, chaves/caminhos de hash incompatíveis, índices inválidos, travessia de diretórios, links fora do limite do servidor e caminhos de metadados protegidos/excluídos da busca não são suportados. A CLI rejeita formatos inválidos e caminhos protegidos antes do HTTP; as verificações de propriedade do sistema de arquivos e de links permanecem com o serviço. Ela nunca faz substituição no espaço de trabalho local.

As respostas são limitadas a 8 MiB. --timeout-seconds 1..3600 define o prazo HTTP completo (padrão 30); redirecionamentos e tentativas automáticas estão desabilitados. O altifigence.dds.service-receipt.v1 preserva o status e o corpo HTTP, incluindo uma resposta DELETE bem-sucedida vazia. Um 409 permanece um conflito. CAS e atomicidade do backend não são uma garantia entre backends, e hashes de conteúdo local/Cloud não devem substituir o hash esperado por esse serviço sem seu contrato.

O manifesto de ações

Tudo que não é tratado pelo analisador local vai para o despachante do manifesto, que compara seu caminho de comando com o customer-tools.v1.json embutido. alti commands imprime o manifesto inteiro como um array JSON de vinte e cinco entradas e sai com 0 sem credenciais.

Vinte e duas entradas são marcadas como executes: true. Três — analyze, evolve e verify — são executes: false e imprimem uma nota [plan-only] antes do despacho. Essas mesmas três são as únicas que contêm bytes de código-fonte e têm acesso condicionado por --allow-source-upload.

Quatorze das vinte e cinco também contêm o perfil remote_core; as demais têm apenas local_extended. O significado desse perfil para a disponibilidade é abordado em Contrato de ações e capacidades.

Toda ação abaixo lê ALTI_TOKEN e ALTI_ORG_ID do ambiente do processo antes de construir um cliente e falha com saída 1 se qualquer um estiver ausente:

Texto

$ alti credits
Config error: ALTI_TOKEN is not set (org API key or access token).

Opções comuns às ações de listagem

Várias ações compartilham um formato de paginação: --limit <INTEGER> no intervalo 1..=100 e --cursor <STRING>. Ambos são validados localmente antes de qualquer solicitação:

Texto

$ alti project ls --limit 101
Invalid value for --limit: outside allowed range.

Isso sai com 2, assim como uma flag desconhecida (Unknown option(s): --limti), uma opção obrigatória ausente (Missing required option(s): --projectId) ou um valor fora da enumeração (Invalid value for --visibility: expected one of public, private.).

Espaços de trabalho e projetos

RTL conversacional

chat models é correspondido antes de chat, pois o despachante prefere o caminho de comando correspondente mais longo. alti chat tem acesso condicionado a créditos e registrado em auditoria no servidor.

Estimativas e ações que apenas geram planos

--rtl e --testbench são strings inline de código-fonte com limite rígido de 1048576 bytes cada, verificado localmente:

Texto

$ alti analyze --target kv260-fpga --rtl "$(cat huge.sv)" --allow-source-upload
Invalid value for --rtl: exceeds size limit.

Isso sai com 2. Sem --allow-source-upload qualquer uma dessas três sai com 4 antes de construir um cliente:

Texto

Source upload is disabled by default. Re-run with --allow-source-upload only
after reviewing the destination and input.

Essas três são executes: false, portanto mesmo com a adesão imprimem uma nota [plan-only] em stderr e o servidor retorna um plano estruturado de despacho em vez de uma execução.

Artefatos, evidências, runners e faturamento

Registro MCP

Esses comandos leem o registro de ferramentas MCP anunciado pelo servidor e a lista permitida por organização. Eles não têm relação com alti mcp serve, que é interceptado antes de ambos os despachantes e inicia o servidor stdio local. Consulte MCP.

Uma ação do manifesto é inacessível

O manifesto define uma ação de uma palavra trace para resumos de trilhas. Ela não pode ser invocada, pois trace é reservado pelo analisador local como namespace de engine. alti trace chega ao analisador local, não encontra subcomando e sai com 2; alti trace --limit 5 também chega a ele e sai com 2 por um argumento desconhecido.

A ação continua presente na saída de alti commands, por isso a contagem ali é vinte e cinco, enquanto a quantidade de comandos acessíveis é vinte e quatro. Se enumerar o manifesto programaticamente, filtre essa ação.

Escolha o fluxo Cloud

Não reutilize um ID, hash ou comprovante de outro fluxo a menos que seu contrato o aceite explicitamente. Um terminal que reconecta ainda é a sessão remota existente; uma resposta perdida de envio ainda pode corresponder a um job existente. Examine o estado antes de criar uma duplicata.