OmeniaClaw path

Plugin tarafından sağlanan, oc:// adresleme alt katmanına shell erişimi: adreslenebilir çalışma alanı dosyalarını (markdown, jsonc, jsonl) incelemek ve düzenlemek için türe göre yönlendirilen tek bir yol şeması. Kendi barındırmasını yapanlar, Plugin yazarları ve düzenleyici uzantıları, dosya başına ayrıştırıcıları elle yazmadan dar bir konumu okumak, bulmak veya güncellemek için bunu kullanır.

CLI, alt katmanın herkese açık fiillerini yansıtır:

• resolve somuttur ve tek eşleşmelidir.
• find, joker karakterler, birleşimler, yüklemler ve konumsal genişletme için çok eşleşmeli fiildir.
• set yalnızca somut yolları veya ekleme işaretlerini kabul eder; joker karakter kalıpları yazmadan önce reddedilir.

path, birlikte gelen isteğe bağlı oc-path Plugin'i tarafından sağlanır. İlk kullanımdan önce etkinleştirin:

OmeniaClaw plugins enable oc-path

Neden kullanılır?

OmeniaClaw durumu, insanlar tarafından düzenlenen markdown, yorumlu JSONC yapılandırması ve yalnızca sona eklenen JSONL günlüklerine yayılmıştır. Shell betikleri, kancalar ve agent'lar bu dosyalardan çoğu zaman tek bir küçük değere ihtiyaç duyar: bir frontmatter anahtarı, bir Plugin ayarı, bir günlük kaydı alanı veya adlandırılmış bir bölüm altındaki madde imi.

OmeniaClaw path, bu çağıranlara her dosya türü için tek seferlik grep, regex veya ayrıştırıcı yerine kararlı bir adres verir. Aynı oc:// yolu terminalden doğrulanabilir, çözümlenebilir, aranabilir, kuru çalıştırılabilir ve yazılabilir; bu da dar otomasyonun incelenmesini kolaylaştırır ve yeniden oynatılmasını daha güvenli hale getirir. Dosyanın geri kalan yorumlarını, satır sonlarını ve çevresindeki biçimlendirmeyi koruyarak tek bir yaprağı güncellemek istediğinizde özellikle kullanışlıdır.

İstediğiniz şeyin mantıksal bir adresi varsa, ancak fiziksel dosya biçimi değişiyorsa bunu kullanın:

• Bir kanca, değeri geri yazarken yorumları kaybetmeden yorumlu JSONC'den tek bir ayarı okumak ister.
• Bir bakım betiği, tüm günlüğü özel bir ayrıştırıcıya yüklemeden JSONL günlüğündeki eşleşen her olay alanını bulmak ister.
• Bir düzenleyici uzantısı, slug ile bir markdown bölümüne veya madde imine atlamak ve ardından çözümlendiği tam satırı işlemek ister.
• Bir agent, uygulamadan önce küçük bir çalışma alanı düzenlemesini kuru çalıştırmak ve değişen baytları incelemede görünür kılmak ister.

Sıradan tüm dosya düzenlemeleri, zengin yapılandırma geçişleri veya belleğe özel yazmalar için büyük olasılıkla OmeniaClaw path gerekmez. Bunlar owner komutunu veya Plugin'i kullanmalıdır. path, tekrar edilebilir bir terminal komutunun başka bir özel ayrıştırıcıdan daha anlaşılır olduğu küçük, adreslenebilir dosya işlemleri içindir.

Nasıl kullanılır?

İnsan tarafından düzenlenen bir yapılandırma dosyasından tek bir değer okuyun:

OmeniaClaw path resolve 'oc://config.jsonc/plugins/github/enabled'

Diske dokunmadan bir yazmayı önizleyin:

OmeniaClaw path set 'oc://config.jsonc/plugins/github/enabled' 'true' --dry-run

Yalnızca sona eklenen bir JSONL günlüğünde eşleşen kayıtları bulun:

OmeniaClaw path find 'oc://session.jsonl/[event=tool_call]/name'

Markdown'daki bir talimatı satır numarası yerine bölüm ve öğe ile adresleyin:

OmeniaClaw path resolve 'oc://AGENTS.md/runtime-safety/OmeniaClaw-gateway'

Betik okumadan veya yazmadan önce CI'da ya da bir ön kontrol betiğinde bir yolu doğrulayın:

OmeniaClaw path validate 'oc://AGENTS.md/tools/$last/risk'

Bu komutlar shell betiklerine kopyalanabilir olacak şekilde tasarlanmıştır. Bir çağıranın yapılandırılmış çıktıya ihtiyacı olduğunda --json, bir kişi sonucu incelerken --human kullanın.

Nasıl çalışır?

OmeniaClaw path dört şey yapar:

1. oc:// adresini yuvalara ayrıştırır: dosya, bölüm, öğe, alan ve isteğe bağlı oturum.
2. Hedef uzantıdan (.md, .jsonc, .jsonl ve ilgili takma adlar) dosya türü adaptörünü seçer.
3. Yuvaları o dosya türünün AST'sine göre çözümler: markdown başlıkları/öğeleri, JSONC nesne anahtarları/dizi indeksleri veya JSONL satır kayıtları.
4. set için, dokunulmayan dosya parçalarının yorumlarını, satır sonlarını ve yakın biçimlendirmesini türün desteklediği yerlerde koruması için aynı adaptör üzerinden düzenlenmiş baytları üretir.

resolve ve set tek bir somut hedef gerektirir. find keşif fiilidir: joker karakterleri, birleşimleri, yüklemleri ve sıraları, yazmak üzere birini seçmeden önce inceleyebileceğiniz somut eşleşmelere genişletir.

Alt komutlar

Genel bayraklar

oc:// sözdizimi

oc://FILE/SECTION/ITEM/FIELD?session=SCOPE

Yuva kuralları: field, item gerektirir ve item, section gerektirir. Dört yuvanın tamamında:

• Tırnaklı segmentler — "a/b.c", / ve . ayırıcılarından etkilenmez. İçerik bayt düzeyinde sabittir; " ve \ tırnakların içinde izinli değildir. Dosya yuvası da tırnağa duyarlıdır: oc://"skills/email-drafter"/Tools/$last skills/email-drafter değerini tek bir dosya yolu olarak ele alır.
• Yüklemler — [k=v], [k!=v], [k<v], [k<=v], [k>v], [k>=v]. Sayısal işlemler, iki tarafın da sonlu sayılara dönüştürülebilmesini gerektirir.
• Birleşimler — {a,b,c} alternatiflerden herhangi biriyle eşleşir.
• Joker karakterler — * (tek alt segment) ve ** (sıfır veya daha fazla, özyinelemeli). find bunları kabul eder; resolve ve set belirsiz oldukları için reddeder.
• Konumsal — $last, son indeks / son bildirilen anahtar olarak çözümlenir.
• Sıra — belge sırasına göre N'inci eşleşme için #N.
• Ekleme işaretleri — anahtarlı / indeksli ekleme için +, +key, +nnn (set ile kullanın).
• Oturum kapsamı — ?session=cron-daily vb. Yuva iç içeliğinden bağımsızdır. Oturum değerleri hamdır, yüzdeyle çözülmez; denetim karakterleri veya ayrılmış sorgu ayırıcıları (?, &, %) içeremez.

Tırnaklı, yüklem veya birleşim segmentlerinin dışındaki ayrılmış karakterler (?, &, %) reddedilir. Denetim karakterleri (U+0000-U+001F, U+007F), session sorgu değeri dahil her yerde reddedilir.

formatOcPath(parseOcPath(path)) === path, kanonik yollar için garantilidir. Kanonik olmayan sorgu parametreleri, ilk boş olmayan session= değeri dışında yok sayılır.

Dosya türüne göre adresleme

resolve, 1 tabanlı satır numarasıyla birlikte yapılandırılmış bir eşleşme döndürür: root, node, leaf veya insertion-point. Yaprak değerleri metin ve bir leafType olarak sunulur; böylece Plugin yazarları tür başına AST biçimine bağlı kalmadan önizlemeler işleyebilir.

Mutasyon sözleşmesi

set tek bir somut hedef yazar:

• Markdown frontmatter değerleri ve - key: value öğe alanları string yapraklardır. Markdown eklemeleri bölümler, frontmatter anahtarları veya bölüm öğeleri ekler ve değişen dosya için kanonik bir markdown biçimi işler.
• JSONC yaprak yazmaları string değeri mevcut yaprak türüne zorlar (string, sonlu number, true/false veya null). JSONC nesne ve dizi eklemeleri <value> değerini JSON olarak ayrıştırır ve sıradan yaprak yazmaları için jsonc-parser düzenleme yolunu kullanarak yorumları ve yakın biçimlendirmeyi korur.
• JSONL yaprak yazmaları satır içinde JSONC gibi zorlar. Tüm satır değiştirme ve sona ekleme, <value> değerini JSON olarak ayrıştırır. İşlenen JSONL, dosyanın baskın LF/CRLF satır sonu kuralını korur.

Tam baytlar önemli olduğunda kullanıcıya görünür yazmalardan önce --dry-run kullanın. Alt katman, ayrıştırma/üretme gidiş dönüşleri için bayt düzeyinde özdeş çıktıyı korur, ancak bir mutasyon, türe bağlı olarak düzenlenen bölgeyi veya dosyayı kanonikleştirebilir.

Örnekler

# Validate a path (no filesystem access)OmeniaClaw path validate 'oc://AGENTS.md/Tools/$last/risk' # Read a leafOmeniaClaw path resolve 'oc://gateway.jsonc/version' # Wildcard searchOmeniaClaw path find 'oc://session.jsonl/*/event' --file ./logs/session.jsonl # Dry-run a writeOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' --dry-run # Apply the writeOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' # Byte-fidelity round-trip (diagnostic)OmeniaClaw path emit ./AGENTS.md

Daha fazla gramer örneği:

# Quote keys containing / or .OmeniaClaw path resolve 'oc://config.jsonc/agents.defaults.models/"anthropic/claude-opus-4-7"/alias' # Predicate search over JSONC childrenOmeniaClaw path find 'oc://config.jsonc/plugins/[enabled=true]/id' # Insert into a JSONC arrayOmeniaClaw path set 'oc://config.jsonc/items/+1' '{"id":"new","enabled":true}' --dry-run # Insert a JSONC object keyOmeniaClaw path set 'oc://config.jsonc/plugins/+github' '{"enabled":true}' --dry-run # Append a JSONL eventOmeniaClaw path set 'oc://session.jsonl/+' '{"event":"checkpoint","ok":true}' --file ./logs/session.jsonl # Resolve the last JSONL value lineOmeniaClaw path resolve 'oc://session.jsonl/$last/event' --file ./logs/session.jsonl # Address markdown frontmatterOmeniaClaw path resolve 'oc://AGENTS.md/[frontmatter]/name' # Insert markdown frontmatterOmeniaClaw path set 'oc://AGENTS.md/[frontmatter]/+description' 'Agent instructions' --dry-run # Find markdown item fieldsOmeniaClaw path find 'oc://SKILL.md/Tools/*/send_email' # Validate a session-scoped pathOmeniaClaw path validate 'oc://AGENTS.md/Tools/$last/risk?session=cron-daily'

Dosya türüne göre tarifler

Aynı beş fiil türler genelinde çalışır; adresleme şeması dosya uzantısına göre yönlendirir. Aşağıdaki örnekler PR açıklamasındaki fixture'ları kullanır.

Markdown

<!-- frontmatter.md -->---name: drafterdescription: email drafting agenttier: core---## Tools- gh: GitHub CLI- curl: HTTP client- send_email: enabled

$ OmeniaClaw path resolve 'oc://x.md/[frontmatter]/tier' --file frontmatter.md --humanleaf @ L4: "core" (string) $ OmeniaClaw path resolve 'oc://x.md/tools/gh/gh' --file frontmatter.md --humanleaf @ L9: "GitHub CLI" (string) $ OmeniaClaw path find 'oc://x.md/tools/*' --file frontmatter.md --human3 matches for oc://x.md/tools/*:  oc://x.md/tools/gh           →  node @ L9 [md-item]  oc://x.md/tools/curl         →  node @ L10 [md-item]  oc://x.md/tools/send-email   →  node @ L11 [md-item]

[frontmatter] yüklemi YAML frontmatter bloğunu adresler; tools, slug üzerinden ## Tools başlığıyla eşleşir ve öğe yaprakları, kaynak alt çizgi kullansa bile slug biçimlerini korur (send_email → send-email).

JSONC

// config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": false, "role": "chat"}  }}

$ OmeniaClaw path resolve 'oc://config.jsonc/plugins/github/enabled' --file config.jsonc --humanleaf @ L4: "true" (boolean) $ OmeniaClaw path set 'oc://config.jsonc/plugins/slack/enabled' 'true' --file config.jsonc --dry-run--dry-run: would write 142 bytes to /…/config.jsonc{  "plugins": {    "github": {"enabled": true, "role": "vcs"},    "slack":  {"enabled": true, "role": "chat"}  }}

JSONC düzenlemeleri jsonc-parser üzerinden geçer, bu nedenle yorumlar ve boşluklar bir set sonrasında korunur. İşlemeden önce baytları incelemek için önce --dry-run ile çalıştırın.

JSONL

{"event":"start","userId":"u1","ts":1}{"event":"action","userId":"u1","ts":2}{"event":"end","userId":"u1","ts":3}

$ OmeniaClaw path find 'oc://session.jsonl/[event=action]/userId' --file session.jsonl --human1 match for oc://session.jsonl/[event=action]/userId:  oc://session.jsonl/L2/userId  →  leaf @ L2: "u1" (string) $ OmeniaClaw path resolve 'oc://session.jsonl/L2/ts' --file session.jsonl --humanleaf @ L2: "2" (number)

Her satır bir kayıttır. Satır numarasını bilmediğinizde koşulla ([event=action]), bildiğinizde ise kurallı LN segmentiyle adresleyin.

Alt komut referansı

resolve <oc-path>

Tek bir yaprak veya düğüm okur. Joker karakterler reddedilir; bunlar için find kullanın. Eşleşmede 0, temiz bir kaçırmada 1, ayrıştırma hatasında veya reddedilen desende 2 çıkış koduyla çıkar.

OmeniaClaw path resolve 'oc://AGENTS.md/tools/gh/risk' --humanOmeniaClaw path resolve 'oc://gateway.jsonc/server/port' --json

find <pattern>

Bir joker karakter / koşul / birleşim deseninin her eşleşmesini listeler. En az bir eşleşmede 0, sıfır eşleşmede 1 çıkış koduyla çıkar. Dosya yuvası jokerleri OC_PATH_FILE_WILDCARD_UNSUPPORTED ile reddedilir; somut bir dosya geçirin (çok dosyalı globlama sonraki bir özelliktir).

OmeniaClaw path find 'oc://AGENTS.md/tools/**/risk'OmeniaClaw path find 'oc://session.jsonl/[event=action]/userId'OmeniaClaw path find 'oc://config.jsonc/plugins/{github,slack}/enabled'

set <oc-path> <value>

Bir yaprak yazar. Dosyaya dokunmadan yazılacak baytları önizlemek için --dry-run ile birlikte kullanın. Başarılı yazmada 0, substrat reddederse (örneğin bir sentinel koruması tetiklenirse) 1, ayrıştırma hatalarında 2 çıkış koduyla çıkar.

OmeniaClaw path set 'oc://gateway.jsonc/version' '2.0' --dry-runOmeniaClaw path set 'oc://gateway.jsonc/version' '2.0'OmeniaClaw path set 'oc://AGENTS.md/Tools/+gh/risk' 'low'

+key ekleme işaretçisi, henüz yoksa adlandırılmış alt öğeyi oluşturur; +nnn ve yalın + sırasıyla dizinli ekleme ve sona ekleme için çalışır.

validate <oc-path>

Yalnızca ayrıştırma denetimi. Dosya sistemi erişimi yoktur. Değişkenleri yerine koymadan önce bir şablon yolunun iyi biçimlendirilmiş olduğunu doğrulamak istediğinizde veya hata ayıklama için yapısal ayrımı görmek istediğinizde kullanışlıdır:

$ OmeniaClaw path validate 'oc://AGENTS.md/tools/gh' --humanvalid: oc://AGENTS.md/tools/gh  file:    AGENTS.md  section: tools  item:    gh

Geçerliyse 0, geçersizse (yapılandırılmış bir code ve message ile) 1, argüman hatalarında 2 çıkış koduyla çıkar.

emit <file>

Bir dosyayı türüne özgü ayrıştırıcı ve yayıcıdan geçirerek gidiş-dönüş yapar. Sağlam bir dosyada çıktı girdiye bayt düzeyinde özdeş olmalıdır; farklılık bir ayrıştırıcı hatasına veya sentinel tetiklenmesine işaret eder. Gerçek dünya girdilerinde substrat davranışını hata ayıklamak için kullanışlıdır.

OmeniaClaw path emit ./AGENTS.mdOmeniaClaw path emit ./gateway.jsonc --json

Çıkış kodları

Çıktı modu

OmeniaClaw path TTY farkındadır: terminalde insan tarafından okunabilir çıktı, stdout borulandığında veya yönlendirildiğinde JSON üretir. --json ve --human otomatik algılamayı geçersiz kılar.

Notlar

• set, baytları substratın yayma yolu üzerinden yazar; bu yol redaksiyon sentinel korumasını otomatik olarak uygular. __OmeniaClaw_REDACTED__ içeren bir yaprak (birebir veya alt dize olarak) yazma sırasında reddedilir.
• JSONC ayrıştırma ve yaprak düzenlemeleri Plugin yerel jsonc-parser bağımlılığını kullanır; bu nedenle sıradan yaprak yazmaları, elde yazılmış bir ayrıştırıcı/yeniden oluşturma yolundan geçmek yerine yorumları ve biçimlendirmeyi korur.
• path, LKG hakkında bilgi sahibi değildir. Dosya LKG tarafından izleniyorsa bir sonraki gözlem çağrısı yükseltme / kurtarma yapılıp yapılmayacağına karar verir. LKG yükseltme/kurtarma yaşam döngüsü üzerinden atomik çoklu set için set --batch, LKG kurtarma substratıyla birlikte planlanmaktadır.

İlgili

• CLI referansı