Yapay zeka aracıları için oluşturulmuş bir .docx CLI. Biçimlendirmeyi bozmadan veya içeriği kaybetmeden yorum bırakın, kırmızı çizgiler önerin ve Word belgelerini düzenleyin; daha sonra bir insan Word'de kabul eder veya reddeder.
Claude veya Codex'e bir .docx verin ve kırmızı çizgili bir kopyasını yorumlarla birlikte geri alın; onu Word'de açın, her zamanki gibi kabul edin veya reddedin.
Claude veya Codex'e gönderin ve yorumların bulunduğu kırmızı çizgili bir kopyayı geri alın; onu Word'de açın, her zamanki gibi kabul edin veya reddedin. Aracılar, metni karakter uzaklıklarına sahip sabit konumlandırıcılarla adresler ( p3:5-20 ); insanlar diskteki normal Word biçimlendirmesini görür.
Sonuç ve Değerlendirme
karakter uzaklıkları ile ( ); insanlar diskteki normal Word biçimlendirmesini görür. Özel stiller, tema renkleri, gömülü nesneler; hepsi hayatta kalır. CLI, kayıplı bir modelden yeniden yayınlamak yerine XML'i yerinde değiştirir.
Aracıların Word belgelerini düzenlemesinin varsayılan yolu, .docx dosyasını açmak ve OOXML'i içine elle yazmaktır. Bu, doğru sonuç elde etmek için güçlü bir model gerektirir, belirteçleri yakar ve düzenli olarak Word'ün açmayacağı bir dosya üretir. docx-cli, aracıya düz komutların yanı sıra açıklamalı bir Markdown okuma görünümü verir, böylece XML hakkında hiçbir zaman akıl yürütmek zorunda kalmaz.
Bunu ölçtük - kontrollü bir A/B hazırlama: altı gerçek belge görevi (bir gizlilik anlaşması doldurmak, bir faturayı doldurmak, bir özgeçmişi yeniden biçimlendirmek, bir sözleşmeyi yeniden çizmek, bir sözleşmeyi sonuçlandırmak, bir günlük yazmak), aynı başlangıç dosyaları ve Word ile oluşturulmuş sayfalardan her sonucu derecelendiren bağımsız bir yargıç. İki model katmanının her birinde kol başına üç çalıştırma:
Haiku (zayıf, ucuz) Sonnet (güçlü) docx-cli varsayılan beceri docx-cli varsayılan beceri Çözülmüş görevler (6'dan) 4,3 (4–5) 0,7 (0–1) 6,0 (6–6) 4,0 (4–4) Doğru şekilde oluşturulmuş (6'dan) 6 3,7 6,0 4,7 Tamamen bozuk belgeler 0 ~1/run (2'ye kadar) 0 0 Giriş jetonları 2,4M 6,1M (2,6×) 1,6M 3,6M (2,2×) Duvar saati 924 s 1.882 s (2,0× daha yavaş) 1.175 s 2.029 s (1,7× daha yavaş)
Önemli Gelişmeler
Doğruluk farkı ucuz Haiku kademesinde (~6×) en geniştir ve sınır modeli bunu asla kapatmaz; varsayılan beceri sınırları 4/6'dır, sözleşme kırmızı çizgisini ve özgeçmişi her Sonnet koşusunda kaybeder.
ve bir sınır modeli bunu asla kapatmaz - varsayılan beceri sınırları 4/6'dır, sözleşmenin kırmızı çizgisini ve özgeçmişi her Sonnet koşusunda kaybedersiniz. Maliyet ve hız cezaları modelden bağımsızdır; token/zaman aralıkları hiçbir zaman çakışmayacak şekilde her iki katmanda ~2,2–2,6 kat daha fazla jeton ve ~1,7–2 kat daha yavaştır.
Teknik Analiz
— Her iki katmanda da ~2,2–2,6 kat daha fazla jeton ve ~1,7–2 kat daha yavaş; jeton/zaman aralıkları asla örtüşmez. Word, varsayılan becerinin çalışmasını güvenilir bir şekilde açamadı; 36 çıkışından 5'ini açamadı; İlk denemede 36 docx-cli'nin tümü açıldı.
Gelecekte Ne Bekleniyor?
Tam metodoloji, göreve özel değerlendirme listesi ve yan yana görüntülemeler: hazırlık yazısı.
npm — en basit yol (Bun >= 1.3 gerektirir):
bun add -g bun-docx # veya yüklemeden çalıştırın: bunx bun-docx doc.docx'u okuyun
Sistem Güvenliği
Bağımsız ikili (Bun gerekmez). Her sürüm, önceden oluşturulmuş ikili dosyalar artı bir SHA256SUMS bildirimi yayınlar ve yükleyici, yüklemeden önce ikili sistemin SHA-256'sını doğrular:
curl -fsSL https://raw.githubusercontent.com/klimuk/docx-cli/main/install.sh | ş
ÖNEK (varsayılan $HOME/.local/bin ) ve VERSİYON'u (varsayılan en son ) onurlandırır. Linux/x64, linux/arm64, darwin/x64, darwin/arm64, windows/x64 için önceden oluşturulmuştur. Önce incelemeyi mi tercih edersiniz? En son sürümden docx-
Hızlı örnek: bir Gizlilik Anlaşmasının doldurulması
Uzmanların Görüşleri
Depo, testler/fikstürler/mnda.docx adresinde bir Common Paper Mutual NDA şablonu içerir. Aşağıda, bir temsilcinin kapak sayfasını doldurmak ve redline düzenlemeleri bırakmak için oluşturacağı temel öğeler yer almaktadır; yukarıdaki videoda gösterilen akışın aynısı. Her komut fikstüre göre uçtan uca doğrulandı:
# Önce bir kopya oluşturun — geri alma yoktur (git geçmiştir; CLI yerinde üzerine yazar) cp testler/fikstürler/mnda.docx mnda-filled.docx # Aracının hangi yer tutucuların var olduğunu bilmesi için kapak sayfası tablosunu okuyun docx mnda-filled.docx okuyun --t1'den --t1'e # Sarıyla vurgulanmış parantez içindeki yer tutucuları doldurun docx mnda-filled.docx'u değiştirin " Doldur içinde: bugünün tarihi " " 6 Mayıs 2026 " docx mnda-filled.docx'i değiştirin " eyalet ve/veya ilçeyi doldurun " " California " docx mnda-filled.docx'i değiştirin " durumu doldurun " " California " docx mnda-filled.docx'u değiştirin " # Doldurulacak hiçbir şey kalmadığını doğrulayın (çıplak konum belirleyici satırlar, eşleşme başına bir tane; hiçbir şey → çıkış 0) docx find mnda-filled.docx ' \[(Fill|fill)[^]]*\] ' --regex --all # Kırmızı çizgi geçişi için izlenen değişiklikleri çevirin docx track-changes mnda-filled.docx on # Kullanım ve Koruma maddesindeki "makul bir bilme ihtiyacı" ifadesini sıkılaştırın docx mnda-filled.docx \ "'nin makul bir n'ye sahip olduğunu değiştirin " \ " bilmesi gerekiyor ve belgelenmiş bir bilme ihtiyacı var " # İnsan incelemeci için bir yorum bırakın — mevcut bir aralığı --at docx yorumlarla adresler add mnda-filled.docx --at p7:0-30 \ --text " 'Temsilcileri' adlandırılmış bir listeye daraltmalı mıyız? "
Detaylar ve Etkileri
Mnda-filled.docx dosyasını Word'de açın: izlenen değişiklikler ve yorumlar inceleme bölmesinde kabul edilmeye, reddedilmeye veya yanıtlanmaya hazır olarak görünür. Veya bunları CLI'den almak için docx track-changes kabul mnda-filled.docx --all komutunu çalıştırın.
Temsilci becerisi olarak kullanın
docx-cli, Claude Code, Codex, Pi ve açık beceri formatını okuyan diğer donanımlarda çalışan bir SKILL.md olan Ajan Becerisi olarak gönderilir. Beceri, konum belirleyici modelini ve redline / yorum / doldurma iş akışlarını öğretir, ardından çalışma zamanında docx
Nasıl Önlem Alınmalı?
Neden bir beceri? docx-cli en zayıf ve en ucuz aracılar için tasarlandı. Zayıf temsilci kıyaslamamızda - 6 gerçek belge görevi (sözleşmeyi doldurma, kırmızı çizgi, yorum yapma, yeniden biçimlendirme, sıfırdan yazma), Word oluşturmalara göre derecelendirilmiş, her biri 3 çalıştırma - Haiku docx-cli'yi kullanarak 4,3/6 görevi tamamlarken, varsayılan Claude becerisi için 0,7/6'yı kabaca 2,5 kat daha az jetonla tamamladı; Sonnet ile 6/6'ya karşı 4/6, kabaca 2 kat daha az jetonla. Ve her docx-cli çıktısı, ilk denemede Word'de temiz bir şekilde açıldı; oluşturucunun reddettiği bir dosyayı asla yayınlamaz. (Metodoloji ve donanım: .claude/skills/weak-agent-test .)
Herhangi bir aracı (skills.sh) — tek bir çapraz koşum komutu, kullandığınız aracıya yüklenir:
npx becerileri kklimuk/docx-cli'yi ekleyin
Claude Code — tek satırlık eklenti kurulumu:
/plugin market kklimuk/docx-cli ekle /plugin install docx-cli@docx-cli
Codex — pazarı ekleyin (eklentinin otomatik keşfetme becerileri):
kodeks eklentisi pazarı kklimuk/docx-cli ekle
Pi - tek komutla kurulum (package.json'daki pi bildirimi beceriyi çeker), ardından /skill:docx-cli'yi çağırın:
pi git git:github.com/klimuk/docx-cli # global; bir proje için -l ekle (ekip paylaşımlı) kurulum # manuel alternatif: pi --skill /path/to/docx-cli/skills/docx-cli
Herhangi bir koşum takımı / kılavuz - skill/docx-cli/'yi temsilcinizin skill dizinine bırakın (örn. ~/.claude/skills/ veya çapraz araç ~/.agents/skills/ ). İlk etkinleştirmede, becerinin scripts/bootstrap.sh dosyası docx ikili dosyasını yükler (ve eski olanı kendi kendine günceller).
Beceriyi güncel tutmak
İkili dosya gerçeğin kaynağıdır: docx info skill, kurulu sürüm için standart SKILL.md dosyasını yazdırır ve taahhüt edilen kopya sürüklenirse CI testi başarısız olur. Herhangi bir değişiklikten sonra şunu kullanarak yeniden oluşturun:
docx bilgi becerisi > beceriler/docx-cli/SKILL.md
docx
Aracılar: bir çağrı oluşturmadan önce docx
- kanonik yer belirleyici dilbilgisi (makine tarafından okunabilen bir form için). Üst düzey bunu açıkça söylüyor: "Ajanların yeteneklerini anlamak için harekete geçmeleri şiddetle tavsiye edilir." docx bilgi şeması — --ast'ı okuyan AST türü tanımları ( TypeScript kaynağı için --ts).
docx
Okuma ve sorgulama (stdout'a yazdırın, asla dosyayı yazmayın)
docx DOSYA'yı oku [--LOC'den] [--LOC'ye] [--kabul edildi | --temel | --current] [--comments] docx DOSYA'yı oku --ast # Markdown yerine JSON-AST (yalnızca işaretleme işaretlerini devre dışı bırakır) docx find DOSYA SORGUSU [--regex] [--ignore-case] [--all] [--nth N] [--current | --baseline] [--exact] [--json] docx DOSYA'yı bul (--highlight RENK | herhangi bir | --color HEX | --bold | --italik | --underline) [--all] [--json] # biçimlendirmeye göre bul (SORGU yok) docx wc DOSYA [KOTUCU] [--kabul edildi | --temel | --current] [--json] docx anahat DOSYA [--style-prefix S] [--json] docx stilleri DOSYA [--used] [--STYLEID'de] [--json] # stil kataloğu (gövdede değil) — ne --style İSİMLER var docx stilleri --catalog [--json] # isteğe bağlı olarak uygulayabileceğiniz yerleşik stiller (Başlık, Başlık1–9, Alıntı, …), DOSYA gerekmez docx stilleri set DOSYA --at STYLEID [--bold --color HEX --size PT --font NAME --space-before PT --indent-left IN …] # kullanılan her paragrafı/çalışmayı yeniden biçimlendir stil docx stilleri oluşturur DOSYA STYLEID [--type paragraf | karakter] [--isim " … " ] [--temelli STYLEID] [--sonraki STYLEID] [biçimlendirme] # yeni bir özel stil tanımlayın docx oluşturma DOSYA [--out DİZİN] [--engine word | libreoffice | auto] [--dpi N] [--pages 1-N] [--format png | jpg] docx yorum listesi DOSYA [--include-resolved] [--thread cN] docx dipnot listesi DOSYA docx sonnot listesi DOSYA docx başlık listesi DOSYA docx altbilgi listesi DOSYA docx resim listesi DOSYA docx köprüler listesi DOSYA docx değişiklik listesi DOSYA docx bilgi şeması [--ts] docx bilgi bulucuları [--json]
docx, Markdown gövdesinin HTML yorum ek açıklamaları olarak gösteremediği yapısal gerçekleri okur ( ). Bunlar okuma zamanı görünürlük ipuçlarıdır - aracı yapıyı GÖREBİLİR, ancak ithalatçı bunları bırakır (yapı normal düzenlemelerde hayatta kalır, read --ast kayıpsız görünümdür ve docx bölümleri / docx tabloları ... bunu yönetir). Yalnızca sapma nedeniyle yayınlanırlar (yalnızca bir değer belge varsayılanından farklı olduğunda düz bir belge temiz kalır):
Paragraf başına stil/boşluk/girinti - en yaygın açıklama - yalnızca sapma olarak yayınlanan bir notunu kullanır (yalnızca stil/belge varsayılanından farklı olan öznitelikler). Her özellik, eşleşen düzenleme / ekleme bayrağıyla ( --style , --alignment , --space-before / --space-after , --line-spacing , --indent-left / --indent-right / --first-line / --hanging ) eşlenir, böylece bir aracı bir değeri okur ve onu yeniden uygular. Paragrafın konum belirleyicisi bu notu önde gelen pN belirteci olarak kullanır, dolayısıyla açıklamalı bir paragraf aynı zamanda çıplak bir ALAMAZ (yalnızca sapmayan paragraflar çıplak konumlayıcıyı alır). Tüm özellikler read --ast dosyasındadır.
- en yaygın ek açıklama - yalnızca sapma olarak yayılan bir notu içerir (yalnızca stil/belge varsayılanından farklı olan öznitelikler). Her öznitelik eşleşen / bayrağıyla ( , , / , , / / / ) eşlenir, böylece aracı bir değeri okur ve onu yeniden uygular. Paragrafın konum belirleyicisi bu notu baş belirteci olarak kullanır, bu nedenle açıklamalı bir paragraf da çıplak hale GELMEZ (yalnızca sapmayan paragraflar çıplak konum belirleyiciyi alır). Tüm özellikler içindedir. Bölüm sonları kendi satırlarında olarak oluşturulur - hiçbir zaman çıplak değildir --- (bu tematik bir aradır ve bunu bir bölüm için yayınlamak düzeni sessizce kenar paragraflarına dönüştürmüştür). Elle yazılmış bir yazı artık açıkça tematik bir kopuş anlamına geliyor.
kendi satırlarında olduğu gibi işlenir - asla çıplak değildir (bu tematik bir kopuştur ve bunu bir bölüm için yayınlamak düzeni sessizce kenar paragraflarına dönüştürdü). Elle yazılan bir yazı artık açıkça tematik bir kopuş anlamına geliyor. Sayfa US-Letter-portrait-1″'den saptığında, sayfa geometrisi önde gelen bir notunu alır — text-width kullanılabilir sütun genişliğidir ve baştaki sN yeniden uygulanacak bölümdür. Daha sonraki bir bölümün sayfa düzeni baştaki bölümden farklı olduğunda bir change="by-section" özelliği eklenir - ve bu durumda not, sayfa 1 düz varsayılan Letter-portrait-1″ olsa bile tetiklenir (daha sonra yalnızca text-width + Varis="by-section" değerini gösterir), gösterilen geometrinin yalnızca ön bölümü tanımladığı konusunda uyarı verir; her bölümün kesin geometrisi için read --ast kullanın. Tam twip'ler read --ast konumundadır (her bölüm sonunda: pageWidth / pageHeight / pageOrientation / marj* ). Bunu, docx bölümleri --orientation/--size/--margins içeren TAM belge için ayarlayın (hayır --at → her bölüm alır, böylece çok bölümlü bir belge sondaki bölümü geride bırakmaz), docx bölümleri olan bir bölüm --at sN … veya oluşturma sırasında; track-changes altında bölüm başına bir
sayfa US-Letter-portrait-1″'den saptığında önde gelen bir not alır - kullanılabilir sütun genişliğidir ve öndeki, yeniden başvurulacak bölümdür. Daha sonraki bir bölümün sayfa düzeni öncekinden farklı olduğunda bir öznitelik eklenir ve bu durumda not tetiklenir (daha sonra yalnızca + gösterilir), gösterilen geometrinin yalnızca ön bölümü tanımladığı uyarısı yapılır; her bölümün kesin geometrisi için kullanın. Tam twip'ler mevcut (her bölüm sonunda : / / / ). Bunu BÜTÜN belge için şununla ayarlayın: (hayır → her bölüm alır, böylece çok bölümlü bir belge izleyen bölümü geride bırakmaz), bir bölüm ile veya aynı anda; parça değişiklikleri altında bölüm başına bir tane olarak kaydeder (Word'de kabul et/reddet). Kenar boşluklarını/boyutunu da değiştirme (özgeçmiş tarihleri/konumları): eski kenar boşluklarına göre kalibre edilmiş bir SOL sekme taşar ve yeni genişliğe sarılır, böylece sayfa düzeni her birini yeni kenar boşluğunda hizalanan bir SAĞ sekmeye dönüştürür ve kaç tanesinin sabitlendiğini bildirir; ikinci bir adıma gerek yoktur. Sütunlar eşit olmadığında veya kenarlıklar varsayılandan saptığında tabloların başında bir ve ayrıca birleştirilmiş/gölgeli hücrelerle ilgili hücre başına bir notu bulunur; böylece GFM'de görünmez yapı görünür olur ( Okuma --ast'ta Table.borders / TableCell.shading).
sütunlar eşit olmadığında veya kenarlıklar varsayılandan saptığında bir satır aralığı ve ayrıca birleştirilmiş/gölgeli hücreler hakkında hücre başına bir not taşır; böylece GFM'de görünmez olan yapı görünür olur (/ içinde). Görüntüler bir note: size her zaman (  tek başına "6 inç genişliğinde" demez) ve yalnızca saptıklarında kayan / saran / hizalayan / taşan bir çizgi izler (satır içi, sınır içi görüntü yalnızca boyutunu gösterir). taşma, bir görüntüyü kullanılabilir metin sütunundan daha geniş bir şekilde işaretler ( ImageRun.floating / sarma / align + EMU kapsamları read --ast içinde).
bir notun izini sürün: her zaman (tek başına "6 inç genişliğinde" demez) ve / / / yalnızca saptıklarında (satır içi, sınır içi görüntü yalnızca boyutunu gösterir). kullanılabilir metin sütunundan daha geniş bir görüntüyü işaretler ( / / + EMU'nun kapsamı ). Üstbilgiler/altbilgiler / notları olarak görünür (attr türü yalnızca ilk / çift için görünür). Belirteç olarak okunan alanlar — {page} {pages} {date} {time} {styleref:NAME} {filename} {title} {author} ( {time} salt okunur). Her bölümde aynı olan bir marjinal zirveye çıkıyor; o bölümün başındaki bölüm oluşturma işlemine göre farklılık gösteren bir ipucu (bölümün başlangıcında Apply-to="… (below)" ile oluşturulan docx:section notunun yanı sıra), böylece her ipucu, yönettiği içerikten hemen önce okunur. Metin, yorum özelliğinde bulunduğundan içe aktarıcı onu bırakır (gövdeye yeniden enjekte edilemez); tüm girişler üstbilgiler/altbilgiler ( Marginal[] ) altında read --ast konumundadır. Docx üstbilgileri / docx altbilgileriyle ayarlayın.
/ notları olarak yüzey (öznitelik yalnızca / için görünür). Belirteç olarak okunan alanlar — (salt okunur). Her bölümde aynı olan bir marjinal zirveye çıkıyor; o bölümde işlenen bir ipucu (bölümün başında da işlenen notun yanında), böylece her ipucu, yönettiği içerikten hemen önce okunur. Metin, yorum özelliğinde bulunduğundan içe aktarıcı onu bırakır (gövdeye yeniden enjekte edilemez); tam girişler / ( ) altındadır. / ile ayarlayın. Değişiklikleri izle durumu, belgenin izleme geçişi etkinleştirildiğinde bir baş satırına geçer (yalnızca sapma — kapalı hiçbir şey yaymaz), böylece bir aracı, settings.xml incelenmeden sonraki düzenlemelerin yeniden çizileceğini görür. Bunu docx track-changes FILE ile açık|kapalı olarak değiştirin; izlenen üç değişiklik okuma görünümü ( --accepted / --current / --baseline ) aşağıdaki inceleme döngüsü kapsamında ele alınmaktadır.
Mutasyon yapın (DOSYA'yı yerinde değiştirin; --dry-run , -v her yerde; -o, konumsal FILE'ı zaten çıktı olan create dışında her değiştiricide PATH)
docx DOSYA oluştur [--title T] [--author A] [--text " ... " | --text-file YOL | --PATH.md'den | --from -] [--oryantasyon O] [--size BOYUT] [--margins M] [--header " ... " ] [--footer " ... " | --page-numbers] [--force] docx DOSYA ekle (--after | --before) KONUMLANDIRICI < içerik > # KONUMLANDIRICI = pN | tN | sN | tN:rRcC:pK docx DOSYA ekle (--at-start | --at-end) < içerik > # konum belirleyici yok — belgenin başına ekle / ekle docx DOSYA düzenle --KONUM BELİRTİCİSİ'nde < içerik > # KONUM BELİRTİCİSİ = pN | pN:S-E | pN-pM | sN | eqN | tN:rRcC:pK[:S-E] docx DOSYA sil --at LOCATOR # LOCATOR = pN | pN-pM | tN | sN | tN:rRcC:pK (hücre paragrafı) docx bölümleri DOSYA [--LOCATOR'da] [--sütunlar N] [--type T] [--oryantasyon O] [--size BOYUTU] [--margins M] # LOCATOR = pN-pM | pN (bir aralığı N sütuna sar) | sN (bir bölümün sütunlarını/türünü/sayfa geometrisini düzenleyin). Çok sütunlu düzen VE sayfa düzeni BURADA yayında. SAYFA GEOMETRİSİ (kenar boşlukları/yönelimi/boyutu) HAYIR --at ile BÜTÜN belgeye (her bölüm) uygulanır; --at sN birini hedefler. Sütunlar/tür --at'e ihtiyaç duyar. docx stilleri set-defau lt-font FILE " Yazı Tipi Adı " [--size N] [--all] # belge çapında yazı tipi: stiller.xml'i ayarlar docDefaults + tema büyük/küçük; --all ayrıca kendi yazı tipini sabitleyen stilleri/çalışmaları yeniden işaretler docx değiştirin DOSYA DESENİ DEĞİŞTİRME [--at pN] [--regex] [--ignore-case] [--all] [--limit N] [--current | --baseline] [--exact] [--track] [--dry-run] # Çalıştırmanın biçimlendirmesini (kalın/yazı tipi) ve tüm sekmeleri korur — biçimlendirilmiş/sekmeli bir şablon satırını doldurmanın yeniden oluşturma gerektirmeyen yolu (örneğin, "**Kuruluş Adı**⇥Tarih"); yeniden doldurmak için --runs'u elle yapmayın. # --at pN (veya bir hücre paragrafı tT:rRcC:pN) Değiştirmeyi bir paragrafla SINIRLANDIRIR — # AYNI yer tutucusu belge boyunca tekrarlandığında (özgeçmişin her girişte "Şehir, Eyalet") tekrarlandığında ve belirli bir paragrafta # birini istiyorsanız, pN:S-E yayılma ameliyatında bul → düzenle --at yerine # birini istiyorsanız bunu kullanın. Toplu girişler de "at" alır. # Toplu - BİR okumadan birçok değişikliği uygulayın (düzenlemeler arasında yeniden okuma yok). Her JSONL satırındaki # tuşları, komutun bayraklarını yansıtır; tüm konum belirleyiciler dokümanı #okundu olarak adresler. ekleme/düzenleme ayrıca JSONL'yi stdin'den okumak için --batch - seçeneğini de kabul eder. docx düzenleme DOSYA --batch fills.jsonl # { at,
Ezberlenmesi gereken bir kural: Mevcut bir şeye hitap etmek her zaman --at'tır. yorumlar yanıtlama/çözme/silme, dipnotlar/sonnotlar düzenleme/silme, görüntüleri çıkarma/değiştirme/silme, köprüleri değiştirme/silme, tablolar *, izleme değişikliklerini kabul etme/reddetme, düzenleme ve silme tümünü LOCATOR'da al. İstisnalar, doğası gereği konumsal veya yönseldir: ekleme, KONUMLANDIRICI olmadan --after / --before kullanır (veya belge sınırları için --at-start / --at-end, konum belirleyici yoktur); --from / --to LOCATOR ile dilimleri okuyun; wc konumsal bir [LOCATOR] alır; bul / değiştir konumsal bir SORGU / KALIP alır (ve değiştirme, değişikliği bir paragrafla sınırlamak için isteğe bağlı --at pN'yi kabul eder). Images extract --to DIR bir konum belirleyici değil, bir çıktı dizinidir.
CLI etkileşimli olmayan aracılar için oluşturulmuştur. Çıkış kodu başarı sinyalidir, çıktı ise veridir:
Çıkış Anlamı Hata kodları 0 başarılı — 2 kullanım / hatalı konum belirleyici KULLANIM, INVALID_LOCATOR 3 adresli şey bulunamadı FILE_NOT_FOUND, PART_NOT_FOUND, BLOCK_NOT_FOUND, COMMENT_NOT_FOUND, IMAGE_NOT_FOUND, HYPERLINK_NOT_FOUND, TRACKED_CHANGE_NOT_FOUND, MATCH_NOT_FOUND 1 genel hata NOT_A_ZIP , TRACKED_CHANGE_CONFLICT , TABLE_STRUCTURE , IMAGE_SOURCE , RENDER_ENGINE , RENDER_FAILED , UNHANDLED
Hatalar, {code, error, hint?} JSON'u sıfırdan farklı bir çıkışla stdout'a yazdırır - tamam alanı olmadığına dikkat edin; çıkış kodu artı kodu kesin sinyaldir.
Tamam alanı tam olarak tek bir yerde görünür: --verbose başarı onayı ( {ok:true, işlem, yol, …} ). -v olmadan, bir sonraki komut için başarı çıktısı şekillendirilir:
Komut sınıfı Başarı için varsayılan stdout --verbose Mutator yeni bir tutamaç oluşturur — yorumlar ekle → cN , yorumlar yanıtla → cN , dipnotlar/son notlar ekle → fnN / enN , köprüler ekle → linkN , ekle → yeni pN çıplak konumlayıcı(lar), satır başına bir tane (çoklu blok --markdown eklemesi birkaç tane yazdırır) full {ok:true,…} ack Mutator yeni tanıtıcısı yok — düzenle, sil, değiştir , oluştur , yorumları çöz/sil , görselleri değiştir/sil , köprüleri değiştir/sil , dipnotları/sonnotları düzenle/sil , üstbilgileri/altbilgileri ayarla/temizle , tablolar * , değişiklikleri takip et kabul et/reddet ve tek satırlık onay arasında geçiş yap -
--dry-run her zaman bir önizleme nesnesi yazdırır (tamam yok) ve hiçbir şey yazmaz; -o/--output'u kazanır.
Konumlandırıcıların iki çeşidi vardır. Konumsal blok kimlikleri (pN, tN, sN), belge sırasından ve yapısal düzenlemelerden sonraki değişimden türetilir - önemsiz olmayan mutasyonlar arasında yeniden okunur. Varlık kimlikleri ( cN , imgN , linkN , fnN , enN , tcN , eqN ) bir liste fiili (veya read --ast ) tarafından ortaya çıkarılır ve --at'a ilettiğiniz şeydir:
Kimlik Keşfet pN / tN / sN tarafından kullanılır (blok kimlikleri) docx DOSYA'yı oku ( fragmanlar), docx DOSYA'yı oku --ast , docx anahat DOSYA'sı (pN s başlığı) veya docx oluşturma sayfası görüntüleri oku , düzenle , ekle , sil , wc , sonuçları bul cN (yorum) docx yorum listesi DOSYA yorumları yanıtla/çöz/sil --at fnN / enN (dip/sonnot) docx dipnot listesi DOSYA / docx sonnot listesi DOSYA dipnotları/sonnotları düzenle/sil --at hdrN / ftrN (üstbilgi/altbilgi) docx üstbilgileri listesi DOSYA / docx altbilgi listesi DOSYA (veya oku --ast ) kimliğe değil bölüm+türüne göre adreslenir: üstbilgiler/altbilgiler seti --at sN --type T imgN (görüntü) docx resim listesi DOSYA resimlerini çıkarma/değiştirme/silme -- linkN'de (köprü) docx köprü bağlantıları listesi DOSYA köprü bağlantıları değiştir/sil --at tcN (izlenen değişiklik) docx değişiklik takibi listesi DOSYA parça değişiklikleri kabul et/reddet --at eqN (denklem) docx DOSYA'yı oku --ast (lateks alanını çalıştır) düzenle --at eqN --equation
Her liste fiili, her öğenin kimliğinin tam olarak --at — jq'ye filtre uygulamak için yönlendirdiğiniz tanıtıcı olduğu çıplak bir JSON dizisi yazdırır ( docx yorum listesi doc.docx | jq '.[] | select(.author=="Jane")' ).
docx bilgi bulucuları (makine tarafından okunabilirlik için --json) kanonik referanstır. Kısaca gramer:
pN paragraf N pN:S-E karakterler S..E paragraf N içinde pN-pM tam paragraf aralığı pN:S-pM:E çapraz paragraf karakter aralığı sN bölüm sonu N tN tablo N tN:rRcC R satırındaki hücre, sütun C tN:rRcC:pK o hücrenin K paragrafı (zincirlenebilir) tN:rR / tN:cC tablo satır R / sütun C tN:rR1cC1-rR2cC2 dikdörtgen hücre bölgesi (birleştirme) cN imgN linkN fnN enN tcN eqN varlık kimlikleri (yorum / resim / köprü / dipnot / son not / izlenen değişiklik / denklem)
Ofset semantiği: karakter uzaklıkları 0 tabanlıdır, başlangıç dahil, bitiş hariçtir — p3:5-20, paragraf 3'ün 5..19 indekslerindeki 15 karakterdir. Uzaklıklar, seçilen görünümde paragrafın görünür metnini sayar (varsayılan olarak kabul edilir).
İç içe tablolar aynı sözdizimini isteğe göre derin bir şekilde zincirler - t0:r2c1:t0:r0c0:p0, belgenin ilk tablosunun (2,1) hücresinin içine yerleştirilmiş ilk tablonun (0,0) hücresinin ilk paragrafıdır.
Her komut her biçimi kabul etmez; her komutun --at / --from /positional help'i tam olarak ne gerektiğini listeler. şekiller:
Form Kabul Edilen pN , tN , sN , tN:rRcC:pK (bloklar) okuma --from/--to , ekleme --after/--before , wc , yorumlar ekleme pN , pN:S-E , pN-pM , sN , eqN , tN:rRcC:pK , tN:rRcC:pK:S-E düzenle --at (yayılma/hücre formları yalnızca bu aralığı çıkarır veya değiştirir) pN , pN-pM , tN , sN , tN:rRcC:pK sil --at pN:S-E , pN:S-pM:E , tN:rRcC:pK:S-E (yayılma alanları) yorumlar ekle --at , köprüler ekle --at (tek paragraf), find / wc sonuçları pN[:offset] (nokta) dipnotlar/son notlar --at cN / fnN / enN / imgN / linkN / tcN (varlıklar) eşleşen ismin --at'ını ekleyin (c / fn / en / img / link / tc öneki isteğe bağlıdır) tN , tN:rR , tN:cC , tN:rRcC , tN:rR1cC1-rR2cC2 tablolar fiiller
bul → yorum yapın. find, doğrudan yorumların içine bırakılan çıplak konumlayıcılar yayar add --at (aynı varsayılan görünüm, dolayısıyla ofsetler sıraya girer - koordinat çevirisi yoktur):
docx yorumlar add doc.docx --at " $( docx find doc.docx 'ölümcül kusurlu' | head -1 ) " \ --text " Burada bir kaynak alıntılansın mı? " # veya doğrudan ifadeye göre bağlantı: docx yorumlar add doc.docx --anchor " ölümcül kusurlu " --text " Burada bir kaynak alıntılansın mı? "
oku → gidiş-dönüş işaretlemeyi düzenle. read, edit --markdown'ın yeniden ayrıştırdığı bir işaretleme lehçesi yayar, bu nedenle render → LLM-rewrite → splice-back paragraflar/listeler/alıntılar için kayıpsızdır:
docx okuma doc.docx --p3'ten --p3'e # → işaretleme ( fragmanla) # … bir LLM'ye verin, revize edilmiş bloğu geri alın … docx edit doc.docx --at p3 --markdown-file revize edilmiş.md # çoklu blok kaynağı doğal olarak genişler
Kaynak şununla başladığında --markdown-file kullanın ( --markdown TEXT değil) - — Düğümün parseArgs'ı öndeki çizgi işaret değerlerini reddeder.
değişiklikleri izleme döngüsü. İzlemeyi açın, düzenlemeler yapın (otomatik olarak
docx değişiklikleri izle doc.docx docx'te doc.docx'i değiştirin " eski ifade " " yeni ifade " --all docx parça değişiklikleri listesi doc.docx # → { id:tcN, tür, yazar, metin, … } JSON dizisi docx doc.docx'i okuyun --current # → CriticMarkup {++ins++}[^tcN] / {--del--}[^tcN] docx parça değişiklikleri kabul doc.docx --at tc0 --at tc2 # veya --all
okumanın üç izlenen değişiklik görünümü vardır: default --accepted temiz metin oluşturur - çıkarmalı düzenlemeleri bırakır ve satır içi eklemeli düzenlemeleri bırakır (kabul sonrası belge); --current CriticMarkup'ı [^tcN] dipnotlarla gösterir; --baseline, kabul edilenin (değişiklik öncesi belge) tam tersini yapar. find , replacement , wc ve yorumlar aynı --accepted / --baseline / --current bayraklarını onurlandırır, böylece ofsetler komutlar arasında tutarlı kalır. Yorum aralıklarına [^cN] dipnot eklemek için okunacak --comments ekleyin.
Yerinde XML mutasyonu. Read tarafından döndürülen AST, ayrı bir model değil, ayrıştırılmış XML ağacı üzerindeki bir görünümdür. Düzenlediğinizde veya yorum eklediğinizde, CLI temeldeki XML düğümlerini doğrudan değiştirir ve yeniden serileştirir. AST'de modellenmeyen her şey (özel stiller, tema renkleri, şema uzantıları), dokunulmamış bölgeler hiçbir zaman yeniden yayınlanmadığından hayatta kalır. Dosyayı bozan bir şeyin hâlâ referans verdiği bir ilişkiyi asla silmeyin — böylece parça/ilişki budaması bir referans taramasına bağlanır; referanssız yetimler yerinde bırakılır.
Yayıcılar için JSX. OOXML parçalarını zorunlu olarak oluşturmak (
Span uyumlu yorumlar ve köprüler. yorumlar add --at p3:5-20 (ve köprüler add ) 5 ve 20 ofsetlerini içeren işlemleri bulur, bunları sınırlardan ayırır (her iki yarıda da
Değişiklikler izlendi.
Zengin içerik. Bir yoldan, veriden eklenen resimler: URI veya http(s) URL'si (sınırlı getirme; HEIC→JPEG kod dönüştürme; SVG temizlendi; herkese açık olmayan/meta veri adresleri her yeniden yönlendirme atlamasında reddedildi). Denklemler gidiş-dönüş OOXML
Markdown lehçesi. create --from , insert/edit --markdown ve not gövdelerinin tümü aynı GFM + math + CriticMarkup + satır içi-HTML biçimlendirme lehçesini ayrıştırır (remark + comment-gfm + comment-math + şirket içi satır içi cerrahi dönüşümü), mevcut OOXML yayıcıları oluşturur. okuma uyumlu bir lehçe yayar, bu nedenle okuma → düzenle → yazma döngüsü gidiş dönüşleri (paragraflar, listeler ve iç içe geçmiş blok alıntılar için kayıpsız; bir blok alıntı içindeki kod/tablolar/matematik/başlıklar içe aktarma sırasında kasıtlı olarak en üst seviyeye kaçar). read --ast tamamen kayıpsız JSON formudur.
Değişmez metin — ayrıştırıcı içermeyen kanal. Düzyazının tam olarak eklenmesini istediğinizde - inceleme notları, alıntılanan alıntılar, Markdown'ın yanlış sonuç vereceği herhangi bir şey - create --text-file PATH / insert --text-file PATH (veya stdin için -) kullanın. Her karakter kelimesi kelimesine yer alır ve her yeni satır yeni bir paragrafa başlar; hiçbir şey yorumlanmaz, dolayısıyla 3. not 3. olarak kalır (sıralı liste yeniden numarası yoktur) ve *x* , [t](u) , çıplak URL'ler ve {++x++} yazıldığı gibi tutulur. Bunun nedeni, GFM bozulmasının her zaman kaçınılmaz olmamasıdır: Çıplak URL'ler, hiçbir çıkış dizisi olmadan otomatik olarak bağlanır ve CriticMarkup, ters eğik çizgilerden bağımsız olarak {++…++} yer. Bu nedenle, gerçek yol, dokunulmamış düzyazı yazmanın tek güvenli yoludur.
Belge çapında yazı tipi. docx stilleri set-default-font FILE "Times New Roman", yazı tipini bir yazı tipinin gerçekte yaşadığı iki yere ayarlar - word/styles.xml
Stilleri düzenleyin ve oluşturun. docx stilleri set FILE --at Heading1 --color 1F4E79 --size 16 --bold word/styles.xml dosyasındaki stil tanımını yeniden yazar, böylece stili kullanan her paragraf veya çalıştırma değişikliği alır aynı anda ("tüm Başlık 1'leri yeşil yap") - düzenlemeyle aynı uzun/paragraf biçimlendirme bayrakları (paragraf stilleri için renk/yazı tipi/boyut/vurgu/altı çizili/büyük harfler + hizalama/aralık/girinti). docx stilleri DOSYA Bilgisi'ni oluşturur --color C00000 --bold, ekleyen/düzenleyen yeni bir paragraf veya karakter stili oluşturur --style Callout daha sonra uygulayabilir. Gerçekleştirilmemiş bir yerleşik öğeyi ( --at Heading3'ü hiç kullanmamış bir belgede) düzenlemek, önce onu hazırlar; kendi doğrudan formatına sahip bir paragraf onu korur (geçersiz kılma kazanır - tanım düzenlemesi asla gövdeye dokunmaz). Stil düzenlemeleri, parça değişiklikleri altında bile izlenmeyen değişikliklerdir; stil tanımı düzenlemelerini hiçbir kırmızı çizgi olmadan doğrudan style.xml dosyasına uygulayan Word ile eşleşir.
Liste numaralandırma. docx listeleri set FILE --at p12 --start 5 numaralı listenin 5'ten başlamasını sağlar; --format üst-roman (veya alt-alfa / üst-alfa / alt-roman) glifi değiştirir; --restart yeni bir listeyi o öğeye böler; --continue, listenin yeniden başlatmak yerine önceki listenin numaralandırmasını almasını sağlar. --at herhangi bir öğeyi adlandırır; değişiklik tüm listeye uygulanır. Başlangıç gidiş-dönüşleri, işaretleme sırası boyunca (gövdede 5. 6. 7. yazıyor); GFM'nin ifade edemediği glif ve herhangi bir devam bağlantısı, yalnızca sapma olarak yüzeye çıkar / ipucu (her docx: note gibi içe aktarma sırasında bırakılır - read --ast, list.start / list.format'ı kayıpsız olarak taşır). Liste numaralandırma değişikliği için herhangi bir düzeltme kaydetmeyen, izlenmeyen, eşleşen Word.
Biçimlendirmeyi kalın/italik ötesinde çalıştırın. Özellikler işaretlemesinin yerel bir sözdizimi yoktur - metin rengi, tema rengi, vurgu, gölgeleme, alt çizgi (18 stilin tamamı + renk), üst simge, küçük/tümü büyük harfler, yazı tipi ve boyut - bir işaretleme okuyucusunun gerçekte oluşturduğu HTML olarak yayınlanır, böylece çıktı GitHub, VS Code, Obsidian ve tarayıcılarda doğru görünür (Pandoc [metin]{…} yayılımları bunların tümünde gerçek parantez olarak oluşturulur). read, bulundukları yerde anlamsal etiketler yayar - gecikmiş, x, 2 - CSS ile ifade edilebilir özellikler için bir … ve CSS'nin ifade edemediği yalnızca OOXML için data-* nitelikleri (tema renkleri, alt çizgi stilleri); insert/edit --markdown bunları kayıpsız bir şekilde geri ayrıştırır ve baştaki notu belgenin baskın yazı tipini/boyutunu bir kez bildirir, böylece gövde çalıştırma başına tekrara gömülmez. Kalın/italik/üstü çizili/kod/bağlantılar yerel kalır ( ** / * / ~~ / ` / [](…) ). Satır içi cerrahi dönüşümü tüm kardeş dizileri taradığından, bir CriticMarkup işaretçisi veya aralığı diğer biçimlendirmelerin arasında yer alabilir — {++**kalın ekleme**++} doğru bir şekilde izlenir. Geçersiz bir numaralandırma değeri (örneğin sahte bir vurgu adı), sessizce kaybolmak yerine net bir hatayla başarısız oluyor. Eklenen düz içerik, çevredeki paragrafın yazı tipini/boyutunu devralır, böylece uyum sağlar.
Görsel doğrulama. docx render, harici bir çalışma zamanına ihtiyaç duyan tek komuttur: PDF oluşturmak için Microsoft Word'ü (osascript aracılığıyla macOS, PowerShell COM aracılığıyla Windows - temel gerçek oluşturucu) veya LibreOffice'i (soffice, çapraz platform) çalıştırır, ardından paketlenmiş @hyzyla/pdfium WASM paketi aracılığıyla işlem sırasında rasterleştirir - poppler/pdftoppm/ImageMagick'e gerek yoktur. PNG'leri kullanan aracılar bunu düzenlemeleri doğrulamak, öncesi-sonrası-sonrası kabul/red farklılıklarını belirlemek veya ekran görüntüleri oluşturmak için kullanır.
Çalışma zamanı: Bun ( node:util parseArgs, özel fabrika ile JSX, yerel zlib)
: Bun ( parseArgs, özel fabrika ile JSX, yerel zlib) Ayrıştırıcı : jszip + fast-xml-parser + fast-xml-builder
: + + Markdown : birleşik + açıklama-ayrıştırma + açıklama-gfm + açıklama-matematik
: + + + Math : temml (MIT) LaTeX → MathML'yi derler; şirket içi bir MathML → OMML adaptörü OOXML tarafını çift yönlü olarak yönetir
: (MIT) LaTeX → MathML'yi derler; şirket içi bir MathML → OMML bağdaştırıcısı OOXML tarafını çift yönlü olarak yönetir Oluşturma: PDF → PNG/JPG adımı için @hyzyla/pdfium (MIT sarmalayıcı + Apache-2.0 PDFium-as-WASM), artı görüntü kodlama için pngjs / jpeg-js
: (MIT sarıcı + Apache-2.0 PDFium-as-WASM) PDF → PNG/JPG adımı için artı / görüntü kodlaması için Resimler : heic-convert (wasm libheif), HEIC/HEIF girişini ekleme sırasında JPEG'e dönüştürür
: (wasm libheif) HEIC/HEIF girişini ekleme sırasında JPEG'e dönüştürür Kalite: Biome + Knip + tsc; LibreOffice gidiş-dönüş entegrasyon testleri için başsız
: Biome + Knip + tsc; LibreOffice gidiş-dönüş entegrasyon testleri için başsız Standart: ECMA-376 Bölüm 1 §17 (WordprocessingML), Geçiş profili
Geliştirme kurulumu ve mimariye genel bakış için CONTRIBUTING.md'ye bakın ve CI.
