# 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 ` | 任务进入 `review`(待验收) | | 验收 | QA 测试 Agent | `taskboard.js test --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 ` 等价:`git add -A` + `git commit -m "[验收通过] <标题>"`。 - ⚠️ 与 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 ` 提交;管道此后只处理新增 | | `[提交失败] ... 下轮自动重试` | git 异常/冲突 | 查看日志详情,修复后无需操作,下轮自动重试 | | 状态文件损坏 | 异常写入 | 管道自动按全新状态处理(重新记基线);也可删除 `auto-commit-state.json` 重置 | | 提交未触发 | 工作区无改动 | 正常:管道记录「跳过(无改动)」,不产生空提交 | | 想重新触发某任务提交 | 状态文件把该任务记为 approved | 手动执行 `node gitflow.js approve `(或改状态文件后重启管道) |