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:
- Rolünüzün sahip olduğu varlığı seçin.
- JSON Schema’dan ve başvuru sayfasından yapısını öğrenin.
- Boş bir dosya yerine bir iskeletten başlayın.
- Rolünüzün sahip olduğu alanları doldurun, geri kalanını sahiplerine bırakın.
- 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 --lististeyebileceğiniz her türü listeler. Bir asistan aynı baytlarıschema://<kind>kaynağından okur.aggrega get-schemabaş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
validatearacı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 inspectise çözümleme yapıp derleyicinin gördüğünü gösterir. Tüm topoloji hazır olduğundaaggrega pull --release <release>bağımlılıklarını çözümler ve kilit dosyasını yazar, ardındanaggrega 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çinlangref://<path>ve bu kılavuz içinauthoring://<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çinvalidate, bir katalog varlığını incelemek içindescribeve türe göre bir şema getirmek içinget-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
- Personalar — bir varlık seçmeden önce dört rolü anlayın.
- Role göre varlıklar — türden role tam eşleme.
- Kurulum — ikili dosyayı kurun; MCP sunucusunu bağlama asistanınızı bağlar.
- Aggrega’yı yapay zekâ asistanınızla kurma — asistanınızın Aggrega’yı kendisinin kurmasını ve bağlamasını sağlayan tek bir istem.
- CLI’a genel bakış — her
aggregaalt komutu.