CLI 实战：工作树、终端与文件命令

工作树命令

orca worktree ps --json                 # 列出全部工作树
orca worktree create --repo id:<repoId> --name my-task --issue 123 --json
orca worktree current --json            # 当前 shell 目录所在的工作树
orca worktree set --worktree active --comment "reproduced bug" --json
orca worktree rm --worktree id:<id> --force --json

• create 支持 --issue 关联任务；还有 --worktree new-child 建父子工作树（编排场景）
• set --comment 就是 Worktree Checkpoints 的入口（模块三展开）

终端命令

orca terminal list --json                         # 全部终端
orca terminal read --json                         # 读取当前终端缓冲
orca terminal send --text "continue" --enter --json   # 发送按键/文本
orca terminal wait --for tui-idle --timeout-ms 30000 --json  # 等 TUI 空闲
orca terminal create --worktree path:/projects/app --command "npm test" --json
orca terminal split --direction vertical --command "npm run dev" --json

关键能力是 terminal wait——脚本可以「发一条消息，等到 Agent 空闲，再读输出」，把异步的 Agent 变成可同步驱动的流程。

需要跟踪多 Agent 并拥有完成语义时，别用裸终端 prompt，用模块三的 Orchestration。

文件命令

orca file open src/App.tsx
orca file diff src/App.tsx --staged
orca file open-changed --mode both

shell 当前目录不在目标工作树内时，加 --worktree <selector> 显式指定。

浏览器与模拟器（回顾 + 补充）

orca goto --url https://example.com --json
orca snapshot --json        # 元素引用 @e1...
orca click --element @e3 --json
orca fill --element @e1 --value "hi" --json
orca screenshot --json
orca set device --name "iPhone 12" --json   # 响应式

补充两个参数：--worktree <selector>、--device <udid-or-name>、--emulator <id> 用于显式指定目标。模拟器：orca emulator list / attach / tap 0.5 0.7 / type / gesture / rotate landscape_left / kill。

浏览器 Profiles 的 CLI 侧

orca tab profile list --json
orca tab profile create --no-ua-spoof      # 保持原生 UA 的 profile
orca tab profile set / clone / use-default

脚本化测试不同登录身份的必备。

落地练习：写一个 CLI 脚本

1. 用 orca worktree create 建一个测试工作树（--name cli-demo）
2. orca terminal create --command "npm test" 在里面跑一次测试
3. orca terminal wait --for tui-idle 等它结束，再 read 读结果
4. 用 orca file open src/App.tsx 打开一个文件
5. 把 1~4 包进一个 bash 脚本，加 --json 全链路

怎么判断做对了？——你能写出一段「创建工作树 → 跑命令 → 等空闲 → 读输出」的完整脚本，并知道何时该改用 Orchestration。

卡住了怎么办？ selector 报错：确认语法（path: 用绝对路径，id: 用 orca worktree ps --json 查到的值）；wait --for tui-idle 超时：把 --timeout-ms 调大。

小结

1. selector 优于长 ID：active / path: / branch: / id:
2. 工作树：ps / create / set / rm；create 支持 --issue 与父子工作树
3. 终端：send + wait 让异步 Agent 可同步驱动
4. 文件：open / diff / open-changed，跨目录加 --worktree
5. 浏览器与模拟器全可脚本化，Profiles 也有 CLI 入口

下一节，Orca Skills 注册表与 MCP。