next-partial-prefetching-optimizer

部分预取优化器

将每个请求的源链接和目标页分别视为独立契约。把请求中指定的预取 UI、仅导航时显示的 UI 和触发时机转化为生产环境中的 instant() 测试。记录当前行为，实施最小幅度的优化，验证差异，并保留通过的测试作为回归覆盖。

更改框架行为前，请先阅读随项目附带的预取优化指南： node_modules/next/dist/docs/01-app/02-guides/optimizing-prefetching.md。如果无法获取随项目附带的指南，请使用在线 指南。预取阶段、prefetch={true}、会话专属 UI 和成本权衡均以该指南为准。

如果工作会改变 App Shell 中包含的内容，请遵循 即时导航和 缓存文档，了解缓存位置、Suspense 边界、加载 UI 和授权。

指南规定框架行为和实现模式。本技能负责导航契约、生产测试环境、可靠的 RED 到 GREEN 循环、对等性检查、差异验证和报告。

这不是用于采用功能的技能。如果尚未采用 Cache Components 或 Partial Prefetching，请使用相应的采用技能，然后返回此工作流。如果 App Shell 本身无法在 instant() 下提交，请先使用 next-cache-components-optimizer，然后继续处理所选导航。

请在无人值守的情况下运行工作流。根据请求和现有应用确定契约。只有在产品决策确实受阻，且无法在不改变成本、新鲜度、授权或用户可见行为的前提下安全推断时，才向用户请求输入。

向用户报告

此循环会在无人值守的情况下运行，因此不要在实现步骤之间停下来。完成用户指定的导航后，再进行确认。测试环境、锁定、RED/GREEN 循环和阶段名称都是内部脚手架；报告时应描述产品行为。

• 使用用户熟悉的说法。 根据用户点击前后看到的内容来描述源链接和结果，而非验证机制。
• 展示，而非空谈。 在生产环境的浏览器中操作确切的链接，让用户看到哪些内容在点击前已经可用，哪些内容会在点击后流式呈现。如果无法进行实时演示，请附上前后截图。
• 提供简洁的点击导航列表，而非技术结果表。 每项导航占一行，列出源 URL、要点击的链接、点击前就绪的 UI、需要等到导航后才显示的 UI，以及预取是在进入视口时还是用户表达意图后开始。
• 只针对真正存在分歧的情况提出问题。 如果选择会改变成本、新鲜度、授权或可见行为，请提出问题。如果用户已经要求创建 PR，或列明了每项导航，就不要再次询问，应完成指定范围。

定义契约

检查源路由、确切的链接或交互、目标页的 Suspense 边界、数据读取、现有预取策略，以及任何现有的 instant() 测试。记录：

• 点击前应就绪的目标页 UI；
• 应等到导航后才显示的可复用 UI；
• 每个链接的预取应在进入视口时开始，还是仅在用户表达意图后开始。

触发时机也是契约的一部分。指向同一 URL 的两个链接可以使用不同的预取策略，因此需要分别测试。

如果尚未指定触发时机，请使用指南中的成本模型。不要擅自增加可能调用服务端的链接数量，也不要缓存新鲜度契约未知的数据。

复用生产环境测试装置

阅读现有的 instant-nav.rig.md。缓存组件优化、部分预取的采用以及此优化器共用相同的构建、身份验证、数据和 Playwright 约定。添加确切的源链接、目标标记和预取预算，而不是另建一套测试装置。

如果项目没有测试装置，请使用 rig-template.md 来查找并记录一套。测量运行必须使用生产构建或预览环境，并且仅在测试时启用 experimental.exposeTestingApiInProductionBuild。 开发环境可以帮助诊断路由，但自动链接预取仅适用于生产环境。

证明当前行为

搜索是否已有针对确切源链接和目标的 instant() 测试。如果已有测试覆盖相同行为，就扩展它。否则，使用指南中的预取和延迟内容测试模式，添加一个由点击触发的专门测试。

每种源链接、目标和触发约定，只保留一个生产环境浏览器测试。不要在一个测试中循环访问多个目标，或收集它们的就绪结果。专门测试仍可在同一个浏览器工作进程中串行运行。

首先，运行一个未锁定的脚手架测试，证明链接会到达确切的路径名和查询参数，并且所选 UI 最终会为测试用户渲染。不要交付此脚手架测试。

然后，在 instant() 内执行相同交互。现有 App Shell 必须保持可见，同时使用指南中的肯定和否定断言捕获预取结果。锁释放后，每个选定区域都必须最终渲染。

在将此失败视为 RED 之前，请阅读 reference/red-test-robustness.md。URL 尚未更改就超时、App Shell 缺失、发生重定向、数据缺失或预览过期，都表明测试装置或路由存在问题，不能据此更改预取行为。

如果完整的目标约定在锁定期间已经通过，就此停止。绝不要仅为制造 RED 而添加 prefetch={false}。

这些运行完成之前，只能更改测试文件和启用测试 API 所需的配置。在前台运行构建和测试。如果测试框架将其中一项移至后台，请等待其退出，并在同一任务中继续这一循环。仅编写测试或仍在进行中的构建，都不算验证。

实施最小优化

遵循预取优化指南中的阶段和链接策略。如果契约还要求更改缓存位置、Suspense 或加载 UI，请遵循 next-cache-components-optimizer 使用的静态外壳文档。保留现有的新鲜度和授权行为。只更改所选契约要求的内容。

当可复用 UI 应等待导航时，请遵循 navigation() 参考文档，包括其中与 connection() 的比较。然后分别验证这两项属性。instant() 断言能证明 UI 未包含在预取内容中，但不能证明底层工作仍可复用。请验证可复用工作仍缓存在阶段边界之下。

当契约需要显式运行时阶段时，请遵循 prefetch() 和 navigation() 的 API 参考文档。

每次只让一个已接受的导航达到 GREEN，再处理另一个。不要根据单个案例创建适用于整个应用的 Link 或缓存抽象。

如果优化新增或扩展了缓存边界，请遵循重新验证。当写入操作可能更改缓存数据时，请测试完整生命周期：填充缓存、执行变更，然后再次读取数据并验证更新后的值。instant() 测试通过只能证明预取内容已就绪，不能证明变更后的数据是最新的。

验证并交付

保留针对真实源链接的通过锁定测试，作为回归覆盖。保留已加载页面的内容、顺序、空状态和错误状态、授权、新鲜度、重定向及直接加载行为。

最后，只移除该优化并重新运行测试：

• App Shell 保持 GREEN；
• 所选预取契约返回 RED。

重新应用优化，并再次要求达到 GREEN。这个差异对比能证明测试保护的是确切的链接策略，而不是无关的缓存状态。只交付最终的正向测试。

使用上文面向用户的格式报告已验证结果。请明确说明预取属于尽力而为；如果预取尚未完成，App Shell 仍是回退方案。

将请求数、传输字节数和缓存行为视为测量指标，而非 instant() 契约的一部分。不要使用私有 RSC URL 或 next-router-prefetch 等内部标头对请求分类。公开测试 API 验证的是渲染结果，而非产生各个请求的协议阶段。

完成清单

• 已采用 Cache Components 和 Partial Prefetching。
• 已根据请求和现有应用确定目标 UI、触发条件、新鲜度及授权约束。
• 测试会点击确切的源链接，并验证确切的目标页面。
• 每个源链接、目标页面和触发条件契约都有各自的测试。
• 未锁定基线与锁定后的 RED 使用同一生产产物。
• 在整个 RED/GREEN 循环中，App Shell 始终可见。
• 锁定时，所选 UI 会显示，且仅在导航时显示的 UI 不会显示。
• 仅在导航时使用的可复用工作仍缓存在其导航阶段之下。
• 填充任何数据可能更新的新缓存后，变更测试会确认下一次读取返回预期数据。
• 已加载内容、新鲜度、授权和直接访问行为均未改变。
• 只移除优化后，契约会返回 RED。
• 最终的正向 instant() 回归测试已交付。

交接

完成请求中指定的每项导航。如果未采用 Cache Components 或 Partial Prefetching，请使用 next-cache-components-adoption 或 next-partial-prefetching-adoption，然后返回此工作流。如果 App Shell 无法在 instant() 下提交，请使用 next-cache-components-optimizer，然后继续执行所选导航。不要留下需要用户监控的构建或测试。

报告其他优化候选项，但不要修改它们，除非它们已在范围内。不要将选定的单链接策略扩大为全应用的 Link 或缓存抽象。

文件

• rig-template.md：为没有现有 instant-nav.rig.md 的项目提供生产构建、测试上下文、导航契约和无人值守循环发现。
• reference/red-test-robustness.md：可信的 RED 和差异检查。

延伸阅读

• 优化预取
• 即时导航
• 缓存
• 预取