当多个 Agent 同时在不同 worktree 里干活，靠手动点窗口很快就会乱。Orca CLI 命令把仓库、工作区、终端、文件和内置浏览器变成可脚本化的操作，让 agent 能先读取现场，再稳定地推进任务。

一、Orca CLI 能做什么

在终端用 orca 命令直接驱动 Orca（如 orca repo add）
在终端用 orca 命令直接驱动 Orca（如 orca repo add） · 图片来自 Orca 官方项目

Orca CLI 是 agent 驱动 Orca 的脚本化入口。它覆盖运行时状态、Repo、Worktree、Terminal、File 与内置浏览器：既能找到当前工作区、读取终端输出，也能创建任务终端、打开变更文件，或在浏览器里执行 snapshot → act → snapshot 循环。对多 Agent 工作流来说，价值不在“命令更多”，而在每一步都有明确对象和可读取结果。

先确认系统能找到 Orca，再查看帮助与运行状态。所有命令都可以加 --json；需要让 agent 消费输出时，结构化结果比面向人的界面文本更稳。

command -v orca
orca <cmd> --help
orca status --json
orca open --json

可以把这些入口理解为三层：运行时回答 Orca 是否可用，资源层回答仓库与 worktree 在哪里，操作层再进入终端、文件或浏览器。自动化如果跳过前两层，后续即使命令拼写正确，也可能缺少稳定目标；按层读取，则每一步都能用上一层得到的上下文继续。

二、运行时与选择器

Orca 可在前台启动服务而不打开桌面窗口。下面的端口、配对地址和参数顺序都按官方文档原样使用；该进程由 Ctrl-C 停止。

orca serve --port 6768 --pairing-address 100.64.1.20 --json

自动化最怕“操作了错误的窗口”。因此先给对象加选择器：仓库用 id，worktree 可以按活动项、当前项、绝对路径、分支或 issue 定位。脚本里优先写清选择器，不要依赖人眼看到的焦点。

--repo id:<repoId>
--worktree active|current
--worktree path:/abs/path
--worktree branch:feature-name
--worktree issue:123

active 指向 Orca 当前活动的 worktree；路径、分支和 issue 则适合已有稳定上下文的流程。先确定目标，再执行读写，是后面所有命令的共同原则。

三、Repo 与 Worktree 命令

先识别仓库

Repo 层负责列出、添加和查看仓库，也能设置 base ref 或搜索引用。新接入仓库时先列出和查看，再决定是否调整基准。

orca repo list
orca repo add --path /abs/path/to/repo
orca repo show --repo id:<id>
orca repo set-base-ref --repo id:<id> --ref origin/main
orca repo search-refs --repo id:<id> --query main --limit 10

再管理隔离工作区

Worktree 是并行 Agent 互不干扰的边界。可以先查看仓库下的工作区和当前项，再查看活动 worktree 的详情；创建时既可只命名，也可同时指定 agent 与 prompt。删除命令带有明确 id 与 force，应该放到任务确认结束之后。

orca worktree list --repo id:<id>
orca worktree ps
orca worktree current
orca worktree show --worktree active
orca worktree create --repo id:<id> --name fix-login
orca worktree create --name child-task --agent codex --prompt "..."
orca worktree set --worktree active --comment "..."
orca worktree rm --worktree id:<id> --force

需要表达父子关系或启动方式时，使用官方给出的关系 flag 与启动 flag。它们分别控制父 worktree、agent、prompt 和 setup 策略。

--parent-worktree active
--no-parent
--agent claude|codex
--prompt "..."
--setup run|skip|inherit

实际组织任务时，仓库和 worktree 不要混成一个概念。Repo 层保存仓库范围与 base ref，Worktree 层承载具体并行任务。先从 repo list 找到对象，再用 repo show 或 search-refs 核对上下文；进入 worktree 后，再用 list、current、show 判断哪个隔离工作区正在被操作。父子关系与 setup 策略也应在创建任务时明确，而不是等 Agent 启动后再猜。

四、Terminal 命令

终端是 agent 真正工作的现场。可靠流程不是反复发送文本，而是先列出终端、读取输出，再以 cursor 增量读取；确认终端进入 tui-idle 后，才继续推进。这样既保留上下文，也减少重复输入。

orca terminal list --worktree active
orca terminal read --terminal <h>
orca terminal read --terminal <h> --cursor <c> --limit 1000
orca terminal send --terminal <h> --text "continue" --enter
orca terminal wait --terminal <h> --for tui-idle --timeout-ms 300000

测试和开发服务可以各占一个终端。创建 tests 终端后，还能从已有终端水平分屏启动开发命令；任务结束再关闭明确的终端句柄。

orca terminal create --worktree active --title "tests" --command "npm test"
orca terminal split --terminal <h> --direction horizontal --command "npm run dev"
orca terminal close --terminal <h>

cursor 读取适合持续跟踪同一终端：第一次读取拿到现场，后续从指定 cursor 继续，并用 limit 控制返回量。send 的 --enter 会把文本送入终端，wait 则等待 tui-idle。把读取、发送和等待分开，Agent 才能在每次动作前后检查状态，而不是连续灌入多条输入。

五、内置浏览器命令：snapshot → act → snapshot

浏览器自动化采用 snapshot → act → snapshot：先进入页面并取得快照，从快照拿到元素 ref，再点击或填写；发生导航或点击后重新 snapshot，不能继续沿用旧 ref。下面的 @e3 与 @e1 都来自快照。

orca goto --url http://localhost:3000
orca snapshot
orca click --element @e3
orca fill --element @e1 --value "[email protected]"
orca wait --text "Welcome"
orca snapshot

需要留下页面证据时可截取当前画面或完整页面；遇到前端异常，则读取 console 与 network。设备切换也使用官方给出的设备名。

orca screenshot
orca full-screenshot
orca console --limit 50
orca network --limit 50
orca set device --name "iPhone 12"

移动模拟器与桌面操作入口

官方还提供移动模拟器和桌面 computer use。模拟器先列出设备并附加，再按 0–1 归一化坐标点击，也可以输入文本、返回主页或旋转方向。桌面操作则先列出应用，再按应用与元素索引点击，或向应用粘贴文本。

orca emulator list
orca emulator attach "<device>"
orca emulator tap 0.5 0.7
orca emulator type "hello"
orca emulator button home
orca emulator rotate landscape_left
orca computer list-apps
orca computer click --app com.apple.Safari --element-index 12
orca computer paste-text --app ... --text "hello"

六、File 命令

文件层适合把终端与代码审阅接起来：打开指定源码、查看 staged diff，或一次打开工作区里的变更。它不会替代判断，却能让 agent 与开发者围绕同一份实际变更沟通。

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

七、Agent 自动化最佳实践

⌘J 快速跳转 worktree——键盘优先的高效导航
⌘J 快速跳转 worktree——键盘优先的高效导航 · 图片来自 Orca 官方项目

第一，面向 agent 的关键查询使用 --json，并在不确定参数时查看帮助。第二，先用 repo 或 worktree 选择器锁定对象，不让“当前焦点”替脚本做决定。第三，坚持先读后写：先 status、list、show、terminal read 或 snapshot，确认现场后再 create、send、click；点击或导航后立即重新 snapshot。

第四，把长流程拆成可检查的小循环。终端操作以 read → send → wait → read 收口；浏览器操作以 snapshot → act → snapshot 收口；代码审阅则先打开变更，再决定下一步。每个循环都能留下清楚结果，失败时也知道应回到哪一层排查。

第五，并行任务始终绑定独立 worktree。让一个 Agent 的命令只作用于一个明确工作区，完成后先看 diff，再决定保留或删除。需要更高层的自动分派与结果汇总时，继续阅读 Orca 编排教程，不要把所有协调逻辑硬塞进单个终端脚本。

最后，脚本中出现句柄或 id 占位符时，应先用对应的 list、show、current、snapshot 或 read 找到真实对象。浏览器 ref 在导航或点击后必须重新 snapshot；终端则用 cursor 接续读取。把“对象是否仍有效”当成每轮动作的检查项，比单纯重试同一条写命令更容易保持流程清楚。

交给 Agent 执行前，还应把帮助、选择器和结构化输出当成固定检查清单：参数拿不准就先看 help，需要机器继续处理就保留 JSON，涉及仓库或工作区就写明 repo 与 worktree。这样命令的输入对象、执行动作和返回结果都更容易复核。

延伸阅读

🛫 账号被封 / IP 不干净？换个稳的节点就好了
很多「打不开、验证失败、被封号」的根源，都是节点乱跳、出口 IP 不干净。选一个稳定不跑路、地区固定的机场，账号更稳、访问更顺——这也是养号和顺利注册的前提。
🔥 看花渡机场推荐榜⚡ 机场测速排行榜

主题授权提示：请在后台主题设置-主题授权-激活主题的正版授权，授权购买：RiTheme官网

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。