基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-20 22:00

给编程智能体提供 Markdown 版 API 文档

dev.to · AI#API 文档#Markdown#内容协商
Editor brief · 编辑速览

团队为 API 文档提供 Markdown 直链、llms.txt 入口,并支持通过 Accept 请求头在原 URL 获取 Markdown。单页实测中,HTML 响应约为 Markdown 的 30 倍,测试只统计了响应字节数。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

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 里的链接能打开。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
识别冒牌 GPTBot 要看来源 IP
下一篇
修图智能体通过质检仍可能漏改

资讯速览

dev.to · AI · 2026-11-20 22:00

AI 评分 8.0 / 10

相关标签

#API 文档#Markdown#内容协商

继续阅读

  • 只算 FLOPs,微调工期平均错了 12 小时
  • 识别冒牌 GPTBot 要看来源 IP
  • 修图智能体通过质检仍可能漏改
  • 两万多次调用归纳出 12 类 MCP 故障
  • 实测 16 个 Python Agent 包的依赖开销