llm.energy：为AI智能体精准提取文档的引擎，告别爬虫噪音

1. 项目概述为AI智能体“供能”的文档提取引擎如果你正在构建AI智能体、自动化工作流或者只是想让Claude、Cursor这类AI助手更好地理解和使用某个项目的文档那你一定遇到过这样的困境文档散落在各个角落格式五花八门AI很难直接、准确地“消化”它们。传统的爬虫抓取回来的内容往往夹杂着导航栏、广告、无关的样式代码真正有用的核心文档信息被淹没在噪音里。更别提让AI去执行像“安装并配置这个项目”这样的具体任务了——它可能连从哪里开始、需要哪些步骤都搞不清楚。这正是llm.energy这个项目要解决的核心痛点。它不是一个简单的网页抓取工具而是一个专门为AI时代设计的、智能化的文档提取与结构化引擎。它的目标非常明确从任何支持llms.txt或install.md标准的网站中精准地提取出机器可读、AI友好的文档内容并将其转化为智能体可以直接“食用”的格式。简单来说llm.energy扮演着“AI文档营养师”的角色。它知道AI“吃”什么最健康、最容易吸收。llms.txt就像一份为AI特制的“营养成分表”以标准化的格式通常是YAML或JSON清晰地列出了项目的描述、API端点、工具定义、使用示例等关键元数据。而install.md则是一份“AI可执行的食谱”用结构化的Markdown语言详细说明了安装、配置、运行的每一步操作AI可以像解析程序一样解析并执行它。这个项目最初由开发者nirholas发起其价值在于它精准地捕捉到了当前AI应用开发中的一个关键需求上下文供给的质量。无论是基于RAG检索增强生成的系统还是需要调用外部工具的智能体其表现的上限很大程度上取决于喂给它的上下文信息是否精准、结构化和及时。llm.energy通过拥抱并推广llms.txt和install.md这两个新兴标准试图从源头解决这个问题让文档的发布者能够以一种AI原生AI-native的方式来准备他们的文档。接下来我将为你深入拆解这个项目的设计思路、核心功能、实际用法并分享我在探索和测试过程中的一些实操心得与避坑指南。2. 核心设计思路为什么是“提取”而非“爬取”在深入代码和API之前理解llm.energy背后的设计哲学至关重要。这决定了它和普通爬虫工具的根本区别。2.1 从“人类可读”到“机器可理解”的范式转变传统文档是为人类设计的。我们通过视觉布局、颜色、字体大小来区分标题、正文、代码块和注意事项。但AI特别是大型语言模型LLM处理的是纯文本序列。它没有“视觉”概念一个漂亮的卡片式设计在它看来可能只是一堆混乱的HTML标签和CSS类名。llm.energy的设计前提是承认并利用一种新的文档标准。llms.txt和install.md本身就是为机器解析而生的。它们的结构是声明式的、数据化的。例如一个llms.txt文件可能明确地用description:字段描述项目用tools:数组列出所有可用工具及其参数。这种结构消除了歧义让AI无需猜测就能获得准确信息。因此llm.energy的“提取”过程更像是一个“解析”和“转换”的过程。它首先会智能地探测目标网站是否提供了这些标准文件通常位于/.well-known/llms.txt或根目录的install.md。如果找到了它就直接解析这些结构化的数据如果没有它会尝试从常规文档页面中推断和提取出类似结构的信息但其核心逻辑始终围绕着这些标准展开。2.2 架构分层清晰的责任边界从项目结构图中可以看出llm.energy采用了清晰的分层架构这保证了其扩展性和可维护性交互层Presentation Layer包含Web应用Next.js和MCP服务器。前者提供友好的图形界面后者则通过标准化的Model Context ProtocolMCP将功能暴露给Claude Desktop、Cursor等AI原生开发环境。这意味着你不仅可以在浏览器里使用它还能让AI助手直接调用它的能力。逻辑层Logic Layer即REST API/api/*和核心Core模块。所有复杂的业务逻辑如URL探测、内容解析、格式转换、缓存处理都封装在这里。这是项目的“大脑”。数据源层Data Source Layer直接与llms.txt、install.md以及网站地图Sitemap交互。这一层负责最原始的获取工作。这种架构的好处是每层都可以独立演化。例如未来可以轻松增加对新的AI文档标准的支持只需在数据源层和核心逻辑层添加对应的解析器而上层的Web应用和API无需大幅改动。2.3 面向AI工作流的设计项目的每一个功能点都透露出对AI工作流的深度思考批量处理AI智能体可能需要同时了解多个相关库的文档批量提取功能可以一次性构建一个丰富的上下文知识库。多格式导出除了给人看的Markdown还提供JSON、YAML等机器更易解析的格式方便直接集成到RAG系统的向量化管道或智能体的初始化配置中。AGENT-GUIDE.md这不是简单的原始文档拼接。提取后会生成一个专门优化的指南可能包含更清晰的步骤总结、常见的调用示例、错误处理建议等相当于为AI准备了一份“快速上手指南”。理解了这些设计思路我们就能更好地运用这个工具而不是把它当作一个黑盒。3. 核心功能实战解析llm.energy提供了多种使用方式从简单的网页操作到API集成再到与开发环境深度结合。我们来逐一拆解。3.1 网页端零代码快速提取对于大多数用户访问 llm.energy 是最直接的开始方式。它的界面非常直观。基本提取流程在首页的输入框填入你想要提取文档的网站域名或具体文档页URL。例如docs.anthropic.com或https://docs.anthropic.com/en/docs/quickstart。点击“Extract”按钮。工具会首先尝试查找/.well-known/llms.txt和/install.md。如果找到页面会展示解析后的结构化内容包括项目描述、工具列表、安装步骤等并清晰地区分哪些信息来自llms.txt哪些来自install.md。你可以直接在线浏览也可以选择以Markdown、JSON或ZIP压缩包格式下载全部内容。实操心得域名 vs 具体页面输入顶级域名如docs.anthropic.com通常是最佳选择因为标准文件通常放在根目录。输入具体页面URL工具可能会尝试从该页面的内容中推断和提取相关信息但效果取决于页面的结构化程度。“Site Directory”的妙用网站内置了一个精选目录列出了已知支持llms.txt的网站如Anthropic、Vercel、Stripe的文档站。当你不知道哪些项目支持该标准时来这里逛逛能发现很多“宝藏”也可以直接从这里点击跳转提取非常方便。生成器工具Wizard如果你在维护一个开源项目强烈建议使用它的llms.txt和install.md生成器。它通过一系列引导式问题帮你生成符合标准的文件内容你只需要复制粘贴到项目的对应位置即可。这是推动生态发展的举手之劳。3.2 API集成自动化文档管道对于开发者API才是发挥其威力的关键。它允许你将文档提取能力集成到自己的CI/CD流程、监控脚本或后台服务中。核心API端点详解POST /api/extract- 核心提取功能这是最常用的端点。发送一个包含目标URL的JSON请求即可获取结构化的文档数据。curl -X POST https://llm.energy/api/extract \ -H Content-Type: application/json \ -d {url: https://docs.anthropic.com}响应分析返回的JSON结构通常包含success状态、提取到的data按章节组织的Markdown内容数组、metadata来源URL、提取时间、支持的格式列表以及用于下载的downloadUrls。你可以根据data里的内容直接构建你的知识库。POST /api/batch- 批量处理当需要为多个相关项目建立文档集合时批量处理能节省大量时间。curl -X POST https://llm.energy/api/batch \ -H Content-Type: application/json \ -d {urls: [docs.anthropic.com, docs.stripe.com, supabase.com/docs]}注意事项批量处理是异步的。响应中通常会返回一个jobId或taskId你需要轮询另一个端点或通过Webhook来获取最终结果。请仔细查阅最新的API文档以确认其具体实现方式。POST /api/generate-install- AI驱动的install.md生成这是我认为最具创新性的功能。它利用AI项目集成的是Claude来分析一个现有的GitHub仓库或文档页自动生成一份结构良好的install.md文件。# 从GitHub仓库生成 curl -X POST https://llm.energy/api/generate-install \ -H Content-Type: application/json \ -d { url: https://github.com/anthropics/anthropic-sdk-python, type: github }内部工作流GitHub模式它会分析仓库的README、package.json/pyproject.toml/Cargo.toml等依赖文件、GitHub Actions工作流以及发布版本信息。URL模式它会抓取指定文档页并尝试识别其使用的平台如Mintlify, Docusaurus然后提取核心安装和配置说明。AI合成将分析得到的原始信息发送给Claude按照install.md的标准格式进行重写和组织产出包括“前提条件”、“安装步骤”、“配置方法”、“验证安装”、“获取帮助”等标准章节的文档。避坑指南权限与限流对GitHub API的调用可能有频率限制。对于私有仓库通常需要提供GitHub Token。公开仓库虽然不需要但在大规模使用时仍需注意。生成质量AI生成的结果需要人工复核。虽然Claude能力很强但对于特别复杂或非标准的项目可能仍需要手动调整步骤顺序或补充细节。3.3 MCP服务器与AI开发环境无缝融合Model Context Protocol (MCP) 是Anthropic推出的一种协议旨在让AI助手如Claude能够安全、可控地使用外部工具和资源。llm.energy提供了MCP服务器这是将其能力深度融入开发者工作流的关键。配置示例以Claude Desktop为例在你的MCP客户端配置文件例如claude_desktop_config.json中添加{ mcpServers: { llm-energy: { command: npx, args: [-y, llm-energy/mcp-server] } } }配置完成后重启Claude Desktop你的Claude助手就获得了以下新能力extract_docs直接让Claude“去查一下某某项目的文档”。validate_url询问Claude“某个网站有没有AI可读的文档”。list_sites让Claude“列举一些已知的支持llms.txt的网站”。真实场景体验 当你在Cursor或Claude中编码需要了解一个库的用法时不再需要手动打开浏览器搜索、筛选广告、复制代码。你只需对AI说“请使用llm-energy工具提取docs.pydantic.dev的安装指南。” AI会调用MCP服务器获取结构化的install.md然后基于此给你提供准确的安装命令和配置建议。这极大地提升了开发效率和信息准确性。4. 自托管部署与深度定制虽然官方提供了托管服务但出于数据隐私、定制化需求或网络环境考虑你可能需要自托管部署。4.1 本地开发环境搭建项目使用现代TypeScript/Next.js技术栈依赖管理工具是pnpm。# 1. 克隆仓库 git clone https://github.com/nirholas/extract-llms-docs.git cd extract-llms-docs # 2. 安装依赖 (确保已安装Node.js和pnpm) pnpm install # 3. 配置环境变量可选但推荐 cp .env.example .env.local # 编辑 .env.local设置如ANTHROPIC_API_KEY用于install.md生成、缓存、限流等参数 # 4. 启动开发服务器 pnpm dev启动后Web应用默认运行在http://localhost:3001。4.2 关键配置解析环境变量文件.env.local是你调优和定制化的入口# API Keys (用于增强功能) ANTHROPIC_API_KEYsk-... # 用于install.md生成器的AI合成功能 GITHUB_TOKENghp_... # 用于提高GitHub API速率限制或访问私有仓库 # 性能与资源控制 RATE_LIMIT_REQUESTS100 # 每个时间窗口内每个IP的最大请求数 RATE_LIMIT_WINDOW_MS60000 # 时间窗口长度毫秒默认1分钟 CACHE_TTL3600 # 提取结果的缓存时间秒减轻源站压力 MAX_CONTENT_LENGTH5000000 # 单个页面最大处理内容长度字节防止内存溢出 # 安全与管理 ADMIN_KEYyour-secret-key # 管理API的密钥用于清理缓存等操作 ALLOWED_DOMAINS* # 允许提取的域名可设置为特定域名列表以提高安全性配置建议ANTHROPIC_API_KEY如果你计划频繁使用install.md生成器这是必选项。否则该功能将不可用或降级为简单提取。RATE_LIMIT_*在生产环境中务必根据你的服务器性能和预期流量设置合理的限流值防止恶意爬取或意外过载。ALLOWED_DOMAINS在内部部署中可以将其设置为公司内部的文档域名将其变成一个内部知识提取工具避免被滥用。4.3 生产环境部署项目基于Next.js可以轻松部署到Vercel原作者的选择、Netlify、AWS等平台。以Vercel为例将你的仓库导入Vercel。在项目设置中配置上述环境变量。Vercel会自动识别为Next.js项目并完成构建部署。构建与优化# 构建生产版本 pnpm build # 预览生产构建 pnpm start # 运行测试套件项目包含163个测试 pnpm test # 生成测试覆盖率报告 pnpm test:coverage在部署前运行pnpm build和pnpm test是良好的习惯确保代码质量和功能正常。5. 高级应用场景与避坑指南掌握了基本用法后我们可以探索一些更高级的应用模式并分享一些实践中容易遇到的问题。5.1 构建自动化的RAG文档管道假设你正在为公司内部构建一个AI问答助手需要集成多个内部技术栈的文档。传统做法手动维护一个文档列表定期用爬虫抓取然后清洗、分割、向量化。过程繁琐且文档更新不同步。使用llm.energy的优化方案清单管理创建一个YAML文件如docs-sources.yaml列出所有需要集成的内部文档站地址。定时提取编写一个简单的脚本如Python或Node.js定期例如每天调用llm.energy的批量API (/api/batch) 处理清单中的所有URL。结构化存储将API返回的JSON结果已按章节分割好的Markdown存储下来。向量化与更新将这些结构化的文本块送入你的向量数据库如Chroma, Weaviate, Pinecone进行嵌入Embedding。由于llm.energy已经做了清洗和分割这一步的质量和效率会高很多。自动化将整个流程封装成GitHub Action或CI/CD流水线实现全自动的文档同步。优势文档更新及时内容干净结构化减少了大量数据预处理工作让RAG系统能基于更高质量的上下文给出答案。5.2 为开源项目添加AI原生支持如果你是一个开源项目的维护者让项目对AI更友好能极大地提升其易用性和采用度。行动步骤生成llms.txt使用llm.energy网站上的生成器向导。你需要准备项目的简短描述、主要功能、API端点如果有、使用示例、获取帮助的渠道如Discord链接、问题模板地址等信息。生成后将文件保存为.well-known/llms.txt并提交到仓库根目录。生成或编写install.md如果你的项目安装过程简单可以手动编写。如果复杂可以先用llm.energy的AI生成器基于你的GitHub仓库生成一个初稿然后在此基础上修改和完善。确保步骤清晰、命令准确、包含了所有常见的环境配置和故障排查点。提交与验证将这两个文件推送到仓库后可以立即用llm.energy验证你的网站如果文档已部署或仓库的GitHub Pages地址看是否能被正确提取。这样做的好处你的项目会出现在llm.energy的站点目录中更容易被其他开发者发现。更重要的是任何集成了llm.energyMCP工具的AI助手如未来团队内部的Claude都能以最标准、最准确的方式获取你的项目信息降低支持成本。5.3 常见问题与排查技巧在实际使用中你可能会遇到以下问题问题现象可能原因排查与解决思路提取失败返回“未找到llms.txt或install.md”1. 目标网站确实不支持该标准。2. 网站有反爬机制或访问限制。3. URL格式错误如包含了https://但服务器重定向。1. 先用浏览器手动访问https://目标域名/.well-known/llms.txt和https://目标域名/install.md确认。2. 检查网站是否要求登录或有Cloudflare等防护。自托管版可考虑配置代理或User-Agent。3. 尝试只输入域名部分如example.com让工具自己构建URL。提取的内容不完整或杂乱1. 工具的回退解析器针对非标准页面未能正确识别主要内容区域。2. 页面是动态加载SPA初始HTML内容不足。1. 这属于当前技术的局限。最佳实践是推动网站所有者提供标准的llms.txt。2. 对于重要网站可以考虑为llm.energy项目贡献针对该网站的特殊解析规则在lib/parsers目录下。AI生成的install.md步骤有误1. 仓库的README或文档本身不清晰。2. AI在理解复杂或非典型工作流时出现偏差。永远要人工复核将AI生成的内容作为初稿和参考维护者必须根据实际经验进行校准和补充。这是目前AI辅助工具的通用原则。MCP服务器连接失败1.npx命令执行慢或网络问题。2. MCP客户端配置路径或格式错误。3. 防火墙或安全软件阻止。1. 尝试全局安装llm-energy/mcp-server包然后在配置中使用绝对路径指向其可执行文件。2. 仔细检查MCP客户端的配置文件格式确保JSON有效。3. 查看客户端日志通常会有更详细的错误信息。自托管版访问公开网站慢服务器网络出口问题。考虑将服务部署在海外网络较好的区域或者对频繁请求的站点配置更长的缓存时间CACHE_TTL。一个重要的心得llm.energy在遇到标准文件时表现最佳。因此最大的“避坑”技巧其实是主动推动生态建设。当你发现一个优秀的项目但没有llms.txt时可以友好地提一个Issue或PR建议他们添加并附上llm.energy生成器的链接。众人拾柴火焰高当支持标准的网站越来越多时这个工具的价值才会指数级增长。这个项目代表了一种趋势开发者工具正在从“为人服务”向“为AI与人共同服务”演进。它可能不是终点但它清晰地指出了一个方向——通过标准化和工具化让AI更可靠、更高效地接入人类的知识体系。无论是将其作为一次性文档提取工具还是作为自动化管道的关键组件亦或是通过MCP深度融入你的AI开发流llm.energy都提供了一个坚实且思路清晰的起点。