你写给人看的文档,AI agent 每天都要读一遍,还要为每个星号、每个多余空格付 token 费。熟悉吗?
问题:Markdown 为人类美观而生。LLM 不需要漂亮,需要紧凑、结构清晰、能按章节提取。agent-md 正好解决这件事:一个 Rust CLI,让 Markdown 对 LLM 友好,节省 token,同时人类依然可读。
Agent-md 是什么?#
像给 10 岁孩子解释:想象给朋友打包午餐。人类喜欢多格精美饭盒,机器人只想要一个紧凑、标签清晰、打开就能拿到的盒子。agent-md 就是给机器人打包的人。
具体来说,agent-md 是:
- 为 AI agent 格式化和 lint Markdown 的高速 Rust CLI,单个二进制文件
- Rust 库 (
agent_md),提供format_markdown、parse_markdown、validate_markdown - VS Code 扩展 Agent-MD Formatter,支持保存时格式化
- 所有命令返回 JSON,方便 LLM 解析,另有
--human给人看
当前版本 0.2.16,可用 cargo install agent-md 或源码构建安装。
为什么普通 Markdown 浪费 Token?#
LLM 生成的 Markdown 常常冗余:
- 装饰性
**bold**和斜体标记,对机器没有增加含义 - 宽表格和长分隔符
|----------|,其实|---|就够 - 代码注释里大量空格:
bun dev # run server - 连续空行、水平线
---、正文 4 空格缩进 - 无意义链接如
[https://example.com](https://example.com) - 框线字符画的图和手绘风目录树,很难解析
LLM 每次读文件,你都在为装饰交 token 税。文档多的仓库累积很快。
Agent-md 如何工作?#
它不是简单的按行格式化。agent-md 做结构化解析:
主要步骤:
- 严格保留文件头 YAML frontmatter
- 识别每个 block:标题、代码、表格、列表、HTML、段落
- 按类型做上下文相关、节省 token 的格式化
- 用 linter 校验,返回含
valid、errors、warnings的 JSON
Agent-md 写作规范#
linter 有 17 条规则,分两组。错误会阻止写入,警告建议修复。
常见错误规则:
no-bold:代码外禁止**bold**和__bold__,见下例simple-table:最多 5 列,分隔符必须是|---|,去掉对齐冒号table-trailing-spaces:表格单元格禁止多余尾空格no-ascii-graph:禁止框线图,改用 CSV、JSON、Mermaid、列表heading-structure:只允许一个 H1,禁止 H1 跳到 H3code-blocks:代码必须写语言,必须闭合 fencelist-formatting:标记统一,禁止空条目space-indentation:正文最多 2 空格,代码豁免no-useless-links:链接文字必须与 URL 不同
no-bold 示例:
This line fails because it has double stars.
Replace with plain text, or use a heading, or use code.
Code blocks may keep their original syntax.text警告规则包括重复标题、连续空行、标题上下缺少空行、文件缺首 H1、缺末尾换行、硬 Tab、行尾空格。
完整细节在源仓库 docs/markdown-writing-rules.md。
安装#
cargo install agent-md
# 或源码构建
cargo build --release
# 二进制在 target/release/agent-md
# 作为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);rust实战:Format 与 Lint#
格式化单个文件或整个目录,自动尊重 .gitignore 和 .markdownlintignore:
agent-md README.md
agent-md fmt README.md
agent-md fmt .
# 查看对某文件生效的配置
agent-md config path/to/document.md
# 查看合并后的ignore规则
agent-md ignorebashlint 返回 JSON,agent 可直接读:
agent-md lint README.md
agent-md --human lint README.md
agent-md lint --content "# Title\nContent here"
agent-md lint-file README.mdbash通过时的例子:
{
"valid": true,
"errors": [],
"warnings": []
}json表格前后对比:
| Function | Arguments | Return Type | Description |
-|----------|-----------|-------------|-------------------------------|
-| `add()` | a, b | i32 | Adds two numbers |
+|---|---|---|---|
+| `add()` | a, b | i32 | Adds two numbers |diff代码注释空格压缩:
-bun i # Install dependencies
-bun run dev # Run the development server
+bun i # Install dependencies
+bun run dev # Run the development serverdiff默认还会去粗体标记、压缩空行、合并多空格、删除水平线、去斜体、HTML 压成一行、无名代码块加 text、删除空 list 项、list 缩进统一 2 空格。
只读一节,不读全文#
这是对 agent 最有用的功能:700 行 README 不用全读,只取需要的 section。
# 先看结构
agent-md headings README.md
agent-md read README.md --field headings
# 只读Development一节
agent-md read README.md --content "## Development"
# 嵌套节
agent-md read README.md --content "## Development > Build"
# 取单个字段
agent-md read README.md --field content
agent-md read README.md --field word_count
# 搜索、统计、转JSONL
agent-md search README.md "TODO"
agent-md stats README.md
agent-md to-jsonl README.mdbash推荐的 agent 流程:
# 1. 取结构
agent-md read README.md --field headings
# 2. 搜索要改的位置
agent-md search README.md "TODO"
# 3. 写之前先校验
agent-md lint --content "# New Title\nValid content"
# 4. 带校验写入
agent-md write README.md "# New Title\nValid content"
# 5. 只替换一节
agent-md write-section README.md --section "## Development" --content "New content"bash其它写入命令:write、append、insert、delete、write-section、list。write 会先自动校验,很难写出不合规文件。
接入 Agent 工作流#
在 AGENTS.md 加一行,agent 就会遵守:
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简单说:读写改 Markdown 都用 agent-md CLI,而不是直接改文件。源仓库 docs/llm-agent-rule.md 有完整集成指南。
VS Code 装 Agent-MD Formatter,给 Markdown 打开保存时格式化:
{
"[markdown]": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "agent-md.agent-md-formatter"
}
}json[!TIP] LLM 生成的文档在 commit 前先过一遍
agent-md fmt。信息完整保留,很多场景可省约 20% token,LLM 读得更快,花得更少。
什么时候不该用?#
- 文档要给人精美打印,需要复杂表格对齐:保留人用版,另生一份紧凑的 agent 版
- ASCII 图是团队文化:迁到 Mermaid,人和机器都能读
- 文件已经 valid:
lint通过就不用再格式化
参考文献#
- 主仓库:loclv/agent-md on GitHub ↗
- Rust 包:agent-md on crates.io ↗
- Markdown 规则:源仓库
docs/markdown-writing-rules.md - Agent 指南:源仓库
docs/llm-agent-rule.md - 扩展:Agent-MD Formatter on VS Code Marketplace ↗
- 相关标准:llms.txt ↗