Valid — Vehicle Identity Mcp Server

AI Agent 可见性

搜索正从链接转向答案。要出现在这些答案中，你的内容必须便于 AI Agent 和爬虫读取，并遵循各自查找内容时采用的规范。此模板由 Workers AI 提供支持，可将单一内容库投射到所有 Agent 发现入口，让你的网站在这些入口中都清晰可见。

工作原理： Worker 通过 Workers AI 一次性丰富你的内容，提取简洁的标题、便于 Agent 阅读的摘要、要点和主题标签；随后将其缓存到 KV，再将同一内容库转换为 Agent 可能请求的各种形式：

• /llms.txt 和 /llms-full.txt — llms.txt 索引规范
• /index.json — 面向结构化 Agent 的类型化 JSON 索引
• /<slug>.md — 每个页面对应的简洁 Markdown，适合用于内容依据和引用
• /robots.txt — 明确指令，欢迎指定的 AI 爬虫
• Content-Signal 标头 — 声明 Agent 可以如何使用你的内容
• JSON-LD（/jsonld、/<slug>.jsonld）— 面向传统爬虫和 AI 爬虫的 schema.org 结构化数据
• Web Bot Auth (可选) — 验证已签名 Agent 的身份（RFC 9421，Ed25519）

同一份数据，可按 Agent 偏好的形式提供。模板还附带 UI，可供你实时预览和复制各个入口的内容。

此模板附带示例内容，部署后即可使用。编辑 src/lib/content.ts，将其指向你自己的页面；也可以通过 POST 将内容发送到 /api/resources，即时丰富内容。

适用对象

• 想要出现在 AI 答案中的任何人。 如果读者越来越常向 ChatGPT、Claude 或 Perplexity 提问，而不是点击搜索结果，此模板会为这些 Agent 提供一份简洁、结构化的内容副本，供其引用。
• 探索 AEO（答案引擎优化）的开发者。 一个可运行的参考项目，将新兴的 Agent 发现规范集中在一个 Worker 中。
• 经常遇到 Agent 4xx 错误的团队。 如果机器人分析数据显示 AI Agent 正在访问它们无法读取的路径，此模板就是解决方案：向它们提供可读取的内容。

想要针对电商场景的版本？请参阅 commerce-llms-txt-template，其中的 /llms.txt 专为产品目录设计。此模板则是通用的多入口版本。

开始使用

在此仓库之外，你可以使用此模板通过 C3（create-cloudflare CLI）启动新项目：

npm create cloudflare@latest -- --template=cloudflare/templates/agent-visibility-template

每个拉取请求都会通过上方的 Deploy to Cloudflare 按钮生成实时预览。

设置

1. 安装依赖：

   npm install
   

2. 创建 KV 命名空间，并将其 ID 添加到 wrangler.jsonc（替换示例命名空间 ID）：

   npx wrangler kv namespace create VISIBILITY_CACHE
   

3. 在 wrangler.jsonc 的 vars 下设置站点信息（SITE_NAME、SITE_DESCRIPTION）。

4. （可选）要使用运行时写入 API，请设置管理员密钥 —— 在设置之前，POST 路由处于禁用状态：

   npx wrangler secret put ADMIN_TOKEN
   

5. 在本地运行：

   npm run dev
   

6. 部署：

   npm run deploy
   

部署后

Worker 部署后即可立即运行，并提供附带的示例内容——无需数据源。 访问根 URL 可打开入口浏览器 UI，然后查看实时 Agent 入口：

• https://<your-worker>/llms.txt 和 /llms-full.txt
• https://<your-worker>/index.json
• https://<your-worker>/getting-started.md（任意示例 slug）
• https://<your-worker>/robots.txt

首次请求某个入口时，系统会通过 Workers AI 丰富内容并将其缓存； 后续请求则由 KV 提供内容。替换示例内容（参见 添加你自己的内容），即可改用你自己的内容。

配置

所有配置都位于 wrangler.jsonc 的 vars 中：

变量	描述	默认值
SITE_NAME	网站名称，会显示在所有界面中	Acme Docs
SITE_DESCRIPTION	为 Agent 提供的一句话描述	(sample)
AI_MODEL	用于内容增强的 Workers AI 模型	@cf/meta/llama-3.3-70b-instruct-fp8-fast
ENRICHMENT_CACHE_TTL	在 KV 中缓存增强记录的秒数	3600
CONTENT_SIGNAL	内容信号策略（写入 robots.txt 并作为标头发送）	ai-input=yes, search=yes, ai-train=no
ENABLE_WEB_BOT_AUTH	启用可选的 Agent 身份界面	false

密钥（使用 npx wrangler secret put <NAME> 设置，切勿提交）：

密钥	描述
ADMIN_TOKEN	修改 API 路由所需的 Bearer 令牌（POST /api/resources、POST /api/refresh）。未设置时，这些路由会返回 401。

添加自己的内容

选项 A — 编辑源文件： 将 src/lib/content.ts 中的条目替换为自己的页面（slug、url、可选的 title，以及 HTML 或 Markdown 格式的 body），然后重新部署。

选项 B — 运行时 POST： 设置 ADMIN_TOKEN 后，将内容发送到 API，即可立即完成增强并添加：

curl -X POST https://your-worker.workers.dev/api/resources \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H "content-type: application/json" \
  -d '{"slug":"about","url":"https://example.com/about","title":"About","body":"<h1>About us</h1>..."}'

Slug 必须符合 ^[a-z0-9-]{1,63}$，url 必须使用 http(s)，正文上限为 100 KB，存储最多可容纳 100 个资源。调用 POST /api/refresh （同样需要身份验证）即可清除缓存，并从源文件重新进行增强。

端点

方法	路径	描述
GET	/llms.txt	llms.txt 索引（Markdown）
GET	/llms-full.txt	内联完整内容（Markdown）
GET	/index.json	类型化 JSON 索引
GET	/:slug.md	单页 Markdown
GET	/:slug.jsonld	单页 schema.org JSON-LD
GET	/jsonld	站点级 schema.org JSON-LD
GET	/robots.txt	AI 机器人指令
GET	/api/site	站点配置 + 界面列表（供 UI 使用）
GET	/api/resources	增强后的资源（JSON）
GET	/api/resources/:slug	单个增强后的资源
POST	/api/resources	增强并添加/替换资源 （需要 ADMIN_TOKEN）
POST	/api/refresh	清除增强缓存 （需要 ADMIN_TOKEN）
GET	/.well-known/web-bot-auth/directory	可信 Agent 密钥 （如果已启用）
POST	/api/identity	验证已签名的 Agent 请求 （如果已启用）

缓存

增强处理是开销最大的步骤（每页调用一次 Workers AI），因此结果会以单个键的形式缓存在 KV 中，并重复使用，直到 ENRICHMENT_CACHE_TTL 到期（默认 1 小时）。POST /api/resources 只会增强新增或已更改的页面，并就地更新缓存；POST /api/refresh 会清除缓存，使下一次读取从源数据重新进行增强。如果 Workers AI 暂时不可用，Worker 会回退到确定性增强，并且只将降级结果缓存 60 秒，避免短暂的故障污染界面，使其在整个 TTL 期间都无法恢复。

已知限制

• 增强处理会在请求路径中运行。 冷缓存后的首次请求会内联增强所有页面，因此比读取缓存慢。对于大型站点，请将增强处理移至 Queue 或定时 Cron Trigger。
• 存储数据分布在两个 KV 键中，并限制为 100 个资源 / 每个正文 100 KB，以确保远低于 KV 限制。对于更大的目录，请改为每个资源使用一个 KV 键（或 D1），并添加分页。
• KV 采用最终一致性。 执行 POST 后，其他区域的界面读取可能会短暂返回旧版本。
• 运行时写入使用 KV 读-改-写。 可变 API 旨在用于轻量级管理员更新。请避免并发写入；对于高频或多写入方的工作流，请通过 Durable Object 串行化写入，或将存储迁移至 D1。
• Web Bot Auth 是一个精简的参考实现（见下文），并非经过强化的实现——依赖它之前，请先查看当前草案。

可选：Web Bot Auth（Agent 身份）

以上内容都是为了让内容可读。Web Bot Auth 则是另一个方面——让行为良好的 Agent 通过签名请求（RFC 9421，Ed25519）证明自己的身份。默认情况下，此功能处于关闭状态。设置 ENABLE_WEB_BOT_AUTH=true，即可开放 /.well-known/web-bot-auth/directory 密钥目录和 /api/identity 验证端点。将 src/lib/web-bot-auth.ts 中的示例密钥替换为你实际信任的 Agent 的密钥，并在生产环境依赖此功能前，查看最新的 Web Bot Auth 草案。

测试

npm test

测试套件会在访问公开接口前预先填充 KV 缓存，因此可在本地运行，无需发起 Workers AI 请求。

许可证

请参阅仓库中的 LICENSE。