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

147 lines
8.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 启动 / 停止
```bat
:: 后台常驻(最小化窗口)
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 演练模式(干跑)
```bat
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 工程师执行:
```bash
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 | findstr node` |
| 本地提交/远端 | `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>`(或改状态文件后重启管道) |