blog.dopana

返回

你写给人看的文档,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 做结构化解析:

Markdown输入分离YAML frontmatter识别block: heading, table, list,code, HTML按类型做上下文格式化17条规则lint紧凑输出, 按需JSON

主要步骤:

  1. 严格保留文件头 YAML frontmatter
  2. 识别每个 block:标题、代码、表格、列表、HTML、段落
  3. 按类型做上下文相关、节省 token 的格式化
  4. 用 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 跳到 H3
  • code-blocks:代码必须写语言,必须闭合 fence
  • list-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"
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

实战: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 ignore
bash

lint 返回 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.md
bash

通过时的例子:

{
  "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 server
diff

默认还会去粗体标记、压缩空行、合并多空格、删除水平线、去斜体、HTML 压成一行、无名代码块加 text、删除空 list 项、list 缩进统一 2 空格。

只读一节,不读全文#

这是对 agent 最有用的功能:700 行 README 不用全读,只取需要的 section。

推荐的 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 通过就不用再格式化

参考文献#