内容
# @obaronai/astro-ai-readiness
> Astro AI 准备工具包 — 目前包含六个 JSON-LD 帮助组件以及 `dist/llms.txt`、`dist/agents.md` 和 `dist/.well-known/mcp.json` 文件；未来还将包含 `llms-full.txt` 和 `robots.txt` 文件。
**状态：** v0.0.6 — 第六个组件已发布。**组件子线路已完成（6/6）；五个文件输出中有三个文件输出已上线。** 在 `astro:build:done` 钩子上建立了多输出编排 — 随后的文件输出切片无需修改钩子即可连接。
## v0.0.6 中包含的内容
**六个 JSON-LD 组件**（组件子线路已完成）：
- `<OrganizationSchema />` — 组织块。根据配置驱动；放置在 `BaseLayout` 中，以便在整个站点范围内生效，并且 `#organization` `@id` 引用在每个页面上都能解析。
- `<WebSiteSchema />` — 网站块。根据配置驱动；与 `<OrganizationSchema />` 一起放置在 `BaseLayout` 中。
- `<CollectionSchema name url description? />` — 收藏页面块。根据属性驱动；放置在收藏索引页面（例如 `/articles/`、`/tags/[tag]/` 等）。
- `<BreadcrumbSchema items={[{ name, url }, ...]} />` — 面包屑列表。根据项目数组属性驱动；放置在多级页面中导航层次结构未内联声明的位置。空 `items` 数组跳过输出。
- `<FAQPageSchema items={[{ question, answer }, ...]} />` — 常见问题页面。根据项目数组属性驱动；放置在具有常见问题数据页面。长篇答案自动跳过 `<script>` 标签和 U+2028 / U+2029。空 `items` 数组跳过输出。
- `<TechArticleSchema headline description datePublished {...optional} />` — 技术文章块。根据属性驱动；放置在文章详情页面。`author` 默认从 `config.organization.founder` 合成；可以传递显式 `author` 属性覆盖。
**三个文件输出**（五个文件输出子线路中有三个已上线）：
- `dist/llms.txt` — [llmstxt.org](https://llmstxt.org/) 格式，来自 `llmsTxt` 配置块。H1 / 块引用摘要 / 可选正文 / H2 章节，带有项目符号链接 / 可选规范参考页脚。需手动开启。
- `dist/agents.md` — 来自 `agentsMd` 配置块的 AI 代理爬虫 Markdown 发现文件。H1 / 块引用描述 / 可选 `## Audience`、`## Contact`、`## Links` 章节。需手动开启。
- `dist/.well-known/mcp.json` — 来自 `mcp` 配置块的 [Model Context Protocol](https://modelcontextprotocol.io/) 发现文件。带有 `$schema` 引用到工具包发布的 v1 格式的漂亮 JSON（按照 D-22）。支持 `status: 'active'`（需要 `url` + `tools[]`）和 `status: 'planned'`（需要 `planned_tools[]`；禁止 `url`）。需手动开启。
**根据 D-8 检测 `@astrojs/sitemap`。** 当调用 `aiReadiness({...})` 且 `@astrojs/sitemap` 未在集成列表中时，工具包会记录一个构建时警告。站点地图是 AI 准备就绪的基线；站点地图引用本身包含在 `robots.txt` 中（v0.0.8）。
所有六个组件都发出规范的 Schema.org JSON-LD，并带有跨组件的 `@id` 引用（`#organization`、`#website`），以便搜索引擎和 AI 消费者无需重新声明共享字段即可解析实体图。
URL 配置字段（`site`、`organization.url`、`organization.logo`、`founder.sameAs`、`llmsTxt.*.url`）需要 `https://`（或开发环境下的 `http://localhost`）。
配置验证错误按每行一个问题格式化 — `path: message` 按 Zod 问题 — 而不是默认的 `ZodError` JSON 对象。
## 路线图（朝向 v0.1.0）
- v0.0.7 — `dist/llms-full.txt`（内容集合内省 — 工具包首次读取消费者内容）
- v0.0.8 — `dist/robots.txt` 组合（与现有模式组合；站点地图引用在此处）
- v0.1.0 — 完善、测试、文档；FF-3.7 全量安装（obaron.ai）
跟踪进度：<https://github.com/obaronai/astro-ai-readiness/milestones>
## 安装
```bash
npm install @obaronai/astro-ai-readiness
```
## 快速开始
配置（v0.0.6 接受 `site`、`organization`，可选 `webSite`、`llmsTxt`、`agentsMd` 和可选 `mcp` 块 — Zod 模式拒绝未知键，URL 字段必须使用 `https://` 或 `http://localhost`）：
```ts
// astro.config.mjs
import { defineConfig } from 'astro/config'
import sitemap from '@astrojs/sitemap'
import aiReadiness from '@obaronai/astro-ai-readiness'
export default defineConfig({
site: 'https://your-site.com',
integrations: [
sitemap(), // 推荐 — AI 准备就绪基线（D-8）
aiReadiness({
site: 'https://your-site.com',
organization: {
name: '您的品牌',
url: 'https://your-site.com',
logo: 'https://your-site.com/logo.png',
founder: {
name: '您的姓名',
jobTitle: '创始人',
sameAs: ['https://your-site.com', 'https://x.com/handle'],
},
},
webSite: {
// 可选。`name` 在缺失时默认为 `organization.name`。
description: '您的站点做什么，用一句话概括。',
},
llmsTxt: {
// 可选。设置后，工具包会在构建时生成 dist/llms.txt。
// 注意：`summary` 必须为单行 — 多段摘要会破坏
// llms.txt 块引用形状。使用 `body`（自由格式 Markdown）进行
// 额外描述。多行摘要在配置验证时抛出错误。
summary: '您的站点做什么，用一句话概括 — AI 代理发现您的内容。',
body: '自由格式 Markdown 段落或两段，介于摘要和章节之间。纯文本；无顶级 H2（预留给下面的链接章节）。',
sections: [
{
title: '文章',
links: [
{ title: '所有文章', url: 'https://your-site.com/articles/' },
{ title: 'RSS 源', url: 'https://your-site.com/rss.xml' },
],
},
],
deferTo: {
// 单个规范参考链接，渲染为页脚。
title: '文章索引',
url: 'https://your-site.com/articles/',
},
},
agentsMd: {
// 可选。设置后，工具包会在构建时生成 dist/agents.md。
description: '您的站点做什么以及为谁服务 — 面向 AI 代理爬虫。',
audience: '开发者和代表他们行动的 AI 代理。',
contact: 'hello@your-site.com',
links: [
{ title: '文章', url: 'https://your-site.com/articles/', description: '所有文章' },
{ title: 'RSS 源', url: 'https://your-site.com/rss.xml', description: '机器可读的文章流' },
],
},
mcp: {
// 可选。设置后，工具包会在构建时生成 dist/.well-known/mcp.json。
// 每个服务器必须具有状态：'active' 或状态：'planned'。
// 活动：需要 url + tools[]。计划中：需要 planned_tools[]；禁止 url。
servers: [
{
// 一个活动 MCP 服务器 — 必须有 url + tools。
status: 'active',
name: 'your-knowledge',
url: 'https://mcp.your-site.com',
description: 'MCP 服务器，为 AI 代理公开您的站点知识。',
tools: [
{ name: 'search_articles', description: '按关键词或标签搜索文章。' },
{ name: 'fetch_article', description: '按 slug 获取特定文章。' },
],
},
{
// 一个计划的服务器 — 声明意图，无需活动 URL。
status: 'planned',
name: 'your-future-server',
description: '计划的 MCP 服务器，用于未来功能。',
planned_tools: [
{ name: 'lookup', description: '一旦服务器上线，按 ID 查找。' },
],
},
],
},
}),
],
})
```
> **原始 Markdown 注意。** `llmsTxt.*` 和 `agentsMd.*` 字符串字段作为原始 Markdown 输出。如果您将用户生成的内容模板化到 `llmsTxt.summary`、`llmsTxt.body`、`llmsTxt.sections[].*.title`、`agentsMd.description`、`agentsMd.audience`、`agentsMd.contact` 或 `agentsMd.links[].*.title` / `agentsMd.links[].*.description`，请转义 `]`、`)` 和前导 `>` 以避免破坏渲染的 Markdown 形状。作者控制的字符串（典型情况）无需转义。`mcp.json` 是 JSON 序列化，没有 Markdown 注入漏洞。
使用组件：
```astro
---
// src/layouts/BaseLayout.astro — 站点范围
import { OrganizationSchema, WebSiteSchema } from '@obaronai/astro-ai-readiness/components'
---
<head>
<OrganizationSchema />
<WebSiteSchema />
</head>
```
`<OrganizationSchema />` 声明 `@id: '<site>#organization'`；`<WebSiteSchema />` 引用它。头部顺序很重要 — Organization 优先。
```astro
---
// src/pages/articles/index.astro — 收藏索引页面
import { CollectionSchema } from '@obaronai/astro-ai-readiness/components'
---
<CollectionSchema
name="所有文章"
url={new URL('articles/', Astro.site).toString()}
description="生产测试的文章，版本固定环境。"
/>
```
```astro
---
// 任意多级页面 — 站点上下文导航
import { BreadcrumbSchema } from '@obaronai/astro-ai-readiness/components'
import type { BreadcrumbItem } from '@obaronai/astro-ai-readiness/components'
const crumbs: BreadcrumbItem[] = [
{ name: '首页', url: new URL('/', Astro.site).toString() },
{ name: '文章', url: new URL('/articles/', Astro.site).toString() },
{ name: '代理如何处理错误', url: Astro.url.toString() },
]
---
<BreadcrumbSchema items={crumbs} />
```
```astro
---
// 具有 FAQ 数据的页面 — 问题/答案对数组
import { FAQPageSchema } from '@obaronai/astro-ai-readiness/components'
import type { FAQItem } from '@obaronai/astro-ai-readiness/components'
const faqs: FAQItem[] = [
{ question: '什么是 X？', answer: 'X 是...' },
{ question: '为什么 Y 很重要？', answer: '因为...' },
]
---
<FAQPageSchema items={faqs} />
```
```astro
---
// 文章详情页面 — 仅需必填属性
import { TechArticleSchema } from '@obaronai/astro-ai-readiness/components'
---
<TechArticleSchema
headline="代理如何处理错误"
description="一种适用于代理的错误处理模式，不会丢失上下文。"
datePublished="2026-04-01T12:00:00Z"
/>
```
`<TechArticleSchema>` 默认 `author` 从 `config.organization.founder` 合成（姓名来自 `founder.name`，URL 来自 `founder.sameAs[0]`）。在多作者站点上，可以传递显式 `author={{ name, url? }}` 以覆盖。组件在构建时抛出错误，如果 `author` 被省略且 `founder` 未设置 — 可操作错误指向 `aiReadiness({...})` 配置。
高级 — 完整属性表面：
```astro
<TechArticleSchema
headline={article.title}
description={article.description}
datePublished={article.pubDate.toISOString()}
dateModified={(article.updatedDate ?? article.pubDate).toISOString()}
author={{ name: '客座作者', url: 'https://example.com' }}
image={{ url: 'https://your-site.com/og.png', width: 1200, height: 630 }}
articleSection="教程"
keywords={['ai', 'agents', 'error-handling']}
proficiencyLevel="intermediate"
dependencies={['Node 22', 'Astro 5.5']}
/>
```
构建您的站点（`npm run build`）；检查任意 `dist/*.html` — 您将看到带有跨引用 `@id` 的内联 `<script type="application/ld+json">` 块，将实体图联系起来。
## 设计原则
- **零客户端 JS。** 每个组件在构建时发出内联 `<script type="application/ld+json">`。水合 JSON-LD 会削弱它所代表的 Schema.org 类别。
- **组合，不要覆盖。** 未来的文件输出（例如 `robots.txt`）将与现有的用户文件合并，而不是覆盖。用户意图获胜。
- **与 `@astrojs/sitemap` 组合。** 不会取代它。当需要时，会警告一旦输出涉及站点地图。
## v0.1 之后的内容
v0.1 线路是内容 → 工件：组件和文件。构建时 AI 就绪自我评分（针对 Obaron 公布的评分标准）、针对 [llmstxt.org](https://llmstxt.org) 的规范验证和内容检查计划在 v0.2 阶段 — 但未承诺范围。v0.1 首先发布。
## 已发布于
- [aiallthethings.com](https://aiallthethings.com) — AATT，工具包的第一个参考实现。在生产环境中运行所有六个组件以及三个工具包生成的输出文件：`dist/llms.txt` 在 <https://aiallthethings.com/llms.txt>、 `dist/agents.md` 在 <https://aiallthethings.com/agents.md>，以及 `dist/.well-known/mcp.json` 在 <https://aiallthethings.com/.well-known/mcp.json>。组件：Organization + WebSite（通过 BaseLayout 站点范围）、CollectionPage（文章 + 框架 + 标签索引）、BreadcrumbList（`/about`）、FAQPage（带有 FAQ 前置的文章）、TechArticle（每个文章详情页面）。
- [obaron.ai](https://obaron.ai) — Obaron 的主站点。一旦 v0.1.0 发布，将在 FF-3.7 中安装。
## 贡献
欢迎 PR。请参阅 [CONTRIBUTING.md](./.github/CONTRIBUTING.md) 和我们的 [行为准则](./CODE_OF_CONDUCT.md)。
## 许可证
MIT — 版权所有 (c) 2026 Adam Kinney, LLC（DBA Obaron）。
