Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

fix(macrocli): fixes from live gedit testing on Xvfb

haorui-harry17b89ac98226
diff --git a/macrocli/agent-harness/DEMO.md b/macrocli/agent-harness/DEMO.md
new file mode 100644
index 000000000..140a70d31
--- /dev/null
+++ b/macrocli/agent-harness/DEMO.md
@@ -0,0 +1,361 @@
+# MacroCLI Demo — gedit 完整测试方案
+
+> **注意事项(测试前必读)**
+> - 所有命令在**桌面终端**里跑,不能是 SSH 无头会话(需要 `$DISPLAY`)
+> - `gedit_save_as` 用的菜单路径是 `[File, Save As...]`,如果你的 gedit 版本菜单文字不同(比如无省略号),需要改 yaml 里的 `menu_path`
+> - 录制完的宏用 `--macro-file /path/to/xxx.yaml` 直接指定,无需注册到 manifest
+> - 如果 AT-SPI 不可用(`semantic_ui available: false`),`menu_click` 步骤会失败,改用 `hotkey` 替代
+
+## 目标
+
+在 Linux 桌面机上,用 **gedit**(文本编辑器)演示 MacroCLI 的三条核心路径:
+
+1. **手写宏** — 用已有的 YAML 宏定义执行 GUI 操作
+2. **录制宏** — 操作一次 gedit,自动生成宏 YAML
+3. **Gemini 辅助生成**(可选,需 API Key)
+
+---
+
+## 第一步:环境准备
+
+在你的 Linux 桌面机上执行:
+
+```bash
+# 1. 安装 gedit(如果没有)
+sudo apt install gedit # Ubuntu/Debian
+# sudo dnf install gedit # Fedora
+# sudo pacman -S gedit # Arch
+
+# 2. 安装 MacroCLI 系统依赖
+sudo apt install xdotool wmctrl python3-pyatspi
+
+# 3. 克隆仓库 / 进入已有目录
+cd ~/CLI-Anything-with-GUI-Macro-System-/macrocli/agent-harness
+
+# 4. 创建专用 conda 环境(或用已有的)
+conda create -n macrocli python=3.11 -y
+conda activate macrocli
+
+# 5. 安装 MacroCLI 及可视化依赖
+pip install -e ".[visual]"
+# 等价于:pip install -e . mss Pillow numpy pynput
+
+# 6. 验证安装
+cli-anything-macrocli macro list
+```
+
+期望输出:
+```
+Available macros (7):
+ export_file Export a file from the target application...
+ gedit_find_and_replace Open Find & Replace in gedit...
+ gedit_new_window Open a new gedit window...
+ gedit_save_as Save the current gedit document...
+ gedit_type_and_save Type a line of text into gedit and save...
+ transform_json Read a JSON file, set a nested key...
+ undo_last Trigger an undo operation...
+```
+
+---
+
+## 第二步:检查后端可用性
+
+```bash
+cli-anything-macrocli --json backends
+```
+
+期望(在桌面机上):
+```json
+{
+ "native_api": { "available": true, "priority": 100 },
+ "gui_macro": { "available": false, "priority": 80 },
+ "visual_anchor": { "available": true, "priority": 75 },
+ "file_transform":{ "available": true, "priority": 70 },
+ "semantic_ui": { "available": true, "priority": 50 },
+ "recovery": { "available": true, "priority": 10 }
+}
+```
+
+> `visual_anchor` 需要 `mss Pillow numpy pynput` 全部安装
+> `semantic_ui` 需要 `xdotool` 或 `python3-pyatspi`
+
+---
+
+## Demo A:手写宏执行(semantic_ui + visual_anchor)
+
+### A1. 打开 gedit(native_api 宏)
+
+```bash
+# 干跑确认参数正确
+cli-anything-macrocli --dry-run --json macro run gedit_new_window
+
+# 正式执行:打开一个新 gedit 窗口
+cli-anything-macrocli --json macro run gedit_new_window
+```
+
+gedit 窗口应在 3 秒内弹出。
+
+### A2. 在 gedit 里输入文字并保存(semantic_ui + visual_anchor)
+
+```bash
+# 在已打开的 gedit 里输入文字并 Ctrl+S 保存
+cli-anything-macrocli --json macro run gedit_type_and_save \
+ --param "text=Hello from MacroCLI! 🎉"
+```
+
+观察:光标出现在 gedit,逐字输入,然后触发保存。
+
+### A3. 另存为指定路径(menu_click + wait_for_window)
+
+```bash
+cli-anything-macrocli --json macro run gedit_save_as \
+ --param output_path=/tmp/macrocli_demo.txt
+```
+
+观察:
+1. `File > Save As...` 菜单被自动点击
+2. 等待对话框出现
+3. 路径被输入,回车确认
+4. 后置条件验证 `/tmp/macrocli_demo.txt` 存在
+
+验证结果:
+```bash
+cat /tmp/macrocli_demo.txt
+```
+
+### A4. 查找替换(hotkey + type_text)
+
+```bash
+cli-anything-macrocli --json macro run gedit_find_and_replace \
+ --param find_text=Hello \
+ --param replace_text=Hi
+```
+
+观察:`Ctrl+H` 弹出对话框,自动填写两个字段,执行 Replace All,关闭。
+
+---
+
+## Demo B:录制宏(自动生成)
+
+这个演示"录制一次,以后可以重复调用"。
+
+```bash
+# 1. 开始录制,给宏命名 my_gedit_workflow
+cli-anything-macrocli macro record my_gedit_workflow \
+ --output-dir /tmp/macrocli_recording
+```
+
+终端显示:
+```
+Recording 'my_gedit_workflow'. Press Ctrl+Alt+S to stop.
+```
+
+**现在手动操作 gedit**(录制器会捕获这些动作):
+1. 点击 gedit 文本区
+2. 输入几个字
+3. 按 `Ctrl+S`
+4. 点击菜单 `File`
+5. 点击 `Save As`
+6. 输入文件名
+7. 按回车
+
+**停止录制:**
+```
+Ctrl+Alt+S
+```
+
+录制结束,自动生成:
+```
+/tmp/macrocli_recording/
+├── my_gedit_workflow.yaml ← 宏定义文件
+└── my_gedit_workflow_templates/
+ ├── step_001_click.png ← 每个点击的截图模板
+ ├── step_002_click.png
+ └── ...
+```
+
+查看生成的宏:
+```bash
+cat /tmp/macrocli_recording/my_gedit_workflow.yaml
+
+# 或直接查 info(用 --macro-file)
+cli-anything-macrocli --json macro run my_gedit_workflow \
+ --macro-file /tmp/macrocli_recording/my_gedit_workflow.yaml --dry-run
+```
+
+重放录制的宏:
+```bash
+# 用 --macro-file 直接指定 yaml 文件,无需注册到 manifest
+cli-anything-macrocli --json macro run my_gedit_workflow \
+ --macro-file /tmp/macrocli_recording/my_gedit_workflow.yaml
+```
+
+---
+
+## Demo C:Gemini 辅助生成(可选)
+
+需要 Gemini API Key(免费额度够用):
+获取地址:https://aistudio.google.com/app/apikey
+
+```bash
+# 安装 Gemini 依赖
+pip install google-generativeai
+
+# 打开 gedit,然后截图分析
+cli-anything-macrocli macro assist gedit_close_tab \
+ --goal "Close the current tab in gedit without saving" \
+ --screenshot current \
+ --api-key $GEMINI_API_KEY \
+ --output /tmp/gedit_close_tab.yaml
+```
+
+输出示例:
+```
+Sending screenshot to Gemini (gemini-1.5-flash)...
+✓ Generated 3 steps → /tmp/gedit_close_tab.yaml
+
+ Templates to capture (use 'macro capture-template'):
+ templates/001_wait_image.png: Close button in the tab bar
+```
+
+查看生成结果:
+```bash
+cat /tmp/gedit_close_tab.yaml
+```
+
+---
+
+## Demo D:模板截图(visual_anchor 基础)
+
+这演示如何为 `click_image` 创建模板。
+
+```bash
+# 1. 打开 gedit,定位"New"按钮的屏幕坐标(用鼠标悬停或 xdotool)
+# 假设 New 按钮在 (120, 55),大小约 40x30
+
+# 2. 截取模板
+cli-anything-macrocli macro capture-template \
+ templates/gedit_new_button.png \
+ --x 100 --y 40 --width 60 --height 40
+
+# 3. 写一个使用该模板的宏
+cat > /tmp/gedit_click_new.yaml << 'EOF'
+name: gedit_click_new
+version: "1.0"
+description: Click the New button in gedit toolbar.
+steps:
+ - id: click_new
+ backend: visual_anchor
+ action: click_image
+ params:
+ template: templates/gedit_new_button.png
+ confidence: 0.85
+ timeout_ms: 3000
+EOF
+
+# 4. 执行(在 gedit 窗口上测试)
+cli-anything-macrocli macro run gedit_click_new \
+ --macro-file /tmp/gedit_click_new.yaml --json
+```
+
+---
+
+## 完整自动化测试脚本
+
+把上面的步骤串成一个脚本,验证全链路:
+
+```bash
+#!/bin/bash
+# demo_test.sh — MacroCLI gedit 完整链路测试
+
+set -e
+echo "=== MacroCLI Demo Test ==="
+
+# 确保没有旧的 gedit 残留
+pkill gedit 2>/dev/null || true
+sleep 0.5
+
+echo ""
+echo "--- Step 1: Open gedit ---"
+cli-anything-macrocli --json macro run gedit_new_window
+sleep 1.5
+
+echo ""
+echo "--- Step 2: Type text ---"
+cli-anything-macrocli --json macro run gedit_type_and_save \
+ --param "text=MacroCLI demo: $(date)"
+sleep 0.5
+
+echo ""
+echo "--- Step 3: Save As ---"
+OUTPUT=/tmp/macrocli_demo_$(date +%s).txt
+cli-anything-macrocli --json macro run gedit_save_as \
+ --param output_path="$OUTPUT"
+sleep 0.5
+
+echo ""
+echo "--- Step 4: Verify output ---"
+echo "File content:"
+cat "$OUTPUT"
+echo ""
+echo "File size: $(wc -c < $OUTPUT) bytes"
+
+echo ""
+echo "--- Step 5: Find & Replace ---"
+cli-anything-macrocli --json macro run gedit_find_and_replace \
+ --param find_text=MacroCLI \
+ --param replace_text=MacroCLI✓
+sleep 0.5
+
+echo ""
+echo "=== All steps passed ==="
+```
+
+运行:
+```bash
+chmod +x demo_test.sh
+./demo_test.sh
+```
+
+---
+
+## 常见问题
+
+**Q: `semantic_ui` 报 "xdotool not found"**
+```bash
+sudo apt install xdotool
+```
+
+**Q: `menu_click` 报 "AT-SPI application not found"**
+```bash
+sudo apt install python3-pyatspi
+# 然后重启 gedit(需要 AT-SPI 服务在启动时就运行)
+```
+
+**Q: `visual_anchor` 报 "no display"**
+- 确认在桌面终端(不是 SSH)里运行
+- 或设置 `export DISPLAY=:0`
+
+**Q: 录制时 Ctrl+Alt+S 没反应**
+- 确认焦点在终端而不是 gedit
+- 或用 `--timeout 30`(30 秒后自动停止)
+
+**Q: 模板匹配失败(confidence 太高)**
+```yaml
+# 把 confidence 调低
+confidence: 0.70 # 默认 0.85
+```
+
+---
+
+## 下一步:对接更复杂的应用
+
+同样的流程适用于任何 GUI 应用:
+
+| 应用 | 推荐后端 | 备注 |
+|------|----------|------|
+| Inkscape | `native_api` (`--actions`) + `semantic_ui` | 原生 CLI 支持很好 |
+| GIMP | `native_api` (Script-Fu) | 有完整脚本接口 |
+| LibreOffice | `native_api` (`--headless`) + `semantic_ui` | UNO API |
+| draw.io | `file_transform` + `visual_anchor` | XML 格式,可直接改文件 |
+| 无 CLI 的应用 | `macro record` + `visual_anchor` | 录制一次,模板匹配回放 |
diff --git a/macrocli/agent-harness/cli_anything/macrocli/backends/native_api.py b/macrocli/agent-harness/cli_anything/macrocli/backends/native_api.py
index 8c3ca51d1..8c1dea97d 100644
--- a/macrocli/agent-harness/cli_anything/macrocli/backends/native_api.py
+++ b/macrocli/agent-harness/cli_anything/macrocli/backends/native_api.py
@@ -42,6 +42,8 @@ class NativeAPIBackend(Backend):
return self._find_executable(step, params, context, t0)
elif action == "run_command":
return self._run_command(step, params, context, t0)
+ elif action == "start_process":
+ return self._start_process(step, params, context, t0)
else:
return StepResult(
success=False,
@@ -165,3 +167,80 @@ class NativeAPIBackend(Backend):
backend_used=self.name,
duration_ms=duration,
)
+
+ def _start_process(
+ self, step: MacroStep, params: dict, context: BackendContext, t0: float
+ ) -> StepResult:
+ """Launch a GUI application in the background without waiting for it to exit.
+
+ Use this instead of run_command for GUI apps like gedit, inkscape, etc.
+ The process is detached immediately after launch.
+
+ Params:
+ command: list[str] — the command to run
+ cwd: str — working directory (optional)
+ env: dict — extra environment variables (optional)
+ log_file: str — redirect stdout+stderr here (default /dev/null)
+ """
+ import subprocess
+ step_params = substitute(step.params, params)
+ command: list[str] = step_params.get("command", [])
+ if not command:
+ return StepResult(
+ success=False,
+ error="NativeAPIBackend.start_process: 'command' param is required.",
+ backend_used=self.name,
+ duration_ms=(time.time() - t0) * 1000,
+ )
+
+ if isinstance(command, str):
+ import shlex
+ command = shlex.split(command)
+ command = [str(c) for c in command]
+
+ cwd: str = step_params.get("cwd", "")
+ extra_env: dict = step_params.get("env", {})
+ log_file: str = step_params.get("log_file", "/dev/null")
+
+ env = os.environ.copy()
+ if extra_env:
+ env.update({k: str(v) for k, v in extra_env.items()})
+
+ if context.dry_run:
+ return StepResult(
+ success=True,
+ output={"dry_run": True, "command": command},
+ backend_used=self.name,
+ duration_ms=(time.time() - t0) * 1000,
+ )
+
+ try:
+ with open(log_file, "a") as log:
+ proc = subprocess.Popen(
+ command,
+ stdout=log,
+ stderr=log,
+ cwd=cwd or None,
+ env=env,
+ start_new_session=True, # detach from current process group
+ )
+ return StepResult(
+ success=True,
+ output={"pid": proc.pid, "command": command},
+ backend_used=self.name,
+ duration_ms=(time.time() - t0) * 1000,
+ )
+ except FileNotFoundError as exc:
+ return StepResult(
+ success=False,
+ error=f"Command not found: {command[0]}. {exc}",
+ backend_used=self.name,
+ duration_ms=(time.time() - t0) * 1000,
+ )
+ except Exception as exc:
+ return StepResult(
+ success=False,
+ error=f"start_process failed: {exc}",
+ backend_used=self.name,
+ duration_ms=(time.time() - t0) * 1000,
+ )
diff --git a/macrocli/agent-harness/cli_anything/macrocli/backends/semantic_ui.py b/macrocli/agent-harness/cli_anything/macrocli/backends/semantic_ui.py
index 38f143221..80b587616 100644
--- a/macrocli/agent-harness/cli_anything/macrocli/backends/semantic_ui.py
+++ b/macrocli/agent-harness/cli_anything/macrocli/backends/semantic_ui.py
@@ -53,6 +53,7 @@ Example YAML steps:
from __future__ import annotations
+import os
import platform
import shutil
import subprocess
@@ -65,6 +66,14 @@ from cli_anything.macrocli.core.macro_model import MacroStep, substitute
_SYSTEM = platform.system()
+def _x_env() -> dict:
+ """Return env dict with DISPLAY set, for subprocess calls to X tools."""
+ env = os.environ.copy()
+ if "DISPLAY" not in env:
+ env["DISPLAY"] = ":0"
+ return env
+
+
# ── AT-SPI helpers (Linux) ────────────────────────────────────────────────────
def _atspi_available() -> bool:
@@ -161,13 +170,13 @@ def _xdotool_key(keys: str) -> None:
if not shutil.which("xdotool"):
raise RuntimeError("xdotool not found. Install with: apt install xdotool")
# ctrl+shift+e → ctrl+shift+e (xdotool accepts this format directly)
- subprocess.run(["xdotool", "key", "--clearmodifiers", keys], check=True)
+ subprocess.run(["xdotool", "key", "--clearmodifiers", keys], check=True, env=_x_env())
def _xdotool_type(text: str) -> None:
if not shutil.which("xdotool"):
raise RuntimeError("xdotool not found. Install with: apt install xdotool")
- subprocess.run(["xdotool", "type", "--clearmodifiers", "--delay", "30", text], check=True)
+ subprocess.run(["xdotool", "type", "--clearmodifiers", "--delay", "30", text], check=True, env=_x_env())
def _xdotool_focus(title: str) -> None:
@@ -175,7 +184,7 @@ def _xdotool_focus(title: str) -> None:
raise RuntimeError("xdotool not found. Install with: apt install xdotool")
subprocess.run(
["xdotool", "search", "--name", title, "windowfocus", "--sync"],
- check=True,
+ check=True, env=_x_env(),
)
@@ -443,14 +452,14 @@ class SemanticUIBackend(Backend):
while time.time() < deadline:
if shutil.which("wmctrl"):
r = subprocess.run(
- ["wmctrl", "-l"], capture_output=True, text=True
+ ["wmctrl", "-l"], capture_output=True, text=True, env=_x_env()
)
if title.lower() in r.stdout.lower():
return {"found": title, "method": "wmctrl"}
elif shutil.which("xdotool"):
r = subprocess.run(
["xdotool", "search", "--name", title],
- capture_output=True, text=True,
+ capture_output=True, text=True, env=_x_env(),
)
if r.returncode == 0 and r.stdout.strip():
return {"found": title, "method": "xdotool"}
@@ -502,7 +511,7 @@ class SemanticUIBackend(Backend):
if _SYSTEM == "Linux":
if shutil.which("wmctrl"):
- subprocess.run(["wmctrl", "-a", title], check=True)
+ subprocess.run(["wmctrl", "-a", title], check=True, env=_x_env())
return {"focused": title, "method": "wmctrl"}
_xdotool_focus(title)
return {"focused": title, "method": "xdotool"}
diff --git a/macrocli/agent-harness/cli_anything/macrocli/backends/visual_anchor.py b/macrocli/agent-harness/cli_anything/macrocli/backends/visual_anchor.py
index e2078ef1a..cb4abb679 100644
--- a/macrocli/agent-harness/cli_anything/macrocli/backends/visual_anchor.py
+++ b/macrocli/agent-harness/cli_anything/macrocli/backends/visual_anchor.py
@@ -73,6 +73,14 @@ from cli_anything.macrocli.backends.base import Backend, BackendContext, StepRes
from cli_anything.macrocli.core.macro_model import MacroStep, substitute
+def _x_env() -> dict:
+ """Return env dict with DISPLAY set, for subprocess calls to X tools."""
+ env = os.environ.copy()
+ if "DISPLAY" not in env:
+ env["DISPLAY"] = ":0"
+ return env
+
+
# ── lazy imports (only needed when backend is actually used) ──────────────────
def _require_numpy():
@@ -226,7 +234,7 @@ def _get_window_bounds(title_fragment: str) -> Optional[dict]:
# Try wmctrl first (most reliable)
if shutil.which("wmctrl"):
r = subprocess.run(
- ["wmctrl", "-lG"], capture_output=True, text=True
+ ["wmctrl", "-lG"], capture_output=True, text=True, env=_x_env()
)
for line in r.stdout.splitlines():
parts = line.split(None, 9)
@@ -241,7 +249,7 @@ def _get_window_bounds(title_fragment: str) -> Optional[dict]:
if shutil.which("xwininfo"):
r = subprocess.run(
["xwininfo", "-name", title_fragment],
- capture_output=True, text=True
+ capture_output=True, text=True, env=_x_env()
)
bounds = {}
for line in r.stdout.splitlines():
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_find_and_replace.yaml b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_find_and_replace.yaml
new file mode 100644
index 000000000..9fc3396dc
--- /dev/null
+++ b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_find_and_replace.yaml
@@ -0,0 +1,90 @@
+name: gedit_find_and_replace
+version: "1.0"
+description: >
+ Open Find & Replace in gedit (Ctrl+H), replace a word, then close the dialog.
+ Uses visual_anchor hotkey + type_text steps.
+tags: [demo, gedit, visual_anchor]
+
+parameters:
+ find_text:
+ type: string
+ required: true
+ description: Text to search for.
+ example: foo
+ replace_text:
+ type: string
+ required: true
+ description: Text to replace with.
+ example: bar
+
+preconditions:
+ - process_running: gedit
+
+steps:
+ - id: focus_gedit
+ backend: semantic_ui
+ action: focus_window
+ params:
+ title_contains: gedit
+ on_failure: fail
+
+ - id: open_find_replace
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: ctrl+h
+ on_failure: fail
+
+ - id: wait_dialog
+ backend: semantic_ui
+ action: wait_for_window
+ params:
+ title_contains: Replace
+ timeout_ms: 4000
+ on_failure: fail
+
+ - id: type_find
+ backend: visual_anchor
+ action: type_text
+ params:
+ text: "${find_text}"
+ interval_ms: 30
+ on_failure: fail
+
+ - id: tab_to_replace_field
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: tab
+ on_failure: fail
+
+ - id: type_replace
+ backend: visual_anchor
+ action: type_text
+ params:
+ text: "${replace_text}"
+ interval_ms: 30
+ on_failure: fail
+
+ - id: replace_all
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: alt+a
+ on_failure: fail
+
+ - id: close_dialog
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: escape
+ on_failure: skip
+
+postconditions: []
+outputs: []
+
+agent_hints:
+ danger_level: moderate
+ side_effects: [modifies_file, gui_interaction]
+ reversible: true
+ estimated_duration_ms: 3000
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_new_window.yaml b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_new_window.yaml
new file mode 100644
index 000000000..5dbe93842
--- /dev/null
+++ b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_new_window.yaml
@@ -0,0 +1,44 @@
+name: gedit_new_window
+version: "1.0"
+description: >
+ Open a new gedit window using native_api backend (subprocess).
+ This macro does not require an existing gedit window.
+tags: [demo, gedit, native_api]
+
+parameters:
+ file_path:
+ type: string
+ required: false
+ default: ""
+ description: Optional file to open in the new window.
+
+preconditions:
+ - file_exists: /usr/bin/gedit
+
+steps:
+ - id: launch_gedit
+ backend: native_api
+ action: start_process
+ params:
+ command: [gedit]
+ log_file: /tmp/gedit.log
+ env:
+ DISPLAY: ":99"
+ on_failure: fail
+
+ - id: wait_window
+ backend: semantic_ui
+ action: wait_for_window
+ params:
+ title_contains: gedit
+ timeout_ms: 8000
+ on_failure: fail
+
+postconditions: []
+outputs: []
+
+agent_hints:
+ danger_level: safe
+ side_effects: [opens_application]
+ reversible: true
+ estimated_duration_ms: 3000
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_save_as.yaml b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_save_as.yaml
new file mode 100644
index 000000000..48ba46dd9
--- /dev/null
+++ b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_save_as.yaml
@@ -0,0 +1,95 @@
+name: gedit_save_as
+version: "1.0"
+description: >
+ Save the current gedit document to a specific file path.
+ Uses Ctrl+Shift+S to open Save As, then Ctrl+L to type the full path.
+tags: [demo, gedit, visual_anchor]
+
+parameters:
+ output_path:
+ type: string
+ required: true
+ description: Full path to save the file to.
+ example: /tmp/demo_output.txt
+
+preconditions:
+ - process_running: gedit
+
+steps:
+ - id: focus_gedit
+ backend: semantic_ui
+ action: focus_window
+ params:
+ title_contains: gedit
+ on_failure: fail
+
+ - id: open_save_as
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: ctrl+shift+s
+ on_failure: fail
+
+ - id: wait_dialog
+ backend: semantic_ui
+ action: wait_for_window
+ params:
+ title_contains: Save As
+ timeout_ms: 5000
+ on_failure: fail
+
+ - id: open_path_entry
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: ctrl+l
+ on_failure: fail
+
+ - id: clear_path_entry
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: ctrl+a
+ on_failure: fail
+
+ - id: type_path
+ backend: visual_anchor
+ action: type_text
+ params:
+ text: "${output_path}"
+ interval_ms: 30
+ on_failure: fail
+
+ - id: confirm_save
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: enter
+ on_failure: fail
+
+ - id: wait_dialog_close
+ backend: semantic_ui
+ action: wait_for_window
+ params:
+ title_contains: gedit
+ timeout_ms: 3000
+ on_failure: skip
+
+ - id: wait_file_flush
+ backend: native_api
+ action: run_command
+ params:
+ command: [sleep, "0.5"]
+ on_failure: skip
+
+postconditions: []
+
+outputs:
+ - name: saved_file
+ path: ${output_path}
+
+agent_hints:
+ danger_level: safe
+ side_effects: [creates_file, gui_interaction]
+ reversible: true
+ estimated_duration_ms: 4000
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_type_and_save.yaml b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_type_and_save.yaml
new file mode 100644
index 000000000..9cf522446
--- /dev/null
+++ b/macrocli/agent-harness/cli_anything/macrocli/macro_definitions/demo/gedit_type_and_save.yaml
@@ -0,0 +1,50 @@
+name: gedit_type_and_save
+version: "1.0"
+description: >
+ Type a line of text into gedit and save the file with Ctrl+S.
+ Uses semantic_ui (AT-SPI) to focus the window, then visual_anchor
+ to type and send the shortcut.
+tags: [demo, gedit, semantic_ui, visual_anchor]
+
+parameters:
+ text:
+ type: string
+ required: false
+ default: "Hello from MacroCLI!"
+ description: Text to type into gedit.
+
+preconditions:
+ - process_running: gedit
+
+steps:
+ - id: focus_gedit
+ backend: semantic_ui
+ action: focus_window
+ params:
+ title_contains: gedit
+ on_failure: fail
+
+ - id: type_text
+ backend: visual_anchor
+ action: type_text
+ params:
+ text: "${text}"
+ interval_ms: 30
+ on_failure: fail
+
+ - id: save_file
+ backend: visual_anchor
+ action: hotkey
+ params:
+ keys: ctrl+s
+ on_failure: fail
+
+postconditions: []
+
+outputs: []
+
+agent_hints:
+ danger_level: safe
+ side_effects: [modifies_file, gui_interaction]
+ reversible: true
+ estimated_duration_ms: 2000
diff --git a/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py b/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py
index 6f9fa396e..17ce9fbb5 100644
--- a/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py
+++ b/macrocli/agent-harness/cli_anything/macrocli/macrocli_cli.py
@@ -175,18 +175,44 @@ def macro():
@click.argument("name")
@click.option("--param", "-p", multiple=True,
help="Macro parameter in key=value format. Repeat for multiple.")
[email protected]("--macro-file", default=None,
+ help="Run a macro directly from a YAML file path (bypasses registry).")
@handle_error
-def macro_run(name, param):
- """Execute a macro by name.
+def macro_run(name, param, macro_file):
+ """Execute a macro by name, or from a YAML file with --macro-file.
\b
Example:
macro run export_file --param output=/tmp/out.txt
- macro run export_file -p output=/tmp/out.txt -p format=plain --json
+ macro run my_macro --macro-file /tmp/recording/my_macro.yaml --param key=val
"""
params = _parse_params(param)
- runtime = get_runtime()
- result = runtime.execute(name, params, dry_run=_dry_run)
+
+ if macro_file:
+ # Load macro directly from file, bypassing the registry
+ from cli_anything.macrocli.core.macro_model import load_from_yaml
+ from cli_anything.macrocli.core.routing import RoutingEngine
+ from cli_anything.macrocli.core.runtime import MacroRuntime, ExecutionResult
+ from cli_anything.macrocli.core.registry import MacroRegistry
+ try:
+ macro_def = load_from_yaml(macro_file)
+ except Exception as e:
+ if _json_output:
+ click.echo(json.dumps({"success": False, "error": str(e)}))
+ else:
+ click.echo(f"Error loading macro file: {e}", err=True)
+ if not _repl_mode:
+ sys.exit(1)
+ return
+ reg = MacroRegistry.__new__(MacroRegistry)
+ reg._cache = {macro_def.name: macro_def}
+ reg._scanned = True
+ reg.macros_dir = None
+ runtime = MacroRuntime(registry=reg, session=get_session())
+ result = runtime.execute(macro_def.name, params, dry_run=_dry_run)
+ else:
+ runtime = get_runtime()
+ result = runtime.execute(name, params, dry_run=_dry_run)
if _json_output:
output(result.to_dict())