yasyf/orca

Orca-Worker

Laden Sie zuerst die versionsabgestimmten Anleitungen: orca skills get orca-cli und orca skills get orchestration. Diese Fähigkeit definiert den Worker-Einstiegspunkt und den Quellrückgabe-Vertrag.

Jeder orca orchestration-Befehl hier übergibt --full: Seit Orca 1.4.246 gibt es ohne --full eine kompakte Ansicht aus, die die Felder weglässt, die diese Schritte lesen. orca-worker-launch.sh und orca-reclaim.py im bin/-Verzeichnis dieses Plugins übergeben --full --json selbst. Führen Sie beide vom Checkout-Wurzelverzeichnis aus.

Repository-Werte

Ein Repository, das Worker startet, hat .orca.json im Wurzelverzeichnis eingecheckt, und beide Tools lesen daraus aus dem Arbeitsverzeichnis:

{
  "ccRemote": "tools/cc-remote/bin/cc-remote",
  "ccRemoteConfig": "tools/cc-remote/config.yaml",
  "repo": "<orca-repository-id>",
  "baseBranch": "origin/main",
  "sparse": [".agents", ".claude"]
}

Schlüssel	Umgebungsvariable, die es füllt	Route
ccRemote	WORKER_CC_REMOTE, die cc-remote CLI, ein Pfad vom Checkout-Wurzelverzeichnis oder ein PATH-Name	Sprite und orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG, die cc-remote Konfiguration, vom Checkout-Wurzelverzeichnis	Sprite und orca-reclaim.py
repo	WORKER_REPO, die Orca-Repository-ID	lokal
baseBranch	WORKER_BASE_BRANCH, der Branch, von dem ein lokaler Worktree ausgeht	lokal
sparse	führt zu WORKER_SPARSE, dem Sparse-Cone des lokalen Worktrees	lokal

Eine gesetzte Umgebungsvariable gewinnt gegenüber ihrem Schlüssel, und WORKER_SPARSE fügt Verzeichnisse nach dem Cone der Datei hinzu. Jeder Schlüssel ist optional, und ein Repository ohne .orca.json übergibt die Variablen selbst.

Worker starten

Implementierungs- und Test-Worker verwenden standardmäßig einen ungenutzten vorinstallierten Sprite-Agenten-Arbeitsbereich. Der Launcher beansprucht ihn exklusiv, aktualisiert flach den angeforderten Ref, bereitet den Agenten vor und hängt die native Task in einem Aufruf an. Wenn kein kompatibler ungenutzter Arbeitsbereich bereit ist, erstellt er den Arbeitsbereich der Lane. Jede Zuordnung startet eine begrenzte Hintergrundbefüllung in Richtung des orca.pool.ready der Konfiguration, sodass aufeinanderfolgende Starts warme Arbeitsbereiche beanspruchen. Beanspruchte Worker bleiben nach Abschluss beansprucht; die Wiederverwendung eines zurückgehaltenen Agenten erfordert einen expliziten neuen nativen Dispatch.

Ein Sprite-Lanenname hat höchstens 55 Kleinbuchstaben, Ziffern und Bindestriche und beginnt mit einem Buchstaben oder einer Ziffer:

WORKER_RUN="<gehörende-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" "<model>" "<effort>" "<brief.md>"

Führen Sie dies vom Terminal aus, das bereits den genannten nativen Run besitzt. Das Skript überprüft diese Bindung vor der Zuordnung, ruft cc-remote orca prepare --warm einmal auf und startet dann den vorbereiteten, inaktiven Worker mit einem nativen worker-start auf dem Orca-Server des Sprite, wobei es dessen vorbereitetes Terminal und Worktree wiederverwendet. Prepare kopiert die vollständige Aufgabenbeschreibung auf die VM und zeichnet ihren Hash, ihre Länge und den tatsächlichen Checkout-HEAD auf. Die erste Aufgabe ist ein Zeiger, der dem Worker sagt, diese Datei zu lesen und zu verifizieren.

Prepare startet die Orca-Laufzeitumgebung des Sprite über seine orca CLI, und Orca 1.4.224 bedient sie auf seinem verwalteten Server, orcad. Die vorbereitete Aufgabe zeichnet diesen Build des Servers als managedServer auf, gelesen aus dem Ready-Ereignis, das orca serve --json ausgibt. Das Skript startet nichts, wenn das Feld fehlt, was bedeutet, dass Orca auf Electron zurückgefallen ist. Orcas Grund ist die [serve]-Zeile in ~/.cc-remote/orca/serve.log auf dem Sprite.

Der Launcher führt die CLI WORKER_CC_REMOTE oder ccRemote aus, benannt nach der Konfiguration CC_REMOTE_CONFIG oder ccRemoteConfig. Wenn keine CLI gesetzt ist, führt er cc-remote aus PATH aus, wo der PATH einer langlebigen Sitzung oder eine neuere Homebrew-Installation eine andere Version enthalten kann, daher nennt ein Repository, das seine Version festpinnt, seinen Wrapper in ccRemote. Ein Sprite-Launch ohne Konfiguration lehnt vor der Zuordnung ab.

cc-remote bereitet einen Sprite nur vor, wenn die CLI die exakte Version des orca.bootstrap_helper der Konfiguration ist; ein neuerer Patch-Release schlägt fehl wie ein älterer, daher bewegen sich der CLI-Pin und der Helper in einer Pin-Änderung gemeinsam. Vor der Zuordnung vergleicht der Launcher die version, die die ausgewählte CLI ausgibt, mit der bootstrapHelper.version der agents-payload.json neben der Konfiguration, Links aufgelöst, und lehnt bei Unterschied ab, wobei er beide nennt. cc-remote führt denselben Check selbst durch, aber ein warmer Anspruch erreicht ihn erst, nachdem der Reserve-Arbeitsplatz beansprucht wurde, und dieser Reserve-Arbeitsplatz bleibt dann als fehlgeschlagen beansprucht. Eine Konfiguration ohne agents-payload.json daneben überlässt den Check cc-remote.

Wenn ein frisch installierter signierter Release beim ersten Start auf einem Mac hängt, beheben Sie es selbst. Dies ist eine Installationswiederherstellung, niemals eine Frage an den Eigentümer. Stellen Sie sicher, dass die ausgewählte ausführbare Datei der signierte Release ist, entfernen Sie com.apple.quarantine von dieser einen Datei und wiederholen Sie den Versionsbefehl:

exe="$(readlink -f "<selected-executable>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<selected-cc-remote>" version

xattr gibt No such xattr aus, wenn das Attribut bereits entfernt ist. Übergeben Sie niemals -r, nennen Sie kein Verzeichnis und ändern Sie die Systemrichtlinie von Gatekeeper nicht.

Der Launcher übergibt kein --config. Er exportiert CC_REMOTE_CONFIG als absoluten Pfad an cc-remote, und ein relativer Wert wird vom Verzeichnis des Aufrufers aufgelöst. Die ausgewählte Konfiguration benennt das Repository, das der Sprite auscheckt. WORKER_REPO wählt nur ein lokales Orca-Repository; das Setzen auf der Sprite-Route lehnt vor einem Versuch oder einer Zuordnung ab. Der Launcher bildet keine lokale Repo-ID auf ein Remote-Repository ab.

Stellen Sie ein anderes Binär-/Konfigurationspaar bereit, z. B. einen Runner, der eine Version behält, während sich sein Checkout bewegt, wie folgt:

WORKER_CC_REMOTE=/absoluter/pfad/zu/cc-remote \
CC_REMOTE_CONFIG=/absoluter/pfad/zu/config.yaml \
WORKER_RUN="<gehörende-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

WORKER_REF benennt einen Remote-Branch oder -Tag und wird unverändert durchgereicht; wenn weggelassen, liefert die Konfiguration den Ref. WORKER_BASE_BRANCH gehört zur expliziten lokalen Worktree-Route. Übergeben Sie ihn nicht als Remote-Branch, entfernen Sie keine beliebigen Präfixe und ersetzen Sie den angeforderten Ref nicht durch eine Commit-ID aus einem lokalen Vorab-Nachschlag. Der baseCommit des vorbereiteten Datensatzes ist die tatsächliche VM-Basis. Das Setzen von WORKER_BASE_BRANCH auf der Remote-Route lehnt ab; WORKER_REF und WORKER_EXPECT_BASE lehnen auf der lokalen Route ab.

Gewöhnliche Branch-Bewegungen sind gültig. Setzen Sie WORKER_EXPECT_BASE nur, wenn die Aufgabe eine exakte Basis erfordert. Geben Sie eine vollständige 40- oder 64-stellige Kleinbuchstaben-Commit-ID an. Der Launcher vergleicht sie nach der Vorbereitung; ein Missmatch behält den vorbereiteten inaktiven Worker und stoppt vor worker-start. Dieser Vergleich wählt nicht den Checkout aus. Prepare hat keine separate Exakter-Commit-Checkout-Option, und ein Branch- oder Tag-Name ist immer noch ein Ref, wenn seine Schreibweise hexadezimal aussieht.

Bewahren Sie das ausgewählte Modell und den Aufwand auf. WORKER_SERVICE_TIER übergibt eine explizite Codex-Service-Stufe unverändert; sie lehnt mit einem Claude-Modell ab. Die Schnellstufe ist nur für Incident-Lanes: WORKER_SERVICE_TIER=fast lehnt ab, es sei denn, WORKER_INCIDENT=1 ist gesetzt. Ohne eine Stufe übergibt der Launcher kein Service-Stufen-Flag, und codex läuft auf der Standardstufe.

Verwenden Sie WORKER_LOCAL=1 für eine lokale Wurzel, die Opus ausführt, oder für wurzelautorisierte, äußerst sensible Arbeiten, der einzige Fall für Fable:

WORKER_RUN="<gehörende-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

Die lokale Route lehnt ohne ein Repository und einen Basis-Branch ab, von WORKER_REPO und WORKER_BASE_BRANCH oder repo und baseBranch.

Der lokale Worktree heißt <lane>-<erste 8 Hex-Ziffern der SHA-256 der Run-ID>, sodass zwei Runs niemals denselben Namen vergeben. Ein zweiter Start für diese Lane im selben Run setzt seinen live-Worktree fort; wenn der Worktree, den ein früherer Versuch erstellt hat, weg ist, lehnt der Start ab, weil ein Name nie zweimal vergeben wird.

Ein neuer lokaler Worktree ist sparse über sparse, gefolgt von den Verzeichnissen, die WORKER_SPARSE nennt, durch Leerzeichen getrennt, und ist ein vollständiger Checkout, wenn beide leer sind. Der Launcher gibt den Erweiterungsbefehl aus. Die Aufgabenbeschreibung einer sparsen Lane trägt "diese Lane ist sparse: erweitern mit git sparse-checkout add <dir> vor dem Lesen außerhalb".

Ein nicht gesetztes oder leeres WORKER_LOCAL wählt Sprite; jeder andere nicht leere Wert lehnt ab. Die lokale Route startet nur Claude und lehnt Codex-Modelle ab. Remote-Fable lehnt vor der Vorbereitung ab; es wird niemals zu einem lokalen Start oder einem anderen Modell. Lokales Claude behält die vorhandene interaktive Authentifizierung des Rechners und das aufgabenbezogene Bypass-Verhalten. Es wird stripped unter lane_env und lane_settings gestartet, ohne Auto-Update, nativen ~/.claude-Watcher, Animation, Telemetrie oder Statuszeile, und lane_denied_tools hindert es daran, auf einen Menschen zu parken. Interaktive Sitzungen und claude plugin update aktualisieren dennoch den Plugin-Cache. Setzen Sie CLAUDE_LANE_SETTINGS auf ein JSON-Objekt, um lokale Einstellungen hinzuzufügen.

Starten Sie nur die Model Context Protocol-Server, die in der Erlaubnisliste der Aufgabe genannt sind. Auf Sprite übergibt WORKER_MCP_CONFIG ein Inline-JSON-Objekt für Claude oder eine Inline-TOML-Tabelle für Codex an das --mcp-config von prepare; es ist kein lokaler Dateipfad. Auf der lokalen Route folgt der Wert der Syntax von Claudes --mcp-config.

Remote-Claude und Codex verwenden dedizierte API-Schlüssel aus den konfigurierten Callbacks von cc-remote. Claude verwendet normale API-Umgebungsauthentifizierung; seine gewöhnlichen Tool-Prozesse können diese Schlüssel erben. Für Codex schließt die gepinnte CLI OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN und CLAUDE_CODE_OAUTH_TOKEN aus eingebauten Shell-Tools aus. Der Akteur und seine nativen Hooks behalten die für API-Aufrufe benötigte Umgebung. Diese Ausschlüsse bieten keine Prozess- oder Dateisystemisolierung im Bypass-Modus.

Halten Sie API-Anmeldeinformationen im Remote-Akteur und seinen erlaubten Nachkommen. Akteur-lokale Hook-Evaluatoren können ausgewählte Schlüssel an kurzlebige Inferenz-Kinderprozesse weitergeben. Halten Sie Schlüssel fern von residenten Hook-Daemons, Images, Artefakten, Protokollen, gemeinsamen Dateien und globaler Konfiguration. Setzen Sie keine API-Key-Variablen global, ersetzen Sie keine lokale interaktive Authentifizierung und kopieren Sie keine OAuth-Refresh-Token oder vollständige Authentifizierungs-Caches auf einen Worker.

Jede Aufgabenbeschreibung beansprucht <brief-stem>.worker neben der Beschreibung. Für /briefs/lane-a.md ist das /briefs/lane-a.worker. Ein vorhandenes Verzeichnis, ein Link, ein fehlgeschlagener Versuch oder eine veraltete <brief-stem>.dispatch.json lehnt eine Wiederholung ab. Das Verzeichnis zeichnet request.json mit der angeforderten Route, dem Modell, dem Aufwand, der Stufe, dem Ref, der optionalen erwarteten Basis und dem lokalen Brief-Hash/den Bytes auf.

Die Remote-Route behält das rohe allocation.json, prepare.err und prepare.status. Sie validiert die angeforderte Lane, den tatsächlichen Arbeitsbereich, den angeforderten Ref, die Art der Zuordnung, den Task-HEAD, den Agenten, die Aufgabenbeschreibung, die Umgebung, das Terminal und den Worktree <repoId>::<projectRoot>, bevor sie die Aufgabe in prepared.json extrahiert. Dann führt sie worker-start mit --on der vorbereiteten Umgebung, --worktree id:<worktreeId> und --terminal des vorbereiteten Terminals aus. Beide Routen behalten worker-start.json, worker-start.err und worker-start.status. Behalten Sie diese Dateien bei jedem Ergebnis.

Erfolg erfordert einen Exit-Code Null von worker-start und eine Quittung, die ok liest, Zustand ready, den gehörenden Run und druckbare Task- und Dispatch-IDs. IDs in einer fehlgeschlagenen Quittung machen ihn nicht bereit. Erfolg gibt eine JSON-Zeile mit den Feldern state, task, dispatch, terminal und worktree aus.

Auf Sprite nennt das JSON auch lane, den tatsächlichen workspace und allocation (warm oder created). terminal ist prepared.terminal und worktree ist prepared.projectRoot, der Checkout auf der VM. Verwenden Sie diesen tatsächlichen Arbeitsbereich für spätere cc-remote orca collect-Aufrufe. Ein fehlgeschlagener oder nicht bestätigter Start gibt kein Erfolgs-JSON aus und behält den Versuch ohne Wiederholung oder Bereinigung.

Vorbereiten und Anhängen separat

Verwenden Sie die ausgewählte CLI und Konfiguration, die oben beschrieben wurde, wenn die Vorbereitung und das Anhängen der ersten Aufgabe eine getrennte Inspektion benötigen. Dieses explizite frische Sprite-Agenten-Beispiel gibt eine einfache vorbereitete Aufgabe zurück:

"<selected-cc-remote>" orca prepare "<lane>" --config "<configured-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Prepare startet den ausgewählten Agenten und stoppt im natives Leerlauf, ohne seine Aufgabe zu senden. Erfordern Sie Exit-Code Null des Befehls, prepared:true, das angeforderte Modell/den Aufwand, den tatsächlichen baseCommit und den exakten Brief-Hash und die Länge vor dem Anhängen. Bewahren Sie für eine Codex-Zuweisung die angeforderte Agentenart, das Modell, den Aufwand und die explizite Service-Stufe. Halten Sie API-Anmeldeinformationen in den konfigurierten Prozess-nur-Callbacks.

Vom Koordinator, der bereits den Run besitzt, hängen Sie einmal mit den Feldern des vorbereiteten Datensatzes und einer neuen Quittungsdatei an:

orca orchestration worker-start --run "<gehörende-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane>: read the whole brief at <brief.path>, verify its SHA-256 is <brief.sha256> and its size is <brief.bytes> bytes, then follow it exactly." \
  --full --json >"<new-receipt.json>"

Dies verwendet das vorbereitete Terminal und den Worktree wieder und erstellt die native Task mit einem Zeiger auf die vollständige Aufgabenbeschreibung. Übergeben Sie keinen Agenten, kein Modell, keinen Aufwand oder keine Service-Stufe, sodass der vorbereitete Prozess seine eigenen behält. Die Ready-Quittung nennt die Task und den Dispatch. Der vorhandene Inhaber des Posteingangs behandelt ihre Nachrichten; senden Sie keinen zweiten Task-Zeiger und starten Sie keinen anderen Consumer. Bei akzeptiertem Abschluss behalten Sie die Sitzung und verwenden den Quellrückgabe- und Sammelvertrag. Behalten Sie Quittungen bei jedem Ergebnis. Ein Fehler bei der Neuerstellung kann mit dem normalen CLI-Rollback ausgeführt werden; melden Sie die tatsächlichen verbleibenden Ressourcen und wiederholen Sie niemals einen mehrdeutigen Versuch.

Erster Worker auf einem aufgezeichneten Arbeitsbereich

Version 0.15.0 fügt das Prepare-nur --existing für einen ersten Worker auf dem genauen aufgezeichneten Arbeitsbereich und beibehaltenem Checkout hinzu:

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Quelle für Root-Review zurückgeben

Verwenden Sie orca-reclaim.py mit dem Pfad zur Quittung und dem Artefaktverzeichnis des Runs für die Quellrückgabe. Dieses Skript sammelt die Aufgabe, validiert den Quellrückgabe-Vertrag und gibt die Artefakte an den Koordinator zurück.

orca-reclaim.py --receipt "<receipt.json>" --artifacts "<artifacts-dir>" \
  --run "<run-id>" --output "<output-dir>"

Fehlerbehebung

Wenn ein frisch installierter signierter Release beim ersten Start auf einem Mac hängt, beheben Sie es selbst. Dies ist eine Installationswiederherstellung, niemals eine Frage an den Eigentümer.

Stellen Sie sicher, dass die ausgewählte ausführbare Datei der signierte Release ist, entfernen Sie com.apple.quarantine von dieser einen Datei und wiederholen Sie den Versionsbefehl:

exe="$(readlink -f "<selected-executable>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<selected-cc-remote>" version

xattr gibt No such xattr aus, wenn das Attribut bereits entfernt ist. Übergeben Sie niemals -r, nennen Sie kein Verzeichnis und ändern Sie die Systemrichtlinie von Gatekeeper nicht.