CLI 命令参考 — Altifigence Documentation

概览

完成验证和安装后使用已安装二进制文件。本参考区分命令发现、执行结果、预检凭据和服务响应。

操作清单

成功时输出一个 JSON 数组。每个条目包含name、description、inputSchema、executes以及class。内置客户清单包含 25 个操作，其中 22 个具有executes: true。altifigence.analyze.run、altifigence.evolve.launch以及altifigence.verify.run仅用于规划。原生 CLI 子命令在客户清单之外提供各自的具体子命令帮助。服务器响应决定服务操作是否已授权且就绪。

使用具体子命令帮助查看原生参数：

alti commands

alti xls upstream run --help
alti compute rtl-evolve --help
alti ide workspace hierarchy-plan --help
alti ide cloud search --help
alti ide service workspace replace --help

离线作业预检

按照CLI 首次成功运行准备源文件和封装对象，然后运行：

成功结果的 schema 为altifigence.cli.engine-job-preflight.v1。submitted: false和server_authority_verified: false为必需字段：源文件哈希和作业结构已在本地检查，但未提交或执行任何作业。封装对象请求的execution_placement不会改变这一事实。

alti --json job validate \
  --job "$ALTI_WORKSPACE/job.json" \
  --workspace-root "$ALTI_WORKSPACE" \
  --source rtl/top.sv

JSON 错误契约

失败的--json job validate不会向 stdout 写入成功凭据，而会向 stderr 输出一个altifigence.cli.error.v1对象：

可用时使用error.code。其他命令族有各自的错误 schema；不要假定这个封装适用于所有 CLI 命令。

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

退出状态

状态	含义
`0`	所选命令已完成；阅读结果以确定其报告的是就绪情况、预检、计划还是执行
`1`	CLI 运行时、验证、传输或安装失败；服务失败可能包含 HTTP 响应
`2`	参数无效，或请求在传输/引擎启动前被拒绝；引擎也可能返回此状态
`3`	客户清单路径上的保留类别拒绝；引擎可能赋予同一数字不同含义
`4`	客户清单拒绝，包括不可用的顶层登录/身份或缺少源文件上传授权
`126`	引擎启动或安装认证失败
`127`	所需引擎可执行文件不可用
其他非零值	可能是原样传递的子引擎自身状态

解析 stdout 前始终检查退出状态，并单独保留 stderr。空文件或不完整输出文件不是成功结果。保存的计划不是已应用事务，服务器接受也不是作业完成。

引擎命令：实际运行的内容

XLS、compute 和原生 DDS 适配器使用固定打包的同级程序。已安装执行根据签名发布记录认证相关运行器；将其他可执行文件加入PATH不能修复缺失的必需同级程序。部分旧版兼容命令保留其文档规定的解析行为。参阅命令接口。

不使用--json时，引擎 stdout 直接转发，因此可直接保存不透明的原生计划。使用--json时，引擎调用通常生成altifigence.local-engine-execution.v1；其stdout和stderr字段以字符串包含子进程输出流。请单独解析内部结果。

对于文件和层次结构计划，将完整原生计划结果传给对应 apply 命令。不要传入外层 CLI 封装或仅传计划摘要。原生后端验证当前文件哈希及事务条件。

服务与流式输出

ide service返回altifigence.dds.service-receipt.v1，包含operation、ok、httpStatus及限定大小的响应body。替换操作返回的 HTTP409仍然是冲突，不会重试。成功 DELETE 的空响应保持为空，不会伪造成服务器 JSON 对象。

原生 DDS 搜索和 Cloud 搜索分别提供自己的匹配/内容证据。请使用将要写入的后端提供的身份；为另一搜索后端计算的哈希不会自动成为有效 CAS 令牌。

ide cloud terminal向 stdout 流式输出终端字节，向 stderr 输出连接状态。即使使用全局--json，它也不是单一 JSON 凭据。请限定连接时长，并在计划重新连接时保留游标。

--json release install和--json release uninstall输出altifigence.cli.release-bootstrap.v1，包含operation、ok以及exitCode。安装程序诊断输出到 stderr。验证或权限失败可能发生在成功封装产生之前。

为自动化捕获结果

每次调用选择新的输出目录。分别保存 stdout 和 stderr，立即捕获退出状态，并且仅在退出码为零后解析成功 schema。对于引擎封装，仅在命令契约说明其内容为 JSON 时，将其中的stdout字符串作为原生文档解析。

对于 plan/apply 工作流，保留完整原始原生计划，并使用同一项目。apply 前审阅受影响文件和当前哈希。冲突需要重新读取和审阅计划，而不是放弃哈希检查的理由。参阅自动化与 CI了解可复现的本地检查。