Orca 按工作区环境（Per-Workspace Environments）：从 skill-stub 到版本一致的运行时配方指南

2026-09-06 11:41:32作者：盛欣凯Ernestine

Orca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

项目地址：https://gitcode.com/GitHub_Trending/orca48/orca

本文以 skill-stubs/orca-per-workspace-env.md 为主体，讲解 Orca 的「按工作区环境」（per-workspace environment）技能桩（discovery stub）机制：它如何为每个 workspace 按需创建一次性的云沙箱、VM 或本地运行时，如何在本会话中正确解析 orca 可执行文件，如何通过 orca skills get 拉取与二进制版本严格一致的完整操作指南，以及在旧版二进制上如何安全地降级为只读探测。读完后，你将掌握解析 Orca CLI、加载版本匹配指南、运行 vm recipe doctor 静态检查，并理解 environmentRecipes 在 orca.yaml 中的底层类型与校验实现。

1. 为什么是「发现桩」而不是静态使用指南

skill-stubs/orca-per-workspace-env.md 开宗明义：这个文件是一个 discovery stub（发现桩），不是使用指南。完整、版本匹配的 per-workspace 环境参考文档由 orca 二进制自身通过 skills get 命令提供——这是有意为之的设计，目的是让指南永远不会与实际执行命令的二进制发生漂移（drift）。

这意味着一个清晰的分工：

技能桩（本文件，位于仓库 skill-stubs/ 目录）：只负责「发现」与「定位」——告诉你何时应该启用 Orca 来处理 per-workspace 环境，以及如何拿到真正的指南；
完整指南（由二进制内嵌提供）：包含 provider 配置、base 快照、auth 快照、environmentRecipes 字段、生命周期脚本、orca vm recipe doctor 的全部细节，且与执行你命令的那个二进制版本一一对应。

从源码结构看，完整指南确实被内嵌进了 CLI：src/cli/bundled-skill-guides.ts 中定义了 ORCA_PER_WORKSPACE_ENV_MARKDOWN 常量，其内容与 skills/orca-per-workspace-env/SKILL.md 的 frontmatter（name: orca-per-workspace-env 及 description）保持一致。skills get 命令的实现在 src/cli/handlers/skills.ts，命令规格声明在 src/cli/specs/skills.ts（用法为 orca skills get <topic> [--full] [--json]）。

技能桩定义的启用时机（Engage 场景）值得完整保留——当你设置、审查、调试或验证一个 per-workspace 环境配方时应启用 Orca，它覆盖的范围是「按需、一次性的运行时（云沙箱、VM 或本地），为每个 workspace 全新生成」，具体包括：

首次搭建：provider 前置条件、可复用的 base 快照、coding-agent 鉴权快照、凭据与状态文件，而不仅仅是 per-workspace 生命周期脚本；
修复 orca.yaml 中的某个 environmentRecipes 条目；
搭建 provider 生命周期脚本；
解决 orca vm recipe doctor 的失败。

同时技能桩划定了 Orca 的能力边界：Orca 是一个 thin wrapper（薄封装层）——你（Agent）负责引导、检测、搭脚手架（scaffold）；永远不拥有用户的云账号、账单、镜像或凭据，并且绝不在没有用户明确许可的情况下花钱。

2. 为本会话解析 CLI 可执行文件

技能桩给出的第一段可操作内容是「Resolve the CLI for this session」——选择一个可执行文件并在本会话所有后续命令中复用同一个。解析规则按优先级排列：

ORCA_CLI_COMMAND 环境变量已设置 → 直接使用它的值。Orca 为受管理的 WSL 会话导出这个变量；
否则，处于 dev checkout 且会话暴露了 ORCA_DEV_REPO_ROOT → 使用 orca-dev；
否则，在 Orca 托管终端之外的 Linux 上 → 使用 orca-ide。技能桩特别警告：不要在那里运行裸 orca ——在 Orca 终端之外，orca 通常解析为 GNOME Orca 屏幕阅读器（/usr/bin/orca），会在用户机器上启动语音朗读；
否则 → 使用 orca。

后续内容中，ORCA 是一个占位符，指代你解析出的可执行文件：运行任何命令前都要先替换它，不要真的创建 shell 变量、更不要字面执行 ORCA。这套写法在 POSIX shell、PowerShell 和 cmd.exe 中行为一致。

失败处理规则同样明确：如果选定的可执行文件无法运行，报告它的原始错误并停止，不要回退（fall through）到另一个可执行文件——那可能悄悄指向另一个 Orca 构建，造成版本漂移，恰恰违背了 stub 机制的初衷。

3. 运行 Orca 命令前先加载完整指南

技能桩要求：在运行任何 Orca 命令之前，先执行：

ORCA skills get orca-per-workspace-env

这会打印出与将要处理你下一条命令的二进制精确版本匹配的完整指南——涵盖 provider 配置、base 与 auth 快照、orca.yaml 中的 environmentRecipes、生命周期脚本以及 orca vm recipe doctor。先读它，再运行你需要的具体命令。

技能桩同时给出两条纪律：

不要凭记忆或凭这份 stub 的缓存副本猜测子命令与 flag。 它们在 Orca 各版本之间会变化，这份文件刻意不再列举它们；
用 ORCA status --json 确认应用已启动（必要时用 ORCA open --json 启动），并且Agent 驱动的调用优先使用 --json。

4. 旧版 Orca 的有界降级：只有 `skills get` 不可用时的兜底

技能桩为「较老的 Orca 不认识 skills get」准备了一个严格受限的兜底流程，其触发条件与边界都非常苛刻：

仅当选定的二进制明确报告 skills get 是一个未知命令时，才使用兜底。任何其他失败都不能作为「二进制过旧」的证据——应当如实报告，而不是猜测或更换可执行文件；
对已确认的 pre-guide 二进制，只允许使用下面这对有界的、只读的引导命令来定位状态，不要死胡同、不要发明命令：

ORCA status --json
ORCA vm recipe doctor <recipe-id> --repo-path <repo> --json

其中 doctor 命令是免费的静态检查。技能桩特别强调：永远不要在未获得用户明确批准的情况下追加 --provision，因为它会创建 provider 资源并可能产生费用。

之后应告知用户：更新 Orca 即可通过 ORCA skills get orca-per-workspace-env 恢复完整的版本匹配指南。超出上述命令的范围，应当询问用户，而不是猜测这个旧版二进制可能不支持的命令面。

5. 源码级佐证：`environmentRecipes` 的类型定义与 doctor 校验

技能桩提到的 environmentRecipes 与 orca vm recipe doctor，可以在当前仓库中找到完整的实现证据，这为「按 stub 指路、以二进制为准」的工作方式提供了底层支撑。

5.1 `environmentRecipes` 的数据结构

在 src/shared/orca-yaml-hook-types.ts 中，environmentRecipes 是 OrcaHooks（即 orca.yaml 的 hook 配置）的一个可选字段，与 scripts.setup、scripts.archive 等并列。每个条目的类型是 OrcaVmRecipe：

export type OrcaVmRecipe = {
  id: string
  name: string
  create: string
  checkoutMode?: EphemeralVmCheckoutMode
  description?: string
  suspend?: string
  resume?: string
  destroy?: string
  destroyDisabled?: boolean
}

字段语义与技能桩描述的生命周期合同一致：create 必填，suspend/resume/destroy 可选，destroyDisabled 对应 destroy: none 的显式禁用；checkoutMode 的取值来自 EphemeralVmCheckoutMode = 'orca-worktree' | 'provisioned-root'。此外，OrcaHooks 上还带有 environmentRecipeDiagnostics 字段（OrcaVmRecipeDiagnostic[]，含 index、可选 field 和 message），用于承载解析 environmentRecipes 时的非致命校验问题——也就是说，配方写错不会直接让 orca.yaml 不可读，而是以诊断形式暴露。

解析入口在 src/shared/orca-yaml.ts：normalizeVmRecipes(record.environmentRecipes) 负责归一化，仅当解析出非空配方时才会把 environmentRecipes 字段写回规范化结果。本仓库根目录的 orca.yaml 目前只有 scripts.setup 而没有 environmentRecipes，正说明该字段是项目级的可选配置。

5.2 `vm recipe doctor` 的静态检查实现

CLI 侧的命令规格在 src/cli/specs/vm.ts，其声明与技能桩的兜底命令完全对应：

orca vm recipe doctor <recipe-id> [--repo-path <path>] [--provision|--connect] [--json]

规格中的 notes 明确写着：默认模式非破坏性、不执行配方命令；只有 --provision 或 --connect 才会真正运行配方、校验其结果并（在配置了清理时）执行清理。这解释了为什么技能桩可以把不带 --provision 的 doctor 称为「免费的静态检查」、而把 --provision 视为需要用户明确批准的危险操作。

静态检查的具体逻辑在 src/shared/ephemeral-vm-recipe-doctor.ts 的 doctorEphemeralVmRecipe 中，可以逐项核对技能桩承诺的检查内容：

本地执行目标（v1 限制）：localExecutionSupported 为假时直接失败，消息为 “Ephemeral VM recipes run on the local desktop host in v1.”；
repo 路径检查：路径不存在或不是目录即失败，remediation 提示传入包含 orca.yaml 的本地仓库；
recipe.exists：在 environmentRecipes 中按 id 查找配方，未找到即失败；
recipe.create 命令路径检查：通过 firstRecipeCommandToken 提取命令首 token（支持引号包裹的 token），空命令失败，绝对路径给出 warn（建议使用仓库相对路径以便跨机器工作）；
recipe.destroy 三分支：destroyDisabled 时 warn（“Only use destroy: none when provider resources are cleaned up elsewhere.”）；配置了 destroy 则做路径检查；两者皆无则 warn 要求显式设置 destroy: none 或补充 destroy；
suspend/resume 成对性：源码注释解释了原因——被 suspend 挂起的工作区只有存在 resume 才能被唤醒，只定义其一会把工作区永远“卡睡”，因此单边定义会得到 recipe.suspend_resume_pairing 的 warn。

这些检查与技能桩“先静态、后花钱”的安全叙事严格吻合：doctor 的默认模式不启动任何东西，--provision 才会跑 create → 校验 → destroy 的真实闭环，因此后者必须获得用户一次性明确批准。

5.3 指南分发链的闭环

把三条证据串起来，可以得到完整的版本一致性链路：

Agent 通过 skill-stubs/orca-per-workspace-env.md 知道「什么时候该启用 Orca、去哪找完整指南」；
ORCA skills get orca-per-workspace-env 从二进制内嵌的 src/cli/bundled-skill-guides.ts 打印出与该二进制同版本的完整指南（skills/orca-per-workspace-env/SKILL.md 是其源形态）；
指南中的一切命令（如 vm recipe doctor）最终由 src/cli/specs/vm.ts 声明的命令面与 src/shared/ephemeral-vm-recipe-doctor.ts 的校验逻辑执行，其结果通过 --json 供 Agent 消费。

6. 实践要点与边界总结

把技能桩全文提炼为可执行清单：

步骤	命令 / 动作	约束
解析可执行文件	`ORCA_CLI_COMMAND` → `orca-dev` → `orca-ide`（Linux 非托管终端）→ `orca`	一次选定、全程复用；不可运行时报告原错并停止，不得换可执行文件
加载指南	`ORCA skills get orca-per-workspace-env`	运行任何 Orca 命令之前；不凭记忆猜 flag
确认应用状态	`ORCA status --json`（必要时 `ORCA open --json`）	Agent 调用优先 `--json`
旧版兜底（仅 `skills get` 明确未知时）	`ORCA status --json` + `ORCA vm recipe doctor <id> --repo-path <repo> --json`	只读；未经用户明确批准禁止 `--provision`
告知用户	更新 Orca 以恢复完整版本匹配指南	超出兜底命令面时询问用户，不猜测

边界（Boundaries）方面，技能桩反复强调的两条红线必须内化：其一，Orca 是薄封装——引导、检测、搭脚手架可以，但云账号、账单、镜像、凭据的所有权永远在用户手里；其二，任何可能花钱的操作（provider 资源创建，即 --provision）都必须在用户明确许可之后执行，这一点在技能桩正文、兜底章节中出现两次，与 src/cli/specs/vm.ts 中「默认非破坏性」的规格声明互为印证。