企业官网建设流程全解析

本文基于 XERJ 仓库中 2026-09-18 完成的一项系统性研究（docs/research/llms-txt-2026-09/README.md）展开：它盘点了 46 个知名项目的llms.txt/llms-full.txt/AGENTS.md/SKILL.md等面向 AI Agent 的文件，并对照 XERJ 自己发布在https://xerj.org/llms.txt的文件（研究当日 40,064 字节、234 行），逐行验证出 12 项缺陷。读完后你会掌握三样东西：面向 Agent 的文档（agent-facing docs）应当满足的 12 条硬规则、16 种被反复验证的安装/接入提示模式，以及"为什么要求 Agent 开 PR 收反馈注定收不到"的四条结构性原因——这套方法可以直接迁移到任何产品自己的llms.txt、AGENTS.md与安装文案上。

一、研究方法与可信度边界：先说清哪些数字能信

研究原文开篇即声明"阅读本目录的产物前，先读本节"。方法分三步，全部由 Agent 执行并留痕：

原文对可信度的四条自我限定值得任何同类研究效仿：

1. 每个项目的每个事实都是 2026-09-18 对活 URL 的单次 Agent 抓取，引用为 Agent 返回的原文（verbatim），并非全部独立重抓。维护者用curl抽检 14 条声明：13 条确认，1 条无法判定（检查脚本自身的搜索模式写错了，不是声明错）。5 个文件大小重新测量与解剖记录逐字节吻合（Ollama 1,674 B / 29 行；DuckDB 3,371 / 37；turbopuffer 4,012 / 59；AI SDK 2,217 / 46；XERJ 40,064 / 234）。
2. 对 XERJ 自身文件的每一项缺陷（§三）都在当天对照landing/llms.txt与线上站点人工核验过——那些是事实，不是 Agent 意见。
3. 锚定偏差：每个解剖 Agent 都预先被简报了 XERJ 的已知缺口（无 shell 即失败、lexical 被误读为 neural、"required 却写在 Optional 下"的矛盾），并被告知要对比。因此"46 份解剖里都出现"的批评（如 shell-less 缺口）是简报的回声，不是 46 次独立确认；独立的是每个 Agent 在对方项目文件里找到的引用、大小、片段与 URL。
4. Agent 的推断被自己标记为INFER/INFERENCE，这些标记在产物中全部保留。

此外，Web 是会变的——原文要求任何人对外引用这些数字前重新测量（仓库当前landing/llms.txt已演变为 288 行，其中包含由scripts/seo/build_articles.py生成的 Answers/Comparisons 索引树；研究数字一律对应 2026-09-18 快照）。

二、关键数字：XERJ 的问题不在"文件太大"

以下统计全部由脚本从 data/dissections.json 计算，而非任何人的总结：

完整表格见 comparison-table.md（2026-09-19 又加入 10 个项目后为 56 个、52 个发布 llms.txt，XERJ 排名更新为 53 个中的第 39）。这张表由 scripts/build_tables.py 从两个数据文件机械生成，--check模式会在表与数据不一致时退出 1——"每个单元格都读自记录，没有一个是手打的"。

这组数字最重要的结论：XERJ 的 40 KB 按字节数并不是离群值；真正的离群维度是首屏信息密度、义务性措辞的数量，以及一个文件承担了几种职责。

三、XERJllms.txt的 12 项缺陷（M1–M12，逐条对照文件验证）

以下缺陷的行号均指研究当日landing/llms.txt在 commit4d8dadbf的版本。研究强调这些都是"当天对着文件与线上站点手工验证过的事实"。成文时再次核验了仓库当前状态：M1 与 M4 至今仍在活文件中复现——当前 landing/llms.txt 第 7 行仍有 "required, not optional"，## Optional标题仍在（第 277 行），全文仍无claude mcp add/mcpServers片段；其余条目以研究记录为准。

结构类缺陷

M1 — 一条"义务"，被自己的位置否定。第 7 行称 field report 是 "required, not optional"，但它指向的模板放在名为## Optional的标题（第 223 行）之下，正文还说"模板在 Optional 下"。在 llms.txt 惯例里，## Optional的语义是上下文不够长就跳过这段——会做裁剪的 Agent 会连同义务一起丢掉。Vercel 的## Optional只放 Agent 可以忽略的机器目录，才是该惯例的本意。同一措辞也出现在 AGENTS.md 的第二个标题 "If you used XERJ, you owe it a field report"——两处必须一起改。

M7 — 一个文件干了四份活。索引、安装指南、注意事项、贡献协议挤在一个文档里。别处的模式是：一份短的手写简报、一份生成的索引、一份全量 dump，各用一句话声明自己的职责（Deno：四个文件、每个一行角色；Turso、Typesense、Upstash、Exa、Zed、ParadeDB：两层结构）。对 Agent 的硬规则应放在 Agent加载它的地方——SKILL.md或agents.md——而不是索引里（CrewAI 把 "MANDATORY WORKFLOW … This isnot optional" 放在 skill 内部）。

M6 — 首屏密度 + 编号缺陷。最长单行 1,124 字符；curl行与 step 1 之间约有 1,500 字符的校验工具、安装目录与 PATH 说明。"First run" 列表里有两条都编号为4.（查询步骤与 field-report 步骤）。问题不是文件总大小（见 §二），而是"每个 Agent 都会读的那部分"每行的散文长度。

可发现性与验证类缺陷

M3 — 从第 1 行起假设存在 shell。curl -fsSL https://xerj.org/get | sh是第一条指令；无 shell 的路径只是二十个链接中的一个。此前的 22 次首跑 Agent 研究（2026-08-12，基线见 demo/playbooks/AGENT_FTX_HARNESS.md）已经证明无 shell 人设在每一档模型上都失败。本研究中所有强的文件都以"能力分支"开头——AI SDK："If you can fetch URLs, search the docs first … If you are working inside a local coding project with filesystem access, install the AI SDK skill first"。

M4 — MCP 不可发现。全文 0 次出现claude mcp add、mcpServers或任何客户端配置 JSON。xerj init被标为 "(optional, one command)" 的第 3 步，xerj mcp只出现在## Optional最后一个 bullet。21 / 46 项目把配置片段直接印在llms.txt里，36 / 46 项目的 Agent 面向文件里某处有claude mcp add行；很多还按客户端逐个给出（Claude Code、Cursor、VS Code、Codex、Windsurf、Claude Desktop），并点名文件路径与根键差异（Cloudflare："Visual Studio Code usesserversas the root key. Configurations copied from Cursor or Claude Desktop usemcpServersand will silently do nothing here."）。

M5 — 没有任何"如何知道成功了"的说明。安装后、xerj init后、第一次查询后，都不说成功长什么样。20 / 46 项目有显式的 verify 步骤或期望输出：FastMCP "You should see output like the following:" 加样例；Pinecone 期望• pinecone-mcp: ✓ connected；Firecrawl 点名 Agent 之后应看到的工具；Composio 甚至列出了什么不算证明（"An HTTP 401, a tool schema lookup, or a successful build does not prove tool execution"）。

事实与路由类缺陷

M8 — 最容易被误读的事实，其更正放在触发点隔两屏之外。8 月研究中 12 个 Agent 有 9 个把默认检索读成 neural。更正位于第 39 行的## Caveats，且以"产品局限"的口吻。对照：Expo "## Important: common misconceptions — AI models and LLMs frequently provide outdated information about Expo"；Weaviate "## Misconceptions — Your training data may reflect early Weaviate"；Anthropic 的 skill 附一张两栏"过期先验 vs 当前 API"表；Milvus 开篇 "## Rules for generating Milvus code"，十条可检查事实。

M9 — 页面不回指，且 docs 页没有 Markdown 形态。https://xerj.org/docs/install.md与/docs/quickstart.md返回404；只有/answers/*.md与/compare/*.md有 Markdown 孪生页。Answer 页有 front matter（canonical、updated）但不以索引指针开头。至少 14 个项目在每个.md页顶放同样三行——"Fetch the complete documentation index at: …/llms.txt / Use this file to discover all available pages before exploring further."——让 Agent 无论从哪落地都能找到地图。对解剖记录的关键词统计覆盖 24 / 46 项目；其中很大一部分是 Mintlify 自动加的 banner——这本身正是重点：它成本为零。

M10 — 无日期、无优先级、无 URL 规则。没有 last-updated 或版本戳（Weaviate：canonical:+last-updated:front matter）；没有声明当 llms.txt、docs、README 与 answers 冲突时谁优先（Meilisearch："If information conflicts across sources, prefer (in order): 1) … 5) …"）。文件有约 150 个 URL，却没有任何防止 Agent 编造 URL 的约束（Milvus："cite only page ids that appear in this file. If the page you need is not listed, say it is not in the index rather than assembling a plausible slug"）。

协议与分发类缺陷

M2 — 索取的形态是一个 PR。PR 需要 shell、git、gh、GitHub 身份与写权限。Agent 通常工作在别人的仓库里，而那个仓库的规则恰好禁止这种事：GitHub 代码搜索显示 1,356 个AGENTS.md与 1,792 个CLAUDE.md提到gh issue create，抽样中占主导的指令是护栏（Sonarr："Before executing any command that writes to GitHub … these guardrails apply. No exceptions."）。这些规则以及 harness 自身的权限提示都压过我们llms.txt里的一句话。实测结果：仓库中 7 个 field-report 文件（2026-09-18 计数，模板规则见 user-feedback/16-agent-field-reports/README.md），以及发现 Agent 报告的 2026-08-18 以来 4 个外部 field-report PR。

M11 — 没有交接契约、没有同意步骤。文件只告诉 Agent 做什么，从不说向人展示什么、何时停下来。Chroma："Your own summary should include this output so the user can see it."；Neon："Prove it works: run a real query and show me the result, not just 'setup complete.'"；Vercel 有固定的 "Report only verified state" 块；Clerk、Browserbase、Deno：先展示清单、等人说 yes 再安装。

M12 — 没有 Agent 原生分发面。xerj.org 上以下路径全部404：/SKILL.md、/skill.md、/agents.md、/llms-install.md、/.well-known/skills/index.json。没有npx skills add路径、没有插件市场清单、没有cursor://或vscode:mcp/install链接。xerj init会写 skill，但前提是二进制已装好，所以它做不了入口（on-ramp）。npx skills add <owner>/<repo>出现在 36 个被探测文件中；"托管SKILL.md+ 七词粘贴提示"（"Read https://browserbase.com/SKILL.md to set up Browserbase"）是本次研究找到的出现最多的安装提示。

四、为什么 field report 收不到：四个结构性原因

这是本次研究被委托要回答的问题，原文"直白地只说一次"：

1. 没有别人这么要。在全部被探测的llms.txt、llms-full.txt、agents.md、SKILL.md中，没有任何项目要求 Agent 回报使用反馈，也没有任何项目把反馈框定为"欠债"。最强文件里的语气都是程序性的、不索取的。
2. 通道与执行者不匹配。真正批量收到 Agent 反馈的项目，用的是不需要 git、CLA、GitHub 身份的通道：
   • 产品内工具——Claude CodeSendFeedback（由失败而非会话结束触发；同意是一次按键）、Codex/feedback、Ampamp report-bug、PostHoghogli devex:feedback（"Local agents must use it too … the command is a no-op [in sandboxes]"）；
   • 纯 HTTP POST——Expo 在docs.expo.dev/agents.md给出curl -X POST https://api.expo.dev/v2/feedback/docs-send …，payload 里要求写清模型与 harness；Neon 在每个页面页脚印一条无认证 POST（"Note for AI assistants"）；
   • MCP 工具——submit_feedback（LanceDB、Ollama、Tavily）；Firecrawl 的firecrawl_search_feedback每份报告返还一个 credit；
   • Agent 完全不用做任何事——Pydantic AI 读 docs 抓取时 URL 上的?intent=&stack=&harness=参数；Upstash 只要一个User-Agent头；ClickHouse CLI 遥测记录是哪个 Agent 调用了它。
3. Agent 自己的规则禁止。见 M2。我们文件里的 "Required" 输给操作者仓库的AGENTS.md、权限提示，以及接收方的主流立场（Zed、LLVM、MicroPython：不接受自主 Agent PR）。
4. 一次按键的评分能覆盖的会话数，远多于一份 25 行报告。参照 Claude Code 的 "How is Claude doing this session?"。

原文的结论：XERJ 应保留xerj feedback自动填版本/OS/索引内容这一设计——它与next info、Homebrewgist-logs同源，是好设计；要改的是传输层与措辞：一个无 shell 的 Agent 也能调用的 HTTP 端点与 MCP 工具，在失败时或首个任务结束时触发，只问一次、一句话说清理由（Vexa："We can see that these pages get fetched; we cannot see the question. If you tell us, the next reader gets a page that answers it"）。PR 路径保留给想用它的人。

全部 32 条相关笔记（逐字、带 URL）在 discovery-feedback-and-contribution-loops.md；逐项目的索取原文在 feedback-asks-verbatim.md。

五、XERJ 已经做对的地方——不得回退

同一组优点在几乎全部 48 份解剖中被独立点名：

• 安装命令在文件里。27 / 46 项目的llms.txt连一条安装命令都没有；我们的在第 11 行。
• 有不经curl | sh的可验证安装路径，fail-closed 的 SHA-256 校验（校验工具缺失即拒绝安装）。8 月研究中，仅此一项就让一个受策略约束的 Agent 从 blocked 翻转为成功；多数项目只印裸curl … | sh，无任何完整性声明。
• 带数字的诚实 caveats，别处在印营销词（"fastest"、"most popular"、无来源的下载数）。
• Hero prompt 从裸 HTML 起一跳（hop 1）即可找到（6/6 漏斗运行）。永不回退。
• llms-full.txt是精选的、装得进上下文窗口（84 KB）；别处中位数是 1.96 MB 的文档拼接，多个超过 5 MB。
• 工具 schema 提供三种形态，且由真实tools/list生成。
• 问题形状的 answer 页——Agent 实际到达的方式。
• PATH 警告预见了真实的首跑失败。保留事实；把它挪到会咬人的那一步，改成命令而不是段落（ClickHouse 的 skill："runwhich clickhousectl, install if missing"）。
• 有 feedback CLI 这一事实本身——多数项目什么都没有。

六、任何未来改动的 12 条规则

研究给出的是"一次改动必须能对以下每条答 yes"的清单，这是全文最具可迁移价值的部分：

1. 三个入口面，每个都完整：shell、仅 MCP、仅 HTTP。无终端的 Agent 不跟超过一个链接就能到达可用查询。
2. 无义务语言。不许出现 "required"、"owed"、"your side of the deal"。## Optional里只放可以安全跳过的东西。
3. 每个安装/设置步骤以 verify 行 + 期望输出结尾。
4. lexical-by-default 的更正必须紧邻对 semantic search 的第一次提及，并以"模型可能持有的先验"来框定。
5. MCP 注册按客户端逐条印出，含文件路径与根键差异（mcpServersvsservers），外加claude mcp add …一行命令。
6. 反馈要有沙箱化、无 shell 的 Agent 也能用的通道（HTTP 或 MCP 工具），只问一次，并说明理由。
7. 首屏散文要短。第一条命令之前，没有超过约 300 字符的行；编号列表编号正确。
8. 文件要声明它是什么、最后更新时间、冲突时哪个来源优先。docs 链接能以 Markdown 解析。
9. 告诉 Agent 完成时向人展示什么、何时先询问。
10. 同一时间只有一个 open PR 编辑landing/llms.txt。多个 feature 分支并发追加行，正是这个文件变成"四合一"的原因。
11. 改动前后对无 shell 人设重跑首跑 Agent harness（demo/playbooks/AGENT_FTX_HARNESS.md）。8 月研究是基线。
12. 先测量，再断言。见 §八。

七、16 种安装提示模式（按出现频率与采用成本排序）

完整逐字示例与 URL 见 discovery-install-prompt-patterns.md；每个项目所有"对 Agent 说话"的段落见 install-prompt-catalogue.md。16 种模式一览：

背景：llms.txt 惯例在 2026-08-10 修订（v2）——路径作用域文件、.md孪生页、通过rel="alternate" type="text/markdown"发现。llms-full.txt不在规范内，它是事实惯例，在不同站点含义不同。

八、研究过程中说错的话：纠错记录

原文认为"过程错误和文件错误一样重要"，专门留了一节：

• "按 40 KB 算我们大概是离群值。"测量前说的，错了。排名 47 个中的第 35。真正的离群维度是首屏密度与文件承担的职责数。
• "llms-install.md是头部项目遵循的惯例。"两个视角互相矛盾，又都在各自范围内为真：Cline 市场里的 MCP server 广泛使用它；被研究的基础设施项目全部没有。不是优先级。
• 探测陷阱：GitBook、Fern、Mintlify 站点会对/AGENTS.md、/llms-install.md、/SKILL.md返回HTTP 200加一个 "Page Not Found" 的 Markdown 正文。状态码不是文件存在的证据——要读正文。研究的事实核查器（scripts/factcheck.py）为此专门实现了soft-404分类。
• 同族的两个更早文档缺陷（来自 8 月研究）：MCP server 有描述却没人收到过；mcp-tools.json过期、只列 6 个工具。面向 Agent 的文档必须从发布物生成、或与发布物对账——这个教训后来落地为 scripts/mcp-schema-check.sh（--write再生、默认门控）与 engine/crates/xerj-mcp/tests/published_schema_drift.rs（schema 漂移即构建失败）两个仓库级守卫。
• 工作流设计：单个综合 Agent 一次性接了全部 52 份结果（约 317k token），跑了数小时，中途两次因账号切换暂停。这个规模的综合应该 map-reduce，结果应随到随写盘，而不是攒到最后一步。

九、重写优先级、提案与两个产品级发现

重写按 8 级优先级排序（每条括注对应缺陷）：

1. 删除义务语言；反馈索取移到首任务末尾；加 HTTP 端点与 MCPfeedback工具。(M1, M2, §四)
2. 用三个能力分支 + 完整的仅 MCP 路径开头；按客户端印出 MCP 注册。(M3, M4)
3. 在安装、xerj init、首次查询之后各加一行带期望输出的 verify。(M5)
4. 顶部放短小的"你大概以为 / 实际如此"块，lexical-by-default 排第一。(M8)
5. 发布https://xerj.org/SKILL.md与七词粘贴提示；加.well-known/skills/index.json。(M12)
6. 每个.md页加三行索引 banner；为/docs/*发布.md孪生页。(M9)
7. 简报与索引分文件；加 last-updated、优先级与 URL 规则；修掉重复的4.。(M6, M7, M10)
8. 给 hero prompt 加交接契约与同意步骤。(M11)

2026-09-19，综合、批评与事实核查三个 pass 收尾，产物在 proposals/：修订版报告（proposals/report.md）、拟议llms.txt（proposals/proposed-llms.txt）、拟议llms-install.md、10 条可粘贴提示、事实核查记录（259 条声明重抓，258 条确认，1 条未确认并被删除），以及一份把提案中印出的全部 XERJ 命令在 Linux 上对xerj v1.0.0-rc.74真实运行、记录字面输出的验证记录（proposals/data/xerj-cli-verification-2026-09-19.md），其中明确列出"未运行"清单（curl | sh安装器、macOS 与 Windows、--embed-mode neural、claude mcp add --scope local与各客户端注册行——后者引自各客户端文档而非执行）。

提案不改动任何活文件：landing/llms.txt、llms-full.txt与AGENTS.md未动，因为上面第 10 条规则适用，且报告列出了任何一条上线前必须先具备的条件。

其中两条发现关于产品而非文案，均复现两次：

• xerj feedback --open-pr会在你当前所在的任何仓库里建分支、提交并推送——这正解释了 M2 的结构性危险，也解释了为什么它不配作为"必选项"；
• xerj init写出的 MCP 条目不带XERJ_AUTH，而对默认（开认证）节点，每个工具调用都返回 401。

另外，2026-09-19 给对比表补了 10 个项目（6 个报告引用过但未列表的、4 个本地代码搜索同行），总数到 56；这 4 个本地同行（Lucene、Quickwit 一类）全部不发布llms.txt——它们的 Agent 接入面就是 README。

十、仓库中如何继续深入

这份研究在仓库里的制度化方式本身也值得一看：AGENTS.md 设有专门的 "Before you touchllms.txt, install text, or a feedback ask" 一节，明确要求任何要动 Agent 面向文件的人先读本报告，并复述其核心结论——"12 条已验证缺陷、为什么以 PR 索取 field report 收不到、以及一次改动必须满足的 12 条规则"，同时重申"同一时间只有一个 open PR 编辑landing/llms.txt"。这就是研究文档的终极形态：不只是结论，还是一套防同一错误发生两次的流程。