MacroCLI 命令列工具 是做什麼的？
用途
MacroCLI 可將有價值的 GUI 工作流程轉換為可參數化的 CLI 巨集。AI 代理從不直接操作 GUI，而是透過此穩定 CLI 呼叫巨集，由運行時將執行路由至最佳可用後端（原生外掛/API、檔案轉換、語意 UI 控制，或預編譯 GUI 巨集重播）。
安裝
cd macrocli/agent-harness
pip install -e .
系統需求： Python 3.10+、PyYAML、click、prompt-toolkit。
快速入門（供代理使用）
# 1. 查看可用的巨集
cli-anything-macrocli macro list --json
# 2. 檢視巨集的參數
cli-anything-macrocli macro info export_file --json
# 3. 執行乾執行，檢查參數但不產生副作用
cli-anything-macrocli --dry-run macro run export_file \
--param output=/tmp/test.txt --json
# 4. 執行巨集
cli-anything-macrocli macro run export_file \
--param output=/tmp/result.txt --json
# 5. 查看可用的後端
cli-anything-macrocli backends --json
指令參考
全域旗標
| 旗標 | 說明 |
|---|---|
--json | 將機器可讀的 JSON 輸出至 stdout |
--dry-run | 模擬所有步驟，跳過副作用 |
--session-id <id> | 繼續或建立一個具名工作階段 |
macro 指令群組
| 指令 | 說明 |
|---|---|
macro list | 列出所有可用的巨集 |
macro info <name> | 顯示巨集的結構（參數、步驟、條件） |
macro run <name> --param k=v | 執行巨集 |
macro dry-run <name> --param k=v | 模擬執行，不產生副作用 |
macro validate [name] | 結構驗證 |
macro define <name> | 建立新的巨集 YAML 骨架 |
session 指令群組
| 指令 | 說明 |
|---|---|
session status | 顯示工作階段統計 |
session history | 顯示最近的執行歷史 |
session save | 將工作階段持久化至磁碟 |
session list | 列出所有已儲存的工作階段 |
backends
cli-anything-macrocli backends --json
# 顯示：native_api, file_transform, semantic_ui, gui_macro, recovery
# 以及每個後端在目前環境中是否可用。
巨集參數
使用 --param key=value 傳遞參數。可重複使用多次：
cli-anything-macrocli macro run transform_json \
--param file=/path/to/data.json \
--param key=settings.theme \
--param value=dark \
--json
輸出格式（--json）
所有指令在設定 --json 時都會輸出 JSON：
{
"success": true,
"macro_name": "export_file",
"output": {
"exported_file": "/tmp/result.txt"
},
"error": "",
"telemetry": {
"duration_ms": 312,
"steps_total": 2,
"steps_run": 2,
"backends_used": ["native_api"],
"dry_run": false
}
}
失敗時（"success": false），請讀取 "error" 欄位以了解原因。失敗時退出碼為 1。
執行後端
根據巨集的步驟定義自動選擇後端：
| 後端 | 觸發條件 | 使用案例 |
|---|---|---|
native_api | backend: native_api | 子行程 / shell 指令 |
file_transform | backend: file_transform | XML、JSON、純文字檔案編輯 |
semantic_ui | backend: semantic_ui | 無障礙輔助 / 鍵盤快速鍵 |
gui_macro | backend: gui_macro | 預編譯的座標重播 |
recovery | backend: recovery | 重試 / 備用協調 |
撰寫巨集
巨集是位於 cli_anything/macrocli/macro_definitions/ 目錄下的 YAML 檔案。可使用以下指令建立骨架：
cli-anything-macrocli macro define my_macro --output \
cli_anything/macrocli/macro_definitions/examples/my_macro.yaml
最小結構範例：
name: my_macro
version: "1.0"
description: 此巨集的用途。
parameters:
output:
type: string
required: true
description: 寫入結果的位置。
example: /tmp/result.txt
preconditions:
- file_exists: /path/to/input
steps:
- id: step1
backend: native_api
action: run_command
params:
command: [my-app, --export, "${output}"]
timeout_ms: 30000
on_failure: fail # 或：skip, continue
postconditions:
- file_exists: ${output}
- file_size_gt: [${output}, 100]
outputs:
- name: result_file
path: ${output}
agent_hints:
danger_level: safe # safe | moderate | dangerous
side_effects: [creates_file]
reversible: true
代理使用規則
- 一律使用
--json以獲得程式化的輸出。 - 使用
--dry-run驗證參數，然後再執行會產生副作用的巨集。 - 檢查
success欄位——不要僅根據退出碼判斷成功。 - 當
success為 false 時讀取error欄位——它會說明失敗原因。 - 使用
macro info <name>探索參數，然後再呼叫macro run。 - 為所有檔案參數使用絕對路徑。
工作流程範例
# 步驟 1：有什麼可用的？
cli-anything-macrocli macro list --json
# 步驟 2：transform_json 需要哪些參數？
cli-anything-macrocli macro info transform_json --json
# 步驟 3：安全測試
cli-anything-macrocli --dry-run macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
# 步驟 4：實際執行
cli-anything-macrocli macro run transform_json \
--param file=/tmp/config.json \
--param key=theme \
--param value=dark --json
版本
1.0.0