企业官网建设流程全解析

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采用了清晰的分层架构，这保证了其扩展性和可维护性：

1. 交互层（Presentation Layer）：包含Web应用（Next.js）和MCP服务器。前者提供友好的图形界面，后者则通过标准化的Model Context Protocol（MCP）将功能暴露给Claude Desktop、Cursor等AI原生开发环境。这意味着你不仅可以在浏览器里使用它，还能让AI助手直接调用它的能力。
2. 逻辑层（Logic Layer）：即REST API（/api/*）和核心（Core）模块。所有复杂的业务逻辑，如URL探测、内容解析、格式转换、缓存处理，都封装在这里。这是项目的“大脑”。
3. 数据源层（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 是最直接的开始方式。它的界面非常直观。

基本提取流程：

1. 在首页的输入框，填入你想要提取文档的网站域名或具体文档页URL。例如，docs.anthropic.com或https://docs.anthropic.com/en/docs/quickstart。
2. 点击“Extract”按钮。工具会首先尝试查找/.well-known/llms.txt和/install.md。
3. 如果找到，页面会展示解析后的结构化内容，包括项目描述、工具列表、安装步骤等，并清晰地区分哪些信息来自llms.txt，哪些来自install.md。
4. 你可以直接在线浏览，也可以选择以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端点详解：

1. 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里的内容直接构建你的知识库。

2. 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文档以确认其具体实现方式。

3. 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_KEY=sk-... # 用于install.md生成器的AI合成功能 GITHUB_TOKEN=ghp_... # 用于提高GitHub API速率限制或访问私有仓库 # 性能与资源控制 RATE_LIMIT_REQUESTS=100 # 每个时间窗口内每个IP的最大请求数 RATE_LIMIT_WINDOW_MS=60000 # 时间窗口长度（毫秒），默认1分钟 CACHE_TTL=3600 # 提取结果的缓存时间（秒），减轻源站压力 MAX_CONTENT_LENGTH=5000000 # 单个页面最大处理内容长度（字节），防止内存溢出 # 安全与管理 ADMIN_KEY=your-secret-key # 管理API的密钥，用于清理缓存等操作 ALLOWED_DOMAINS=* # 允许提取的域名，可设置为特定域名列表以提高安全性

配置建议：

• ANTHROPIC_API_KEY：如果你计划频繁使用install.md生成器，这是必选项。否则该功能将不可用或降级为简单提取。
• RATE_LIMIT_*：在生产环境中，务必根据你的服务器性能和预期流量设置合理的限流值，防止恶意爬取或意外过载。
• ALLOWED_DOMAINS：在内部部署中，可以将其设置为公司内部的文档域名，将其变成一个内部知识提取工具，避免被滥用。

4.3 生产环境部署

项目基于Next.js，可以轻松部署到Vercel（原作者的选择）、Netlify、AWS等平台。

以Vercel为例：

1. 将你的仓库导入Vercel。
2. 在项目设置中，配置上述环境变量。
3. Vercel会自动识别为Next.js项目并完成构建部署。

构建与优化：

# 构建生产版本 pnpm build # 预览生产构建 pnpm start # 运行测试套件（项目包含163个测试） pnpm test # 生成测试覆盖率报告 pnpm test:coverage

在部署前，运行pnpm build和pnpm test是良好的习惯，确保代码质量和功能正常。

5. 高级应用场景与避坑指南

掌握了基本用法后，我们可以探索一些更高级的应用模式，并分享一些实践中容易遇到的问题。

5.1 构建自动化的RAG文档管道

假设你正在为公司内部构建一个AI问答助手，需要集成多个内部技术栈的文档。

传统做法：手动维护一个文档列表，定期用爬虫抓取，然后清洗、分割、向量化。过程繁琐，且文档更新不同步。

使用llm.energy的优化方案：

1. 清单管理：创建一个YAML文件（如docs-sources.yaml），列出所有需要集成的内部文档站地址。
2. 定时提取：编写一个简单的脚本（如Python或Node.js），定期（例如每天）调用llm.energy的批量API (/api/batch) 处理清单中的所有URL。
3. 结构化存储：将API返回的JSON结果（已按章节分割好的Markdown）存储下来。
4. 向量化与更新：将这些结构化的文本块送入你的向量数据库（如Chroma, Weaviate, Pinecone）进行嵌入（Embedding）。由于llm.energy已经做了清洗和分割，这一步的质量和效率会高很多。
5. 自动化：将整个流程封装成GitHub Action或CI/CD流水线，实现全自动的文档同步。

优势：文档更新及时，内容干净结构化，减少了大量数据预处理工作，让RAG系统能基于更高质量的上下文给出答案。

5.2 为开源项目添加AI原生支持

如果你是一个开源项目的维护者，让项目对AI更友好能极大地提升其易用性和采用度。

行动步骤：

1. 生成llms.txt：使用llm.energy网站上的生成器向导。你需要准备项目的简短描述、主要功能、API端点（如果有）、使用示例、获取帮助的渠道（如Discord链接、问题模板地址）等信息。生成后，将文件保存为.well-known/llms.txt并提交到仓库根目录。
2. 生成或编写install.md：如果你的项目安装过程简单，可以手动编写。如果复杂，可以先用llm.energy的AI生成器基于你的GitHub仓库生成一个初稿，然后在此基础上修改和完善。确保步骤清晰、命令准确、包含了所有常见的环境配置和故障排查点。
3. 提交与验证：将这两个文件推送到仓库后，可以立即用llm.energy验证你的网站（如果文档已部署）或仓库的GitHub Pages地址，看是否能被正确提取。

这样做的好处：你的项目会出现在llm.energy的站点目录中，更容易被其他开发者发现。更重要的是，任何集成了llm.energyMCP工具的AI助手（如未来团队内部的Claude）都能以最标准、最准确的方式获取你的项目信息，降低支持成本。

5.3 常见问题与排查技巧

在实际使用中，你可能会遇到以下问题：

一个重要的心得：llm.energy在遇到标准文件时表现最佳。因此，最大的“避坑”技巧其实是主动推动生态建设。当你发现一个优秀的项目但没有llms.txt时，可以友好地提一个Issue或PR，建议他们添加，并附上llm.energy生成器的链接。众人拾柴火焰高，当支持标准的网站越来越多时，这个工具的价值才会指数级增长。

这个项目代表了一种趋势：开发者工具正在从“为人服务”向“为AI与人共同服务”演进。它可能不是终点，但它清晰地指出了一个方向——通过标准化和工具化，让AI更可靠、更高效地接入人类的知识体系。无论是将其作为一次性文档提取工具，还是作为自动化管道的关键组件，亦或是通过MCP深度融入你的AI开发流，llm.energy都提供了一个坚实且思路清晰的起点。