docx-cli: ویرایش فایل‌های ورد توسط عامل‌های هوش مصنوعی با دقت ۱۰۰ درصدی

یک خطای کوچک در کدهای XML می‌تواند کل یک سند مایکروسافت ورد را غیرقابل خواندن کند؛ نقطه‌ای که تا امروز، پاشنه آشیل عامل‌های هوش مصنوعی در ویرایش اسناد بوده است. ابزار docx-cli که در ۷ ژوئیه ۲۰۲۶ منتشر شد، با ارائه یک رابط خط فرمان (CLI) اختصاصی، این مشکل را حل کرده تا عامل‌ها بتوانند بدون دست زدن به کدهای پیچیده OOXML، تغییرات را مستقیماً روی فایل اعمال کنند.

این ابزار در واقع یک مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن جواب می‌دهد — را از بازنویسی کل فایل در قالب‌های کم‌دقت (lossy) رها می‌کند. همان‌طور که در تحلیل قبلی ما درباره‌ی اینکه چگونه Anthropic در حال تبدیل ابزارهایی مانند Claude به سیستم‌های کنترل‌پذیر از راه دور است اشاره کردیم، صنعت در حال حرکت به سمت «مهارت‌های عامل‌محور» (agentic skills) است. docx-cli به‌جای تغییرات تخریبی، با سند مانند یک پایگاه‌داده ساختاریافته برخورد می‌کند. این ابزار از یک سیستم مکان‌یاب پایدار — مانند p3:5-20 برای هدف‌گیری کاراکترهای خاص در یک پاراگراف — استفاده می‌کند تا اطمینان حاصل شود که استایل‌های سفارشی، رنگ‌های تم و اشیاء جاسازی‌شده در طول فرآیند ویرایش باقی می‌مانند.

شکاف عملکردی

طبق یک آزمون کنترل‌شده A/B که در گیت‌هاب مستند شده است، تفاوت میان استفاده از docx-cli و «مهارت‌های پیش‌فرض» سنتی (جایی که عامل‌ها فایل .docx را Unzip کرده و XML را به‌صورت دستی می‌نویسند) خیره‌کننده است. پژوهشگران ۶ تکلیف واقعی را آزمایش کردند: پر کردن قراردادهای عدم افشا (NDA) و فاکتورها، بازطراحی رزومه‌ها، خط زدن (Redlining) قراردادها، نهایی‌کردن یک قرارداد، نویسندگی یک ژورنال و استایل‌دهی کلی سند. برای هر بازو، سه بار اجرا در دو سطح مدل انجام شد: Haiku (ضعیف و ارزان) و Sonnet (قدرتمند).

• موفقیت مدل‌های سطح پایین: مدل ارزان‌قیمت Haiku با این ابزار توانست ۴.۳ از ۶ تکلیف را درست انجام دهد، در حالی که در روش سنتی این عدد تنها ۰.۷ بود. شکاف دقت در این سطح از مدل‌ها در بیشترین حد خود است که نشان‌دهنده تفاوتی حدود ۶ برابری است.
• سقف مدل‌های پیشرفته: حتی مدل قدرتمند Sonnet در روش سنتی روی ۴ از ۶ تکلیف متوقف شد و در هر بار اجرا، همواره در بخش خط زدن قرارداد و ویرایش رزومه شکست خورد. در مقابل، docx-cli به موفقیت کامل ۶ از ۶ رسید.
• قابلیت اطمینان: ۱۰۰٪ خروجی‌های docx-cli در اولین تلاش در ورد باز شدند. در مقابل، ۵ مورد از ۳۶ خروجی روش سنتی کاملاً خراب بودند و امکان باز شدن آن‌ها وجود نداشت.
• بهره‌وری: مصرف توکن (Token) — تکه‌های کوچکی از متن شبیه برش‌های کیک که مدل می‌خورد — بین ۲.۲ تا ۲.۶ برابر کاهش یافت و سرعت پردازش (wall-clock time) بین ۱.۷ تا ۲ برابر افزایش پیدا کرد. برای مدل Haiku، توکن‌ها از ۲.۴ میلیون به ۱.۶ میلیون و برای Sonnet از ۶.۱ میلیون به ۳.۶ میلیون کاهش یافت.

سازوکار فنی

این ابزار از طریق تغییر در جایای (in-place) XML عمل می‌کند. به‌جای اینکه یک فایل را بر اساس بازنمایی مدل دوباره تولید کند، گره‌های (nodes) خاصی از درخت XML را هدف قرار می‌دهد. این کار مانع از «مشکل مدل‌های تخریبی» می‌شود که در آن رنگ‌ها یا استایل‌های خاص هنگام بازنویسی حذف می‌شدند. برای ساخت قطعات OOXML، از یک کارخانه مبتنی بر JSX استفاده می‌کند؛ مثلاً تبدیل <w.rPr><w.b/><w.color w-val="800080"/>\w.rPr> به یک درخت صحیح از XmlNode.

برای عامل‌ها، این CLI یک نمای Markdown حاشیه‌نویسی‌شده ارائه می‌دهد. این حاشیه‌ها واقعیت‌های ساختاری را نمایش می‌دهند که در HTML معمولی از طریق GFM دیده نمی‌شوند و با نشانه‌های <!-- docx:TYPE ... --> ارسال می‌شوند. این اطلاعات تنها در صورتی ارسال می‌شوند که مقدار مورد نظر با پیش‌فرض سند متفاوت باشد (deviation-only).

• پاراگراف‌ها: با یادداشتی مثل <!-- docx:p pN style="Caption" align="center" space-after="6pt" --> مشخص می‌شوند. پارامترها مستقیماً به پرچم‌های ویرایشی مانند --style ،--alignment و --space-after متصل هستند. مکان‌یاب پاراگراف، توکن pN در ابتداست؛ پاراگراف‌های ساده از پسوند <!-- pN --> استفاده می‌کنند.
• بخش‌ها و صفحات: شکست‌های بخش (Section breaks) به صورت <!-- docx:section sN cols="2" type="continuous" --> رندر می‌شوند. هندسه صفحه با <!-- docx:page sN orientation="landscape" size="…in" --> نمایش داده می‌شود، مگر اینکه با پیش‌فرض US-Letter-portrait-1″ یکسان باشد. اگر بخش‌های بعدی متفاوت باشند، ویژگی varies="by-section" اضافه می‌شود.
• جداول: با شناسه‌هایی مثل <!-- docx:table t0 widths="1,2,3in" borders="double" --> شروع می‌شوند و برای سلول‌های ادغام‌شده یا رنگی، یادداشت‌های مجزا دارند: <!-- docx:cell t0:r0c0 gridSpan="2" vMerge="continue" shading="FFE699" -->.
• تصاویر: یک یادداشت شامل ویژگی‌های اندازه، شناور بودن، Wrap و تراز-بندی دارند (مثلاً <!-- docx:image img0 size="6.2x4.1in" float="yes" wrap="square" align="center" overflow="yes" -->). پرچم overflow زمانی فعال می‌شود که تصویر از عرض ستون متن بیشتر باشد.
• حاشیه‌ها: سرصفحه و پانویس‌ها به صورت <!-- docx:header text="..." --> و <!-- docx:footer text="..." --> ظاهر می‌شوند. اگر در هر بخش متفاوت باشند، در ابتدای همان بخش رندر می‌شوند. فیلدهایی مانند {page}، {pages}، {date} و {styleref:NAME} به عنوان توکن خوانده می‌شوند.
• ردگیری تغییرات: خط <!-- docx:track-changes on --> زمانی ظاهر می‌شود که تغییر وضعیت ردگیری فعال باشد. این به عامل اجازه می‌دهد بفهمد ویرایش‌های بعدی به صورت Redline ثبت می‌شوند، بدون اینکه نیاز باشد فایل settings.xml را بررسی کند.

قابلیت‌های کلیدی

بررسی و بازبینی: عامل‌ها می‌توانند با دستور docx track-changes FILE on|off وضعیت ردگیری را تغییر دهند. آن‌ها می‌توانند متنی را درج، ویرایش یا حذف کنند که ورد آن را به عنوان بازبینی بومی ثبت می‌کند. CLI یک حلقه بررسی را پشتیبانی می‌کند: عامل‌ها می‌توانند از docx track-changes list برای فهرست تغییرات (به صورت جدول متنی یا JSON) استفاده کنند و سپس IDهای خاص را با accept یا reject بپذیرند یا رد کنند. برای نهایی‌کردن بازبینی بدون تغییر شماره IDها در میان عملیات، دستور apply هر دو تصمیم را در یک فراخوان مدیریت می‌کند تا فایل هیچ‌گاه نیمه‌کاره باقی نماند. این ابزار انواع بازبینی‌ها از جمله sectPrChange ،تغییرات علامت پاراگراف و بازبینی‌های ساختاری جدول مانند rowIns/rowDel و tblGridChange را مدیریت می‌کند.

ناوبری و کامنت‌گذاری: افزودن کامنت به بازه‌های خاص با پرچم --at (مثلاً p7:0-30) یا لنگر انداختن روی عبارت‌ها با docx comments add --anchor "phrase" امکان‌پذیر است. پاسخ به کامنت‌ها با docx comments reply و حل آن‌ها نیز پشتیبانی می‌شود. ناوبری سند بر اساس دستور docx info locators انجام می‌شود:

• pN: پاراگراف N
• pN:S-E: کاراکترهای S تا E در پاراگراف N (شروع شامل و پایان غیرشامل)
• pN-pM: بازه پاراگراف‌ها
• pN:S-pM:E: بازه کاراکترها بین دو پاراگراف
• sN: شکست بخش N
• tN:rRcC:pK: پاراگراف K از سلول در ردیف R و ستون C از جدول N
• tN:rR / tN:cC: ردیف R یا ستون C از جدول N
• tN:rR1cC1-rR2cC2: ناحیه مستطیلی سلول‌ها برای ادغام
• شناسه‌های پایدار cN, imgN, linkN, fnN, enN, tcN, eqN برای کامنت‌ها، تصاویر، هایپرلینک‌ها، پاورقی‌ها، اندنوت‌ها، تغییرات ردشده و معادلات.

مدیریت محتوای غنی:

• فرمول‌ها: تبدیل دوطرفه OOXML <m:oMath> به LaTeX را انجام می‌دهد. از temml (تبدیل LaTeX به MathML) و یک تبدیل داخلی MathML به OMML بدون وابستگی‌های LGPL استفاده می‌کند. این‌ها با eqN شناسایی می‌شوند.
• تصاویر: از مسیر فایل، URIهای داده یا URLهای http(s) پشتیبانی می‌کند. شامل کتابخانه WASM heic-convert برای تبدیل HEIC/HEIF به JPEG است. همچنین استخراج و جایگزینی تصاویر با docx images extract و replace ممکن است.
• جداول: روی یک شبکه منطقی آگاه از ادغام (merge-aware) عمل می‌کند. ویرایش‌های ساختاری مانند insert-row, insert-column یا merge اجازه نمی‌دهند ادغام‌های موجود شکسته شوند. عرض‌های سفارشی با docx tables set-widths از طریق درصد، twips یا auto تنظیم می‌شوند.
• متن‌های خام: برای متونی که Markdown باعث تخریب داده می‌شود (مثل URLهای عریان، CriticMarkup یا شماره‌گذاری‌های خاص مثل "3. note")، دستور insert --text-file PATH اجازه می‌دهد کاراکترها دقیقاً همان‌طور که هستند وارد شوند. هر خط جدید یک پاراگراف جدید شروع می‌کند و هیچ‌چیز تفسیر نمی‌شود؛ این یک «کانال بدون پارسر» حیاتی برای متون دست‌نخورده است.
• هایپرلینک‌ها: افزودن و جایگزینی لینک‌ها با docx hyperlinks add و replace با استفاده از مکان‌یاب‌های بازه پشتیبانی می‌شود.
• لیست‌ها: دستور docx lists set به عامل‌ها اجازه مدیریت لیست‌های شماره‌دار را می‌دهد. پشتیبانی از شماره شروع (--start N)، تغییر فرمت گلیف (--format decimal|lower-alpha|upper-alpha|lower-roman|upper-roman) و مدیریت تداوم لیست با --restart یا --continue.

کنترل استایل و چیدمان: کاربران می‌توانند استایل‌های جهانی در styles.xml را با docx styles set تغییر دهند. مثلاً docx styles set --at Heading1 --color 1F4E79 --size 16 --bold تمام نمونه‌های آن استایل را به‌روز می‌کند. استایل‌های جدید با docx styles create ساخته می‌شوند که می‌تواند استایلی را بر اساس استایل دیگر (--based-on STYLEID) تعریف کند. ابزار همچنین فونت‌های سراسری را با به‌روزرسانی هم‌زمان docDefaults در styles.xml و طرح فونت تم در theme1.xml مدیریت می‌کند تا تغییرات توسط ورد نادیده گرفته نشوند. دستور set-default-font با پرچم --all می‌تواند استایل‌ها یا اجراهایی که فونت خودشان را تثبیت کرده‌اند، بازتنظیم کند.

ادغام با عامل‌ها

این ابزار به عنوان یک «مهارت عامل» (Agent Skill) با مدل‌های Claude Code، Codex و Pi سازگار است. این رویکرد در راستای استانداردسازی تعاملات مدل‌هاست، مشابه آنچه در پذیرش گسترده‌ی AGENTS.md برای یکپارچه‌سازی قوانین کدنویسی در ابزارهای مختلف مشاهده شده است. docx-cli از یک فایل SKILL.md برای آموزش مدل مکان‌یاب و جریان‌های کاری استفاده می‌کند و در زمان اجرا برای قراردادهای قطعی به docx <command> --help ارجاع می‌دهد.

• نصب: از طریق npx skills add kklimuk/docx-cli یا برای Claude Code از طریق /plugin marketplace add kklimuk/docx-cli. برای Pi از طریق pi install git:github.com/kklimuk/docx-cli. باینری‌های مستقل از طریق اسکریپت نصب تأیید شده با SHA-256 در دسترس هستند.
• راه‌اندازی: از scripts/bootstrap.sh استفاده می‌کند که باینری را در اولین فعال‌سازی نصب می‌کند. نصب‌کننده متغیرهای محیطی PREFIX (پیش‌فرض $HOME/.local/bin) و VERSION را می‌شناسد.
• خود-اصلاح: برای جلوگیری از «لغزش مهارت» (skill drift)، باینری منبع حقیقت باقی می‌ماند. این مکانیزم برای مقابله با مشکلاتی است که در آن مستندات قدیمی باعث بروز باگ در کدهای تولیدشده توسط عامل‌ها می‌شوند و منجر به خروجی‌های نامعتبر می‌گردد. عامل‌ها تشویق می‌شوند docx info locators و docx <command> --help را اجرا کنند تا پرچم‌ها و فرم‌های مکان‌یاب فعلی را تأیید کنند.

برای تایید بصری، دستور docx render وجود دارد. این دستور نمونه‌های واقعی مایکروسافت ورد (از طریق osascript در macOS یا PowerShell COM در ویندوز) یا LibreOffice (از طریق soffice) را برای تولید PDF اجرا می‌کند که سپس با بسته WASM @hyzyla/pdfium به PNG تبدیل می‌شود. این برای رفع مشکل Wrap شدن متن حیاتی است؛ مثلاً edit --tabs right تب‌های چپ را برای رزومه‌ها به تب‌های راست‌چین تبدیل می‌کند تا از شکستن متن‌های طولانی جلوگیری شود.

جزئیات پیاده‌سازی

سیستم بر پایه ران‌تایم Bun (نیازمند Bun >= 1.3) ساخته شده و از کتابخانه‌های تخصصی زیر بهره می‌برد:

• پارسینگ: ترکیب jszip با fast-xml-parser و fast-xml-builder برای مدیریت XML. CLI به جای بازنویسی، XML را در جایای خود تغییر می‌دهد.
• Markdown: خط لوله‌ای شامل unified, remark-parse, remark-gfm, remark-math و یک تبدیل داخلی برای جراحی‌های درون‌خطی. این سیستم از GFM، ریاضیات و CriticMarkup پشتیبانی می‌کند. برای فرمت‌بندی متون (رنگ، هایلایت و غیره)، تگ‌های HTML معنایی مانند <mark> و <span برای رندر در مرورگر صادر می‌کند.
• موتور رندر: @hyzyla/pdfium برای تبدیل PDF به تصویر و pngjs/jpeg-js برای کدگذاری. از فرمت‌های PNG و JPG پشتیبانی می‌کند.
• تضمین کیفیت: تست‌های یکپارچه‌سازی از LibreOffice Headless برای تأیید بازگشتی استفاده می‌کنند و Biome و Knip برای سلامت کدبیس به کار می‌روند. ابزار از پروفایل ECMA-376 Part 1 §17 WordprocessingML Transitional پیروی می‌کند.

تحلیل تحریریه

تغییر رویکرد از «بازنویسی مولد» به «تغییر دقیق» (precision mutation) برای پذیرش هوش مصنوعی در سازمان‌ها حیاتی است. اکثر گردش‌های کاری شرکتی به فرمت‌های سخت‌گیرانه .docx متکی هستند؛ مدلی که بتواند یک تگ پایانی XML را «توهم» بزند، در محیط‌های حقوقی یا مالی بی‌فایده است. با انتزاع پیچیدگی‌های OOXML به مجموعه‌ای از دستورات قابل‌اعتماد CLI، ابزار docx-cli عملاً «کف هوش» مورد نیاز برای اتوماسیون اسناد را پایین می‌آورد.

این بدان معناست که شرکت‌ها دیگر برای کارهای روتین اسناد به گران‌ترین مدل‌های پیشرو نیاز ندارند. شکاف ۶ برابری در دقت سطح Haiku نشان می‌دهد که ابزارسازی تخصصی تأثیر بیشتری نسبت به مقیاس‌بندی خام مدل‌ها در مدیریت فایل‌های خاص دارد. ما در حال مشاهده تولد یک لایه «میان‌افزار» (middleware) برای عامل‌ها هستیم که یکپارچگی ساختاری را صرف‌نظر از توانایی استدلال مدل تضمین می‌کند.

اگر در حال اتوماسیون قراردادهای حقوقی یا گزارش‌های شرکتی هستید، باید ارزیابی کنید که آیا عامل فعلی شما در حال جنگ با فرمت فایل است یا از ابزاری طراحی‌شده برای آن استفاده می‌کند. تکامل بعدی احتمالاً ادغام این تغییرات دقیق در جریان‌های کاری چند-عاملی خواهد بود، جایی که یک عامل پیش‌نویس را می‌نویسد و عامل دیگر یکپارچگی XML را از طریق رندرینگ «حسابرسی» می‌کند.