CLI 作业与云端命令

概述

本页介绍作业传输、原生 DDS Cloud 会话与工作区操作、显式的旧版 HTTP 服务适配器，以及 25 个客户清单操作。原生 Evolve 操作具有独立的请求契约。

阅读 CLI 命令接口，了解路由规则、两组退出码及回执封装格式。本地解析的引擎命名空间请参阅 CLI 引擎命令。当前版本的限制请参阅 CLI 命令参考，清单的阅读方式请参阅 操作与能力契约。

job 命名空间

job 涵盖离线客户端预检及与 Job Service 之间的作业传输。它由本地解析器处理，因此 -h 可用，且值范围会在联系任何服务之前检查。

八个子命令中有六个接受 --runner <local|cloud|private>，默认值为 cloud。该标志用于选择要联系的 Job Service，不是 rtl compile 等命令上的引擎运行器标志。job readiness 和 job validate 完全没有 --runner，且从不访问网络。

<JOB_ID> 和 --artifact-id 可以直接以连字符开头，无需 -- 分隔符；解析器允许这些参数的值以连字符开头。

在 job wait 上的两个选项会检查范围，检查由解析器强制执行，而非服务：

文本

$ 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

这会以退出码 2 退出。

job readiness

job readiness 无需凭据或网络即可响应。此版本中，它是一个固定、不含路径的投影：每个组件均报告 configured: false 和 ready: false，且 blockers 数组是完整的。

{
  "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"
  ]
}

它以退出码 0 退出。此处的 0 表示就绪状态问题已得到回答，不表示任何组件已经就绪。

job validate

job validate 是 CLI 首次成功运行 中逐步介绍的离线预检。它从 --job 读取 EngineJobV1 文档（当 --job 为 - 或省略时从 stdin 读取），根据精确的 Cloud CPU RTL 客户端封装进行检查，并对一个本地源文件计算哈希。它不解析凭据，不创建客户端，也不联系任何服务。

其回执格式为 altifigence.cli.engine-job-preflight.v1。成功时，status 为 client_preflight_valid，submitted 为 false，server_authority_verified 为 false，job_schema 为 altifigence.engine.job.v1，execution_placement 为 cloud，operation 块为 rtl-engine / analyze / rtl-analysis-request.v1，source 块包含 workspace_uri，sha256，以及 size_bytes。

作业文档读取的硬性上限为 8388608 字节。超过该值，命令失败并报告 EngineJobV1 JSON exceeds the CLI limit.

Cloud 提交要求明确同意上传源码

使用 --runner cloud 时，job submit 和 analyze run 都要求同时提供全部三个源码上传选项。在此版本中，没有这些选项就无法提交 Cloud CPU RTL 作业：

文本

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

这会以退出码 1 退出。提供 --allow-source-upload 但未提供 --workspace-root 时，消息为 --workspace-root is required with --allow-source-upload.；对于 --source 也是如此。

--workspace-root 必须是绝对路径。--source 是位于 <workspace-root>/inputs 下的可移植相对路径。

Cloud 工件下载要求单独明确同意

在 job result 使用 --runner cloud 时，三个工件选项构成一组。提供任意一个选项便会切换到下载模式，随后要求三个全部提供：

• 缺少 --allow-artifact-download：Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• 缺少 --artifact-id：--artifact-id is required with --allow-artifact-download.

• 缺少 --output-dir：--output-dir is required with --allow-artifact-download.

--output-dir 必须是绝对目录。--artifact-id 来自终态 EngineResultV1 的输出列表。

按运行器范围拒绝

有三组选项限定于特定运行器，在其他运行器下会被拒绝。这些决定均在启动任何进程或发送任何请求之前作出：

旧的本地/私有路径指定已停用的 alti-engine-job 适配器，它不在此版本的 24 个运行器清单中。被接受的运行器语法和端点变量，并不能证明已交付本地/私有 Job Service。仅在服务及账户已启用时使用内置 Cloud 路径，或者使用已有文档的直接本地引擎命令。

机器可读的作业错误

job 子命令和 analyze run 在使用 --json 调用时，失败会输出结构化错误封装，而非单独一条消息：

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

完整错误码如下：

retryable 在此版本的所有错误中均为 false。该封装用于 job 命名空间和 analyze run。其他命令族采用各自的错误/回执契约；参阅 命令参考。

analyze run 与 evolve run

analyze run 和显式的原生 Evolve 子命令会进入本地解析器。单词形式的客户操作 analyze 和 evolve 具有独立契约。

analyze run 接受与 job submit 相同的选项，并遵循相同的 Cloud 源码上传规则。它有一处不同：接受 --runner，但拒绝除 cloud 之外的所有值。

文本

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

这会以退出码 1 退出。

evolve run 没有 --runner、没有 --project，也不支持透传。它读取一个请求文档——--request - 从 stdin 读取——并分派到打包的 alti-evolve 引擎，其退出状态原样传递：

文本

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

这个 2 是 alti-evolve 自身退出状态的直接传递，不是 CLI 参数错误。安装环境中若无法解析引擎，同一命令会以退出码 127 退出，并生成回执，其中 status 为 unavailable。

evolve capabilities，evolve analyze，evolve cx-search，evolve measured-ppa，以及 evolve artifact 也已有路由。例如，evolve analyze SAVED_RTL --top TOP [--project ABS] 分析已保存的源码。实测 PPA 的准入/就绪状态/预检不会产生实测 PPA。

公开的 GPU 活动操作为 compute rtl-evolve --request FILE_OR_DASH。它具有独立的原生生成封装，以及明确的 CPU 参考/CUDA 策略。请参阅 引擎命令，不要向它转发 evolve run 请求。

Digital Design Studio Cloud

使用 ide cloud login，随后使用 ide cloud whoami 验证原生会话的身份。refresh 和 logout 管理该会话；--session-dir 选择一个不同于默认值的私有选项。参阅 CLI 身份验证。

ide cloud contract --request FILE_OR_DASH 离线验证类型化的项目/成员/源码/工作区请求。ide cloud run --request FILE_OR_DASH 使用已保存的会话，通过原生 API 发送该请求。包含源码的请求需要 --allow-source-upload。契约验证从不授予组织访问权限，也不能替代服务当前的权限检查。

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

请使用真实且已获授权的组织/项目 UUID。搜索接受 --match-case，--whole-word、保守的固定宽度 --regex，--limit 1..500，以及 --timeout-seconds 1..120。它使用已有、限定范围的 files/read 路由和已保存内容，预算为 500 个文件、每个文件 4 MiB、总计 16 MiB，以及 1 MiB 输出。清单、头部或生成代次变化会使混合快照失效。返回的 contentHash 对读取的精确 UTF-8 文本计算哈希，在当前 Cloud 所有者实现中必须等于 fileVersion。请将 fileVersion 和 workspaceRevision 保留为独立的 CAS 字段。

终端附加保留 WebSocket 传输及当前授权。它以流方式输出 stdout 字节；状态写入 stderr，即使使用全局 --json 也是如此。请使用 --cursor 恢复，并使用 --cols 2..500，--rows 1..200，以及 --max-seconds 1..300 限定附加范围。断开附加不意味着请求终止持久 PTY。这是 Cloud 项目执行，不是本地 CLI shell。

旧版 DDS Workspace Service

ide service 面向显式配置的旧版 HTTP 工作区所有者服务。请在调用方的私有环境中设置 --endpoint 或 ALTI_STUDIO_ENDPOINT，以及其已有的 ALTI_STUDIO_SERVICE_SECRET。不会改用原生 Cloud 会话、浏览器 cookie，或任意 URL/请求体转发。这描述的是旧版服务适配器，并不声称当前原生桌面 UI 使用这些端点，也不声称公开生产服务已启用。

搜索接受 --match-case，--whole-word、保守的固定宽度 --regex，以及 --limit 1..1000（默认 80）。正则准入特意只接受所有者 JavaScript 语法的一个子集；分组、分支和量词均被拒绝。后端匹配仍由服务负责。

替换接受一个封闭的 JSON 对象，必需字段为 query，replacement，paths: [one portable path]，以及 expectedHashes: {same path: 64 hex digits}。可选的 options 仅包含布尔值 matchCase，regex，以及 wholeWord。可选的 match 包含相同的 path，以及从 1 开始的整数 line/column，取值范围为 1 至 4194305。省略 match 时，仅在所选文件内替换，而非整个工作区。哈希必须来自同一服务的当前结果。

请求上限为 64 KiB，包括 JSON 编码与替换文本。不支持未知字段、哈希键/路径不匹配、无效索引、路径穿越、越过服务端边界的链接，以及受保护元数据/排除搜索的路径。CLI 会在 HTTP 请求前拒绝无效格式和受保护路径；文件系统归属及链接检查仍由服务负责。它从不进行本地工作区替换。

响应上限为 8 MiB。--timeout-seconds 1..3600 设置整个 HTTP 请求的截止时间（默认 30）；禁用重定向和自动重试。altifigence.dds.service-receipt.v1 保留 HTTP 状态和响应体，包括成功 DELETE 的空响应。409 仍表示冲突。后端 CAS 与原子性不构成跨后端保证，没有该服务契约的明确允许，不得用本地/Cloud 内容哈希替代其预期哈希。

操作清单

凡是不由本地解析器处理的命令，都交给清单分派器，它将命令路径与嵌入的 customer-tools.v1.json 进行匹配。alti commands 输出整个清单，即包含 25 个条目的单个 JSON 数组，并以退出码 0 退出，无需凭据。

其中 22 个条目标记为 executes: true。另外三个——analyze，evolve，以及 verify——标记为 executes: false，会在分派前打印一条 [plan-only] 提示。同样只有这三个携带源码字节，且需要通过 --allow-source-upload 门控。

25 个条目中还有 14 个带有 remote_core 配置；其余仅带有 local_extended。该配置对可用性的含义见 操作与能力契约。

下述每个操作都会在创建客户端之前从进程环境中读取 ALTI_TOKEN 和 ALTI_ORG_ID；任一缺失时，会以退出码 1 失败：

文本

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

列表操作的通用选项

多个操作共享分页格式：--limit <INTEGER> 的范围为 1..=100，以及 --cursor <STRING>。两者都会在发出任何请求前进行本地验证：

文本

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

这会以退出码 2 退出，未知标志（Unknown option(s): --limti）、缺少必需选项（Missing required option(s): --projectId）及枚举外的值（Invalid value for --visibility: expected one of public, private.).

工作区与项目

对话式 RTL

chat models 在 chat 之前匹配，因为分派器优先匹配最长的命令路径。alti chat 在服务端受额度门控，并记录审计日志。

估算与仅规划操作

--rtl 和 --testbench 是内联源码字符串，各自硬性上限为 1048576 字节，在本地检查：

文本

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

这会以退出码 2 退出。未提供 --allow-source-upload 时，这三个操作中的任意一个都会在构建客户端之前以退出码 4 退出：

文本

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

这三个操作均为 executes: false，因此即使明确同意，也会向 stderr 打印一条 [plan-only] 提示，服务端返回结构化分派计划，而非实际运行。

工件、证据、运行器与计费

MCP 注册表

这些命令读取服务端公布的 MCP 工具注册表及各组织的允许列表。它们与 alti mcp serve 无关；后者在任一分派器之前被拦截，并启动本地 stdio 服务器。参阅 MCP。

一个清单操作无法调用

清单定义了一个单词形式的 trace 操作，用于轨迹摘要。它无法调用，因为 trace 已被本地解析器作为引擎命名空间占用。alti trace 会进入本地解析器，因未找到子命令而以退出码 2 退出；alti trace --limit 5 同样进入本地解析器，并因未知参数以退出码 2 退出。

该操作仍存在于 alti commands 的输出中，因此清单计数为 25，而可调用命令只有 24 个。如果以程序枚举清单，请过滤掉此项。

选择 Cloud 工作流

除非契约明确允许，请勿复用其他工作流的 ID、哈希或回执。重连的终端仍是已有远程会话；提交回复丢失仍可能意味着作业已存在。创建重复项之前，请检查状态。