🐋 Orca 完全教程

什么是 Orca

Orca 是一个桌面 AI 开发环境（ADE），专为使用 AI 编码助手的专业开发者设计。它的核心理念是：

• 每个任务一个 git worktree — 不再需要 stash 或切换分支，每个任务在独立的磁盘副本上工作
• 多个 Agent 并行运行 — 同时启动 Claude Code、Codex、Cursor CLI 等，各自在独立 worktree 中工作
• 本地运行，用你自己的订阅 — Orca 不是模型，它调用你已有的 agent 订阅
• 完整的开发环境 — 内置终端、编辑器、浏览器、Diff 查看器、Design Mode

支持的 Agent

安装指南

macOS

# 方式一：Homebrew
brew install --cask stablyai/orca/orca

# 方式二：直接下载 DMG
# 从 GitHub Releases 下载对应芯片的 DMG
# https://github.com/stablyai/orca/releases

Windows

从 GitHub Releases 下载安装程序 EXE 运行即可。建议在 Settings → Terminal 中将默认 shell 设为 PowerShell。

Linux

提供 AppImage 和 .deb 两种格式，从 GitHub Releases 下载。

首次启动

1. Orca 会请求访问你的 home 目录（用于添加仓库）
2. 如果检测到已有的 ~/.claude、~/.codex 或 Ghostty 配置，会提示导入
3. 进入空的主界面后，点击 Add Repo 添加你的第一个项目

第一次使用：3-Agent 并行任务

这是官方推荐的入门流程，5 分钟内完成三个 agent 并行跑同一个任务。

fix-login-race   → Claude Code
fix-login-race-2 → Codex
fix-login-race-3 → Cursor CLI

Worktree 详解

Orca 是「worktree 原生」的。每个任务有自己的磁盘副本，agent 之间互不干扰。

Worktree 的生命周期

1. 创建 — 指定任务名、起始 ref，可选关联 Linear/GitHub issue
2. 工作 — 所有终端、编辑器标签、浏览器标签都限定在当前 worktree
3. 审查 — 查看相对于起始 ref 的 diff，用 Annotate AI Diff 批注
4. 提交 — 直接在 Orca 内 commit、push、开 PR
5. 归档/删除 — 一键删除 worktree 及其关联分支

创建时的起始 ref 选项

侧边栏操作

• 置顶（Pin） — 右键 → Pin，把常用 worktree 固定在项目顶部
• 多选 — 按住 Cmd（Windows/Linux 是 Ctrl）点选多个，或 Shift 选范围
• 重命名 — 双击侧边栏中的 worktree 标题
• 排序 — 拖动项目行调整顺序
• 快速跳转 — Cmd-J 打开 Jump Palette

Agent 与会话

状态指示

每个标签页上有一个小圆点，显示 agent 的当前状态：

Agent 仪表板

侧边栏的每个 worktree 卡片上显示其 agent 会话状态，让你一眼看到所有 agent 的工作情况，不需要逐个切换查看。需要关注的 worktree 会加粗显示。

会话恢复

• Agent 退出后（正常或崩溃），标签页会显示一个 Restart 按钮，一键重启同一个 agent
• Orca 支持 Session Restore — 重启应用后恢复所有 worktree 和 agent 会话
• Codex 的 Restart 还会保留当前使用的账号

标签页与分屏

每个 worktree 可以有多个标签页（终端、编辑器、浏览器），支持拖拽分屏：

• 拖动标签页到窗口右边缘 → 垂直分屏
• 拖动标签页到窗口底边缘 → 水平分屏
• 每个分屏可以独立切换 worktree

CLI 基础

Orca CLI 让你从任何 shell 控制正在运行的 Orca 编辑器。这是自动化和脚本化的核心。

启用 CLI

1. 在 Orca 中打开 Settings → Experimental → CLI，点击注册
2. 验证安装：

command -v orca    # 确认 orca 命令可用
orca status --json  # 确认 Orca 运行中且 CLI 可连接

npx skills add https://github.com/stablyai/orca --skill orca-cli

选择器（Selectors）

大多数命令接受选择器来指定目标，而不是完整 ID：

通用约定

• 所有命令支持 --json 输出机器可读格式（脚本中务必使用）
• 如果 Orca 未运行，先用 orca open --json 启动
• 操作终端时，先读后写 — 不确定终端在等什么时，先 orca terminal read 再 send

Worktree 命令

创建 Worktree 的完整参数

orca worktree create \
  --repo id:abc123 \
  --name fix-auth-bug \
  --agent claude \
  --prompt "修复认证模块的竞态条件" \
  --parent-worktree active \
  --issue 42 \
  --json

Terminal 命令

控制 agent 终端的输入输出。终端 handle 在 Orca 重启后会变化，需要重新获取。

读取大量终端输出

# 第一次读取
orca terminal read --terminal h1 --cursor 0 --limit 1000 --json

# 用返回的 nextCursor 继续读取
orca terminal read --terminal h1 --cursor 1000 --limit 1000 --json

File 命令

在 Orca 编辑器中打开文件和查看 diff。路径相对于选中的 worktree。

如果当前 shell 不在目标 worktree 目录中，用 --worktree 指定：

orca file open src/main.py --worktree branch:feature-auth --json

Browser 命令

控制 Orca 内置的 worktree 级浏览器（不是外部浏览器）。采用「快照 → 操作 → 快照」的交互模式。

多 Agent 编排（Orchestration）详解

这是 Orca 最强大也最复杂的功能。编排提供了一套结构化的多 agent 协调机制，包括：

• 共享收件箱 — agent 之间的消息传递
• 任务记录 — 带规格、依赖和状态的任务项
• 分发状态 — 任务分配给终端的追踪
• Worker 完成消息 — 标准化的完成报告
• 决策门 — 阻塞任务直到决策被解决

核心概念

消息（Messages）

终端间的持久化笔记，支持以下类型：

任务（Tasks）

带规格说明和依赖的工作项，状态流转：

pending → ready → dispatched → completed / failed / blocked

分发（Dispatches）

将任务分配给终端。任务可以用新的分发上下文重试。完成权限来自活跃的分发上下文——worker 的完成消息和心跳消息必须同时包含 taskId 和 dispatchId。

决策门（Decision Gates）

协调者拥有的问题，会阻塞相关任务直到被解决。用于需要人工决策或跨 agent 确认的场景。

手动编排流程

完整的手动编排一个任务给 worker 的流程：

orca status --json                    # Orca 运行时状态
orca worktree ps --json               # 运行中的 worktree 进程
orca terminal list --json             # 所有终端列表
orca orchestration task-list --json   # 当前任务列表

orca orchestration task-create \
  --task-title "修复认证竞态条件" \
  --display-name "auth-race-fix" \
  --spec "修复 src/auth/ 目录下的竞态条件 bug，确保并发登录请求不会导致 token 重复生成" \
  --json

# 创建带 agent 的 worktree
orca worktree create \
  --repo id:abc123 \
  --name worker-auth-fix \
  --agent claude \
  --json

# 列出终端，找到 worker 的 handle
orca terminal list --worktree id:workerWtId --json

# 等待终端空闲（agent 启动完毕）
orca terminal wait --terminal h:workerHandle --for tui-idle --timeout-ms 60000 --json

orca orchestration dispatch \
  --task task:abc123 \
  --to h:workerHandle \
  --inject \
  --json

orca orchestration check \
  --wait \
  --type worker_done \
  --timeout-ms 300000 \
  --json

# 查看收件箱中的完成消息
orca orchestration inbox --limit 20 --json

# 查看任务状态
orca orchestration task-list --json

Worker 端的操作

被分发的 worker 收到 preamble 后，按以下方式工作：

# Worker 需要提问时（阻塞式）
orca orchestration ask \
  --question "是否允许修改数据库 schema？" \
  --options "允许,不允许,需要讨论" \
  --json | jq -r .answer

# Worker 发送心跳
orca orchestration send \
  --to coordinator \
  --type heartbeat \
  --subject "仍在工作中" \
  --body "已完成 60%，正在处理 token 刷新逻辑" \
  --task-id task:abc123 \
  --dispatch-id dispatch:def456 \
  --json

# Worker 报告完成
orca orchestration send \
  --to coordinator \
  --type worker_done \
  --subject "任务完成" \
  --body "修复了 src/auth/token.ts 中的竞态条件，添加了分布式锁。所有测试通过。" \
  --task-id task:abc123 \
  --dispatch-id dispatch:def456 \
  --files-modified "src/auth/token.ts,src/auth/lock.ts" \
  --report-path "docs/fix-report.md" \
  --json

自动编排（Automated Coordinator Loop）

如果你不想手动管理每个步骤，用 orca orchestration run 让 Orca 自动协调：

orca orchestration run \
  --spec "将整个项目的 API 调用从 fetch 迁移到 axios，包括错误处理和类型定义" \
  --max-concurrent 3 \
  --repo id:abc123 \
  --json

Orca 会自动：

1. 分析工作规格，拆分成子任务
2. 为每个子任务创建 worktree 并分发
3. 收集 worker 的完成报告
4. 管理任务依赖和决策门

监控自动编排进度

# 查看所有任务
orca orchestration task-list --json

# 只看就绪的任务
orca orchestration task-list --ready --json

# 查看待处理的决策门
orca orchestration gate-list --status pending --json

# 停止运行中的编排
orca orchestration run-stop --json

决策门（Decision Gates）

当任务 DAG 中某个步骤需要明确决策时，使用决策门：

# 创建决策门
orca orchestration gate-create \
  --question "是否采用方案 A（重构）还是方案 B（补丁）？" \
  --blocks-task task:abc123 \
  --options "方案A:重构,方案B:补丁" \
  --json

# 解决决策门
orca orchestration gate-resolve \
  --gate gate:xyz789 \
  --decision "方案A:重构" \
  --rationale "长期可维护性更重要" \
  --json

被阻塞的任务在决策门解决前会保持 blocked 状态。

恢复与重置

# 预览分发上下文（包括 worker preamble）
orca orchestration dispatch-show --dispatch dispatch:def456 --json

# 手动更新任务状态
orca orchestration task-update \
  --task task:abc123 \
  --status completed \
  --result "手动标记完成" \
  --json

# 重置编排状态（谨慎使用！）
orca orchestration reset --tasks --json    # 清除所有任务
orca orchestration reset --messages --json # 清除所有消息
orca orchestration reset --all --json      # 清除全部状态

广播地址

发送消息时可以使用组广播地址：

何时使用哪种方式

实战配方（Recipes）

配方 1：三个 Agent 竞赛同一任务

Orca 的「杀手级用法」——不同 agent 做同一个任务，选最优结果。

1. 创建三个 worktree（同名加序号后缀）
2. 分别启动 Claude Code、Codex、Cursor CLI
3. 粘贴完全相同的 prompt
4. 分屏同时观察
5. 审查每个 diff，用 Annotate AI Diff 批注最优解
6. 从胜出的 worktree 提交 PR
7. 一键删除另外两个 worktree

配方 2：逐行审查 AI Diff

1. 打开 worktree 的 diff 视图
2. 用 Annotate AI Diff 功能逐行添加批注
3. Orca 会将批注发送回 agent，agent 据此修正代码
4. 反复迭代直到满意

配方 3：在 10 个 Worktree 间跳转

1. 用 Cmd-J 打开 Jump Palette
2. 输入关键词过滤 worktree
3. 回车跳转
4. 侧边栏中未读的 worktree 会加粗显示

配方 4：用 Design Mode 修 UI Bug

1. 在 worktree 中打开内置浏览器
2. 进入 Design Mode，选中 UI 元素
3. Orca 提取元素的尺寸、颜色、字体等信息
4. 将这些信息直接注入 agent 的 prompt
5. Agent 根据精确的 UI 规格修复代码

配方 5：通过 SSH 在远程机器工作

1. 配置 SSH worktree，Orca 连接到远程机器
2. 远程 worktree 中的 agent 在远程机器上运行
3. 本地 Orca 界面控制远程 agent
4. Diff 查看、代码提交全部在远程完成

定时自动化（Scheduled Automations）

让 Orca 按计划自动运行 agent 任务——定期 triage、代码审查、维护等。

创建自动化

orca automations create \
  --name "每日依赖检查" \
  --trigger daily \
  --time "09:00" \
  --timezone "Asia/Tokyo" \
  --prompt "检查 package.json 中的过时依赖，报告需要更新的包" \
  --provider claude \
  --repo id:abc123 \
  --disabled \
  --json

触发器格式

管理自动化

# 列出所有自动化
orca automations list --json

# 查看详情
orca automations show auto:xyz --json

# 启用
orca automations edit auto:xyz --enabled --json

# 手动触发（测试用）
orca automations run auto:xyz --json

# 查看运行历史
orca automations runs --id auto:xyz --json

# 删除
orca automations remove auto:xyz

Worktree 检查点

每个 worktree 有一个轻量级的自由文本注释字段，用于记录「当前在做什么」的状态快照。

orca worktree set \
  --worktree active \
  --comment "复现了认证失败；正在测试 credential-chain 修复方案" \
  --json

建议设置检查点的时机

• 完成一个有意义的实现切片
• 确认或推翻了一个假设
• 完成代码审查
• 遇到阻塞（等待外部输入、上游 bug、权限不足）
• 阶段转换（调查 → 修复，修复 → 验证）

orca worktree current --json

Computer Use（桌面应用控制）

让 Agent 控制本地桌面应用——通过辅助功能树、截图和 UI 操作。Beta 功能，需要授权。

首次设置

orca status --json
orca computer permissions --json
orca computer capabilities --json

如果缺少权限，在系统设置中授予 "Orca Computer Use" 辅助功能和屏幕录制权限（macOS）。

核心工作流

采用「快照 → 操作 → 快照」循环：

# 1. 获取应用状态（辅助功能树 + 截图）
orca computer get-app-state --app com.apple.Safari --json

# 2. 操作特定元素（使用返回的 element-index）
orca computer click --app com.apple.Safari --element-index 12 --json

# 3. 重新获取状态确认结果
orca computer get-app-state --app com.apple.Safari --json

可用操作

echo "my-secret" | orca computer set-value --app ... --element-index 5 --value-stdin --json

Skills 与 MCP

可用的 Orca Skills

所有官方 skill 通过以下方式安装：

npx skills add https://github.com/stablyai/orca --skill <name>

默认 agent 设置包含 orca-cli、computer-use 和 orchestration。

自定义 Skills

在 GitHub 仓库中创建 skills/<name>/SKILL.md 文件，然后用 npx skills add 安装，即可给 agent 提供公司内部工具。

MCP 服务器

在 Settings → Integrations → MCP 中注册 MCP 端点，兼容 MCP 的 agent CLI 就能使用这些外部工具。

远程与 SSH

SSH Worktree

Orca 支持通过 SSH 在远程机器上创建 worktree，agent 在远程运行，你在本地控制。适合：

• 需要在特定环境（GPU 服务器、生产环境副本）中调试
• 本地机器性能不足
• 代码不能离开远程服务器

Remote Orca Servers

在远程机器上运行 Orca 服务器（headless）：

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

然后在本地 Orca 中配对远程环境，即可像本地一样使用。

移动端

Orca 提供 iOS 和 Android 伴侣应用，让你在手机上：

• 实时监控 agent 工作进度
• 查看终端输出
• 发送简单指令（如 "continue"）
• 接收完成通知
• 审批决策门

适合离开电脑时远程操控正在运行的 agent。