agentremote-cli 1.0.0__py3-none-any.whl

remotecli/guides/GUIDE.md

@@ -0,0 +1,397 @@
+# remotecli 使用指南
+
+`remotecli` 是 AgentRemote 的 Agent 侧 CLI。AI 沙箱通过它调用远程客户机能力：桌面控制、远程 Shell、预定义 RPA 流程。
+
+这份文件是 `remotecli` 的主文档。旁边的 `agent.md`、`cua.md`、`shell.md`、`rpa.md` 只做速查入口，避免同一规则在多个文件里重复维护。
+
+## 一句话架构
+
+```text
+AI / remotecli --HTTP--> Middleware --MQTT--> Runtime --插件--> 桌面 / Shell / RPA
+```
+
+AI 不直接接触 MQTT，也不直接连接客户机 Runtime。它只调用 `remotecli`，`remotecli` 只访问 Middleware HTTP API。
+
+## 快速开始
+
+```bash
+python -m remotecli.cli \
+  --wait \
+  --middleware http://<MIDDLEWARE_IP>:9100 \
+  --tenant <TENANT_ID> \
+  --node <NODE_ID> \
+  --handle wch_v1_... \
+  shell info
+```
+
+常用全局参数：
+
+| 参数 | 说明 |
+|---|---|
+| `--config` | CLI 配置文件，默认使用 `remotecli/config/agentremote.cli.toml` |
+| `--middleware` | Middleware HTTP 地址 |
+| `--tenant` | 租户 ID |
+| `--node` | 目标客户机节点 ID |
+| `--agent` | Agent ID，可选 |
+| `--handle` | Auth Broker handle，格式通常为 `wch_v1_...` |
+| `--wait` | 提交底层任务后轮询最终结果，必须放在 `cua` / `shell` / `rpa` 前 |
+| `--wait-timeout` | 等待结果的最大秒数 |
+| `--poll-interval` | 轮询间隔秒数 |
+
+参数优先级遵循：命令行参数 > 环境变量 > TOML 配置 > 本地开发默认值。
+
+## 先用哪个命令
+
+普通 AI Agent 默认用 `agent` 子命令。只有需要底层能力时才降到 `cua`、`shell` 或 `rpa`。
+
+| 目标 | 优先命令 | 何时降级 |
+|---|---|---|
+| 执行 PowerShell / cmd | `agent ps` / `agent cmd` | 需要异步提交或完整底层返回时用 `shell` |
+| 打开或准备应用窗口 | `agent open <app>` | 要自定义启动脚本时用 `shell exec-script` |
+| 判断页面是否 ready | `agent probe` | 已有 `pid/window_id` 时用 `cua probe-window` |
+| 观察页面状态 | `agent observe` | 需要完整原始状态时加 `--format full` 或用 `cua get-window-state` |
+| 点击 / 输入 / 热键 | `agent click/type/key/hotkey` | 坐标、右键、拖拽、多窗口手选时用 `cua` |
+| 固定业务自动化流程 | `rpa run` | 不建议用 `agent` 拼固定 RPA 流程 |
+| 查询异步结果 | `result <trace_id>` | `agent` 默认已自动等待，一般不需要 |
+
+## Agent 高层入口
+
+```bash
+python -m remotecli.cli agent <action> [args]
+```
+
+`agent ...` 面向普通 AI 使用，默认会：
+
+- 等待任务最终结果。
+- 解包 Middleware 返回里的 `result.output` JSON 字符串。
+- GUI 操作前按应用名自动执行 `list-apps -> list-windows`，拿到真实 `pid/window_id`。
+- 使用同一个 `--session` 时缓存窗口引用，后续步骤复用，失败时自动刷新一次。
+
+常用命令：
+
+| 命令 | 用途 | 示例 |
+|---|---|---|
+| `ps` | 执行 PowerShell | `agent ps "Get-Process | Select-Object -First 5"` |
+| `cmd` | 执行 cmd | `agent cmd "whoami"` |
+| `open` | 确保应用主窗口存在并写入 session 缓存 | `agent open firefox --session crm-export-001` |
+| `probe` | 探测关键目标是否出现 | `agent probe firefox --targets "Download Export,Start Date"` |
+| `observe` | 返回窗口 compact 状态摘要 | `agent observe firefox --mode uia --targets "Username,Password"` |
+| `click` | 语义点击目标 | `agent click firefox "Sign in"` |
+| `type` | 定位目标后输入 | `agent type firefox "Username" "user@example.com"` |
+| `key` | 发送单键 | `agent key firefox escape` |
+| `hotkey` | 发送组合键 | `agent hotkey firefox ctrl,l` |
+| `scroll` | 滚动窗口 | `agent scroll firefox --direction down --amount 3 --dispatch foreground` |
+| `session-clear` | 清理窗口缓存 | `agent session-clear crm-export-001` |
+
+同一个 GUI 任务建议固定一个 session：
+
+```bash
+python -m remotecli.cli agent open firefox --session crm-export-001
+python -m remotecli.cli agent probe firefox --targets "Download Export,Start Date" --session crm-export-001
+python -m remotecli.cli agent click firefox "Download Export" --session crm-export-001
+python -m remotecli.cli agent session-clear crm-export-001
+```
+
+也可以用环境变量省略每条命令的 `--session`：
+
+```powershell
+$env:REMOTECLI_SESSION="crm-export-001"
+python -m remotecli.cli agent probe firefox --targets "Download Export"
+python -m remotecli.cli agent click firefox "Download Export"
+python -m remotecli.cli agent session-clear
+```
+
+窗口缓存控制：
+
+- `--refresh-window`：强制重新解析窗口并更新缓存。
+- `--no-window-cache`：完全绕过缓存，适合多窗口排查。
+- 不传 session：不读写窗口缓存。
+
+### probe 和 observe
+
+页面 ready check 优先用 `agent probe`，不要一上来扫完整页面。
+
+```bash
+python -m remotecli.cli agent probe firefox --targets "Download Export,Start Date" --mode smart
+python -m remotecli.cli agent observe firefox --mode uia --targets "Username,Password,Sign in"
+python -m remotecli.cli agent observe firefox --mode vision
+python -m remotecli.cli agent observe firefox --mode som-full
+```
+
+模式含义：
+
+| 模式 | 用途 |
+|---|---|
+| `uia` | 读取 UIA/AX 树，适合后台系统、普通表单、调试页面结构 |
+| `vision` | 只截图，不遍历 UIA/SOM |
+| `som-full` | 全量 YOLO/OCR + 标注图，仅用于 UIA 缺失后的兜底或调试 |
+| `smart` | `probe` 默认模式，先 UIA，目标未命中再走 SOM/OCR |
+
+`agent click/type` 使用独立 SmartFind 定位链路，不依赖 `observe` 返回的元素全集。如果 `observe` 结果里已经有目标元素，下一步直接行动，不要重复 observe。
+
+## CUA 桌面控制
+
+```bash
+python -m remotecli.cli [global flags] cua <action> [args]
+```
+
+`cua` 是底层桌面控制入口。普通 Agent 优先用 `agent`；以下场景直接用 `cua`：
+
+- 已经知道准确 `pid/window_id`。
+- 需要坐标点击、右键、双击、拖拽、真实滚轮事件。
+- 一个应用有多个窗口，需要人工选择窗口。
+- 需要异步提交任务并保留 `trace_id`。
+
+常用命令：
+
+| 命令 | 用途 | 示例 |
+|---|---|---|
+| `list-apps` | 列出运行应用 | `cua list-apps --query Firefox` |
+| `list-windows` | 列出窗口 | `cua list-windows --pid 17376` |
+| `launch-app` | 启动应用 | `cua launch-app --name notepad.exe` |
+| `bring-to-front` | 窗口置前 | `cua bring-to-front --pid 17376 --window-id 7014188` |
+| `get-window-state` | 获取窗口状态或截图 | `cua get-window-state --pid 17376 --window-id 7014188 --mode uia` |
+| `probe-window` | 探测关键目标 | `cua probe-window --pid 17376 --window-id 7014188 --targets "Save,Cancel"` |
+| `click` | 语义或坐标点击 | `cua click --pid 17376 --window-id 7014188 --target 保存` |
+| `type-text` | 输入文本 | `cua type-text --pid 17376 --window-id 7014188 --target 文件名 --text report.txt` |
+| `set-value` | 设置控件值 | `cua set-value --pid 17376 --window-id 7014188 --target 数量 --value 10` |
+| `hotkey` | 组合键 | `cua hotkey --pid 17376 --window-id 7014188 --keys ctrl,s` |
+| `press-key` | 单键 | `cua press-key --pid 17376 --window-id 7014188 --key enter` |
+| `scroll` | 滚动 | `cua scroll --pid 17376 --window-id 7014188 --direction down --amount 3 --dispatch foreground` |
+| `move-mouse` | 验证屏幕坐标落点 | `cua move-mouse --x 500 --y 300` |
+| `drag` | 按住拖拽 | `cua drag --pid 17376 --window-id 7014188 --from-x 100 --from-y 100 --to-x 400 --to-y 100` |
+
+定位规则：
+
+- 优先用 `--target` 语义定位，不要优先猜坐标。
+- `click/type-text/set-value` 支持 `--locate-mode smart|uia|som`。
+- `smart` 默认先 UIA-only，UIA 找不到才截图 + SOM/OCR。
+- `uia` 适合可访问控件，速度最快。
+- `som` 适合无障碍树缺失或视觉复杂页面。
+- 坐标使用客户机物理屏幕像素，不依赖固定分辨率或 DPI。
+- 坐标不确定时先 `move-mouse --x ... --y ...` 验证落点。
+- 普通鼠标移动不要用 `drag`；只有明确需要按住拖拽时才用。
+
+`get-window-state` 是唯一截图入口：
+
+```bash
+python -m remotecli.cli cua get-window-state --pid 17376 --window-id 7014188 --mode vision
+python -m remotecli.cli cua get-window-state --pid 17376 --window-id 7014188 --mode som-full
+```
+
+如果 `click/type-text/set-value --target` 返回 `TARGET_NOT_RESOLVED`，通常表示目标不可见、页面未加载、被弹窗挡住或 UIA/SOM 都未命中。先 `get-window-state` 或 `agent observe` 看当前窗口，处理遮挡后再重试，不要重复点击背后的目标。
+
+## Shell 远程命令
+
+```bash
+python -m remotecli.cli [global flags] shell <action> [args]
+```
+
+`shell` 走 `native.shell` capability，在目标 Runtime 节点本机执行。适合环境探测、短脚本、启动 Windows 应用；涉及桌面交互时，启动后继续用 `agent` 或 `cua` 操作窗口。
+
+| 命令 | 用途 | 示例 |
+|---|---|---|
+| `info` | 获取目标机器环境 | `shell info` |
+| `exec` | 执行单条命令 | `shell exec --cmd "whoami"` |
+| `exec-script` | 执行多行脚本 | `shell exec-script --shell powershell --script "Get-Process | Select-Object -First 5"` |
+
+PowerShell 脚本建议用单引号包住整段 `--script`，避免 `$_.Name` 被本地 shell 展开。
+
+打开 Windows 应用时，不要猜 AppID，先查真实启动目标：
+
+```bash
+python -m remotecli.cli shell exec-script --shell powershell --script 'Get-StartApps | Where-Object {$_.Name -like "*微信*"}'
+python -m remotecli.cli shell exec-script --shell powershell --script '$app = Get-StartApps | Where-Object {$_.Name -like "*微信*"} | Select-Object -First 1; Start-Process ("shell:AppsFolder\" + $app.AppID)'
+```
+
+## RPA 流程
+
+```bash
+python -m remotecli.cli [global flags] rpa <action> [args]
+```
+
+`rpa` 用于执行 Runtime 侧预定义的 Robot Framework 流程。当前可用流程：
+
+| Flow ID | 任务 |
+|---|---|
+| `crm-transaction-filter` | `01 - Fill Transaction Date Range` |
+
+示例：
+
+```bash
+python -m remotecli.cli --wait rpa run \
+  --flow crm-transaction-filter \
+  --task "01 - Fill Transaction Date Range" \
+  --param START_DATE=20260701 \
+  --param END_DATE=20260701
+```
+
+规则：
+
+- 参数用重复的 `--param KEY=VALUE` 传入。
+- Runtime 会把参数转为 Robot Framework 变量：`--variable KEY:VALUE`。
+- Robot 文件里用 `${KEY}` 读取。
+- 参数名必须匹配 `[A-Za-z_][A-Za-z0-9_]*`。
+- 参数值按字符串传递；含空格或特殊字符时按当前 shell 规则给整个 `KEY=VALUE` 加引号。
+
+## 结果和输出
+
+底层 `cua` / `shell` / `rpa` 默认异步提交，返回：
+
+```json
+{"trace_id": "task_xxx", "status": "queued"}
+```
+
+查询结果：
+
+```bash
+python -m remotecli.cli result <trace_id>
+```
+
+自动等待结果：
+
+```bash
+python -m remotecli.cli --wait shell info
+python -m remotecli.cli --wait --wait-timeout 60 cua click --pid 17376 --window-id 7014188 --target 保存
+```
+
+注意：`--wait` 必须放在 `shell` / `cua` / `rpa` 前。`agent ...` 默认已经等待最终结果，不需要顶层 `--wait`。
+
+`agent` 命令输出会尽量压平成 AI 友好的 JSON：
+
+```json
+{
+  "ok": true,
+  "trace_id": "task_xxx",
+  "stdout": "...",
+  "stderr": "",
+  "exit_code": 0,
+  "json": null,
+  "error": ""
+}
+```
+
+GUI 类 `agent` 命令还会带：
+
+```json
+{
+  "ok": true,
+  "action": "click",
+  "pid": 8748,
+  "window_id": 460902,
+  "title": "GitHub - Mozilla Firefox",
+  "window_cached": true
+}
+```
+
+## AI 集成
+
+推荐让 AI 通过 subprocess 调 CLI，最容易隔离依赖和认证配置：
+
+```python
+import json
+import subprocess
+
+BASE = [
+    "python", "-m", "remotecli.cli",
+    "--middleware", "http://10.0.0.5:9100",
+    "--tenant", "acme_shanghai",
+    "--node", "sh_win_01",
+    "--handle", "wch_v1_...",
+]
+
+def call_remotecli(args: list[str]) -> dict:
+    result = subprocess.run(BASE + args, capture_output=True, text=True, timeout=60)
+    result.check_returncode()
+    return json.loads(result.stdout)
+
+call_remotecli(["agent", "ps", "whoami"])
+call_remotecli(["agent", "click", "firefox", "Sign in"])
+call_remotecli(["--wait", "shell", "info"])
+```
+
+也可以直接用 Python client：
+
+```python
+from remotecli.client import RemoteCliClient
+
+client = RemoteCliClient(
+    middleware_url="http://10.0.0.5:9100",
+    tenant_id="acme_shanghai",
+    node_id="sh_win_01",
+    handle="wch_v1_...",
+)
+
+queued = client.submit("desktop.cua", "click", {
+    "pid": 17376,
+    "window_id": 7014188,
+    "target": "保存",
+})
+result = client.poll_result(queued["trace_id"])
+```
+
+## 典型流程
+
+打开应用、输入并保存，普通 Agent 优先这样写：
+
+```bash
+python -m remotecli.cli agent open notepad --session note-001
+python -m remotecli.cli agent type notepad "Text Editor" "hello world" --session note-001
+python -m remotecli.cli agent hotkey notepad ctrl,s --session note-001
+python -m remotecli.cli agent type notepad "文件名" "hello.txt" --session note-001
+python -m remotecli.cli agent key notepad enter --session note-001
+python -m remotecli.cli agent session-clear note-001
+```
+
+已有 `pid/window_id` 或需要底层调试时：
+
+```bash
+python -m remotecli.cli --wait cua get-window-state --pid <pid> --window-id <wid> --mode uia
+python -m remotecli.cli --wait cua click --pid <pid> --window-id <wid> --target 保存 --locate-mode smart
+```
+
+## 错误处理
+
+| 错误 | 含义 | 处理 |
+|---|---|---|
+| `AUTH_HANDLE_REQUIRED` | strict 模式下没传 handle | 加 `--handle wch_v1_...` |
+| `AUTH_HANDLE_INVALID` | handle 无效或过期 | 重新签发 handle |
+| `AUTH_TENANT_DENIED` | handle 不允许访问该 tenant | 检查 `--tenant` |
+| `busy` / `409` | 节点被其他 Agent 租约占用 | 稍后重试或换 `--node` |
+| `NODE_NO_RESPONSE` | Middleware 下发后 Runtime 无 ACK | 检查 Runtime、Broker、节点注册状态 |
+| `Unknown capability` | 目标 capability 未注册 | 检查 Runtime 插件是否加载 |
+| `TARGET_NOT_RESOLVED` | 目标不可见或定位失败 | 先观察窗口，处理弹窗/遮挡/页面加载后重试 |
+
+## 常见问题
+
+**截图在哪里？**
+`cua get-window-state --mode vision` 返回 screenshot 元数据，例如 `local_path`、`size_bytes`、`width`、`height`。截图 PNG 保存在客户机本地 `runtime_state/screenshots/`。Agent 与 Runtime 同机时可直接读 `local_path`；跨机访问需要另行提供文件访问通道。
+
+**handle 是必须的吗？**
+取决于 Middleware 启动模式。demo mode 下 handle 可选；strict auth 模式下所有任务都必须带 handle。
+
+**能同时控制多台客户机吗？**
+能。不同 `--node` 指向不同客户机。一台客户机同一时刻只允许一个 Agent 独占控制。
+
+**四个子文档还要维护吗？**
+只维护速查和入口说明。完整规则集中在本文件，避免重复内容互相过期。
+
+## 目录
+
+```text
+remotecli/
+├── cli.py
+├── client.py
+├── agent.py
+├── cua.py
+├── shell.py
+├── rpa.py
+├── config/
+│   └── agentremote.cli.toml
+└── guides/
+    ├── GUIDE.md      # 主文档
+    ├── agent.md      # Agent 高层命令速查
+    ├── cua.md        # CUA 底层命令速查
+    ├── shell.md      # Shell 命令速查
+    └── rpa.md        # RPA 流程速查
+```

remotecli/guides/agent.md

@@ -0,0 +1,60 @@
+# Agent 命令速查
+
+完整规则见 [GUIDE.md](./GUIDE.md)。本文件只保留普通 AI Agent 最常用入口。
+
+`agent` 是默认推荐入口：
+
+```bash
+python -m remotecli.cli agent <action> [args]
+```
+
+它会自动等待最终结果、解包 `result.output`，并在 GUI 操作前按应用名查找真实 `pid/window_id`。
+
+## 什么时候用
+
+| 目标 | 命令 |
+|---|---|
+| 执行 PowerShell | `agent ps "<script>"` |
+| 执行 cmd | `agent cmd "<command>"` |
+| 确保应用窗口存在 | `agent open <app>` |
+| 判断按钮/输入框是否出现 | `agent probe <app> --targets "A,B"` |
+| 看窗口 compact 状态 | `agent observe <app>` |
+| 点击目标 | `agent click <app> "<target>"` |
+| 输入文本 | `agent type <app> "<target>" "<text>"` |
+| 单键 | `agent key <app> enter` |
+| 组合键 | `agent hotkey <app> ctrl,l` |
+| 滚动 | `agent scroll <app> --direction down --amount 3` |
+| 清理窗口缓存 | `agent session-clear <session>` |
+
+## 常用示例
+
+```bash
+python -m remotecli.cli agent ps "Get-Process | Select-Object -First 5"
+python -m remotecli.cli agent open firefox --session crm-export-001
+python -m remotecli.cli agent probe firefox --targets "Download Export,Start Date" --session crm-export-001
+python -m remotecli.cli agent click firefox "Download Export" --session crm-export-001
+python -m remotecli.cli agent session-clear crm-export-001
+```
+
+## 关键规则
+
+- `agent ...` 默认等待最终结果，不需要顶层 `--wait`。
+- 同一个 GUI 任务建议固定一个 `--session`，避免每步重复查窗口。
+- 页面 ready check 优先用 `probe`，不要先扫完整页面。
+- `observe --mode uia` 用于查看页面结构；`--mode vision` 只截图；`--mode som-full` 只用于 UIA 缺失后的调试。
+- `click/type` 有自己的 SmartFind 定位链路，不依赖 `observe` 返回完整元素列表。
+- 多窗口手选、坐标点击、右键、拖拽、异步任务、固定 RPA 流程，降到底层 `cua` / `shell` / `rpa`。
+
+## 窗口缓存
+
+```powershell
+$env:REMOTECLI_SESSION="crm-export-001"
+python -m remotecli.cli agent probe firefox --targets "Start Date,End Date"
+python -m remotecli.cli agent click firefox "Download Export"
+python -m remotecli.cli agent session-clear
+```
+
+调试缓存：
+
+- `--refresh-window`：强制重新解析并更新缓存。
+- `--no-window-cache`：绕过缓存。

remotecli/guides/cua.md

@@ -0,0 +1,60 @@
+# CUA 命令速查
+
+完整规则见 [GUIDE.md](./GUIDE.md)。本文件只保留底层桌面控制速查。
+
+```bash
+python -m remotecli.cli [global flags] cua <action> [args]
+```
+
+普通 AI Agent 优先用 `agent` 子命令。只有需要 `pid/window_id`、坐标、右键、拖拽、多窗口手选或异步任务时，直接用 `cua`。
+
+## 常用命令
+
+| 目标 | 命令示例 |
+|---|---|
+| 查运行应用 | `cua list-apps --query Firefox` |
+| 查窗口 | `cua list-windows --pid 17376` |
+| 启动应用 | `cua launch-app --name notepad.exe` |
+| 前置窗口 | `cua bring-to-front --pid 17376 --window-id 7014188` |
+| 获取 UIA 状态 | `cua get-window-state --pid 17376 --window-id 7014188 --mode uia` |
+| 只截图 | `cua get-window-state --pid 17376 --window-id 7014188 --mode vision` |
+| SOM/OCR 调试 | `cua get-window-state --pid 17376 --window-id 7014188 --mode som-full` |
+| 探测目标 | `cua probe-window --pid 17376 --window-id 7014188 --targets "Save,Cancel"` |
+| 语义点击 | `cua click --pid 17376 --window-id 7014188 --target 保存` |
+| 输入文本 | `cua type-text --pid 17376 --window-id 7014188 --target 文件名 --text report.txt` |
+| 设置控件值 | `cua set-value --pid 17376 --window-id 7014188 --target 数量 --value 10` |
+| 热键 | `cua hotkey --pid 17376 --window-id 7014188 --keys ctrl,s` |
+| 单键 | `cua press-key --pid 17376 --window-id 7014188 --key enter` |
+| 滚动 | `cua scroll --pid 17376 --window-id 7014188 --direction down --amount 3 --dispatch foreground` |
+| 验证坐标 | `cua move-mouse --x 500 --y 300` |
+| 拖拽 | `cua drag --pid 17376 --window-id 7014188 --from-x 100 --from-y 100 --to-x 400 --to-y 100` |
+
+底层命令默认异步返回 `trace_id`。需要等待时：
+
+```bash
+python -m remotecli.cli --wait cua click --pid 17376 --window-id 7014188 --target 保存
+```
+
+`--wait` 必须放在 `cua` 前。
+
+## 定位规则
+
+- 优先用 `--target`，不要优先猜坐标。
+- `click/type-text/set-value` 支持 `--locate-mode smart|uia|som`。
+- `smart` 默认先 UIA-only，UIA 找不到才截图 + SOM/OCR。
+- `uia` 适合可访问控件，速度最快。
+- `som` 适合 UIA 缺失或视觉复杂页面。
+- 坐标使用客户机物理屏幕像素。
+- 坐标不确定时先 `move-mouse` 验证落点。
+- 普通鼠标移动不要用 `drag`；只有明确需要按住拖拽时才用。
+
+## 失败处理
+
+`TARGET_NOT_RESOLVED` 表示目标不可见、页面未加载、被弹窗挡住或定位链路未命中。先观察窗口状态：
+
+```bash
+python -m remotecli.cli --wait cua get-window-state --pid 17376 --window-id 7014188 --mode uia
+python -m remotecli.cli --wait cua get-window-state --pid 17376 --window-id 7014188 --mode vision
+```
+
+处理弹窗、遮挡或页面加载后再重试，不要重复点击背后的目标。

remotecli/guides/rpa.md

@@ -0,0 +1,45 @@
+# RPA 命令速查
+
+完整规则见 [GUIDE.md](./GUIDE.md)。本文件只保留 Robot Framework 流程速查。
+
+```bash
+python -m remotecli.cli [global flags] rpa <action> [args]
+```
+
+`rpa` 用于执行 Runtime 侧已经注册的固定业务流程，不用于临时桌面操作。
+
+## 常用命令
+
+```bash
+python -m remotecli.cli rpa list-flows
+```
+
+```bash
+python -m remotecli.cli --wait rpa run \
+  --flow crm-transaction-filter \
+  --task "01 - Fill Transaction Date Range" \
+  --param START_DATE=20260701 \
+  --param END_DATE=20260701
+```
+
+当前流程：
+
+| Flow ID | 任务 |
+|---|---|
+| `crm-transaction-filter` | `01 - Fill Transaction Date Range` |
+
+## 参数规则
+
+- 参数用重复的 `--param KEY=VALUE` 传入。
+- Runtime 会转成 Robot Framework 变量：`--variable KEY:VALUE`。
+- Robot 文件里用 `${KEY}` 读取。
+- 参数名必须匹配 `[A-Za-z_][A-Za-z0-9_]*`。
+- 参数值按字符串传递；含空格或特殊字符时给整个 `KEY=VALUE` 加引号。
+
+## 等待结果
+
+底层 `rpa` 默认异步返回 `trace_id`。自动等待时把 `--wait` 放在 `rpa` 前：
+
+```bash
+python -m remotecli.cli --wait --wait-timeout 120 rpa run --flow crm-transaction-filter --task "01 - Fill Transaction Date Range"
+```

remotecli/guides/shell.md

@@ -0,0 +1,49 @@
+# Shell 命令速查
+
+完整规则见 [GUIDE.md](./GUIDE.md)。本文件只保留远程 Shell 速查。
+
+```bash
+python -m remotecli.cli [global flags] shell <action> [args]
+```
+
+`shell` 走 `native.shell` capability，在目标 Runtime 节点本机执行。适合环境探测、短脚本、启动应用；桌面交互继续用 `agent` 或 `cua`。
+
+## 常用命令
+
+```bash
+python -m remotecli.cli --wait shell info
+python -m remotecli.cli --wait shell exec --cmd "whoami"
+python -m remotecli.cli --wait --wait-timeout 60 shell exec --cmd "dir C:\\"
+```
+
+执行脚本：
+
+```bash
+python -m remotecli.cli --wait shell exec-script --shell powershell --script "Get-Process | Select-Object -First 5"
+python -m remotecli.cli --wait shell exec-script --shell cmd --script "@echo off\r\necho Hello"
+python -m remotecli.cli --wait shell exec-script --shell bash --script "echo hello; ls -la"
+```
+
+支持的 shell 取决于目标 Runtime 机器，通常包括 `cmd`、`powershell`、`pwsh`、`bash`、`sh`。
+
+## 打开 Windows 应用
+
+不要猜 AppID，先查真实启动目标：
+
+```bash
+python -m remotecli.cli --wait shell exec-script --shell powershell --script 'Get-StartApps | Where-Object {$_.Name -like "*微信*"}'
+python -m remotecli.cli --wait shell exec-script --shell powershell --script '$app = Get-StartApps | Where-Object {$_.Name -like "*微信*"} | Select-Object -First 1; Start-Process ("shell:AppsFolder\" + $app.AppID)'
+```
+
+然后用 `agent` 或 `cua` 操作窗口：
+
+```bash
+python -m remotecli.cli agent probe 微信 --targets "进入微信"
+python -m remotecli.cli agent click 微信 "进入微信"
+```
+
+## 关键规则
+
+- 底层 `shell` 默认异步返回 `trace_id`；自动等待时把 `--wait` 放在 `shell` 前。
+- PowerShell 脚本建议用单引号包住整段 `--script`，避免 `$_.Name` 被本地 shell 展开。
+- 长时间任务设置 `--wait-timeout` 或底层命令自己的 `--timeout`。

remotecli/rpa.py

@@ -0,0 +1,57 @@
+"""
+remotecli rpa — RPA 流程执行子命令.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict
+
+from .client import RemoteCliClient
+
+_PARAM_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class RpaCommands:
+    """RPA 流程命令构建器。"""
+
+    def __init__(self, client: RemoteCliClient) -> None:
+        self._client = client
+
+    def run(
+        self,
+        flow: str,
+        task: str = "",
+        timeout_sec: int = 180,
+        params: Dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
+        """Execute an RPA flow."""
+        args: Dict[str, Any] = {"flow": flow, "task": task}
+        normalized_params = _normalize_params(params)
+        if normalized_params:
+            args["params"] = normalized_params
+        return self._client.submit(
+            capability_id=flow,  # flow id IS the capability id
+            tool="run",
+            args=args,
+            timeout_sec=timeout_sec,
+        )
+
+    def list_flows(self) -> Dict[str, Any]:
+        """List available RPA flows."""
+        caps = self._client.list_capabilities()
+        capabilities = caps.get("capabilities", [])
+        rpa_flows = [c for c in capabilities if c.get("runner") == "rpa"]
+        return {"flows": rpa_flows}
+
+
+def _normalize_params(params: Dict[str, Any] | None) -> Dict[str, str]:
+    if not params:
+        return {}
+    normalized: Dict[str, str] = {}
+    for key, value in params.items():
+        name = str(key).strip()
+        if not _PARAM_NAME_RE.match(name):
+            raise ValueError(f"invalid RPA param name: {name}")
+        normalized[name] = "" if value is None else str(value)
+    return normalized