astro-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro Code Review

Astro代码审查

Review a proposed change for correctness and fit with the Astro codebase. Report actionable findings; do not implement fixes.

审查拟议变更的正确性及其与Astro代码库的适配性。报告可执行的审查结果；请勿实施修复。

Safety Boundary

安全边界

This is a static review. Preserve the developer's working tree exactly as found.

Do not create, edit, move, or delete files.
Do not apply patches or create a changeset.
Do not run project code, package-manager commands, scripts, tests, type checks, linters, formatters, builds, benchmarks, dev servers, or browser automation.
Do not delegate the review to another agent because these restrictions may not carry into the delegated task.
Do not use GitHub APIs,
```
gh
```
,
```
curl
```
, or arbitrary network tools to gather review context.
Read-only documentation search and fetch tools are allowed when a security-sensitive change requires current Astro or web-platform guidance.
Do not run mutating Git operations such as pull, merge, rebase, checkout, switch, reset, restore, clean, stash, commit, or push.

The permitted network operations are the targeted documentation lookups above and one

git fetch origin main

before reviewing the default scope. Fetching updates Git metadata but not source files. If it fails, continue with the existing local

origin/main

and disclose that the comparison may be stale. Do not troubleshoot or retry the fetch.

Shell commands are limited to these read-only Git operations and the fetch exception:

```
git fetch origin main
```
```
git status --short --branch
```
```
git branch --show-current
```
```
git rev-parse
```
```
git merge-base HEAD origin/main
```

git --no-pager diff --no-ext-diff --no-textconv ...

git --no-pager show --no-ext-diff --no-textconv ...

```
git --no-pager log ...
```
```
git ls-files ...
```

Use file-reading, globbing, and text-search tools for all other investigation. Do not use shell pipelines or scripts to analyze source code.

这是静态审查。严格保留开发者的工作树原样。

请勿创建、编辑、移动或删除文件。
请勿应用补丁或创建变更集。
请勿运行项目代码、包管理器命令、脚本、测试、类型检查、代码检查器、格式化工具、构建、基准测试、开发服务器或浏览器自动化工具。
请勿将审查委托给其他Agent，因为这些限制可能无法传递到委托任务中。
请勿使用GitHub API、
```
gh
```
、
```
curl
```
或任意网络工具收集审查上下文。
当涉及安全敏感的变更需要当前Astro或Web平台指南时，允许使用只读文档搜索和获取工具。
请勿执行会修改状态的Git操作，例如pull、merge、rebase、checkout、switch、reset、restore、clean、stash、commit或push。

允许的网络操作仅限上述针对性文档查询，以及审查默认范围前执行一次

git fetch origin main

。Fetch操作仅更新Git元数据，不修改源文件。如果操作失败，继续使用现有本地

origin/main

，并说明比较结果可能已过时。请勿排查或重试fetch操作。

Shell命令仅限以下只读Git操作和上述fetch例外：

```
git fetch origin main
```
```
git status --short --branch
```
```
git branch --show-current
```
```
git rev-parse
```
```
git merge-base HEAD origin/main
```

git --no-pager diff --no-ext-diff --no-textconv ...

git --no-pager show --no-ext-diff --no-textconv ...

```
git --no-pager log ...
```
```
git ls-files ...
```

所有其他调查请使用文件读取、通配符匹配和文本搜索工具。请勿使用Shell管道或脚本分析源代码。

Establish the Review Scope

确定审查范围

Prefer an explicit scope supplied by the user, such as files, a diff, commits, or a base branch. Otherwise review the current branch and complete working tree against the latest available

origin/main

Run the permitted fetch once.
Find the merge base of
```
HEAD
```
and
```
origin/main
```
.
Inspect the diff from that merge base to the working tree. This includes committed, staged, and unstaged changes to tracked files.
Use Git status to identify untracked files, then read those files directly.

Do not fetch when the user provides a self-contained patch or asks for specific files only. If

origin/main

is unavailable or the intended base is ambiguous, ask for the base rather than guessing.

Establish the intended behavior from the user's description, commit messages, changed tests, and surrounding code. If correctness depends on requirements that are not available locally, state the assumption or ask for the missing context. A URL alone is not permission to fetch issue or pull-request data.

优先使用用户提供的明确范围，例如文件、差异、提交或基准分支。否则，针对最新可用的

origin/main

审查当前分支和完整工作树：

执行一次允许的fetch操作。
找到
```
HEAD
```
与
```
origin/main
```
的合并基准。
检查从该合并基准到工作树的差异。这包括已提交、暂存和未暂存的跟踪文件变更。
使用Git状态识别未跟踪文件，然后直接读取这些文件。

当用户提供独立补丁或仅要求审查特定文件时，请勿执行fetch操作。如果

origin/main

不可用或预期基准不明确，请询问基准而非猜测。

从用户描述、提交消息、修改的测试及周边代码确定预期行为。如果正确性依赖本地未提供的需求，请说明假设或询问缺失的上下文。仅提供URL并不允许获取问题或拉取请求数据。

Gather Context

收集上下文

Read enough surrounding code to understand the change rather than reviewing the diff in isolation:

Read the complete changed functions and the relevant portions of their files.
Inspect callers, importers, exports, and data flow affected by the change.
Inspect existing tests and nearby test conventions.
Search for equivalent logic, existing helpers, and analogous implementations before suggesting a new abstraction or reuse opportunity.
Inspect comments changed by the diff and existing comments whose claims may have been invalidated by the new behavior.
Read the root and nearest applicable
```
AGENTS.md
```
and
```
CONTRIBUTING.md
```
guidance.
Consult package-specific documentation only when it governs the changed code.

Focus findings on the proposed change. Mention a pre-existing problem only when the change depends on it, worsens it, or makes it newly reachable.

阅读足够的周边代码以理解变更，而非孤立审查差异：

阅读完整的修改函数及其文件的相关部分。
检查受变更影响的调用方、导入方、导出项和数据流。
检查现有测试及附近的测试约定。
在建议新抽象或复用机会前，搜索等效逻辑、现有工具函数和类似实现。
检查差异中修改的注释，以及其声明可能因新行为失效的现有注释。
阅读根目录及最近适用的
```
AGENTS.md
```
和
```
CONTRIBUTING.md
```
指南。
仅当文档管辖修改的代码时，才查阅包特定文档。

将审查结果聚焦于拟议变更。仅当变更依赖、恶化或使预先存在的问题变得可访问时，才提及该问题。

Review Method

审查方法

Review in two passes:

Design pass: Understand the goal, decide whether the change belongs at the chosen architectural layer, and trace how its pieces interact with the rest of Astro.
Implementation pass: Review every human-written changed line and the relevant tests for correctness, failure behavior, and maintainability.

If part of the change cannot be understood from the available local context, ask for clarification or state the review limitation. Do not silently skip complex code.

Judge whether the change improves the codebase, not whether it is perfect. Distinguish defects that require action from optional improvements, and do not block useful work on personal preferences or unrelated cleanup.

分两轮进行审查：

设计审查： 理解目标，判断变更是否属于所选架构层，并追踪其组件与Astro其余部分的交互方式。
实现审查： 审查每一行人工修改的代码及相关测试的正确性、失败行为和可维护性。

如果部分变更无法从可用本地上下文理解，请询问澄清或说明审查限制。请勿跳过复杂代码。

判断变更是否改进代码库，而非是否完美。区分需要处理的缺陷与可选改进，不要因个人偏好或无关清理工作阻碍有用的变更。

Review Priorities

审查优先级

Review in this order so correctness and compatibility are not displaced by style suggestions:

Design and architectural layer placement
Functional correctness and regressions
Security and trust boundaries
Runtime portability, state ownership, and generated output
Astro feature, API, and monorepo completeness
Error handling and failure behavior
Test coverage and test quality
Simplicity, duplication, and function boundaries
Comments and behavior documentation
Changeset coverage

按以下顺序进行审查，确保正确性和兼容性不会被风格建议取代：

设计与架构层定位
功能正确性与回归
安全性与信任边界
运行时可移植性、状态所有权与生成输出
Astro功能、API与单体仓库完整性
错误处理与失败行为
测试覆盖与测试质量
简洁性、重复代码与函数边界
注释与行为文档
变更集覆盖

Design and Layer Placement

设计与层定位

Check that the change solves the stated problem at the narrowest appropriate layer and integrates with existing architecture. In particular, distinguish build-time processing, Vite plugin implementation, generated virtual modules, shared application state, and per-request runtime behavior.

Runtime code should receive build results through an explicit transport such as the manifest or a virtual module rather than import build implementation directly.
New logic should use an existing subsystem boundary when one already owns the behavior.
Unrelated behavior, refactors, or formatting should not be mixed into the change when they make review, rollback, or maintenance harder.
A new feature should not introduce generic machinery or public surface area beyond its current requirements.

Consult

astro-developer/architecture.md

when the change crosses build, development, rendering, or production boundaries.

检查变更是否在最窄的合适层解决所述问题，并与现有架构集成。特别区分构建时处理、Vite插件实现、生成的虚拟模块、共享应用状态和每个请求的运行时行为。

运行时代码应通过清单或虚拟模块等显式传输接收构建结果，而非直接导入构建实现。
当已有子系统边界负责该行为时，新逻辑应使用现有子系统边界。
不应将无关行为、重构或格式化混入变更，以免增加审查、回滚或维护难度。
新功能不应引入超出当前需求的通用机制或公共接口。

当变更涉及构建、开发、渲染或生产边界时，请查阅

astro-developer/architecture.md

。

Functional Correctness

功能正确性

Trace actual inputs and outputs through the affected callers. Check that the implementation matches the intended contract in development, build, prerendering, and SSR contexts that can reach it.

Look for concrete problems involving:

incorrect conditions, ordering, defaults, or state transitions
empty, missing, malformed, duplicate, or boundary inputs
asynchronous control flow, unawaited work, races, or cleanup
mutation, caching, and lifecycle assumptions
error and fallback behavior
public API compatibility and changed observable behavior
operating-system and runtime differences

Do not report a theoretical edge case without explaining how the changed code can encounter it and what fails.

追踪受影响调用方的实际输入和输出。检查实现是否与开发、构建、预渲染和SSR等可访问该实现的上下文的预期契约匹配。

寻找以下具体问题：

错误的条件、顺序、默认值或状态转换
空值、缺失、格式错误、重复或边界输入
异步控制流、未等待的任务、竞争条件或清理问题
突变、缓存和生命周期假设
错误与回退行为
公共API兼容性与可观察行为变更
操作系统与运行时差异

请勿报告理论边缘情况，除非说明修改后的代码如何遇到该情况以及会发生什么故障。

Security and Trust Boundaries

安全性与信任边界

Apply security review when changed code accepts less-trusted input, emits executable or interpreted output, handles credentials or secrets, changes a public request endpoint, or modifies an existing defense. Trace a reachable input to its sink or protection boundary and explain the attacker capability and impact. Do not report a vulnerability from a dangerous-looking name or API alone.

Before reviewing a security-sensitive change, use read-only documentation search or fetch tools rather than model memory. Consult MDN's XSS guidance for rendering or DOM-insertion changes and its CSRF guidance for state-changing request paths. Use the applicable Astro security configuration, Actions, or server-island guidance for the public contract, and the checked-out source for the implementation under review.

When a change reaches an Astro-owned security mechanism, establish its contract from the current implementation, neighboring tests, and public documentation rather than a fixed checklist in this skill. Verify that the change preserves that contract and its trust boundary. Framework-generated raw HTML, ciphertext, or other security-sensitive values are not findings by themselves; demonstrate a reachable bypass and impact.

Use these source areas as starting points, then follow their callers and tests:

Rendering and escaping:

runtime/server/escape.ts

and

runtime/server/render/util.ts

Request security:
```
core/app/
```
,
```
core/csp/
```
,
```
actions/
```
, and the
```
security
```
configuration types

Server-island data protection:

core/encryption.ts

core/server-islands/

, and

runtime/server/render/server-islands.ts

For generated output, trace whether less-trusted or server-only values cross into client bundles or interpreted output, then apply the owning subsystem's validation, escaping, and serialization contract.

当修改的代码接受可信度较低的输入、输出可执行或解释性内容、处理凭据或机密、更改公共请求端点或修改现有防御措施时，进行安全审查。追踪可访问的输入到其接收端或保护边界，并说明攻击者的能力和影响。请勿仅根据危险的名称或API报告漏洞。

在审查安全敏感变更前，使用只读文档搜索或获取工具而非模型记忆。对于渲染或DOM插入变更，查阅MDN的XSS指南；对于状态变更请求路径，查阅其CSRF指南。对于公共契约，使用适用的Astro安全配置、Actions或server-island指南；对于待审查的实现，使用检出的源代码。

当变更涉及Astro维护的安全机制时，从当前实现、相邻测试和公共文档而非此技能中的固定检查清单确定其契约。验证变更是否保留该契约及其信任边界。框架生成的原始HTML、密文或其他安全敏感值本身并非问题；需证明存在可访问的绕过方式及影响。

以下列源代码区域为起点，然后追踪其调用方和测试：

渲染与转义：

runtime/server/escape.ts

和

runtime/server/render/util.ts

请求安全：
```
core/app/
```
、
```
core/csp/
```
、
```
actions/
```
以及
```
security
```
配置类型

Server-island数据保护：

core/encryption.ts

、

core/server-islands/

和

runtime/server/render/server-islands.ts

对于生成的输出，追踪可信度较低或仅服务器端的值是否进入客户端包或解释性输出，然后应用所属子系统的验证、转义和序列化契约。

Runtime, State, and Generated Output

运行时、状态与生成输出

Astro-generated SSR code must run on non-Node runtimes such as Cloudflare Workers and Deno. Classify where code executes; do not infer safety only from the source file's location.

Inspect these boundaries carefully:

Within
```
packages/astro/src
```
, files inside a
```
runtime/
```
directory and files named
```
*runtime*.ts
```
must not use Node.js APIs.
Code emitted in a virtual module or generated source string is runtime code even when a Node-compatible Vite plugin creates it.
A Vite plugin implementation may use Node.js APIs, but the virtual modules and values it emits must remain portable.
```
packages/astro/src/core/
```
contains mixed execution contexts. Trace whether changed code enters generated or production SSR output.
For integrations and adapters, establish the declared target runtime before reporting Node.js usage. Node-specific adapter runtime code is allowed to depend on Node.js.
Test-only Node.js usage is not a runtime leak.

Check both direct and transitive dependencies introduced by the change:

```
node:*
```
and bare Node built-in imports
```
process
```
,
```
Buffer
```
,
```
require
```
,
```
__dirname
```
, and other Node-specific globals
imports and re-exports whose implementation depends on Node.js
dependencies or package export paths that only work in Node.js
generated code containing any of the above

Follow newly introduced import chains far enough to establish the execution boundary. The absence of a direct

node:*

import does not establish portability.

Astro生成的SSR代码必须在非Node运行时（如Cloudflare Workers和Deno）运行。对代码执行位置进行分类；不要仅从源文件位置推断安全性。

仔细检查以下边界：

在
```
packages/astro/src
```
内，
```
runtime/
```
目录下的文件和命名为
```
*runtime*.ts
```
的文件不得使用Node.js API。
虚拟模块或生成的源字符串中输出的代码即使由兼容Node的Vite插件创建，也属于运行时代码。
Vite插件实现可以使用Node.js API，但它输出的虚拟模块和值必须保持可移植性。
```
packages/astro/src/core/
```
包含混合执行上下文。追踪修改的代码是否进入生成或生产SSR输出。
对于集成和适配器，在报告Node.js使用情况前确定声明的目标运行时。特定于Node的适配器运行时代码允许依赖Node.js。
仅测试用的Node.js使用不属于运行时泄漏。

检查变更引入的直接和间接依赖：

```
node:*
```
和裸Node内置导入
```
process
```
、
```
Buffer
```
、
```
require
```
、
```
__dirname
```
和其他Node特定全局变量
其实现依赖Node.js的导入和重新导出
仅在Node.js中有效的依赖项或包导出路径
包含上述内容的生成代码

追踪新引入的导入链，足以确定执行边界。没有直接

node:*

导入并不代表可移植性。

State Ownership and Pipeline Parity

状态所有权与管道一致性

Astro separates request state from state shared by the application or build:

```
RenderContext
```
and
```
FetchState
```
contain per-request data such as the request, URL, route, params, cookies, locals, and response state.
```
Environment
```
and
```
Pipeline
```
are created outside an individual request and may be reused across requests. Do not place request-specific mutable data on them.

When pipeline behavior changes, trace every applicable implementation: runnable development, non-runnable development, build/prerender, production SSR, and the Container API. Do not require irrelevant variants, but do not assume behavior exercised by one pipeline automatically reaches the others.

Use

core/render/README.md

and

astro-developer/architecture.md

to establish these boundaries.

Use these repository sources as the authoritative starting points:

```
CONTRIBUTING.md
```
, "Naming convention and APIs usage"
```
biome.jsonc
```
, the
```
noNodejsModules
```
runtime overrides
```
astro-developer/constraints.md
```
, "Node.js API Restrictions"

Astro将请求状态与应用或构建共享的状态分离：

```
RenderContext
```
和
```
FetchState
```
包含每个请求的数据，例如请求、URL、路由、参数、Cookie、本地变量和响应状态。
```
Environment
```
和
```
Pipeline
```
在单个请求外部创建，可跨请求复用。请勿将特定于请求的可变数据放在它们上面。

当管道行为变更时，追踪所有适用的实现：可运行开发模式、不可运行开发模式、构建/预渲染、生产SSR和Container API。不需要无关变体，但不要假设一个管道执行的行为会自动覆盖其他管道。

使用

core/render/README.md

和

astro-developer/architecture.md

确定这些边界。

使用以下仓库源作为权威起点：

```
CONTRIBUTING.md
```
，"命名约定和API使用"
```
biome.jsonc
```
，
```
noNodejsModules
```
运行时覆盖
```
astro-developer/constraints.md
```
，"Node.js API限制"

Astro Feature, API, and Monorepo Completeness

Astro功能、API与单体仓库完整性

Apply these checks only when the changed area makes them relevant. Search the surrounding subsystem rather than assuming this list is exhaustive.

仅当变更区域相关时应用这些检查。搜索周边子系统而非假设此列表详尽无遗。

Configuration and Runtime Transport

配置与运行时传输

A new or changed Astro configuration option may need coordinated updates to:

the hand-maintained public configuration type and its generated documentation
defaults and the base, relative, and refined schemas
integration update validation
build settings and manifest serialization/deserialization
every applicable development, build, prerender, and production consumer
applicable runtime and compile-time type tests

Use

core/config/schemas/README.md

to understand the three-schema model. If configuration must survive into production, trace it from user config through the serialized

SSRManifest

and back into the runtime environment.

新的或修改的Astro配置选项可能需要协调更新：

手动维护的公共配置类型及其生成的文档
默认值以及基础、相对和细化的模式
集成更新验证
构建设置和清单序列化/反序列化
每个适用的开发、构建、预渲染和生产消费者
适用的运行时和编译时类型测试

使用

core/config/schemas/README.md

理解三模式模型。如果配置必须保留到生产环境，追踪其从用户配置到序列化

SSRManifest

再回到运行时环境的过程。

Public Types and Package Exports

公共类型与包导出

Types under

packages/astro/src/types/public/

are public API and follow semver. For public type or API changes, check backward compatibility, editor-facing documentation, and compile-time contract tests under

packages/astro/test/types/

When exports change:

Public Astro exports belong in both
```
exports
```
and
```
publishConfig.exports
```
.
Workspace-only internals belong under an explicit
```
./_internal/*
```
subpath and only in the monorepo export map.
Other workspace packages should use declared subpaths instead of deep relative imports into another package.

Follow the "Public vs. internal API" section in

CONTRIBUTING.md

packages/astro/src/types/public/

下的类型是公共API，遵循语义化版本控制。对于公共类型或API变更，检查向后兼容性、面向编辑器的文档以及

packages/astro/test/types/

下的编译时契约测试。

当导出变更时：

公共Astro导出应同时存在于
```
exports
```
和
```
publishConfig.exports
```
中。
仅工作区内部的代码应放在显式的
```
./_internal/*
```
子路径下，且仅在单体仓库导出映射中。
其他工作区包应使用声明的子路径，而非深度相对导入到另一个包。

遵循

CONTRIBUTING.md

中的"公共与内部API"部分。

Dependencies and Project References

依赖项与项目引用

When package dependencies change:

Dependencies on local workspace packages in packages, test fixtures, and examples should use
```
workspace:*
```
.
External dependencies should use
```
catalog:
```
when the root catalog already owns the version.
Runtime dependencies must be declared in the package that imports them and must be compatible with that package's execution environments.
A package's TypeScript build references should mirror its workspace dependencies.
A new package needs the standard build/test solution files and a reference from the root
```
tsconfig.json
```
.

Do not inspect or report missing dependent-package version bumps or internal dependency-range updates that arise solely because another workspace package is being released. Changesets computes these propagation updates from

.changeset/config.json

when release versions are applied, so feature pull requests should not make them manually. Continue to check dependency declarations, workspace protocols, runtime compatibility, TypeScript references, and directly modified packages against the changeset criteria below.

Use the "TypeScript project references" section in

CONTRIBUTING.md

and the package-boundary guidance in

astro-developer/constraints.md

当包依赖变更时：

包、测试 fixture 和示例中对本地工作区包的依赖应使用
```
workspace:*
```
。
外部依赖项在根目录catalog已管理版本时应使用
```
catalog:
```
。
运行时依赖项必须在导入它们的包中声明，且必须与该包的执行环境兼容。
包的TypeScript构建引用应与其工作区依赖项一致。
新包需要标准的构建/测试解决方案文件，以及根目录
```
tsconfig.json
```
的引用。

请勿检查或报告仅因另一个工作区包即将发布而产生的依赖包版本缺失或内部依赖范围更新。Changesets在应用发布版本时会从

.changeset/config.json

计算这些传播更新，因此功能拉取请求不应手动进行这些操作。继续检查依赖声明、工作区协议、运行时兼容性、TypeScript引用以及直接修改的包是否符合以下变更集标准。

使用

CONTRIBUTING.md

中的"TypeScript项目引用"部分和

astro-developer/constraints.md

中的包边界指南。

Generated Files and Feature Registries

生成文件与功能注册表

Identify generated files from their headers and repository scripts. Review the human-authored source of truth, confirm checked-in generated output corresponds to it when applicable, and do not treat minified or generated code as independently designed source. Never run the generator during this review.

When adding a feature, handler, enum member, or manifest field, search for parallel registration points such as serializers, deserializers, feature flags, warning checks, export maps, and tests. Prefer reading a subsystem README or a matching document under

reference/

over embedding a hard-coded inventory in the review. For example, changes to dependency optimization or fetch handlers should consult

reference/optimize-deps.md

reference/handlers.md

, respectively.

从文件头和仓库脚本识别生成文件。审查人工编写的真实源，确认已签入的生成输出（如适用）与其对应，不要将压缩或生成的代码视为独立设计的源代码。审查期间绝不运行生成器。

当添加功能、处理程序、枚举成员或清单字段时，搜索并行注册点，例如序列化器、反序列化器、功能标志、警告检查、导出映射和测试。优先阅读子系统README或

reference/

下的匹配文档，而非在审查中嵌入硬编码清单。例如，依赖优化或fetch处理程序的变更应分别查阅

reference/optimize-deps.md

或

reference/handlers.md

。

Error Handling and Failure Behavior

错误处理与失败行为

Treat filesystem reads and writes,

JSON.parse()

, network access, serialization, and promises as fallible operations. Determine which layer owns recovery before deciding that a local

try/catch

is needed.

Good handling may take different forms:

Recover locally from an expected failure with a safe, intentional fallback.
Distinguish expected errors such as a missing optional file from corruption, permission failures, and other unexpected errors.
Propagate the original error to an established caller or application boundary that can handle it.
Wrap an error in the repository's domain error type with useful operation and path context while preserving its
```
cause
```
.
Clean up resources or temporary state in
```
finally
```
when later operations can fail.

Report handling that can cause real harm, including:

empty or broad catches that silently convert unexpected failures into success
defaults that hide corrupt input, permission failures, or incomplete state
lost error causes or messages that omit the failed operation or relevant path
unawaited promises or rejected work that escapes the owning lifecycle
continuing after a failed read, parse, or write with partial or invalid data
writes that can expose partial state when the surrounding contract requires atomicity
parse results trusted as a type without validation when the input crosses a trust boundary
missing cleanup after a failed multi-step operation

Do not recommend

try/catch

solely because an operation can throw. Propagation is correct when the caller owns error presentation or recovery. Match established Astro error and logging patterns in nearby code rather than imposing a generic wrapper.

Check whether tests exercise meaningful failure paths, including malformed data and expected I/O failures, when those paths are part of the changed behavior.

When the change adds or modifies an Astro error contract, also check that:

stable error names are not renamed or reused for a different condition
the error uses established
```
AstroErrorData
```
patterns and preserves the underlying cause
user-facing text explains what happened, why, and what action to take
```
@docs
```
metadata is present or updated when the error belongs in the generated reference

Use

core/errors/README.md

for Astro-specific error requirements.

将文件系统读写、

JSON.parse()

、网络访问、序列化和Promise视为可能失败的操作。在决定是否需要本地

try/catch

之前，确定哪个层负责恢复。

良好的处理方式可能有以下形式：

从预期失败中本地恢复，使用安全、有意的回退方案。
区分预期错误（如缺少可选文件）与损坏、权限失败和其他意外错误。
将原始错误传播到已确定的调用方或应用边界，使其能够处理。
使用有用的操作和路径上下文将错误包装到仓库的领域错误类型中，同时保留其
```
cause
```
。
当后续操作可能失败时，在
```
finally
```
中清理资源或临时状态。

报告可能造成实际危害的处理方式，包括：

空的或宽泛的catch块，将意外失败无声转换为成功
隐藏损坏输入、权限失败或不完整状态的默认值
丢失错误原因或消息，省略失败操作或相关路径
未等待的Promise或被拒绝的任务，脱离所属生命周期
在读取、解析或写入失败后继续使用部分或无效数据
当周围契约要求原子性时，可能暴露部分状态的写入操作
当输入跨越信任边界时，未经验证就将解析结果视为类型可信
多步操作失败后缺少清理

请勿仅因操作可能抛出就建议

try/catch

。当调用方负责错误呈现或恢复时，传播是正确的做法。匹配附近代码中已建立的Astro错误和日志模式，而非强加通用包装器。

检查测试是否涵盖有意义的失败路径，包括格式错误的数据和预期的I/O失败（当这些路径属于变更行为的一部分时）。

当变更添加或修改Astro错误契约时，还需检查：

稳定的错误名称未被重命名或用于不同条件
错误使用已建立的
```
AstroErrorData
```
模式，并保留根本原因
面向用户的文本解释了发生的情况、原因以及应采取的操作
当错误属于生成的参考文档时，存在或更新了
```
@docs
```
元数据

使用

core/errors/README.md

获取Astro特定的错误要求。

Test Coverage

测试覆盖

Review test code statically; never run it.

A bug fix should include a regression case that would fail without the fix.
A feature should cover its observable behavior and meaningful branches, boundaries, and failure modes.
Runtime-sensitive behavior may need coverage for relevant build, SSR, adapter, or platform contexts.
Prefer testing public behavior. A focused direct test is useful when a self-contained function contains substantial branching or a domain invariant.
Do not demand one test per function or tests for type-system guarantees.
Verify that assertions would fail when the changed behavior regresses; tests are not sufficient merely because they execute the new lines.
Prefer the smallest appropriate test layer. Use integration or end-to-end coverage only when the behavior cannot be established with a focused unit test.
Unit tests belong in the package's
```
test/units/
```
, use
```
node:test
```
and
```
node:assert/strict
```
, import built
```
dist/
```
output, and should reuse existing test helpers.
Public type contracts belong in the package's type-test suite.
Integration fixtures must use isolated output directories and workspace dependencies so parallel tests cannot share generated state.

Every missing-test finding must name the untested scenario and the defect that the test would detect. Do not write generic findings such as "add more tests."

Use

reference/unit-testing.md

for test placement, imports, and available helpers. Confirm that a new test file is selected by the package's test scripts; a test that is never discovered provides no coverage.

静态审查测试代码；绝不运行测试。

错误修复应包含一个回归用例，若无修复则该用例会失败。
功能应涵盖其可观察行为以及有意义的分支、边界和失败模式。
运行时敏感行为可能需要针对相关构建、SSR、适配器或平台上下文的覆盖。
优先测试公共行为。当独立函数包含大量分支或领域不变量时，聚焦的直接测试非常有用。
无需为每个函数编写测试，也无需为类型系统保障编写测试。
验证断言在变更行为回归时会失败；仅执行新代码行的测试是不够的。
优先使用最小的合适测试层。仅当行为无法通过聚焦的单元测试确定时，才使用集成或端到端覆盖。
单元测试应放在包的
```
test/units/
```
目录下，使用
```
node:test
```
和
```
node:assert/strict
```
，导入构建的
```
dist/
```
输出，并应重用现有测试工具函数。
公共类型契约属于包的类型测试套件。
集成fixture必须使用隔离的输出目录和工作区依赖项，以便并行测试不会共享生成的状态。

每个缺失测试的结果必须指明未测试的场景以及该测试将检测到的缺陷。请勿编写诸如"添加更多测试"之类的通用结果。

使用

reference/unit-testing.md

获取测试放置、导入和可用工具函数的信息。确认新测试文件被包的测试脚本选中；未被发现的测试无法提供覆盖。

DRY, KISS, and Function Boundaries

DRY、KISS与函数边界

DRY and KISS can conflict. Duplication is sometimes simpler than an abstraction that couples unrelated behavior.

Report a DRY opportunity when duplicated code represents the same domain rule or invariant, must evolve together, or reimplements an existing repository helper. Do not suggest abstraction for code that is merely syntactically similar.

Report a KISS opportunity when the change adds avoidable indirection, speculative configurability, generic machinery for one concrete case, premature caching or fast paths, or layers that obscure a straightforward data flow.

Evaluate extracted functions by the boundary they create, not only by call count:

A single-use function can be justified when it names a domain operation, isolates a meaningful invariant, reduces cognitive load, or enables a focused test of non-trivial behavior.
A single-use function is questionable when it only renames a trivial expression, requires jumping between files without hiding complexity, or is generalized for hypothetical reuse.
Reuse alone does not justify a function, and one call site alone does not justify inlining it.

For performance-oriented code, look for evidence that the optimization is needed and verify that its complexity, invalidation, and fallback behavior remain correct. Flag premature optimization only when the simpler implementation meets the known requirement.

DRY（避免重复）和KISS（保持简洁）可能冲突。有时重复代码比耦合无关行为的抽象更简单。

当重复代码代表相同的领域规则或不变量、必须共同演进或重新实现现有仓库工具函数时，报告DRY复用机会。请勿仅因代码在语法上相似就建议抽象。

当变更添加不必要的间接性、推测性可配置性、针对单个具体案例的通用机制、过早的缓存或快速路径，或模糊直接数据流的层时，报告KISS简化机会。

通过函数创建的边界而非仅调用次数评估提取的函数：

当函数命名领域操作、隔离有意义的不变量、减少认知负荷或启用对非平凡行为的聚焦测试时，单次使用的函数是合理的。
当函数仅重命名平凡表达式、需要在文件间跳转却未隐藏复杂性，或为假设的复用而泛化时，单次使用的函数值得商榷。
复用本身不足以证明函数的合理性，单个调用点也不足以证明内联的合理性。

对于面向性能的代码，寻找优化必要的证据，并验证其复杂性、失效处理和回退行为是否保持正确。仅当更简单的实现满足已知需求时，才标记过早优化。

Comments and Behavior Documentation

注释与行为文档

Load and apply the

writing-comments

skill as the canonical guidance. Review comments and behavior documentation added or changed by the diff, plus existing documentation made false or incomplete by the changed behavior. Do not audit unrelated comments in the surrounding file.

Keep comment findings non-invasive. Report inaccurate or misleading documentation as a finding when it can lead callers or maintainers to incorrect behavior. Put a missing explanation under suggestions unless an undocumented contract, invariant, or public caveat creates a concrete correctness or compatibility risk.

加载并应用

writing-comments

技能作为规范指南。审查差异中添加或修改的注释和行为文档，以及因变更行为而变得虚假或不完整的现有文档。请勿审核周边文件中无关的注释。

保持注释结果的非侵入性。当文档不准确或具有误导性可能导致调用方或维护者行为错误时，将其报告为结果。除非未记录的契约、不变量或公共警告会造成具体的正确性或兼容性风险，否则将缺失的解释归为建议。

Changeset Coverage

变更集覆盖

Require a pending changeset for each package whose non-test source is directly modified when the change affects its user-facing API, including observable API behavior. Test-only changes and changes outside packages, including

examples/

, do not require one by themselves. Follow the current repository policy in

CONTRIBUTING.md

and use the

changeset

skill as the format reference.

Check for a newly added
```
.changeset/*.md
```
file in the review scope. Configuration, README, and prerelease metadata files are not pending changesets.
For each qualifying source change, confirm the changeset frontmatter names the package containing that source.
Do not require a package in changeset frontmatter solely because it depends on another package receiving a bump; Changesets handles that dependent bump during release versioning.
Report a missing or ineffective changeset as a finding.
Do not invoke the changeset skill or create or edit a changeset.

当变更影响包的面向用户的API（包括可观察的API行为）时，每个直接修改非测试源代码的包都需要一个待处理的变更集。仅测试变更和包外变更（包括

examples/

）本身不需要变更集。遵循

CONTRIBUTING.md

中的当前仓库策略，并使用

changeset

技能作为格式参考。

检查审查范围内是否有新增的
```
.changeset/*.md
```
文件。配置文件、README和预发布元数据文件不属于待处理变更集。
对于每个符合条件的源代码变更，确认变更集前置元数据命名了包含该源代码的包。
请勿仅因包依赖另一个将被升级的包就要求在变更集前置元数据中包含该包；Changesets在发布版本控制期间会处理依赖升级。
将缺失或无效的变更集报告为结果。
请勿调用changeset技能或创建/编辑变更集。

Finding Threshold

结果阈值

Report only issues that are actionable and supported by the inspected code.

Explain the input, call path, runtime, or maintenance condition that triggers the problem.
Explain the resulting incorrect behavior or concrete long-term cost.
Point to the smallest relevant changed line or range.
Give a minimal remediation direction without writing the patch.
For a security finding, identify the attacker-controlled input or weakened boundary, the reachable sink or bypassed defense, and the concrete impact.
Put uncertain requirements or design choices under questions, not findings.
Avoid formatter, naming, and stylistic comments unless they violate an explicit repository standard and materially reduce correctness or maintainability.
Consolidate repeated symptoms with the same root cause into one finding and list the affected locations instead of repeating the comment.
List optional improvements after required findings. Do not use severity to make a personal preference appear mandatory.

仅报告可执行且有检查代码支持的问题。

说明触发问题的输入、调用路径、运行时或维护条件。
说明由此产生的错误行为或具体长期成本。
指向最小的相关修改行或范围。
给出最小的修复方向，无需编写补丁。
对于安全结果，识别攻击者可控的输入或弱化的边界、可访问的接收端或被绕过的防御，以及具体影响。
将不确定的需求或设计选择归为问题，而非结果。
除非违反明确的仓库标准并实质性降低正确性或可维护性，否则避免格式化、命名和风格相关的评论。
将具有相同根本原因的重复症状合并为一个结果，并列出受影响的位置，而非重复评论。
在必填结果后列出可选改进。请勿使用严重性将个人偏好伪装成强制性要求。

Report Format

报告格式

Return the complete review as raw, unrendered Markdown inside a single fenced code block. Put no text before or after the code block, and do not escape Markdown syntax inside it. The code block's contents must be directly pasteable into a GitHub comment.

Put findings first, order required findings by severity, and list optional improvements last. Do not lead with a summary or praise.

Use exactly one severity and one primary category per finding. Required findings use

high

medium

, or

low

; non-blocking improvements use

optional

```
high
```
: credible exploitation, data loss, broad regression, incompatible behavior, or likely runtime breakage
```
medium
```
: credible edge-case failure, weakened security defense, missing required failure handling, or material test gap
```
low
```
: localized correctness, maintainability, documentation, or process issue with limited impact that should still be addressed
```
optional
```
: non-blocking improvement with a concrete benefit

Use one of these categories:

design

correctness

security

runtime

completeness

error-handling

tests

maintainability

documentation

, or

changeset

. Choose the category that describes the root cause rather than a downstream symptom.

completeness

covers missing API, configuration, export, dependency, generated-file, or registry wiring.

Use this structure:

```

将完整审查结果作为原始、未渲染的Markdown返回在单个围栏代码块中。代码块前后不要添加任何文本，也不要转义其中的Markdown语法。代码块内容必须可直接粘贴到GitHub评论中。

先列出结果，按严重性排序必填结果，最后列出可选改进。不要以摘要或赞美开头。

每个结果使用恰好一个严重性和一个主类别。必填结果使用

high

、

medium

或

low

；非阻塞改进使用

optional

。

```
high
```
：可信的利用、数据丢失、广泛回归、不兼容行为或可能的运行时中断
```
medium
```
：可信的边缘情况失败、弱化的安全防御、缺失的必要失败处理或重大测试缺口
```
low
```
：局部正确性、可维护性、文档或流程问题，影响有限但仍需处理
```
optional
```
：非阻塞改进，具有具体收益

使用以下类别之一：

design

、

correctness

、

security

、

runtime

、

completeness

、

error-handling

、

tests

、

maintainability

、

documentation

或

changeset

。选择描述根本原因而非下游症状的类别。

completeness

涵盖缺失的API、配置、导出、依赖项、生成文件或注册表连接。

使用以下结构：

```

Findings

```
[high][security]
```
```
path/to/file.ts:42
```
- Short title. Explain the triggering scenario, impact, and minimal remediation direction.
```
[medium][correctness]
```
```
path/to/file.ts:87
```
- Short title. Explain the triggering scenario, impact, and minimal remediation direction.
```
[low][documentation]
```
```
path/to/file.ts:110
```
- Short title. Explain the concrete problem and why it should be addressed.
```
[optional][maintainability]
```
```
path/to/file.ts:125
```
- Explain the non-blocking improvement and its concrete benefit.

```
[high][security]
```
```
path/to/file.ts:42
```
- 简短标题。说明触发场景、影响和最小修复方向。
```
[medium][correctness]
```
```
path/to/file.ts:87
```
- 简短标题。说明触发场景、影响和最小修复方向。
```
[low][documentation]
```
```
path/to/file.ts:110
```
- 简短标题。说明具体问题及为何需要处理。

[optional][maintainability]

path/to/file.ts:125

- 说明非阻塞改进及其具体收益。

Questions

Include only unresolved assumptions that affect correctness. Omit this section when there are none.

仅包含影响正确性的未解决假设。若无则省略此部分。

Review Status

Scope:

<base>

through the current working tree, plus listed untracked files. Changeset: present and covers

<packages>

| missing for

<packages>

| not required. Validation: Static review only; no project code, tests, builds, or checks were run. Fetch: updated

origin/main

| fetch failed and local

origin/main

was used | not needed for the supplied scope.

undefined

Severity reflects impact, not confidence.

If there are no required or optional findings, write

No findings.

under

## Findings

. Still include review status and mention any residual uncertainty caused by unavailable requirements or context.

Scope:

<base>

到当前工作树，加上列出的未跟踪文件。 Changeset: 已存在并覆盖

<packages>

| 缺失

<packages>

的变更集 | 不需要。 Validation: 仅静态审查；未运行项目代码、测试、构建或检查。 Fetch: 更新了

origin/main

| fetch失败，使用本地

origin/main

| 提供的范围不需要。

undefined

严重性反映影响，而非置信度。

如果没有必填或可选结果，请在

## Findings

下写入

No findings.

。仍需包含审查状态，并提及因需求或上下文不可用导致的任何剩余不确定性。