8.2 KiB
8.2 KiB
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>(或改状态文件后重启管道) |