Bạn có bao giờ để ý rằng file README.md hay tài liệu dự án — thứ mà AI agent đọc hàng ngày — lại chứa đầy định dạng con người thích, AI không cần?
In đậm, in nghiêng, bảng phức tạp, ASCII graph trang trí… tất cả đều tốn token khi AI đọc. Mỗi lần agent đọc tài liệu, bạn trả tiền cho những ký tự trang trí ấy.
Agent MD ra đời để giải quyết vấn đề này: một CLI viết bằng Rust, thiết kế riêng cho AI agent làm việc với markdown — tiết kiệm token, dễ parse, output JSON.
Agent MD Là Gì?#
Agent MD (tác giả: loclv ↗) là một CLI tool giúp viết markdown thân thiện với AI. Nó không chỉ format — nó kiểm tra, dọn dẹp, và cung cấp API kiểu JSON để agent đọc/ghi markdown một cách thông minh.
Triết lý: Markdown nên tối ưu cho AI đọc, không chỉ cho người xem. Bỏ qua các decoration không cần thiết, giữ lại cấu trúc và nội dung.
Vấn Đề: Token Tax#
Mỗi khi LLM đọc file markdown, nó phải xử lý:
**bold**và__bold__— in đậm, AI không cần- Bảng phức tạp với alignment — con người thích, AI parse cũng được nhưng dư thừa
- ASCII art — vẽ bằng ký tự, AI đọc không hiểu
- Khoảng trắng thừa, dòng trống — lãng phí
Hệ quả: ~20% token bị lãng phí cho định dạng, mỗi lần đọc là một lần mất tiền vô ích.
Cài Đặt#
Yêu cầu Rust, build từ source:
git clone https://github.com/loclv/agent-md.git
cd agent-md
cargo build --release
# Binary tại target/release/agent-md
export PATH="/path/to/agent-md/target/release:$PATH"Các Lệnh Chính#
Lint — Kiểm Tra Markdown#
agent-md lint README.md
# output JSON
# {"valid":false,"errors":[
# {"line":7,"message":"No bold text allowed","rule":"no-bold"},
# {"line":34,"message":"ASCII graph detected","rule":"no-ascii-graph"}
# ]}Quy tắc lint gồm:
Lỗi (errors):
no-bold— cấm**bold**và__bold__heading-structure— không skip cấp headingno-ascii-graphs— cấm ASCII art (kể cả trong code block)space-indentation— tối đa 2 spaces indenttable-syntax— bảng phải đơn giảncode-blocks— code block phải có language speclist-formatting— list marker nhất quánno-useless-links— link không trùng URL
Cảnh báo (warnings):
no-duplicate-headings— heading trùng nội dungno-multiple-blanks— nhiều dòng trống liên tiếp
Output luôn là JSON, agent có thể parse dễ dàng.
Format — Dọn Dẹp#
agent-md fmt document.md
# Xoá bold, compact blank lines, collapse spaces, remove HR...Các option format:
| Option | Mô tả |
|---|---|
remove_bold | Xoá **bold** và __bold__ |
compact_blank_lines | Gom dòng trống |
collapse_spaces | Gom nhiều spaces |
remove_horizontal_rules | Xoá ---, *** |
remove_emphasis | Xoá *italic* |
Ví dụ input:
# My Project
## Overview
This is a really awesome project with many features:
| Feature | Description | Status |
|---|---|---|
| API | RESTful API | ✅ Complete |
| UI | Modern interface | 🚧 In Progress |Sau format:
# My Project
## Overview
This is a really awesome project with many features:
- API: RESTful API (Complete)
- UI: Modern interface (In Progress)Bảng được chuyển thành list — dễ đọc hơn cho AI, ít token hơn.
Read — Đọc Thông Minh#
# Đọc toàn bộ
agent-md read README.md --field content
# Chỉ đọc headings (không cần content)
agent-md read README.md --field headings
# Chỉ đọc một section
agent-md read README.md --content "## Development"
# Section lồng nhau
agent-md read README.md --content "## Development > Build"Đây là tính năng cực kỳ hữu ích cho AI agent: thay vì đọc cả file dài, agent chỉ cần đọc đúng section cần thiết.
Write — Ghi Có Kiểm Tra#
# Ghi file, tự động validate trước
agent-md write README.md "# Title\nContent"
# Ghi vào section cụ thể
agent-md write-section README.md \
--section "## Development" \
--content "New content"
# Append vào cuối file
agent-md append README.md "# New Section\nContent"
# Chèn tại dòng cụ thể
agent-md insert README.md 10 "# Inserted line"Tất cả lệnh ghi đều tự động chạy lint trước — đảm bảo content luôn AI-friendly.
Search — Tìm Kiếm#
agent-md search README.md "TODO"
# {"query":"TODO","matches":[{"line":15,"content":"## TODO"}],"total":1}Headings — Cấu Trúc#
agent-md headings README.md
# [{"level":1,"text":"My Project","line":1},
# {"level":2,"text":"Overview","line":3}]Stats — Thống Kê#
agent-md stats README.md
# {"word_count":120,"line_count":30,"heading_count":5}Convert — JSONL#
agent-md to-jsonl README.md
# {"type":"heading","content":"My Project","level":1}
# {"type":"paragraph","content":"Description..."}Dùng Cho AI Agent#
Agent MD có một rule cho AI agent trong docs/llm-agent-rule.md:
Khi cần đọc, ghi, hoặc sửa file markdown, luôn dùng
agent-mdCLI thay vì thao tác file trực tiếp.
Workflow mẫu:
# 1. Lấy cấu trúc document
agent-md read README.md --field headings
# 2. Tìm kiếm content
agent-md search README.md "TODO"
# 3. Validate content trước khi ghi
agent-md lint --content "# New Title\nContent with **bold**"
# 4. Ghi content đã validate
agent-md write README.md "# New Title\nValid content"VS Code Extension#
Agent MD còn có extension cho VS Code:
- Format on demand (
Shift+Option+F) - Format on save
- Configurable options (xoá bold, compact blanks…)
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "agent-md.agent-md-formatter"
}
}So Sánh Với Công Cụ Khác#
| Tiêu chí | Prettier / markdownlint | Agent MD |
|---|---|---|
| Mục đích | Làm đẹp cho người đọc | Tối ưu cho AI |
| Output | Markdown gốc | JSON |
| In đậm/nghiêng | Giữ nguyên | Xoá bỏ |
| Bảng | Giữ nguyên | Chuyển thành list |
| Section reading | Không | Đọc theo heading path |
| Lint rules | Style cho người | Token-efficient cho AI |
Kết Luận#
Agent MD là công cụ đặc thù cho kỷ nguyên AI: nó tối ưu markdown cho LLM đọc, không phải cho người xem.
Nếu bạn đang xây dựng hệ thống AI agent phải đọc/ghi markdown (documentation, README, blog), Agent MD giúp:
- Tiết kiệm ~20% token
- Output JSON dễ parse
- Đọc theo section, không cần đọc cả file
- Tự động validate content trước khi ghi
Một công cụ nhỏ, ý tưởng lớn, viết bằng Rust — đáng để thử trong stack AI của bạn.