orcakit

orcakit

Orca 会为每个 git worktree 显示一个工作区，其中的卡片包含关联的问题、状态，以及其中正在运行的终端。Worktree 本身由原生的 git worktree 创建（遵循 gitkit 的约定、使用 issuekit 的 start，或由你亲自创建），Orca 会自动发现它们。

但没有任何工具负责协调两者之间的偏差。名为 issue-42-add-sso-login 的 worktree 出现在侧边栏中，却没有关联问题，因此卡片上什么也没显示。问题关闭且 PR 合并后，工作区却一直留在那里；三周后，侧边栏里大多都是已完成的工作。orcakit 专门负责这种协调：让 Orca 中的 worktree 视图与任务跟踪器保持一致。

orcakit 不会越界

Git 是 worktree 的事实来源。 orcakit 绝不会为了实际工作运行 orca worktree create，也不会自行编造路径，因为创建 worktree 使用的是原生 git worktree，并遵循 gitkit 的约定，所以没有安装 Orca 的无头 Linux 机器也能运行完全相同的命令。orcakit 在更上一层工作，处理只有 Orca 才了解的内容：

• 元数据，即关联的问题、工作区状态、评论和显示名称；
• Git 无法表达的 Orca 侧资源，即绑定到工作区的实时终端，以及仓库的归档／设置钩子。

使用 Git 移除 worktree 就足够了：Orca 会在几秒内发现并自行移除对应条目。唯一的例外是由 Orca 创建的工作区，详见 模式：clean，其中说明了原因并限定了该例外的适用范围。

orcakit 绝不操作任务跟踪器。 它会读取问题和 PR 以判断状态；绝不会关闭问题、移动标签或编辑 PR。如果它发现某个 PR 已合并，但对应问题仍处于打开状态，这就是任务跟踪器中的偏差，它会指出这一点，并引导你使用 issuekit close，而不会绕过它直接操作。

何时使用

• list。“Orca 工作区里都有什么”“哪些工作区已过时”“把我的 Orca 侧边栏显示为表格”。只读。
• link。“将我的 worktree 关联到对应问题”“我的工作区卡片是空白的”“Orca 不知道 #42 的工作区是做什么的”。
• clean。“清理我的 Orca 工作区”“移除问题已合并的工作区”“我的侧边栏里全是已完成的工作”。
• align。“Orca 应该把新的 worktree 放在哪里”“让 Orca 使用我的 worktree 根目录”“别让 Orca 把 worktree 创建在自己的文件夹里”。

如果无法确定模式，请先询问。 list 不会产生任何影响，而 clean 会删除目录；切勿在两者之间擅自猜测。

**此工具不负责：**创建 worktree（gitkit）、关闭问题或在合并后清理（issuekit close）、操作 Orca 终端、浏览器或 Agent（应直接使用 orca CLI，或使用已安装的 Orca 提供的技能）。orcakit 负责工作区的整洁维护，而非工作区的操作。

预检（所有模式）

orca status --json      # app running? runtime reachable?

• 未安装 orca → 这台机器上没有 Orca，因此没有需要协调的内容。请如实说明这一点，然后停止。不要回退到其他方案：没有 Orca，工作树也已经可以正常使用，而且工作流中的其他环节都不依赖此技能。
• 无法连接运行时 → orca open 会启动应用并等待。请先征求同意，再在他人的机器上启动桌面应用。
• 缺少 gh 或未通过身份验证 → list 仍然可用，但所有判断都会降级为“跟踪器状态未知”；而且 clean 完全无法运行，因为它的安全性完全依赖于确认 PR 已合并。请说明是哪种情况，然后停止，不要猜测。
• orca 标志或选择器被拒绝 → CLI 更新很快；在断定操作不受支持之前，请先查看 orca <command> --help。目标是实现约定，即链接、状态和移除；具体的标志拼写并不重要。

Orca 还必须配置为显示外部创建的工作树，否则它看不到 gitkit 创建的任何内容：

orca repo list --json    # each repo carries externalWorktreeVisibility

如果仓库的设置为 "externalWorktreeVisibility": "hide"，那么所有模式都看不到该仓库的 gitkit 工作树。没有对应的 CLI 标志；这是 Orca UI 中的仓库级设置。请按名称报告仓库，让用户切换此设置，不要把空结果误当成工作树根目录为空。

Orca 对工作区的了解

orca worktree list --json
orca worktree show --worktree "branch:$BRANCH" --json

每条记录都包含 path、branch、linkedIssue、linkedPR、workspaceStatus、isArchived、isMainWorktree 和 lastActivityAt。选择器包括 branch:<name>、path:<abs-path>、issue:<number> 以及 active/current；你应优先使用 branch:，原因与 gitkit 按分支查找工作树相同：路径只是猜测，分支才是身份标识。

发现结果最终会保持一致。刚创建几秒的工作树可能已能通过 worktree show 找到，但还未出现在 worktree list 中；已移除的工作树也可能短暂残留。请重新读取，而不要根据一次过时的列表就下结论。

两种工作区

以下所有内容都取决于这一区别：

类型	所在位置	创建者	移除方式
Git 原生	$WORKTREE_ROOT 下（默认为 ~/worktrees/<repo>/<branch>）	gitkit / issuekit start，通过 git worktree add 创建	由 git 移除；Orca 会自行删除对应条目
Orca 原生	Orca 工作树基础路径下（默认为 ~/orca/workspaces/<repo>/<name>）	orca worktree create	使用 orca worktree rm，以便处理钩子和终端

请按以下顺序分类，并在首次匹配时停止：

1. gitkit 的标记表明这是 Git 原生工作树。 gitkit 创建的工作树会在其管理目录中包含一个 gitkit-created 文件，可通过 test -e "$(git -C "$WT" rev-parse --absolute-git-dir)/gitkit-created" 查找。
2. Orca 的基础路径表明这是 Orca 原生工作树，但前提是该基础路径与 $WORKTREE_ROOT/<repo> 不同。
3. 其他情况都属于未知类型。 这包括手动创建的工作树，以及 align 将两种工作树放在同一根目录下之后任何未标记的工作树。请报告此类工作树，并在 clean 中跳过；绝不要根据两个工具共用的路径猜测其类型。

路径前缀只是一种启发式判断，并非 Orca 记录的事实，因此标记的优先级更高。align 会有意让前缀重叠，因此执行 align 后，标记是区分这两种工作树的唯一依据。

模式：list

只读。不做任何更改，不提出任何问题；状态不明时，应首先使用此模式。

筛选所有 isMainWorktree 为 false 的工作区，并将它们与跟踪器关联：

orca worktree list --json
gh pr list --head "$BRANCH" --state all --json number,state,url,mergedAt
gh issue view "$N" --json number,state,title,labels     # $N parsed from an issue-<n>-<slug> branch
git -C "$WT" status --porcelain                          # dirty?
git -C "$WT" log --oneline "@{upstream}..HEAD"           # unpushed?

呈现一个表格（工作区、分支、问题、PR、Orca 状态、Git 状态），并为每一行给出判定：

判定	含义	处理方式
active	问题或 PR 仍处于打开状态，工作正在进行	无需处理
unlinked	分支名称包含问题编号，但 linkedIssue 为 null	link
stale status	Orca 显示 in-progress，但 PR 已合并或正在审核	link
reapable	PR 已合并，问题已关闭，工作树干净	clean
tracker drift	PR 已合并，但问题仍处于打开状态	使用 issuekit close <n> 关闭；这不是 orcakit 要处理的
dirty	有未提交或未推送的工作，无论跟踪器状态如何	先交由人工处理
unknown	分支名称中没有问题编号，且没有 PR	保留原样；说明原因

最后说明哪些模式会处理哪些行。如果存在 dirty，请将它放在最前面，因为这类工作可能会丢失。

模式：link

补上 Orca 无法推断的元数据，让工作区卡片能清楚说明其用途。

对于每个分支匹配 issue-<n>-<slug> 且 linkedIssue 为 null 的 Git 原生工作区：

orca worktree set --worktree "branch:$BRANCH" --issue "$N" --json

同时使 workspaceStatus 与跟踪器状态保持一致。Orca 使用 todo、in-progress、in-review、done、archived 这些状态；请根据实际状态进行映射，不要只看标签：

跟踪器状态	workspaceStatus
问题打开，没有 PR，分支上没有提交	todo
问题打开，没有 PR，已有已提交的工作	in-progress
PR 打开	in-review
PR 已合并	done
问题已关闭且 PR 已合并	done（同时也是 clean 的候选项）

orca worktree set --worktree "branch:$BRANCH" --workspace-status in-review --json

规则：

• 将所有计划执行的 set 操作预览为一个表格，然后一次性确认整批操作。 此处不会销毁任何内容，但它会重写用户的侧边栏，因此应先让用户查看，而不是让用户措手不及。
• 绝不覆盖已设置为其他值的 linkedIssue。 人工或 orca worktree create --issue 有意设置了该值；报告不一致并保留原值。
• 绝不覆盖手写的 comment。 仅在其为空时设置。
• 不要处理主工作树。 它不用于功能开发，其中的状态没有意义。
• 分支名称中没有问题编号时，直接跳过。说明跳过了多少个；不要根据 slug 虚构关联。

交接

本技能中的所有交接都使用操作性语体：每句话只写一条指令，使用主动语态和现在时，不使用比喻。

更改内容。 报告有多少个工作区添加了问题关联、有多少个工作区的状态已更正，以及跳过了多少个工作区和跳过原因。

更改位置。 更改位于 Orca 侧边栏；磁盘上的内容没有移动，Git 状态也没有改变。

后续步骤。 如果 link 将任何内容标记为 done，这些内容就是 clean 的全部输入，因此接下来使用该模式。否则请停止：已关联的卡片就是最终状态，不是通往其他状态的步骤。

模式：clean

回收工作已完成的工作区。每次移除都不可撤销，因此流程固定为：收集、筛选、一次性预览全部内容、逐行确认、重新检查，然后移除。

1. 筛选

只有在可以证明工作区的更改已合并，且跟踪器已同步时，该工作区才是候选项：

gh pr list --head "$BRANCH" --state merged --json number,url,mergedAt
gh issue view "$N" --json state                       # must be CLOSED

• 主要筛选条件。 分支对应的 PR 已合并，且分支名称中要么没有 Issue，要么对应的 Issue 已关闭。
• 次要筛选条件，单独列为一组。 从未创建过 PR，但分支已完全合并到基分支（git branch --merged "origin/$BASE"；基分支按 gitkit 的方式解析，绝不硬编码为 main）。直接推送时确实会出现这种情况，但证据较弱，因此在预览中单独列出，绝不与主要筛选结果合并。

PR 已合并但 Issue 仍处于打开状态的，不是候选项。 这是跟踪器状态漂移；应将其列出，并交由 issuekit close <n> 处理。此命令会关闭 Issue、解除其依赖项的阻塞，并拆除工作树，从而正确完成操作，而不是背着跟踪器删除证据。

2. 排除

以下情况一律跳过。在预览中，每项都会列在已跳过部分，并注明原因，不会有任何项目悄然从报告中消失：

• 存在未提交更改或未跟踪文件，即 git status --porcelain 输出非空；
• 存在未推送的提交，或分支完全没有上游分支；
• 主工作树，始终排除；
• 当前所在的工作树，因为绝不能拆掉自己脚下的地板；
• 未知类型，参见两种工作区类型，因为凭猜测选择任何一种移除方式都不安全；
• 有正在运行的 Orca 终端，通过 orca terminal list --worktree "branch:$BRANCH" --json 查找。将 orca terminal stop --worktree "branch:$BRANCH" 作为单独步骤提供，并明确要求确认；整理时绝不能顺带停止他人正在运行的进程。

PR 已合并不代表工作树为空。临时文件、暂存的实验内容，以及从未推送的后续提交，都不在 PR 中，却仍存在于工作树里。

到此为止：每个工作区要么是候选项，要么是注明原因的跳过项，要么是跟踪器状态漂移项。

3. 预览并确认

用一张表列出所有候选项，并为每项列出其符合筛选条件的证据（PR 编号、合并日期、Issue 状态）、类型（git 原生或 Orca 原生）及其 lastActivityAt。在表格下方列出跳过项及原因。

然后逐项确认是否移除。 移除规则由 gitkit 负责，每个工作树和每个分支都要分别确认；除非是由 gh 证明的 squash 合并，否则使用 -d。没有 gitkit 时，每行询问一次，并使用 -d 删除。在每次询问中注明工作区、分支和 PR。到此为止：每个候选项都已得到用户本人的答复。

4. 重新检查，然后按类型移除

每次移除前都要立即重新检查活动情况。 预览和答复之间会经过一段时间，用户可能已经在其中打开了工作区。使用 orca worktree show --worktree "branch:$BRANCH" --json、orca terminal list --worktree "branch:$BRANCH" --json 和 git -C "$WT" status --porcelain 重新读取该行。如果 lastActivityAt 晚于预览中的值、出现了正在运行的终端，或者工作树不再干净，就跳过该行并说明原因。

git-native → 交由 gitkit 执行清理：它会按分支查找工作树，并依据其移除规则将其移除。如果未安装 gitkit，以下两个命令就是全部操作：

git -C "$REPO" worktree remove "$WT"
git -C "$REPO" branch -d "$BRANCH"

然后停止。不要再调用 orca worktree rm，因为 Orca 会自行删除已发现的条目；在路径已经不存在时再次尝试移除，只会产生令人困惑的错误。

Orca-native → 由 Orca 管理，因此也由 Orca 移除：

orca worktree rm --worktree "path:$WT" --run-hooks --json

这是 orcakit 唯一会运行同时执行 git 移除操作的供应商命令的场景，原因很明确：该检出由 Orca 创建，Orca 有归档钩子和绑定到该检出的终端会话，而其 rm 会依次处理这三项。先用 git 移除会使 Orca 的元数据成为孤项，并跳过钩子。此例外仅适用于由 Orca 创建的工作区，绝不适用于 gitkit 工作树。

绝不使用 --force。 此处的每次移除都已通过工作树干净且 PR 已合并的检查；如果 git 仍然拒绝移除，这个拒绝本身就是重要信息。报告情况，然后处理下一行。

当每个已确认的行都已移除、因重新检查而跳过或遭到拒绝，并且每种结果都已记录时，流程结束。

5. 移交

变更内容。 按类型报告已移除的工作区数量，以及跳过的数量。说明被跳过的工作区及其原因；未能清理且仍然存在的脏工作树是报告中最重要的一项，必须放在首位。

移除位置。 列出已不存在的路径，以及随之删除的分支。说明 Orca 侧边栏会在几秒内更新，因此此刻仍可见的条目不代表失败。

后续操作。 选出一项：

• 有任何工作区因脏状态而被跳过 → 这件事优先于其他所有事项。指出路径并让用户前去查看；真正可能丢失的是过时工作树中尚未提交的工作。
• 发现跟踪器状态不一致 → 对这些问题使用 issuekit 的 close <n>；否则使用 gh issue close <n> 并手动清理。
• 没有剩余的清理工作 → 明确说明这一点，然后停止。正确的下一步完全是另一回事：如果已安装，就使用 statuskit 重新了解情况；否则什么也不做。侧边栏整洁并不值得反复循环处理。

模式：align

停止让 Orca 在 gitkit 永远不会查找的位置创建工作树。Orca 的默认路径是 ~/orca/workspaces/<repo>/<name>；gitkit 的约定是 $WORKTREE_ROOT/<repo>/<branch>（除非环境另有说明，否则为 ~/worktrees）。两个根目录会把用户的工作树分散到两个位置。执行 align 后，两种工作树都会共用一个根目录，因此路径不再能区分它们；此时 clean 会根据 gitkit 的标记进行分类，详见两种工作区。

orca project setups --json                                  # find the setup id for the repo
orca project setup-update --setup "$SETUP_ID" \
  --worktree-base-path "$WORKTREE_ROOT/$(basename "$REPO")" --json

验证，而非假设。 设置列表不会回显基础路径，而且 Orca 是否会在该路径后追加仓库名称，在任何地方都没有文档说明。因此，请针对每个仓库用一个临时工作树进行实测确认：

orca worktree create --repo "path:$REPO" --name orcakit-align-check --no-parent --json
# read the path it reports:
#   .../worktrees/<repo>/orcakit-align-check    → correct
#   .../worktrees/<repo>/<repo>/orcakit-…       → doubled; re-set the base to "$WORKTREE_ROOT"
orca worktree rm --worktree "name:orcakit-align-check" --json

这是此技能中唯一一次 orca worktree create，目的只是读取路径，因此请先征得用户同意，并在同一过程中移除这个临时工作树。如果用户拒绝确认，或无法运行检查，请说明基础路径已设置，但未经验证；不要声称实现了你并未观察到的统一。

现有工作树不会受到影响。 已位于 ~/orca/workspaces 下的工作树会照常运行；git 会存储绝对路径，手动移动它们需要执行 git worktree repair。align 只会改变下一个工作树的创建位置。请明确说明这一点，因为“已统一”听起来像“已迁移”，但事实并非如此。

交接

变更内容。 报告哪些仓库已设置基础路径，以及临时检查是否确认了最终路径。

设置位置。 给出每个仓库的新基础路径，并提醒用户现有工作区仍留在原处。

下一步。 现在只有一个根目录，可以运行 list，在一张表中查看全部工作树。如果没有其他待办事项，就此结束；这是每个仓库只需设置一次的选项，不是例行操作。

说明

• orcakit 是本机工具，始终可选。 机器上没有 Orca 时就不执行任何操作，而且工作流中的其他部分不得依赖它。gitkit、issuekit 等工具都不会调用它，因为在没有该应用的机器上会导致故障。它是供你运行的清理工具，不是流程链中的一环。
• paseokit 是同级工具，不是继任者。 它会将相同的工作树同步到 Paseo；Paseo 的模型恰好相反：Paseo 不会发现任何内容，只会清理目录已不存在的条目，因此 paseokit 负责注册和回收，而 orcakit 负责补充信息和清理。Paseo 版本相关信息由 paseokit 管理。两者都仅限本机使用且均为可选工具，彼此绝不会调用对方。
• 工作树相关信息归 gitkit 管理。 默认路径约定仅作为没有 gitkit 的机器可使用的通用回退方案，在此声明；其他所有内容，包括分支命名、基础引用解析和拆除规则，都由 gitkit 管理。此处出现的任何其他 gitkit 信息副本都是错误。
• 跟踪器相关信息归 issuekit 管理。 orcakit 会读取 issue 和 PR 状态来判断工作区情况，但不会写入任何相关信息。
• 破坏性步骤先预览再确认；只读操作则直接运行。 list 不会询问。link 会预览一批操作。clean 会先预览所有候选项，再逐一确认是否移除，遵循 gitkit 的移除规则。align 会在创建临时工作树前征求确认。
• 无法使用 shell？ 那么你就无法访问 orca CLI 或 gh。请根据用户提供的信息进行判断，并用代码块原样打印准确命令供用户运行；切勿声称已链接或移除你无法实际操作的工作区。