135 lines
13 KiB
Markdown
135 lines
13 KiB
Markdown
# Gitea Workflow 实施计划审查
|
||
|
||
审查日期：2026-08-24
|
||
审查范围：`task_plan.md`、`findings.md`、`Gitea Workflow TO DO list.csv` 及用户目标“完整实现 Gitea Webhook → Codex App 持久会话 → 官方 gitea-mcp → Gitea 回执的可靠工作流，并提供管理页面、队列、恢复、测试和文档”。本审查只产生本文件，不修改业务代码或其它计划文件。
|
||
|
||
## 结论
|
||
|
||
当前计划在“阶段主题”层面与 CSV 基本一致，但还不能作为可直接执行和可验收的实施基线。建议先补齐 Phase 1 的协议、状态机、数据模型和安全设计，再进入实现；否则最容易出现“功能链路能跑一次，但重启、重复 Webhook、回执失败或并发时不可靠”的假完成。
|
||
|
||
建议结论：**有条件通过，暂不进入核心编码**。以下 P0 项未关闭前，不应把 CSV 中的核心实现项标记为 DONE。
|
||
|
||
## 计划与 CSV 一致性
|
||
|
||
| 计划范围 | 对应 CSV | 一致性 | 审查意见 |
|
||
|---|---|---|---|
|
||
| Phase 1 需求、协议、设计（`task_plan.md:13-18`） | 1、2 | 基本一致 | CSV 第 1 项为 `IN_PROGRESS`，与计划“进行中”一致；但“已完成边界汇总”和“设计文档尚在编写”的完成定义没有拆开。 |
|
||
| Phase 2 状态、Webhook、工作区（`task_plan.md:20-25`） | 3、4 | 基本一致 | 计划把队列/恢复和工作区放在同一阶段，CSV 分成两项；缺少明确前置依赖、交付物和负责人。 |
|
||
| Phase 3 Codex App、MCP、回执（`task_plan.md:27-32`） | 5 | 基本一致 | CSV 将线程注入、监听、补触发、REST 兜底合成一项，无法分别验收可靠性。 |
|
||
| Phase 4 管理界面、测试（`task_plan.md:34-39`） | 6、7 | 基本一致 | 计划中的重启恢复、并发、自触发回归没有在 CSV 中单列，容易被“测试已补充”掩盖。 |
|
||
| Phase 5 整合、验证、交付（`task_plan.md:41-45`） | 8、9、10 | 一致 | 但“解决冲突”“协议形状检查”“文档/审计”均没有明确输出文件、命令和通过阈值。 |
|
||
|
||
总体上，CSV 的 10 项与计划的 15 个子项不是一一映射关系。建议在计划和 CSV 中增加稳定的任务 ID（例如 P1-01、P2-02），并为每项写明 `交付物 / 依赖 / 验收命令或证据 / 负责人`；否则状态同步只能凭文字判断。
|
||
|
||
## P0 阻断项
|
||
|
||
### P0-1：Phase 1 没有可执行的退出条件
|
||
|
||
计划只写“核验协议”“完成 PRD、状态机、数据模型和安全设计”（`task_plan.md:16-17`），没有指定文档路径、协议版本、决策结果或评审证据。`findings.md` 目前只有研究结论，没有状态转移表、字段定义、接口契约或威胁模型。
|
||
|
||
进入 Phase 2 前至少应产出并评审：
|
||
|
||
- Webhook 请求/响应和签名头的版本化协议矩阵；官方 `gitea-mcp` 版本、启动参数、stdio 生命周期和工具能力清单。
|
||
- 任务/会话/回执状态机（状态、事件、合法转移、重试上限、超时、取消、死信、人工恢复）。
|
||
- 持久化数据模型、唯一键、索引、迁移/版本策略和崩溃恢复规则。
|
||
- 线程、任务、Webhook delivery、评论和回执之间的关联契约。
|
||
- 安全威胁模型与密钥生命周期设计。
|
||
|
||
### P0-2：持久化方案无法证明并发安全和崩溃一致性
|
||
|
||
`findings.md:17` 仅指出现有 JSON 持久化或“新增独立存储模块”，但没有做出选择。队列、去重、状态转移、会话映射和回执确认若继续散落写 JSON，会遇到并发覆盖、半写文件、重复消费和重启丢失；这与目标中的“持久化、可靠、可恢复”直接冲突。
|
||
|
||
计划必须明确单一事实源及原子性边界：至少要定义 inbox（Webhook 去重）、任务状态、会话映射、outbox（评论/补发意图）如何在一次事务或等价原子操作中落盘；并定义锁、文件替换、fsync、备份/恢复和 schema 迁移。若采用 JSON，需证明单写者/进程锁和崩溃恢复；若不能证明，应在计划中选择具备事务语义的存储。
|
||
|
||
### P0-3：状态机、幂等和回执可靠性没有闭环
|
||
|
||
`findings.md:34-39` 给出了“先验签/去重/过滤”“最多一次隐藏补触发”“REST 兜底”的原则，但没有定义可判定的幂等键、评论标记、确认窗口、重复运行保护或失败终态。尤其“任务完成但没有回帖”时，如何区分 MCP 调用已成功但查询延迟、调用超时、网络重试导致重复评论，当前不可执行。
|
||
|
||
需要补充：
|
||
|
||
- delivery、任务、turn、评论发送各自的唯一 ID 及跨表关联。
|
||
- 评论内容中的稳定 run/attempt 标记或等价查询条件，保证 MCP、补触发和 REST 兜底不会重复发同一回执。
|
||
- Gitea 查询的最终一致性轮询窗口、退避、最大次数和“未知”状态；未知不能直接当失败重跑。
|
||
- 重试分类（网络/5xx、4xx 权限、超时、进程崩溃）、退避与死信/人工重放策略。
|
||
- 重启时每个状态的恢复动作，特别是 `running`、`waiting_user`、`receipt_pending` 和 `cancel_requested`。
|
||
|
||
### P0-4：三方协议的真实形状和版本未锁定
|
||
|
||
`findings.md:19-25` 只记录官方仓库和大致参数，`task_plan.md:29-30` 也没有 app-server 方法、事件类型或 MCP 注入字段。没有固定版本和 mock 契约，无法验收“线程级注入”和“turn 状态监听”是否真的走原生协议。
|
||
|
||
应在 Phase 1 固化并纳入 mock/回归断言：
|
||
|
||
- Gitea Webhook 事件类型、评论字段路径、签名算法/头、delivery ID、超时和 HTTP 返回语义。
|
||
- Codex App `initialize/initialized`、能力探测、`thread/start`、线程恢复、turn 事件和取消/中止的确切参数形状。
|
||
- `thread/start.config.mcp_servers.*` 的线程级 env 注入、stdio 子进程启动/退出、超时和错误事件；不得退回动态工具或进程级来源上下文。
|
||
- 官方 `gitea-mcp` 版本/校验和、`GITEA_HOST` 与 token 注入方式、工具列表和权限边界。
|
||
|
||
### P0-5：全写权限下的安全边界不足
|
||
|
||
计划确认“开放官方 gitea-mcp 全部写权限”（`task_plan.md:63`），但安全设计只写 HMAC 和 Token 分离（`task_plan.md:62`）。这不足以支撑公网 Webhook 和自动接入。至少要覆盖重放、密钥轮换、日志脱敏、仓库/主机 allowlist、请求体大小和限流、路径穿越、命令注入、工作区权限、MCP 子进程隔离，以及管理页面的认证/授权/CSRF。
|
||
|
||
同时要明确 Bot 自评论过滤不能只依赖用户名：应定义稳定的 bot identity、来源 delivery/run 标记和异常情况下的 fail-closed 行为，避免自触发风暴（`findings.md:34-36`）。
|
||
|
||
### P0-6：跨模块写冲突和整合策略未规划
|
||
|
||
Phase 5 写“整合子任务改动并解决冲突”（`task_plan.md:43`），但没有任务分区、文件所有权、接口冻结点或整合顺序。预期热点很可能包括 `server.js`、配置/持久化模块、Codex App turn 路径、MCP 配置、路由和前端状态；多个实现项若直接改同一入口，会产生不可审计的隐式冲突。
|
||
|
||
进入实现前应把工作拆成不重叠边界（例如 domain/state、webhook/queue、workspace、app-server adapter、API/UI、tests/docs），先冻结共享接口，再按依赖顺序合并；禁止以“最后人工解决冲突”作为验收条件。
|
||
|
||
## P1 重要遗漏与可执行性问题
|
||
|
||
### 1. 队列与恢复
|
||
|
||
Phase 2 只列“状态、队列、去重和恢复”（`task_plan.md:22`），缺少全局并发上限为 2 的调度算法、公平性、每仓库串行锁的租约/心跳、进程崩溃后的 stale runner 判定、优雅停机、取消排队与中止 turn 的区别、超时、死信和人工重放。应为每一类恢复场景写出输入、状态变化和预期结果，并加入 kill/restart 测试。
|
||
|
||
### 2. Webhook 与自动接入
|
||
|
||
`findings.md:5-7` 未定义配置校验、首次接入的授权边界、仓库 URL/owner/repo 的规范化、默认分支和私有仓库权限失败处理。需要明确先快速返回 HTTP，再异步入队还是同步处理；验签失败、重复 delivery、非评论事件、非目标评论、Bot 自评论分别返回什么，避免 Gitea 重试风暴。
|
||
|
||
### 3. 工作区与 Git 认证
|
||
|
||
`findings.md:40` 的“脏工作区不 reset、不覆盖”是原则，不是行为契约。要决定脏状态时任务是失败、暂停、继续当前会话还是创建隔离 worktree；定义分支/ref 切换、fetch 冲突、仓库删除、磁盘不足、凭据泄露（命令行/日志/remote config）和清理策略。持久 checkout 与“同仓库串行”还需明确锁的持有范围。
|
||
|
||
### 4. Codex App 会话与 waiting_user
|
||
|
||
计划确认会话键（`task_plan.md:59`）和固定 `codexapp + yolo`（`task_plan.md:58`），但没有说明首次建线程、重启后的线程恢复、线程不存在/过期、app-server 断线、turn 超时及取消后的映射。`waiting_user`（`task_plan.md:31`、`task_plan.md:64`）没有定义由哪类 Gitea 评论恢复、是否阻塞同仓库、超时/过期和最大连续轮数；“连续评论投递”也没有顺序和幂等规则。
|
||
|
||
### 5. 管理 API 与前端
|
||
|
||
Phase 4 只写“实现管理 API 和前端页面”（`task_plan.md:36`），没有端点契约、权限角色、敏感配置展示规则、暂停/停用/取消/中止的并发控制、审计记录格式、分页过滤、实时刷新和错误提示。管理页面不能成为绕过队列状态机的第二套写入口；所有操作应复用同一领域命令和审计链。
|
||
|
||
### 6. 测试与验收证据
|
||
|
||
CSV 第 7、9 项虽覆盖“测试、构建、协议验收”，但没有测试矩阵、通过阈值或运行命令。至少应覆盖：重复/乱序 Webhook、伪造/重放签名、Bot 自触发、首次接入、同仓库并发、不同仓库并发上限、脏工作区、clone/fetch 失败、app-server 断线、MCP 缺失/工具报错、turn 中止、waiting_user、MCP 成功但查询延迟、补触发成功/失败、REST 兜底、进程 kill 后恢复、密钥轮换和管理 API 未授权。
|
||
|
||
协议测试不能只断言“调用成功”，还要断言真实参数形状、线程级 env、没有重复顶层字段、调用的是 MCP 工具而非动态工具，并保存 mock 输入/输出作为审计证据。应明确单元/集成/E2E 的最小通过标准和 CI/本地命令。
|
||
|
||
### 7. 运维、可观测性与交付
|
||
|
||
用户目标包含队列、恢复和文档，但计划未列指标、结构化日志、关联 ID、告警、数据保留、备份恢复、升级/回滚、配置校验和运行手册。Phase 5 的“文档、审计和最终交付”（`task_plan.md:45`）应明确至少包括架构/状态机、部署配置、Webhook 配置、密钥轮换、故障处理、恢复/重放、权限说明和已知限制。
|
||
|
||
## 建议的执行顺序与退出条件
|
||
|
||
1. **先完成 Phase 1 冻结契约**：补齐上述协议矩阵、状态机、schema/迁移、领域命令、错误/重试表、安全威胁模型和 mock fixture；每项有文档路径和评审人。
|
||
2. **再实现持久化领域核心**：先落地 inbox、任务、会话、outbox、审计的原子状态转移和恢复算法，再接 Webhook/工作区，避免入口先写出不可恢复的副作用。
|
||
3. **接入 Codex App 与 gitea-mcp**：以固定版本和协议 mock 验证线程级配置、turn 事件、取消/重连；所有回执发送经过幂等 outbox。
|
||
4. **最后接 API/UI 和故障测试**：API/UI 只发领域命令；并发、重启、自触发和回执异常测试必须在标记 Phase 4 完成前通过。
|
||
5. **Phase 5 交付门槛**：构建、静态检查、全测试和协议形状断言均有可复现命令；文档、审计样例、恢复演练记录和回滚方案齐全。
|
||
|
||
推荐把每个阶段的状态改成“未开始/进行中/阻塞/完成”，并在完成条件中引用证据文件或测试名称，而不是只保留勾选框。
|
||
|
||
## 最小验收清单（对应用户目标）
|
||
|
||
- Webhook：合法评论可入队；伪造、重放、重复 delivery、非目标事件和 Bot 自评论均按契约处理。
|
||
- 持久会话：会话键稳定；重启后任务、锁、turn 和 waiting_user 状态可恢复且不重复执行。
|
||
- 官方 MCP：固定版本、线程级配置、凭据不落盘/不泄露；读写工具调用可被 mock 和审计验证。
|
||
- 回执：成功评论可确认；未知状态不会盲目重跑；只允许一次补触发，之后 REST 兜底仍幂等。
|
||
- 队列/并发：同仓库串行、不同仓库并行、全局上限 2 可证明；暂停、取消、终止和死信可操作。
|
||
- 管理面：认证授权、审计、状态查询和运维操作与领域状态机一致，不暴露 token/secret。
|
||
- 可靠性测试：覆盖崩溃恢复、并发、网络/权限/协议失败和自触发回归，并有可重复命令与结果。
|
||
- 文档交付：架构、配置、部署、密钥、故障恢复、重放、回滚和已知限制齐全。
|
||
|
||
## 审查结论摘要
|
||
|
||
CSV 与计划没有明显的宏观漏项，但粒度、状态和验收证据不一致；当前最大的风险不是缺少页面或接口，而是持久化原子性、状态机幂等、三方协议形状和全写权限安全边界尚未冻结。补齐 P0 并将其转成带 ID/依赖/证据的任务后，计划才具备可靠实施条件。
|