Fu-Jie_openwebui-extensions/.github/gh-aw/review-mirrors/aw-release-preflight.zh.md

aw-release-preflight 中文对照

对应源文件：.github/workflows/aw-release-preflight.md

用途：这是一份给维护者 review 用的中文对照说明，不是 gh-aw 工作流源文件，也不参与 gh aw compile。

工作流定位

这个工作流的目标是对触发变更做一次“发布前预检语义审查”。

它不是发布执行器，也不是自动补版本工具，而是用于判断：

• 这次改动是否真的在做 release-prep
• 如果是在做 release-prep，版本同步是否完整
• 双语 README、docs 镜像、release notes 是否齐全
• 是否存在会影响发布质量的说明缺失或文档漂移

如果当前变更并不是发布准备，或者已经足够一致、没有可操作反馈，就执行 noop。

Frontmatter 对照

触发方式

• pull_request
  • 类型：opened、reopened、synchronize、ready_for_review
  • 路径限制：
    • plugins/**/*.py
    • plugins/**/README.md
    • plugins/**/README_CN.md
    • plugins/**/v*.md
    • plugins/**/v*_CN.md
    • docs/plugins/**/*.md
    • README.md
    • README_CN.md
    • .github/**
• workflow_dispatch
• roles: all
• skip-bots
  • github-actions
  • copilot
  • dependabot
  • renovate

权限

当前设计为只读：

• contents: read
• issues: read
• pull-requests: read

说明：工作流不会发 release、不会推代码、不会改文件。

Safe Outputs

已配置：

• add-comment
  • 目标：当前触发 PR
  • 最多 1 条
  • 隐藏旧评论
  • 不加 footer

最终只能二选一：

• 有问题时执行 add_comment
• 无问题时执行 noop

工具

• github
  • repos
  • issues
  • pull_requests
• bash
  • 仅开放只读类命令，如 pwd、ls、cat、rg、git diff、git show

正文指令对照

主要目标

要求代理检查：

• 版本同步完整性
• 双语 README 与 docs 一致性
• release notes 完整性
• 发布面索引或 badge 漂移
• 用户可见发布是否缺失迁移说明或维护者上下文

明确限制：

• 只做 review
• 不改文件
• 不推代码
• 不创建 release
• 不创建 PR

高优先级依据文件

在形成结论前，优先把这些文件当成“发布规则源”：

• .github/copilot-instructions.md
• .github/instructions/commit-message.instructions.md
• .github/skills/release-prep/SKILL.md
• .github/skills/doc-mirror-sync/SKILL.md
• .github/workflows/release.yml
• docs/development/gh-aw-integration-plan.md
• docs/development/gh-aw-integration-plan.zh.md

审查范围

• 从 PR diff 和 changed files 开始
• 只有在验证发布同步时才扩展到相关 release-facing 文件
• 优先遵循仓库既有 release-prep 规则，而不是泛泛的 release 建议

换句话说，它应该像“合并前最后做一致性复核的维护者”。

重点检查项

1. 发布相关文件中的版本同步

当某个插件明显在准备发版时，检查这些位置是否同步：

• 插件 Python docstring 的 version:
• 插件目录下 README.md
• 插件目录下 README_CN.md
• docs/plugins/** 英文镜像页
• docs/plugins/**/*.zh.md 中文镜像页
• docs/plugins/{type}/index.md 中该插件的条目或版本 badge
• docs/plugins/{type}/index.zh.md 中该插件的条目或版本 badge

但只有在“这次改动明显带有发布意图”时才提示，不要把所有 PR 都按发布处理。

2. README 与 docs 镜像一致性

当插件 README 变化时，检查 docs 镜像是否同步。

路径映射：

• plugins/actions/{name}/README.md -> docs/plugins/actions/{name}.md
• plugins/actions/{name}/README_CN.md -> docs/plugins/actions/{name}.zh.md
• plugins/filters/{name}/README.md -> docs/plugins/filters/{name}.md
• plugins/filters/{name}/README_CN.md -> docs/plugins/filters/{name}.zh.md
• plugins/pipes/{name}/README.md -> docs/plugins/pipes/{name}.md
• plugins/pipes/{name}/README_CN.md -> docs/plugins/pipes/{name}.zh.md
• plugins/pipelines/{name}/README.md -> docs/plugins/pipelines/{name}.md
• plugins/pipelines/{name}/README_CN.md -> docs/plugins/pipelines/{name}.zh.md
• plugins/tools/{name}/README.md -> docs/plugins/tools/{name}.md
• plugins/tools/{name}/README_CN.md -> docs/plugins/tools/{name}.zh.md

如果是纯文档调整、而且并非发版预备，不要过度报错。

3. What's New 与 Release Notes 覆盖度

当这次更新明显是发布面插件更新时，检查：

• What's New 是否只反映最新版本
• 最新更新 是否与英文对应
• 是否存在 v{version}.md 和 v{version}_CN.md
• release notes 是否覆盖当前 diff 中有意义的功能、修复、文档或迁移变化

对纯内部小改动，不要强制要求 release notes。

4. 根 README 与发布面索引漂移

当改动明显面向正式发布时，再检查：

• 根 README.md 的日期 badge
• 根 README_CN.md 的日期 badge
• docs/plugins/**/index.md
• docs/plugins/**/index.zh.md

不要把这种检查强加给普通内部 PR。

5. 维护者上下文与发布清晰度

检查 PR 描述或发布面文案是否缺少关键上下文：

• 这次到底发布了什么
• 为什么这次发布值得做
• 是否需要迁移或重新配置

只有在缺失信息会明显增加 release review 成本时，才提示。

严重级别

只允许三档：

• Blocking
  • 高概率发布回归、缺少必要版本同步、发布面更新明显不完整
• Important
  • 合并前最好修，避免发布混乱或文档漂移
• Minor
  • 可选的发布面清理或一致性建议

并且明确要求：

• 不要为了留言而造问题

评论格式

如果要评论，必须只有一条总结评论。

要求：

• 英文
• 简洁
• 先给 findings，不先夸赞
• 带可点击路径引用
• 不使用嵌套列表
• 不要机械复述 diff

固定结构：

## Release Preflight Review

### Blocking
- `path/to/file`: specific release-facing problem and why it matters

### Important
- `path/to/file`: missing sync or release-documentation gap

### Minor
- `path/to/file`: optional cleanup or consistency improvement

### Release Readiness
- Ready after the items above are addressed.

补充规则：

• 空 section 要省略
• 如果只有一个严重级别，只保留那个 section 和 Release Readiness
• 正常情况下控制在约 250 词以内

No-Comment 规则

如果没有有意义的发布前预检反馈：

• 不要发“看起来不错”这类表扬评论
• 不要复述 checks passed
• 直接走 noop

示例：

{"noop": {"message": "No action needed: reviewed the release-facing diff, version-sync expectations, and bilingual documentation coverage, and found no actionable preflight feedback."}}

建议执行流程

1. 判断这次改动是否真的带有发布意图
2. 检查 PR diff 中的变更文件
3. 读取仓库的 release-prep 规则文件
4. 只有在存在发布意图时，才检查 plugin version sync
5. 检查 README、README_CN、docs 镜像、索引和 release notes 是否漂移
6. 起草最短但有用的维护者总结
7. 最终只执行一次 add_comment 或一次 noop

额外约束

• 不要把完整 release-prep 要求硬套到微小内部改动上
• 非明确发布型 PR，不要强制要求根 README 日期 badge 更新
• 如果这次改动并不现实地构成发版预备，就不要强求 release notes
• 优先给出仓库特定的同步反馈，而不是泛泛的发布建议
• 如果不确定某个 release-facing 同步文件是否必需，把级别降为 Important
• 如果问题依赖“推测出来的意图”，要用条件式表述，不要装作确定

最终要求

必须以且仅以一次 safe output 结束：

• 有可操作反馈：add_comment
• 无可操作反馈：noop