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 首次成功準備來源與封套，再執行：

成功結構描述為 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。其他命令系列各有錯誤結構描述；不要假設此封套適用於所有 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。替換傳回的 HTTP 409 仍屬衝突，不會重試。成功 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，立即擷取結束狀態，只有結束碼為零後才解析成功結構描述。對引擎封套，只有命令契約明定包含 JSON 時，才將其 stdout 字串解析為原生文件。

對計畫／套用工作流程，請保留完整原始原生計畫，並使用相同專案。套用前審查受影響檔案與目前雜湊。衝突代表需重新讀取並審查計畫，不是移除雜湊檢查的理由。可重現的本機檢查請參閱自動化與 CI。