★ FEATURED ARTICLE 【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载你有没有想过让 AI 直接调用你的 API结果它只能靠猜参数和示例开源框架 Forge 中的 astro-fern 引擎可以从一份 OpenAPI 规范自动为 AI Agent 生成友好的 Markdown 文档与 llms.txt 索引让 AI 真正读懂你的 API 文档。为什么 API 文档需要AI 可读传统 API 参考页是为人类设计的大量导航栏、动态加载、JavaScript 渲染的 HTML。AI Agent 抓到这样的页面往往只能看到一堆与 API 本身无关的噪音。而 llms.txt 约定正在改变这一点——它是一个纯文本索引文件告诉 AI这份文档里有什么、在哪里。配合结构清晰的 Markdown 操作文档AI 就能按图索骥精准获取方法、路径、参数与示例。astro-fern 是什么Forge是 Cloudflare 开源的 schema-first OpenAPI 代码生成框架Apache-2.0核心引擎负责解析 OpenAPI 3.x、应用 JSONPath 覆层并生成 SDK 与 CLI。astro-fern 则是其中通用的 Astro 引擎加载 OpenAPI 文档、解析 schema、构建目录catalog、规划路由并为 Agent 渲染 Markdown——这正是本文的主角。简单说你只需要维护一份 OpenAPI 文件它既产出人类看的 API 参考页也同时产出 AI 能高效消费的两类文档。✨astro-fern 自动生成的两类 AI 友好文档一每个操作一篇 Markdown 文档每个 API 操作operation都会生成独立的 Markdown 文档分两种形态聚合文档包含所有执行目标如 curl、各语言 SDK目标文档每个 target 一篇只含对应语言的调用示例路径规划一目了然假设路由基座为/api/api/dns/records/methods/list.md # 聚合文档 /api/dns/curl/records/methods/list.md # curl 目标文档 /api/dns/v1/records/methods/list.md # v1 快照一篇生成的文档长这样来自 renderPageMarkdown() 的实际输出结构# Configure gadget Configures a gadget. **Destructive operation:** This operation removes all gadgets. - Product: Gadgets - Section: Gadget Management - Snapshot: Current - Method: POST - Path: /gadgets/{gadget_id} - Availability: beta (Subject to change.) ## Path parameters ### gadget_id Type: string Required: yes ## Execute with curl bash curl -X POST https://api.example.com/gadgets/123 ## Responses ### Response 200 Category: success几个专为 AI 设计的细节文档开头默认注入一行指令directiveThis page is optimized for agents. Use the linked Markdown pages and llms.txt indexes for related API content.引导 Agent 沿着关联链接继续探索破坏性操作会用醒目的Destructive operation标记让 AI 在调用前意识到风险参数与 schema 递归展开包括枚举值、默认值、废弃标记、字段描述——Agent 读到的是原始 Markdown 源码而非渲染后的 HTML文末附Related representations链接到人类文档、各目标 Markdown 与各级 llms.txt形成可遍历的文档图二四层嵌套的 llms.txt 索引除单篇 Markdown 外astro-fern 还会按四个作用域生成 llms.txt 索引作用域路径内容site/llms.txt全部产品清单product/api/{product}/llms.txt产品默认快照的全部操作snapshot/api/{product}/{snapshot}/llms.txt产品某个版本快照的操作target/api/{product}/targets/{target}/llms.txt某快照下单一执行目标的操作站点级索引renderLlmsIndexFromCatalog() 输出类似# API documentation ## Products - DNS: Manage DNS records and settings. - Gadgets: Configure and manage gadgets.产品级索引则按章节分组每个操作一行带 HTTP 方法与一句话摘要AI 读一个索引文件就能摸清整个 API 的全貌——这是典型的长尾友好设计小索引指路Markdown 正文承载细节。快速上手三步获得 Markdown 与 llms.txt好消息是这些路由默认自动挂载无需额外代码。在 astro.config.mjs 注册集成astroFern({ routing: { base: /api, target: path } })agents相关选项injectRoutes、markdown、llms全部默认为开启在 src/content.config.ts 注册内容通过defineFernCollections({ source, manifest })指向你的openapi.json构建部署Markdown 与 llms.txt 路由即随站点一起生效站点根部的 llms.txt 见 src/pages/llms.txt.ts如果想自己接管路由把agents.injectRoutes设为false再用getAgentRoutes()获取全部计划路径挂载 renderLlmsPathnameResponse() 与 renderPageMarkdownPathnameResponse() 即可。安全与自定义的细节设计Markdown 净化Agent 文档面向公开访问markdown.ts 中的净化插件会把来源文档里的可执行 HTML 转为纯文本仅保留http、https、mailto、tel协议的链接自定义 URL 方案不想用默认路径可关闭包的 agent 计划改用renderPageMarkdown()/renderLlmsIndexFromCatalog()配合语义链接解析器SemanticHrefResolver把同样的文档渲染到查询参数或其他 URL 方案下版本快照为不同 API 版本注册 snapshot 后每个版本都有独立的 llms.txt 与 Markdown历史文档同样 AI 可达关键源码与文件参考文件说明packages/astro-fern/agents/index.tsrenderPageMarkdown()与renderLlmsIndexFromCatalog()核心渲染逻辑packages/astro-fern/agents/routes/root-llms.ts站点级/llms.txt路由packages/astro-fern/agents/routes/scoped-llms.tsproduct/snapshot/target 作用域 llms.txt 路由packages/astro-fern/agents/routes/markdown.ts操作 Markdown 文档路由packages/astro-fern/runtime-config.tsagents配置项解析injectRoutes/markdown/llms/directivepackages/astro-fern/README.mdastro-fern 完整文档Publish agent documents 章节小结想让 AI Agent 真正用好你的 API别再让它硬啃 HTML 了。用 Forge 的 astro-fern一份 OpenAPI 就能同时产出人类可读的 API 参考页、Agent 友好的操作级 Markdown 和四层 llms.txt 索引——这正是AI 友好 API 文档的完整配方。赞分享【免费下载链接】forge项目地址https://gitcode.com/gh_mirrors/forge55/forge点击查看免费下载相关推荐Instructor 采用 llms.txt让结构化输出文档对 LLM 与 AI 编程助手更友好Instructor 采用 llms.txt让结构化输出文档对 LLM 与 AI 编程助手更友好 本文基于仓库内公告《 Instructor Adopts l人工智能大模型AI 应用Lightweight Charts™ 的 AI 开发实践Agent Skills 与 llms.txt 友好的文档生态Lightweight Charts™ 的 AI 开发实践Agent Skills 与 llms.txt 友好的文档生态 这篇指南以 Lightweight前端图表库金融科技数据可视化Instructor 文档开启 llms.txt 支持用 mkdocs-llmstxt 为 LLM 打造 AI 友好文档Instructor 文档开启 llms.txt 支持用 mkdocs llmstxt 为 LLM 打造 AI 友好文档 本文介绍 Instructor 项目人工智能大模型AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
