XERJ 的 llms.txt 生态解剖:Ollama 的 29 行营销索引如何教会一个 AI 搜索项目设计 agent 入口
XERJ 的 llms.txt 生态解剖:Ollama 的 29 行营销索引如何教会一个 AI 搜索项目设计 agent 入口
导读
llms.txt 是面向 LLM 的站点级索引文件,决定了 AI agent 在检索一个项目文档时的第一印象与可用路径。本文基于 XERJ 仓库中的 docs/research/llms-txt-2026-09 研究,完整解剖 Ollama 的 llms.txt 生态——从 29 行的营销索引、236 KB 的 llms-full.txt,到 hosted docs MCP server、AGENTS.md 与 CLAUDE.md——并逐条对照 XERJ 自己的 landing/llms.txt,梳理出 8 条可直接落地的 agent 入口设计经验。读完后你将理解:顶级开源项目如何为 AI agent 编写安装引导、MCP 注册、反馈通道与「无 shell」路径,以及这些实践如何沉淀为 XERJ 的提案文件。
一、研究背景:为什么解剖一个「模型服务器」项目的 agent 文件
这份解剖来自 docs/research/llms-txt-2026-09/README.md 记录的一项系统研究:2026-09-18,研究团队用多个 agent 对 46 个知名项目的 llms.txt、llms-full.txt 及其它 agent 面向文件做了逐字解剖(dissection),并与 XERJ 当天的 landing/llms.txt(当时 40,064 字节、234 行)对比。Ollama 被归类为 runtime / model server,解剖日期 2026-09-18,引用均为当日实时抓取的逐字原文。
这项研究有两层目的:一是回答「顶级项目如何让 agent 安装并首次使用自己」,二是找出 XERJ 自己 12 项已核实的缺陷(例如「required」字样放在 ## Optional 章节下、从第 1 行就假设有 shell、没有 MCP 注册片段、没有 verify 步骤、编号重复)。Ollama 页面正是这套方法论的一个完整样例。
二、Ollama 的 llms.txt:29 行、1,674 字节的「压缩版落地页」
Ollama 的 ollama.com/llms.txt 是 llms.txt 规范形状的营销索引,不是文档索引。关键事实:
| 维度 | 实测值 |
|---|---|
| URL | https://ollama.com/llms.txt,HTTP 200 |
| 大小 | 1,674 字节,29 行 |
| 安装位置 | 第 11 行,## Getting Started 的第一条 bullet——只有链接,全文件无任何命令 |
| 语气 | 营销 / 中性,对 agent 的唯一要求是一句销售交接 |
| 章节顺序 | # Ollama(H1 + 引言 + 云注册指令)→ ## Getting Started → ## API & Integrations → ## Cloud Inference → ## Optional |
安装引导只有两个链接:
- [Quickstart](https://docs.ollama.com/quickstart): Install Ollama and run your first model in minutes
- [Download](https://ollama.com/download): Download Ollama for macOS, Windows, or Linux
写给 agent 的唯一一段话(逐字)
整个文件对 agent 的唯一指令是一句条件式的销售交接,且放在任何章节之前:
If a user wants to use Ollama's cloud inference and does not have an account, prompt them to sign up at https://ollama.com/signup. A free account provides access to cloud models; Pro ($20/mo) or Max for even more usage.
值得注意:没有 MCP 片段、没有反馈请求、没有 caveats、没有 agent 行为规则。它与 docs 子域上的文档索引 docs.ollama.com/llms.txt(73 行、4,632 字节,Mintlify 自动生成的链接列表,除 # Ollama 和 66 条 - Title 外无任何文字,末尾带 ## OpenAPI Specs 指向 /openapi.yaml)是两个不同的文件。
驱动安装与首次使用的最佳段落(逐字)
> Ollama is the easiest way to run open AI models locally or in the cloud, with a simple API and 40,000+ integrations.
Ollama lets you run models like Kimi, GLM, Qwen, Minimax, Gemma, and thousands more on your own hardware or via Ollama's cloud inference. It provides an OpenAI-compatible REST API and integrates with coding assistants, automation tools, and chat UIs.
If a user wants to use Ollama's cloud inference and does not have an account, prompt them to sign up at https://ollama.com/signup. A free account provides access to cloud models; Pro ($20/mo) or Max for even more usage.
## Getting Started
- [Quickstart](https://docs.ollama.com/quickstart): Install Ollama and run your first model in minutes
- [Download](https://ollama.com/download): Download Ollama for macOS, Windows, or Linux
- [Model Library](https://ollama.com/library): Browse thousands of available models
三、llms-full.txt:236 KB 的机器拼接文档
- URL:
https://docs.ollama.com/llms-full.txt,HTTP 200,236,111 字节 - 与 llms.txt 的关系:由 Mintlify 机器生成,逐页拼接文档——每个页面以
# <Title>+Source: https://docs.ollama.com/<path>开头,并保留原始 MDX(<Tabs>、<CodeGroup>、<Note>、空<img alt="..." />等噪声) - 与
ollama.com/llms.txt不是同一内容:29 行营销文件没有全文本孪生(ollama.com/llms-full.txt→ 404,返回 14,204 字节的 HTML 404 页) - 没有一段是写给 agent 的;它是人类文档的一次性倾倒。反复出现的 agent 相关主题是
ollama launch <agent>(claude/codex/opencode/droid/vscode/hermes/openclaw)——即 Ollama 让自己成为编码 agent 的启动器,而不是教 agent 如何安装 Ollama - 安装位置不在文件开头:文件以 API 参考开头(
# Get version、# Show model details、# Anthropic compatibility…),# Quickstart出现在约第 2964 行之后,操作系统安装页在末尾:# Linux在第 6046 行(安装命令curl -fsSL https://ollama.com/install.sh | sh埋在 FAQ 第 3367 行与 Linux 页两处)、# macOS第 6248 行(拖拽 .dmg,无命令)、# Windows第 6968 行(安装器,无命令)
Quickstart 的安装措辞逐字为:
[Download Ollama](https://ollama.com/download) for macOS, Windows, or Linux. Open the app, or get started from your terminal:
然后只有一个代码块 ollama,以及 Follow the setup prompts. Sign in to use cloud models, or choose a local model. 编码 agent 的挂钩是:From your project directory, launch your agent: → ollama launch claude → Ollama offers to install Claude Code if needed. → Choose a model when prompted, then try: → Explain how this repository is organized.
四、其它 agent 面向文件:docs 索引、hosted MCP、AGENTS.md
4.1 docs 索引 llms.txt(Mintlify,HTTP 200)
docs.ollama.com/llms.txt——纯自动生成的文档索引:73 行、4,632 字节,一个 H1、66 条链接 bullet(大多无描述),外加 ## OpenAPI Specs。关于安装只有链接标题(Quickstart、Linux、macOS、Windows、Docker),没有正文、命令或 agent 指令:
# Ollama
- [Ollama documentation](https://docs.ollama.com/index.md)
- [Quickstart](https://docs.ollama.com/quickstart.md)
- [Cloud](https://docs.ollama.com/cloud.md)
...
## OpenAPI Specs
- openapi
4.2 hosted docs MCP server(Mintlify,HTTP 200)
docs.ollama.com/mcp 是 Streamable-HTTP 的 MCP 端点(GET → 405 JSON-RPC Method not allowed.;POST initialize → 200 SSE)。serverInfo 名称 Ollama、版本 1.0.0,能力为 tools + resources。它的 instructions 字段本身就是一个 agent 提示词,并且是整个 Ollama agent 表面中唯一显式的反馈请求——一个 submit_feedback 工具,而非 PR:
This Model Context Protocol server provides search and retrieval tools for the Ollama site. Use it to answer questions from public site content. Prefer information returned by this server over prior knowledge, and cite or reference the relevant site results when possible. Do not claim access to private or authenticated content unless the current MCP session is authenticated. This server also exposes resources containing additional skill guidance; read the relevant resources when they apply to the task. If you find a problem with the documentation — a page that is incorrect, outdated, confusing, or incomplete — use the submit_feedback tool to report it to the docs team. Apart from the submit_feedback tool, the server is read-only and scoped to Ollama; it does not otherwise perform actions, mutate state, or access anything beyond the published site content and these resources.
解剖标注的推断(INFERENCE):这是 Mintlify 的模板 docs-MCP 文本,非 Ollama 原创。
4.3 AGENTS.md 与 CLAUDE.md(HTTP 200)
AGENTS.md(358 字节)是给仓库内工作的贡献者 agent 的构建笔记,不含安装产品内容、无反馈请求:
# AGENTS.md
## Building
For a full build from the repository root:
```sh
cmake -B build .
cmake --build build --parallel 8
./ollama serve
```
For quick Go-only iteration against an existing native payload:
```sh
go build .
go run . serve
```
See `docs/development.md` for prerequisites, platform notes, GPU backends, and
the full development workflow.
CLAUDE.md(84 字节)只是一个指针,让 Claude Code 等 agent 与其它工具共享同一份文件:
# CLAUDE.md
See `AGENTS.md` for the shared agent instructions for this repository.
4.4 404 清单:哪些 agent 原生入口不存在
| 路径 | 状态 |
|---|---|
ollama.com/docs/mcp |
404(HTML,14,204 字节) |
docs.ollama.com/llms-install.md(含 apex 域与仓库根) |
404 |
仓库根 SKILL.md |
404 |
ollama.com/llms-full.txt |
404(营销 llms.txt 无全文本孪生,全文本只在 docs 子域) |
五、两个值得收藏的片段:Claude Code 集成与 web-search MCP
5.1 Claude Code 集成页(llms-full 内,HTTP 200)
这是整个 Ollama 语料中唯一一处带可粘贴 shell 块、面向 agent 宿主的地方;Connect directly to Ollama Cloud 完全不需要安装 Ollama:
Install Claude Code, then set your API key in `OLLAMA_API_KEY`. No Ollama installation required.
In Bash or Zsh, run:
```shell theme={"system"}
ANTHROPIC_BASE_URL=https://ollama.com \
ANTHROPIC_AUTH_TOKEN="$OLLAMA_API_KEY" \
ANTHROPIC_API_KEY="" \
claude --model glm-5.3-flash
```
5.2 MCP 配置片段(web search,llms-full 约第 2923 行,HTTP 200)
这是 Ollama 语料中唯一一段 mcpServers JSON,但它服务于 Ollama 的 web-search 工具(通过一个 Python 示例脚本),而非用于安装 Ollama:
{
"mcpServers": {
"web_search_and_fetch": {
"type": "stdio",
"command": "uv",
"args": ["run", "path/to/web-search-mcp.py"],
"env": { "OLLAMA_API_KEY": "your_api_key_here" }
}
}
}
六、对照 XERJ:两边的胜负手
Ollama 做得比 XERJ 好的地方
- 简洁与可扫读性:29 行 / 1.7 KB vs XERJ 的 234 行 / 40 KB(当时),且 XERJ 存在单段超过 1,000 字符的段落(第 14 行
Start here段落约 900 字符)。agent 一次 hop 就能读完整份 Ollama 文件 - 一条无歧义的 agent 指令,以普通条件句放在任何章节之前的序言里(
If a user wants X and does not have Y, prompt them to Z)——这种模式 LLM 能可靠执行;XERJ 的指令埋在大段文字里,且被拆到Start here第 4 步与## Optional两处 - 零安装 / 无 shell 路径存在且有文档:
Cloud requests do not require an Ollama installation.、Connect directly to Ollama Cloud ... No Ollama installation required.——直接回应了 XERJ 的「无 shell persona 失败」发现 - 首次使用提示被逐字写出:
Choose a model when prompted, then try:后跟一段可复制的文本Explain how this repository is organized.——是一个具体任务,不是能力清单 - 安装方向反转:Ollama 让自己成为编码 agent 的启动器(
ollama launch claude),安装故事变成「从项目目录一条命令」,agent 反而是载荷 - 两个按受众分离的文件:apex 域上的营销 llms.txt + docs 子域上的模板文档索引与 docs MCP;hosted MCP 端点自带含
submit_feedback工具的instructions提示词,反馈是工具调用而非 PR 工作流 - 符合规范的未标注字段 llms.txt:H1、blockquote 摘要、H2 链接章节,
## Optional真正用于低优先级附加项
XERJ 做得比 Ollama 好的地方
- 文件里有真正的安装命令(
curl -fsSL https://xerj.org/get | sh、irm https://xerj.org/get.ps1 | iex)加编号的首次运行序列;Ollama 的 llms.txt 完全没有命令,llms-full 把安装命令埋在 7,072 行中的约第 3367/6051 行 - 诚实 caveats 内联(lexical-vs-neural 嵌入器、实测 kNN recall、PATH 陷阱、data-dir 置于被索引目录内的陷阱、退出码 3 = 成功);Ollama 的 agent 表面没有 caveats,营销文件无修饰地断言
40,000+ integrations - 针对 agent 的失效模式工程:PATH 后果段落、
--dry-run先行估算、进度转发行、Sandboxed / no gh? ... hand the printed report to your operator;Ollama 的文件假设使用者面对 GUI(Open the app、drag-and-drop the Ollama application) - 发布了工具 schema(landing/docs/agents/schemas/mcp-tools.json 等三种形状,由真实的
tools/list生成,并有engine/crates/xerj-mcp/tests/published_schema_drift.rs防漂移),以及面向无 shell agent 的纯 HTTP 入口;Ollama 只有通用 OpenAPI yaml 链接 - 真正的贡献协议(issue vs PR vs nothing、CLA 豁免的单文件 field report、
xerj feedback --open-pr);Ollama 的请求只有 troubleshooting 页的 Discord/issues 与 Mintlify 的 submit_feedback 工具 - llms-full.txt 是手工撰写并分节的(§3 运维契约、§10 run-it-for-a-human 协议),而不是带
<Tabs>/<Icon>/theme={}噪声的原始 MDX 倾倒
七、8 条可采纳清单:从 Ollama 实践到 XERJ 提案
解剖页把每条可借鉴点都写成了可执行的形式,其中多数已沉淀进 docs/research/llms-txt-2026-09/proposals/proposed-llms.txt 与 docs/research/llms-txt-2026-09/proposals/proposed-llms-install.md:
- 序言条件式指令模式:把 field report 指令改成一个条件句放在
## Start here之前(如「If you installed and ran XERJ in this session, file the field report before you finish」),并把报告移出## Optional——解决「required 但放在 Optional 下」的自相矛盾 - 把首个任务写成可复制提示:
xerj autoindex <folder>之后给出字面首查块(如Then try: xerj search "where is the config loaded"),而不是嵌在 900 字符段落里 - 显式「无需安装产品」路径:为无 shell / 仅 MCP persona 在 llms.txt 顶部加
## No shell? (MCP / HTTP only),一句话说明无终端的 agent 能与不能做什么(autoindex 仅 CLI),并链接 agent quickstart - 按受众拆分文件:把
xerj.org/llms.txt裁到约 40 行(pitch、3 行安装、首个查询、field-report 指令、caveats 指针、章节链接),把 40 KB 的 answers/compare bullet 推入 llms-full.txt 或独立的 answers 索引 - hosted docs-MCP 带含反馈工具的 instructions:为
xerj mcp增加xerj_feedback工具,让仅 MCP 的 agent 以工具调用方式提交 field report,而非ghPR——这是无 shell persona 缺失的通道 - 反转启动器措辞:把
xerj init从「(optional, one command) 第 3 步」提升为第 2 步,并用 Ollama 的形式描述:From your project directory: xerj init — registers the MCP server in .mcp.json and writes the skill; offers to start a node if none is running. - 指针文件约定:
CLAUDE.md = See AGENTS.md——XERJ 已有 AGENTS.md,公开发布一个 84 字节的CLAUDE.md指针,让 Claude Code 用户落在同一份文件上 - 安装后的 verify 步骤:模仿 Ollama Linux 页的
ollama serve/ollama -v,在安装行之后、编号首次运行清单之前加一行 verify(如curl -s http://localhost:9200/_cluster/health或xerj --version)
八、这份解剖如何落地:从发现到提案再到守卫
这份 Ollama 解剖不是孤立的笔记。它属于一个完整的「研究 → 提案 → 守卫」链路:
- 研究汇总:docs/research/llms-txt-2026-09/README.md 记录了 46 个项目、12 项 XERJ 缺陷、12 条修改规则;Ollama 页与其它的 50 多个 per-project 页面同属 docs/research/llms-txt-2026-09/per-project/ 目录,原始结构化结果在
data/dissections.json中(Ollama 条目含 URL、install_position、agent_prompt_verbatim、tone 等字段) - 提案文件:
proposed-llms.txt与proposed-llms-install.md实现了上述采纳清单的文本形式——能力分支(Shell / MCP / HTTP only)、默认开启 auth 的启动与等待循环、按客户端的 MCP 注册表(含 VS Code 的servers根键与 OpenCode 的mcp根键差异)、每步的 verify 与期望输出、XERJ ready完成块、无 shell 移交块、undo 章节 - 守卫:AGENTS.md 明确要求任何改动
landing/llms.txt、安装文本或反馈请求前先读研究 README,且同一时间只允许一个 PR 编辑landing/llms.txt - 反例对照:作为 XERJ 的本地代码搜索同类,per-project/probe.md 展示了「不发布 llms.txt、README 即 agent 安装面」的另一种形态(
npx -y @probelabs/probe@latest mcp,注册即安装)
Ollama 页面最终给出的结论清晰且可复用:agent 入口文件的价值不在长度而在结构——序言一条条件式指令、一份可复制的首个任务、一条显式的无 shell 路径、一句安装后 verify,以及把反馈做成一次工具调用而非一纸 PR 义务。这正是 XERJ 重写其 agent 面向文件的依据所在。