ParadeDB 的 llms.txt 解剖报告:从 131 行纯索引到一条命令装进 76 个 Agent

原创2026-10-17 14:01:101,829 阅读
文章标签:人工智能搜索引擎本地部署后端MCP 服务

ParadeDB 的 llms.txt 解剖报告:从 131 行纯索引到一条命令装进 76 个 Agent

本文是 XERJ 团队在 2026-09-18 发起的"46 个顶级项目的 llms.txt 解剖研究"中关于 ParadeDB(Postgres 搜索引擎扩展)的单项目实录,逐字摘录了其 llms.txt、llms-full.txt 及 agent-skills 仓库中的安装命令、Agent 定向文本、MCP 端点与反馈索取方式,并与 XERJ 自身的 agent-facing 文件做了双向对照。读完本文,你将掌握 ParadeDB 的 agent 接入设计全貌(一条 npx skills add 命令、约 100 行的 SKILL.md 契约、受限 docs-fetch 脚本、两层 llms.txt 结构),以及这些模式对本地二进制工具在安装、MCP 注册、反馈渠道上的具体可借鉴之处。

一、解剖对象:一个藏在 Postgres 里的搜索引擎

ParadeDB 是搜索引擎领域的 Postgres 扩展(原文分类为 "search engine (Postgres extension)"),其文档体系由 Mintlify 自动生成。本次解剖发生在 2026-09-18,由一个 agent pass 抓取下列线上 URL 完成,所有引文均为原文逐字返回,未经独立复核(独立复核的范围见 docs/research/llms-txt-2026-09/README.md 的方法论说明):

  • 文档索引 https://www.paradedb.com/docs/llms.txt(docs.paradedb.com/llms.txt 301 重定向至此),HTTP 200,18,336 字节 / 131 行;
  • 全量文档拼接 https://www.paradedb.com/docs/llms-full.txt,HTTP 200,680,006 字节;
  • 营销站根级 https://www.paradedb.com/llms.txt(8,323 B,手写),与其 llms-full.txt(444,921 B / 6,614 行:博客 + 客户故事 + 学习文章)是另一套文件;
  • 面向 agent 的安装页 ai-agents.md、agent-skills 仓库的 README.md / SKILL.md / EXAMPLES.md;
  • 两个 MCP 端点 https://www.paradedb.com/docs/mcp 与 https://www.paradedb.com/mcp,均返回 HTTP 405(协议端点,仅接受 POST,无人类可读页面、无公开的客户端配置 JSON)。

有趣的是:ParadeDB 主仓库(paradedb/paradedb)的根目录不存在 AGENTS.md、CLAUDE.md、llms.txt、.cursorrules、llms-install.md(全部 HTTP 404)——它的 agent 层全部放在独立的 agent-skills 仓库和文档站上,而非主仓库。

二、llms.txt:131 行、18 KB 的"纯索引"

ParadeDB 的 llms.txt 是整个解剖中最典型的 Mintlify 自动生成索引:单一 H1(# ParadeDB),无任何 H2 小节,一个扁平的项目符号列表,共 129 个 标题: 一句话描述 链接,每个页面一句描述,无内联正文。

2.1 隐式的章节顺序

列表虽然扁平,但隐含顺序就是 Mintlify 站点导航:

  1. Start:Welcome、vs. Alternatives、Install、Connect Your App、Create Your First Index、Run Queries、Load Data、Integrate with AI、Go to Production;
  2. Reference:indexing、tokenizers、token filters、full-text queries、filtering、vector、hybrid、aggregates、joins、operators、configuration、SQL functions;
  3. Concepts:Architecture、Guarantees、How the Index Works、text/vector/hybrid、Limitations;
  4. Operate:deploy(extension/Kubernetes/Railway/Render/Fly/DigitalOcean/Dokku)、logical replication、HA、BYOC、Enterprise、maintenance、tuning、upgrading、CI;
  5. Project:Roadmap、Changelog ×5、Help and Support。

2.2 安装位置:一行链接,零命令

llms.txt 第 5 行(131 行中的第 3 个项目符号)是唯一的安装入口,只给链接、不给命令:

- [Install ParadeDB](https://www.paradedb.com/docs/start/install.md): How to run the ParadeDB Docker image

真正的安装命令藏在链接背后的 install.md 里,本次解剖将其挖了出来:

docker run \
  --name paradedb \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_DB=mydatabase \
  -v paradedb_data:/var/lib/postgresql/ \
  -p 5432:5432 \
  -d \
  paradedb/paradedb:latest

以及连接命令:

docker exec -it paradedb psql -U myuser -d mydatabase -W

2.3 语气与 Agent 定向文本:中性、零要求

llms.txt 本身是中性、目录式的:对 agent 不做任何要求,除了一行链接没有任何安装相关内容。全文件唯一的命令式 agent 文本有两处,且都不在 llms.txt 里:

  • 每个链接到的 .md 页面顶部都有同一段三行横幅:

Documentation Index

Fetch the complete documentation index at: https://www.paradedb.com/docs/llms.txt Use this file to discover all available pages before exploring further.

  • agent-skills 仓库的 SKILL.md 是命令式的("always fetch"、"Do not use any tool other than"、"Never silently switch to guessed documentation structure")。

也就是说:ParadeDB 的 llms.txt 不索取任何东西,也不制造任何义务——首次接触的 agent 永远不会被告知它"欠"项目什么。这一点与 XERJ 当时的 llms.txt(称 field report "required, not optional")形成了最强烈的语气对照。

三、llms-full.txt:680 KB 的字母序拼接

ParadeDB 的 llms-full.txt(680,006 B)是 llms.txt 所列每个页面的拼接,每页以 # Title / Source: <url> / description / body 的形式出现(Mintlify 生成,MDX 组件如 <ArchitectureDiagram /> 以字面标签泄漏出来)。关键解剖发现:

  • 页面顺序是文件系统/按目录字母序(concepts、operate/deploy、reference/aggregates……),不是 llms.txt 的策划导航顺序;
  • 安装位置在第 14,253 行(共 18,613 行),docker run 在第 14,266 行——即文件的 77% 处;
  • 文件不是按阅读顺序排列的:以 # Architecture(concepts)开头,# Welcome to ParadeDB 在第 14,292 行(排在 Install 之后),# Integrate with AI 在第 13,291 行。自上而下阅读的首次 agent 会先撞上 13k 行的 aggregates/tokenizer 参考,然后才看到安装命令。

对照之下,XERJ 的 llms-full.txt 是经过策划、按阅读顺序排列的(当时 1,235 行 / 84 KB,正好能放进一个上下文窗口;见 landing/llms-full.txt)。这是两类 llms-full.txt 设计哲学的差异:机器拼接 vs 人工编排。

四、藏在 llms.txt 之外的 agent 层:agent-skills 仓库

ParadeDB 的 llms.txt 里没有 agent 层,但他们确实有 agent 层,只是不在 llms.txt 里——这是本次解剖对既有简报的一个重要修正。

4.1 一条命令装遍所有 agent

来自 ai-agents.md 页(HTTP 200,也逐字出现在 llms-full.txt 第 13,291 行):

Integrate with AI

Teach your coding assistant to use ParadeDB Before getting started, let's give your coding agent full context of ParadeDB by adding the ParadeDB agent skill.

npx skills add paradedb/agent-skills

This installs paradedb-skill into your agent's skills directory (for example, Codex uses $CODEX_HOME/skills/paradedb-skill) and works with all major coding assistants like Claude Code, Cursor, Codex, Windsurf, Gemini, and more.

npx skills add paradedb/agent-skills 一条命令,覆盖 76 个 agent,没有 shell 相关的 PATH 注意事项,没有"你是哪个 agent"的文档内分支——分支逻辑住在安装器里和 README 的 fallback 表里。这正是 Agent Skills 规范(36 个被探测文件都提到它)的推广形态。此外还有 Cursor 市场插件:https://cursor.com/marketplace/parade-db。

4.2 SKILL.md:约 100 行的 agent 契约

SKILL.md(agent-skills 仓库根,HTTP 200)是 ParadeDB 真正的 agent-facing 文档,包含:

  • frontmatter description 触发器,使技能自触发;
  • 版本探测指令:"check first with SELECT extversion FROM pg_extension WHERE extname = 'pg_search';";
  • 命名漂移纠正(USING paradedb 而不是 USING bm25);
  • 6 条响应准则(版本检查 SQL、命名纠正);
  • 强制的网络失败规则——全文约 100 行中最值得抄的部分:

Network Failure Rules (Mandatory)

If any documentation cannot be fetched due to DNS/network/access errors:

  1. State clearly that live docs could not be accessed and include the actual error.
  2. If you have cached session docs from an earlier successful fetch, say that you can continue from that cached copy unless the user wants to stop.
  3. If you do not have cached session docs, ask whether to proceed with local/repo-only context or to retry later.
  4. Do not invent or infer doc URLs, page paths, or feature availability.
  5. Do not present unverified links as real.
  6. Label any fallback statements as assumptions and keep them minimal.

Never silently switch to guessed documentation structure when network access fails.

注意第 4、5 条——禁止发明 URL 和页面路径——与 XERJ llms.txt 里"never invent a number"的诚实规则是同一家族。ParadeDB 把这条规则做成了技能的硬性契约,而非产品文案。

4.3 受限 docs-fetch 脚本:解决沙箱授权难题

README.md(HTTP 200)解释了整个"live docs 而非静态文档"的设计:

Instead of bundling static docs that can become stale, this skill instructs agents to fetch the latest ParadeDB docs to answer your questions. The skill includes a tiny script called scripts/paradedb-docs that allows the agent to fetch only the documentation using curl. This approach ensures the agent sees the full content of docs instead of a summarized view and makes it easy to allow the agent to fetch the docs freely without also granting it unrestricted access to curl.

这个约 5 行的脚本唯一允许的参数是一个 .md/.txt 路径——沙箱 agent 可以自由抓文档,却不被授予无限制的 curl 权限,精准解决了受策略约束 agent 的权限提示问题。这是 XERJ 研究中最被认可的"借力"模式之一。

4.4 EXAMPLES.md:可粘贴的示例提示

EXAMPLES.md(HTTP 200)提供分类的示例提示,人类用户可以粘给已安装技能的 agent,例如:

Getting Started & Setup

What are the ways to index large datasets for search using ParadeDB? What's the quickest way to create a full-text searchable table?

五、MCP 端点与 one-click 链接

  • MCP 端点:https://www.paradedb.com/docs/mcp(ai-agents.md 原文:"This allows MCP-enabled tools to query ParadeDB documentation programmatically and provide contextual assistance.")。经核实,该端点与 https://www.paradedb.com/mcp 均返回 HTTP 405——协议端点,仅 POST,无人类页面、未在任何地方发布客户端配置 JSON 块,整个片段就是端点 URL 本身。README 说明:"The /mcp route is a protocol endpoint, not a human-readable docs page."
  • 营销站根级 llms.txt(手写、与文档索引不同)还提供了另一个 https://www.paradedb.com/mcp(streamable HTTP)指针,并明确声明它不是什么:"This website and its MCP server provide product information, blog posts, customer stories, and learn articles, not a hosted database API." ——这种"它不是什么"的免责声明能防止一整类滥用。
  • One-click 链接:llms.txt 内没有;来自 ai-agents.md 的有 npx skills add paradedb/agent-skills 与 Cursor 市场插件。

六、反馈与贡献:零索取

llms.txt、llms-full.txt、ai-agents 页和 SKILL.md 中没有任何索取 field report、PR、issue 或贡献的内容。链接的 support.md 只提供了企业支持/商业许可的销售邮箱、社区 Slack,以及页面底部的 "Ask a question..." 提问栏。

对照 46 个项目里 23 个有某种反馈/贡献索取的项目(其中没有一个把反馈做成义务),ParadeDB 属于"完全零索取"的阵营。而 XERJ 是被探测项目中唯一一个要求 agent 用后上报的项目——xerj feedback --open-pr 是全场唯一的一键 PR 反馈通道,这也是 XERJ 的反馈瓶颈所在(详见 docs/research/llms-txt-2026-09/proposals/report.md §4:没有别人要求、渠道对执行者不对、agent 自身规则禁止)。

七、双向对照:ParadeDB vs XERJ

本次解剖的每篇 per-project 页都要求同时回答"他们哪里比 XERJ 好"和"XERJ 哪里比他们好"。以下是 docs/research/llms-txt-2026-09/per-project/paradedb.md 的原始结论。

7.1 ParadeDB 做得比 XERJ 好的地方

  1. Agent 接入是一条跨 76 个 agent 的统一命令:npx skills add paradedb/agent-skills——无 shell 相关 PATH 注意事项、无"你是哪个 agent"的文档内分支;分支逻辑在安装器和 README fallback 表里。XERJ 的 xerj init 需要二进制先安装且在 PATH 上。
  2. 他们确实有 agent 层,只是不在 llms.txt:SKILL.md 是紧凑的 ~100 行 agent 契约,含自触发 frontmatter、版本探测、命名漂移纠正、强制网络失败规则。XERJ 当时生成的 10 行技能要薄得多。
  3. live-docs-via-restricted-script 模式:5 行脚本只允许 .md/.txt 路径,解决了沙箱 agent 的 curl 授权问题。
  4. 每个 .md 页面都带同一段三行索引横幅,从任意深页落地的 agent 都会被路由回索引。XERJ 页面不自路由。
  5. 两层 llms.txt:手写的站点根文件负责定位/定价/何时使用,机器生成的文档文件负责参考。根文件明确告诉 agent MCP 服务器不是什么。
  6. Docs MCP 服务器公开且可达(streamable HTTP、无本地进程),正好补上 XERJ 研究发现的 shell-less 人物缺失路径;Cursor 用户还有市场插件。
  7. llms.txt 短(131 行 / 18 KB)且是纯索引:每行标题 + 一句话描述,无内联散文,agent 扫描成本几乎为零。
  8. 语气零要求零义务:首次 agent 永远不会被告知它"欠"什么。

7.2 XERJ 做得比 ParadeDB 好的地方

  1. XERJ 的 llms.txt 把真正的安装命令写在文件里(第 11-12 行:curl -fsSL https://xerj.org/get | sh / irm https://xerj.org/get.ps1 | iex,外加编号的首跑序列;见 landing/llms.txt);ParadeDB 的 llms.txt 只有链接,其 llms-full.txt 把 docker run 埋在 18,613 行的第 14,266 行。
  2. XERJ 的 llms-full.txt 是策划且按阅读顺序排列的(1,235 行 / 84 KB);ParadeDB 的是 680 KB 字母序拼接,以 # Architecture 开头、# Welcome 排在 # Install 之后,自上而下的读者先撞 13k 行 aggregate 参考,且有 MDX 标签(<ArchitectureDiagram />、theme={null})泄漏。
  3. XERJ 有 "Caveats (read before you rely on a capability)" 诚实声明区块(lexical 默认、实测 recall、RSS 规模);ParadeDB 的 llms.txt 完全没有 caveats——"beta" 的向量搜索只在 SKILL.md 准则 6 里披露。
  4. XERJ 发布现成的工具 schema(mcp-tools.json、openai-tools.json、anthropic-tools.json)和面向无 shell agent 的文档化 HTTP-only 路径;ParadeDB 只发布一个无配置片段的 MCP URL。
  5. XERJ 文档化了 PATH 后果、退出码、进度行和先估算后运行协议;ParadeDB 假设 Docker 和一个人在 psql 前。
  6. XERJ 有显式的反馈/贡献渠道和一键 PR(xerj feedback --open-pr)以及缺陷分诊规则(issue vs PR vs 什么都不发);ParadeDB 零索取(只有 Slack + 销售)。

7.3 关键度量对照(来自 docs/research/llms-txt-2026-09/comparison-table.md)

指标 ParadeDB XERJ
llms.txt 大小 18,336 B / 131 行 40,064 B / 234 行
llms-full.txt 大小 680,006 B 83,712 B
安装命令在 llms.txt 内 否(第 5 行只有链接) 是(第 11-12 行)
Agent 定向文本 是(仅每个页面的索引横幅) 是
One-click 链接 3(skill 安装、Cursor 插件等) 0
MCP 片段 是(仅端点 URL,无配置 JSON) 无(当时)
反馈索取 无 是(且是全部 46 个项目中唯一用 PR 形式要求 agent 上报的)

八、可借鉴清单:XERJ 的落地建议

解剖页的第三部分是"Adoptable ideas"——直接可抄的模式,随后已固化进 docs/research/llms-txt-2026-09/proposals/report.md 的优先改动清单:

  1. 在 vercel-labs skills registry 发布 agent skill,让接入成为一条通用命令:复制 ai-agents.md 的措辞("Before getting started, let's give your coding agent full context of XERJ by adding the XERJ agent skill." + npx skills add xerj-org/agent-skills + "works with all major coding assistants like Claude Code, Cursor, Codex, Windsurf, Gemini, and more")。这直接服务 shell-less/策略受限人物:skill 安装不需要 XERJ 在 PATH 上,且可在 skill 内部携带手工验证安装路径。
  2. 在 xerj.org 的每个 .md 页面和 llms-full.txt 顶部放三行自路由横幅,逐字照抄 ParadeDB 模式。
  3. 给 XERJ 的生成 skill 和 llms.txt Caveats 加 "Network Failure Rules (Mandatory)" 块,尤其是第 4-5 条(禁止发明文档 URL、禁止把未验证链接当真),与 XERJ 已有的"never invent a number"配对。
  4. 加版本探测指令:SKILL.md 准则 2 的 XERJ 等价物是"依赖 release-gated flag 前先查 xerj --version / GET /"——这本来能在 9/12 的 8 月研究中抓住"把 lexical 误读成 neural"的 agent(若探测同时打印 embed-mode)。
  5. 在 skill 里带一个受限 docs-fetch 脚本(scripts/xerj-docs <path>.md,只允许访问 xerj.org),让沙箱 agent 无需 blanket curl 权限即可读 llms.txt。
  6. 修复 "required ... under Optional" 的矛盾,反用 ParadeDB 的教训:ParadeDB 什么都不索取,也就什么都不会被欠;XERJ 用散文索取并把索取放在 ## Optional 下。重命名该节(如 "## Your side of the deal")并把 xerj feedback --open-pr 作为自己的步骤放进编号首跑列表(ParadeDB 证明"在列表里的步骤会被执行,Optional 下的链接不会")。
  7. 发布托管的无进程 docs-MCP 端点 + 一行 Cursor 插件,并在 llms.txt 里说清它不是什么(抄根文件的免责风格)。
  8. 加 EXAMPLES.md 可粘贴提示,按 '## Getting Started & Setup'、'## Indexing'、'## Basic Full-Text Search' 分组,让人类操作者用一个提示就能驱动 install → autoindex → search → feedback 全流程。

这些建议的工程后果(MCP 注册逐客户端配置、auth-on 默认下的 XERJ_AUTH、--open-pr 越界风险、verify 行、完成块)都已写进 docs/research/llms-txt-2026-09/proposals/proposed-llms.txt 和 docs/research/llms-txt-2026-09/proposals/proposed-llms-install.md(标注 "(proposed — not implemented)" 之处为当前二进制尚不支持),并经过真实 CLI 验证(xerj-cli-verification-2026-09-19.md:claude mcp add --scope user → Status: ✔ Connected,--scope project → ⏸ Pending approval;xerj init 不写 XERJ_AUTH 导致默认节点 401;xerj feedback --open-pr 会在任意仓库里分支/提交/推送)。

九、结语:一份有意的缺席

ParadeDB 的 llms.txt 解剖最有价值的发现恰恰是它缺了什么:没有安装命令、没有索取、没有 MCP 配置 JSON、没有 caveats。它把"让 agent 装好并用好"的全部重量转移到了一行 npx skills add 命令 + 一个 ~100 行的 SKILL.md 契约上——命令解决分发,契约解决行为,docs-fetch 脚本解决沙箱授权,EXAMPLES.md 解决人的首次驱动。XERJ 的研究据此得出结论:安装的载体很少是 llms.txt 本身,而是一跳之遥的短 agent 定向文件;llms.txt 应当是一个短、纯索引、零义务的路由器(研究区 46 个项目里 27 个的 llms.txt 完全没有安装命令,XERJ 的第 11 行反而是少数派优势)。这份解剖连同其余 45 个项目页、比较表和提案,共同构成了 docs/research/llms-txt-2026-09/ 目录下可复算的完整证据链——所有数字都能通过 scripts/measure_llms_txt.py 与 scripts/factcheck.py 重新测量与复核。

深入阅读(仓库内相关文件)

登录后查看全文
xerj