orca-per-workspace-env

工作区独立环境

本文件仅用于功能检索与入口引导，并非完整的使用指南。对应当前版本的完整工作区环境参考文档由 orca 二进制文件本身直接提供——故意不在本文件中罗列，以确保文档与实际执行命令的 CLI 程序始终保持同步，绝不漂移。

在配置、检查、调试或验证工作区独立环境 Recipe（即为每个工作区按需新建、用完即弃的云端沙盒、虚拟机或本地运行环境）时，均可唤醒 Orca。处理范围涵盖首次初始化（服务商前置条件、可复用的基础快照、编程 Agent 鉴权快照、凭据与状态管理），而非仅限于工作区的生命周期脚本。你可以用它来拉起工作区环境、修复 orca.yaml 中 environmentRecipes 节点、生成服务商生命周期脚本脚手架，或解决 orca vm recipe doctor 的校验失败。Orca 本质上是一个轻量封装层：你的职责是引导、检测与生成脚手架，绝不能接管用户的云账号、账单、镜像或凭据，未经用户明确授权也绝不可产生任何计费操作。

确认本会话使用的 CLI 可执行文件

请先一次性确定要调用的可执行文件，并在后续所有命令中复用该程序：

• 如果设置了环境变量 ORCA_CLI_COMMAND，直接使用其设定的值。Orca 在受控的 WSL 会话中会自动导出该变量。
• 否则，在暴露了 ORCA_DEV_REPO_ROOT 环境变量的开发源码树会话中，请使用 orca-dev。
• 否则，若在 Linux 环境且不在 Orca 托管的终端内，请使用 orca-ide。切勿在此时直接运行原生的 orca 命令——在 Orca 终端之外，直接输入 orca 通常会误唤醒 GNOME 的 Orca 屏幕阅读器（/usr/bin/orca）并在用户的机器上开启语音朗读。
• 其余情况下，使用 orca。

下文中出现的 ORCA 仅作为你所确认的可执行文件的占位符。在执行任何命令前，请将其替换为实际的可执行程序名；不要在 Shell 中创建名为 ORCA 的变量，也不要字面运行 ORCA。这一规则同样适用于 POSIX Shell、PowerShell 以及 cmd.exe。

若选定的可执行程序无法运行，请直接上报其精准报错并终止流程。切勿自动降级切换到其他可执行程序，否则可能会静默调用到不同构建版本的 Orca。

执行 Orca 命令前加载完整指南

ORCA skills get orca-per-workspace-env

该命令会输出与即将处理后续指令的 Orca 二进制文件完全匹配的最新版指南——涵盖服务商配置、基础与鉴权快照、orca.yaml 中的 environmentRecipes、生命周期脚本以及 orca vm recipe doctor。请先阅读指南，再执行具体所需的命令。

切勿凭记忆或本地缓存的存根导引去凭空猜测子命令或 Flag 参数。它们会在不同的 Orca 版本间发生变化，本文件也已特意移除了子命令列表。请先通过 ORCA status --json 确认应用状态正常（必要时通过 ORCA open --json 启动），对于 Agent 驱动的自动化调用，请优先使用 --json 参数。

若旧版 Orca 不支持 skills get 命令

仅当选定的二进制文件明确提示 skills get 为未知命令时，才可开启此降级机制。其他报错并不代表版本过旧；遇到报错应如实上报，而不是凭空猜测或擅自更换可执行文件。若确定为尚未支持该指南命令的旧版二进制程序，仅使用以下受控的只读初始化命令来进行情况排查。切勿陷入僵局，也不要捏造不存在的命令：

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

上述 doctor 命令属于免费的静态检查。未经用户明确批准，切勿附加 --provision 参数，因为该参数会触发服务商资源创建并可能产生费用。

随后请提示用户：将 Orca 升级至新版本即可通过 ORCA skills get orca-per-workspace-env 获取与当前版本完全契合的完整指南。除上述命令外，请主动向用户寻求指示，切勿臆测旧版本可能不支持的指令集。