Files
perler-lab/docs/RELEASE-PIPELINE.md

8.2 KiB
Raw Permalink Blame History

PERLER LAB 发布流水线(Release Pipeline)

版本: v1.0 · 文档编号: RELEASE-PIPELINE · 关联任务: T-080 流水线目标:验收通过 → 自动提交 → 手动推送 → CI 构建部署,全程可追溯、可监控、可回滚。


1. 流水线总览

┌──────────┐   taskboard.js test --pass    ┌──────────────┐   轮询检测新验收任务   ┌────────────────┐
│ QA 测试  │ ───────────────────────────▶ │  任务状态:    │ ──────────────────▶ │  auto-commit   │
│  Agent   │   状态: review → approved     │  approved     │  (AUTO_COMMIT_INTERVAL│  自动提交管道   │
└──────────┘                              └──────────────┘   默认 60 秒)          └───────┬────────┘
                                                                                          │ git add -A + commit
                                                                                          │ "[验收通过] T-xxx 标题"
                                                                                          ▼
┌──────────┐   人工执行(不自动推送!)      ┌────────────────┐   GitHub Actions    ┌───────────────┐
│ GitOps   │ ───────────────────────────▶ │  git push       │ ──────────────────▶ │  CI/CD        │
│ 工程师   │   node gitflow.js push        │  origin/master  │   触发 .github/workflows│  构建+测试+部署 │
└──────────┘                              └────────────────┘                      └───────────────┘

核心原则:

  • 任务状态机(pending → in_progress → review → approved)由 taskboard.js 管理,本管道只读取任务文件、不修改任务状态。
  • 验收通过后的提交由 auto-commit.js 自动完成;推送是独立步骤,由 GitOps 工程师手动执行,两者解耦。
  • CI/CD(GitHub Actions)由 push 触发,属于发布环节的最后一道自动化闸门。

2. 各角色职责(谁跑什么)

环节 负责人 执行方式 产物 / 记录
开发 实施 Agent taskboard.js submit <id> 任务进入 review(待验收)
验收 QA 测试 Agent taskboard.js test <id> --pass/--fail 状态 → approved(通过)/ rejected + 自动生成 Bug
自动提交 Release-Manager(本管道) auto-commit.bat 常驻 或 node auto-commit.js --once auto-commit.log(提交 hash、结果)
推送 GitOps 工程师 node gitflow.js push 或 git push 远端提交记录
构建/部署 CI(GitHub Actions) push 自动触发 .github/workflows/deploy.yml Actions 运行记录
监控 主代理 / 全体 看板 node taskboard.js serve + auto-commit.log 实时状态

3. 自动提交管道(auto-commit.js)

3.1 工作方式

  • 轮询读取 taskboard/tasks.json,间隔由环境变量 AUTO_COMMIT_INTERVAL 控制(默认 60 秒)。
  • 对比状态文件 auto-commit-state.json 中记录的「上次见到的状态」:
    • 任务当前为 approved 且 上次记录不是 approved → 判定为「新验收通过」→ 触发提交。
  • 提交逻辑与 node gitflow.js approve <id> 等价:git add -A + git commit -m "[验收通过] <id> <标题>"。
    • ⚠️ 与 gitflow.js 的区别:本管道不推送。gitflow.js 的 approve 在配置了 origin 时会顺带推送,本管道刻意省略推送,保持「提交 / 推送」分离。
  • 提交前检查工作区:git status --porcelain 为空 → 记录「跳过(无改动)」,不产生空提交。
  • 提交信息通过临时文件传给 git commit -F,避免中文标题/引号在 shell 中出错。

3.2 幂等性(重复运行不会重复提交)

  • auto-commit-state.json 记录每个任务最近一次状态;提交成功或「无改动跳过」后,该任务被标记为 approved,后续轮询不再触发。
  • 首次运行只记录基线:不追溯提交已存在的验收通过任务(避免启动管道时一次性提交全部历史任务)。
  • 提交失败(如 git 异常)会保留旧状态,下轮自动重试,不会静默丢失。

3.3 文件清单

文件 说明
auto-commit.js 管道主程序(Node,零依赖)
auto-commit.bat Windows 后台启动脚本(最小化窗口运行,窗口标题 PERLER LAB Auto-Commit)
auto-commit-state.json 运行状态(每个任务最近状态),已加入 .gitignore,不进入提交
auto-commit.log 运行日志(时间戳 / 任务 id / commit hash / 结果)

3.4 启动 / 停止

:: 后台常驻(最小化窗口)
auto-commit.bat

:: 或前台运行,Ctrl+C 停止
node auto-commit.js

:: 环境变量示例(管理员/命令行先 set 再启动)
set AUTO_COMMIT_INTERVAL=30
auto-commit.bat

停止后台任务:任务管理器结束 node.exe(标题为 PERLER LAB Auto-Commit 的窗口),或 taskkill /F /FI "WINDOWTITLE eq PERLER LAB Auto-Commit*"。

3.5 演练模式(干跑)

node auto-commit.js --dry-run --once

只打印「将要提交哪些任务、提交信息是什么、工作区是否有改动」,不提交、不改状态文件,可在正式接入前安全验证。

3.6 日志格式(auto-commit.log)

[2026-08-14 09:00:00+08:00] [启动] 验收自动提交管道 v1.0
[2026-08-14 09:00:00+08:00] [初始化] 首次运行:已记录 81 个任务的当前状态为基线(其中验收通过 43 个,不追溯提交)
[2026-08-14 09:01:00+08:00] [检测] 发现 1 个新验收通过任务: T-082
[2026-08-14 09:01:00+08:00] [提交成功] 任务 T-082「xxx」→ commit a1b2c3d4...
[2026-08-14 09:02:00+08:00] [巡检] 无新验收通过任务(任务总数 82,验收通过 44)

4. 推送(手动、独立步骤)

自动提交只生成本地 commit。发布到远端由 GitOps 工程师执行:

node gitflow.js push        # 推当前分支到 origin
# 等价: git push -u origin master

为什么推送不自动化:push 是对外发布动作,涉及远端仓库与 CI 触发,必须由人确认后执行(验收 → 提交已自动,发布 → 人工闸门)。


5. CI(push 触发)

  • push 到远端后,GitHub Actions(.github/workflows/deploy.yml)自动执行:测试 → 构建 → 部署(详见 docs/DEPLOY.md)。
  • CI 失败处理:GitOps/DevOps 工程师查看 Actions 日志 → 修复 → 重新 push(或 revert 问题提交后重新推送)。

6. 监控

监控点 方法
任务状态 node taskboard.js serve 打开实时看板(默认 http://localhost:8787,2 秒刷新)
提交结果 查看 auto-commit.log 尾部:Get-Content auto-commit.log -Tail 20
管道是否在跑 任务管理器找标题 PERLER LAB Auto-Commit 的窗口;或 `tasklist
本地提交/远端 node gitflow.js status;git log --oneline -10

7. 故障排查

现象 原因 处理
日志无新提交,任务已是 approved 该任务在管道启动前就已通过验收(基线任务) 手动 node gitflow.js approve <id> 提交;管道此后只处理新增
[提交失败] ... 下轮自动重试 git 异常/冲突 查看日志详情,修复后无需操作,下轮自动重试
状态文件损坏 异常写入 管道自动按全新状态处理(重新记基线);也可删除 auto-commit-state.json 重置
提交未触发 工作区无改动 正常:管道记录「跳过(无改动)」,不产生空提交
想重新触发某任务提交 状态文件把该任务记为 approved 手动执行 node gitflow.js approve <id>(或改状态文件后重启管道)