modiqo/cliare

CLI agent-readiness measurement, command-shape inference, and CI scorecards

What it solves

CLIARE（CLI Agent Readiness Evaluation）針對指令列介面（CLI）在設計給人類使用與 AI 代理人實際使用之間的落差提供解決方案。大多數 CLI 都會出現「漂移」——文件、說明文字與實際執行時行為不一致——導致 AI 代理人因試錯探索而浪費 token 與延遲。它同時協助安全審查者找出看似唯讀的二進位檔中未文件化的副作用。

How it works

CLIARE 把 CLI 二進位檔視為黑箱，在受控的範圍內探測它，以測量實際執行時行為。它不依賴靜態文件，而是記錄哪些指令存在、哪些旗標安全、哪些輸出可機器解析（JSON/YAML）。可在不同情境（乾淨環境、已驗證或使用測試資料）下執行，並產生完整的產出集合，最重要的是 command-index.json，作為代理程式使用的測量合約。

Who it’s for

  • CLI Maintainers：在發佈新版本前找出並修正說明覆蓋、診斷資訊與輸出合約的缺口。
  • Security Reviewers：偵測本應安全的指令中意外的檔案寫入或網路行為。
  • Agent Harness Builders：提供代理人預先測量好的 CLI 表面圖，減少 token 消耗並提升可靠性。

Highlights

  • Evidence-Based Indexing：根據執行時證據產生 command-index.json，而非手寫文件。
  • Black-Box Probing：對二進位檔進行測試，以推斷指令結構並偵測副作用。
  • Role-Specific Reporting：為維護者（修正清單）、安全人員（副作用報告）與代理程式（路由回應）提供客製化報告。
  • CI Integration：內建 GitHub Action，可自動化就緒度稽核並依分數卡設定發佈門檻。
  • Surface Querying：允許代理程式透過 cliare surface query 將任務意圖對應到具備就緒狀態的具體指令。