تصور کنید ساعت ۱۱ شب است و باید سریعاً نقطه‌ی سربه‌سر قیمت‌گذاری محصولتان را حساب کنید، اما مجبورید بین یک فایل متنی و یک نرم‌افزار سنگین مثل اکسل جابه‌جا شوید. این اصطکاک کوچک اما آزاردهنده، دلیل خلق VisiMark است؛ ابزاری که فایل‌های Markdown را به اسناد محاسباتی زنده تبدیل می‌کند. جمله‌ی «من فقط به یک محاسبه ساده نیاز دارم»، توصیف‌کننده‌ی همان چالش‌های شبانه‌ی توسعه‌دهندگانی است که منجر به ساخت این ابزار شد.
طبق گزارش منتشر شده در ۲۱ سپتامبر ۲۰۲۶، این پروژه به عنوان راهکاری برای کسانی برجسته شد که به محاسبات ریاضی نیاز دارند اما نمی‌خواهند درگیر پیچیدگی‌ها و سربارهای یک نرم‌افزار کامل صفحه‌محاسبه شوند. اکثر برنامه‌نویسان با یک نقطه اصطکاک رایج روبرو هستند: آن‌ها عددی حیاتی را در ابزاری مانند LibreOffice Calc یا Excel محاسبه می‌کنند و سپس آن عدد را به‌صورت دستی در فایل README پروژه تایپ می‌کنند. این روند باعث ایجاد شکافی خطرناک می‌شود؛ به محض اینکه یکی از متغیرهای ورودی در صفحه‌محاسبه خارجی تغییر کند، مستندات پروژه به «دروغگو» تبدیل می‌شوند.
اصطکاک ابزارهای سنتی
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی اتوماسیون مستندات اشاره کردیم، همگام‌سازی دستی داده‌ها همیشه منجر به خطا می‌شود. در مورد سازنده‌ی VisiMark، این کلافگی زمانی به اوج رسید که ساعت ۱۱ شب، پس از ساعات کاری معمول، در حال ساخت یک محصول بود. او نیاز داشت مقدار GMV (ارزش ناخالص کالای فروش رفته) را پیدا کند که در آن، هزینه یک طرح ماهانه ثابت با یک طرح کمیسیونی برابر شود. به‌جای یک یادداشت ساده حاوی محاسبات ریاضی، ابزارهایی مثل Calc او را با پنجره‌های راهنمای «آیا می‌دانستید؟» و نیاز به ذخیره یک فایل .ods در کنار فایل Markdown مواجه کردند.
این گردش کار «دو فایل برای یک عدد»، منجر به انحراف داده‌ها (Drift) می‌شود. تا دومین تغییر در متغیرها، فایل اکسل و README از هم فاصله می‌گیرند و هیچ چیزی جز حافظه‌ی خسته‌ی برنامه‌نویس — که احتمالاً تا آن زمان به رختخواب رفته است — آن‌ها را هم‌راستا نمی‌کند. VisiMark با تبدیل فایل Markdown به «تنها منبع حقیقت» (Single Source of Truth) این مشکل را حل می‌کند. این ابزار اجازه می‌دهد متغیرها و فرمول‌ها مستقیماً در متن تعریف شوند و سپس توسط ابزار محاسبه و مجدداً در متن تزریق شوند.
سازوکارهای فنی اصلی
بر اساس مستندات فنی این پروژه، قابلیت‌های کلیدی آن شامل موارد زیر است:
- لنگرهای زنده (Live Anchors): مقادیر به متن گره می‌خورند؛ وقتی متغیری تغییر می‌کند، جمله‌ای که به آن ارجاع داده شده به‌طور خودکار به‌روز می‌شود. برای مثال، مقداری مانند ۲۴۳۷۵.۰۰ مستقیماً به یک بلوک محاسباتی متصل است.
- تأییدیه (Assertions): کاربران می‌توانند بررسی‌های منطقی بنویسند (مثلاً
assert breakeven <= 50000) که مانند حفاظ‌هایی برای منطق کسب‌وکار عمل می‌کنند. اگر شرط غلط باشد، ابزار با کد وضعیت ۱ (status code 1) متوقف می‌شود. - یکپارچگی با CLI: دستور
visimark checkاعداد «کهنه» (stale) را شناسایی می‌کند؛ یعنی جاهایی که متن دیگر با مقدار محاسبه‌شده مطابقت ندارد. این دستور دقیقاً گزارش می‌دهد که چه تعداد از لنگرهای متنی به مقادیر کهنه متصل شده‌اند. - پروجکشن JSON: این ابزار می‌تواند وضعیت فعلی فایل Markdown را از طریق دستور
visimark eval --jsonبه فرمت JSON صادر کند. این قابلیت به سایر عامل‌ها (Agents) — شبیه دستیاران هوشمندی که می‌توانند دستورات پیچیده را اجرا کنند — اجازه می‌دهد بدون نیاز به یک سند دوم، داده‌ها را مصرف کنند.
در یک مثال کاربردی، کاربری قیمت ثابت را از ۲,۰۰۰ به ۵,۰۰۰ افزایش داد، زیرا احساس می‌کرد سطح متوسط قیمت‌گذاری بیش از حد ارزان است. در حالی که یک صفحه‌محاسبه سنتی صرفاً یک سلول را به‌روز می‌کرد، VisiMark هشدار داد که README اکنون «کهنه» شده است (۲۴۳۷۵.۰۰ ≠ ۶۱۸۷۵.۰۰) و یکی از حفاظ‌های قیمت (Price Cap Assertion) که از پیش تعریف شده بود، شکست خورده است.
ادغام در خط لوله تولید (Build Pipeline)
این تغییر، مفهوم «دفتر کار» را به درون مخزن کد (Repository) می‌برد. با ادغام ریاضیات در مستنداتی که تحت کنترل نسخه (Version Control) هستند، تضمین می‌شود که نقاط انتهایی صورت‌حساب (Billing Endpoints) و مستندات کاربر هرگز از هم فاصله نگیرند.
هنگام ساخت یک نقطه انتهایی برای طرح‌های قیمتی، توسعه‌دهنده از یک عامل استفاده کرد تا مرحله صورت‌حساب را از روی فایل Markdown تغذیه کند. با تبدیل visimark eval --json به یکی از مراحل Build، فرآیند پیش از آنکه سیستم قیمتی را اعلام کند که سقف داخلی اجازه آن را نمی‌دهد، متوقف می‌شود.
برای یک توسعه‌دهنده انفرادی، این یعنی پایان جابه‌جایی بین ترمینال و یک رابط گرافیکی (GUI) سنگین فقط برای تأیید یک درصد ساده. این ابزار README را از یک فایل متنی ایستا به قطعه‌ای کاربردی از خط لوله تولید (Build Pipeline) تبدیل می‌کند.
این رویکرد برای هر کسی که لایه‌های قیمتی یا مشخصات فنی را مدیریت می‌کند و تغییر یک متغیر در آن موجی از تغییرات در چندین سند ایجاد می‌کند، بسیار مفید است. در واقع، این ابزار با مستندات مانند کد برخورد می‌کند که مشمول همان اعتبارسنجی‌ها و تأییدیه‌هایی است که یک مجموعه تست نرم‌افزاری (Test Suite) دارد.
VisiMark در حال حاضر به عنوان یک پروژه با مجوز MIT، همراه با افزونه VS Code و یک محیط تست وب (Playground) در دسترس است. این پروژه هیچ مدل تجاری یا تیم فروشی پشت خود ندارد.
کاربران علاقه‌مند می‌توانند مخزن گیت‌هاب این پروژه را بررسی کنند تا این لنگرهای محاسباتی را در مستندات پروژه‌های خود ادغام نمایند.
گام بعدی شما
- اگر مستندات فنی پروژه شما حاوی اعداد متغیر است، مخزن VisiMark را در گیت‌هاب بررسی کنید.
- برای جلوگیری از خطاهای انسانی در قیمت‌گذاری، از قابلیت Assertions برای تعریف سقف‌های مجاز استفاده کنید.
- خروجی JSON ابزار را به اسکریپت‌های استقرار (Deployment) خود متصل کنید تا مستندات و کد هم‌زمان به‌روز شوند.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو