blog.dopana

Quay lại

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 API format_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:

Markdown inputTach frontmatter YAMLNhan dien block: heading,table, list, code, HTMLFormat theo tung loai blockLint 17 quy tacOutput gon, JSON neu can

Các bước chính:

  1. Giữ nguyên YAML frontmatter đầu file
  2. Nhận diện từng block: heading, code, table, list, HTML, paragraph
  3. Format theo ngữ cảnh từng loại, tối ưu token
  4. 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ưới
  • simple-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ảng
  • no-ascii-graph: cấm sơ đồ ký tự khung, thay bằng CSV, JSON, Mermaid, list
  • heading-structure: một H1 duy nhất, không nhảy cấp từ H1 xuống H3
  • code-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ỗng
  • space-indentation: text thường tối đa 2 spaces, code được miễn
  • no-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.
text

Nhó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"
bash
use 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);
rust

Dù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 ignore
bash

Lint 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.md
bash

Ví dụ output khi file đạt chuẩn:

{
  "valid": true,
  "errors": [],
  "warnings": []
}
json

Ví 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 |
diff

Ví 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 server
diff

Mặ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.

Luồ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"
bash

Cá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.
text

Hoặ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 fmt trướ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: lint báo valid thì thôi, không cần format lại

Tài liệu tham khảo#