# Gitea Workflow 持久化实施计划

## 目标

在 cc-web 内完整落地 Gitea Webhook → 持久 Codex App 会话 → 官方 gitea-mcp → Gitea 回执的工作流，并提供可恢复的队列、工作区和管理界面。

## 当前阶段

Phase 5：集成验收与交付

## 阶段

### Phase 1：需求与协议确认

- [x] 汇总用户已确认的产品边界
- [x] 核验官方 Gitea Webhook 与 gitea-mcp 协议
- [x] 完成 PRD、状态机、数据模型和安全设计
- 状态：已完成

### Phase 2：核心工作流实现

- [x] 实现配置、状态、队列、去重和恢复
- [x] 实现 Webhook 验签、事件过滤和自动接入
- [x] 实现 clone/fetch、仓库锁和工作区状态
- 状态：已完成

### Phase 3：Codex App 与回执集成

- [x] 注入线程级 gitea-mcp 配置
- [x] 实现 turn 状态监听、回执确认、补触发和 REST 兜底
- [x] 实现 waiting_user 与连续评论投递
- 状态：已完成

### Phase 4：管理界面与测试

- [x] 实现工作流管理 API 和前端页面
- [x] 补充单元、回归、协议 mock 和安全测试
- [x] 完成重启恢复、并发和自触发回归
- 状态：已完成

### Phase 5：集成验收与交付

- [x] 整合子任务改动并解决冲突
- [x] 运行测试、构建和真实协议形状检查
- [x] 完成文档、审计和最终交付
- 状态：已完成

## 已确认决策

| 决策 | 结论 |
|---|---|
| 触发 | Issue/PR 普通评论中的 `@ccweb-bot` |
| 实例 | MVP 单个 Gitea 实例，一个全局 Bot |
| 未登记仓库 | 首次合法触发自动接入并 clone |
| 工作区 | 全局根目录下每仓库持久 checkout |
| Git 认证 | HTTPS + Bot Token，临时凭据，不写 remote URL |
| 并发 | 同仓库串行，不同仓库并行，全局上限默认 2 |
| Agent | 固定 `codexapp` + `yolo` |
| 会话键 | `gitea + owner/repo + type + number` |
| 交互 | Gitea 主交互，cc-web 镜像和运维 |
| 回复 | 状态评论 + MCP 最终回复；缺失时补触发一次，最后 REST 兜底 |
| 安全 | HMAC Webhook Secret；Bot Token 与 Secret 分离 |
| MCP 权限 | 用户明确要求开放官方 gitea-mcp 全部写权限 |
| 恢复 | queued 恢复，waiting_user 保留，running 中断并最多重试一次 |
| 运维 | 全局暂停、仓库停用、取消排队、中止 turn、审计日志 |

## 错误记录

| 错误 | 尝试 | 处理 |
|---|---:|---|
| 暂无 | 1 | - |