gh-aw 集成方案¶

本文档用于为 openwebui-extensions 仓库设计一套安全、渐进式的 GitHub Agentic Workflows (gh-aw) 接入方案。

1. 目标¶

在不替换现有稳定 CI 的前提下，引入具备仓库理解能力的 AI 维护层。
将 gh-aw 用于更适合自然语言推理的任务，而不是机械脚本执行。
保留当前发布、部署、发布插件和统计工作流作为执行骨架。
为仓库维护引入可观测性、自动诊断和长期记忆能力。

2. 为什么这个仓库适合 gh-aw¶

本仓库已经有一套很强的确定性自动化：

/.github/workflows/release.yml
/.github/workflows/plugin-version-check.yml
/.github/workflows/deploy.yml
/.github/workflows/publish_plugin.yml
/.github/workflows/community-stats.yml

这些工作流擅长精确执行，但并不擅长理解仓库规范本身。

gh-aw 更适合以下任务：

联合阅读代码、文档和 PR 描述后再做判断
带语义地应用仓库规范
生成结构化的 review 评论
自动分析失败的工作流运行
在多次运行之间保存维护经验和模式

这与当前仓库的真实需求高度匹配：

双语文档同步
插件代码、README 与 docs 一致性检查
跨多个文件的发布前完整性核查
Issue 与 PR 的规模化维护

3. 非目标¶

第一阶段不建议让 gh-aw：

替换 release.yml
替换 publish_plugin.yml
替换 MkDocs 部署
默认自动合并或自动推送代码
一开始就拥有过宽的写权限

第一阶段应把它定位为 review、诊断和 preflight 层。

4. 接入原则¶

4.1 确定性执行继续由 YAML 工作流承担¶

现有 YAML workflow 继续负责：

创建 release
发布插件
部署文档
提取和比较版本号
生成社区统计

4.2 Agentic workflow 只负责判断和总结¶

gh-aw workflow 优先承担：

基于规范的语义审查
发布前完整性检查
文档漂移巡检
CI 失败原因分析
Issue 分流与回复草稿生成

4.3 默认只读¶

优先使用最小权限，并通过 safe outputs 进行受控评论或低风险输出。

4.4 逐步扩容¶

一次只上线一个 agentic workflow，验证质量后再扩大范围。

5. 建议的仓库结构¶

5.1 新增文件和目录¶

.github/
├── workflows/
│   ├── release.yml
│   ├── plugin-version-check.yml
│   ├── deploy.yml
│   ├── publish_plugin.yml
│   ├── community-stats.yml
│   ├── aw-pr-maintainer-review.md
│   ├── aw-pr-maintainer-review.lock.yml
│   ├── aw-release-preflight.md
│   ├── aw-release-preflight.lock.yml
│   ├── aw-ci-audit.md
│   ├── aw-ci-audit.lock.yml
│   ├── aw-docs-drift-review.md
│   └── aw-docs-drift-review.lock.yml
├── gh-aw/
│   ├── prompts/
│   │   ├── pr-review-policy.md
│   │   ├── release-preflight-policy.md
│   │   ├── ci-audit-policy.md
│   │   └── docs-drift-policy.md
│   ├── schemas/
│   │   └── review-output-example.json
│   └── README.md
└── copilot-instructions.md

5.2 命名规范¶

所有 agentic workflow 源文件统一使用 aw- 前缀：

aw-pr-maintainer-review.md
aw-release-preflight.md
aw-ci-audit.md
aw-docs-drift-review.md

这样做的原因：

可以和现有手写 YAML 工作流明确区分
便于在仓库中快速搜索和定位
方便调试和发布时识别来源

5.3 为什么不直接替换 `.yml`¶

当前 .yml 文件承担的是生产执行逻辑。第一阶段 gh-aw 的角色应该是补充，而不是接管。

6. 建议优先建设的 workflow 组合¶

6.1 第一阶段：PR 维护者语义审查¶

文件: /.github/workflows/aw-pr-maintainer-review.md

作用:

审查涉及插件、文档或开发规范的 PR
对缺失的仓库标准更新给出评论
作为 plugin-version-check.yml 之上的语义层

建议检查项:

插件代码修改后是否更新版本号
是否同时更新 README.md 和 README_CN.md
是否同步更新 docs 镜像页
是否需要更新根 README 的日期 badge
插件代码是否遵守 i18n 与 helper 规范
PR 标题或正文是否符合 Conventional Commits 精神

建议权限:

permissions:
  contents: read
  pull-requests: write
  issues: write

建议工具:

只读型 github: 工具
只开放少量只读 bash: 命令
第一阶段不开放 edit:
agentic-workflows: 可在后续成熟后再启用

6.2 第一阶段：发布前预检¶

文件: /.github/workflows/aw-release-preflight.md

作用:

在 release 前或手动触发时执行
在 release.yml 打包和发布之前，先检查发布完整性

建议检查项:

代码版本号和文档版本号是否一致
双语 README 是否完整更新
docs 插件镜像页是否存在并匹配当前发布目标
release notes 来源文件是否齐全
commit message 与 release 草案是否连贯

输出方式:

在 PR 或 issue 中写总结评论
可附带 checklist artifact
不直接执行正式发布

6.3 第二阶段：CI 失败自动审计¶

文件: /.github/workflows/aw-ci-audit.md

作用:

分析 release.yml、publish_plugin.yml、community-stats.yml 等关键 workflow 的失败运行
输出根因判断和下一步修复建议

适合 gh-aw 的原因:

可以通过 gh aw mcp-server 使用 logs、audit 等能力
原生支持对 workflow 执行痕迹进行事后分析

6.4 第二阶段：文档漂移巡检¶

文件: /.github/workflows/aw-docs-drift-review.md

作用:

定期检查插件代码、插件目录 README、本地 docs 镜像和根索引之间是否发生漂移

建议检查项:

是否缺少 README_CN.md
README 章节顺序是否偏离规范
插件更新后 docs 页面是否缺失
代码和文档中的版本号是否不一致

6.5 第三阶段：Issue 维护助手¶

候选文件: /.github/workflows/aw-issue-maintainer.md

作用:

汇总长期未回复的 issue
生成英文或双语回复草稿
按插件归类重复问题

这个阶段建议在前面的 review 和 audit 流程稳定后再上线。

7. 与现有 workflow 的职责映射¶

当前 Workflow	是否保留	gh-aw 搭档	职责划分
`/.github/workflows/release.yml`	保留	`aw-release-preflight.md`	`release.yml` 负责执行，`gh-aw` 负责判断是否已准备好
`/.github/workflows/plugin-version-check.yml`	保留	`aw-pr-maintainer-review.md`	硬性门禁 + 语义审查
`/.github/workflows/deploy.yml`	保留	初期不加	确定性构建和部署
`/.github/workflows/publish_plugin.yml`	保留	`aw-ci-audit.md`	确定性发布 + 失败诊断
`/.github/workflows/community-stats.yml`	保留	`aw-ci-audit.md`	确定性统计 + 异常诊断

8. 工具模型建议¶

8.1 第一阶段建议启用的内建工具¶

建议从窄权限工具集开始：

tools:
  github:
    toolsets: [default]
  bash:
    - echo
    - pwd
    - ls
    - cat
    - head
    - tail
    - grep
    - wc
    - git status
    - git diff

第一阶段不要开放完全不受限的 shell。

8.2 MCP 使用策略¶

后续可通过 gh aw mcp-server 引入：

workflow status
workflow compile
workflow logs
workflow audit
mcp-inspect

这对 aw-ci-audit.md 特别有价值。

8.3 Safe output 策略¶

第一阶段仅开放低风险 safe outputs：

给 PR 写评论
给 issue 写评论
在明确需要时创建低风险维护 issue

一开始不要让 agent 自动提交代码修改。

9. Repo Memory 策略¶

gh-aw 的 repo memory 很适合本仓库，但必须加限制。

9.1 第一批适合保存的内容¶

重复出现的 CI 失败模式
常见文档同步遗漏
高频 review 提醒项
按插件聚类的 issue 模式

9.2 推荐配置思路¶

只允许 .md 和 .json
限制 patch size
按主题拆成多个 memory stream

建议的逻辑布局：

memory/review-notes/*.md
memory/ci-patterns/*.md
memory/issue-clusters/*.json

9.3 重要提醒¶

不要把 secret、token 或未公开敏感信息写入 repo memory。

10. 分阶段落地顺序¶

Phase 0: 准备阶段¶

维护者本地安装 gh-aw
添加一个简短的 /.github/gh-aw/README.md
写清楚 workflow 命名规范和 review 预期

Phase 1: 只读语义审查¶

上线 aw-pr-maintainer-review.md
上线 aw-release-preflight.md
输出先限制为总结和评论

Phase 2: 诊断与记忆¶

上线 aw-ci-audit.md
在需要的地方启用 agentic-workflows:
为重复失败模式加入受限 repo-memory

Phase 3: 维护自动化¶

增加文档漂移巡检
增加 issue 维护 workflow
只有在信号质量足够稳定后，再考虑有限度的代码修改建议

11. 维护者本地使用建议¶

11.1 安装 CLI¶

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

11.2 常用命令¶

gh aw version
gh aw compile
gh aw status
gh aw run aw-pr-maintainer-review
gh aw logs
gh aw audit <run-id>

11.3 VS Code MCP 集成¶

后续可选增强项是把 gh aw mcp-server 加入本地 MCP 配置，这样编辑器内的 agent 会直接具备 workflow 自省能力。

12. 最小可行落地建议¶

建议第一步只做这两个 workflow：

aw-pr-maintainer-review.md
aw-release-preflight.md

这样可以以最低风险获得最高价值的增强。

13. 成功标准¶

如果接入有效，应该看到这些结果：

PR 评论更具体，更贴合仓库规范
发布前能更早发现文档或版本同步遗漏
CI 失败后更快得到可执行的总结
维护者花在重复性规范检查上的时间下降
现有确定性 workflow 的核心行为保持稳定

14. 总结¶

对 openwebui-extensions 来说，gh-aw 最合适的定位是智能维护层。

现有 YAML workflow 继续负责执行。
agentic workflow 负责语义审查和诊断。
第一阶段默认只读。
等输出质量稳定后再逐步放权。

这条路径和仓库现状是匹配的：规范密度高、双语维护复杂、插件生命周期长，而且已经具备成熟的 AI 工程上下文。

gh-aw 集成方案¶

1. 目标¶

2. 为什么这个仓库适合 gh-aw¶

3. 非目标¶

4. 接入原则¶

4.1 确定性执行继续由 YAML 工作流承担¶

4.2 Agentic workflow 只负责判断和总结¶

4.3 默认只读¶

4.4 逐步扩容¶

5. 建议的仓库结构¶

5.1 新增文件和目录¶

5.2 命名规范¶

5.3 为什么不直接替换 .yml¶

6. 建议优先建设的 workflow 组合¶

6.1 第一阶段：PR 维护者语义审查¶

6.2 第一阶段：发布前预检¶

6.3 第二阶段：CI 失败自动审计¶

6.4 第二阶段：文档漂移巡检¶

6.5 第三阶段：Issue 维护助手¶

7. 与现有 workflow 的职责映射¶

8. 工具模型建议¶

8.1 第一阶段建议启用的内建工具¶

8.2 MCP 使用策略¶

8.3 Safe output 策略¶

9. Repo Memory 策略¶

9.1 第一批适合保存的内容¶

9.2 推荐配置思路¶

9.3 重要提醒¶

10. 分阶段落地顺序¶

Phase 0: 准备阶段¶

Phase 1: 只读语义审查¶

Phase 2: 诊断与记忆¶

Phase 3: 维护自动化¶

11. 维护者本地使用建议¶

11.1 安装 CLI¶

11.2 常用命令¶

11.3 VS Code MCP 集成¶

12. 最小可行落地建议¶

13. 成功标准¶

14. 总结¶

5.3 为什么不直接替换 `.yml`¶