SuperAPI AI 工具集

worktree-spinoff

编程与开发

查看项目

更新于 10-23 11:10

技能介绍

Worktree spin-off(Orca IDE)是一个自进化技能,通过使用不断改进。当任务需要在独立的 Orca worktree 中继续(拥有自己的分支、侧边栏条目和智能体会话)而不是在当前 worktree 中继续时,可使用此技能。一个命令 scripts/orca-spinoff 即可完成整个分离和干净移除。它遵循 Orca 捆绑的 orca-cli 指南,并保持 Orca 的原生模型:worktree、内置智能体启动器、仓库与项目、主机以及配对运行时。以下内容基于 Orca 1.4.22x 在 Linux 和 macOS 上的观察。

用途:将任务从默认分支分离到独立的 Orca worktree,并启动一个智能体终端,附带交接提示。

主要能力:

  • 创建(create):指定名称、标题、交接文件、显示名称等,可选参数包括 issue、comment、link、setup、dry-run。
  • 移除(remove):指定名称,可选删除远程分支、强制、dry-run。
  • 支持本地机器、配对 Orca 运行时(通过 --environment 或 --pairing-code)、项目主机(通过 --host)等目标。
  • 交接文件在启动前提交到 docs/handoff/ 下,默认提示要求智能体首先阅读它。
  • 可链接主检出中的路径(如 .venv、node_modules、.env)到 worktree。
  • 默认使用 --no-parent 使任务成为顶级条目,--activate 默认关闭,不切换当前视图。
  • 输出一行 JSON,包含 worktree、path、branch、terminal、terminals、setup_tabs、prompt_seen 字段;进度和警告输出到 stderr。

使用方式:

  1. 设置 SPIN 变量指向技能目录下的 scripts/orca-spinoff。
  2. 运行 create 命令,例如: "$SPIN" create --name my-task --title "My task (issue #12)" --handoff ./handoff.md --display "My task: readable name" [--issue 12] [--comment "status"] [--link .venv] [--setup skip] [--dry-run]
  3. 运行 remove 命令,例如: "$SPIN" remove --name my-task [--delete-remote-branch] [--force] [--dry-run]
  4. 可选使用 --dry-run 运行所有检查并打印计划,不改变分支或 worktree(可能仍会 git fetch)。

适用场景:当任务需要独立分支、侧边栏条目和智能体会话时;需要将任务分发到配对运行时或项目主机时;需要干净移除 worktree 时。

限制与注意事项:

  • 需要 Orca IDE 管理智能体,并通过 Orca CLI 和 GUI 驱动 Claude Code 或其他 TUI 智能体。
  • 工具链来自 Nix,但脚本也可在原生 macOS(/bin/bash 3.2、BSD 用户空间)上运行,因为它不使用仅 GNU 的标志。要求 bash ≥ 3.2、git ≥ 2.20、python3 ≥ 3.9 和 Orca IDE CLI。
  • 仓库需在目标运行时上注册(orca repo add --path <checkout>),且其远程可从运行脚本的机器访问。
  • 在配对运行时上,内置启动器被拒绝,智能体在 worktree 自己的 shell 标签页中启动;远程 Orca 的 agentDefaultArgs 不会应用;提示无法从标签页读回,因此 prompt_seen 为 false;Claude Code 可能会询问文件夹信任问题。
  • orca 可能不是 Orca:在 Linux 桌面上,/usr/bin/orca 通常是 GNOME 屏幕阅读器。脚本使用 $ORCA_CLI(若设置),否则使用帮助中提到 worktree create 的 orca,否则使用 IDE 自己的 CLI(Linux 上 ~/.config/orca/linux-orca-cli-shim/orca,macOS 上 /Applications/Orca.app/Contents/Resources/bin/orca)。
  • 若 macOS CLI 链接损坏,可创建用户拥有的链接:ln -s /Applications/Orca.app/Contents/Resources/bin/orca ~/.local/bin/orca。
  • 远程 URL 中需要真实主机名,否则 Orca 可能将其视为未解析的 SSH 别名或自托管 forge。
  • Orca 缓存远程身份,修正 URL 后需重启 Orca 生效。
  • Claude Code 的文件夹信任是每个仓库根独立的,不继承父文件夹。在配对运行时路线上,需在该机器上信任仓库根一次。
  • 登录等待钥匙串;钥匙串锁定可能导致侧边栏停留在“Refreshing sign-in”。
  • 移除操作是异步的,脚本会等待文件夹消失。Orca 仅当分支名等于 worktree 名称时删除分支,否则脚本自行删除带前缀的分支。不使用 --force 时,若有未提交更改、未跟踪文件(链接除外)或不在远程分支上的提交,则拒绝移除。
  • 主 worktree 永远不会被匹配。

其他信息:运行后建议进行检查,包括命令是否成功、Orca CLI 或输出是否有变化、是否需要变通方法,并仅在问题真实且可复现时更新技能。