← Dokumentasi

Otomasi & CI

Tiga mode non-interaktif

Bentuk · Kapan dipakai

minicode "prompt" · Sekali jalan; output teks model + ledger ke terminal

`echo "prompt" \ · minicode` · Prompt datang dari pipeline/another tool

minicode exec "prompt" --json · CI: envelope minicode.output.v1 JSONL di stdout + baris terakhir {"type":"summary"} berversi

exec --json memancarkan satu JSON per event lifecycle kanonik (langkah tool, output, error) dengan envelope minicode.output.v1, termasuk source dan visibility; skema lengkap ada di Output Protocol Spec. Summary terstruktur berversi muncul di akhir. Kegagalan setup (mis. tanpa provider) pun membawa satu baris {"type":"summary","ok":false,…} di stdout — stream tak pernah kosong; pesan manusia tetap di stderr, exit 1. Teks model mengalir sebagai record {type:"text",delta} terpisah yang sudah di-scrub dan bebas ANSI.

Ringkasan mesin: field opsional verify

Summary sukses exec --json dapat membawa hasil verifikasi terakhir (opt-in --verify) sebagai field opsional:

{
  "schema": "minicode.output.v1",
  "type": "summary",
  "ok": true,
  "verify": { "active": true, "ok": false, "command": "bun run lint" }
}
  • verify muncul hanya pada success summary dan **hanya bila verifikasi

benar-benar dijalankan pada run ini; tanpa --verify (atau tanpa perintah verify efektif) kuncinya absen** dari summary (bukan null).

  • verify.ok menyatakan hasil verifikasi operator (lulus/gagal) dan bukan

pengganti top-level ok. Keduanya independen: summary dapat "ok":true (exit 0) meski verify.ok:false.

  • verify.command = perintah verifikasi yang diotorisasi operator

(MINICODE_VERIFY_CMD, config, atau hasil deteksi) — bukan output verifier.

Failure summary tidak menyertakan verify. Saat proses gagal (mis. budget habis, writer basi, error penghenti) — termasuk bila verifikasi sudah berjalan sebelum kegagalan — record terminal memakai error envelope yang telah ditentukan (schema, type, ok:false, error, prompt) dan tidak membawa field verify. Hasil verifikasi terakhir tidak dapat diandalkan lewat summary pada jalur ini karena field-nya memang tidak ada.

Perbedaan sukses/gagal ini adalah kontrak saat ini yang sengaja diterima untuk P11 (keputusan pemilik atas temuan N-1): implementasi dan bentuk output tidak diubah, hanya dinyatakan eksplisit di dokumentasi. Ini bukan jaminan desain permanen — perluasan verify ke failure summary (memuat hasil verifikasi yang sudah berjalan beserta tes kontraknya) memerlukan keputusan protokol tersendiri di luar P11. Cakupan bukti: kombinasi "verifikasi sudah berjalan lalu proses gagal" tidak diklaim telah diuji pada seluruh jalur kegagalan.

Server JSON-RPC untuk IDE: minicode acp

minicode acp membaca satu JSON per baris di stdin dan menulis respons/notifikasi satu JSON per baris di stdout (stderr murni diagnostik manusia). Subset minimal Fase 5 — bukan klaim kompatibel ACP penuh:

Method · Params · Balasan

initialize · {client} · {server:"minicode-acp", capabilities:{run, streamText, cancel, approval:"deny-headless"}}

run · `{prompt*, cwd?, model?, maxSteps?, timeoutMs?, budget?, mode?, workMode?:"DISCUSS"\ · "PLAN"\ · "BUILD"}` · notifikasi lifecycle (turn.*, tool.*, approval.*, file.changed, test.completed, diagnostic.raised, checkpoint.created, plan.updated, finding.detected, result.produced, context.compacted) + {type:"text",delta}, lalu {ok,tokens,steps,turns,text} atau {error} ({type:"tool",name} hanya legacy bila lifecycle absen). workMode terpisah dari mode; lihat CLI.

cancel · — · {cancelled:true/false} (menggugurkan run berjalan)

shutdown · — · keluar 0

Batasan v1 yang jujur: tiap run = sesi BARU (tanpa thread/resume); SATU run dalam terbang (run kedua ditolak, bukan antre); tool gated DITOLAK tanpa TTY (fail-closed, sama seperti CI) — IDE yang butuh tulis/eksekusi memakai mode auto dengan allowlist atau prompt yang self-contained.

printf '%s\n' '{"id":1,"method":"initialize"}' '{"id":2,"method":"shutdown"}' | minicode acp

Hasil terstruktur: submit_result

Tool submit_result menghasilkan JSON akhir terstruktur, dipanggil paling banyak 1× per run, dengan mode NO_PROMPT (tidak minta konfirmasi). Di exec --json, isi hasil diteruskan verbatim — pengganti response_format ala API. Bila result.findings berisi daftar eksplisit {category, severity, summary, evidence?}, temuan tersebut juga diproyeksikan sebagai event finding.detected. Cocok untuk tugas yang hasilnya dikonsumsi program lain, bukan manusia.

Mode --json memakai envelope lifecycle dan summary yang dijelaskan di atas serta di Output Protocol Spec; teks model tetap record {type:"text",delta} terpisah. Setup failure selalu membawa satu baris summary ok:false.

Klarifikasi mid-run: ask_user

ask_user menanyakan manusia di tengah run. Gated + dirender lewat injeksi promptAskText; fail-closed di non-TTY — di CI tanpa TTY, pertanyaan tidak akan menggantung build tanpa jejak, tool ditolak dengan pesan jelas. Desain CI: jangan bergantung pada ask_user; tulis prompt yang self-contained.

Batas runtime

Kendali · Default · Catatan

--max-steps <n> · 50 · Batas langkah tool per run

--timeout <ms> · 900000 (15 menit) · Hard deadline per run; 0 = Infinity

--ratelimit <rpm> · — · Token bucket request LLM per menit

--budget <usd> · — · Warn 80%; lewat → one-shot exit(1), TUI break loop; exec menegakkan sama seperti one-shot

MINICODE_TIMEOUT_MS mengisi default bila --timeout tidak diset.

Contoh pipeline CI

# gate PR: verify + budget ketat + hasil JSON
minicode exec --work-mode BUILD --verify --json --budget 0.50 --budget-strict --max-steps 40 \
  "perbaiki lint di src/ lalu jalankan bun run lint"

# pakai provider tertentu tanpa mengubah config
minicode exec "ringkas diff ini" --json --provider openai --model gpt-4o

# prompt dari file
minicode exec "$(cat task.md)" --json

Catatan keamanan untuk CI

  • Config lokal .minicode/config.json diabaikan secara default (--allow-local-config untuk percayai) — repo clone-an tidak bisa men-spawn MCP atau menyedot prompt. Di runner yang Anda kendalikan penuh, boleh diaktifkan.
  • git_commit dan semua tool MCP di-gate: di non-TTY selalu ditolak. CI yang butuh commit harus lewat jalur lain (mis. workflow git, bukan agent).
  • Env kredensial di-scrub dari subprocess; GITHUB_TOKEN dkk. tidak bocor ke tool bash. Detail di Keamanan.

Lanjut