CLI 作業與雲端指令

概觀

本頁介紹作業傳輸、原生 DDS Cloud 工作階段與工作區操作、明確指定的舊版 HTTP 服務配接器，以及 25 個客戶資訊清單動作。原生 Evolve 操作具有獨立的請求契約。

請先閱讀 CLI 指令介面，以瞭解路由規則、兩組結束代碼與回執封套。若要瞭解本機解析的引擎命名空間，請參閱 CLI 引擎指令。目前版本的限制請參閱 CLI 指令參考；資訊清單的解讀方式請參閱 動作與能力契約。

job 命名空間

job 包含離線用戶端預檢，以及對 Job Service 的作業傳輸。它由本機解析器處理，因此 -h 可正常使用，且在聯絡任何服務前會檢查值的範圍。

八個子指令中的六個接受 --runner <local|cloud|private>，預設為 cloud。該旗標選擇要聯絡哪個 Job Service。它不是 rtl compile 及相關指令上的引擎 runner 旗標。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 是 - 或省略時，則從標準輸入讀取），對照精確的 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 的輸出清單。

Runner 範圍的拒絕條件

三組選項限定於特定 runner，在其範圍外會遭拒。這些判斷都在啟動任何程序或發出任何請求前完成：

較舊的 local／private 路徑指定了已退役的 alti-engine-job 配接器，它不在此版本 24 個 runner 的清單中。runner 語法與端點變數被接受，並不代表已交付 local／private 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 - 會讀取標準輸入——並派送至封裝的 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] 會分析已儲存的原始碼。Measured-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] 提示，而且伺服器會傳回結構化派送計畫，不會執行。

成品、證據、runner 與計費

MCP 登錄

這些指令讀取伺服器公告的 MCP 工具登錄與各組織允許清單。它們與 alti mcp serve 無關；後者會在任一派送器之前被攔截，並啟動本機 stdio 伺服器。請參閱 MCP。

有一個資訊清單動作無法存取

資訊清單定義了單一字詞的 trace 動作，用於追蹤摘要。但它無法被呼叫，因為 trace 已被本機解析器作為引擎命名空間接管。alti trace 會進入本機解析器，找不到子指令，並以 2 結束；alti trace --limit 5 也會進入本機解析器，並因未知引數以 2 結束。

該動作仍會出現在 alti commands 輸出中，因此該處的數量是 25，而實際可存取的指令數量為 24。若以程式列舉資訊清單，請篩除這個動作。

選擇 Cloud 工作流程

除非契約明確接受，否則不要重用其他工作流程的 ID、雜湊或回執。重新連線的終端機仍是原本的遠端工作階段；遺失提交回覆時，作業仍有可能已存在。建立重複項目前，請先檢查狀態。