Docs

Aracı modu çıktısı

Hata zarfları üst düzeyde her zaman terminal içerir. awaiting_review, payment_required ve unauthenticated için true olur: kişi karar verene veya dış durum değişene kadar yeniden deneme durur. İsteğe bağlı üst düzey data, hatadan önce üretilen sonucu taşır. awaiting_review aynı hata zarfını kullanır. Yerel sohbet araçları onay kartını gönderdikten sonra status: "awaiting_approval" içeren başarılı veri döndürebilir; işlem henüz çalışmamıştır. Kişi karar verene kadar turu bitir.

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, kişinin incelemesini gerektiren işlemler). 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, hata sınıfı için 1–9, awaiting_review için 10'dur.
  • 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.
  • Component yayınları inceleme gerektirir. Checklist tamamlanınca ppl component promote çağırın; awaiting_review, inceleme isteğinin beklediğini belirtir. Kişi karar verene kadar turu bitirin. --into, yayımlanmış sürümü değiştirmek için aynı sözleşmeyi izler.

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 etkin profile uyar 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. Kişinin onayını gerektiren işlemler onun kararını bekler; aracı kendi onayını bu kararın yerine koymaz. 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 onay gerekliliklerine uymaktı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

  1. İnsan yüzeyi: tablolar, etkileşimli istemler ve açık onay.
  2. Agent yüzeyi: profiller, JSON zarfları, yalın kayıtlar ve kaynağa özel --query araması.
  3. Gerekli onayı kişi verir; inceleme beklenirken tur biter.

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>},"terminal":<bool>}

Çıkış kodu başarıda 0'dır; 1–9 hata sınıfını, 10 ise awaiting_review durumunu belirtir. Bekleyen inceleme HTTP 202 ve terminal: true döndürür: tekrar denemeden veya onay bekleyerek bloklamadan kişi karar verene kadar turu bitirin. 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.

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 onay

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. Kişinin onayını gerektiren işlemler bu kararı bekler. Onay sözleşmesi 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, işlem onayları 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 işlem onaylarına uy, 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?