Agent-browser Geistdocs 回归套件¶

测试夹具来源¶

fixtures/docs-baseline.json 固定到提交 efee3893d9080fcacb1aa6c9a21d13fbc6021f20。捕获脚本读取该提交处的 git 对象，而非迁移后的应用代码或内容。它保留了全部 39 个原始 docs/src/app/**/page.mdx 文件、它们的布局、根元数据、mdx-components.tsx、page-metadata.ts、page-titles.ts、导航、搜索实现以及 mdx-to-markdown.ts：共 86 个完整源文件，并带有 SHA-256 哈希。公共资源和 favicon 通过字节长度和 SHA-256 固定。

每个页面记录其完整源哈希、原始 H1 插入位置、元数据、标题层级/文本/ID、散文段落、表格单元格、代码示例、链接、从原始来源推导出的旧版 Markdown 和新版 Markdown。H1 插入位置保留了标题前的导入，如 /diffing 页面所示。

生成器执行原始的 slugger 和递归 React 子文本提取器，不会替换为 GitHub 的 slug 生成方式，也不会对 ID 去重。独立的 oracle 使用原始标题组件编译并渲染捕获的原始 MDX，检查每个捕获的标题和内容样本。合成用例覆盖嵌套的内联子节点、数字文本、标点符号和重复 ID。围栏代码不会被解析为标题。

切勿根据迁移后的输出重新生成测试夹具来接受失败的断言。要从固定提交验证可重现性：

node scripts/capture-docs-baseline.mjs --check

要显式复现相同的冻结基线：

node scripts/capture-docs-baseline.mjs
node scripts/capture-docs-baseline.mjs --check

运行测试¶

在 docs/ 目录下运行：

node --test tests/docs-baseline.test.mjs tests/baseline-oracle.test.mjs
node scripts/test-routes.mjs

路由运行器需要已完成的生产构建。它在一个临时的回环端口上启动独立的 next start 进程，等待就绪后运行 Node 测试，传播失败信息，并清理其子进程。它不会构建或启动开发服务器。其生命周期遵循 portless 和 json-render 参考套件。

生产环境和预览环境的检查需要匹配的构建环境，包括静态生成的元数据和 robots：

VERCEL_ENV=production pnpm run build
node scripts/test-routes.mjs
VERCEL_ENV=preview pnpm run build
node scripts/test-routes.mjs --preview

运行器显式设置 VERCEL_ENV 和 DOCS_EXPECT_NOINDEX。预览环境要求 HTML 元数据和响应头中包含 noindex，并且 robots 中包含 Disallow: /。复用生产构建可能会暴露在错误环境中构建的元数据。

要测试已运行的生产服务器而不启动或停止任何服务器：

DOCS_TEST_URL=http://127.0.0.1:3000 DOCS_EXPECT_NOINDEX=0 node --test tests/docs-routes.test.mjs

在测试现有预览服务器时，设置 DOCS_EXPECT_NOINDEX=1。捕获脚本和原始渲染 oracle 使用 typescript、@mdx-js/mdx、react 和 react-dom；HTTP 套件使用 Node 内置模块。

回归不变量¶

逐字节 MDX 重建、完整 Markdown 等价性、标题多重性和旧版搜索排名是针对固定提交的迁移检查。它们在迁移合并后被移除，因为任何后续内容编辑都会使它们失败。其余检查将基线视为最低要求：每一行原始文本仍必须按顺序渲染，新行可以添加在任何位置，包括表格和代码块内部。当某个更改有意重写原始文本时，需在该页面的 fixtures/docs-edits.json 中添加一条 from/to 条目；若更改的是公共资源，则添加新的尺寸和 SHA-256。每个 from 仍必须出现在基线中，因此过时条目会失败。切勿编辑 docs-baseline.json 本身。

• 来自基线的 SSR 散文/表格/代码内容、元数据、规范 URL 和 Markdown 替代版本。
• 每个页面的 Markdown API、.md、内容协商 Markdown、旧版查询 API 和 HEAD 表示。
• 链接目标在比较前会根据规范页面 URL 进行解析。指向同一资源的绝对引用和相对引用是等价的；更改来源、路径、查询或片段则不等价。
• 图片保留原始 alt 文本。直接来源和每个响应式 srcset 候选都会通过 Next 的图像优化器解析为底层的同源资源。这些字节必须与原始资源测试夹具的长度和 SHA-256 匹配，包括静态导入生成哈希文件名的情况。仅凭 alt 文本或文件名无法确定图片的一致性。
• 接受质量/排除、浏览器、AI 机器人、预览/搜索机器人、未经修改的 Sec-Fetch 头、RSC、两个 Next 预取头、Purpose 和 Sec-Purpose。
• RSC 请求使用有效的空缓存破坏参数 /commands?_rsc。另一个独立的测试检查 Next 对无效缓存破坏参数的 307 规范化，然后验证目标位置的 Flight 响应。重定向不被视为成功的 Flight 响应。
• 针对 Accept、User-Agent、Signature-Agent、Sec-Fetch-Mode、Sec-Fetch-Dest、RSC、Next-Router-State-Tree、Next-Router-Prefetch、Next-Router-Segment-Prefetch、Next-Url、Purpose 和 Sec-Purpose 的显式 Vary 令牌；private/no-store 以及两个 CDN no-store 头；没有区域设置 cookie。
• 交替的 HTML/Markdown 请求不能相互污染。跟踪参数不得改变可见文本、元数据、文档链接或 Markdown。Next 的 Flight 水合脚本可能序列化请求 URL；它们的存在并不构成内容或规范链接泄漏。变更测试证明可见内容、规范链接和 OG 泄漏仍然会被判定为失败。
• 永久性的区域设置和尾斜杠重定向保留请求来源和查询。HTML/Markdown/API 未命中时返回真正的 404，包括 HEAD。原始畸形编码、编码的分隔符/控制字符、双重编码和不安全的旧版路径值都会被拒绝。
• 旧版搜索对象形状和空查询行为；包含表格文本和可解析为 SSR 锚点的嵌套区块片段的本机搜索数组。
• 精确的规范 sitemap/index 清单、感知环境的 robots、原始静态资源哈希、全部 39 个 OG PNG 端点（含签名和 1200x630 尺寸），以及 Next CSS/JS/字体路由。

兼容性契约¶

1. 旧版 /api/search?q=... 返回 { "results": [...] }。条目具有 title、href、section 和 snippet，最多返回 20 条排名结果。缺失、空字符串以及仅含空白的旧版查询返回 { "results": [] }。原生 ?query=...&locale=en 返回 Fumadocs 结果数组。
2. 旧版 /api/docs-markdown?path=... 返回来自原始转换器的裸输出，已修剪，不含 YAML 前置元数据或末尾换行。它接受 commands、/commands 和尾部斜杠。第一个重复的 path 参数生效。缺失/空参数返回 JSON 400，提示 Missing ?path= parameter；未知路径返回 JSON 404，提示 Page not found。
3. 原始转换器会删除以 export 或 import 开头的行，即使位于代码围栏内部，并保留 <DiffDemo />。旧版 fixture 保留了这些历史字节。新版 Markdown 是独立的、无损的契约：原始 MDX 仅移除 AST 级导入、非文本的 DiffDemo 组件以及演示用 className 属性。围栏内的 imports/exports 保持完整。不得通过更改 fixture 来人为地使这些端点相等。
4. 原始 slugger 是无状态的。/diffing 有三个 #options 和两个 #output 标题；/changelog 有 53 个 #bug-fixes 标题；/streaming 在其 H1 和 H2 中有两个 #streaming 目标。嵌套标题不得静默获得数字后缀。当 Geistdocs 渲染标题时，H1 可以使用单独的可寻址别名，但原始 ID 的多重性仍然是必需的。
5. 主页的 H1 是 agent-browser；其文档/OG/Twitter 标题是 agent-browser | Browser Automation for AI。根 PAGE_TITLES 条目用于 OG 渲染，而非文档标题。
6. 不安全的旧版遍历必须返回 JSON 400 或 404，而不是重现旧清理器将遍历转换为无关有效页面的能力。对于这些输入，绝不接受成功的内容。