Orca orca-cli 技能：发现桩与版本一致 CLI 指南的设计与使用

Orca orca-cli 技能发现桩与版本一致 CLI 指南的设计与使用【免费下载链接】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/orcaOrca 是一个面向并行 agent 集群的 ADEAgent Development Environment其orcaCLI 是操作 Orca 托管 worktree、终端、自动化任务与内嵌浏览器的统一入口。本文基于仓库中的技能文件 skills/orca-cli/SKILL.md 展开讲清楚这套orca-cli技能的核心机制它为什么是一个发现桩discovery stub而不是完整手册、agent 如何安全地解析出正确的可执行文件、以及如何通过skills get拿到与所运行二进制严格版本一致的完整命令参考。读完后你能掌握在任意环境含 WSL、dev checkout、Linux 裸 shell中正确调用 Orca CLI 的完整契约以及该契约背后由源码与测试保证的实现细节。一、定位orca-cli 技能何时触发skills/orca-cli/SKILL.md 的 YAML frontmatter 定义了技能名称orca-cli与一段触发描述。其核心判断原则是只要 Orca 正在运行的编辑器/运行时是事实来源source of truth就应使用orcaCLI 而不是裸工具。具体覆盖的状态面包括Orca 托管的 worktree 与文件夹上下文folder contexts终端terminals、仓库repos、自动化automations、工件artifactsworktree 评论comments与嵌入在 Orca 应用内的浏览器built-in browser。文档列出的触发语包括$orca-cli、use orca cli、Orca worktree、child worktree、cardStatus、spawn codex/claude in a worktree、read/wait/send Orca terminal、terminal send、full handoff、handover、give this to another agent、another worktree、Orca browser、orca artifacts、share HTML/Markdown、public artifact link、share skills以及 control the browser inside Orca。frontmatter 还明确了与其他自动化工具的分工边界这是 agent 选型时的关键约束当任务触及 Orca 托管状态时优先使用orca-cli而非裸git worktree、临时 PTY、Playwright 或 Computer Use只有当任务需要操作系统/窗口级控制焦点、菜单、对话框、坐标、截图时才对外部浏览器窗口、webview 或桌面 UI 使用 Computer UseOrca 内嵌页面用orca-cli外部页面用 Playwright 或 CDP 这类页面自动化工具。文档同时给出一条反向约束当 Orca 状态无关紧要时直接用普通 shell 工具不要为了用 CLI 而用 CLI。二、核心设计发现桩而非版本化的完整手册这是整个文档最重要的设计决策。skills/orca-cli/SKILL.md 开宗明义This file is a discovery stub, not the usage guide. The full, version-matched Orca CLI reference is served by theorcabinary itself — kept out of this file on purpose so it can never drift from the binary that will actually run your commands.即这个文件刻意不包含任何子命令与 flag 清单因为子命令在各 Orca 版本之间会变。完整参考由将要执行命令的那个orca二进制自身提供——指南与执行者永远同源从机制上杜绝了文档说 A 版本、二进制是 B 版本的漂移问题。从仓库结构看这套设计是四层文件协同完成的skills/orca-cli/SKILL.md安装到技能目录的发现桩只做三件事——说明触发条件、给出可执行文件解析规则、指导 agent 去加载完整指南skill-stubs/orca-cli.md桩的源模板与安装桩同构仅首行标题差异作为技能分发的投影skill-guides/orca-cli.md完整命令参考源文件覆盖 Full Handoffs、Worktrees、Terminals、Automations、Artifacts、Skill Sharing、Built-In Browser、Mobile Emulator 全部章节src/cli/bundled-skill-guides.ts构建期由 config/scripts/generate-bundled-skill-guides.mjs 生成的、内嵌进 CLI 的指南表ORCA_CLI_MARKDOWN等常量skills get输出的内容就来自这里。2.1skills get的实现指南如何被二进制自举出来CLI 侧的实现位于 src/cli/handlers/skills.ts。要点有三skills list: 输出全部内置指南的主题表name 压缩后的 description skills get: 按主题名取出指南支持 --full 输出 fullMarkdown--json 包裹输出大体积的BUNDLED_SKILL_GUIDES表被惰性import()源码注释明确解释无关 CLI 命令不应在启动期支付该模块的加载与解析成本。也就是说只有真的执行skills list/get时才加载指南数据skills get orca-cli输出的 markdown 与生成它的二进制来自同一次构建因此天然版本匹配——这正是桩文件敢于不列任何子命令的底气。2.2 测试对桩文件的强约束config/scripts/orca-cli-skill-guidance.test.mjs 用断言锁死了桩文件的行为契约防止有人把命令清单加回桩里桩必须包含discovery stub、ORCA skills get orca-cli安全的 CLI 解析契约ORCA_CLI_COMMAND、orca-dev、orca-ide、GNOME Orca screen reader必须留在桩内桩内不允许出现以orca开头的裸命令行expect(stub).not.toMatch(/^orca /mu)桩必须包含老版本回退措辞explicitly reports thatskills getis an unknown command、do not invent commands、ask the user rather than guessing与 fail-stop 措辞report its exact error and stop、Do not fall through to another executable桩必须不含完整指南中的命令细节如--parent-worktree、ORCA automations create且长度严格小于对应 guide 文件桩与 guide 的 frontmatter 必须一致。这些测试意味着发现桩的瘦身不是排版偏好而是被持续集成强制维护的架构约束。三、可执行文件解析契约一个会话只选一次文档的 Resolve the CLI for this session 一节给出四级解析规则按优先级若设置了ORCA_CLI_COMMAND环境变量使用它的值。Orca 会为托管的 WSL 会话导出该变量否则在暴露ORCA_DEV_REPO_ROOT的 dev checkout 中使用orca-dev否则在 Orca 托管终端之外的 Linux 上使用orca-ide。绝不要在那里运行裸orca——在 Orca 终端外orca通常解析到 GNOME Orca 屏幕阅读器/usr/bin/orca会在用户机器上启动语音朗读其余情况使用orca。文档随后给出两条纪律下文所有命令中的ORCA是占位符运行前把它替换成你选定的可执行文件不要创建 shell 变量、不要逐字运行ORCA。该替换方式在 POSIX shell、PowerShell、cmd.exe 中行为一致如果选定的可执行文件无法运行报告其精确错误并停止。不要降级到另一个可执行文件——那可能悄无声息地指向另一个 Orca 构建例如 dev 会话打到了生产 CLI或 Linux 落到了屏幕阅读器。3.1ORCA_CLI_COMMAND在源码中的落点该契约不是文档约定而是运行时行为。在 src/main/ipc/pty/host-env/assembly.ts 中PTY 宿主环境装配逻辑明确写道if (opts.isWsl) { baseEnv.ORCA_USER_DATA_PATH opts.userDataPath // Why: managed WSL registration uses orca-ide; exposing that literal // scopes agent guidance to WSL without a bare-orca shim. baseEnv.ORCA_CLI_COMMAND opts.isPackaged ? orca-ide : orca-dev } else { if (!opts.isPackaged) { baseEnv.ORCA_USER_DATA_PATH ?? opts.userDataPath } delete baseEnv.ORCA_CLI_COMMAND }即只有 WSL 分支会导出ORCA_CLI_COMMAND生产构建取orca-ide、dev 构建取orca-dev非 WSL 终端则主动删除该变量——与文档Orca exports this for managed WSL sessions完全对应。注释还解释了为什么托管 WSL 注册用orca-ide字面量让 agent 引导被限定在 WSL 场景同时避免引入裸orcashim。配套的 WSLENV 透传在 src/main/pty/wsl-orca-env.ts由于wsl.exe只导入被选中的 Windows 环境变量ORCA_CLI_COMMAND/u被显式列入 passthrough 清单/u表示不翻译直接透传保证 WSL 客户端 shell 里也能读到同一个值。同文件还解释了 Linux 上为何安装包名orca-ide而非orcaassembly.ts L246-L254Linux CLI 以orca-ide安装以避免遮蔽 GNOME 的/usr/bin/orca屏幕阅读器在 Orca 托管 PTY 内则通过 shim 目录注入 PATH让终端里的orca始终指向本应用的 CLI。dev 模式下则把 userData 下cli/bin前置到 PATH使orca解析到 dev 构建而非/usr/local/bin/orca的生产二进制。四、加载完整指南skills get优先确认状态用status --json桩文件的第二步是指令化的ORCA skills get orca-cli该命令打印与将处理你下一条命令的那个确切二进制版本匹配的完整指南——涵盖 worktrees、handoffs、terminals、automations 与内置浏览器。文档要求先读它再运行你真正需要的那条具体命令。配套的反幻觉纪律同样写在文档里不要凭记忆或这份桩的缓存副本去猜子命令/flag。它们随 Orca 版本变化桩文件刻意不再列出用ORCA status --json确认应用已启动必要时ORCA open --json拉起agent 驱动的调用一律优先--json如果 CLI 缺失要明确说出来而不是先去翻源码文件。五、老版本回退有边界的只读自举桩文件最后一节处理老 Orca 不认识skills get的场景其措辞本身就是 agent 安全策略的范本仅在选定的二进制明确报告skills get是未知命令时才使用回退。其他形式的失败不能作为二进制过旧的证据——应报告它而不是猜、或换可执行文件对已确认的 pre-guide 二进制只允许执行一组有界的只读命令来定位现状不许走进死胡同更不许发明命令ORCA status --json ORCA worktree ps --json ORCA terminal list --json然后告知用户升级 Orca 即可通过ORCA skills get orca-cli恢复完整的、版本匹配的指南超出这三条命令的任何操作先问用户而不是去猜这套更老的二进制可能不支持的命令面。这三条命令status/worktree ps/terminal list恰好是完整指南 skill-guides/orca-cli.md Start Here 一节推荐的起步命令可见回退集被刻意收敛为最小只读面。六、完整指南覆盖什么进阶阅读发现桩是入口真正的操作面在版本匹配的完整指南里。skill-guides/orca-cli.md 是它的仓库源文件章节包括Full Handoffsworktree create --no-parent --agent ...与terminal send的移交流程以及移交后原 agent 即停止的语义边界与orchestration监督式协调的区分WorktreesrepoId::worktreePath双段 id 的语义、selector 语法id:/name:/path:/branch:/issue:/active、谱系规则--parent-worktree、--no-parent只控制 Orca 谱系不控制 Git baseWorktree Commentsworktree set --comment与--workspace-statustodo/in-progress/in-review/completedTerminalslist/show/read/send/wait/create/split/rename/switch/close、句柄失效terminal_handle_stale的重取规则、cursor 分页读取、wait --for tui-idle --timeout-msAutomationshourly/daily/weekdays/weekly/5 段 cron/RRULE 触发器--repo与--workspace互斥--reuse-session语义Artifactsshare/update/unshare/list/delete发布默认关闭、只能由人在桌面端 Settings → Artifacts 开启拒绝时返回artifact_sharing_disabled且不应重试Skill Sharingskills installed/skills shareagent_skill_sharing_disabled/agent_skill_sharing_busy错误码与只发布显式请求的技能的权限边界Built-In Browsersnapshot–interact–re-snapshot 循环、eNref 的 tab 作用域与失效规则、browser_stale_ref/browser_no_tab/browser_host_unavailable等常见错误的恢复动作Mobile Emulatororca emulator的 workspace 作用域规则与orca-emulator技能的分界。需要强调适用前提完整指南中的子命令与 flag 随版本演进本文引用的具体命令以 skill-guides/orca-cli.md 当前内容为准在真实使用中应始终以ORCA skills get orca-cli的输出为唯一权威——这正是 orca-cli 技能设计要传达的核心工程思想把命令参考做成二进制的自描述能力用测试锁死文档桩不越界让版本漂移在架构上不可能发生。【免费下载链接】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），仅供参考