diff --git a/plans/1-workflow.md b/plans/1-workflow.md new file mode 100644 index 0000000..d4b0fd7 --- /dev/null +++ b/plans/1-workflow.md @@ -0,0 +1,69 @@ +# 需求分析:Issue #1 一个新的 Workflow:工程师 +## 1. 背景与目标 +需要新增一个自动化 Workflow(engineer.yml),定时扫描 `plans/` 中的计划文件,判断是否存在未完成任务,并在必要时调用 Codex Action 自动完成任务并创建 PR,且保证同一时间只有一个工程师 Workflow 在运行,避免重复工作。 + +## 2. 需求摘要 +- 新增 GitHub Actions Workflow:`engineer.yml`。 +- 触发方式:定时任务,每小时执行一次。 +- 目标范围:`plans/` 目录下的 Plan Markdown 文件,使用 FrontMatter 的 `status` 字段驱动流程。 +- 处理逻辑:发现 TODO/DOING 任务则分析是否已完成;未完成则调用 codex action 完成任务并创建 PR;已完成则不处理。 +- 并发控制:同一时间只允许一个 engineer workflow 运行。 + +## 3. 范围定义(In Scope / Out of Scope) +In Scope: +- `plans/` 下 Plan 文件的扫描与读取 FrontMatter。 +- 仅依据 `status` 字段判断状态(TODO/DOING/DONE),且缺失 `status` 视为 TODO。 +- 多个待处理计划按序号顺序处理。 +- 调用 `openai/codex-action@v1` 完成任务,并在完成后自动创建 PR。 +- Workflow 并发控制(避免同一时间多个 engineer 执行)。 + +Out of Scope: +- 对 FrontMatter 其他字段进行校验或强制要求。 +- 非 `plans/` 目录的任务管理。 +- 自定义非 GitHub Actions 方式的 Codex 调用。 + +## 4. 需求拆解 +1. Workflow 触发 + - 定时触发:每小时执行一次。 +2. 计划扫描与选取 + - 扫描 `plans/` 目录下的 Markdown 文件。 + - 读取 FrontMatter 的 `status` 字段;缺失视为 TODO。 + - 多个 TODO/DOING 计划按序号顺序处理(例如文件名中的序号)。 +3. 状态判断与完成判定 + - `status: DONE` 视为已完成,不触发 Codex。 + - `status: TODO/DOING` 视为未完成,进入任务分析流程。 +4. Codex 调用与任务完成 + - 采用 GitHub Actions 方式调用 `openai/codex-action@v1`。 + - Prompt 需包含计划文件内容与预期任务说明。 +5. PR 自动创建 + - Codex 完成任务后自动创建 PR(包含变更内容)。 +6. 并发控制 + - 使用 `concurrency` 或等效方式确保同一时间只有一个 engineer workflow 运行。 + +## 5. 技术方案建议 +- Workflow 文件:`.github/workflows/engineer.yml`。 +- 触发:`schedule` + `cron` 每小时一次。 +- 并发控制:使用 `concurrency: engineer` 并启用 `cancel-in-progress: false`(避免并行)。 +- 计划扫描:使用脚本读取 `plans/` 下文件并解析 FrontMatter;以文件名序号排序。 +- Codex 调用:参考 issue 中提供的 `openai/codex-action@v1` 使用方式。 +- PR 创建:使用 `gh` CLI 或 `actions/github-script`,根据 Codex 输出生成 PR。 + +## 6. 风险与依赖 +- 依赖:`openai/codex-action@v1` 可用且 `OPENAI_API_KEY` 已配置。 +- 风险:多文件处理排序依赖命名规范,需要约定文件名序号格式。 +- 风险:任务“完成”仅依赖 `status` 字段,若未及时更新可能重复触发。 + +## 7. 验收标准 +- 每小时定时触发 workflow 能执行。 +- `plans/` 中存在 TODO/DOING 计划时能按序号顺序选取并处理。 +- `status: DONE` 的计划不会触发 Codex。 +- 缺少 `status` 的计划会被视为 TODO。 +- Workflow 可调用 Codex Action 并自动创建 PR。 +- 同一时间不会出现多个 engineer workflow 并行执行。 + +## 8. 待确认问题 +- 暂无(用户在 2026-02-20 询问是否还有待确认问题,当前未新增)。 + +## 9. 更新记录 +- 2026-02-20:创建需求分析文档,整合 Issue 讨论的已确认规则与约束。 +- 2026-02-20 23:09:12 +08:00:根据最新评论确认暂无新增待确认问题,补充待确认说明。