orca-frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Orca Frontend

Layer: Practice

Orcaは、並列worktreeの一覧、agent terminal、diff review、mobileからの通知と操作を一つの画面にまとめるfrontendとして使える。ただし、projectの正しさはOrcaに依存させない。Orcaを閉じても、別のmachineでOrcaがなくても、Worktrunkかplain gitで同じ状態を作れることを保つ。

worktreeのlifecycleの正本は

worktree-workflow

である。このSkillは、その上にOrcaを載せる時の扱いだけを書く。

Layer: 实践

Orca 可作为 frontend，将并行 worktree 列表、agent terminal、diff review 以及来自移动端的通知和操作集中到同一个屏幕中。不过，不应让 project 的正确性依赖 Orca。即使关闭 Orca，或者换到没有安装 Orca 的另一台 machine，也必须能够通过 Worktrunk 或 plain git 复现相同状态。

worktree lifecycle 的正本（source of truth）是

worktree-workflow

。本 Skill 仅说明在其之上集成 Orca 时的处理方式。

Orcaに持たせないもの

不交给 Orca 管理的内容

worktreeのsetup / teardown：処理は
```
worktree-workflow
```
のrepository-controlledな入口に置き、
```
orca.yaml
```
からはそれを呼ぶだけにする。
作業の正本：Issue、branch、PRがcanonical stateである。Orcaのworkspace名、親子関係、sidebarの状態はUIの状態として扱う。
orchestrationの状態：Orcaの Run / Task / Dispatch / 完了通知はtelemetryとして扱う。taskの完了やresultの採否は、GitHub IssueとPR、検証結果で判断する（
```
parallel-orchestration
```
）。
共有されるmutable state：
```
worktree.sharedDirectories
```
はsymlinkで同一directoryを共有するため、並行して書き込むbuild outputや
```
node_modules
```
には使わない。ユーザー設定のWorktree Shared PathsはmacOSでAPFS clone-copy（非対応環境ではsymlink）となる場合があり、複製後の変更は自動同期されない。方式を混同せず、mutable stateのworktree別ownershipと各worktreeでの検証を維持する（Mutable Ownership Safety）。

worktree 的 setup / teardown：处理逻辑放在
```
worktree-workflow
```
的 repository-controlled 入口中，
```
orca.yaml
```
只负责调用该入口。
工作的正本：Issue、branch 和 PR 是 canonical state。Orca 的 workspace 名称、父子关系和 sidebar 状态仅作为 UI 状态处理。
orchestration 状态：Orca 的 Run / Task / Dispatch / 完成通知均视为 telemetry。task 是否完成、result 是否被采纳，应根据 GitHub Issue 与 PR 以及验证结果判断（
```
parallel-orchestration
```
）。
共享的 mutable state：
```
worktree.sharedDirectories
```
通过 symlink 共享同一 directory，因此不应用于会被并行写入的 build output 或
```
node_modules
```
。用户配置的 Worktree Shared Paths 在 macOS 上有时会采用 APFS clone-copy（在不受支持的环境中则使用 symlink），复制后的变更不会自动同步。不要混淆这些方式；应维持 mutable state 按 worktree 划分的 ownership，并在每个 worktree 中进行验证（Mutable Ownership Safety）。

設定

配置

orca.yaml

は

worktree-workflow

と同じ入口を呼ぶ。

setupAgentStartupPolicy: wait-for-setup

にして、setupが終わる前にagentを起動させない。

yaml

undefined

orca.yaml

调用与

worktree-workflow

相同的入口。将其设置为

setupAgentStartupPolicy: wait-for-setup

，确保 setup 完成前不会启动 agent。

yaml

undefined

orca.yaml

scripts: setup: | mise run worktree:setup archive: | mise run worktree:teardown setupAgentStartupPolicy: wait-for-setup


- `.worktreeinclude` はWorktrunkとOrcaの両方が読む。literalなpathだけで書き、承認済みのnon-secret pathに限る。`.env` やcredentialは入れず、secretは `secrets-management` のruntime injectionで渡す。
- worktreeの作成にはWorktrunk（`wt switch --create <issue-number> --base=release-x-y-z`）を使ってよい。Orcaの Settings → General → Workspace で、Worktrunkのworktree置き場を外部worktreeの置き場として登録すると、Orcaのsidebarに表示できる。
- Orcaからworktreeを作る場合は、Advancedでbranch名をIssue番号にする。Orcaが作業名から派生させるbranch名は、ticket branchの命名規則に合わない。
- Orca同梱のSkill（`orca-cli` 等）は、Orcaの実行中だけ動くdiscovery stubで、Orcaのbuildと版を合わせる必要がある。machine単位のglobal配置はOrcaのupdaterに任せてよい（updaterは実行中のbuildのcommitにpinして入れ直す）。projectの `skills-lock.json` には入れず、projectの正しさをこれらのstubに依存させない。

scripts: setup: | mise run worktree:setup archive: | mise run worktree:teardown setupAgentStartupPolicy: wait-for-setup


- `.worktreeinclude` 会被 Worktrunk 和 Orca 同时读取。文件中只应写入 literal path，并且仅限已批准的 non-secret path。不要包含 `.env` 或 credential；secret 应通过 `secrets-management` 的 runtime injection 传入。
- 创建 worktree 时可以使用 Worktrunk（`wt switch --create <issue-number> --base=release-x-y-z`）。在 Orca 的 Settings → General → Workspace 中，将 Worktrunk 的 worktree 存放位置注册为 external worktree 存放位置后，便可在 Orca 的 sidebar 中显示。
- 从 Orca 创建 worktree 时，应在 Advanced 中将 branch 名称设为 Issue 编号。Orca 根据作业名称派生的 branch 名称不符合 ticket branch 的命名规则。
- Orca 附带的 Skill（如 `orca-cli`）是仅在 Orca 运行期间生效的 discovery stub，需要与 Orca 的 build 和版本保持一致。machine 级别的 global 安装可以交由 Orca 的 updater 管理（updater 会固定到当前运行 build 的 commit 并重新安装）。不要将这些 stub 添加到 project 的 `skills-lock.json` 中，也不应让 project 的正确性依赖它们。

操作の注意

操作注意事项

Linuxでは、Orcaのterminal外で
```
orca
```
と打つとGNOMEのscreen readerが起動することがある。Orcaのterminal外では
```
orca-ide
```
を使うか、
```
ORCA_CLI_COMMAND
```
が設定されていればその値を使う。
外部で作ったworktreeをOrcaから削除する場合も、teardownが動いたかを確認する。入口は何度実行しても同じ状態になるので、迷ったら手動で再実行してよい。
Orcaのorchestrationはexperimental扱いである。Herdr等ほかのSupervisorと同時に、同じworkerを管理させない。

在 Linux 上，于 Orca 的 terminal 外部输入
```
orca
```
时，可能会启动 GNOME 的 screen reader。在 Orca 的 terminal 外部，应使用
```
orca-ide
```
；如果已设置
```
ORCA_CLI_COMMAND
```
，则使用该变量的值。
即使从 Orca 删除在外部创建的 worktree，也应确认 teardown 是否已执行。该入口无论执行多少次都会得到相同状态，因此如果不确定，可以手动重新执行。
Orca 的 orchestration 目前属于 experimental 功能。不要让 Herdr 等其他 Supervisor 与 Orca 同时管理同一个 worker。

外す時

移除 Orca 时

Orcaをやめる時に移行作業が要らないことが、この扱いの目的である。次がOrca以外の場所にあれば、Orcaのuninstallだけで済む。

worktreeのsetup / teardownとport決定（repositoryの入口）
branch、Issue、PR、検証結果（GitHub）
```
.worktreeinclude
```
と、Orcaを使わない場合の作り方（
```
worktree-workflow
```
）

采用这种处理方式的目的，是确保停止使用 Orca 时无需进行迁移。只要以下内容位于 Orca 之外，卸载 Orca 即可完成迁移。

worktree 的 setup / teardown 和 port 确定方式（repository 入口）
branch、Issue、PR 和验证结果（GitHub）
```
.worktreeinclude
```
以及不使用 Orca 时的创建方式（
```
worktree-workflow
```
）