CLI 引擎命令 — Altifigence Documentation

使用本地设计引擎、原生 XLS 与 CUDA，以及 DDS 创作功能，并遵守明确的限制和输入契约。

概述

本页介绍本地设计引擎命令、主要参数及其执行边界。完整的选项和值枚举列表，请查看已安装命令末级子命令的 --help。将结果用作工程依据之前，请先阅读结果本身列明的限制。

阅读 CLI 命令接口。该页定义了下述所有命令依赖的路由、退出码、回执封装格式及同级程序解析规则。有关 job 命名空间、analyze run，以及 evolve run 的说明，请参阅 CLI 作业与云端命令。

表格中的约定：

<ANGLE> 是位置参数；[ANGLE]... 是可重复指定的可选参数。
“必需项”列中的选项必须提供，否则命令会在启动任何操作前以退出码 2 退出。
每个子命令也接受 --json 和 -h/--help。各行不再重复列出这两个选项。
--project 为 --project <PROJECT>，用于相对输入、输出路径的可选工作目录，除非某行另有说明。它必须能解析为真实目录；无法解析的值会使命令以退出码 2 退出。

capabilities

alti capabilities 检查已认证的安装布局并报告其操作接口。请先完成在 Linux 上安装；0.1.9 的嵌入式引导程序提供了此前缺失的回执和载荷布局。能力响应不能证明内核或设计已实际执行。

rtl

共有 28 个子命令。rtl compile 和 rtl synthesize 是两条带有 --runner 的兼容路径；其余所有 rtl 子命令均无条件在本地运行。

与 physical run 和 px analyze 不同，这两个命令即使没有透传参数，也会启动引擎，因为它们各自提供固定的引擎操作。随后引擎会报告自己的缺失参数错误，其退出状态原样传递。请在 -- 之后提供所需参数。

命令	必需项	其他选项	用途
`rtl` `compile`	—	`--runner` `<local\|cloud\|private>`（默认值为 `local`），`--project`，`--` `<ENGINE_ARG>...`	委派给打包的编译引擎的兼容路径
`rtl` `synthesize`	—	`--runner`（默认值为 `local`），`--project`，`--` `<ENGINE_ARG>...`	原始底层本地综合委派的兼容写法
`rtl` `schematic` `<FILE>...`	至少一个 `<FILE>`	`--project`，`--top` `<TOP>`，`--format` `<json\|text>`（默认值为 `json`），`-I` `<DIR>`，`-D` `<NAME[=VALUE]>`	为已保存的 RTL 源码输出经编译器确认的原理图契约
`rtl` `analysis` `<PATH>...`	至少一个 `<PATH>`	`--project`	对指定源码运行打包的分析操作
`rtl` `synth` `[FILE]...`	`--top` `<TOP>`	`--project`，`--pretty`，`--netlist-only`，`--source` `<LOGICAL_PATH>` `<DISK_PATH>`	运行打包的综合操作
`rtl` `map`	`--netlist` `<NETLIST>`，`--liberty` `<LIBERTY>`	`--project`，`--pretty`	运行打包的工艺映射操作
`rtl` `target-analysis` `capabilities`	—	—	报告固定的目标分析契约和执行器可用性
`rtl` `target-analysis` `readiness`	—	—	报告不含路径的只读目标分析执行就绪状态
`rtl` `target-analysis` `admit`	下述 11 个选项	`--cell-decomposition`	从 stdin 中的源码包 JSON 验证一次类型化准入请求
`rtl` `target-analysis` `preflight`	下述 11 个选项	`--cell-decomposition`	从 stdin 中的源码包 JSON 运行结构预检
`rtl` `simulate` `admit\|preflight\|run` `<REQUEST_JSON>`	`<REQUEST_JSON>`	`--project`	对一次有界的已保存 RTL 仿真请求执行准入、预检或执行
`rtl` `simulate-v2` `capabilities`	—	—	报告固定的四态多时钟仿真契约
`rtl` `simulate-v2` `admit\|preflight\|run` `<REQUEST_JSON>`	`<REQUEST_JSON>`	`--project`	对一次有界的四态多时钟请求执行准入、预检或执行
`rtl` `artifact` `store` `<RESULT_JSON_OR_DASH>`	`<RESULT_JSON_OR_DASH>`	`--project`，`--schematic`	将一份结果回执持久保存到项目工件存储中
`rtl` `artifact` `list`	—	`--project`，`--schematic`	列出已存储的条目
`rtl` `artifact` `show` `<ENTRY_ID>`	`<ENTRY_ID>`	`--project`，`--schematic`	读取一个已存储的条目
`rtl` `fanout-free-committed-identities` `list`	—	`--project`	列出固定所有者私有注册表中有限数量的已验证标识
`rtl` `fanout-free-committed-identities` `read`	`--entry-id` `<SHA256>`	`--project`	重新读取从当前已验证列表中选出的一个标识
`rtl` `global-sharing-committed-identities` `list\|read`	`read`：`--entry-id` `<SHA256>`	`--project`	同上，适用于全局共享标识
`rtl` `mapped-timing-committed-identities` `list\|read`	`read`：`--entry-id` `<SHA256>`	`--project`	同上，适用于映射时序标识
`rtl` `mapped-register-timing-committed-identities` `list\|read`	`read`：`--entry-id` `<SHA256>`	`--project`	同上，适用于映射寄存器时序标识

--schematic 在三个 rtl artifact 子命令中用于选择固定的原理图回执存储，而非 RTL 操作结果存储。

--entry-id 在已提交标识的末级子命令中，必须恰好为 64 个小写十六进制字符。其他值会使命令以退出码 2 退出，并报告 entry id must be exactly 64 lowercase hexadecimal characters。

rtl schematic 的限制

rtl schematic 会在启动任何操作之前验证路径。每个源文件、包含目录和宏定义，只要违反下列任一限制，就会在准入时被拒绝：

限制	值
源文件	最多 256 个
包含目录（`-I`）	最多 128 个
宏定义（`-D`）	最多 256 个
路径长度	1 至 4096 字节
路径组成部分	1 至 128 个
单个路径组成部分	最多 255 字节

路径必须相对于所选项目，不能以 - 开头，不能包含控制字节，也不能包含 ..。--top 和宏定义名称必须是 1 至 128 字节的 SystemVerilog 标识符；宏定义可在 = 后附带值，总长度不得超过 4096 字节。

rtl target-analysis 选项

admit 和 preflight 都从 stdin 读取规范的源码包 JSON，并要求相同的 11 个选项：--module <NAME>，--top <NAME>，--targets <CSV>，--primary-target <ID>，--tools <CSV>，--report-detail <LEVEL>，--profile <ID>，--cpu-slots <N>，--memory-bytes <N>，--max-wall-time-ms <N>，以及 --deadline-unix-ms <N>。--cell-decomposition 是可选的布尔标志。

选项	可接受的值
`--primary-target`	`generic-asic`，`sky130-asic`，`xc7-fpga`
`--targets`	以逗号分隔的子集，取自 `generic-asic`，`sky130-asic`，`xc7-fpga`，且不得重复
`--tools`	以逗号分隔的子集，取自 `waveform`，`schematic`，`roofline`，`perf`，`timing`，`ppa`，`evidence`，且不得重复
`--report-detail`	`brief`，`standard`，`detailed`

--cpu-slots 是 32 位无符号整数；--memory-bytes，--max-wall-time-ms，以及 --deadline-unix-ms 是 64 位无符号整数。

任一 CSV 列表中出现重复或未列出的值，都会在解析时被拒绝，例如 targets must be a comma-separated subset of: generic-asic, sky130-asic, xc7-fpga。

仿真请求封装格式

<REQUEST_JSON> 是相对于项目的文件路径，CLI 会在启动任何操作之前读取并检查该文件。路径必须规范化且为相对路径，任何组成部分都不得经过符号链接，最终必须解析到项目根目录内。文件必须是普通文件，且不得超过 260 MiB。

其 JSON 必须是恰好包含四个键的对象：

{
  "schema": "altifigence.rtl.operation-request.v1",
  "version": 1,
  "operationId": "altifigence.rtl.simulate.v1",
  "request": {}
}

operationId 必须为 altifigence.rtl.simulate.v1（用于 rtl simulate）或 altifigence.rtl.simulate.v2（用于 rtl simulate-v2）。不匹配时会在启动前被拒绝，并报告 RTL simulation request must be the exact <id> envelope。

已提交标识子命令无法运行

八个 rtl *-committed-identities list 和 read 末级子命令分派到名为 alti-rtl-runner 的引擎。该二进制程序不在此版本构建和交付的 24 个引擎二进制程序之列，因此在正确安装的环境中，既无法将其解析为 alti 的同级程序，也无法从 PATH 中解析。调用这些命令之一，会生成带有 status: "unavailable" 和 exitCode: 127 的本地引擎回执：

文本

$ alti --json rtl fanout-free-committed-identities list
{
  "schema": "altifigence.local-engine-execution.v1",
  "status": "unavailable",
  "domain": "rtl",
  "operation": "fanout-free-committed-identities-list",
  "runner": "local",
  "binary": "alti-rtl-runner",
  ...
}

请勿基于这八个命令构建自动化流程。

sv

共有 23 个子命令，全部无条件在本地运行。均不接受 --runner。

命令	必需项	其他选项	用途
`sv` `frontend` `index` `[PATH]...`	—	`--project`	针对指定路径构建前端索引
`sv` `frontend` `symbols` `[PATH]...`	—	`--project`	报告指定路径的符号接口
`sv` `frontend` `symbols-v2` `[PATH]...`	—	`--project`	第二代符号响应格式
`sv` `frontend` `definition` `<PATH>` `<LINE>` `<COLUMN>` `[ANALYSIS_PATH]...`	位置	`--project`	解析某个位置的定义
`sv` `frontend` `hover` `<PATH>` `<LINE>` `<COLUMN>` `[ANALYSIS_PATH]...`	位置	`--project`	解析某个位置的悬停响应
`sv` `frontend` `complete` `<PREFIX>` `[PATH]...`	`<PREFIX>`	`--project`	解析某个前缀的补全项
`sv` `frontend` `references` `<PATH>` `<LINE>` `<COLUMN>` `[ANALYSIS_PATH]...`	位置	`--project`	解析某个位置上符号的引用
`sv` `frontend` `rename-plan` `<PATH>` `<LINE>` `<COLUMN>` `<REPLACEMENT>` `[ANALYSIS_PATH]...`	位置，`<REPLACEMENT>`	`--project`	生成重命名计划，但不编辑文件
`sv` `frontend` `rename-apply` `<PATH>` `<LINE>` `<COLUMN>` `<REPLACEMENT>` `<REVIEWED_PLAN_SHA256>`	全部五个	`--project` `<ABSOLUTE_WORKSPACE>` 均为必需项	应用重命名操作，以已审核计划的哈希作为门控条件
`sv` `review` `immediate`	—	—	审核立即断言，但不编译或仿真
`sv` `review` `interprocess`	—	—	审核进程间同步，但不编译或仿真
`sv` `library` `constrained-random` `list`	—	`--category` `<item\|control\|checker>`，`--filter` `<FILTER>`，`--limit` `<LIMIT>`（默认值为 `64`）	列出约束随机参考目录中的条目
`sv` `library` `constrained-random` `show` `<STABLE_ID>`	`<STABLE_ID>`	—	显示一个约束随机目录条目
`sv` `library` `sva` `list`	—	`--category`，`--filter`，`--limit`（默认值为 `64`）	列出 SVA 参考目录中的条目
`sv` `library` `sva` `show` `<STABLE_ID>`	`<STABLE_ID>`	—	显示一个 SVA 目录条目
`sv` `uvm` `capabilities`	—	—	报告编译后的 UVM 桥接契约
`sv` `uvm` `environment`	—	—	报告 UVM 桥接环境视图
`sv` `uvm` `readiness`	—	—	返回固定组件的签名就绪回执，但不加载或运行该组件
`sv` `uvm` `abi`	—	—	报告 UVM 桥接 ABI
`sv` `uvm` `simulation` `capabilities`	—	—	报告有界 UVM 仿真契约
`sv` `uvm` `simulation` `readiness`	—	—	报告不含路径的实现就绪状态和外部执行权限就绪状态
`sv` `uvm` `simulation` `admit`	下述 13 个选项	—	验证一次有界且默认拒绝的 UVM 仿真请求
`sv` `uvm` `simulation` `preflight`	下述 16 个选项	`--cancellation-requested`	预检一次有界且默认拒绝的 UVM 仿真请求

位置参数值的规则：

<LINE> 和 <COLUMN> 是从 1 开始的非零整数。0 会以退出码 2 退出。
<REPLACEMENT> 必须是 SystemVerilog 标识符：首字符为字母、_，或 $，其余字符为字母数字、_，或 $。
<REVIEWED_PLAN_SHA256> 必须为 64 个小写十六进制字符。
<STABLE_ID> 必须为 1 至 128 个字符，且只能包含小写字母、数字和连字符。
--filter 必须为 1 至 128 个非控制字节；--limit 必须为 1 至 64 的整数，而 --limit 65 会以退出码 2 退出。

sv frontend rename-apply 是唯一一个 sv 子命令，要求 --project，其值必须是指向真实目录的绝对路径，且该目录不能是符号链接。未提供时，命令会以退出码 1 退出，并报告 SV rename apply requires --project <absolute-workspace>。

sv review immediate 和 sv review interprocess 从 stdin 读取 SystemVerilog 源码。它们是仅有的两个由各自独立引擎支持的 sv 子命令，引擎分别为 alti-sv-immediate-review 和 alti-sv-interprocess-review；该命名空间中的其余命令均使用 alti-sv-frontend。

sv uvm simulation admit 要求 13 个选项：--bundle-id，--bundle-sha256，--source-count，--source-bytes，--test，--top，--clock，--period-ps，--cycles，--max-wall-time-ms，--max-cpu-cores，--max-memory-bytes，以及 --max-artifact-bytes。sv uvm simulation preflight 要求上述 13 个选项，再加上 --attempt-id，--observed-at-unix-ms，以及 --deadline-unix-ms，还接受布尔选项 --cancellation-requested（默认值为 false）。--source-count 是 32 位无符号整数，--max-cpu-cores 是 16 位无符号整数，其余数值选项为 64 位无符号整数。

verification

命令	必需项	其他选项	用途
`verification` `golden-diff` `emit-profile` `<TRACE>`	`<TRACE>`	`--project`，`--tolerance-pct` `<TOLERANCE_PCT>`（默认值为 `10`）	从一份轨迹输出比较配置
`verification` `golden-diff` `check` `<REFERENCE>` `<TRACE>`	两项均必需	`--project`，`--format` `<text\|json\|json-v1>`（默认值为 `text`）	根据参考检查一份轨迹

--tolerance-pct 必须是有限的非负数；负数或非数值会使命令以退出码 2 退出，并报告 tolerance-pct must be a finite non-negative number。

--format 在此处选择引擎自身的输出格式，与 CLI 级别的 --json 封装标志相互独立。两者可以同时使用。

trace

命令	必需项	其他选项	用途
`trace` `inspect` `<TRACE>`	`<TRACE>`	`--project`，`--format` `<json\|text>`（默认值为 `json`）	检查一个轨迹文件
`trace` `timeline` `<TRACE>` `<OUTPUT>`	两项均必需	`--project`	将一份轨迹的时间线视图写入 `<OUTPUT>`
`trace` `export` `<FORMAT>` `<TRACE>` `<OUTPUT>`	三项均必需	`--project`	导出一份轨迹
`trace` `review` `materialize` `<TRACE_ARTIFACT_ID>`	`<TRACE_ARTIFACT_ID>`	`--project`，`--reference` `<REFERENCE_ARTIFACT_IDS>`（可重复指定）	根据所有者存储中的工件标识，生成一个 v1 审核包
`trace` `review` `list`	—	`--project`	最多列出所有者存储中最近五个审核包
`trace` `review` `show` `<PACKAGE_ID>`	`<PACKAGE_ID>`	`--project`	显示一份不含路径的审核包摘要
`trace` `review` `readback` `<PACKAGE_ID>`	`<PACKAGE_ID>`	`--project`	回读一个已验证的审核包

<FORMAT> 在 trace export 中是一个位置参数值枚举，而不是标志，并且位于输入路径之前。可接受的值为 vcd 和 chrome。

--reference 可重复指定，以引用更多参考工件。<TRACE_ARTIFACT_ID>、参考标识及 <PACKAGE_ID> 均可直接以连字符开头，无需使用 --。

注意，alti trace 未带子命令时会进入本地解析器，并以退出码 2 退出，要求提供子命令。因此，嵌入式操作清单中的单词 trace 操作，在此版本中无法从命令行调用；参见 CLI 作业与云端命令。

labs

只读描述符与验证功能。CLI 不提供工作流执行功能。

命令	必需项	其他选项	用途
`labs` `inspect`	—	—	检查固定的编译时工作流描述符目录
`labs` `validate` `<DESCRIPTOR>`	`<DESCRIPTOR>`，`--project` `<ABSOLUTE_WORKSPACE>`	—	验证一个受检查的 JSON 边界健康描述符，但不执行它
`labs` `status`	—	—	输出确定性的 Labs 状态，仅包含描述符

labs validate 严格检查其两个输入，下列所有规则都在引擎启动前验证：

--project 必须是指向真实目录的绝对路径，不能是符号链接。
<DESCRIPTOR> 必须相对于工作区，不能包含 .. 或根组件，且不得超过 4096 字节。
必须使用 .json 扩展名。
必须解析为不超过 1048576 字节的真实普通文件，且解析后的路径仍须位于项目内。

tcl

命令	必需项	其他选项	用途
`tcl` `capabilities`	—	—	报告 Tcl 运行时能力描述符
`tcl` `environment`	—	—	报告 Tcl 运行时环境描述符
`tcl` `commands`	—	—	报告有界命令描述符
`tcl` `readiness`	—	—	返回固定的已签名运行时就绪回执，但不加载 Tcl
`tcl` `evaluate`	—	—	执行从 stdin 读取的有界 Tcl 脚本

前四个命令通过打包的 alti-tcl 引擎根据描述符作答，并输出标准的本地引擎封装。

tcl evaluate 有三点不同。它从 stdin 读取脚本，限制为 4194304 字节，并拒绝空输入。它要求 alti-tcl-local-runner 必须是 alti 的直接同级程序，不允许回退到 PATH，且会根据已安装的信任链检查该程序。0.1.9 引导程序会安装此路径所需的固定签名 Tcl 组件；请使用已安装的二进制程序。此外，它输出自己的回执格式 altifigence.cli.tcl-evaluation.v1，并使用自己的退出码——两者均见 CLI 命令接口。

eidb

命令	必需项	其他选项	用途
`eidb` `capabilities`	—	—	报告 EIDB 边界契约
`eidb` `list`	—	`--project`	列出项目下的包
`eidb` `create`	`--source-artifact-ref` `<WORKSPACE_RELATIVE_ARTIFACT>`	`--project`，`--label` `<LABEL>`	从相对于工作区的工件创建一个归属明确的 R1 包
`eidb` `export`	`--bundle-key` `<BUNDLE_KEY>`	`--project`	生成一个包的便携导出
`eidb` `readback`	`--bundle-key` `<BUNDLE_KEY>`	—	回读一个包
`eidb` `semantic-readback`	`--bundle-key` `<BUNDLE_KEY>`	—	通过语义视图回读一个包

eidb capabilities，eidb readback，以及 eidb semantic-readback 不接受 --project；从 CLI 的角度看，这些命令不包含路径。

physical

共有 42 个子命令。physical run 是一条带有 --runner 的兼容路径；其余均无条件在本地运行，每个命令将其自身子命令名称直接传递给 alti-physical-runner 作为引擎操作。CLI 在此命名空间中的作用是参数准入和回执封装，因此其接口足够规则，可以分为两组。

组别	成员	参数
项目范围的操作	`pdn-stripe-plan`，`optimize-clock-tree`，`optimize-global-route`，`optimize-placement`，`placement-legalize`，`placement-pipeline-manifest`，`placement-pipeline-run`，`placement-seed-grid`，`single-clock-tree`，`two-pin-manhattan-route`，`two-pin-manhattan-route-congestion`，`two-pin-obstacle-route`，`two-pin-obstacle-route-bend-aware`，`multi-net-obstacle-route`，`multi-net-obstacle-route-bend-aware`，`multi-net-uniform-capacity-route`，`multi-net-edge-capacity-route`，`multi-net-congestion-cost-route`，`multi-net-congestion-cost-route-improve`，`multi-net-congestion-cost-route-improve-two-pass`，`multi-net-congestion-cost-route-improve-bounded`	`--project` 即可
条目范围的后续操作	`optimize-detailed-route`，`verify-detailed-route`，`placement-pipeline-analyze`，`placement-pipeline-verify`，`multi-net-route-metrics`，`two-pin-manhattan-route-verify`，`two-pin-obstacle-route-verify`，`multi-net-obstacle-route-verify`，`multi-net-obstacle-route-bend-aware-verify`，`multi-net-uniform-capacity-route-verify`，`multi-net-edge-capacity-route-verify`，`multi-net-congestion-cost-route-verify`，`multi-net-congestion-cost-route-improve-verify`，`multi-net-congestion-cost-route-improve-two-pass-verify`，`multi-net-congestion-cost-route-improve-bounded-verify`	`--entry-id` `<ENTRY_ID>` 为必需项，另加 `--project`

每个条目范围的后续操作都会读取之前某次项目范围操作生成的持久化条目。若省略 --entry-id，会在启动任何操作之前以退出码 2 退出。上述共 36 个，占全部 42 个子命令中的 36 个。其余六个如下：

命令	必需项	其他选项	用途
`physical` `route-evidence-closure` `list`	—	—	列出当前项目下有限数量的已提交标识
`physical` `route-evidence-closure` `read`	`--identity-key-sha256` `<LOWERCASE_SHA256>`	—	重新验证从当前有限列表中选出的恰好一个标识
`physical` `artifact` `store` `<RESULT_JSON_OR_DASH>`	`<RESULT_JSON_OR_DASH>`	`--project`	将一份结果回执持久保存到项目工件存储中
`physical` `artifact` `list`	—	`--project`	列出已存储的条目
`physical` `artifact` `show` `<ENTRY_ID>`	`<ENTRY_ID>`	`--project`	读取一个已存储的条目
`physical` `run`	—	`--runner`（默认值为 `local`），`--project`，`--` `<ENGINE_ARG>...`	原始底层运行器委派的兼容路径

physical route-evidence-closure read 是分两步执行的命令：CLI 先列出已提交标识，要求你的 --identity-key-sha256 出现在该列表中，然后重新读取恰好这一项。若键不是 64 个小写十六进制字符，或不在当前列表中，会在第二步执行前被拒绝，并以退出码 1 退出。列出标识的步骤不包含路径，也不接受 --project。

physical run 若 -- 后没有引擎操作，则不会启动：

文本

$ alti physical run
error: legacy local engine operation is required after `--`

这会以退出码 1 退出。接受的旧版操作为 --capabilities-json，capabilities，以及 execute；其他操作会以退出码 1 退出，并报告 legacy local engine operation ... is not in the public allowlist。

px

px analyze 是一条带有 --runner 的兼容路径。如果位置参数名为 <INPUTS_RELATIVE_...>，则会在项目的 inputs/ 目录下解析，而不是相对于当前工作目录解析。

命令	必需项	其他选项	用途
`px` `capabilities`	—	—	报告 px 能力契约
`px` `fdtd2d` `capabilities`	—	—	打印所有者定义的 FDTD2D 能力契约
`px` `fdtd2d` `readiness`	—	—	报告动态的已安装执行就绪状态，但不获取 CPU 租约
`px` `fdtd2d` `preflight` `<INPUTS_RELATIVE_JSON>`	`<INPUTS_RELATIVE_JSON>`	`--project`	验证 FDTD2D 请求并报告其无法运行的原因
`px` `execute`	—	`--project`	运行打包的 px 执行操作
`px` `static-timing` `<INPUTS_RELATIVE_JSON>`	`<INPUTS_RELATIVE_JSON>`	`--project`	对一个项目输入文件运行有界、非签核级的单时钟静态时序分析
`px` `process-recipe` `<INPUTS_RELATIVE_JSON>`	`<INPUTS_RELATIVE_JSON>`	`--project`	验证并编译一个 `px-recipe-1` JSON 文件的声明顺序计划
`px` `spef-summary` `<INPUTS_RELATIVE_SPEF>`	`<INPUTS_RELATIVE_SPEF>`	`--project`	报告一个有界 SPEF 文件中被动提取的 R/C，不赋予分析权限
`px` `spef-analyze` `<INPUTS_RELATIVE_SPEF>` `<INPUTS_RELATIVE_CONFIG_JSON>`	两项均必需	`--project`	在调用方解析确定的一个工艺角下运行有界、已配置的寄生参数和 IR 压降分析
`px` `readback` `<RUN_ID>`	`<RUN_ID>`	`--project`	回读一次已记录的运行
`px` `artifact` `store` `<RESULT_JSON_OR_DASH>`	`<RESULT_JSON_OR_DASH>`	`--project`	将一份结果回执持久保存到项目工件存储中
`px` `artifact` `list`	—	`--project`	列出已存储的条目
`px` `artifact` `show` `<ENTRY_ID>`	`<ENTRY_ID>`	`--project`	读取一个已存储的条目
`px` `analyze`	—	`--runner`（默认值为 `local`），`--project`，`--` `<ENGINE_ARG>...`	原始底层运行器委派的兼容路径

其中三个命令在各自帮助文本中说明了自身限制，这些限制属于契约的一部分：px static-timing 明确为非签核级，px spef-summary 明确不赋予分析权限，而 px fdtd2d preflight 报告的是就绪阻碍，而非计算结果。请据此解释它们的输出。

与 physical run 类似，px analyze 要求 -- 后带有旧版操作，否则会以退出码 1 退出。其允许列表为 capabilities 和 execute。

PX CPU 与 CUDA 操作

命令	后端与输入
`px` `fdtd2d` `execute` `<INPUT>`	必需项 `--backend`，后端为 `cpu`，`cuda`，或 `auto`；文件路径相对于工作区 `inputs/`
`px` `fft-convolution` `<INPUT>`	采用相同的后端与输入规则
`px` `heat-pinn-jtr`	必需项 `--backend`，后端为 `cpu`，`cuda`，或 `auto`；有界的内置数值测试样例
`px` `hotspot-sensitivity`	采用相同的显式后端策略；有界的内置测试样例
`px` `csr-gmres`	采用相同的显式后端策略；有界的内置测试样例

这些命令接受 --project；前两个也接受 --timeout-ms 1..300000。显式选择 cuda 要求 CUDA 可用且能实际执行。auto 则单独允许引擎记录的 CPU 回退；请检查报告中的后端。这些有界数值操作不能证明通用物理签核能力，也不能证明所有 PX 操作都已获得 GPU 加速。

isa

六个子命令中有四个仅从 stdin 读取 CX 源码。isa run 是一条带有 --runner 的兼容路径。

命令	必需项	其他选项	用途
`isa` `elaborate`	—	—	对从 stdin 读取的 CX 源码进行展开
`isa` `assemble`	`--text` `<TEXT>`	—	依据从 stdin 读取的 CX 源码汇编一条指令
`isa` `disassemble`	`--bits` `<BITS>`，`--bit-len` `<BITS>`	—	依据从 stdin 读取的 CX 源码反汇编一个编码字
`isa` `cosimulate`	—	—	运行有界的 CX 协同仿真投影，源码从 stdin 读取
`isa` `assistant` `verify`	`--check` `<CHECK>`，`--source` `<CX_FILE>`	`--project`	对一个 CX 文件运行一个指定名称的检查
`isa` `run`	—	`--runner`（默认值为 `local`），`--project`，`--` `<ENGINE_ARG>...`	原始允许列表内本地 CX 操作的兼容路径

--check 仅接受 elaboration，static-semantics，encoding-uniqueness，以及 decode-determinism。--bit-len 是 32 位无符号整数。--text 和 --bits 不得为空或仅包含空白字符。

不同于 physical run 和 px analyze，isa run 携带固定的引擎操作，因此没有透传参数也会启动，随后引擎报告自身要求：

文本

$ alti isa run
cx run: run requires --program <path> or --program-text
[failed] isa.run runner=local engine=alti-cx/run executable=alti-cx resolution=path exit=1 project=.

ide

桌面宿主操作。计算仍由上述引擎命名空间负责。

命令	必需项	用途
`ide` `open`	`--project` `<ABSOLUTE_DIR>`	在已安装的 IDE 中打开一个规范的绝对项目目录

ide open 启动另行安装的桌面应用。下述原生工作区、Cloud、服务及项目创建命令通过各自明确的后端工作。

--project 必须是规范的绝对目录：路径为绝对路径，目录已存在，不是符号链接，且路径等于自身的规范形式。经由符号链接解析的路径会被拒绝，而不会静默跟随。

ide open 不使用引擎二进制程序。它先将名为 altifigence-ide 的可执行程序解析为 alti 的同级程序，再从 PATH 中查找，以 --project <canonical-dir> 启动子进程，并输出一份 altifigence.ide-launcher-receipt.v1 回执：

字段	含义
`schema`	始终为 `altifigence.ide-launcher-receipt.v1`
`status`	`spawned`，`unavailable`，或 `failed`
`pid`	子进程 ID，或 `null`
`binary`	始终为 `altifigence-ide`
`project`	规范的项目目录；若规范化失败，则为请求中提供的值
`resolution`	`sibling`，`path`，或 `unresolved`
`executable`	解析后的路径，或不含路径的程序名称
`error`	当 `status` 不为 `spawned` 时的消息，否则为 `null`

退出状态为 0（当状态为 spawned 时），其他情况为 1。altifigence-ide 随 Digital Design Studio 提供，不包含在 CLI 归档中，因此仅安装 CLI 时，ide open 会报告 unavailable。

原生项目与工作区操作

ide init --parent ABSOLUTE_DIR --name NAME 在调用方拥有的规范父目录下创建新的项目骨架，不会覆盖已有项目。ide workspace 对已保存的本地文件操作，无需打开 UI：

后接命令的前缀为 `ide` `workspace`	输入与行为
`capabilities`	报告平台契约
`health` `--project` `ABS`	在公开工作区之前恢复待处理事务
`files` `--project` `ABS` `[--limit` `N]`	有界列出；默认 500 项，上限 20000 项
`read` `--project` `ABS` `PATH`	读取一个允许访问的已保存文本文件
`write` `--project` `ABS` `PATH` `--expected-sha256` `HASH` `--content` `FILE_OR_DASH`	仅在当前 SHA-256 匹配时替换已有文本
`edit` `--project` `ABS` `--request` `FILE_OR_DASH`	替换项数组，包含 `path`，`expected_sha256`，以及 `content` 替换项
`file-plan` `--project` `ABS` `--request` `FILE_OR_DASH`	审核类型化的文件创建、替换、删除或目录创建
`file-apply` `--project` `ABS` `--request` `FILE_OR_DASH`	应用完整的已审核文件计划
`hierarchy-plan` `--project` `ABS` `--request` `FILE_OR_DASH`	审核提取、移动、合并或常量头文件创作
`hierarchy-apply` `--project` `ABS` `--request` `FILE_OR_DASH`	应用完整的已审核层级计划
`settings` `read` `--project` `ABS`	读取持久化的 DDS 项目设置
`settings` `patch` `--project` `ABS` `--request` `FILE_OR_DASH`	递归合并一个有界 JSON 对象

原生计划结果是一个不透明且完整的应用输入。请保存不带全局 --json 的原始引擎输出，审核后，将同一文档传给对应的应用命令。例如，使用已有的绝对项目路径和类型化层级请求：

alti ide workspace hierarchy-plan --project "$PROJECT" \
  --request "$HIERARCHY_REQUEST" > "$PLAN_FILE"
# Review the complete plan and changed source before the next command.
alti ide workspace hierarchy-apply --project "$PROJECT" --request "$PLAN_FILE"

请勿将失败命令的输出通过管道传给应用命令。请选择新的计划文件，并检查每次退出状态。文件创作使用持久、串行化的事务及当前源码哈希；这不意味着面对无关写入方时整个文件系统能够瞬间原子更新。发生冲突需要重新审核。层级创作是有界的源码选择与骨架生成，不是完整的 SystemVerilog 语义重构，也不能证明等价性。

设置保留 DDS 的 .alti/ide-settings.json 格式、未知键及字面 null 值。补丁采用递归合并，不采用 RFC 7396 的删除语义。请求和结果的大小预算为 256 KiB，深度上限为 8；原生 UI 与 CLI 使用同一 .alti/.ide-settings.lock。CLI 处理当前项目格式，不提供另一个独立的桌面全局设置范围。

原生事务与 Git 需要 Linux 契约。当前恢复机制读取 V1 和 V2 日志。创建、删除或层级应用操作中断后，请先运行新版 CLI 的 health，再打开仅支持 V1 的旧 DDS 后端。旧后端会拒绝待处理的 V2 日志，并保留日志。正常完成的事务会清除活动日志；建议升级到支持透明恢复的后端，但这不是每次已完成 CLI 编辑的前提。

Git

在 ide workspace git 下，所有命令均接受 --project ABS:

命令	附加参数
`status`，`refs`，`worktrees`	无
`history`	可选项 `--limit` `1..200` 和 `--skip` `0..100000`
`commit-detail`	提交 ID
`commit-file`	提交 ID 和相对路径
`diff`	相对路径，可选 `--staged`
`stage`，`unstage`	1–128 个相对路径
`commit`	`--message` `TEXT`
`switch`	已有本地分支；拒绝脏工作区以及不受支持的属性或过滤器行为

这些操作会先恢复原生工作区事务，并与之串行化。它们不提供任意 Git 参数、钩子或远程推送凭据。

已保存源码搜索

alti ide workspace search --project "$PROJECT" --query 'module' --limit 80

原生搜索支持 --match-case，--whole-word、保守的固定宽度 --regex、1–500 条匹配的限制，以及 --timeout-seconds 1..120。它通过原生 files/read 边界读取已保存文本，预算为 500 个文件、每个文件 4 MiB、总计 16 MiB，以及 1 MiB 输出。请检查截断情况和内容依据。未保存的编辑器缓冲区不参与搜索。Cloud 搜索及旧版 HTTP 搜索/替换属于独立的服务操作。

xls

命令	请求与用途
`xls` `capabilities`	报告原生子集及后端可用性
`xls` `check`，`eval`，`optimize`，`codegen`	必需项 `--request` `FILE_OR_DASH`，可选项 `--project`；原生操作 JSON，最多 16 KiB
`xls` `run`	相同标志与大小限制；使用 XLS EngineJobV1 封装，具有显式的本地放置与设备策略
`xls` `artifact` `store`	`--request` `FILE_OR_DASH`，可选项 `--project`
`xls` `artifact` `list`，`xls` `artifact` `show` `ID`	可选项 `--project`；有界的存储结果及回读
`xls` `upstream` `install`	必需的新绝对路径 `--destination` 和 `--toolchain-config`；可选的原始固定版本 `--archive`
`xls` `upstream` `capabilities`	必需的绝对路径 `--toolchain-config`；报告实际已安装的工具覆盖情况
`xls` `upstream` `run`	必需项 `--toolchain-config`、已有的 `--work-root`，以及 `--request` `FILE_OR_DASH`；请求上限为 2 MiB

原生路径支持有界的 DSLX 与 XLS IR 函数，数值宽度为 1–64 位，支持常量折叠和死代码删除，以及组合 RTL 或具有 1–16 级输出寄存器的 RTL。请求选择 cpu，或者为受支持的批量求值显式选择 cuda。CUDA 后端不可用时会报错，不会自动改用 CPU。请先运行 CPU 示例。

独立的上游路径安装固定版本的公开 Google XLS Linux 工具链，验证其归档及工具/标准库清单，并保留许可证文件。所选上游工具支持请求的操作时，它支持导入、参数化、结构体、枚举、聚合类型、任意位宽类型及 proc。它不使用有界的 bits64 解析器，也不会用 CUDA 加速整个 Google 工具链。

上游请求可选择 check，eval，convert，optimize，或 codegen。未显式提供向量或 tick 的 DSLX eval 会运行实际模块测试；执行零个单元测试不算成功。基础归档不含独立的 IR/proc 求值器可执行程序。显式向量或通道 tick 需要额外的已验证求值器包，在安装时通过 --evaluator-bundle 和 --evaluator-manifest-sha256 准入。请求这些操作前，请检查能力。上游流水线代码生成支持 1–64 级；单位延迟调度不是经过表征的硅片时序。

compute

命令	用途
`compute` `capabilities`	发现设备，但不运行 GPU 内核
`compute` `rtl-capabilities`	检查打包 RTL 执行契约
`compute` `rtl-simulate` `--request` `FILE_OR_DASH`	有界的组合 RTL 执行，显式选择 `cpu` 或 `cuda`
`compute` `rtl-evolve` `--request` `FILE_OR_DASH`	有界的原生生成请求，显式选择 `cpu-reference` 或 `cuda` 活动后端
`compute` `rtl-verify` `--request` `FILE_OR_DASH`	验证已存储的打包 RTL 结果，但不加载 CUDA

请求命令接受 --project。仿真/Evolve 输入上限为 4 MiB，verify 输入上限为 16 MiB。打包的 alti-rtl-cuda 负责此路径。compute rtl-evolve 接受 altifigence.rtl.evolve-request.v1，其中已有的原生生成请求嵌套在 request 下；它不是 evolve run 操作封装。

Evolve CUDA 计算有界的组合活动诊断。候选生成、正确性检查、综合及目标评估仍在 CPU 上执行。宿主工具配置必须提供实际的 Icarus iverilog 和 vvp。cpu-reference 要求 cuda_timeout_ms: 0 和 device_memory_bytes: 0；cuda 会在执行不可用时拒绝请求，而不会回退。请使用新的 request.run_dir，其父目录须已存在。

请求将代数和子代数限制为 1–16，岛数限制为 1–4，计划评估总数限制为 256，LLM 子代数限制为零。设备内存是有界的工作器缓冲区预算，并非驱动总内存的限制。可选的本地 cancel_file 和截止时间支持协作式取消；原生工具调用仍受各自限制。成功的 CUDA 结果需要实际已接受候选的活动数据和已存储的硬件来源记录，仅有设备发现或初始探测不够。CPU/CUDA 功能一致并不能证明提速。

当前下载版本缺少的命令

此前未包含的 eda 和 reports 命名空间现在已有路由：

命令	输入
`eda` `inspect`	`--project` `ABS` `--format` `FORMAT` `PROJECT_RELATIVE_INPUT`
`eda` `sdc-bind`	`--project` `ABS` `--constraints` `PATH` `--logic-netlist` `PATH`
`eda` `artifact` `store`，`reports` `artifact` `store`	`--input` `RECEIPT_JSON`，可选项 `--project`
`eda` `artifact` `list`，`reports` `artifact` `list`	可选项 `--project`
`eda` `artifact` `show`，`reports` `artifact` `show`	`--entry-id` `SHA256`，可选项 `--project`
`reports` `parse`	请查看末级子命令帮助，了解类型化报告格式和有界输入

这些是有界的检查、解析或绑定操作，不是通用 EDA 工具执行。ide init 与显式的原生 Evolve 命令也可使用。前述未随版本交付的 alti-rtl-runner 兼容路径仍是独立限制；请勿仅凭帮助文本推断支持情况。

准备引擎工作流

选择操作，阅读已安装程序的能力响应和末级子命令帮助。
在所选项目中创建一个小型已保存输入，并明确其顶层/模块或入口点。
提供所需外部工具；若请求支持 CPU/CUDA 选择，请使用明确的后端。
在有界资源条件下运行一次，并保留诊断信息与完整原生结果。
构建更大的工作流之前，检查实际后端、输入、输出工件及不受支持的指标。

请参阅 DDS 分析了解图形工作流，并参阅 Evolve 了解候选比较。CLI 引擎支持、桌面面板与 Cloud 路由是不同的集成；请检查你实际要使用的工作流。