Orkestrasyon

Ajanları Run'lar, görevler, denetlenen işçiler, mesajlar ve karar kapılarıyla koordine edin.

Orkestrasyon, Nethür'ün yapılandırılmış çoklu ajan katmanıdır: bir Run (ad alanı + koordinatör gelen kutusu), Görevler, Dispatch'ler, denetlenen işçiler, mesajlar ve karar kapıları.

Sahiplik, tamamlanma takibi veya bir DAG gerektiğinde kullanın. Tek seferlik istemler için nethur terminal send kullanın. Denetim olmadan tam sahiplik devri için nethur-cli becerisindeki çalışma alanı/terminal komutlarını kullanın.

Temel model

  • Run — kalıcı ad alanı ve ana gelen kutusu. İşçileri asla zamanlamaz veya yerleştirmez.
  • Görev — bir spesifikasyon, bağımlılıklar ve durum içeren iş öğesi: pending, ready, dispatched, completed, failed veya blocked.
  • Dispatch — bir görevin bir terminaldeki tek denemesi; worker_done / kalp atışı için yaşam döngüsü yetkisi.
  • Mesaj — gelen kutusu postası (status, dispatch, worker_done, escalation, question, heartbeat, …).
  • Karar kapısı — bir görevi çözülene kadar engelleyen koordinatöre ait soru.

Tamamlanma yetkisi etkin dispatch bağlamından gelir. İşçi tamamlanma ve kalp atışı mesajları hem taskId hem dispatchId içermelidir.

Terminallerde yazdırılan task_... gibi görev kimlikleri tıklanabilir bağlantılardır. Birine tıklamak Nethür çalışma zamanından görevin geçerli dispatch'ini ister ve atanmış terminale odaklanır; görev uzak veya SSH çalışma zamanında olsa bile.

Tercih edilen denetimli döngü

bash
nethur orchestration run-create --objective "Split checkout QA and summarize blockers" --json
nethur orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
nethur orchestration worker-start --task <taskId> --worktree current --agent codex --json
# veya yeni çalışma alanı:
nethur orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# isteğe bağlı işçi başına model / çaba (Claude, Codex, Cursor, Antigravity, Muse; --terminal ile değil):
nethur orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json

--agent, işçi sunucusunda etkin olan herhangi bir Nethür ajan kimliğini alır: claude, codex, cursor, antigravity, muse, opencode veya opencode2 gibi. --model, Claude, Codex, Cursor, Antigravity ve Muse için opak sağlayıcı model kimliklerini kabul eder (örneğin --agent muse --model muse-spark-1.3); OpenCode modeli yalnızca mevcut bir çalışma alanında, yürütme hostu CLI sürümünü ve model kullanılabilirliğini doğruladığında başlatma başına kabul eder; OpenCode çabası desteklenmez. Diğer ajanlar modellerini kendi yapılandırmalarından çalıştırır. --effort, --model gerektirir ve yalnızca o ajan/model düzeyi desteklediğinde uygulanır. İki bayrak da --terminal (mevcut paneli yeniden kullan) ile birleştirilemez. Geçersiz kılmalar yalnızca o başlatmaya uygulanır ve başlatma makbuzunda launch.requested / launch.effective altında görünür. Federe başlatmalar başlatma tercihi desteğini duyuran bir işçi hostu gerektirir.

Tamamlanmaları bekleyin (bir Delivery'deki her mesajı işleyin, sonra ack):

bash
nethur orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
nethur orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --json

İşçi tamamlanması (işçi panelinden; enjekte edilen kimlikler dahil):

bash
nethur orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx" \
  --json

worker_done, --outcome succeeded|failed gerektirir.

İncele / kurtar:

bash
nethur orchestration worker-show --dispatch <dispatchId> --json
nethur orchestration worker-read --dispatch <dispatchId> --limit 50 --json
nethur orchestration worker-stop --dispatch <dispatchId> --json
# Kabul edilmiş bir worker_done sonrası: aynı terminali takip Dispatch'i için yeniden kullan veya bırak
# (incelenebilir çıktıyı arşivler, sonra yalnızca o koordinatöre ait ajan terminalini kapatır):
nethur orchestration worker-release --dispatch <dispatchId> --json
# Kullanıcı saklamayı istediyse hata ayıklama için oturmuş işçiyi canlı tut:
nethur orchestration worker-retain --dispatch <dispatchId> --json
# yeniden deneme yerleşimi açıktır — --retry-of, --on/worktree'yi miras almaz:
nethur orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --json

Yalnızca çıktıyı yeniden okumak için tamamlanmış işçi terminallerini açık bırakmayın — worker-release sonrası worker-read kullanın. Release release_pending veya release_unknown döndürdüğünde geniş bir terminal close ile ikame etmeyin; makbuzun kurtarma eylemini izleyin.

Federe işçiler (isteğe bağlı)

bash
nethur orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run \
  --json
nethur orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --json

Sonraki komutlar Dispatch ID'sine göre yönlenir; --on'ı tekrarlamayın.

Düşük düzey dispatch (özel topoloji)

bash
nethur worktree create --name billing-audit --agent codex --json
nethur terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
nethur orchestration dispatch --task <taskId> --to <workerHandle> --inject --json

Mesajlaşma notları

  • Varsayılan check bağlı Run'ın en eski onaylanmamış Delivery'sidir (FIFO). --ack'e kadar yeniden oynatın.
  • --peek / --all postayı tüketmez.
  • Grup adresleri: @all, @idle, @claude, @codex, @opencode, @gemini, @droid, @grok, @cursor, @worktree:<id> — worker_done / kalp atışı için asla.
  • @worktree:<id> dışındaki her grup gönderenin kendi Run'ının canlı Dispatch'lerini kasteder; onların Dispatch posta kutularına (veya iç içe koordinatörler için alt Run posta kutularına) teslim edilir. Hiçbir Run'da olmayan gönderen reddedilir; --run hedef kitleyle eşleşmeli ve asla üyelik vermez.
  • Run grupları sahip koordinatörlerini hariç tutar. Engel yükselten bir işçi run:<id> adresine gönderir. @worktree:<id> o çalışma alanındaki koordinatörleri içerir.
  • PowerShell grup adreslerini tırnaklayın: --to "@all".
bash
nethur orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
nethur orchestration send --to @idle --subject "Anyone free?" --json
nethur orchestration send --to @codex --subject "Codex workers in this Run only" --json

Bir bekleme etkinken CLI her 15 saniyede stderr'e küçük JSON kalp atışı satırları yayar. Stdout son komut sonucu olarak kalır.

İşçi sözleşmesi

Dispatch edilen işçiler koordinatörle nasıl iletişim kuracaklarını söyleyen bir önsöz alır:

  • worker_done'ı tam olarak bir kez gönderin, başarısızlıkta bile, --outcome ile.
  • Kısa bir --body özeti ekleyin: ne yapıldı, ne bulundu ve ne kaldı.
  • Hem görev hem dispatch kimliklerini ekleyin; böylece bayat yeniden denemeler yanlış dispatch'i tamamlayamaz.
  • Uzun etkin çalışma sırasında heartbeat mesajları gönderin.
  • Yerel TUI istemleri yerine engelleyici sorular için nethur orchestration ask kullanın.
bash
nethur orchestration ask \
  --to <coordinatorHandle> \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only" \
  --timeout-ms 600000 \
  --json

--json ile ask standart {id, ok, result, _meta} zarfını yazdırır; böylece işçiler yanıtı jq -r .result.answer ile okur.

Karar kapıları

İşçiden koordinatöre sorular için ask kullanın. Koordinatör bir görev DAG'ı oluşturduysa ve bir karar kaydedilene kadar bir görevi engellemek istiyorsa açık kapıları kullanın:

bash
nethur orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]' \
  --json

nethur orchestration gate-resolve --id <gateId> --resolution "yes" --json

Kurtarma

bash
nethur orchestration dispatch-show --task <taskId> --json
nethur orchestration dispatch-show --task <taskId> --preamble --json
nethur orchestration task-list --json
nethur orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --json

Yalnızca orkestrasyon durumunu bilinçli olarak terk ediyorsanız sıfırlayın:

bash
nethur orchestration reset --tasks --json
nethur orchestration reset --messages --json
nethur orchestration reset --all --json

reset, çalışma zamanı genelindeki orkestrasyon durumunu etkiler. Amaçlanan temizlik değilse başka bir koordinatör etkinken çalıştırmayın.

Doğru komutu seçme

İzlediğiniz bir ajana hafif bir istem için nethur terminal send kullanın.

Bir işçi worker_done bildirmek, koordinatör üzerinden soru sormak ve görev kimliğiyle izlenmek zorundaysa nethur orchestration worker-start (veya dispatch --inject) kullanın.

Kalıcı bir Run ad alanı ve denetimli çoklu ajan döngüsü istiyorsanız nethur orchestration run-create + görevler + işçiler kullanın — kullanımdan kaldırılmış orchestration run komutunu değil.

Tam rehber

Komut bayrakları uygulamayla evrilir. Kurulumdan sonra ajanlar şunu çalıştırmalıdır:

bash
nethur skills get orchestration --full