# 策展 · X (Twitter) 🔥

> 📖 本站完整內容索引（documentation index）：[llms.txt](/llms.txt)

> 作者：Aiden Bai (@aidenybai) · 平台：X (Twitter) · 日期：2026-04-11

> 原始來源：https://x.com/aidenybai/status/2043034194939670723

## 中文摘要

`cli-to-js` 將任何 CLI 工具自動轉換為強型別的 JavaScript API。

`cli-to-js` 是一個實驗性專案，旨在透過自動解析 CLI 工具的 `--help` 輸出，將任何指令列介面轉換為具備強型別的 JavaScript API，讓開發者能以程式碼方式呼叫系統工具。該專案目前處於高度實驗階段，API 可能隨時變動，開發者需留意其穩定性。

**核心運作機制**
該工具的核心邏輯在於「自動化解析」，它透過讀取二進位檔案的 `--help` 資訊，將其轉化為結構化的 Schema，並回傳一個基於 Proxy 的 API。
- 子指令（Subcommands）被映射為 JavaScript 方法。
- 旗標（Flags）被映射為選項物件。
- 系統會自動處理參數轉換，例如將 `{ verbose: true }` 轉換為 `--verbose`，或將陣列參數展開為多個旗標。
- 支援從二進位名稱直接轉換，也支援從現有的幫助文字字串（Help text string）進行轉換。

**對 Agent 的重要性**
對於 Agent 開發而言，此工具解決了與系統互動的結構化問題。Agent 通常需要呼叫 CLI 工具，但直接處理原始 Shell 字串既不安全也不穩定。
- 結構化介面：Agent 可以對系統上的任何二進位檔案進行內省（Introspection），取得強型別介面並安全地呼叫。
- 錯誤修正：內建的 `$validate` 功能可在產生處理程序（Process）之前捕捉虛構的旗標名稱，並回傳建議，讓 Agent 能在單次重試中自我修正。
- 串流處理：`$spawn` 回傳標準的非同步迭代器，讓串流與管道操作能透過 `for await` 迴圈輕鬆實現。

**關鍵技術特性**
- TypeScript 整合：API 開箱即用，具備完整型別定義，無需額外的程式碼生成。開發者可透過泛型傳遞子指令的選項型別，或使用 `npx` 指令產生 `.d.ts` 文件。
- 嚴格驗證：在執行指令前，可透過 `$validate` 檢查選項。系統會檢查未知旗標（並提供基於 Levenshtein 距離的建議）、型別不匹配（如布林值與數值混用）以及位置參數的數量錯誤。
- 輸出解析：每個指令回傳的 `CommandPromise` 支援多種輸出格式，包括 `.text()`（原始字串）、`.lines()`（字串陣列）以及 `.json()`（自動解析 JSON 輸出），大幅簡化了處理 CLI 輸出的繁瑣工作。
- 指令組合：透過 `$command` 可取得 Shell 字串而非直接執行，並可使用 `script()` 將多個指令組合成可執行的腳本，支援順序執行與失敗中斷。

**執行與串流控制**
`cli-to-js` 提供了細緻的執行控制能力，適合複雜的自動化場景：
- 串流回呼：支援 `onStdout` 與 `onStderr` 回呼，允許在接收緩衝結果的同時取得即時輸出。
- 非同步迭代：`$spawn` 允許開發者透過非同步迭代器逐行讀取輸出，適用於監控長時間運行的指令。
- 互動模式：透過設定 `stdio: "inherit"`，可將標準輸入輸出傳遞給父終端，支援需要互動的 CLI 工具。
- 執行配置：每個方法皆可接收第二個參數進行配置，包括 `cwd`（工作目錄）、`env`（環境變數）、`timeout`（逾時設定）以及 `AbortSignal`（中止訊號），確保執行環境的靈活性。

**獨立性與部署**
該專案強調生成的程式碼具有高度獨立性：
- 獨立執行：透過 `npx cli-to-js` 產生的 JS/TS 封裝器是獨立的，內嵌了輕量級的執行時（Runtime），對 `cli-to-js` 本身零依賴。
- 部署彈性：開發者可以將產生的程式碼直接放入任何專案中，無需擔心相依性問題，這對於需要將 CLI 工具整合至現有專案的開發者來說非常便利。

**注意事項**
由於 `cli-to-js` 仍處於實驗階段，其 API 介面可能在未經通知的情況下發生變更。在生產環境中使用時，建議對其產生的 Schema 與執行結果進行充分測試，並密切關注專案的更新動態。

## 標籤

CLI, 開源專案, 其他, cli-to-js