CLI 自动化与 CI

配置经过验证的 CLI 安装，自动执行有界本地工作、保存回执，并明确检查后端。

概述

配置经过验证的 Linux 安装后，以普通作业用户身份，在全新工作区中运行设计工作。将安装权限与源文件处理分开。本页使用 CLI 0.1.9 安装契约；请通过下载选择实际可用的发布版本。

准备门槛

  1. 固定工作流程接受的确切版本、归档名称和签名目录清单。

  2. 执行任何下载的二进制文件之前，请遵循验证下载文件流程，验证公钥 DER 固定值、已签名校验和清单、归档签名和目录清单签名。

  3. 请参阅在 Linux 上安装。内嵌引导程序会创建已签名的目录布局及固定 Tcl 组件，无需检出仓库、构建或访问网络。仅在管理员控制的步骤中安装。

  4. 运行确切的已安装 PREFIX/bin/alti，并保留其版本和功能报告。不要替换为开发二进制文件或未经验证的 PATH 运行器。

存在归档和帮助输出并不能证明安装已就绪。针对打算运行的操作，检查 alti capabilities 及功能响应。检查失败时应停止该操作，不应启用后备方案。

离线 CI 示例

准备 job.json 及其仅限所有者访问的源文件，具体步骤参阅 CLI 首次成功运行。将 ALTI_BIN 设置为确切的已验证安装，将 ALTI_WORKSPACE 设置为此作业已准备好的工作区：

Bash
set -euo pipefail
ALTI_BIN="${ALTI_BIN:?set the verified absolute installed alti path}"
ALTI_WORKSPACE="${ALTI_WORKSPACE:?set the private prepared workspace}"
case "$ALTI_BIN" in /*) ;; *) exit 1 ;; esac
EVIDENCE="$(mktemp -d)"

"$ALTI_BIN" version > "$EVIDENCE/version.txt"
"$ALTI_BIN" capabilities > "$EVIDENCE/capabilities.json"
"$ALTI_BIN" commands > "$EVIDENCE/commands.json"
"$ALTI_BIN" --json job validate \
  --job "$ALTI_WORKSPACE/job.json" \
  --workspace-root "$ALTI_WORKSPACE" \
  --source rtl/top.sv \
  > "$EVIDENCE/preflight.json" 2> "$EVIDENCE/preflight-error.json"

jq -e 'length == 25' "$EVIDENCE/commands.json" >/dev/null
jq -e '
  .receipt_schema == "altifigence.cli.engine-job-preflight.v1" and
  .status == "client_preflight_valid" and
  .submitted == false and
  .server_authority_verified == false
' "$EVIDENCE/preflight.json" >/dev/null

此步骤检查的是预检，而非 RTL 执行。工作流程需要执行结果时，应明确添加 CPU XLS 求值或其他有界本地引擎操作。这些本地检查无需 Cloud 凭据。

功能与输出规则

  • 解析预期的命令专属模式之前，先检查进程退出状态。

  • 保持 stdout 和 stderr 分离。使用 --json 时，从封装的 stdout 解析引擎输出；对于 DDS plan/apply 管道，应保存原始原生结果。

  • 使用全新的工作区或运行目录。应用前检查完整的编写计划；发生冲突后应重新生成，不要替换其哈希值。

  • 明确使用 cpu/cuda 或 Evolve 的 cpu-reference/cuda 策略。XLS 和打包 RTL 不会静默回退。PX 的 auto 是独立的自愿启用策略，应从回执中读取实际后端及回退情况。

  • 单独安排 GPU 资格验证，并配备所需驱动和 Icarus 工具。要求实际被接受的 CUDA 工作和已存储的硬件来源信息；仅发现硬件并不充分。不要从功能测试推断性能。

  • Cloud 写入需要账户/项目权限，以及该操作明确的上传同意。旧版 HTTP 替换需要该服务提供的新哈希值；409 表示冲突，不是使用较弱检查重试的许可。

保留证据

保留经过验证的目录清单/签名、已安装二进制文件摘要、CLI 版本、已脱敏参数、输入摘要、退出状态，以及有界的结果/诊断输出流。GPU 记录还需要实际设备/驱动和外部工具身份信息。开发或调试证据应与签名安装包资格验证分别处理。避免不必要地保留凭据或项目源文件。

保持 CI 可重复

  1. 在运行器配置中固定经过验证的发布版本和外部工具链版本。

  2. 为每个作业使用新的用户所有源目录和新输出路径。

  3. 运行功能检查，以及适合所请求操作的小规模实际执行。

  4. 出现非零退出、格式错误输出、过期源文件身份信息或缺失必需产物时，让流水线失败。

  5. 保留有界诊断和摘要；通过 CI 秘密信息存储轮换凭据，不要放入已保存日志。

按版本和摘要缓存经过验证的安装输入或不可变工具链。不要将项目结果、会话文件和提供商凭据放入共享缓存。远程工作需要独立的明确授权和作业跟踪；本地 CI 通过不意味着 Cloud 工作已运行。