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

Orca 按工作区环境Per-Workspace Environments从 skill-stub 到版本一致的运行时配方指南【免费下载链接】orcaOrca 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的全部细节且与执行你命令的那个二进制版本一一对应。从源码结构看完整指南确实被内嵌进了 CLIsrc/cli/bundled-skill-guides.ts 中定义了ORCA_PER_WORKSPACE_ENV_MARKDOWN常量其内容与 skills/orca-per-workspace-env/SKILL.md 的 frontmattername: 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.1environmentRecipes的数据结构在 src/shared/orca-yaml-hook-types.ts 中environmentRecipes是OrcaHooks即orca.yaml的 hook 配置的一个可选字段与scripts.setup、scripts.archive等并列。每个条目的类型是OrcaVmRecipeexport 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.tsnormalizeVmRecipes(record.environmentRecipes)负责归一化仅当解析出非空配方时才会把environmentRecipes字段写回规范化结果。本仓库根目录的 orca.yaml 目前只有scripts.setup而没有environmentRecipes正说明该字段是项目级的可选配置。5.2vm 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或补充destroysuspend/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-ideLinux 非托管终端→orca一次选定、全程复用不可运行时报告原错并停止不得换可执行文件加载指南ORCA skills get orca-per-workspace-env运行任何 Orca 命令之前不凭记忆猜 flag确认应用状态ORCA status --json必要时ORCA open --jsonAgent 调用优先--json旧版兜底仅skills get明确未知时ORCA status --jsonORCA vm recipe doctor id --repo-path repo --json只读未经用户明确批准禁止--provision告知用户更新 Orca 以恢复完整版本匹配指南超出兜底命令面时询问用户不猜测边界Boundaries方面技能桩反复强调的两条红线必须内化其一Orca 是薄封装——引导、检测、搭脚手架可以但云账号、账单、镜像、凭据的所有权永远在用户手里其二任何可能花钱的操作provider 资源创建即--provision都必须在用户明确许可之后执行这一点在技能桩正文、兜底章节中出现两次与 src/cli/specs/vm.ts 中「默认非破坏性」的规格声明互为印证。7. 延伸阅读仓库内路径技能桩本体skill-stubs/orca-per-workspace-env.md技能源文件skills/orca-per-workspace-env/SKILL.md内嵌指南构建src/cli/bundled-skill-guides.ts、src/cli/handlers/skills.ts、src/cli/specs/skills.ts配方类型定义src/shared/orca-yaml-hook-types.ts、解析归一化src/shared/orca-yaml.tsdoctor 静态校验src/shared/ephemeral-vm-recipe-doctor.ts、CLI 规格src/cli/specs/vm.ts、doctor 行为测试src/cli/index-vm-recipe-doctor.test.ts项目级配置示例含scripts.setup未配置environmentRecipesorca.yaml【免费下载链接】orcaOrca 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考