Belge Kaynakları

Bir projenin dokümantasyonu nadiren tek bir yerde yaşar. Bir kaynak o yerlerden biridir ve bir proje ihtiyacı kadar çok kaynak taşıyabilir — hepsi tek bir aranabilir endpoint’te birleşir.

Bir Obsidian vault’u bir Markdown klasörüdür, bu yüzden tek bir ayar çevrilerek local directory ya da upload olarak gelir. Bkz. Obsidian Vault’ları.

Mount adı

Her kaynağın bir adı vardır ve bu ad, katkıda bulunduğu her yolun önüne eklenir:

source "handbook"  contains  install.md   →  indexed as  handbook/install.md
source "api-repo"  contains  install.md   →  indexed as  api-repo/install.md

İki kaynağın çakışmadan aynı dosya adını taşıyabilmesinin, ve her arama sonucunun hangi kaynaktan geldiğini söyleyebilmesinin nedeni budur. Adın oluşturulduktan sonra değiştirilememesinin nedeni de budur — her indekslenmiş yol ve bir ajanın gördüğü her yol onu içerir. Bir kaynak hakkındaki geri kalan her şey düzenlenebilir.

Adlar, proje adlarıyla aynı kuralı izler: küçük harf, rakam, - ve _.

Bir kaynak eklemek

Bir proje üzerinde Add source, her tür için bir sekmesi olan bir diyalog açar. Ortak alanlar:

Git, Notion, Confluence ve dokümantasyon sitesi kaynaklarının, hiçbir şeyi indekslemeden kimlik bilgilerini ve erişilebilirliği kontrol eden bir Test connection düğmesi de vardır — kaydetmeden önce kullanın.

Kaynaklar nasıl senkronize edilir

Her kaynak her indeksleme çalıştırmasının başında senkronize edilir, birbiri ardına, sonra taranır:

1. git kaynakları dalın ucunu çeker; Notion kaynakları değişen sayfaları çeker; local ve upload kaynaklarının çekecek bir şeyi yoktur.
2. Her kaynağın klasörü, seçtiği dosya türleri için taranır.
3. Yollar kaynak adıyla öneklenir ve indeksleyiciye verilir.

Tek bir kaynak satırında Sync’e basmak, başlıktaki Re-index ile aynı çalıştırmayı kuyruğa alır — kaynak başına değil, proje başına bir kuyruk vardır.

Bir kaynak başarısız olduğunda

Senkronize olamayan bir kaynak kendi satırında raporlar ve diğerleri yine indekslenir. Projenin durumu bir özetle error olur:

2/3 sources synced; notion: API token is invalid

Önemlisi, içeriği hiç okunamayan bir kaynak, daha önce katkıda bulunduğu dokümanları korur. İptal edilmiş bir Notion paylaşımı ya da ulaşılamayan bir git host’u, bir kaynağı boşaltmaz, yalnızca bayatlatır. Nedeni düzeltin ve o satırda Sync’e basın.

Düzenleme ve kaldırma

Kaynağın ürettiğini değiştiren bir ayarı değiştirmek — yol, dal, alt klasör, dosya türleri, içerik türü — otomatik olarak bir indeksleme çalıştırması kuyruğa alır, bu yüzden bir kaynak asla sessizce bayat kalmaz.

Bir kaynağı silmek, dokümanlarını, chunk’larını ve somutlaştırdığı dosyaları kaldırır. Proje indekslenirken reddedilir.

Ne indekslenir

Yalnızca kaynağın seçtiği dosya türleri: varsayılan olarak .md ve .mdx, isteğe bağlı olarak .txt, .html/.htm, .csv, .docx ve .pdf. Her şey girerken Markdown’a dönüşür — dönüşüm kenarda, bir kez olur; böylece chunker, embedder ve read_document tek bir format görür. .yaml, .yml ve .json bu listede değildir: yalnızca OpenAPI / Swagger içerik türüyle okunurlar ve okunan bir spesifikasyon tek bir belge değil, operasyon başına bir belge olur.

Her zaman atlanır:

• gizli dosyalar ve gizli klasörler (.git/, .obsidian/, …)
• node_modules, dist, build, vendor, __pycache__
• kaynağın dışına işaret eden sembolik linkler
• IGNORE_GLOBS ile eşleşen her şey

Görseller ve diğer ikili dosyalar indekslenmez. OCR da yoktur, bu yüzden dönüştürülemeyen bir dosya — taranmış bir PDF, şifreli bir PDF, tamamı görsel olan bir Word dosyası, bu türlerden herhangi birinin bozuk bir kopyası, hiç metne dönüşmeyen bir sayfa ya da e-tablo — reddedilir, indekslenmez: dosyayı adıyla anan gerekçe kaynağın satırında gösterilir ve kaynağın geri kalanı normal şekilde indekslenir. Bir ret hiçbir zaman senkronizasyonu ya da projeyi başarısız kılmaz: artımlı bir çalıştırmada dosya zaten sahip olduğu belgeyi korur, ve bir rebuild onu yalnızca yeni nesle dahil etmez — hiç okunamayan bir kaynağa uygulanan kuralın aynısı.

Dönüştürme kendi worker thread’inde çalışır, pano ve MCP endpoint’ini sunan thread’de değil, bu yüzden yavaş bir dosya hiçbir zaman bir aramayı engellemez ve heap’ini tüketen bir parser yalnızca o dosyayı başarısız kılar. Boyut tavanları, tek bir dosyanın dönüşürken neye mal olabileceğini sınırlar — bir belge için MAX_CONVERTED_FILE_BYTES, akla yatkın olmayan bir sayfa sayısı iddia eden bir PDF için MAX_PDF_PAGES, bir .docx içindeki bir zip bomb’una karşı MAX_DOCX_UNPACKED_BYTES — ve CONVERSION_TIMEOUT_MS / CONVERSION_IDLE_MS, bir dosyanın ve boşta bir worker’ın ne kadar çalışmasına izin verildiğini sınırlar. Tüm varsayılanlar ve her birinin ne durdurduğu: Yapılandırma.

Uzun bir PDF, MAX_STORED_DOCUMENT_BYTES’a karşı nereye düşer (1 MB UTF-8, bunun ötesinde saklanan önek read_document’ın sunduğu şeydir ve content_truncated ayarlanır — kesme saklanan metin üzerinde olduğu ve parçalar üzerinde olmadığı için belge her durumda tamamen aranabilir kalır). 80, 200, 600 ve 1600 yoğun sayfalık üretilmiş kılavuzlar üzerinde ölçülmüştür (yaklaşık 95 karakterlik 42 satır, bir üst/alt bilgi satırı, her onuncu sayfada bir bölüm başlığı):

Tavan kabaca 250 yoğun sayfada ısırır — daha gevşek gerçek dünya kılavuzları bunu 300–400 sayfaya kadar uzatır. Çıkarma sayfa başına yaklaşık bir milisaniyeye mal olur ve içerik hash’i dosyanın değiştiğini söyledikten sonra bir kez gerçekleşir. Bunların hiçbirinden önce, girişte sınırlanan şey dosyanın kendisidir: varsayılan olarak 50 MB olan UPLOAD_MAX_FILE_BYTES.