Comandos de trabajos y Cloud de la CLI

Descripción general

Esta página cubre el transporte de trabajos, las sesiones nativas de DDS Cloud y las operaciones de espacio de trabajo, el adaptador explícito del servicio HTTP heredado y las 25 acciones del manifiesto de cliente. Las operaciones nativas de Evolve tienen contratos de solicitud independientes.

Lee primero Interfaz de comandos de la CLI para conocer la regla de enrutado, los dos conjuntos de códigos de salida y los sobres de comprobantes. Para los espacios de nombres de motores analizados localmente, consulta Comandos de motor de la CLI. Para las limitaciones de la versión actual, consulta Referencia de comandos de la CLI, y para saber cómo debe interpretarse el manifiesto, consulta Contrato de acciones y capacidades.

El espacio de nombres job

job cubre la comprobación previa sin conexión del cliente y el transporte de trabajos frente a un Job Service. Lo gestiona el analizador local, por lo que -h funciona y los intervalos de valores se comprueban antes de contactar con nada.

Seis de sus ocho subcomandos aceptan --runner <local|cloud|private>, con el valor predeterminado cloud. Ese indicador selecciona con qué Job Service comunicarse. No es el indicador de runner de motor de rtl compile y comandos similares. job readiness y job validate no tienen --runner y nunca acceden a la red.

<JOB_ID> y --artifact-id pueden empezar por un guion sin necesitar un separador --; el analizador acepta valores con guion inicial en estos argumentos.

Las dos opciones con intervalo comprobado de job wait las impone el analizador, no el servicio:

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

Eso termina con 2.

job readiness

job readiness responde sin credenciales ni red. En esta versión es una proyección fija sin rutas: todos los componentes informan de configured: false y ready: false, y el 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"
  ]
}

Termina con 0. Un 0 aquí significa que se respondió a la pregunta sobre preparación, no que algo esté listo.

job validate

job validate es la comprobación previa sin conexión documentada paso a paso en Primer resultado satisfactorio con la CLI. Lee un documento EngineJobV1 desde --job (o desde stdin cuando --job es - o se omite), lo comprueba con el sobre exacto de cliente RTL en CPU de Cloud y calcula el hash de un archivo fuente local. No resuelve credenciales, no crea un cliente ni contacta con nada.

Su esquema de comprobantes es altifigence.cli.engine-job-preflight.v1. Si tiene éxito, status es client_preflight_valid, submitted es false, server_authority_verified es false, job_schema es altifigence.engine.job.v1, execution_placement es cloud, el bloque operation es rtl-engine / analyze / rtl-analysis-request.v1, y el bloque source contiene workspace_uri, sha256, y size_bytes.

El documento del trabajo se lee con un límite estricto de 8388608 bytes. Por encima de ese valor, el comando falla con EngineJobV1 JSON exceeds the CLI limit.

El envío a Cloud requiere autorización explícita del código fuente

Con --runner cloud, tanto job submit como analyze run requieren juntas las tres opciones de subida de código fuente. En esta versión no hay forma de enviar un trabajo RTL en CPU a Cloud sin ellas:

Texto

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

Eso termina con 1. Con --allow-source-upload pero sin --workspace-root el mensaje es --workspace-root is required with --allow-source-upload., y lo mismo ocurre con --source.

--workspace-root debe ser absoluto. --source es una ruta relativa portable bajo <workspace-root>/inputs.

La descarga de artefactos de Cloud requiere su propia autorización explícita

En job result con --runner cloud, las tres opciones de artefactos forman un grupo. Pasar cualquiera de ellas cambia el comando al modo de descarga y entonces se requieren las tres:

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

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

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

--output-dir debe ser un directorio absoluto. --artifact-id procede de la lista de salida de un EngineResultV1 terminal.

Rechazos según el runner

Tres grupos de opciones están vinculados a un runner y se rechazan fuera de él. Cada uno se decide antes de iniciar cualquier proceso o realizar cualquier solicitud:

La ruta local o privada anterior designa el adaptador retirado alti-engine-job, que no está en el inventario de 24 runners de la versión. La sintaxis de runner y las variables de endpoint aceptadas no acreditan un Job Service local o privado distribuido. Usa la ruta de Cloud integrada solo donde el servicio y la cuenta estén habilitados, o usa un comando directo de motor local documentado.

Errores de trabajos legibles por máquinas

job (subcomandos) y analyze run invocado con --json emiten en caso de fallo un sobre de error estructurado en lugar de un mensaje sin estructura:

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

El conjunto completo de códigos es:

retryable es false en todos ellos en esta versión. Este sobre se emite para el espacio de nombres job y para analyze run. Otras familias de comandos usan sus propios contratos de errores y comprobantes; consulta Referencia de comandos.

analyze run y evolve run

analyze run y los subcomandos nativos explícitos de Evolve llegan al analizador local. Las acciones de cliente de una sola palabra analyze y evolve son contratos independientes.

analyze run acepta el mismo conjunto de opciones que job submit y sigue la misma regla de subida de código fuente a Cloud. Difiere en un aspecto: acepta --runner pero rechaza todo salvo cloud.

Texto

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

Eso termina con 1.

evolve run no tiene --runner, ni --project, ni paso directo de argumentos. Lee un documento de solicitud —--request - lee stdin— y lo despacha al motor empaquetado alti-evolve, cuyo estado de salida se transmite:

Texto

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

Ese 2 es el estado de salida propio de alti-evolve transmitido, no un error de argumentos de la CLI. En una instalación donde no pueda resolverse el motor, el mismo comando termina con 127 con un comprobante cuyo status es unavailable.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa, y evolve artifact también se enrutan. Por ejemplo, evolve analyze SAVED_RTL --top TOP [--project ABS] analiza código fuente guardado. La admisión, la preparación y la comprobación previa de PPA medidos no producen PPA medidos.

La operación pública de actividad de GPU es compute rtl-evolve --request FILE_OR_DASH. Tiene un sobre de generación nativa independiente y una política explícita de CPU de referencia o CUDA. Consulta Comandos de motor en lugar de reenviarle una solicitud evolve run.

Digital Design Studio Cloud

Usa ide cloud login y después ide cloud whoami para verificar la identidad de la sesión nativa. refresh y logout gestionan esa sesión; --session-dir selecciona una alternativa privada al valor predeterminado. Consulta Autenticación de la CLI.

ide cloud contract --request FILE_OR_DASH valida sin conexión una solicitud tipada de proyecto, miembro, código fuente o espacio de trabajo. ide cloud run --request FILE_OR_DASH envía esa solicitud mediante la API nativa usando la sesión guardada. Las solicitudes que contienen código fuente requieren --allow-source-upload. La validación del contrato nunca concede acceso a la organización ni sustituye los permisos actuales del servicio.

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

Usa UUID reales de organización y proyecto autorizados. La búsqueda acepta --match-case, --whole-word, un --regex conservador de ancho fijo, --limit 1..500, y --timeout-seconds 1..120. Usa las rutas existentes files/read con ámbito definido y contenido guardado, con presupuestos de 500 archivos, 4 MiB por archivo, 16 MiB en total y 1 MiB de salida. Los cambios de manifiesto, cabecera o generación invalidan una captura mixta. El valor devuelto contentHash calcula el hash del texto UTF-8 exacto leído y, para el propietario actual de Cloud, debe ser igual a fileVersion. Conserva fileVersion y workspaceRevision como campos CAS separados.

La conexión al terminal conserva el transporte WebSocket y la autorización actual. Transmite bytes de stdout; el estado va a stderr, incluso con el indicador global --json. Usa --cursor para reanudar, --cols 2..500, --rows 1..200, y --max-seconds 1..300 para acotar la conexión. Desconectarse no es una solicitud para finalizar el PTY persistente. Esto es ejecución de proyectos de Cloud, no un shell local de CLI.

Servicio heredado de espacios de trabajo DDS

ide service se dirige a un propietario de espacio de trabajo HTTP heredado configurado explícitamente. Establece --endpoint o ALTI_STUDIO_ENDPOINT y su valor existente de ALTI_STUDIO_SERVICE_SECRET en el entorno privado de quien invoca. No se sustituyen por una sesión nativa de Cloud, una cookie de navegador ni reenvío arbitrario de URL o cuerpo. Esto describe el adaptador de servicio heredado, no afirma que la interfaz nativa actual de escritorio use estos endpoints ni que esté habilitado un servicio público de producción.

La búsqueda acepta --match-case, --whole-word, un --regex conservador de ancho fijo, y --limit 1..1000 (80 por defecto). La admisión de expresiones regulares acepta deliberadamente un subconjunto de la sintaxis JavaScript del propietario; se rechazan los grupos, la alternancia y los cuantificadores. La búsqueda de coincidencias en el backend sigue siendo responsabilidad del servicio.

El reemplazo acepta un objeto JSON cerrado que requiere query, replacement, paths: [one portable path], y expectedHashes: {same path: 64 hex digits}. El campo opcional options contiene solo booleanos matchCase, regex, y wholeWord. El campo opcional match contiene ese mismo path y los enteros con base uno line/column entre 1 y 4194305. Omite match para reemplazar dentro del archivo seleccionado, no en todo el espacio de trabajo. Obtén el hash del resultado actual de este mismo servicio.

Las solicitudes tienen como máximo 64 KiB, incluida la codificación JSON y el texto de reemplazo. No se admiten campos desconocidos, claves o rutas de hash discrepantes, índices inválidos, recorrido fuera de ruta, enlaces fuera del límite del servidor ni rutas de metadatos protegidos o excluidas de búsqueda. La CLI rechaza estructuras inválidas y rutas protegidas antes de HTTP; las comprobaciones de propiedad del sistema de archivos y enlaces siguen siendo del servicio. Nunca realiza reemplazos en un espacio de trabajo local.

Las respuestas están limitadas a 8 MiB. --timeout-seconds 1..3600 establece el plazo HTTP completo (30 por defecto); se deshabilitan las redirecciones y los reintentos automáticos. El sobre altifigence.dds.service-receipt.v1 conserva el estado HTTP y el cuerpo, incluida una respuesta DELETE satisfactoria vacía. Un 409 sigue siendo un conflicto. CAS y la atomicidad del backend no son una garantía entre backends, y no deben sustituirse hashes de contenido local o de Cloud por el hash esperado de ese servicio sin su contrato.

El manifiesto de acciones

Todo lo que no gestiona el analizador local va al despachador del manifiesto, que compara tu ruta de comando con el archivo integrado customer-tools.v1.json. alti commands imprime todo el manifiesto como un único array JSON de veinticinco entradas y termina con 0 sin credenciales.

Veintidós entradas están marcadas como executes: true. Tres —analyze, evolve, y verify— son executes: false e imprimen una nota [plan-only] antes del despacho. Esas mismas tres son las únicas que contienen bytes de código fuente y están condicionadas a --allow-source-upload.

Catorce de las veinticinco también incluyen el perfil remote_core; el resto solo son local_extended. El significado de ese perfil para la disponibilidad se explica en Contrato de acciones y capacidades.

Cada acción siguiente lee ALTI_TOKEN y ALTI_ORG_ID del entorno del proceso antes de construir un cliente y falla con salida 1 si falta cualquiera de los dos:

Texto

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

Opciones comunes de las acciones de listado

Varias acciones comparten una estructura de paginación: --limit <INTEGER> en el intervalo 1..=100, y --cursor <STRING>. Ambos se validan localmente antes de cualquier solicitud:

Texto

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

Eso termina con 2, al igual que un indicador desconocido (Unknown option(s): --limti), una opción obligatoria ausente (Missing required option(s): --projectId) y un valor fuera de la enumeración (Invalid value for --visibility: expected one of public, private.).

Espacios de trabajo y proyectos

RTL conversacional

chat models se compara antes de chat, porque el despachador prefiere la ruta de comando coincidente más larga. alti chat está condicionado a créditos y se registra para auditoría en el servidor.

Estimación y acciones de solo planificación

--rtl y --testbench son cadenas de código fuente en línea con un límite estricto de 1048576 bytes cada una, comprobado localmente:

Texto

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

Eso termina con 2. Sin --allow-source-upload cualquiera de estas tres termina con 4 antes de construir un cliente:

Texto

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

Estas tres son executes: false, por lo que incluso con autorización explícita imprimen una nota [plan-only] en stderr y el servidor devuelve un plan de despacho estructurado en lugar de una ejecución.

Artefactos, evidencias, runners y facturación

Registro MCP

Estos leen el registro de herramientas MCP anunciado por el servidor y la lista de permitidos por organización. No guardan relación con alti mcp serve, que se intercepta antes de cualquiera de los despachadores e inicia el servidor stdio local. Consulta MCP.

Una acción del manifiesto es inaccesible

El manifiesto define una acción de una sola palabra trace para resúmenes de traza. No puede invocarse porque trace está reservado por el analizador local como espacio de nombres de motor. alti trace llega al analizador local, no encuentra subcomando y termina con 2; alti trace --limit 5 también llega a él y termina con 2 por un argumento desconocido.

La acción sigue presente en la salida de alti commands, por lo que allí se cuentan veinticinco mientras que el número de comandos accesibles es veinticuatro. Si enumeras el manifiesto mediante código, filtra esta acción.

Elige el flujo de trabajo de Cloud

No reutilices un ID, un hash ni un comprobante de otro flujo de trabajo salvo que su contrato lo acepte explícitamente. Un terminal que se vuelve a conectar sigue siendo la sesión remota existente; una respuesta de envío perdida sigue correspondiendo a un trabajo que podría existir. Inspecciona el estado antes de crear un duplicado.