给编程智能体提供 Markdown 版 API 文档
团队为 API 文档提供 Markdown 直链、llms.txt 入口,并支持通过 Accept 请求头在原 URL 获取 Markdown。单页实测中,HTML 响应约为 Markdown 的 30 倍,测试只统计了响应字节数。
AI 深度解读
PerfectVector 把同一份 API 文档同时做成 HTML 和 Markdown,并给编程 Agent 留了三种入口:直接访问 .md、用 Accept 请求头指定格式,或从 /llms.txt 找文档。团队实测同一页的 HTML 响应大小是 Markdown 的 30.2 倍,其中大头是框架脚本。
这个数字能帮你判断现有文档有多少页面负载可以省掉。至于模型会少用多少 token、Agent 会不会更容易接对 API,作者还没测。比格式更容易借鉴的,是他们怎么把首次接入要查的信息放在一页里。
一次普通请求到底拉回了多少东西?
作者在 2026-11-13 测了自家「API for AI agents」页面。HTML 响应有 370,609 字节,用简单正则匹配 <script>…</script> 块,估算其中约 308,600 字节来自脚本标签及其内容,主要是框架的数据负载。这个值在多次请求之间略有浮动。页面可见文本约有 11,600 个字符,和响应字节数是两种口径。
同一页的 Markdown 版本 /docs/api/agents.md 只有 12,290 字节,仍包含端点表、错误说明和完整示例。30.2 倍是这次记录里的响应大小之比。如果客户端本来就会抽取正文,送进模型的内容差多少,还得看抽取后的结果。
Agent 怎么找到 Markdown?
知道路径的客户端可以直接取 .md。只知道 HTML 地址的客户端也能通过内容协商拿到 Markdown,也就是在请求里声明想要的格式。下面这条命令请求的是原来的文档 URL。
curl -s -H "Accept: text/markdown" https://perfectvector.com/docs/api/agents
这行里起作用的是 -H 传入的 Accept: text/markdown。服务端会返回 Content-Type: text/markdown,调用方无需猜测 .md 路径。
文档入口 /llms.txt 有 3,950 字节,先用一句话介绍产品,再指向产品事实、定价、API 参考和 MCP 文档的 Markdown 版本。HTML 页面通过 Link: </llms.txt>; rel="describedby" 响应头提示这个入口。/llms-full.txt 列出每页文档及摘要,机器可读的 /docs/catalog.json 则记录已发布文档、版本和审阅日期。
为什么首次接入所需的信息要放在同一页?
PerfectVector 把密钥、端点、价格、用量限制、错误和可运行示例放在同一页。写一个最小调用时,Agent 可以在同一份文档里查到怎么发请求、何时重试,以及遇到错误要走哪个分支。
端点、状态码和重试规则适合用表格,因为这些信息会直接影响客户端的处理逻辑。作者还明确约定,程序按稳定的错误码分支,detail 留给人阅读。这样即使错误说明改了措辞,客户端也不用跟着改字符串匹配。
我的判断
我会优先借鉴单页接入指南和稳定错误码。这两项改善的是 API 的接入体验,前端和 Node 调用方读 HTML 时也能用上。对于已经能可靠抽取 HTML 正文的团队,可以拿现有抽取结果和 Markdown 对照,看看端点表、错误说明和示例是否完整,再决定是否值得多维护一种发布格式。
作者没有验证哪些爬虫或 Agent 会请求 /llms.txt、.md 或使用 Accept 协商,也没有对照测试接入成功率。服务端日志可以告诉你哪些地址被访问过,单靠它看不出 Agent 拿到内容之后怎么用。多入口能否改善接入效果,目前还是团队的发布经验。
能拿来做什么
- 选一页常被 AI 编程助手引用的 API 文档,用普通
curl量一下响应字节数,再看看脚本占了多少。如果已有正文抽取流程,顺手核对抽取结果里的表格和代码示例。 - 给前端或 Node 的首次接入整理一页指南,把鉴权、端点、限制、错误和可运行示例放到一起。在重试与错误处理示例里,用稳定错误码写分支。
- 如果决定提供 Markdown,拿同一个文档地址分别测试默认请求和
Accept: text/markdown请求,核对响应类型和关键内容,再确认/llms.txt里的链接能打开。