Astro PR 编写器
编写有助于审阅者快速理解意图、行为变更和验证的 Astro 拉取请求描述。
当用户提出任何与 PR 编写相关的任务时使用此技能，包括：
- 创建/打开一个拉取请求
- 创建/打开一个草稿拉取请求
- 更新 PR 标题
- 更新 PR 正文/描述
- 撰写 PR 注释/摘要
核心原则
描述变更、工作原理以及为什么重要。
Changes解释修复/功能的作用。Testing列出添加或修改了哪些测试代码。Docs说明是否需要面向用户的文档变更。
不要将 PR 各节用作任务日志。
PR 标题规则
使用人类可读、审阅者友好的标题。
- 用平实的语言描述结果。
- 保持简洁且具体。
- 优先使用审阅者在队列中自然看到的措辞。
不要使用：
- 传统提交前缀（
fix:、feat:、docs:等） - 带有作用域的提交风格标题（
fix(cloudflare): ...）
正文规则
使用以下结构：
## Changes
- <行为变更及其重要性>
- <实现细节及影响>
## Testing
- <新增或修改的测试及其覆盖范围>
- <为什么现有断言发生了变更>
## Docs
- <无需文档更新，因为……>
Changes
关注行为、实现方法和影响。
包括：
- 之前不能工作但现在可以工作的内容
- 修复/功能的工作原理（对审阅者有帮助的级别）
- 用户可见的可靠性/兼容性/性能行为变化
不要包括：
- “已添加测试”或“已更新 fixture”（属于
Testing部分） - “已添加 changeset”
- 对行为无影响的内部过程说明
Testing
列出添加或修改的测试代码及其原因。审阅者阅读此部分是为了了解测试覆盖率的变更——而不是听你说运行了测试套件。
包括：
- 新增的测试文件或测试用例，附上简短描述说明它们覆盖了什么
- 更新了哪些现有测试，以及为什么断言发生了变化
不要包括：
- 测试通过（CI 会显示这一点；这属于噪音）
- 你运行了哪些命令
- 通过了多少个测试
Docs
清晰地说明文档影响。
- 如果不需要文档，请用一句话说明原因。
- 如果需要文档，请链接文档 PR。
简洁性指导
默认简短。每个部分 1-2 个要点是正常的——只有当变更确实复杂时才增加更多。扫描 PR 队列的审阅者对于典型的补丁应该能在 30 秒内读完整个正文。
过于冗长：
- 将
server配置属性（位于base.ts和relative.ts中）的.optional().prefault({})移出z.preprocess()，与 #16531 中的integrations修复保持一致。Zod 4.4.0 会拒绝包裹在z.preprocess()内的缺失属性，因为预处理器或内部默认值无法执行——将.optional().prefault({})移出 preprocess 调用即可解决此问题。修复了 @rururux 报告的server属性问题。- 为 Astro 和 DB 错误映射添加了
invalid_key、invalid_element和区分联合options处理程序，以兼容 Zod 4.4.0。Zod 4.4.0 将记录键细化失败（例如 env 架构变量名）作为结构化的invalid_key问题（带有嵌套错误）而不是扁平消息返回。这些处理程序提取实际的细化消息，以提供清晰的用户可见错误。- 所有更改向后兼容 Zod 4.3.x。新的错误映射分支仅在 4.4.0 开始发出的问题代码上激活。
更好的写法：
- 将
server配置的.optional().prefault({})移出z.preprocess()，与 #16531 中的integrations修复保持一致。修复了 @rururux 在那报告的问题。- 为两个错误映射添加了
invalid_key、invalid_element和区分联合options处理程序，以兼容 Zod 4.4.0。- 向后兼容 Zod 4.3.x。
Changesets
每个修改包的 PR 都需要一个 changeset。只有 examples/* 的更改例外。
加载 changeset 技能来创建 changeset 文件并编写消息。它涵盖了文件创建、格式、版本变更类型和消息约定。
在编写 PR 正文时：
- 在发布前，检查是否存在 changeset。如果 PR 修改了一个包且没有 changeset，请立即使用
changeset技能创建它——不要在缺少 changeset 的情况下发布 PR。 - 不要在
Changes部分提及“已添加 changeset”——这是过程噪音，而非行为变更。
发布前自检
- 标题是审阅者友好的（不是提交风格）
Changes要点描述了行为/实现/影响Testing列出了添加/修改的测试代码，而不是测试运行结果Docs决策明确- 对于任何修改包的 PR，
.changeset/目录中存在 changeset 文件——如果缺失，请在发布前创建它