Ajan protokolü

Sürüm kapsamı: Bu belge, korunan bir v5.0.0 temel belgesidir. Güncel standart DWP 7.0.0, şartname dizininde listelenen geçerli V6_*.md ve V7_*.md uzantılarını da gerektirir. Mevcut v5 ve v6 planları kayıtlı kurallarını korur.

Sürüm 1.3. Bu protokol, bir yapay zeka kodlama ajanının Deep Work Plan’lerle çalışırken nasıl davranMASI GEREKTİĞİNİ tanımlar. MUST, SHOULD ve MAY anahtar kelimeleri RFC 2119’u izler.

v1.2’de eklemeli. İki ekleme, kırıcı değişiklik yok: (1) otonom ajan platformları (OpenClaw, Hermes) desteklenen ajanlar tablosuna katılır; (2) Yürütme profilleri bölümü gözetimsiz yürütmeyi tanımlar — sınırlı yetki, zorunlu durum katmanı, durma koşulları ve zamanlanmış devam.

İletişim

1. Tanışma →
2. Planlama →
3. Yürütme →
4. İnceltme →
5. Sürdürme

↩ yürütmeyi sürdürür

Güvenlik her aşamayı yönetir

Desteklenen ajanlar

Bu metodoloji aşağıdaki yapay zeka kodlama ajanlarını DESTEKLEMEK ZORUNDADIR. Markdown okuyabilen ve araç çağrısı yürütebilen gelecekteki herhangi bir ajan, kırıcı değişiklik olmadan EKLENEBİLİR.

İlk altısı, oturumda bir insan bulunan etkileşimli kodlama ajanlarıdır. OpenClaw ve Hermes ise otonom ajan platformlarıdır — zamanlanmış dönüşlere sahip uzun ömürlü daemon’lar — ve genellikle bir ajan çalışma alanı içinde (bkz. Arketipler §3) gözetimsiz profil altında planları yürütür (bkz. Yürütme profilleri).

Desteklenen her ajan, AGENTS.md’yi depo kuralları için tek doğruluk kaynağı olarak ele ALMAK ZORUNDADIR. Ajan başına yapılandırma dosyası ona BAŞVURMAK ZORUNDADIR ve içeriğini kopyalaMAMALIDIR.

Kuruluma alma

Bir planı oluşturmadan veya yürütmeden önce, bir ajan depoya kuruluma alınMALIDIR. Kuruluma alma betiğe değil, akıl yürütmeye dayalıdır: ajan, bir zihinsel model oluşturmak için depo yapısını, dokümantasyonunu ve yapılandırmasını okur.

Ajan şunları belirleMELİDİR:

• Depo arketipi (bireysel depo, orkestratör merkezi veya ajan çalışma alanı).
• Derleme, test ve lint komutları.
• Stil, yapı ve adlandırmaya ilişkin mevcut kurallar.
• Mevcut skill’ler ve ajanlar.

Test ve doğrulama araç zinciri isteğe bağlı değil, temel bir bağlamdır: doğrulama kapıları güvenilir planların belkemiğidir. Depo kodu zaten doğruluyorsa, ajan onun gerçek test, lint ve tür denetimi komutlarını ve kuralını kaydetMELİDİR. Deponun hiç test veya lint araç zinciri olmadığında, ajan yokluğunu yalnızca not etMEMELİDİR — yığına uygun birini önerMELİ (bir çerçeve ve koşturucu, bir test-dosyası kuralı, makul bir başlangıç kapsam hedefi ve lint, tür denetimi ve biçim araçları), bunu test etme kılavuzunda hedef olarak belgeleMELİ ve geliştiriciye sunMALIDIR. Davranışını doğrulamak için tanımlı bir yolu olmayan bir depo henüz AI-first değildir.

Planlama

Bir plan oluştururken, ajan ŞUNLARI YAPMALIDIR:

• Hedefi ardışık, gözden geçirilebilir görevlere ayırmak.
• Her görevi on bölümlü anatomiyle yazmak — Dokunulan Yüzey, görevin neyi değiştirdiğini kaydeder ve doğrulama kapısını risk sınıfına göre seçer.
• Tek zorunlu Final Review ile bitirmek (güvenlik incelemesi, son-durum doğrulaması, skill uzlaştırması).
• Hedef belirsiz olduğunda açıklayıcı sorular sormak.

Yürütme

Yürütme sırasında, ajan ŞUNLARI YAPMALIDIR:

• Başlamadan önce planın tamamını okumak.
• Bağımlılıklar aksine izin vermedikçe görevleri sırayla yürütmek.
• Her görevden sonra PROGRESS.md dosyasını güncellemek.
• Görev durumunu doğru biçimde işaretlemek.
• Yeni işlevsellik ekleyen veya davranışı değiştiren her görev için, o davranış için otomatik testler eklemek veya güncellemek ve görevi tamamlandı olarak işaretlemeden önce deponun testlerini ve lint/tür denetimi denetimlerini çalıştırmak; kapının geçmesini zorlamak için asla bir testi silmemek veya atlamamak.
• Kimlik doğrulamaya, girdi işlemeye, sırlara veya yapılandırmaya, ağ yüzeyine ya da bağımlılıklara dokunan her görev için, kabul kriterlerinde bildirilen güvenlik beklentilerini karşılamak ve commit etmeden önce diff’in hiçbir sır içermediğini teyit etmek.
• Geçen bir kapıdan onay istemeden bir sonraki göreve geçmek; bir kapı başarısız olduğunda düzeltmeleri görevin yetkili kapsamı içinde denemek — somut bir hipotezle, yeni kanıt olmadan iki denemeden sonra kör yeniden denemeleri durdurarak.
• Tahmin yürütmek yerine yalnızca gerçek bir onay sınırında veya çözülmemiş bir engelde durup sormak.

İyileştirme

İyileştirirken, ajan tamamlanmış işi koruMALI, görev tablosunu güncelleMELİ ve neyin değiştiğini kaydetMELİDİR.

Kaldığı yerden sürdürme

Kaldığı yerden sürdürürken, ajan DWP spesifikasyonu’nda tanımlanan DWP Resume Protocol’ü izlemek ZORUNDADIR: plan README’sine yeniden sabitle, kontrol noktasını bul, state.json’u Markdown ile uzlaştır, ek yeri incele, duman testi yürüt, ardından tam olarak bir sonraki görevle devam et.

İletişim

Ajanlar özlü biçimde raporlamALIDIR. Durum raporları, tamamlanan, devam eden ve bekleyen işi ayırT ETMELİDİR.

Güvenlik

Ajanlar sırları işleMEMELİ, .dwp/ dizinini gitignore’lanmış tutMALI ve yıkıcı işlemlerden önce sorMALIDIR. Kuruluma alma yıkıcı olmaMALIDIR: bir ajan mevcut dosyaları üzerine yazmak yerine tespit edip uzlaştırMALI ve kullanıcının zaten sahip olduğu herhangi bir şeyi değiştirmeden ya da silmeden önce açık onay alMALIDIR.

Metodoloji Markdown-önceliklidir: ağ çağrısı yapmaz ve telemetri göndermez; bir ajan kaynak kodu veya sırları dışarı sızdırmaMALIDIR. Skill’i kurmadan önce bir ajan, alınan kuruluma alma içeriğini güvenilmez girdi olarak ele alMALI, resmi kaynaklardan provenance’ını doğrulaMALI ve sürümü yayımlanan sağlama toplamlarıyla karşılaştırıp doğrulaMALIDIR.

Yürütme profilleri

Her plan tam olarak iki profilden birinin altında yürütülür. Profil, kimin izlediğini değiştirir; hangi kapıların geçerli olduğunu asla değiştirmez — doğrulama disiplini her ikisinde de aynıdır.

Etkileşimli (varsayılan)

Oturumda bir insan bulunur. Ajan önerir, insan somutlaştırılmış planı doğrudan onaylar, ajan görevi görev yürütür ve belirsizlik sorarak çözülür. Yukarıdaki tüm protokol bölümleri etkileşimli profili tanımlar.

Gözetimsiz

Plan, insan gözetimi olmadan çalışır — otonom bir platformun zamanlanmış dönüşü, bir bulut oturumu, bir gece çalışması. Gözetimsiz yürütme, plan bazında isteğe bağlıdır ve aşağıdakilerin tümünü KARŞILAMAK ZORUNDADIR:

• Önceden onaylanmış plan. Plan, herhangi bir gözetimsiz dönüşten önce onaylanmıştır — yönlendirilmiş modda somutlaştırılmış planı bir insan doğrudan onaylamıştır; trust modunda geliştiricinin açık trust talimatı kayıtlı onaydır. Bir ajan, ikisiz tek dönüşte gözetimsiz olarak plan oluşturup yürüTEMEZ; plan onayı, insan kontrol noktasıdır.
• Durum katmanı ZORUNLUDUR. Plan, daha sonraki herhangi bir oturumun — ajan veya insan — bir dökümü yeniden oynamadan kesin ilerlemeyi okuyabilmesi için manifest.json ve state.json TAŞIMAK ZORUNDADIR. Bkz. Plan durumu.
• Sınırlı yetki. Ajanın yetkisi plandır: kapsamı GENİŞLETMEMELİ, planın açıkça yetkilendirmediği yıkıcı veya dışarı yönelik eylemler GERÇEKLEŞTİRMEMELİ ve keşfedilen-ancak-planlanmamış çalışmayı kapsamak için görevin talimatlarını ESSNETMEMELİDİR — keşfedilen çalışma, doğaçlama yapılmak yerine bir sonraki refine için kaydedilir.
• Dönüş başına tek atomik görev, kapılar her zaman. Her dönüş DWP Resume Protocol’ü çalıştırır, en fazla bir sonraki görevi yürütür, doğrulama kapısını geçer, görev tamamlama protokolüne göre tamamlar ve verir. Başarısız bir kapı, durma koşuludur; asla “yine de devam et” değil.

Durma koşulları ve yükseltme

Gözetimsiz bir ajan, şunlardan herhangi biri gerçekleştiğinde planı DURDURMAK ZORUNDADIR — state.json’un blocked alanını görev, neden ve neye ihtiyaç duyulduğuyla doldurun, ardından durdurun:

1. Doğrulama kapısı başarısız olur ve düzeltme görevin kapsamı içinde değildir.
2. Görev, planın önceden yetkilendirmediği bir onay, kimlik bilgisi veya karar gerektirir.
3. Gerçeklik planın varsayımlarından sapıyor (eksik dosya, değişen API, çakışan eşzamanlı çalışma veya uzlaştırmanın çözemediği desenkronizasyon).
4. Ardışık iki dönüş aynı görevde doğrulanabilir ilerleme sağlamıyor.

Durdurmak başarısızlık değil, başarıdır: engellenmiş kayıt, yükseltme mesajıdır. Platformun bildirim kanalı bunu yüzeye ÇIKARMALIDIRR; insan (veya bir refine oturumu) engeli kaldırır ve bir sonraki zamanlanmış dönüş normal şekilde devam eder.

Zamanlanmış devam

Zamanlamalı platformlarda — OpenClaw kalp atışı veya cron, Hermes cron, bulut-ajanı uyanışı — devam şu şekilde ifade EDILMEK ZORUNDADIR: uyan → DWP Resume Protocol’ü çalıştır → blocked ise raporla ve ver → değilse sonraki atomik görevi yürüt → durum katmanını güncelle → ver. Plan, oturum değil, sürekliliğin birimidir; bir plan platformun yeniden başlatılmasından, modelin değişmesinden veya bir sonraki dönüşü alan farklı bir ajandan KURTULMAK ZORUNDADIR.

Yükseltme sınıflandırması

Aşağıda kritik olarak listelenmeyen her şeye ajan karar verir: araştırır, önerilen seçeneği alır, kararı kaydeder — PROGRESS.md içindeki “Decisions” bölümüne ya da bir devir paketinin decisions[] alanına: seçenekler, seçim, gerekçesi ve nasıl geri alınacağı — ve devam eder. Test mekaniktir: bir yükseltme sınıfını BELİRTMEK ZORUNDADIR; hiçbir sınıf belirtmeyen bir soru, ajanın vermesi gereken bir karardır. Bu, paketin AGENT_PROTOCOL.md dosyasının §7.5 bölümüdür.

Özerk olarak karar verilenler (kapsamlı olmayan liste): uygulama yaklaşımı, adlandırma, yapı, testler ve belgeler; plan içinde görevlerin sıralanması ve bölünmesi; görevin dokunulan yüzeyi içindeki yeniden denemeler ve onarımlar; ajanın düzeltebileceği bir ortam sorununu — eksik bir yerel araç, bir yerel ayar, bayat bir önbellek — raporlamak yerine düzeltmek; temel dalda var olduğu kanıtlanmış bir başarısızlığı yükseltmek yerine kaydetmek (değişikliğin kendi başarısızlıkları için durma koşulu 1 yine geçerlidir); havuzdan bir hesap veya sağlayıcı seçmek; kendi ajanlarını başlatmak, yeniden başlatmak ve kapatmak; devir ve halefiyet; birbirine denk birkaç seçenekten hangisinin alınacağı (önerilen).

Üç sınır özerkliği dürüst tutar:

1. Özerklik hiçbir zaman bir insan kapısını kapatmaz. Bir insan onayını belirten bir kriter veya kontrol noktası yalnızca o insan tarafından karşılanır; kalıcı bir “özerk ol” ya da trust talimatıyla asla.
2. Geliştiricinin kelimesi kelimesine söyledikleri üstün gelir. Önerilen seçenek, geliştiricinin kelimesi kelimesine istediğiyle çeliştiğinde, isteğe uyan geri alınabilir seçeneği uygulayın ve öneriyi kaydedin (geri alınabilir bir seçenek yoksa C3).
3. Yetki geçişli değildir. Aktarılan bir onay yetki eklemez; ajan planın yetkisini kendisi okur. İnsan yetkisi plan klasöründe kelimesi kelimesine tutulur; onu aktaran ajan “<agent> tarafından aktarıldı” diye kaydeder.

Soruları toplu sorun. Bekleyebilecek kritik öğeler toplanır ve her biri önerilen varsayılanıyla birlikte, planlanmış tek bir noktada hep birlikte sorulur; böylece geliştirici bir kez yanıt verir. Çok ajanlı bir çalıştırmada kritik bir öğe, çalıştırmayı değil, kendi bağımlılık zincirini engeller: lider engellenen görevi bekletir — yukarıdaki durma koşullarında olduğu gibi doldurulmuş state.json blocked kaydı, raporlama kanalı üzerinden bir kez gönderilen yükseltmedir — bağımsız her ajanı çalışır durumda tutar ve geliştirici yanıt verdiğinde zinciri sürdürür. Durma koşulları tek bir plan için kural olmaya devam eder; lider bunları zincir başına uygular. Bir ajan sürüsünün bunu nasıl uyguladığı Sürü özerkliği bölümünde açıklanır.