Bạn viết tài liệu cho người đọc, rồi AI agent đọc nó mỗi ngày và trả tiền token cho từng dấu sao, từng khoảng trắng thừa. Nghe có quen không?
Vấn đề: Markdown sinh ra để người đọc thấy đẹp. LLM thì không cần đẹp, LLM cần gọn, rõ cấu trúc, dễ trích từng phần. agent-md giải quyết đúng việc này: một CLI viết bằng Rust giúp Markdown thân thiện với LLM, tiết kiệm token mà vẫn đọc được với người.
Agent-md Là Gì?#
Giải thích như bạn 10 tuổi: tưởng tượng bạn gói cơm trưa cho bạn mình. Người thì thích hộp nhiều ngăn trang trí, còn robot thì chỉ cần một hộp gọn, dán nhãn rõ ràng, mở đúng ngăn là lấy được cơm. agent-md là người gói hộp cơm đó cho robot.
Cụ thể, agent-md là:
- CLI format và lint Markdown cho AI agent, viết bằng Rust, chạy nhanh, một file binary
- Thư viện Rust (
agent_md) với APIformat_markdown,parse_markdown,validate_markdown - VS Code extension tên Agent-MD Formatter, có format on save
- Mọi lệnh trả về JSON để LLM dễ parse, thêm cờ
--humanđể người đọc
Phiên bản hiện tại là 0.2.16, cài qua cargo install agent-md hoặc build từ source.
Vì Sao Markdown Thường Tốn Token?#
Markdown do LLM sinh ra thường thừa:
- Chữ đậm
**bold**, chữ nghiêng trang trí, không thêm nghĩa cho máy - Bảng rộng, separator dài
|----------|thay vì|---| - Comment trong code block cách nhiều dấu trắng:
bun dev # chạy server - Dòng trống lặp lại, gạch ngang
---, indent 4 spaces trong text thường - Link vô nghĩa kiểu
[https://example.com](https://example.com) - Sơ đồ vẽ bằng ký tự khung, cây thư mục kiểu ký họa, rất khó parse
Mỗi lần LLM đọc file, bạn trả thuế token cho phần trang trí đó. Với repo nhiều tài liệu, con số cộng dồn rất nhanh.
Agent-md Hoạt Động Thế Nào?#
Không phải format theo dòng đơn giản. agent-md parse có cấu trúc:
Các bước chính:
- Giữ nguyên YAML frontmatter đầu file
- Nhận diện từng block: heading, code, table, list, HTML, paragraph
- Format theo ngữ cảnh từng loại, tối ưu token
- Kiểm tra bằng linter, trả JSON gồm
valid,errors,warnings
Quy Tắc Viết Chuẩn Agent-md#
Linter có 17 quy tắc, chia hai nhóm. Nhóm lỗi chặn ghi file, nhóm cảnh báo nên sửa.
Nhóm lỗi thường gặp:
no-bold: cấm**bold**và__bold__ngoài code, xem ví dụ dướisimple-table: bảng tối đa 5 cột, separator đúng|---|, bỏ dấu căn lềtable-trailing-spaces: cấm nhiều space thừa trong ô bảngno-ascii-graph: cấm sơ đồ ký tự khung, thay bằng CSV, JSON, Mermaid, listheading-structure: một H1 duy nhất, không nhảy cấp từ H1 xuống H3code-blocks: code phải có ngôn ngữ, phải đóng fence đầy đủlist-formatting: list nhất quán marker, không để item rỗngspace-indentation: text thường tối đa 2 spaces, code được miễnno-useless-links: text link phải khác URL
Ví dụ quy tắc cấm chữ đậm:
Chuoi nay bi loi vi co dau sao doi.
Thay bang text thuong, hoac dung tieu de, hoac dung code.
Code block thi duoc phep giu nguyen cu phap goc.textNhóm cảnh báo gồm trùng heading, nhiều dòng trống liên tiếp, thiếu dòng trống quanh heading, file thiếu H1 đầu file, thiếu newline cuối file, tab cứng, space cuối dòng.
Chi tiết đầy đủ nằm ở docs/markdown-writing-rules.md trong repo gốc.
Cài Đặt#
cargo install agent-md
# Hoac build tu source
cargo build --release
# Binary nam o target/release/agent-md
# Dung nhu library Rust
# Cargo.toml: agent-md = "0.2.16"bashuse agent_md::{format_markdown, validate_markdown};
let input = "# Heading\n\nSome text with *emphasis*.";
let formatted = format_markdown(input);
let result = validate_markdown(&formatted);
assert!(result.valid);rustDùng Thực Tế: Format Và Lint#
Format một file hoặc cả thư mục, tool tự tôn trọng .gitignore và .markdownlintignore:
agent-md README.md
agent-md fmt README.md
agent-md fmt .
# Xem cau hinh dang dung cho file
agent-md config path/to/document.md
# Xem ignore rules da gop
agent-md ignorebashLint trả JSON để agent dễ đọc:
agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.mdbashVí dụ output khi file đạt chuẩn:
{
"valid": true,
"errors": [],
"warnings": []
}jsonVí dụ trước và sau khi format bảng:
| Function | Arguments | Return Type | Description |
-|----------|-----------|-------------|-------------------------------|
-| `add()` | a, b | i32 | Adds two numbers |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |diffVí dụ comment trong code block được gom space thừa:
-bun i # Install dependencies
-bun run dev # Run the development server
+bun i # Install dependencies
+bun run dev # Run the development serverdiffMặc định formatter còn bỏ marker đậm, gom dòng trống, gộp nhiều space, xóa dòng kẻ ngang, bỏ nghiêng, minify HTML thành một dòng, gắn text cho code block không nhãn, xóa item list rỗng, chuẩn indent list 2 spaces.
Đọc Đúng Phần File, Không Đọc Cả File#
Đây là tính năng hay nhất cho agent: không cần đọc cả README 700 dòng để lấy một section.
# Doc cau truc truoc
agent-md headings README.md
agent-md read README.md --field headings
# Doc dung section Development
agent-md read README.md --content "## Development"
# Doc section long nhau
agent-md read README.md --content "## Development > Build"
# Lay tung field
agent-md read README.md --field content
agent-md read README.md --field word_count
# Tim kiem, thong ke, chuyen JSONL
agent-md search README.md "TODO"
agent-md stats README.md
agent-md to-jsonl README.mdbashLuồng làm việc gợi ý cho agent:
# 1. Lay cau truc
agent-md read README.md --field headings
# 2. Tim noi can sua
agent-md search README.md "TODO"
# 3. Validate truoc khi ghi
agent-md lint --content "# New Title\nValid content"
# 4. Ghi co validate
agent-md write README.md "# New Title\nValid content"
# 5. Ghi dung mot section
agent-md write-section README.md --section "## Development" --content "New content"bashCác lệnh ghi khác: write, append, insert, delete, write-section, list. Lệnh write tự validate trước khi ghi nên khó tạo file lỗi chuẩn.
Gắn Vào Quy Trình Của Agent#
Thêm một dòng vào AGENTS.md là agent tự tuân thủ:
After creating or updating any markdown file, always run agent-md lint path/to/file.md to validate before done.
On task completion, update docs, update README.md, and write unit tests.textHoặc dặn ngắn gọn: dùng CLI agent-md khi đọc, ghi, sửa Markdown thay vì sửa file trực tiếp. Repo gốc còn có file docs/llm-agent-rule.md hướng dẫn tích hợp đầy đủ.
Với VS Code, cài extension Agent-MD Formatter, bật format on save cho Markdown:
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "agent-md.agent-md-formatter"
}
}json[!TIP] Chạy
agent-md fmttrước khi commit tài liệu do LLM sinh ra. Bạn giữ đủ thông tin, giảm khoảng 20% token trong nhiều case, LLM đọc nhanh hơn, trả tiền ít hơn.
Khi Nào Không Nên Dùng?#
- Tài liệu cần in đẹp cho người, cần căn lề bảng cầu kỳ: cứ giữ bản cho người, sinh thêm bản gọn cho agent
- Sơ đồ ASCII là tài sản văn hóa của team: chuyển sang Mermaid để cả người và máy đều đọc được
- File đã đạt chuẩn:
lintbáo valid thì thôi, không cần format lại
Tài liệu tham khảo#
- Repo chính: loclv/agent-md trên GitHub ↗
- Package Rust: agent-md trên crates.io ↗
- Quy tắc Markdown:
docs/markdown-writing-rules.mdtrong repoagent-md - Hướng dẫn agent:
docs/llm-agent-rule.mdtrong repoagent-md - Extension: Agent-MD Formatter trên VS Code Marketplace ↗
- Chuẩn liên quan: llms.txt ↗