Evrak MD: UYAP, PDF ve Word belgelerini yapay zekâ için Markdown'a dönüştürün
Evrak MD ile UYAP UDF, PDF, Word ve taramaları yerelde Markdown'a dönüştürün. Açık kaynak JavaScript aracını ve Codex/Claude skill kurulumunu tanıyın.
Belgeyi yapay zekâya hazırlamak neden ayrı bir iş?
Bir UYAP dosyasının, taranmış dilekçenin veya ekler içeren Word belgesinin bilgisayarda açılması, içeriğinin bir yapay zekâ aracı tarafından doğru okunacağı anlamına gelmez. Metin dosyanın içinde ayrı bir yapıda saklanabilir; bir sayfa yalnızca görüntüden oluşabilir. Kopyala-yapıştır sırasında tablolar, görseller veya sayfa sırası kaybolabilir.
Evrak MD, bu hazırlık aşaması için geliştirdiğimiz açık kaynak JavaScript aracıdır. Desteklediği dosyalardan okunabilir Markdown metni, standart PNG görselleri ve kaynağı izlemeye yardımcı JSON kayıtları üretir. Belge hakkında hüküm vermez, hukuki görüş yazmaz veya otomatik dava analizi yapmaz. Amacı, sizin ya da kullandığınız yapay zekâ aracının inceleyeceği içeriği daha erişilebilir hâle getirmektir.
İlk sürüm hangi dosyaları dönüştürüyor?
0.1.0 sürümünde komut satırı aracı ve JavaScript API'si birlikte bulunur. Aşağıdaki tabloda biçimlerin kapsamı yer alıyor. Destek, belgenin içeriği ve kullandığı özelliklerle sınırlıdır; yalnızca dosya uzantısının listede olması kusursuz bir dönüşüm sözü değildir.
| Girdi | Üretilen içerik | Kontrol edilmesi gereken sınır |
|---|---|---|
| UYAP UDF | XML metin aralıkları, paragraflar, tablolar, gömülü görseller ve tam metin havuzu | Özgün sayfa yerleşimi yeniden çizilmez; farklı UDF yapıları desteklenmeyebilir. |
| Sayfa metni, her sayfanın PNG görseli ve gerektiğinde OCR | Sütunlar, küçük yazılar ve karmaşık tablolar görselle karşılaştırılmalıdır. | |
| Word DOCX | Paragraflar, tablolar ve gömülü görseller | Üstbilgi, altbilgi, yorum, izlenen değişiklik ve çizimler eksik kalabilir. |
| PNG, JPEG, WebP ve TIFF | Normalize PNG, küçük önizleme, OCR metni ve konum verisi | El yazısı veya düşük kaliteli taramalarda doğru okuma garanti edilmez. |
| UTF-8 metin | Markdown ve kaynak bilgili metin parçaları | Farklı karakter kodlamaları ayrıca dönüştürülmelidir. |
Çıktı yalnızca tek bir Markdown dosyası değil
Ana dosya document.md adını taşır. İçinde metin, dönüşüm yöntemi, varsa OCR güven puanı, yerel görsel bağlantıları ve uyarılar bulunur. PDF sayfaları ayrı başlıklar altında gösterilir. UDF ve DOCX için kullanılan bölüm numaraları ise özgün evrakın sayfa numarası değildir; aracın mantıksal bölümüdür.
manifest.json dosyası kaynak dosyanın adını, boyutunu, SHA-256 özetini ve üretilen dosyaların kayıtlarını tutar. SHA-256, iki dosyanın aynı baytlara sahip olup olmadığını karşılaştırmaya yardımcı olur; tek başına belgenin gerçekliğini veya imzanın geçerliliğini kanıtlamaz. chunks.jsonl ise metni kaynak bilgisiyle birlikte küçük parçalara ayırır. Bu parçalar arama veya model bağlamına hazırlıkta kullanılabilir; tam belgenin yerine geçmez.
- document.md: okunabilir ana metin ve dönüşüm uyarıları.
- assets klasörü: tam çözünürlüklü PNG'ler ve uzun kenarı en fazla 1600 piksel olan önizlemeler.
- pages klasörü: PDF metin koordinatları ve OCR uygulanmış sayfaların JSON/TSV verileri.
- source-text.txt: UDF için yapısal çıktı ile karşılaştırılabilen tam metin havuzu.
- manifest.json ve chunks.jsonl: kaynağa geri dönmek ve programlı iş akışları kurmak için kayıtlar.
Görselleri yapay zekâya nasıl hazırlıyor?
Görsel girdilerde EXIF yönü uygulanır, renk uzayı sRGB'ye çevrilir ve şeffaf alanlar beyaz zeminle birleştirilir. Çıktı PNG olarak kaydedilir. Tam görselin yanında daha küçük bir önizleme oluşturulur; bu sayede görsel okuyabilen bir modele önce genel görünüm, gerektiğinde de ayrıntılı sayfa verilebilir. Bu işlem belgeyi yeniden çizmez veya okunmayan bir alanı uydurarak tamamlamaz.
OCR, görseldeki yazıyı metne dönüştürür. Araç Türkçe ve İngilizce modelleri bilgisayarda çalıştırır. OCR kutuları görüntü üzerindeki konumları taşır; PDF'nin yerleşik metin koordinatları ise farklı bir koordinat sistemindedir. Aynı sayfanın metnini ve görselini birlikte tutmak, yanlış okunan tarih veya tutarı fark etmeyi kolaylaştırır. Önizlemede küçük kalan yazıyı tam PNG'den kontrol etmek gerekir.
Kurulum ve ilk dönüşüm
Node.js 22.13 veya üzeri gereklidir. Kaynak kod ve kurulum GitHub üzerinden sunulur; bu sürümün npm kayıt deposunda yayımlandığını varsayarak benzer adlı paketleri çalıştırmayın. İlk kurulum bağımlılıkları ve OCR modellerini indirir. Dönüşüm sırasında API anahtarı, UYAP hesabı veya bir bulut OCR aboneliği istenmez.
Aşağıdaki adımları kendi bilgisayarınızda uygulayın. Örnek dosya adlarını gerçek dosya yolunuzla değiştirin; boşluk içeren yolları tırnak içine alın. Windows'ta da kendi sürücü ve klasör yolunuzu kullanın. Mevcut çıktı klasörünün üzerine yazılmaz; her denemede yeni bir sonuç klasörü seçin.
- Depoyu indirin: git clone https://github.com/e-imza/evrak-md.git
- Depo klasörüne geçin: cd evrak-md
- Kilitli bağımlılıkları kurun: npm ci
- Yardımı görüntüleyin: node bin/evrak-md.js --help
- İlk belgeyi dönüştürün: node bin/evrak-md.js belge.udf --out sonuc
- sonuc/document.md dosyasını açın; uyarıları, kaynak bilgilerini ve görselleri inceleyin.
OCR seçeneklerini ne zaman değiştirmelisiniz?
Varsayılan auto kipinde görsel dosyaları ve UDF/DOCX içindeki gömülü görseller OCR'den geçirilir. PDF'de ise boşluklar dışında 40 karakterden az yerleşik metni olan sayfalar OCR adayıdır. Bu eşik bir karar kuralıdır; sayfanın bütün görsel yazılarını bulduğu anlamına gelmez. Örneğin yalnız başlığı metin, geri kalanı tarama olan bir sayfada her sayfayı OCR'den geçiren always kipi daha uygun olabilir.
Yalnızca yerleşik metne ihtiyacınız varsa never seçeneği OCR'yi kapatır. Görsel dosyada OCR kapalıyken metin çıkarılamadığı ayrıca bildirilir. Düşük güven puanı bulunan sonuçlar kontrol gerektirir; yüksek puan da yüzde yüz doğruluk göstermez. Dosya numarası, tarih, tutar, isim ve süre gibi kritik alanları kaynak görüntüden teyit edin.
| İhtiyaç | Örnek komut |
|---|---|
| Taranmış PDF için otomatik seçim | node bin/evrak-md.js tarama.pdf --out pdf-sonuc --ocr auto |
| PDF'nin bütün sayfalarında OCR | node bin/evrak-md.js karisik.pdf --out tam-ocr --ocr always |
| OCR yapmadan Word metnini çıkarma | node bin/evrak-md.js belge.docx --out word-sonuc --ocr never |
| Birden çok dosyayı işleme | node bin/evrak-md.js belge.udf ek.pdf --out toplu --json |
Codex ve Claude Code'a skill olarak eklemek
Skill, yapay zekâ aracına bu dönüştürücüyü ne zaman ve nasıl kullanacağını anlatan talimat paketidir. Dönüştürücünün kendisiyle aynı şey değildir: Node.js, depo ve bağımlılıklar önce kurulmuş olmalıdır. Evrak MD deposundaki skills/evrak-md paketi; dönüşümü çalıştırmayı, uyarıları okumayı, görüntüleri kontrol etmeyi ve kaynak içindeki komutları güvenilmeyen belge verisi olarak ele almayı açıklar.
Depo klasöründeyken Codex için node scripts/install-skill.js codex --project /tam/proje/yolu komutunu çalıştırın. Bu komut seçtiğiniz projenin .agents/skills/evrak-md klasörünü oluşturur. Claude Code için codex sözcüğünü claude ile değiştirin; paket .claude/skills/evrak-md konumuna kurulur. Yalnızca belirli bir proje yerine kişisel kurulum istiyorsanız --project ve yol yerine --user kullanabilirsiniz.
Kurulum, dönüştürücünün bilgisayarınızdaki yolunu tool.json dosyasına kaydeder. Depoyu daha sonra taşırsanız bu yolun güncellenmesi veya skill'in yeniden kurulması gerekir. Var olan skill üzerine yazılmaz. Makineye özgü tool.json dosyasını takım arkadaşlarınız için ortak ayarmış gibi paylaşmayın; herkes kendi kurulumunu yapmalıdır.
Yeni bir oturumda Codex'te $evrak-md, Claude Code'da /evrak-md ile çağırabilirsiniz. Örneğin belgeyi yeni bir klasöre dönüştürmesini, uyarıları belirtmesini ve özetinde kaynak bölüm numaralarını kullanmasını isteyin. Bu anlatım yerel dosya ve komut erişimi olan araçlar içindir; her sohbet ekranına otomatik kurulum veya hesabınızda bir özelliğin açılması anlamına gelmez.
Yerel dönüşüm ile yapay zekâya paylaşımı ayırın
Evrak MD belgeyi dışarı yükleyen bir servis kullanmaz. Ancak çıktıyı bir bulut yapay zekâya verdiğinizde yeni bir veri paylaşımı yapmış olursunuz. Aracın yerel çalışması, Codex veya Claude'un da çevrimdışı çalıştığı anlamına gelmez. Kullanacağınız ortamın veri işleme ayarlarını ve belgeyi paylaşma yetkinizi ayrıca değerlendirin.
Görsel metaverisinin temizlenmesi belgeyi anonimleştirmez. Metnin içindeki kişi adları, dosya numaraları ve diğer bilgiler çıktıda da bulunabilir. Özgün belgeleri ve dönüştürülmüş dosyaları herkese açık GitHub issue'larına eklemeyin. Hata bildirirken gerçek evrak yerine sentetik veya uygun şekilde kişisel verilerden arındırılmış örnek kullanın.
Elektronik imza ve gerçek evrak için sınırlar
Araç UDF içinde imza dosyası bulunup bulunmadığını kaydedebilir; imzanın geçerliliğini, sertifika zincirini veya zaman damgasını doğrulamaz. Markdown çıktısı elektronik imzayı taşıyan özgün dosyanın yerine geçmez. Dönüştürülmüş içeriği çalışırken yardımcı kopya, orijinali ise ayrıca korunması gereken kaynak olarak düşünün.
Eski Word DOC, XPS, şifreli belgeler, KEP delil paketleri ve tüm UDF varyantları bu ilk sürümün kapsamında değildir. Belgelerin içerik doğruluğu, bütünlüğü veya hukuki etkisi hakkında otomatik karar verilmez. Arşiv ve sayfa boyutu sınırları bulunsa da araç herkese açık, çok kullanıcılı bir dosya yükleme sunucusu olarak tasarlanmadı. Böyle bir ürüne eklemek ayrı erişim ve kaynak izolasyonu çalışması gerektirir.
Açık kaynak olarak geliştirmeye nasıl katkı verilir?
Evrak MD MIT lisansıyla GitHub'da paylaşılır. JavaScript API'si sayesinde belge hazırlama, arama veya kurum içi inceleme iş akışlarına eklenebilir. Kod deposunda kullanım belgeleri, skill paketi, testler ve örnek belge üreticisi birlikte yer alır. Örnek üretici gerçek kişisel veri içermeyen belgeler oluşturur; çıktıları kamuya açık depoya otomatik göndermez.
Bir sorun bildirirken işletim sistemi, Node.js sürümü, kullanılan komut ve beklenen davranışı yazın. Geçen bir test, her gerçek belgeyi doğru okuyacağımız anlamına gelmediği için yeni biçim örnekleri önemlidir. Katkılarda önceliğimiz daha fazla evrakı sessizce eksiltmeden okuyabilmek, belirsizlikleri göstermek ve kullanıcının her önemli bilgiyi kaynak belgeyle karşılaştırabilmesidir.
Kaynaklar ve inceleme
İçerik inceleme tarihi: . Kaynakların kontrol tarihleri aşağıda yer alır.
Bu yazı Evrak MD 0.1.0'ın kaynak kodu ve sentetik belgelerle yapılan dönüşüm testleri temel alınarak hazırlandı. Testler tüm gerçek UYAP varyantları için uyumluluk veya OCR doğruluk garantisi değildir. Araç resmî UYAP yazılımı değildir; imza doğrulaması yapmaz.