GitHub 事件驱动研发协作

本实践通过开源 Demo 展示 QoderWake 如何响应 GitHub 事件，让 Release、Developer、Reviewer 和 Tester 四个 Waker 协同完成一次研发交付。GitHub 保存需求、代码和质量证据，QoderWake 执行具体工作，代码合并与正式发布仍由用户确认。 Demo 适合用于功能体验、方案验证和团队演示。将方案用于实际项目之前，应根据团队的分支策略、质量门禁和权限制度重新配置。

了解交付流程

GitHub 事件依次唤醒对应 Waker；代码 PR 和发布 PR 均保留人工合并门禁。

Waker	负责的工作	不执行的工作
Release	创建迭代分支、准备发布 PR、创建 Tag 和 GitHub Release、关闭 Milestone	不修改业务代码，不替用户合并 PR
Developer	读取需求和验收标准、完成开发和自测、创建或更新代码 PR	不为自己的代码给出评审通过结论
Reviewer	针对当前 head SHA 阅读 Diff、检查 CI、独立测试并回写评审结论	不修改代码，不代替用户合并
Tester	在代码合入迭代分支后独立验收；失败时创建包含复现证据的 Bug	不跳过失败项，不伪造测试通过结论

测试发现 Bug 后，任务会回到 Developer，重新经过开发、评审、人工合并和复测。测试通过后，Release Waker 才开始准备正式发布。

准备运行环境

运行 Demo 前准备以下环境：

Node.js 20 或更高版本、Git 和 GitHub CLI。
已登录并保持运行的 QoderWake。
可创建 Waker 和自动任务的 QoderWake 账号。
可操作目标仓库、GitHub Actions 和 Actions Secrets 的 GitHub 账号。
用于调用 QoderWake API 自动任务的个人访问令牌（PAT）。令牌的创建和保管方式参见配置 API 触发。

建议首次使用独立的测试仓库和测试账号权限范围，不要直接连接生产仓库。

下载并启动 Demo

打开 QoderWake × GitHub DevOps Demo 仓库，从 Releases 下载最新的源码包。
Windows 选择 Windows Source 包；macOS 或 Linux 选择 macOS/Linux Source 包，然后解压到本地目录。
确认 QoderWake 已启动并登录。
在解压目录运行对应命令。

macOS 或 Linux：

./start-demo

Windows：

.\start-demo.cmd

源码包可直接运行，不需要编译，也不需要执行 npm install。如果系统阻止脚本运行，先检查文件执行权限和终端安全提示，不要通过关闭系统安全策略来绕过限制。

完成首次配置

首次启动后，按照终端向导完成以下操作：

登录 GitHub，并确认当前账号和目标仓库正确。
选择或创建本地工作目录。目录不存在时，启动器会创建目录并克隆 Demo 仓库。
在隐藏输入框中填写 QoderWake PAT。不要把令牌粘贴到仓库文件、Waker 说明或普通终端日志中。
按提示创建或复用 Release、Developer、Reviewer 和 Tester 四个 Waker。
确认四个 API 自动任务及其调用地址已经生成。
允许向 GitHub Actions Secrets 写入 PAT 和四个 Waker 的调用地址。
确认 Demo Workflow、事件路由、CI 和状态 Label 已配置完成。

向导完成后，分别打开四个 Waker 的自动任务，检查任务已启用、工作目录正确、触发方式为 API，并确认没有真实凭据出现在任务描述中。

GitHub Actions 只负责过滤和转发事件；四个 API 自动任务分别唤醒职责独立的 Waker。

运行完整交付流程

首次体验建议选择“首轮发现一个 Bug”，以验证缺陷能否完整回流。运行过程如下：

Requirement → Developer → 代码 PR → Reviewer → 人工合并
→ Tester → Bug → Developer 修复 → Reviewer 复评 → 人工合并
→ Tester 复测 → 发布 PR → 人工合并 → Tag / GitHub Release

阶段	系统执行	用户需要确认
创建迭代	Release Waker 创建 Milestone、迭代分支和 Requirement	检查需求与验收标准是否正确
开发	Developer Waker 创建分支、修改代码、执行测试并创建代码 PR	查看 PR 中的需求关联和测试证据
评审	Reviewer Waker 针对当前 revision 独立评审，GitHub Actions 同时运行 CI	Reviewer 通过且 CI 成功后，合并代码 PR
测试与修复	Tester Waker 独立验收；失败时创建 Bug 并自动唤醒 Developer	检查 Bug 的复现步骤、期望结果和实际结果
发布	Release Waker 汇总需求、Bug、PR 和 CI 证据并创建发布 PR	检查发布内容并合并发布 PR
收尾	Release Waker 创建 Tag 和 GitHub Release，并关闭 Milestone	确认版本、Release 内容和迭代状态

终端会显示当前阶段、正在运行的 Waker、实时会话链接和下一项人工操作。需要判断任务为什么暂停时，先查看终端提示，再打开对应的 QoderWake 会话和 GitHub 对象核对事实。

核对关键阶段

Developer 接收需求并开始开发

Release Waker 创建迭代分支后，Requirement 会进入开发链路。终端进度进入 Developer 阶段，并显示对应的实时会话链接。

终端显示 Developer 正在实现需求，可从实时会话链接查看执行过程。

Reviewer 与 CI 通过后等待人工合并

Developer 创建代码 PR 后，Reviewer 只评审当前代码 revision。Reviewer 通过且 CI 成功时，终端进入人工合并门禁；此时由用户决定是否合并代码 PR。

终端明确给出需要人工处理的代码 PR，合并后 Tester 才会开始验收。

打开实时会话，检查 Reviewer 是否读取了 PR、关联 Requirement、目标分支和 head SHA，并执行了独立测试。

Reviewer 会话保留测试过程、评审结论和写回 GitHub 的结果。

GitHub PR 应同时保留需求关联、分支、变更说明和测试证据。不要只依据 QoderWake 会话中的“完成”判断交付成功。

代码 PR 是本次变更的事实页面，最终合并仍由用户确认。

Reviewer 的结论应以带 revision 标识的 Review Summary 回写 PR，并记录测试、Lint、CI、验收标准和 Diff 范围。

评审结论关联具体 revision，代码更新后需重新评审。

同时检查 GitHub Actions 的 CI Job 是否成功。Reviewer 通过不能替代独立 CI，二者都通过后才能进入合并门禁。

GitHub Actions 提供独立的测试门禁。

Tester 发现 Bug 并回流 Developer

代码合入迭代分支后，Tester 开始独立验收。发现问题时，Tester 创建带复现证据的 Bug，并自动把任务交回 Developer 修复。

Bug 会重新进入开发、评审、人工合并和复测链路。

Release 完成发布和迭代收尾

复测通过后，Release Waker 创建发布 PR。用户合并发布 PR 后，Release Waker 创建 Tag 和 GitHub Release，并关闭 Milestone。

终端显示流程进入 9/9，并确认版本发布和 Iteration 关闭。

验收运行结果

完整运行结束后，确认以下结果：

GitHub 中保留本轮独立的 Milestone、Requirement、代码 PR、测试记录和发布 PR。
Reviewer 的结论关联当前 PR 的 head SHA，而不是旧版本代码。
CI 成功且 Reviewer 通过后，流程才进入人工合并阶段。
选择 Bug 路径时，Bug 包含复现证据，并重新进入开发、评审和复测链路。
最终生成正确的 Tag 和 GitHub Release，Milestone 已关闭。
QoderWake 的四个运行记录与 GitHub 对象能够相互对应，没有凭据出现在会话、截图或日志中。

中断演示后，可在源码包目录运行 npm run watch 恢复进度监控。若本地 checkout 被删除，重新运行启动器会尝试从远端恢复；远端仓库不存在或当前账号没有权限时，先修复仓库或权限问题，再重新启动。

迁移到实际研发流程

不要直接复制 Demo 的角色权限和触发条件到生产环境。迁移时按团队系统替换事件适配层和事实读取工具：

Demo 使用的 GitHub 能力	实际系统中的对应能力
Issue / Milestone	需求、缺陷和迭代管理
Pull Request 事件	GitLab Merge Request、Codeup 代码评审等事件
GitHub Actions Router	企业 CI、事件总线或自动化流水线
GitHub CLI	对应平台的官方 CLI 或 OpenAPI
Actions Secrets	企业凭据库或密钥管理服务

迁移后仍应保留以下原则：

一个 Waker 只承担一个清晰职责，开发、评审、测试和发布相互独立。
只在有效业务事件发生时触发，并过滤评论、状态刷新等无关事件。
每次执行重新读取需求、代码、CI 和当前状态，不依赖旧会话结论。
使用唯一事件标识和业务 Marker 防止重复执行；重复事件到达时能够安全退出。
代码、评审、Bug、测试和发布结果回写研发系统，聊天记录只用于观察过程。
凭据只保存在受保护的 Secret 中；正式合并和发布继续保留人工确认。

本实践整理自开源项目的 Demo 流程指南。具体脚本、版本要求和下载包以该项目的最新 Release 说明为准。

​了解交付流程

​准备运行环境

​下载并启动 Demo

​完成首次配置

​运行完整交付流程

​核对关键阶段

​Developer 接收需求并开始开发

​Reviewer 与 CI 通过后等待人工合并

​Tester 发现 Bug 并回流 Developer

​Release 完成发布和迭代收尾

​验收运行结果

​迁移到实际研发流程