Pantrix UI

Pantrix'i bir asistana öğretmek

Kodlama asistanlarının (Claude, Copilot, Cursor…) Pantrix'i tahminle değil kütüphanenin kendi kaynaklarından öğrenmesi için yazılan belgeler.

Burada söylenen her şey bu depoda koşan testlerde ve derlemelerde görülmüştür. Neyin nerede görüldüğü 9. bölümde yazılıdır. Sunucu ve belgeleri kütüphaneyle, onun sürümünde com.pantrixui:mcp olarak yayınlanır (4. bölüm).

1. Sorun

Kütüphaneyi kaynaklarından okumamış bir asistan şunları yapar:

Elle yazılan bir belge bunların bir kısmını çözer ama kütüphane değiştikçe bayatlar. Bir parametre yeniden adlandırılır, belgede eski adı kalır, asistan o eski adı yazar.

2. Üretilenler

DosyaNeNe için
llms.txtDizin, llmstxt.org'un biçiminde. Kütüphanenin ne olduğu, artifact'ları, onunla yayınlanan araçlar (detekt kuralları ve bu sunucu), en küçük uygulama ve Pantrix'le yazılan kodun kuralları; demo'nun her sayfası için, bölümünün altında bir satır (bağlantı, özetinin ilk cümlesi, bileşenin adı); her rehber için bir satır (bağlantı, özetinin ilk cümlesi); modüllerin API başvuruları; skill'in bağlantısı. 33 KB kadar, yaklaşık 8.500 token.Bir asistanın ilk okuyacağı dosya: neyin nerede olduğunu söyler.
llms-full.txtHepsi bir dosyada: aynı açılış, demo'nun 118 sayfası menünün sırasıyla, 24 rehber, ardından hiçbir sayfanın belgelemediği API, modül modül. Bağlantı taşımaz. 4,7 MB kadar, yaklaşık 1,3 milyon token.Bağlamı çok geniş bir model ya da bir belge dizinine (RAG) yüklemek.
pages/<anahtar>.mdDemo'nun bir sayfası: özeti, özellikleri, bileşenin kısa örnekleri, derlenen örnekleri (importlarıyla ve kullandıkları yardımcıların koduyla) ve sayfanın belgelediği API. Anahtar web'deki adrestir: date-picker.Tek bir ekran yazdırırken o ekranın bileşenini vermek.
api/<modül>.mdBir modülün bütün genel API'si, paket paket: imzalar, açıklamalar, parametreler, enum girdileri, üyeler.Bir bildirimin tamamına bakmak.
guides/<anahtar>.mdUygulamalara dönük bir rehber, İngilizce: kütüphanenin bir parçasının bir uygulama boyunca nasıl kullanıldığı, her Compose Multiplatform uygulamasının orada karşılaştığı sorun, kütüphanenin cevabı, tuzakları ve nasıl sınandığı. Anahtar rehberin _GUIDE'sız, küçük harfli adıdır: docs/guide/date-time/DATE_TIME_GUIDE.en.md, guides/date-time.md'dir. Bağlantıları belgeler arasındaki öteki rehberlere, deponun öteki dosyalarına ise GitHub'da gider.Bir asistana bir uygulamanın bütün bir parçasının nasıl yapıldığını vermek: testleri, pencereye göre düzeni, tarihler, pano.
pantrix-ui.jsonKütüphane veri olarak: modüller, sayfalar ve örnekleri, bileşenler, her genel bildirim ve parametreleri. 5 MB kadar.Araçlar: MCP sunucusu, bir site, bir kod üretici.
pantrix-ui.schema.jsonpantrix-ui.json'ın JSON Schema'sı (2020-12). Elle yazılır: ai/schema/pantrix-ui.schema.json.JSON'u okuyan bir aracın neye güvenebileceğini bilmesi.
CHANGELOG.mdDeponun değişiklik günlüğü, olduğu gibi.Bir sürümde neyin değiştiği.
tr/pages/<anahtar>.md, tr/guides/<anahtar>.md, tr/CHANGELOG.mdDemo sayfalarının, uygulamalara dönük rehberlerin ve değişiklik günlüğünün Türkçesi, aynı biçimde. Bir sayfa demo'nun yazdığı gibidir, örneklerinin kodu da; API'sinde kütüphanenin KDoc'u Türkçesi olan yerde Türkçe, olmayan yerde İngilizcedir. Bileşenlerin anotasyonundan gelenler, açıklamaları ve kısa örneklerinin başlıkları, İngilizce kalır. Bir rehberin bağlantıları öteki rehberlerin Türkçesine gider. Dizin (llms.txt) ve MCP sunucusu yalnızca İngilizcesini anar.Türkçe okuyan bir yer, örneğin sitenin Türkçe sayfaları.
skills/pantrix-ui/Skill. SKILL.md: nereye bakılacağı, kütüphanenin kuralları ("Core rules"), Material'ın adlarının Pantrix'teki karşılıkları, bir ekranı yazmanın ve kodu gözden geçirmenin adımları, referansların listesi. references/: kurulum, tema, yerleşim, formlar, katmanlar, grafikler, diller ve platform servisleri, erişilebilirlik, testler, Material 3. Elle yazılır (ai/skills/pantrix-ui/); yalnızca references/components.md her derlemede katalogdan yazılır: her bileşen importu, ne için olduğu, anahtar sözcükleri, etiketleri ve sayfasıyla, ve ikonlar.Bir asistanın kurduğu skill (4. bölüm). llms.txt ve prompt'lar kuralları buradan okur; MCP sunucusu skill'in kendisini de verir (get_rules, get_documentation_page, pantrix://skill).
files.txtBütün belgelerin listesi, satırda bir yol.Jar'ın kaynaklarını listeleyemeyen bir okuyucu: sunucunun docs ve skill komutları.

3. Üretmek

./gradlew :ai:mcp:generateAiDocs

Bir site için

Belgeler bir siteden sunulacaksa adresi verilir; bağlantılar o zaman mutlak olur:

./gradlew :ai:mcp:generateAiDocs -Ppantrix.ai.baseUrl=https://site-adresi

4. Bir asistana vermek

MCP sunucusu

Bir asistan belgeleri en iyi Pantrix'in MCP sunucusundan okur: neyi soracağını kendisi seçer ve yalnızca gerekeni alır. Sunucu kendi başına çalışan tek bir jar'dır, mcp-<sürüm>-all.jar, ve üç yerden alınır:

NeredenNasıl
SürümPaket deposunun her sürümüne ekli bir dosyadır ve token istemez: https://github.com/develappsancho/pantrix-ui-cmp-package/releases/download/v<sürüm>/mcp-<sürüm>-all.jar.
GitHub PackagesKütüphaneyle birlikte, all sınıflandırıcılı com.pantrixui:mcp olarak yayınlanır; okumak read:packages izinli bir token ister (yayın rehberi).
Bu depo./gradlew :ai:mcp:allJar onu ai/mcp/build/libs/mcp-<sürüm>-all.jar'a yazar; ./gradlew publishToMavenLocal'dan sonra ~/.m2/repository/com/pantrixui/mcp/<sürüm>/'dedir.

Bir asistanın ayarlarında onu çalıştıran komut anılır. Claude Code'da:

claude mcp add pantrix-ui -- java -jar /yol/mcp-<sürüm>-all.jar

Ayarlarını bir mcpServers alanından okuyan istemcilerde (Claude Desktop, Cursor…):

{
  "mcpServers": {
    "pantrix-ui": {
      "command": "java",
      "args": ["-jar", "/yol/mcp-<sürüm>-all.jar"]
    }
  }
}

HTTP üzerinden

Sunucu bir siteden, kendi adresinde de sunulur (https://pantrixui.com/mcp gibi). Asistana o zaman yalnızca adres verilir; kullanıcının makinesinde ne Java ne jar gerekir:

claude mcp add --transport http pantrix-ui https://site-adresi/mcp

Bir .mcp.json'da ya da mcpServers alanında girdi "type": "http" ve "url" alır.

Sitede sunucuyu PantrixMcp.http() verir: MCP'nin Streamable HTTP taşıması, bir web çatısına bağlı olmadan. Sitenin kendi sunucusu, Spring Boot, Ktor ya da bir servlet, adrese gelen her isteği answer(method, headers, body)'ye verir ve dönen Response'u (durum, başlıklar, gövde) olduğu gibi yazar. Spring Boot'ta (WebFlux, kotlinx-coroutines-reactor ile):

@RestController
class McpEndpoint {
    private val mcp = PantrixMcp.http(origins = setOf("site-adresi"))

    @RequestMapping("/mcp")
    suspend fun answer(
        request: ServerHttpRequest,
        @RequestBody(required = false) body: String?
    ): ResponseEntity<String> {
        val answer = mcp.answer(request.method.name(), request.headers.toSingleValueMap(), body.orEmpty())
        val response = ResponseEntity.status(answer.status)
            .headers { headers -> answer.headers.forEach { (name, value) -> headers.set(name, value) } }
        return if (answer.body.isEmpty()) response.build() else response.body(answer.body)
    }
}

Claude code eklentisi

Paket deposu Claude Code'un bir eklenti pazarıdır da. Tek eklentisi pantrix-ui, sürümün skill'ini getirir; MCP sunucusu bir siteden sunulduğunda eklenti onun adresini de taşır (release.sh'deki MCP_URL):

claude plugin marketplace add develappsancho/pantrix-ui-cmp-package
claude plugin install pantrix-ui@pantrix-ui

Skill

Skill bir asistana Pantrix'le nasıl çalışılacağını öğretir: kuralları, bir ekranı yazmanın adımlarını ve kütüphanenin parçalarının birbirine nasıl oturduğunu. Agent Skills biçimindedir: bir klasör, içinde SKILL.md ve referansları. Asistan SKILL.md'nin açıklamasından onu ne zaman kullanacağını anlar, referansları gerektikçe okur.

java -jar mcp-<sürüm>-all.jar skill <klasör>

Başka bir projede, baştan sona

Pantrix'i kullanan bir uygulamanın deposu skill'i ve sunucuyu şöyle alır. İlk iki adım her makinede, ötekiler uygulamanın deposunda atılır. Claude Code'da en kısa yol eklentidir (yukarıda); bu tarif skill'i depoya koyar ve her asistanda çalışır.

  1. Kütüphane: uygulama paketleri yerel Maven deposundan (Pantrix'in deposunda ./gradlew clean publishToMavenLocal'dan sonra mavenLocal()) ya da GitHub Packages'tan (token'la) alır; iki deponun satırları ve bağımlılıklar skill'in references/setup.md'sinde, yayının ayrıntısı yayın rehberindedir.

  2. Jar: sunucunun jar'ı sürümden indirilir ya da yerel yayından sonra yerel Maven deposundadır. Her makine onun yerini kendi ortam değişkeninde tutar, ör. kabuğun profilinde:

        # Sürümden
    curl -fL --create-dirs -o ~/.pantrix/mcp-<sürüm>-all.jar https://github.com/develappsancho/pantrix-ui-cmp-package/releases/download/v<sürüm>/mcp-<sürüm>-all.jar
    export PANTRIX_MCP_JAR=$HOME/.pantrix/mcp-<sürüm>-all.jar
    # Ya da Pantrix'in deposunda publishToMavenLocal'dan sonra
    export PANTRIX_MCP_JAR=$HOME/.m2/repository/com/pantrixui/mcp/<sürüm>/mcp-<sürüm>-all.jar

  3. Skill: uygulamanın kökünde java -jar "$PANTRIX_MCP_JAR" skill .claude/skills. .claude/skills/pantrix-ui/ git'e girer; ekip skill'i depoyla alır.

  4. Sunucu: uygulamanın kökünde bir .mcp.json:

        {
      "mcpServers": {
        "pantrix-ui": {
          "command": "java",
          "args": ["-jar", "${PANTRIX_MCP_JAR}"]
        }
      }
    }

    Claude Code ${PANTRIX_MCP_JAR}'ı her makinenin kendi değişkeniyle açar: dosya git'e girer, jar'ın yolu girmez. Etkileşimli bir oturum depodaki sunucuyu ilk açılışta onaya sorar; claude -p sormadan yükler. Sunucu bir siteden sunuluyorsa girdi yalnızca adresi taşır ("type": "http", "url") ve 2. adıma gerek kalmaz.

  5. Denemek: uygulamanın klasöründe claude açılır. /skills listesinde pantrix-ui, /mcp listesinde bağlı pantrix-ui görünür. "Bir kayıt ekranı yaz" gibi bir istekte asistan skill'i yükler, sunucunun araçlarını çağırır ve Pantrix'in bileşenleriyle yazar (9. bölümdeki deneme).

  6. Güncel tutmak: Pantrix güncellenince 1–3 yeniden atılır: kütüphane, jar ve skill aynı sürümden olur. Skill komutu klasörü baştan yazar; değişiklik uygulamanın deposunda bir commit'tir.

  7. Öteki asistanlar: ayarlarını bir mcpServers alanından okuyan istemciler aynı girdiyi kendi ayar dosyalarında alır. Skill'leri okuyan bir asistan pantrix-ui klasörünü kendi skill klasöründen okur. İkisini de okumayan bir asistana llms.txt verilir (aşağıda).

Dosyaları vermek

Ne zamanNe verilir
Asistan Pantrix'te bir ekran ya da bir özellik yazacakllms.txt. Asistan gerektikçe ilgili sayfayı ya da modülün başvurusunu okur.
Tek bir bileşenle çalışılacakO bileşenin sayfası: pages/data-table.md. Sayfada örneklerin kodu importlarıyla, bileşenin bütün parametreleri açıklamalarıyla vardır.
Asistanın her şeyi bir seferde bilmesi isteniyorllms-full.txt. Büyüktür: bağlamı geniş bir model ya da bir belge dizini için.
Bir araç Pantrix'i okuyacakpantrix-ui.json ve şeması (7. bölüm).

5. Belgelerin kaynağı

Belgelerin her satırı derlemenin zaten tuttuğu bir kaynaktan gelir:

KaynakBelgelere giren
Kütüphanenin KDoc'u (İngilizce)Her genel bildirimin, parametrenin, enum girdisinin ve üyenin açıklaması. detekt'in UndocumentedParameter kuralı açıklamasız bir parametrede derlemeyi durdurur (detekt rehberi).
@PantrixComponent ve @PantrixExampleBileşenin adı, grubu, tek cümlelik açıklaması, anahtar sözcükleri ve kısa örnekleri.
Demo'nun sayfaları (@DemoPage, @DemoExample)Sayfanın özeti ve özellikleri, örneklerin başlıkları, açıklamaları ve kodu.
Demo'nun İngilizcesi (app/shared/src/commonMain/translations/en)Sayfaların ve örneklerin İngilizcesi; örneklerin kodundaki metinler de.
READMEİlk paragrafı kütüphanenin özeti, ilk Kotlin örneği en küçük uygulamadır. Örneği de derleme kütüphaneye karşı okur (6. bölüm).
ai/skills/pantrix-ui/Skill, elle yazılmış hâliyle. SKILL.md'nin "Core rules" bölümü kütüphanenin kurallarıdır: skill'in, llms.txt'nin, get_rules'un ve prompt'ların söylediği, kuralların yazıldığı tek yer.
Rehberlerin İngilizcesi (docs/guide/<anahtar>/X_GUIDE.en.md)Uygulamalara dönük rehberler (guides/<anahtar>.md). Derleme önce her birini Türkçesine karşı okur (6. bölüm).
Rehberlerin Türkçesi (docs/guide/<anahtar>/X_GUIDE.md) ve CHANGELOG.tr.mdTürkçe belgeler (tr/guides/<anahtar>.md, tr/CHANGELOG.md): yalnızca İngilizcesi de olan rehberler.
Demo'nun kendi metinleri ve KDoc'un Türkçesi (app/shared/src/commonMain/translations/tr)Sayfaların Türkçesi (tr/pages/<anahtar>.md).

6. Derlemeyi durduranlar

Belgeler bir asistana yanlış bir şey söyleyecekse ya da hiçbir şey söylemeyecekse görev derlemeyi durdurur; sunucunun jar'ı da, paketlediklerinin bildirimi paketledikleri değilse durdurur. Mesaj neyin nerede düzeltileceğini söyler:

NeMesajDüzeltmek
Hiçbir sayfanın belgelemediği bir bileşenui/…/Gauge.kt:198: no page of the sample app documents PantrixGauge, …Bileşen sayfasının @DemoPage'inde, api'de anılır.
@PantrixExample'da kütüphanenin hiçbir biçiminde olmayan adlı bir argümanPantrixButton, "Primary action": tag is given to PantrixButton, and no form of PantrixButton has a parameter of that nameÖrneğin kodu bileşenin bugünkü imzasıyla yazılır.
İngilizcesi olmayan bir demo metniThese texts of the sample app have no English, … ve eksik metinlerin listesi./gradlew :app:shared:generateDemoCatalog çalıştırılır ve app/shared/build/reports/demoCatalog/translations/en altındaki dosyalar doldurulup translations/en'e kopyalanır (demo kataloğu).
Belgelerde aynı kimliği alacak iki bildirim… would share the id … in the documents for coding assistantsBildirimlerden birinin adı değiştirilir.
Anahtar sözcüğü boş, küçük harfle yazılmamış ya da bir sözcüğü iki kez veren bir bileşenui/…/Button.kt:144: the @PantrixComponent of Button gives no keywords. …Anotasyonun keywords'üne, bileşeni arayan birinin kullanacağı ve adında geçmeyen sözcükler yazılır: başka tasarım sistemlerinin ve platformların ona dediği, ne için kullanıldığı (snackbar için toast, undo). Üç ile sekiz, İngilizce ve küçük harfle.
Skill'in ya da README'nin ilk örneğinin, kütüphanede olmayan bir adı (PantrixSlider) ya da bir tipin olmayan bir girdisini veya üyesini (ButtonVariant.Primary) anmasıai/skills/pantrix-ui/SKILL.md:73: ButtonVariant has no Primary Ad kütüphanenin bugünkü adıyla yazılır.
Bir Kotlin bloğunda kütüphanede olmayan bir import, import edilmeyen bir kütüphane adı ya da hiçbir biçimde olmayan adlı bir argüman…/references/overlays.md:55: PantrixDialog is the library's, and the code does not import it: import com.pantrixui.components.overlay.dialog.PantrixDialog Blok importlarıyla ve imzanın bugünkü adlarıyla yazılır.
Yayınlanmayan bir artifact ya da kütüphanenin sürümünden başka bir sürüm…/references/setup.md:36: com.pantrixui:components:0.2.0 is not the version the library is published in, 0.1.0-SNAPSHOTSürüm version.properties'tekidir: sürüm yükseltilince skill'dekiler de yükseltilir.
Skill'in biçimi: adı klasörününki değil, açıklaması 1.024 karakterden, SKILL.md 500 satırdan uzun; SKILL.md'den bağlanmayan bir referans, skill'in bir dosyasına gitmeyen bir bağlantı; 100 satırdan uzun olup başında bölümlerini sayan bir Contents: satırı olmayan bir referans…/references/layout.md:1: a reference of 193 lines lists its sections before the first: Contents: … Mesajın söylediği yazılır.
Elle yazılmış bir references/components.md… the generator writes this reference; it is not written by handDosya silinir: onu üretici yazar.
Anahtarının klasörü (docs/guide/<anahtar>/) dışında duran bir rehber; İngilizcesi olmayan ya da İngilizcesi Türkçesinden ayrılmış, uygulamalara dönük bir rehber: ötekinde olmayan bir başlık, bir tablo satırı, bir kod bloğu, bir liste maddesi ya da bir görsel; öteki dile bağlanmayan bir üçüncü satır; hiçbir dosyaya ya da başlığa gitmeyen, ya da İngilizceden İngilizcesi olan bir rehberin Türkçesine giden bir bağlantıdocs/guide/date-time/DATE_TIME_GUIDE.en.md:120: a bullet, where the Turkish has a numbered item, docs/guide/date-time/DATE_TIME_GUIDE.md:118İngilizce Türkçenin durduğu gibi yazılır; bir parça ikisine birden eklenir ya da ikisinden birden çıkarılır. Türkçe kalan, deponun kendi derlenişine bakan bir rehber AiDocsPlugin'deki REPOSITORY_GUIDES arasında anılır.
Sunucunun jar'ının paketlediği ve ai/mcp/licenses/THIRD-PARTY.md bildiriminin listelemediği bir modül, bildirimin listelediği ve jar'ın paketlemediği bir modül, ya da bildirimin andığı ve jar'da olmayan bir lisans metniai/mcp/licenses/THIRD-PARTY.md: io.ktor:ktor-sse-jvm is bundled into the jar, and no list names it: …Bildirimde kütüphanenin bölümü lisansını söyler ve modülü listeler; paketlenen hiçbir jar'ın taşımadığı bir metin bildirimin yanına, META-INF/licenses/'ten sonraki yoluyla konur.

7. Biçim

pantrix-ui.json'ın her alanını şeması anlatır (ai/schema/pantrix-ui.schema.json). Bir aracın bilmesi gerekenler:

8. Doğrulamak

./gradlew :ai:mcp:test

Üreticinin kendi testleri ./gradlew :build-logic:test ile koşar: tiplerin sınıflandırması, kısa örneklerin, skill'in, rehberlerin iki dilinin ve jar'ın bildiriminin denetimi, JSON yazıcısı, okuyucu ve korumalar, birebir beklenen Markdown, llms.txt, rehberlerin belgeleri ve bileşen dizini.

Gerçek bir asistanda denemek

Skill'in ve sunucunun bir asistanda işe yaradığı, aynı görev iki klasörde verilerek görülür. Klasörlerin ikisi de Pantrix'e bağlı küçük bir uygulamanın iskeletidir (settings.gradle.kts, bağımlılığıyla composeApp/build.gradle.kts, PantrixTheme'i açan bir App.kt). Birine tarifteki gibi skill ve sunucu kurulur (4. bölüm), ötekine hiçbiri. Claude Code'un başsız kipi görevi bir kez koşar ve çağırdığı her aracı yazar:

claude -p "$(cat gorev.txt)" --mcp-config .mcp.json --strict-mcp-config \
  --setting-sources project,local --permission-mode acceptEdits --permission-prompts none \
  --allowedTools "mcp__pantrix-ui Skill" --disallowedTools "Bash WebFetch WebSearch" \
  --max-budget-usd 3 --no-session-persistence --output-format stream-json --verbose > oturum.jsonl

9. Doğrulananlar ve doğrulanmayanlar

Doğrulananlar

Doğrulanmayanlar