Markdown AST для агентів (Abstract Syntax Tree)(Абстрактне синтаксичне дерево Markdown (mdast))

1. Огляд концепції та системна проблема

У сучасній агентській інженерії Markdown став універсальним стандартом: у ньому пишуться системні промпти, файли навичок (SKILL.md), документація, технічні специфікації та інструкції пам'яті.

Проте коли агенту або фоновому скрипту потрібно програмно відредагувати розділ у 50-сторінковому гайді, використання наївних маніпуляцій із рядками (string.replace) чи регулярних виразів призводить до системного псування кодової бази:

1. Знищення цілісності кодових блоків: Спроба замінити всі подвійні зірочки або заголовки часто чіпляє синтаксис Python/Bash всередині блоків ```.
2. Втрата зв'язку з Frontmatter: Звичайний парсер легко може переплутати YAML-розділювач --- на початку файлу зі звичайним горизонтальним розділювачем у тексті.
3. Порушення ієрархії відступів у списках: Автоматичні правки ламають вкладеність списків, перетворюючи акуратну верстку на синтаксичну кашу.

Markdown AST (Абстрактне синтаксичне дерево) перетворює сирий текст на детерміновану деревоподібну структуру даних, де кожен елемент (заголовок, посилання, рядок таблиці) стає строго типізованим об'єктом.

2. Архітектурна таксономія та ментальна модель

Стандарт mdast (Markdown Abstract Syntax Tree) в екосистемі Unified.js описує документ як деревоподібний граф із чіткою типізацією вузлів:

• 1. Кореневий вузол (Root): Вершина дерева, що містить повний масив дочірніх блоків (children), метадані документа та позиційні координати у вихідному файлі.
• 2. Блокові вузли (Block Nodes): Структурні одиниці верхнього рівня:
  • heading: заголовок із глибиною depth: 1..6.
  • paragraph: текстовий абзац.
  • code: блок коду із зазначенням мови (lang: "typescript") та сирим вмістом.
  • table / tableRow / tableCell: табличні структури.
  • blockquote: цитати та GitHub-подібні алерти ([!NOTE]).
• 3. Інлайн-вузли (Inline Nodes): Елементи всередині абзаців: text (чистий текст), inlineCode, strong (жирний шрифт), emphasis (курсив), link (посилання з url та title).
• 4. Трансформатори (Visitors): Функції-обхідники дерева, що використовують патерн Visitor (visit(tree, 'heading', (node) => { ... })) для мутації або фільтрації цільових вузлів без ризику зачепити сусідні секції.

3. Технічний пайплайн та внутрішня механіка

Конвеєр програмної обробки документа через AST складається з 4 етапів:

1. Tokenization & Parsing (remark-parse): Лексер розбирає сирий Markdown-рядок на токени і будує збалансоване дерево синтаксису JSON, де кожен вузол має точні координати у вихідному тексті (position: { start, end }).
2. AST Transformation (unified pipeline): Програмні плагіни або агентський скрипт обходять дерево:
   • Витягують таблицю змісту (TOC).
   • Автоматично знаходять і валідують усі внутрішні посилання [slug](file://...).
   • Модифікують лише текстові вузли всередині специфічного підрозділу, ігноруючи блоки коду.
3. Schema Sanitization & Rehype Bridge (За потреби): Якщо документ призначений для рендерингу у веб-інтерфейсі (React), дерево транслюється у hast (HTML AST) з перевіркою безпеки через rehype-sanitize.
4. Stringification (remark-stringify): Дерево детерміновано серіалізується назад у чистий, стандартизований Markdown-файл без втрати форматування та артефактів.

4. Практичні інженерні сценарії в продакшені

01. Безпечна автоматизована локалізація (i18n) технічної документації

Агент перекладає статтю з англійської на українську. Замість відправки всього файлу в LLM (де модель часто псує синтаксис коду та ламає службові теги), скрипт розбирає документ у AST, відправляє на переклад виключно вузли типу text усередині paragraph, після чого збирає файл назад. Блоки коду, системні шляхи та змінні залишаються 100% недоторканими.

02. Автоматична перелінковка та генерація графа бази знань

Скрипт будує дерево AST для всіх 100 статей глосарію, знаходить у тексті згадки ключових термінів платформи і детерміновано перетворює їх на клікабельні Markdown-посилання, гарантуючи, що заміна не відбудеться всередині заголовків чи кодових вставок.

03. Структурний ієрархічний чанкінг для RAG

Парсер ділить 100-сторінковий мануал строго по вузлах heading глибини 2. Якщо розділ містить підрозділи H3, вони зберігаються разом як єдиний контекстний чанк із зазначенням батьківського шляху в метаданих.

5. Підводні камені, типові помилки та безпека

• Розбіжності форматування при серіалізації (Formatting Drift): Різні конфігурації remark-stringify можуть замінити маркери списків з - на * або змінити відступи табуляції з 2 пробілів на 4, створюючи масивний «брудний» Git Diff. Завжди фіксуйте суворі налаштування форматування при збереженні.
• Втрата розширеного синтаксису (MDX/Custom Directives): Якщо у вашому Markdown використовуються спеціальні компоненти React або нестандартні директиви (:::tabs), стандартний парсер може інтерпретувати їх як простий текст або зламати дерево. Використовуйте розширення micromark-extension-directive.
• Споживання пам'яті на гігантських файлах: Побудова AST для монолітних файлів на десятки мегабайтів може призвести до значного сплеску споживання RAM у Node.js процесі.