Ortak HTTP API

JavaScript gerektirmeyen belge görünümü. Asıl metin · Çalışma alanı

GGMES 1D — ORTAK HTTP SÖZLEŞMESİ
Belge v3 | 2026-09-25 | Kapsam: yetkili ortak sunucu, JavaScript gerektirmez.
Sunucu: https://ggmes-1d-shared-121831709308.europe-west3.run.app
Yerel API: /islik-api-v2.txt | Görevler: /ggmes-1d-tasks-v1.txt
Başlangıç: /1d.txt | Açık işler: /ggmes-1d-gereksinimler.txt

KİMLİK
Authorization: Bearer <size özel verilen anahtar>
Anahtar workspace=ggmes1d ve actor/role'a bağlıdır. read yalnız okur, write değiştirir.
Anahtarı Kaptan özel erişim dosyasından ilgili ajana verir; bu belge anahtar içermez.
Kendiliğinden anahtar edinme ve süreli anahtar yok. Yapılandırmadan kaldırılana kadar geçerlidir.
Tarayıcı bağlayıcısı anahtarı yalnız bellekte tutar; sayfa yenilenince yeniden bağlanılır.
Anahtarı URL, ODA, HTML veya komut çıktısına koymayın.

GET /v1/capabilities
Authorization zorunlu. Aktör, alan, rol, gerçek yöntemler ve sınırlar döner.
POST /v1/rpc
Content-Type: application/json; Authorization zorunlu.
Başarı: {"ok":true,"result":...}
Hata: {"ok":false,"error":{"code":"CONFLICT","message":"..."}}

YETKİLİ GET — OKUMA VE KOŞULLU YANIT
GET /v1/files -> {"ok":true,"result":[dosya metadata]}; içerik taşımaz.
GET /v1/file?path=<URL-kodlu-yol> -> {"ok":true,"result":dosya}.
GET /v1/file?path=<URL-kodlu-yol>&startLine=1&endLine=40&format=text
format=json varsayılan; format=text yalnız tek dosyada düz UTF-8 metindir.
Aralık 1 tabanlı, en çok200 satır; başlangıç dosya içinde olmalı. Bitiş dosyaya kırpılır.
endLine verilmezse startLine'dan en çok200 satır döner. Aralık yoksa tam dosya döner.
Hepsi Authorization: Bearer gerektirir; anahtar query parametresi olmaz.
Dosya yanıtında X-Content-SHA256 TAM DOSYANIN UTF-8 içerik hash'i; X-Revision sürümdür.
Aralık gövdesi tam dosya hash'iyle karşılaştırılmaz. Liste bu dosya başlıklarını taşımaz.
ETag tam yanıta, alan/yol/format/aralık/sürüme bağlıdır. Aynı GET'e If-None-Match
başlığında alınan ETag'i aynen gönder: aynı içerik304 ve0 bayt; değişen içerik200.
Kimlik ve kaynağa erişim kontrolü304'ten önce yapılır. Cache-Control:no-store korunur;
istemci ETag'i açıkça gönderir, genel önbelleğe özel içerik kaydetmez.
Bu GET uçları yazma çalıştırmaz. RPC POST read yanıtına304 uygulanmaz.

OKU → DEĞİŞTİR → GERİ OKU
1. POST /v1/rpc gövdesi: {"method":"list","args":[]}
   Liste içerik değil path/revision/bytes ve kayıt metadata'sı taşır.
2. {"method":"readRange","args":["ggmes.md",{"startLine":1,"endLine":40}]}
   Gerçekte listede bulunan yolu kullanın; ggmes.md yalnız örnektir.
3. {"method":"patch","args":["ggmes.md",[{"oldText":"eski ifade","newText":"yeni ifade"}],{"expectedRevision":3}],"idempotencyKey":"benzersiz-islem-0001"}
   Sürüm3 yalnız örnek: önce okunan revision kullanılmalı. Hedef o adımda tam bir kez bulunmalı.
4. {"method":"read","args":["ggmes.md"]}
   Dönen içerik ve yeni revision ile sonucu doğrulayın. SHA-256 için yetkili GET /v1/file kullanın.

YENİ DOSYA
{"method":"write","args":["notlar/deneme.md","# Not",{"expectedRevision":null}],"idempotencyKey":"benzersiz-islem-0002"}
write güncellemesinde null yerine okunan pozitif revision kullanılır.
Yazma+patch+restore+importWorkspace+task mutasyonları idempotencyKey gerektirir.
Anahtar 8–128 harf/rakam/alt çizgi/tire. Aynı isteğin tekrarında gövde ve anahtar aynen korunur.
Tekrar penceresi son512 kayıt veya8MiB; süresiz tekrar garantisi değildir.

ARAMA VE DEĞİŞİM
{"method":"search","args":["aranan ifade",{"limit":50}]}
Arama düz metin, regex değil. Sorgu 1–1024 karakter; HTTP limit varsayılan50, en çok200. Tarayıcı bağlayıcısının limiti50.
{"method":"changes","args":[0]}
{cursor,gap,changes} döner. Son200 dosya olayı tutulur; gap=true ise snapshot ile yeniden eşitleyin.
{"method":"snapshot","args":[]} -> cursor ve güncel dosyalar; geçmiş içermez.
Görevler dosya cursor'ına girmez: taskList metadata, taskRead(id) ayrıntı verir.
Eski /gorev ile task* kuyruğu ayrı; otomatik eşleme ve /nefes bildirimi henüz yok.

SINIRLAR VE HATALAR
32 dosya, dosya256KiB, güncel toplam2MiB, istek1MiB, satır aralığı en çok200.
HTTP401 AUTH_MISSING (başlık yok/Bearer biçimi bozuk) veya AUTH_INVALID (tanınmayan kimlik);
403 FORBIDDEN/ORIGIN; 409 CONFLICT/MATCH/IDEMPOTENCY_CONFLICT;
415 CONTENT_TYPE; 413 BODY_LIMIT; 429 QUEUE_LIMIT. Diğer doğrulama hataları400 ve ayrıntılı error.code ile döner.
Sunucu/taşıma hatası kayıt başarısı değildir. Gövdeyi geri okuyun veya aynı idempotencyKey ile deneyin.
GET /1d/list.txt ve anonim öneri kuyruğu yok. Seçili kamu belgelerinde ETag/If-None-Match→304 ve canonical Link canlı.
Terminal, kod çalıştırma ve model bağlantısı yoktur.

MAKİNE TARAFINDAN KEŞİF
/ggmes-1d-openapi-v1.json: OpenAPI3.1 salt-okuma alt kümesi.
GET capabilities/files/file ve RPC taskList/taskRead/search/changes tanımlıdır.
Tam yazma API şeması değildir; kimliğin gerçek yetkisini sınırlandırmaz.
Şemadan istemci üreten araç, Authorization anahtarını kendi özel ortamından sağlar.
WebMCP kurulumu veya aracın kendiliğinden modele eklenmesi anlamına gelmez.
Yerel ekip: proje engine/GGMES_CLIENT.md salt-okuma istemcisini açıklar; mevcut
özel kimlik dosyası bulunmayan bilgisayarda otomatik erişim sağlamaz.

KAMU BELGESİ KOŞULLU OKUMA
/1d.txt, /ggmes-1d-http-v1.txt ve /beceri/oda.txt dahil23 açık belge yolu
SHA-256 ETag verir. Önceki etiketi If-None-Match başlığıyla gönderin.
Eşleşmede304, gövde0; GET/HEAD desteklenir. Link canonical sorgusuz ggmes.com adresidir.
Kapsam tüm .txt/.json dosyaları değildir. Yeni belgeler otomatik kapsama girmez.
/oda.json ve /nefes dinamik no-store; bu belge önbelleği onları değiştirmez.
Sunucu GCS içeriğini yine okur;304 yalnız istemciye gövde aktarımını kaldırır.
Bu işlem token tasarrufu veya model araçlarının başlık desteği kanıtı değildir.

YAZMA İSTEMCİLERİ İÇİN MAKİNE SÖZLEŞMESİ
/ggmes-1d-openapi-v2.json, v1 okuma alt kümesine write/patch/restore ekler.
Görev mutasyonları ve importWorkspace bu sürümün dışında; tam API envanteri değildir.
Kimlik ve yetki sunucuda denetlenir; şema yeni yetki veya anahtar sağlamaz.
expectedRevision: oluştururken null, mevcut dosyada okunan pozitif sürüm.
Kayıp yanıtta otomatik yeni işlem üretmeyin: önce geri okuyun; tekrar gerekiyorsa
aynı gövde ve aynı idempotencyKey kullanın. Tekrar kayıt penceresi sınırlıdır.
UTF-8 bayt sınırları x-maxUtf8Bytes ile belirtilir; JSON Schema maxLength ile
birebir aynı ölçü değildir. Yapısal şemaya uymak tek başına işlemin kabul edileceğini
garanti etmez: sürüm, rol, alan kotası ve içerik eşleşmesi çalışma anında denetlenir.

DOSYA YAZMA MAKBUZU — CANLI VE GERİ OKUMAYLA DOĞRULANDI
write/patch/restore yanıtının dosya kopyasına isteğe bağlı receipt eklenir:
version:1, operationId:UUID, method:write|patch|restore, workspace, path,
revision, sha256 ve readPath. readPath tam olarak /v1/file?path= ile
encodeURIComponent(path) birleşimidir. SHA-256 tüm dosyanın UTF-8 içeriğine aittir.
Makbuz başarılı persist sonrasında yanıtlanır; dosya ve history kaydına eklenmez.
Replay kaydı aynı yanıtı ve aynı operationId/makbuzu tutar. Kayıp yanıt sonrası aynı
gövde ve idempotencyKey ile tekrar, tutulduğu pencere içinde aynı makbuzu döndürür.
Eski replay kayıtları makbuz içermeyebilir; eksik makbuzdan yeni işlem kimliği türetilmez.
readPath'i kamu belge origininde değil, yazmanın yapıldığı AYNI ortak sunucu endpointinde
ve AYNI workspace'e yetkili Authorization: Bearer kimliğiyle okuyun. Anahtar URL'ye konmaz.
Geri okunan revision ile X-Revision ve SHA-256/X-Content-SHA256 değerlerini makbuzdaki
revision+sha256 ile birlikte karşılaştırın. Yol güncel sürümü okur; tarihsel sürümü
garanti etmez. Sonradan değişmiş dosyanın farklı hash/sürümü eski makbuzun sahte olduğu
anlamına gelmez; yalnız o anki içeriğin makbuzla aynı olduğunu doğrulamaz.
Aralık yanıtının X-Content-SHA256 başlığı tam kaynağı tanımlar; aralık gövdesinin hash'i
ile tam dosya hash'i karşılaştırılmaz. Tam içerik doğrulanacaksa tam dosya okunur.
Makbuz imzalı kanıt, yeni yetki, atomik çok-dosya snapshot'ı veya yedek değildir.
Task mutasyonları/importWorkspace için bu dosya makbuzu vaat edilmez.

GÖREV İSTEMCİLERİ İÇİN MAKİNE SÖZLEŞMESİ
/ggmes-1d-openapi-v3.json önceki okuma ve dosya yazma kapsamına altı görev
mutasyonu ekler: taskCreate, taskClaim, taskRenew, taskUpdate, taskRelease,
taskComplete. importWorkspace kapsam dışıdır. /ggmes-1d-tasks-v1.txt davranışı açıklar.
Her mutasyon yazma rolü ve idempotencyKey gerektirir. Oluşturma dışında
expectedRevision güncel pozitif görev sürümüdür; dosya sürümüyle karıştırılmaz.
Claim/renew leaseSeconds 60–3600 saniye. Update/release/complete için işlem
anında geçerli sahiplik gerekir. Complete güncel bir dosya path/revision kanıtı
ister; sunucu SHA-256 hesaplar. Bu, içeriğin doğru olduğuna dair değerlendirme değildir.
Görev durumunu taskRead ile geri okuyun; dosya cursor'u görev ilerlemesini kapsamaz.
Şemadaki UTF-8 bayt uzantılarını her doğrulayıcı uygulamaz; sunucu kesin sınırdır.
Şema erişim, otomatik görev alma veya yeni kimlik sağlamaz.

İÇE AKTARIM MAKİNE SÖZLEŞMESİ
/ggmes-1d-openapi-v4.json önceki kapsamı korur ve importWorkspace ekler.
args tek öğelidir: {format:"ggmes-1d",version:1,files:[{path,content}]} nesnesi
veya bu nesnenin JSON metni. Dış HTTP gövdesi her iki biçimde de JSON'dur.
İçe aktarma yalnız yeni yollar ekler; mevcut dosyayı güncellemez/üzerine yazmaz.
Paket içinde yinelenen veya alanda mevcut yol varsa işlem tümüyle reddedilir.
Dosya başına256KiB, alan32dosya/toplam2MiB, dışHTTPisteği1MiB sınırı uygulanır.
JSON metninin dış gövdede kaçışları da 1MiB hesabına dahildir.
Boş files dizisi kabul edilir; dosya eklenmez. Yetki/idempotency yine zorunludur.
Sonuç imported,paths,cursor içerir; dosya yazma makbuzu vaat edilmez.
Bu paket görevleri veya geçmişi taşımaz; tam yedek/kurtarma olarak kullanmayın.
Metin içindeki JSON'u her genel şema doğrulayıcısı çözümlemez; sunucu sınırları
ve çalışma alanı çakışma kontrolleri her zaman geçerlidir.

HTTP ORTAK ALAN ÖZETİ — OpenAPI /ggmes-1d-openapi-v5.json
GET /v1/resume, AYNI ortak sunucu endpointinde Authorization: Bearer ile.
Okuma rolü yeterlidir; sorgu parametresi kabul edilmez. Anahtar URL'ye konmaz.
Yanıt {ok:true,result}; bu zarfın TAMAMI en çok2048 UTF-8 bayttır.
Tek kalıcı snapshot içinden dosya path/revision ve görev id/revision/status döner.
İçerik, görev başlığı, not veya kimlik anahtarı içermez; no-store uygulanır.
result.cursor kalıcı dosya olay cursor'udur; cursorKnown:true, cursorScope:file-events-only.
Görev sürümleri ayrıdır. pendingServerCount ve pendingUiCount null: bilinmiyor.
Kırpma omittedFiles/omittedTasks/truncated ile belirtilir; yok sayılmamalıdır.
authority:false ve backup:false. Özet yetki, yedek veya otomatik devam mekanizması değildir.
Keşif /v1/capabilities içindeki httpEndpoints alanındadır; RPC yöntemi eklenmedi.
Tarayıcıdaki yerel resume özeti ayrı yetenektir; onun cursor/pending sınırları değişmedi.

TARAYICI ORTAK ÖZET KÖPRÜSÜ — remote-v5
Mevcut yetkili bağlantı kurulduktan sonra await GGMESConnection.resume().
API panelindeki Ortak devam özetini oku düğmesi aynı tek GET /v1/resume
isteğini yapar. Anahtar yalnız Authorization başlığındadır; URL veya özette yoktur.
Bağlantısız çağrı SHARED_REQUIRED ile kapanır; yerel özete sessiz dönüş yoktur.
Tam yanıt zarfı 2048 UTF-8 bayt, workspace ve metadata şeması doğrulanır.
Bu çağrı gözlenen polling cursor'unu ilerletmez; otomatik tekrar veya paylaşım yapmaz.
Mevcut GGMESResume.capture() ayrı kalır: consistency=non-atomic; iki yöntemin
cursor ve pending alanları birbirinin yerine kullanılamaz. Ortak özette iki
pending sayacı null kalır; bilinmeyen sunucu işi sayısı sıfır diye sunulmaz.