İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Aggrega dosyalarını yazma

Aggrega’da yazım kısa ve tekrarlanabilir bir döngüdür. Hangi varlığı yazıyor olursanız olun — bir geliştiricinin Aggregate’i, bir mimarın Component’i, bir operasyon Recipe’i ya da bir operatörün Release’i — aynı beş adım sizi boş bir dosyadan doğrulanmış bir dosyaya götürür:

  1. Rolünüzün sahip olduğu varlığı seçin.
  2. JSON Schema’dan ve başvuru sayfasından yapısını öğrenin.
  3. Boş bir dosya yerine bir iskeletten başlayın.
  4. Rolünüzün sahip olduğu alanları doldurun, geri kalanını sahiplerine bırakın.
  5. Doğrulayın, ardından derleyin.

Bu sayfa döngüyü bir kez, hem elle yazan bir kişi hem de Model Context Protocol sunucusu aracılığıyla yazan bir yapay zekâ asistanı için adım adım anlatır. İki yol, aynı başvuru yüzeyleri üzerindeki aynı döngüdür. Her ikisi de aggrega ikili dosyasına ihtiyaç duyar: İkili dosyayı kurun onu tek bir komutla kurar.

1. Rolünüzün sahip olduğu varlığı seçin

Aggrega yazımı birlikte çalışan dört role ayırır: geliştirici amacı, platform kataloğu, altyapı tarifleri ve dağıtım bağlantıları. Her rol genellikle belirli bir varlık türleri kümesine sahiptir. Rolünüzü zaten biliyorsanız ihtiyacınız olan varlığa geçin; bilmiyorsanız dört rol için Personalar sayfasını, türden role tam eşleme için Role göre varlıklar sayfasını okuyun.

Bu ayrım bir yol göstericidir, derleyicinin uyguladığı bir kural değildir. Tek başına çalışan bir yazar her rolü üstlenip tüm varlıkları bir oturumda yazmakta serbesttir; derleyici şema doğrulamasından geçen her yazım biçimini kabul eder. Roller, neler yazabileceğinizi kısıtlamak için değil, sorumlulukları net tutmak için vardır.

2. Yapısını öğrenin

Her varlık türünün kanonik bir JSON Schema’sı ve alan alan bir başvuru sayfası vardır. Yazmadan önce ikisini de okuyun:

  • Şema kesin yapıdır: zorunlu alanlar, izin verilen değerler ve iç içe yerleşim. Komut satırında aggrega get-schema <kind> şemayı yazdırır; aggrega get-schema --list isteyebileceğiniz her türü listeler. Bir asistan aynı baytları schema://<kind> kaynağından okur. aggrega get-schema başvurusuna bakın.
  • Başvuru sayfası her alanın ne anlama geldiğini ve alanların birbiriyle ilişkisini açıklar. Varlık sayfaları language-reference/entities/ altında bulunur — örneğin component veya aggregate. Bir asistan aynı sayfayı langref://entities/<kind> kaynağından okur.

Şema neyin yapısal olarak geçerli olduğunu söyler; başvuru ise neyin mantıklı olduğunu. Doğrulama sırasında reddedilmemek için şemayı, amaçladığınızı yapan bir şey yazmak için başvuruyu okuyun.

3. Bir iskeletten başlayın

Bir iskeletten başlamak, boş bir dosyadan başlamaktan daha hızlı ve daha az hataya açıktır. MCP sunucusuna bağlı bir asistan, türün gerektirdiği her alanı taşıyan ve henüz verilmesi gereken her değerin yerinde bir yer tutucu bulunan asgari bir başlangıç noktası elde etmek için scaffold aracını bir tür ve bir adla çağırır. Elle yazarken aggrega scaffold <kind> <name> aynı başlangıç noktasını standart çıktıya yazdırır, bu yüzden onu bir dosyaya yönlendirin; ya da en yakın çalışılmış örneği kopyalayın ve ihtiyacınız olana kadar sadeleştirin.

Her iki durumda da iskelet, zorunlu üst düzey alanları (apiVersion, kind, metadata.name) doğru yapıda zaten taşır; böylece dikkatinizi kalıp metne değil, rolünüzün sahip olduğu alanlara verirsiniz.

4. Rolünüzün sahip olduğu alanları doldurun

Yalnızca rolünüzün sorumlu olduğu sütunları doldurun, diğerlerini sahiplerine bırakın. Bir geliştirici uygulama amacını ve değerleri sağlar; bir mimar sözleşmeyi bildirir — bir geliştiricinin sağlayabileceği değerler, bir bileşenin sağladığı çıktılar, açığa çıkardığı soketler; operasyon ekibi bu sözleşmeyi geliştiriciye dönük yüzeyi değiştirmeden belirli bir sağlayıcıya eşler; bir operatör dağıtımı bağlar. Role göre varlıklar, her tür için hangi sütunların hangi role ait olduğunu ayrıntılı olarak açıklar.

Her değeri, sahibinin denetlediği sütunda tutmak, aynı geliştirici amacının geliştiricinin dosyası değişmeden ortamlar arasında farklı altyapıları hedeflemesini sağlar. Yazım yüzeyinin bölünmesinin asıl nedeni budur.

Açıklamayı birkaç kısa paragrafla sınırlı tutun. Bir varlığın metadata.description alanı, okuyucunun o varlığı seçmeden önce karşılaştığı metindir: varlıkla birlikte aranabilir açıklaması olarak yayımlanır ve aggrega search sorguyu bununla eşleştirir. Onu o an için, kısa paragraflar halinde yazın — katlanmış bir description: > bloğunda boş bir satır yeni bir paragraf başlatır — varlığın ne olduğunu, okuyucunun onu nasıl kullandığını, nerede gerçekleştirildiğini ve neyi yapmadığını belirtin. Okuyucunun varlığı seçmeden önce bilmesi gereken bir sınırlama da kısaca belirtilerek oraya aittir. Geri kalan her şey — bir varsayılanın neden öyle olduğu, bir ayarın tek bir hedefte nasıl davrandığı, bir değerin her gerçekleştirmede ne anlama geldiği — açıkladığı alanın veya bloğun yanındaki YAML yorumlarına yazılır; o alanla çalışan kişi onu orada okur. Derleyicideki hiçbir şey bir açıklamanın uzunluğunu sınırlamaz veya söylediğine göre işlem yapmaz; dolayısıyla onu kısa tutmak okuyucunun yararınadır.

5. Doğrulayın, ardından derleyin

Dosyaya güvenmeden önce onu denetleyin:

  • Bir asistan validate aracını çağırır; bu araç şema ve başvuru hatalarını satır içinde bildirir, böylece asistan taslağı geri vermeden önce düzeltebilir.
  • Elle çalışırken aggrega validate <file> tek bir Component, Feature, Recipe, FeatureRecipe, Workload veya Plugin dosyasını denetler; aggrega validate --release <release> ise bir Release’in ulaştığı her şeyi, Aggregate’i ve Manifest’i de dahil olmak üzere denetler. aggrega lint, bir katalog varlığı üzerinde yayımlama disiplini kurallarını çalıştırır; aggrega inspect ise çözümleme yapıp derleyicinin gördüğünü gösterir. Tüm topoloji hazır olduğunda aggrega pull --release <release> bağımlılıklarını çözümler ve kilit dosyasını yazar, ardından aggrega build --release <release> Release’i sınır başına yapıtlara derler — başarısız bir derleme neyin düzeltilmesi gerektiğini tam olarak belirtir.

Erken doğrulama, geç gelen başarısız bir derlemeden daha ucuzdur. Yazın, doğrulayın, düzeltin ve ancak ondan sonra derleyin.

Bir yapay zekâ asistanıyla yazım

aggrega mcp komutu, MCP destekli herhangi bir istemciyi Aggrega’yı tanıyan bir yazım asistanına dönüştüren bir Model Context Protocol sunucusu çalıştırır. Bağlandıktan sonra asistan şunları yapabilir:

  • Yerleşik yazım istemleriyle bir rol üstlenmek — her persona (geliştirici, mimar, operasyon) için bir istem ve buna ek olarak varlığa özel odaklı bir şablon. Her istem rolü çerçeveler ve asistanı şemaya, başvuru sayfasına ve bu kılavuza yönlendirir; böylece önerileri rolün sahip olduğu sütunların içinde kalır.
  • Kaynaklar aracılığıyla başvuruyu okumak: bir türün JSON Schema’sı için schema://<kind>, herhangi bir başvuru sayfası için langref://<path> ve bu kılavuz için authoring://<topic>.
  • Araçlar aracılığıyla çalışma alanınızda işlem yapmak: doğru bir iskeletle başlamak için scaffold, bir taslağı denetlemek için validate, bir katalog varlığını incelemek için describe ve türe göre bir şema getirmek için get-schema.

Asistanın okuduğu her şey makinenizden sunulur: şemalar ikili dosyaya gömülüdür, kılavuz ve başvuru sayfaları ise makinenizin önbelleğinde tutulan belge paketinden gelir; sunucu başladığında orada bir kopya bulamazsa bu paketi kayıt defterinden getirir. Bir sayfayı okumak, iskelet oluşturmak ve doğrulamak ağa erişmez; paket getirilemediğinde şemalar yine sunulur, sayfalar sunulmaz. Bir istemciyi bağlamak için MCP sunucusunu bağlama adımlarını izleyin; asistanın eriştiği diğer her şeyi Asistanınızın Aggrega ile yapabilecekleri ele alır. Komutun kendisi için aggrega mcp başvurusuna bakın.

Sonraki adımlar