Docs

Aracı modu çıktısı

TL;DR

  • ppl CLI'sinin iki yüzeyi vardır — bir insan yüzeyi (şık tablolar, etkileşimli istemler, açık onayla mevcut her fiil) ve bir aracı yüzeyi (makine-okunabilir JSON, yalın izdüşümler, mühürlü yıkıcı işleme-tarafı fiiller). Aynı ikili her ikisine de hizmet eder; etkin profil hangi yüzeyin yanıt verdiğini belirler.
  • Aracı modu gerçek bir yürütme yüzeyidir, bir biçimlendirme bayrağı değil. Çıktı biçimi değişir, mevcut fiiller değişir, güvenlik sözleşmesi değişir. Profilleri değiştirmek ppl mode <profile> (yapışkan) veya ppl --agent=<profile> <cmd> (tek seferlik, kuru çalıştırma değil) ile yapılır.
  • Her aracı modu komutu dört çıktı zarfı biçiminden birini döndürür — tek kayıt JSON, sayfalanmış {count, items}, mutasyon {ok:true, data:…} veya stderr üzerinde hata {ok:false, error:{…}}. Çıkış kodu başarıda 0, hatada 1'dir.
  • Liste komutları, LLM bağlam verimliliği için tasarlanmış, varsayılan olarak 20 kayıtla üst sınırlanmış kayıt başına yalın bir izdüşüm döndürür. --query=<text> ile süz (yalnızca aracı bayrağı, kaynağa-özel eşleştirici); üst sınırı --limit ile yükselt.
  • Yıkıcı işleme-tarafı fiiller aracı modunda insanlara mühürlüdür (ppl component promote, yayınlanmış sürümlerin üzerine yazma). Aracılar hazırlar ve önerir; insanlar işler. Aracıdan insana geri dönmek yeni bir ppl login gerektirir — tasarım gereği hızlı değişim yoktur.

Aracı modu aslında nedir

Aracı modu, ppl CLI'sinin üç şeyi aynı anda değiştiren adlandırılmış, kalıcı bir yürütme profilidir: çıktı biçimi makine-okunabilir JSON zarflarına dönüşür, mevcut komut yüzeyi yıkıcı işleme-tarafı fiilleri düşürür ve oturum sınırı bir aracı profilinin iş akışının ortasında sessizce insan profiline geri geçmesini engeller. İnsan komutlarının üzerine katmanlanmış bir --json biçimlendirme bayrağı değil, ayrı bir yürütme yüzeyidir.

Üç değişiklik birbirine bağlıdır çünkü platformu süren bir LLM, hepsine birlikte ihtiyaç duyar. JSON zarfları, LLM'e kazımak zorunda kalacağı insan tabloları yerine ayrıştıracak kararlı bir biçim verir. Yıkıcı fiilleri aracı profilinden kaldırmak, LLM'in onları tanıyıp kaçınmasına güvenmek yerine, LLM'in onları hiç çağıramamasını sağlar. Oturum sınırı, bir insan açıkça yeniden giriş yapana kadar bir aracı iş akışını aracı profilinin içinde tutar.

Bu seçimler, bir LLM'in kabuk komutları çalıştırırken yüzey insanlar için kurulduğunda başarısız olduğu yollara eşlenir. Geniş tablolar, LLM'in sabit bir bütçeye sahip olduğu bağlamı harcar. Etkileşimli onay istemleri, LLM'in yanıtlama yolu olmadığından engellenir. Bir onay yanlış okunduğunda yıkıcı fiiller tetiklenebilir. Uzun süren komutlar, LLM'in ardından süzmesi gereken günlük gürültüsü yayar. Aracı yüzeyi, LLM'in bunların etrafından dolanmak zorunda kalmaması için her birini platform düzeyinde ele alır.

Bunun aracı yazarlarından — aracı ister bir Claude oturumu, ister CI-tabanlı bir betik, ister başka bir LLM-tabanlı iş akışı olsun — istediği sözleşme, görev için doğru profili seçmek, zarf biçimini ayrıştırmak ve mühürlere saygı duymaktır. Platform o zaman LLM'in saramak zorunda olduğu değil, doğrudan sürebileceği bir yüzey sunar.

Zihinsel model — bir ikili, iki yüzey

   ┌──────────────────────────────────────────────────────────────┐
   │ ppl                                                          │
   │   ├── insan yüzeyi                                           │
   │   │     şık tablolar, istemler, etkileşimli akışlar          │
   │   │     yıkıcı işleme-tarafı fiiller açık onayla              │
   │   │     çağrılabilir                                          │
   │   │                                                          │
   │   └── aracı yüzeyi                                           │
   │         ppl mode <profile>  VEYA  ppl --agent=<profile>      │
   │         makine-okunabilir JSON zarfları                      │
   │         kayıt başına yalın izdüşümler                         │
   │         kaynağa-özel --query eşleştirici (yalnız aracı bayr.) │
   │         yıkıcı işleme-tarafı fiiller MÜHÜRLÜ                  │
   └──────────────────────────────────────────────────────────────┘

Açılış istemi için ppl mode general, bir LLM'e en geniş başlangıç yüzeyini verir. Görev belli olduğunda component, backend, ci-cd veya application'a geç.

Çıktı zarfı

Her aracı modu komutu dört biçimden birini yazar:

single-record stdout : <json>
paginated list stdout: {"count":<total>,"items":[...]}
mutation stdout      : {"ok":true,"data":<json>}
error stderr         : {"ok":false,
                        "error":{"error":"<msg>",
                                 "code":"<machine-code>",
                                 "detail":"...",
                                 "suggestion":"...",
                                 "fields":{...},
                                 "trace_id":"...",
                                 "status_code":<int>}}

Çıkış kodu başarıda 0, hatada 1'dir. Hata zarfı iç içe geçmiştir — dıştaki nesne her zaman {"ok":false,"error":{…}} taşır ve içteki nesne error (insan mesajı), code (makine-okunabilir tanımlayıcı) ile detail / suggestion / fields / trace_id / status_code taşır. Bu iç yuvalar her zaman bulunur: atanmamış string yuvaları "" ve fields {} olarak serileşir; bu yüzden anahtarın var olup olmamasına değil, değerin boş olup olmamasına göre dallan. Her zaman hem çıkış kodunu kontrol et HEM DE stderr'i ayrıştır; çıkış kodu tek başına hata kategorilerini ayırt etmek için yeterli değildir.

Yalın liste izdüşümleri

Her liste komutu, aracı modunda tam nesneyi değil, kayıt başına ince bir izdüşüm döndürür. Her kayıt yalnızca bir aracının bir sonucu aramak, ilişkili kaynaklara yönlenmek ve bir sonraki çağrıya zincirlenmek için gereksinim duyduğunu taşır — bir id, insan-okunabilir bir etiket, bir durum, onu diğer kaynaklara bağlayan id'ler, birkaç sayaç ve önemli zaman damgaları. Ağır alanlar — tam yapılandırmalar, belge gövdeleri, iç içe grafikler — yanıtların küçük ve ucuz ayrıştırılabilir kalması için dışarıda bırakılır.

Tam kayda ihtiyaç duyulduğunda, eşleşen get komutuyla id ile getir (ppl component get <id>, ppl backend get <id> ve benzeri).

Sayfalanmış komutlar kayıtları {"count": <total>, "items": [...]} olarak sarar; geri kalanı çıplak bir dizi döndürür. Her komutun tuttuğu kesin alan kümesi o komutun sözleşmesinin parçasıdır — --help'te Output schema: altında basılır ve yetkili referans budur. Bu sayfa biçimi açıklar, komut başına alan listelerini değil.

Sayfalama ve 20 kayıtlık üst sınır

Aracı modu listeleri varsayılan olarak 20 kayıttır ve üst sınır --query ayarlı olsa da geçerlidir. Bayrağı destekleyen komutlarda yükseltmek için --limit=N geç. Kısmi bir eşleşmenin makul olarak 20'den fazla satıra çözülebileceği her durumda --query ile --limit'i birleştir.

--query bayrağı

Her aranabilir liste komutu, aracı modunda --query=<text> kabul eder. Eşleşme yüzeyi, name/display_name üzerinde tek tip bir alt dize değil, kaynağa-özeldir:

  • ppl file list — display_name ve read_me ile eşleşir.
  • ppl node list — display_name ile eşleşir.
  • ppl component list, ppl backend list, ppl runtime list, ppl team list — name ve/veya display_name ile eşleşir, bazı kaynaklarda trigram benzerliğiyle.

Kesin eşleştirici --help'te komut başına belgelenir.

ppl component list --query=detect-objectsppl backend list   --query=demoppl runtime list   --query=prodppl file list      --query=modelppl node list      --query=gpu

CLI'ye karşı betik yazarken tekrar tekrar ortaya çıkan üç desen:

# 1. Kısmi adla bileşen aramasıCOMP_ID=$(ppl component list --query=detect-objects \          | jq -r '.items[] | select(.name=="detect_objects") | .id')# 2. Bir bileşenin en son sürümüVER_ID=$(ppl component versions $COMP_ID \         | jq -r '.[-1].id')# 3. Görünen ada göre bir RuntimeCAP_ID=$(ppl runtime list --query=staging \         | jq -r '.items[0].id')

--query yalnızca aracıya özeldir — insan modu yardımında görünmez.

Akış komutları

ppl component publish, ppl backend deploy ve diğer uzun süren komutlar, nihai JSON'u varsayılan olarak makine-okunabilir tutar. Hata ayıklama için tam akış günlüğünü --verbosity build|all ile yeniden etkinleştir.

Oturumlar ve yalnızca-insan işleme sınırı

Bir ppl login bir insan oturumu açar. Bir aracı profiline geçmek ppl mode <profile> (kalıcı) veya ppl --agent=<profile> <cmd> (çağrı başına) ile yapılır; insana dönmek hızlı bir değişim değil, yeni bir ppl login'dir. Asimetri kasıtlıdır: aracı profilleri yıkıcı işleme-tarafı fiilleri mühürler, böylece aracılar hazırlar ve önerirken insanlar işler. Hangi fiillerin mühürlü olduğu ve nedeni Yıkıcı işlemler ve Yayın anlambilimi sayfalarında ele alınır — bu sayfa onu yeniden anlatmaz.

Aracının haritası olarak belge kayıt defteri

Belge kayıt defteri, platformun neyi sunduğuna dair kanonik gerçek kaynağıdır. Varsayımlara veya eski referanslara tercih et — platform değiştiğinde değişen kayıt defteridir; geri kalan her şey gecikebilir.

ppl docs tree                  # mevcut her şeyppl docs search <substring>    # yol veya başlık alt dizeyi içerirppl docs get flows/quickstart  # bir belge getir

Platformu süren bir LLM için iyi işleyen desen: belgelerin biçimini görmek için ppl docs tree ile başla, belirli bir konu ortaya çıktığında ara, görevin ihtiyaç duyduğu kesin akışı getir, akışın açıkladığı sınırlı komutları yürüt. Kayıt defteri kasıtlı olarak ağaç biçimlidir — keşfet, ara, getir, yürüt — böylece LLM, bir kullanıcının herhangi bir yapılandırılmış referansta gezineceği gibi gezinebilir.

Bunun yeri

Aracı modu, LLM-tabanlı iş akışlarını CLI'nin birinci sınıf bir yüzeyi yapar. Çıktı zarfları, yalın izdüşümler, kaynağa-özel --query eşleştirici, yıkıcı işlem mühürleri ve oturum sınırı; her biri bir LLM'in gerçek bir iş akışını nasıl sürdüğüne uymak için vardır. Karşılığında, her yüzeyin amaçlanan çağırana göre şekillenmesi pahasına, insan yüzeyi ile aracı yüzeyi aksi takdirde özdeş olacakları yerde ayrışır.

Bunun aracı yazarlarından istediği sözleşme, etrafından değil, içinden sürmektir: platformun döndürdüğü zarfları ayrıştır, yalın izdüşümlere saygı duy (gerektiğinde tam kaydı get ile getir), eşleştiricinin kurulduğu arama adımı için --query kullan ve yıkıcı fiiller üzerindeki mühürleri kabul et, adayları insan incelemesine sun. Aracı kendi payına düşeni yaptığı sürece sözleşme geçerlidir.

İlgili

Bu sayfa yardımcı oldu mu?