cc-web/docs/gitea-workflow/PRD.md

Gitea Webhook 驱动 ccweb 工作流 PRD

文档状态：已确认需求基线（MVP）
适用范围：单个 Gitea 实例、一个全局 ccweb-bot 账号
相关设计：ARCHITECTURE.md

1. 背景与目标

本功能把 Gitea Issue/PR 的普通评论作为 ccweb 的任务入口。用户在评论中 提及 @ccweb-bot 后，cc-web 验证 Webhook、准备持久工作区、复用该 Issue/PR 的独立 Codex App 会话，并通过官方 gitea-mcp 完成代码研究、修改 和回帖。Gitea 是唯一主交互入口；cc-web 页面只提供镜像、运维和审计能力。

目标：

1. 让用户无需离开 Gitea 即可驱动一次或连续多轮工程任务。
2. 保证同一仓库的工作区和任务严格串行，不同仓库可并行；MVP 不设置额外的 全局并发上限。
3. 在进程重启、网络抖动、MCP 回帖失败时，任务状态、会话和回执仍可恢复、 重试且不重复执行或重复回帖。
4. 对 Webhook、Bot Token、工作区写入和每次工具调用提供可追溯审计，并允许运 维人员暂停、取消排队和中止运行中的 turn。

2. 已确认决策

主题	决策
Gitea 实例	MVP 只支持一个配置的 Gitea 实例，instanceId=default
Bot	一个全局 ccweb-bot，用于触发识别、起始回执和 REST 兜底
触发	Issue 或 PR 的普通评论正文包含 @ccweb-bot；评论作者不能是 Bot 自身
自动接入	合法触发首次发现未登记仓库时自动登记并 clone；管理员可停用
工作区	可配置工作区根目录下按仓库持久 checkout，后续使用 fetch 更新
并发	同仓库串行；跨仓库并行；MVP 不设置全局运行上限
Agent	固定 Codex App（codexapp）+ yolo，不在 Gitea 交互中暴露模式切换
MCP	官方 gitea-mcp，stdio 传输；线程级注入 Gitea host/token
会话	每个 Issue/PR 一个独立持久会话；后续同资源评论进入同一会话
交互	Gitea 为主；cc-web 页面只展示状态、队列和审计，不替代 Gitea 对话
回复	先发一条“已收到”回执；正常最终答案由 gitea-mcp 发回原 Issue/PR；缺失时一次补触发，最后 REST 兜底
安全	Webhook HMAC、delivery 去重、Bot 自评论过滤、Token/Secret 分离、审计
恢复	queued 重启后继续；waiting_user 保留；running 视为中断并最多重试一次
运维	全局暂停、仓库停用、取消排队、中止 turn、查看审计

3. 范围

3.1 In Scope

• Gitea Webhook 接收、原始请求 HMAC 校验和 delivery 幂等。
• Issue/PR 普通评论事件的规范化、提及解析和 Bot 自评论抑制。
• 未登记仓库自动接入、持久 clone/fetch、脏工作区保护。
• 任务队列、同仓库锁、跨仓库并行。
• Issue/PR 独立会话与 Codex App turn 生命周期管理。
• 线程级官方 gitea-mcp stdio 配置和 Gitea 主交互。
• 起始“已收到”回执、MCP 最终回帖确认、一次补触发和 REST 兜底；不发送运行中、等待用户或成功状态评论。
• 暂停、停用、取消排队、中止、重启恢复、审计和可观测字段。
• 可供前端/运维使用的只读状态和控制接口契约（实现不在本 PRD 变更范围）。

3.2 Out of Scope

• 多 Gitea 实例、跨 Forge 统一协议和 GitHub/GitLab 适配。
• 非评论触发（Push、定时任务、Issue 创建、Actions 等）。
• 让普通用户在 cc-web 中切换模型、推理强度或 yolo/plan 模式。
• 自定义 dynamicTools 代替 MCP；手动填写 MCP 工具参数的 UI。
• 自动清理用户未提交修改、reset --hard、强制覆盖其他会话的工作区。
• 细粒度按用户/路径的写权限策略（Bot 全写权限是已确认前提）；只记录风险并提供暂停/审计。

4. 角色与核心场景

角色	能力
Gitea 用户	在 Issue/PR 评论 @ccweb-bot，查看状态、追问、确认结果
ccweb-bot	发送起始回执、作为 MCP/REST 身份回帖；Bot 自己的评论不会再次触发
运维管理员	全局暂停/恢复、仓库停用/启用、取消排队、中止 turn、查审计
系统	验签、去重、排队、clone/fetch、启动会话、确认回帖、重试和恢复

典型链路：

Gitea 普通评论 @ccweb-bot
        │
        ▼
验签 → delivery 去重 → 解析 Issue/PR → 自动接入仓库
        │                                  │
        └────────────── 持久化任务并入队 ◄──┘
                                           │
                 同仓库锁串行，跨仓并行 ────┘
                                           ▼
             Codex App/yolo + gitea-mcp(stdio)
                         │
             已收到回执 → MCP 最终回帖 → turnId/评论确认
                                      │
                      补触发一次 → REST 兜底（必要时）

5. 功能需求

FR-01 触发与事件规范化

• 接受 Gitea 配置的 Issue/PR 评论 Webhook；事件适配器将不同版本的事件名称 归一为 issue_comment 或 pull_request_comment。
• 仅当正文包含独立 mention @ccweb-bot 时触发，mention 后的文本作为任务 指令；没有有效指令时仍创建可追踪任务并要求用户补充。
• 记录原始 deliveryId、事件类型、仓库、资源类型/编号、评论 ID、作者和 接收时间。无法解析的事件进入 ignored，不启动 Agent。
• Bot 自己发出的状态/最终/兜底评论必须被识别并忽略，防止自触发环路。

FR-02 Webhook 安全与幂等

• 在读取或持久化业务字段前，使用原始 body 和配置 Secret 计算 HMAC-SHA256， 采用常量时间比较；验签失败返回 401，不入队。
• deliveryKey = instanceId + ":" + deliveryId 唯一；已处理或处理中重复 delivery 返回 200（或约定的幂等响应）但不创建新任务。
• Secret、Bot Token、MCP 启动参数不得写入评论、普通日志或审计明文；审计只 记录凭据引用/哈希指纹。

FR-03 仓库自动接入与工作区

• 通过合法 Webhook 首次发现仓库时原子创建 RepositoryRecord；未登记不因 任务排队失败而丢失事件。
• 按 workspaceRoot/<instanceId>/<owner>/<repo> 建立持久目录。首次使用 clone，后续任务在仓库锁内 fetch；凭据通过临时环境或 credential helper 注入，不把 Token 写入 remote URL。
• 检测到未提交修改、冲突或目录被外部占用时，不执行 reset/clean/覆盖；任务 进入 blocked_workspace，写入审计并等待管理员处理。
• PR 任务必须记录 base/head ref 和源仓库信息；Issue 任务使用仓库默认分支， 除非指令明确指定已允许的分支。

FR-04 队列、锁与并发

• 调度器维护持久任务队列；同 repoKey 同时最多一个 preparing/running 任务，跨仓库可并行。
• 不设置额外全局运行信号量；queued 任务只受全局暂停和各自仓库锁影响，暂停时不再领取新任务。
• 队列顺序默认 FIFO；同一资源的新评论可合并为下一轮输入，但不得跳过已持久 化的任务或破坏评论顺序。
• 取消排队只允许作用于尚未启动的任务；中止操作必须向 Codex App 发送取消， 并等待 aborted 或超时后释放锁。

FR-05 会话与 Agent 运行时

• sessionKey = instanceId:owner/repo:kind:number，其中 kind 为 issue 或 pull_request；同一资源永远复用同一个 threadId。
• 每个新任务创建一个 turnId；持久化 threadId/turnId、启动时间、最后事件 序号和重试次数，支持断线后恢复监听。
• 启动参数固定为 codexapp 与 yolo。model、reasoning_effort、 developer_instructions 放入 collaborationMode.settings（若运行时启用 collaborationMode），不得在顶层重复传递。
• thread/start.config.mcp_servers.gitea 线程级注入官方 gitea-mcp stdio；每 个线程使用对应实例的 host/token，不使用进程全局来源会话变量替代。
• Prompt 必须包含仓库/资源标识、评论上下文、工作区路径、预期回帖格式和安全 边界；评论正文视为不可信输入，不得覆盖系统约束。

FR-06 Gitea 交互与回帖确认

• 合法任务只发送一条起始 giteabot: 已收到 回执；运行中、等待用户和成功状态 不再额外发送评论，避免污染 Issue/PR 讨论串。回执仍带不可见关联标记 （taskId、state、可选 turnId）用于去重和审计。
• 正常最终答案必须由 gitea-mcp 的 Issue/PR comment 工具发送；cc-web 记录 MCP 返回的 commentId 或工具调用结果，并通过 Gitea 查询确认实际存在。
• 确认必须同时匹配 resourceKey、taskId、turnId（或等价不可见标记）和 Bot 作者，避免把旧评论当作本轮回执。
• 仅在确认 Gitea 评论查询结果为“缺失”时，发起一次“只补发回执、不重复修改”的 隐藏 turn；补发仍缺失才以 Bot Token 经 Gitea REST 发布最终正文。查询结果为 unknown 时不自动重试或覆盖，任务进入 failed_reply，由终态兜底回执告知用户， 避免把已经成功落库的 MCP 回复重复发布。

FR-07 重试、恢复与状态一致性

• 网络/进程级暂时错误使用持久 retry_wait 和指数退避；执行 turn 因重启被 中断时最多自动重试一次，禁止无界重试。
• queued 重启后恢复调度；waiting_user 保留原会话等待新评论；running 恢复为 retry_wait 并带 interrupted_by_restart 原因；终态不重新执行。
• 所有状态变更、评论发送、MCP 工具调用和重试都追加审计事件，状态写入遵循 版本号/单调序列，防止旧事件覆盖新状态。

FR-08 运维控制与审计

• 全局 pause/resume：暂停只阻止新任务领取，已运行任务继续或由管理员另行中止。
• 仓库 disable/enable：停用后拒绝该仓库的新触发并保留历史；正在运行的任务 不强制杀死。
• cancel queued、abort running turn 必须幂等，响应包含当前状态和操作者。
• 审计事件至少包含 eventId、taskId、sessionKey、actor、action、fromState、 toState、deliveryId、turnId、commentId、errorCode、timestamp；支持按仓库、 资源、任务和时间范围查询。

6. 状态机

6.1 任务状态

状态	含义	可转移
received	已验签并完成事件规范化	queued、ignored、duplicate、rejected
queued	等待仓库锁和全局槽位	preparing、cancelled
preparing	正在登记仓库、clone/fetch、构造线程	running、blocked_workspace、retry_wait、failed
running	Codex App turn 执行中	waiting_user、verifying_reply、retry_wait、aborting、failed
waiting_user	Agent 需要用户补充，保留会话	queued（新评论）、cancelled、failed
verifying_reply	已收到 turn 完成，等待确认最终评论	succeeded、retry_wait、failed_reply
retry_wait	到达退避时间，等待有限次重试	preparing、running、verifying_reply、failed
blocked_workspace	工作区脏/冲突/权限问题	queued（管理员解除后）、cancelled
aborting	已请求取消，等待 Codex App 确认	aborted、failed
succeeded	最终回帖已确认	终态
succeeded_with_rest_fallback	使用 REST 兜底回帖成功	终态
failed / failed_reply	执行或回帖不可恢复失败	终态
cancelled / aborted	排队取消或运行中止	终态
ignored / duplicate / rejected	未触发、重复或安全拒绝	终态

6.2 状态不变量

1. 只有 preparing/running/aborting 持有仓库锁；同一 repoKey 同时最多一个 运行中任务。
2. 终态任务不得创建新 turn、状态评论或重试；重复 Webhook 只能返回原任务。
3. verifying_reply 必须引用本轮 turnId；failed_reply 不代表代码执行必然 失败，必须在审计中区分 executionError 与 replyError。
4. waiting_user 的新评论创建新 taskId，但复用同一 sessionKey/threadId。

7. 非功能需求与风险

类别	要求
安全	HMAC 常量时间校验、凭据隔离、Bot 自触发抑制、敏感字段脱敏
一致性	delivery/task/session/turn/comment 均有唯一键；状态变更可重放且幂等
可恢复性	进程重启不丢队列、会话映射和回帖确认上下文
可观测性	结构化日志 + 审计事件 + task/session/turn 关联 ID
性能	Webhook 验签与入队不等待 Agent 完成；并发只受仓库锁约束
数据保留	任务/会话/审计至少保留到管理员显式清理策略生效；工作区持久保留
风险	gitea-mcp 全写权限意味着 Bot 能修改代码和 Gitea 内容；通过 HMAC、暂停、
中止、审计和脏工作区保护降低风险，不声称实现细粒度授权

8. 验收标准与需求覆盖矩阵

每个验收项都应能在集成测试、协议 mock 或只读审计中独立验证。

ID	验收标准	覆盖需求/设计
AC-01	合法 Issue 普通评论含 @ccweb-bot 创建任务；无 mention、非评论或 Bot 自评论不创建任务	FR-01
AC-02	HMAC 错误返回 401 且无业务写入；相同 delivery 重放不增加任务数	FR-02
AC-03	首次合法触发自动登记仓库并 clone；再次触发只 fetch；脏工作区不被 reset/覆盖	FR-03
AC-04	同仓库两个任务严格串行；两个仓库可并行；不额外施加全局并发上限	FR-04
AC-05	同一 Issue/PR 多条评论复用一个 threadId，每条任务有唯一 turnId	FR-05
AC-06	Codex App 运行时固定 codexapp+yolo；官方 gitea-mcp 以线程级 stdio 配置启动	FR-05
AC-07	合法任务仅有一条“已收到”起始回执；成功正文由 MCP/REST 兜底承担，失败或控制终态最多一条结果回执，Bot 评论不会回触发	FR-06
AC-08	MCP 最终回帖能按 taskId+turnId+resourceKey 确认；缺失只补发一次，随后 REST 兜底	FR-06
AC-09	重启后 queued 继续、waiting_user 保留、running 最多重试一次；终态不重跑	FR-07
AC-10	pause 阻止新领取；仓库 disable 拒绝新任务；cancel/abort 幂等且释放相应资源	FR-08
AC-11	审计可按 task/session/repo 查询，包含状态迁移、delivery、turn、comment 和错误字段	FR-08
AC-12	PRD 与 ARCHITECTURE 的状态枚举、字段名、默认并发、回帖错误语义完全一致	文档一致性
AC-13	生产挂接包含 server.js 路由、lib/gitea-workflow-* 核心模块、管理页与离线回归；不新增第三方依赖	交付约束

9. 交付边界与后续演进

当前仓库已提供 MVP 实现：POST /api/gitea/webhook、持久任务/队列、工作区维护、 Codex App 线程级 gitea-mcp 注入、回帖确认/兜底、管理 API/UI 和离线回归。实现与 测试必须继续以本 PRD 的 FR/AC 编号作为审计索引。

后续可独立评估：多实例、细粒度授权、审批门、工作区隔离容器、任务预算、 SSE/前端实时镜像和更多 Forge 适配；这些不改变 MVP 的 sessionKey、幂等和回帖 确认约束。