Comandi CLI per job e Cloud

Panoramica

Questa pagina descrive il trasporto dei job, le sessioni Cloud e le operazioni sull'area di lavoro DDS native, l'adattatore esplicito del servizio HTTP legacy e le 25 azioni del manifesto cliente. Le operazioni Evolve native hanno contratti di richiesta distinti.

Leggere Interfaccia dei comandi CLI per prima cosa per la regola di instradamento, i due insiemi di codici di uscita e gli involucri delle ricevute. Per i namespace dei motori elaborati dal parser locale vedere Comandi dei motori CLI. Per i limiti della release corrente vedere Riferimento dei comandi CLI, e per l'interpretazione del manifesto vedere Contratto delle azioni e delle capacità.

Il namespace job

job comprende il controllo preliminare offline del client e il trasporto dei job tramite un Job Service. Viene gestito dal parser locale, quindi -h funziona e gli intervalli di valori vengono controllati prima di contattare qualsiasi servizio.

Sei degli otto sottocomandi accettano --runner <local|cloud|private>, con valore predefinito cloud. Questo flag seleziona il Job Service da contattare. Non è il flag del runner del motore di rtl compile e comandi analoghi. job readiness e job validate non hanno alcun --runner e non accedono mai alla rete.

<JOB_ID> e --artifact-id possono iniziare con un trattino senza richiedere un separatore --; il parser accetta valori che iniziano con un trattino per questi argomenti.

Le due opzioni con intervalli controllati di job wait sono verificate dal parser, non dal servizio:

Testo

$ 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

Il comando termina con 2.

job readiness

job readiness risponde senza credenziali né rete. In questa release è una proiezione fissa senza percorsi: ogni componente riporta configured: false e ready: false, e l'array blockers è 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"
  ]
}

Termina con 0. Un 0 qui significa che è stata fornita una risposta sulla disponibilità, non che qualcosa sia pronto.

job validate

job validate è il controllo preliminare offline documentato passo per passo in Prima esecuzione riuscita con la CLI. Legge un documento EngineJobV1 da --job (o da stdin quando --job è - oppure è omesso), lo verifica rispetto all'esatto involucro client RTL CPU Cloud e calcola l'hash di un file sorgente locale. Non risolve credenziali, non crea client e non contatta alcun servizio.

Il suo schema di ricevuta è altifigence.cli.engine-job-preflight.v1. In caso di successo status è client_preflight_valid, submitted è false, server_authority_verified è false, job_schema è altifigence.engine.job.v1, execution_placement è cloud, il blocco operation è rtl-engine / analyze / rtl-analysis-request.v1, e il blocco source contiene workspace_uri, sha256 e size_bytes.

Il documento del job viene letto con un limite rigido di 8388608 byte. Oltre tale limite il comando fallisce con EngineJobV1 JSON exceeds the CLI limit.

L'invio al Cloud richiede un consenso esplicito per i sorgenti

Con --runner cloud, entrambi i comandi job submit e analyze run richiedono insieme tutte e tre le opzioni di caricamento dei sorgenti. In questa release non è possibile inviare un job RTL CPU Cloud senza di esse:

Testo

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

Il comando termina con 1. Con --allow-source-upload ma senza --workspace-root il messaggio è --workspace-root is required with --allow-source-upload., e lo stesso vale per --source.

--workspace-root deve essere assoluto. --source è un percorso relativo portabile all'interno di <workspace-root>/inputs.

Il download degli artefatti Cloud richiede un consenso specifico

Su job result con --runner cloud, le tre opzioni degli artefatti formano un gruppo. Specificarne una attiva la modalità di download del comando e richiede quindi tutte e tre:

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

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

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

--output-dir deve essere una directory assoluta. --artifact-id proviene dall'elenco degli output di un EngineResultV1 finale.

Rifiuti specifici del runner

Tre gruppi di opzioni sono specifici di un runner e vengono rifiutati al di fuori di esso. Ciascuna decisione viene presa prima di avviare qualsiasi processo o inviare qualsiasi richiesta:

Il vecchio percorso locale/privato indica l'adattatore dismesso alti-engine-job, che non è nell'inventario dei 24 runner della release. La sintassi dei runner e le variabili degli endpoint accettate non dimostrano la fornitura di un Job Service locale/privato. Usare il percorso Cloud incorporato solo quando il servizio e l'account sono abilitati oppure usare un comando diretto documentato del motore locale.

Errori dei job leggibili dalle macchine

job e i relativi sottocomandi, insieme a analyze run invocato con --json, generano in caso di errore un involucro strutturato anziché un semplice messaggio:

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

L'insieme completo dei codici è:

retryable è false per tutti questi errori in questa release. Questo involucro viene generato per il namespace job e analyze run. Le altre famiglie di comandi usano i propri contratti di errore/ricevuta; vedere Riferimento dei comandi.

analyze run ed evolve run

analyze run e i sottocomandi Evolve nativi espliciti raggiungono il parser locale. Le azioni cliente di una sola parola analyze e evolve sono contratti distinti.

analyze run accetta lo stesso insieme di opzioni di job submit e segue la stessa regola di caricamento dei sorgenti Cloud. Differisce in un aspetto: accetta --runner ma rifiuta qualsiasi valore diverso da cloud.

Testo

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

Il comando termina con 1.

evolve run non ha --runner, né --project, né argomenti inoltrati. Legge un documento di richiesta — --request - legge stdin — e lo inoltra al motore incluso alti-evolve, il cui stato di uscita viene trasmesso:

Testo

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

Quel 2 è lo stato di uscita di alti-evolve trasmesso direttamente, non un errore degli argomenti CLI. In un'installazione in cui il motore non è risolvibile, lo stesso comando termina con 127 e una ricevuta il cui status è unavailable.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa e evolve artifact sono anch'essi instradati. Per esempio, evolve analyze SAVED_RTL --top TOP [--project ABS] analizza un sorgente salvato. L'ammissione, la disponibilità e il controllo preliminare di measured-PPA non producono PPA misurati.

L'operazione pubblica di attività GPU è compute rtl-evolve --request FILE_OR_DASH. Ha un involucro di generazione nativa distinto e una politica esplicita per riferimento CPU/CUDA. Vedere Comandi dei motori anziché inoltrarle una richiesta evolve run.

Digital Design Studio Cloud

Usare ide cloud login, poi ide cloud whoami per verificare l'identità della sessione nativa. refresh e logout gestiscono tale sessione; --session-dir seleziona un'alternativa privata a quella predefinita. Vedere Autenticazione CLI.

ide cloud contract --request FILE_OR_DASH valida offline una richiesta tipizzata di progetto/membro/sorgente/area di lavoro. ide cloud run --request FILE_OR_DASH invia la richiesta tramite l'API nativa usando la sessione salvata. Le richieste che contengono sorgenti richiedono --allow-source-upload. La validazione del contratto non concede mai accesso all'organizzazione né sostituisce le autorizzazioni correnti del servizio.

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

Usare UUID reali di organizzazioni/progetti autorizzati. La ricerca accetta --match-case, --whole-word, un'espressione conservativa a larghezza fissa --regex, --limit 1..500 e --timeout-seconds 1..120. Usa le route esistenti di file/lettura con ambito definito e il contenuto salvato, con budget di 500 file, 4 MiB/file, 16 MiB totali e 1 MiB di output. Le modifiche a manifesto/header/generazione invalidano uno snapshot misto. Il valore restituito contentHash è l'hash dell'esatto testo UTF-8 letto e, per il proprietario Cloud corrente, deve essere uguale a fileVersion. Conservare fileVersion e workspaceRevision come campi CAS distinti.

Il collegamento al terminale conserva il trasporto WebSocket e l'autorizzazione corrente. Trasmette i byte stdout; lo stato va su stderr, anche con l'opzione globale --json. Usare --cursor per riprendere, --cols 2..500, --rows 1..200 e --max-seconds 1..300 per limitare il collegamento. Scollegarsi non è una richiesta di terminare il PTY persistente. Si tratta di esecuzione di progetto Cloud, non di una shell CLI locale.

Servizio legacy dell'area di lavoro DDS

ide service si rivolge a un proprietario HTTP legacy dell'area di lavoro configurato esplicitamente. Impostare --endpoint oppure ALTI_STUDIO_ENDPOINT e il suo valore esistente ALTI_STUDIO_SERVICE_SECRET nell'ambiente privato del chiamante. Non vengono sostituiti con una sessione Cloud nativa, un cookie del browser o un inoltro arbitrario di URL/corpo. Questo descrive l'adattatore del servizio legacy e non afferma che l'attuale interfaccia desktop nativa usi tali endpoint o che sia abilitato un servizio pubblico di produzione.

La ricerca accetta --match-case, --whole-word, un'espressione conservativa a larghezza fissa --regex e --limit 1..1000 (predefinito 80). L'ammissione delle regex accetta deliberatamente un sottoinsieme della sintassi JavaScript del proprietario; gruppi, alternative e quantificatori vengono rifiutati. La corrispondenza nel backend rimane responsabilità del servizio.

La sostituzione accetta un oggetto JSON chiuso che richiede query, replacement, paths: [one portable path] e expectedHashes: {same path: 64 hex digits}. Il campo facoltativo options contiene soltanto i booleani matchCase, regex e wholeWord. Il campo facoltativo match contiene lo stesso path e gli interi con base 1 line/column tra 1 e 4194305. Omettere match per sostituire nel file selezionato, non nell'intera area di lavoro. Ottenere l'hash dal risultato corrente dello stesso servizio.

Le richieste sono limitate a 64 KiB, inclusi codifica JSON e testo di sostituzione. Non sono supportati campi sconosciuti, chiavi hash/percorsi non corrispondenti, indici non validi, attraversamento dei percorsi, collegamenti oltre il limite del server e percorsi di metadati protetti/esclusi dalla ricerca. La CLI rifiuta strutture non valide e percorsi protetti prima di HTTP; proprietà del filesystem e controlli dei collegamenti rimangono al servizio. Non esegue mai sostituzioni nell'area di lavoro locale.

Le risposte sono limitate a 8 MiB. --timeout-seconds 1..3600 imposta la scadenza HTTP complessiva (predefinita 30); reindirizzamenti e tentativi automatici sono disabilitati. Lo schema altifigence.dds.service-receipt.v1 conserva stato HTTP e corpo, compresa una risposta DELETE riuscita e vuota. Un 409 rimane un conflitto. CAS e atomicità del backend non costituiscono una garanzia tra backend e gli hash dei contenuti locali/Cloud non devono sostituire l'hash atteso da quel servizio senza il suo contratto.

Il manifesto delle azioni

Tutto ciò che non viene gestito dal parser locale passa al dispatcher del manifesto, che confronta il percorso del comando con il file incorporato customer-tools.v1.json. alti commands stampa l'intero manifesto come array JSON di venticinque voci e termina con 0 senza credenziali.

Ventidue voci sono contrassegnate executes: true. Tre — analyze, evolve e verify — sono executes: false e stampano una nota [plan-only] prima dell'inoltro. Queste stesse tre sono le uniche che trasportano byte sorgente e richiedono --allow-source-upload.

Quattordici delle venticinque hanno anche il profilo remote_core; le restanti hanno soltanto local_extended. Il significato di quel profilo per la disponibilità è descritto in Contratto delle azioni e delle capacità.

Ogni azione seguente legge ALTI_TOKEN e ALTI_ORG_ID dall'ambiente del processo prima di costruire un client e fallisce con uscita 1 se manca uno dei due:

Testo

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

Opzioni comuni alle azioni di elenco

Diverse azioni condividono la struttura di paginazione: --limit <INTEGER> nell'intervallo 1..=100 e --cursor <STRING>. Entrambe vengono validate localmente prima di qualsiasi richiesta:

Testo

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

Il comando termina con 2, come un flag sconosciuto (Unknown option(s): --limti), un'opzione obbligatoria mancante (Missing required option(s): --projectId), o un valore fuori dall'enumerazione (Invalid value for --visibility: expected one of public, private.).

Aree di lavoro e progetti

RTL conversazionale

chat models viene riconosciuto prima di chat, poiché il dispatcher preferisce il percorso di comando corrispondente più lungo. alti chat è subordinato ai crediti e registrato nel log di audit lato server.

Azioni di stima e sola pianificazione

--rtl e --testbench sono stringhe sorgente inline con un limite rigido di 1048576 byte ciascuna, verificato localmente:

Testo

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

Il comando termina con 2. Senza --allow-source-upload ciascuna di queste tre termina con 4 prima di costruire un client:

Testo

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

Queste tre sono executes: false, quindi anche con il consenso stampano una nota [plan-only] su stderr e il server restituisce un piano strutturato di inoltro anziché un'esecuzione.

Artefatti, prove, runner e fatturazione

Registro MCP

Leggono il registro degli strumenti MCP dichiarato dal server e l'elenco consentito per organizzazione. Non sono correlati a alti mcp serve, che viene intercettato prima di entrambi i dispatcher e avvia il server stdio locale. Vedere MCP.

Un'azione del manifesto non è raggiungibile

Il manifesto definisce un'azione di una sola parola, trace, per i riepiloghi delle tracce. Non può essere invocata perché trace viene preso in carico dal parser locale come namespace di motore. alti trace raggiunge il parser locale, non trova sottocomandi e termina con 2; alti trace --limit 5 lo raggiunge anch'esso e termina con 2 per un argomento sconosciuto.

L'azione è ancora presente nell'output di alti commands, motivo per cui il conteggio è venticinque mentre i comandi raggiungibili sono ventiquattro. Se si enumera il manifesto tramite codice, escludere questa azione.

Scegliere il flusso di lavoro Cloud

Non riutilizzare ID, hash o ricevute di un altro flusso di lavoro a meno che il contratto li accetti esplicitamente. Un terminale che si riconnette è ancora la sessione remota esistente; una risposta persa a un invio indica ancora un job potenzialmente esistente. Controllare lo stato prima di creare un duplicato.