Perintah tugas dan cloud CLI

Ringkasan

Halaman ini membahas transport tugas, sesi Cloud DDS native dan operasi workspace, adaptor layanan HTTP lama yang eksplisit, serta 25 aksi manifes pelanggan. Operasi Evolve native memiliki kontrak permintaan tersendiri.

Baca Cakupan perintah CLI terlebih dahulu untuk aturan perutean, dua kelompok kode keluar, dan pembungkus bukti hasil. Untuk namespace engine yang diparsing secara lokal, lihat Perintah engine CLI. Untuk batasan rilis saat ini, lihat Referensi perintah CLI, dan untuk cara membaca manifes, lihat Kontrak aksi dan kemampuan.

Namespace job

job mencakup pemeriksaan awal klien secara offline serta transport tugas ke Job Service. Ini ditangani parser lokal, sehingga -h berfungsi dan rentang nilai diperiksa sebelum menghubungi apa pun.

Enam dari delapan subperintahnya menerima --runner <local|cloud|private>, dengan default cloud. Flag tersebut memilih Job Service yang akan dihubungi. Ini bukan flag runner engine pada rtl compile dan perintah sejenisnya. job readiness dan job validate sama sekali tidak memiliki --runner dan tidak pernah mengakses jaringan.

<JOB_ID> dan --artifact-id boleh diawali tanda hubung tanpa memerlukan pemisah --; parser menerima nilai dengan tanda hubung di awal untuk argumen ini.

Dua opsi dengan pemeriksaan rentang pada job wait ditegakkan parser, bukan layanan:

Teks

$ 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

Hasilnya keluar dengan kode 2.

job readiness

job readiness menjawab tanpa kredensial atau jaringan. Dalam rilis ini, responsnya berupa proyeksi tetap tanpa jalur: setiap komponen melaporkan configured: false dan ready: false, dan larik blockers berisi seluruh komponen.

{
  "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"
  ]
}

Perintah keluar dengan kode 0. Nilai 0 di sini berarti pertanyaan kesiapan telah dijawab, bukan berarti ada komponen yang siap.

job validate

job validate adalah pemeriksaan awal offline yang dijelaskan langkah demi langkah dalam Keberhasilan pertama CLI. Perintah membaca dokumen EngineJobV1 dari --job (atau stdin ketika --job adalah - atau tidak diberikan), memeriksanya terhadap pembungkus klien RTL CPU Cloud yang persis, dan menghitung hash satu file sumber lokal. Perintah tidak mencari kredensial, membuat klien, atau menghubungi apa pun.

Skema bukti hasilnya adalah altifigence.cli.engine-job-preflight.v1. Jika berhasil, status adalah client_preflight_valid, submitted adalah false, server_authority_verified adalah false, job_schema adalah altifigence.engine.job.v1, execution_placement adalah cloud, blok operation bernilai rtl-engine / analyze / rtl-analysis-request.v1, dan larik source memuat workspace_uri, sha256, dan size_bytes.

Dokumen tugas dibaca dengan batas tegas 8388608 byte. Jika melebihi batas, perintah gagal dengan EngineJobV1 JSON exceeds the CLI limit.

Pengiriman Cloud memerlukan persetujuan eksplisit untuk sumber

Dengan --runner cloud, baik job submit dan analyze run memerlukan ketiga opsi unggah sumber secara bersamaan. Dalam rilis ini, tugas RTL CPU Cloud tidak dapat dikirim tanpa ketiganya:

Teks

$ alti job submit --job job.json
error: Cloud Engine Job source upload is disabled; pass --allow-source-upload explicitly.

Hasilnya keluar dengan kode 1. Dengan --allow-source-upload tanpa --workspace-root, pesannya adalah --workspace-root is required with --allow-source-upload., dan demikian pula untuk --source.

--workspace-root harus absolut. --source adalah jalur relatif portabel di bawah <workspace-root>/inputs.

Unduhan artefak Cloud memerlukan persetujuan tersendiri

Pada job result dengan --runner cloud, ketiga opsi artefak merupakan satu kelompok. Memberikan salah satunya mengalihkan perintah ke mode unduhan, yang kemudian memerlukan ketiganya:

• Tanpa --allow-artifact-download: Cloud Engine Job artifact download is disabled; pass --allow-artifact-download explicitly.

• Tanpa --artifact-id: --artifact-id is required with --allow-artifact-download.

• Tanpa --output-dir: --output-dir is required with --allow-artifact-download.

--output-dir harus berupa direktori absolut. --artifact-id berasal dari daftar output EngineResultV1.

Penolakan berdasarkan lingkup runner

Tiga kelompok opsi dibatasi untuk runner tertentu dan ditolak di luar runner tersebut. Masing-masing diputuskan sebelum proses apa pun dimulai atau permintaan apa pun dibuat:

Jalur lokal/privat lama menyebut adaptor alti-engine-job yang telah dihentikan dan tidak ada dalam inventaris rilis 24 runner. Sintaks runner dan variabel endpoint yang diterima tidak membuktikan adanya Job Service lokal/privat yang telah dikirim. Gunakan jalur Cloud bawaan hanya jika layanan dan akun telah diaktifkan, atau gunakan perintah engine lokal langsung yang terdokumentasi.

Kesalahan tugas yang dapat dibaca mesin

jobSubperintah analyze run yang dipanggil dengan --json menghasilkan pembungkus kesalahan terstruktur saat gagal, bukan pesan biasa:

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

Daftar kode lengkapnya adalah:

retryable adalah false untuk semuanya dalam rilis ini. Pembungkus ini dihasilkan untuk namespace job dan analyze run. Keluarga perintah lain memakai kontrak kesalahan/bukti hasil masing-masing; lihat Referensi Perintah.

analyze run dan evolve run

analyze run dan subperintah Evolve native eksplisit mencapai parser lokal. Aksi pelanggan satu kata analyze dan evolve memiliki kontrak terpisah.

analyze run menerima kumpulan opsi yang sama dengan job submit dan mengikuti aturan unggah sumber Cloud yang sama. Ada satu perbedaan: perintah menerima --runner tetapi menolak nilai apa pun selain cloud.

Teks

$ alti analyze run --runner local --job job.json
error: Local and Private job service adapters are not available; use --runner cloud.

Hasilnya keluar dengan kode 1.

evolve run tidak memiliki --runner, --project, atau argumen penerusan. Perintah membaca satu dokumen permintaan — --request - membaca stdin — dan meneruskannya ke engine alti-evolve dalam paket, dengan status keluar yang diteruskan apa adanya:

Teks

$ echo '' | alti evolve run --request -
alti-evolve: invalid request JSON: EOF while parsing a value at line 1 column 0

Nilai 2 adalah alti-evolve tersebut adalah status keluar engine itu sendiri yang diteruskan, bukan kesalahan argumen CLI. Pada instalasi yang tidak dapat menemukan engine, perintah yang sama keluar dengan kode 127 dengan bukti hasil yang memiliki status adalah unavailable.

evolve capabilities, evolve analyze, evolve cx-search, evolve measured-ppa, dan evolve artifact juga telah dirutekan. Misalnya, evolve analyze SAVED_RTL --top TOP [--project ABS] menganalisis sumber tersimpan. Penerimaan/kesiapan/pemeriksaan awal measured-PPA tidak menghasilkan PPA terukur.

Operasi aktivitas GPU publik adalah compute rtl-evolve --request FILE_OR_DASH. Operasi ini memiliki pembungkus generasi native terpisah serta kebijakan CPU referensi/CUDA eksplisit. Lihat Perintah Engine alih-alih meneruskan permintaan evolve run ke operasi tersebut.

Digital Design Studio Cloud

Gunakan ide cloud login, lalu ide cloud whoami untuk memverifikasi identitas sesi native. refresh dan logout mengelola sesi tersebut; --session-dir memilih alternatif privat untuk default. Lihat Autentikasi CLI.

ide cloud contract --request FILE_OR_DASH memvalidasi permintaan proyek/anggota/sumber/workspace bertipe secara offline. ide cloud run --request FILE_OR_DASH mengirim permintaan tersebut melalui API native menggunakan sesi tersimpan. Permintaan yang memuat sumber memerlukan --allow-source-upload. Validasi kontrak tidak pernah memberikan akses organisasi atau menggantikan izin terkini layanan.

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

Gunakan UUID organisasi/proyek nyata yang telah diotorisasi. Pencarian menerima --match-case, --whole-word, pola --regex, --limit 1..500, dan --timeout-seconds 1..120 berlebar tetap yang konservatif. Pencarian memakai rute files/read dengan lingkup yang sudah ada dan konten tersimpan, dengan anggaran 500 file, 4 MiB/file, total 16 MiB, dan output 1 MiB. Perubahan manifes/header/generasi membatalkan snapshot campuran. Nilai contentHash yang dikembalikan menghitung hash teks UTF-8 persis yang dibaca dan, untuk pemilik Cloud saat ini, harus sama dengan fileVersion. Pertahankan fileVersion dan workspaceRevision sebagai kolom CAS terpisah.

Penyambungan terminal mempertahankan transport WebSocket dan otorisasi terkini. Byte stdout dialirkan; status dikirim ke stderr, bahkan dengan opsi global --json. Gunakan --cursor untuk melanjutkan, --cols 2..500, --rows 1..200, dan --max-seconds 1..300 untuk membatasi penyambungan. Melepas sambungan bukan permintaan untuk menghentikan PTY persisten. Ini adalah eksekusi proyek Cloud, bukan shell CLI lokal.

Layanan Workspace DDS Lama

ide service menargetkan pemilik workspace HTTP lama yang dikonfigurasi secara eksplisit. Tetapkan --endpoint atau ALTI_STUDIO_ENDPOINT dan ALTI_STUDIO_SERVICE_SECRET yang sudah ada dalam lingkungan privat pemanggil. Tidak ada penggantian dengan sesi Cloud native, cookie browser, atau penerusan URL/body bebas. Ini menjelaskan adaptor layanan lama, bukan klaim bahwa UI desktop native saat ini memakai endpoint tersebut atau bahwa layanan produksi publik telah diaktifkan.

Pencarian menerima --match-case, --whole-word, pola --regex, dan --limit 1..1000 (default 80). Penerimaan regex sengaja hanya menerima subset sintaks JavaScript pemilik; grup, alternasi, dan penguantifikasi ditolak. Pencocokan backend tetap menjadi tanggung jawab layanan.

Penggantian menerima objek JSON tertutup dengan query, replacement, paths: [one portable path], dan expectedHashes: {same path: 64 hex digits} yang wajib. Opsi options hanya berisi boolean matchCase, regex, dan wholeWord yang wajib. Opsi match berisi path yang sama serta bilangan bulat berbasis satu line/column antara 1 dan 4194305. Jangan berikan match untuk mengganti dalam file yang dipilih, bukan seluruh workspace. Dapatkan hash dari hasil terkini layanan yang sama ini.

Permintaan maksimal 64 KiB, termasuk pengodean JSON dan teks pengganti. Kolom tidak dikenal, kunci/jalur hash yang tidak cocok, indeks tidak valid, traversal, tautan di luar batas server, serta metadata yang dilindungi/jalur yang dikecualikan dari pencarian tidak didukung. CLI menolak bentuk tidak valid dan jalur yang dilindungi sebelum HTTP; kepemilikan sistem file dan pemeriksaan tautan tetap berada pada layanan. Perintah tidak pernah melakukan penggantian workspace lokal.

Respons dibatasi hingga 8 MiB. --timeout-seconds 1..3600 menetapkan tenggat HTTP keseluruhan (default 30); pengalihan dan percobaan ulang otomatis dinonaktifkan. altifigence.dds.service-receipt.v1 mempertahankan status HTTP dan body, termasuk respons DELETE berhasil yang kosong. 409 tetap merupakan konflik. CAS dan atomisitas backend bukan jaminan lintas backend, dan hash konten lokal/Cloud tidak boleh menggantikan hash yang diharapkan layanan itu tanpa kontraknya.

Manifes Aksi

Semua yang tidak ditangani parser lokal diteruskan ke dispatcher manifes, yang mencocokkan jalur perintah Anda dengan customer-tools.v1.json. alti commands mencetak seluruh manifes sebagai satu larik JSON berisi dua puluh lima entri dan keluar dengan kode 0 tanpa kredensial.

Dua puluh dua entri ditandai executes: true. Tiga — analyze, evolve, dan verify — berstatus executes: false dan mencetak catatan [plan-only] sebelum diteruskan. Tiga aksi yang sama itu adalah satu-satunya yang membawa byte sumber, dan aksesnya memerlukan --allow-source-upload.

Empat belas dari dua puluh lima juga membawa profil remote_core; sisanya hanya local_extended. Arti profil tersebut bagi ketersediaan dibahas dalam Kontrak aksi dan kemampuan.

Setiap aksi di bawah membaca ALTI_TOKEN dan ALTI_ORG_ID dari lingkungan proses sebelum membuat klien, dan gagal dengan kode keluar 1 jika salah satunya tidak ada:

Teks

$ alti credits
Config error: ALTI_TOKEN is not set (org API key or access token).

Opsi yang sama untuk aksi pencantuman

Beberapa aksi memakai bentuk paginasi yang sama: --limit <INTEGER> dalam rentang 1..=100, dan --cursor <STRING>. Keduanya divalidasi secara lokal sebelum permintaan apa pun:

Teks

$ alti project ls --limit 101
Invalid value for --limit: outside allowed range.

Hasilnya keluar dengan kode 2, begitu pula flag yang tidak dikenal (Unknown option(s): --limti), opsi wajib yang tidak diberikan (Missing required option(s): --projectId), dan nilai di luar enumerasi (Invalid value for --visibility: expected one of public, private.).

Workspace dan proyek

RTL percakapan

chat models dicocokkan sebelum chat, karena dispatcher memilih jalur perintah cocok yang paling panjang. alti chat dibatasi kredit dan dicatat dalam audit pada sisi server.

Aksi estimasi dan perencanaan saja

--rtl dan --testbench adalah string sumber inline dengan batas tegas masing-masing 1048576 byte, diperiksa secara lokal:

Teks

$ alti analyze --target kv260-fpga --rtl "$(cat huge.sv)" --allow-source-upload
Invalid value for --rtl: exceeds size limit.

Hasilnya keluar dengan kode 2. Tanpa --allow-source-upload, salah satu dari ketiganya keluar dengan kode 4 sebelum klien dibuat:

Teks

Source upload is disabled by default. Re-run with --allow-source-upload only
after reviewing the destination and input.

Ketiganya berstatus executes: false, sehingga meski persetujuan diberikan, ketiganya mencetak catatan [plan-only] ke stderr dan server mengembalikan rencana penerusan terstruktur, bukan eksekusi.

Artefak, bukti, runner, dan penagihan

Registri MCP

Aksi ini membaca registri alat MCP yang diumumkan server dan daftar yang diizinkan per organisasi. Aksi ini tidak terkait dengan alti mcp serve, yang dicegat sebelum kedua dispatcher dan memulai server stdio lokal. Lihat MCP.

Satu aksi manifes tidak dapat dijangkau

Manifes menetapkan aksi satu kata trace untuk ringkasan trace. Aksi itu tidak dapat dipanggil, karena trace telah diambil parser lokal sebagai namespace engine. alti trace mencapai parser lokal, tidak menemukan subperintah, dan keluar dengan kode 2; alti trace --limit 5 juga mencapai parser tersebut dan keluar dengan kode 2 karena argumen tidak dikenal.

Aksi itu tetap ada dalam output alti commands, sehingga jumlah di sana adalah dua puluh lima, sedangkan jumlah perintah yang dapat dijangkau adalah dua puluh empat. Jika Anda mengenumerasi manifes secara terprogram, saring aksi ini.

Memilih alur kerja Cloud

Jangan menggunakan kembali ID, hash, atau bukti hasil dari alur kerja lain kecuali kontraknya menerima secara eksplisit. Terminal yang tersambung kembali tetap merupakan sesi jarak jauh yang sudah ada; balasan pengiriman yang hilang tetap berarti tugas mungkin sudah ada. Periksa status sebelum membuat duplikat.