shiyue/cc-web

Fork 0

Files

shiyue bd20a79d4b feat: support MCP elicitation and rebuild release

2026-08-24 17:39:41 +08:00

24 KiB

Raw Permalink Blame History

Gitea Webhook 驱动 ccweb 工作流架构设计

设计基线：PRD.md
目标：定义并实现可实施、可恢复、可审计的协议与数据边界。
MVP：单 Gitea 实例、全局 ccweb-bot。

1. 设计原则与边界

事件先持久化，执行后置：Webhook 线程只做验签、去重、规范化和入队，不同步等待 Codex App 或 Gitea 回帖。
仓库是互斥单元，资源是会话单元：repoKey 决定工作区锁， sessionKey 决定 Issue/PR 独立线程；二者不能混用。
所有外部动作可重放且幂等：delivery、起始回执、MCP 最终回帖和 REST 兜底均带关联键，重复请求只能得到已有结果。
Gitea 是事实来源：cc-web 的状态是工作流镜像；最终用户内容必须能在 Gitea Issue/PR 中查到，MCP 返回成功不等于回帖已落库。
运行时协议贴近 Codex App：初始化后发送 initialized，能力探测失败只降级记录；使用 collaboration mode 时参数放入 settings，不重复传顶层字段。
线程级注入来源上下文：Gitea MCP 配置随 thread/start.config 注入，不使用长驻 app-server 的进程级环境承载某个来源会话的上下文。

当前实现采用项目现有 JSON 持久化（lib/gitea-workflow-store.js），并由 server.js 挂接 HTTP 路由、lib/gitea-workflow-*.js 提供领域实现、public/ 提供管理镜像。所有实现仍必须满足下文的原子写、唯一约束和恢复语义。

2. 逻辑拓扑

┌──────────────┐       HMAC Webhook        ┌──────────────────────────┐
│ Gitea 实例   │ ─────────────────────────▶ │ Webhook Adapter          │
│ Issue/PR     │                            │ 验签/规范化/去重/入队     │
└──────┬───────┘                            └──────────┬───────────────┘
       │ REST 查询/兜底                                  │
       │                                                  ▼
       │                                        ┌──────────────────────┐
       │                                        │ Workflow Store        │
       │                                        │ tasks/sessions/audit  │
       │                                        └──────────┬───────────┘
       │                                                   │
       │                                        ┌──────────▼───────────┐
       │                                        │ Scheduler             │
       │                                        │ repo lock              │
       │                                        └──────┬───────┬────────┘
       │                                               │       │
       │                                  ┌────────────▼─┐ ┌───▼─────────────┐
       │                                  │ Workspace     │ │ Session Manager  │
       │                                  │ clone/fetch   │ │ thread/turn      │
       │                                  └──────┬────────┘ └───┬─────────────┘
       │                                         │              │ JSON-RPC
       │                                         │              ▼
       │                                         │      ┌──────────────────┐
       │                                         └─────▶│ Codex App Server  │
       │                                                │ codexapp + yolo    │
       │                                                └────────┬─────────┘
       │                                                         │ stdio MCP
       │                                                         ▼
       └─────────────────────────────────────────────────┌───────────────┐
                                                         │ gitea-mcp      │
                                                         │ 官方 stdio     │
                                                         └───────────────┘

运维 API/UI ──只读查询/控制──▶ Workflow Store + Scheduler + Audit

组件职责：

组件	职责	不负责
Webhook Adapter	原始 body 验签、delivery 去重、Bot/mention 过滤、规范化	启动 Agent、直接执行 Git
Workflow Store	任务、会话、turn、评论、仓库、控制面和审计的持久化	远程调用
Scheduler	FIFO、每仓库 lease、恢复扫描	解析业务 prompt
Workspace Manager	自动登记、clone/fetch、分支上下文、脏目录保护	修改用户代码内容
Session Manager	Codex App initialize、thread/turn、事件序列、取消	直接向 Gitea 发最终正文
MCP Bridge	为线程启动官方 `gitea-mcp` stdio 并传递 host/token	代替 Agent 决策
Reply Verifier	查询评论、校验 taskId/turnId/resourceKey、触发有限补偿	无条件重复回帖
Control/Audit API	暂停、停用、取消、中止、查询和审计导出	让用户切换 Agent 模式

3. 标识符与幂等键

名称	格式/来源	唯一性与用途
`instanceId`	固定 `default`	为未来多实例预留命名空间
`repoKey`	`default:<owner>/<repo>`	仓库锁、工作区和并发分区
`resourceKey`	`<repoKey>:<kind>:<number>`	Issue/PR 资源身份
`sessionKey`	同 `resourceKey`	一个资源一个 Codex App thread
`deliveryKey`	`default:<X-Gitea-Delivery>`	Webhook 去重；无 header 时使用可靠 payload ID，否则拒绝
`taskId`	`gitea-task-` + deliveryKey 的 SHA-256 前缀	一次用户评论触发的一次可审计任务；同一 delivery 重放保持不变
`threadId`	Codex App 返回值	跨任务复用同一资源上下文
`turnId`	Codex App 每轮返回值	最终回帖确认和恢复边界
`commentId`	Gitea 返回值	状态/最终/兜底评论幂等引用
`leaseId`	UUID + expiry	Scheduler 持有仓库锁和全局槽位的租约

所有唯一键写入必须在同一事务/原子文件替换中完成。重复请求返回原记录，不生成新的 taskId、turnId 或评论。

4. 持久化数据模型

字段名是跨模块契约；时间统一 ISO-8601 UTC，所有枚举使用小写 snake_case。

4.1 `webhook_deliveries`

{
  "deliveryKey": "default:8f7…",
  "deliveryId": "8f7…",
  "eventType": "issue_comment",
  "receivedAt": "2026-08-24T08:00:00Z",
  "signatureValid": true,
  "normalized": true,
  "taskId": "task-uuid-or-null",
  "status": "accepted|ignored|duplicate|rejected",
  "payloadHash": "sha256:…",
  "expiresAt": "2026-09-23T08:00:00Z"
}

deliveryKey 唯一；保留期必须覆盖 Gitea 可能的重试窗口。验签失败可只写安全审计，不写入可用于重放的业务 payload。

4.2 `repositories`

{
  "repoKey": "default:acme/widget",
  "instanceId": "default",
  "owner": "acme",
  "name": "widget",
  "cloneUrl": "https://gitea.example/acme/widget.git",
  "workspacePath": "/workspace/default/acme/widget",
  "defaultBranch": "main",
  "status": "active|disabled|blocked",
  "registeredAt": "2026-08-24T08:00:00Z",
  "lastFetchAt": "2026-08-24T08:02:00Z",
  "version": 3
}

注册采用 compare-and-swap：并发首次触发只能产生一条记录。Token 不落在 cloneUrl；workspacePath 必须经过根目录规范化，禁止路径穿越。

4.3 `sessions`

{
  "sessionKey": "default:acme/widget:issue:42",
  "resourceKey": "default:acme/widget:issue:42",
  "kind": "issue",
  "number": 42,
  "threadId": "thread_…",
  "runtime": {"app": "codexapp", "mode": "yolo"},
  "mcp": {"server": "gitea", "transport": "stdio", "hostRef": "gitea-main"},
  "status": "active|waiting_user|closed",
  "lastTaskId": "task-uuid",
  "lastTurnId": "turn_…",
  "createdAt": "2026-08-24T08:03:00Z",
  "updatedAt": "2026-08-24T08:10:00Z",
  "version": 7
}

sessionKey 唯一，threadId 创建后不可因普通重试而替换；只有明确恢复失败并经审计后才允许新线程。

4.4 `tasks`

{
  "taskId": "task-uuid",
  "deliveryKey": "default:8f7…",
  "repoKey": "default:acme/widget",
  "resourceKey": "default:acme/widget:issue:42",
  "sessionKey": "default:acme/widget:issue:42",
  "commentId": 101,
  "author": "alice",
  "instruction": "请修复……",
  "state": "queued",
  "attempt": 0,
  "replyAttempt": 0,
  "threadId": "thread_…",
  "turnId": null,
  "leaseId": null,
  "nextRetryAt": null,
  "errorCode": null,
  "createdAt": "2026-08-24T08:00:01Z",
  "updatedAt": "2026-08-24T08:00:01Z",
  "stateVersion": 1
}

任务状态必须与 PRD 第 6 节一致；stateVersion 防止并发 worker 的旧写覆盖新写。

4.5 `turns`、`comments`、`audit_events` 与控制面

{
  "turn": {
    "turnId": "turn_…",
    "taskId": "task-uuid",
    "threadId": "thread_…",
    "kind": "normal|reply_retry",
    "status": "started|completed|interrupted|failed|cancelled",
    "eventSeq": 18,
    "startedAt": "…",
    "completedAt": null
  },
  "comment": {
    "commentKey": "task-uuid:status:running",
    "taskId": "task-uuid",
    "kind": "status|mcp_final|rest_fallback",
    "resourceKey": "default:acme/widget:issue:42",
    "turnId": "turn_…",
    "commentId": 102,
    "bodyHash": "sha256:…",
    "status": "pending|sent|confirmed|failed"
  },
  "audit_event": {
    "eventId": "audit-uuid",
    "taskId": "task-uuid-or-null",
    "action": "webhook.accept|task.claim|mcp.call|reply.confirm|…",
    "actor": "system|admin:alice|gitea:user:alice",
    "fromState": "running",
    "toState": "verifying_reply",
    "deliveryId": "8f7…",
    "turnId": "turn_…",
    "commentId": 102,
    "errorCode": null,
    "timestamp": "…",
    "metadata": {"attempt": 0}
  },
  "control": {
    "globalPaused": false,
    "pauseReason": null,
    "updatedBy": "admin:alice",
    "updatedAt": "…",
    "version": 4
  }
}

commentKey 是起始/异常结果回执的幂等键；最终回帖以 taskId+turnId 为主键，REST 兜底不能覆盖已确认的 MCP 评论。

5. 处理时序与事务边界

5.1 Webhook 接收

读取 raw body 和签名 header；HMAC 失败立即 401。
提取 delivery/event header，计算 payloadHash；在 webhook_deliveries 上做唯一插入。
已存在 delivery 时返回原处理结果；首次插入后解析事件。
过滤非评论、无 mention、Bot 自评论、停用仓库；分别落为 ignored/rejected，并追加审计。
在一个原子操作中登记仓库（若需要）、创建 Session 引用和 Task，状态为 received → queued，写入 delivery 与 task 的关联。
立即返回 202（已入队）和 taskId；不等待 clone、Codex App 或评论发送。

5.2 调度与工作区

Scheduler 扫描 queued、到期 retry_wait 和管理员解除的 blocked_workspace。
先检查全局暂停、仓库 active，再以租约方式获取 repo lock。
CAS 将任务置为 preparing；租约含 leaseId/owner/expiresAt，心跳续租。
Workspace Manager 创建目录或执行安全 fetch。失败按错误矩阵决定 blocked_workspace、retry_wait 或 failed。
任务入队后发送唯一的幂等 giteabot: 已收到 起始回执，再将任务置为 running 并启动/恢复 turn；运行中、等待用户和成功状态不再额外发评论。

5.3 Codex App 与 MCP

对长驻 app-server 只初始化一次；成功后发送 initialized notification。
best-effort 探测 experimentalFeature/enablement/set(goals=true) 和 collaborationMode/list；探测失败只记日志并保留降级能力。
thread/start 注入工作区 cwd 和线程级 mcp_servers.gitea；若使用 collaboration mode，model/reasoning_effort/developer_instructions 放在 collaborationMode.settings，顶层不得重复。
turn/start 仅传本轮指令和关联元数据，落库返回的 turnId；按事件序号更新 turns.eventSeq，重复事件不重复处理。
turn 完成后根据 stop reason 判断 waiting_user、执行失败或进入 verifying_reply。

5.4 回帖确认与补偿

仅当 Agent 通过 gitea-mcp 发起最终评论后，才把任务置为 verifying_reply。
Reply Verifier 通过 Gitea API/MCP 查询原资源评论，匹配 Bot 作者、 taskId、turnId 和 resourceKey 标记；确认成功则 succeeded。
只有 Gitea 查询明确返回“评论缺失”时，才将 replyAttempt += 1 并最多创建一个 reply_retry turn；prompt 明确“只补发上一轮最终文本，不重复修改”。查询异常/状态未知不自动写操作，直接标记 failed_reply 并发送状态告警。
reply_retry 仍无法确认时，使用 REST Bot Token 发一条带同样关联标记的兜底评论；成功为 succeeded_with_rest_fallback，失败为 failed_reply。每一步都写审计。

5.5 重启恢复

启动恢复扫描按以下顺序执行：

未过期租约保留 owner；过期租约释放 repo lock 并记录事件。
queued 直接重新入队；retry_wait 按 nextRetryAt 等待。
running/preparing/aborting 若无活跃 worker，标记 retry_wait(errorCode=interrupted_by_restart)；超过执行重试上限则 failed。
waiting_user、所有终态和已确认评论不自动重跑。
恢复过程使用 stateVersion CAS，单实例 Scheduler 只能产生一个有效租约。

5.6 规范状态与转移契约

实现层必须使用以下完整枚举；状态名、终态和转移条件与 PRD 第 6 节保持一致：

当前状态	允许的下一状态	触发者/守卫
`received`	`queued` / `ignored` / `duplicate` / `rejected`	Webhook Adapter 完成规范化
`queued`	`preparing` / `cancelled`	Scheduler 已取得全局槽位和仓库租约；取消请求
`preparing`	`running` / `blocked_workspace` / `retry_wait` / `failed`	Workspace/Session Manager 结果
`running`	`waiting_user` / `verifying_reply` / `retry_wait` / `aborting` / `failed`	Codex App stop reason、错误或管理员中止
`waiting_user`	`queued` / `cancelled` / `failed`	新评论、取消请求或会话不可恢复
`verifying_reply`	`succeeded` / `retry_wait` / `failed_reply`	Reply Verifier 结果；仅允许一次 reply retry
`retry_wait`	`preparing` / `running` / `verifying_reply` / `failed`	`nextRetryAt` 到期且未超过上限
`blocked_workspace`	`queued` / `cancelled`	管理员确认工作区可用或取消
`aborting`	`aborted` / `failed`	Codex App 取消确认或超时
`succeeded` / `succeeded_with_rest_fallback` / `failed` / `failed_reply` / `cancelled` / `aborted` / `ignored` / `duplicate` / `rejected`	无	终态，不得创建新 turn

每次转移都必须带 fromState/toState/stateVersion 和审计事件；未知状态或非法转移拒绝写入并告警。aborting 释放资源前不得被误标为 aborted， succeeded_with_rest_fallback 必须保留原始 MCP 回帖失败原因。

6. 接口契约

6.1 Webhook HTTP

Endpoint：POST /api/gitea/webhook（路径可由部署配置映射，但语义固定）

请求要求：

Content-Type: application/json
X-Gitea-Event: issue_comment
X-Gitea-Delivery: 8f7e…
X-Gitea-Signature: <HMAC-SHA256(raw_body, webhook_secret)>

适配器至少抽取以下规范化结构；原始 payload 只按安全保留策略保存 hash：

{
  "instanceId": "default",
  "deliveryId": "8f7e…",
  "eventType": "issue_comment|pull_request_comment",
  "repo": {"owner": "acme", "name": "widget", "cloneUrl": "…"},
  "resource": {"kind": "issue|pull_request", "number": 42},
  "comment": {"id": 101, "body": "@ccweb-bot 请修复…", "createdAt": "…"},
  "actor": {"login": "alice", "isBot": false},
  "refs": {"base": "main", "head": "feature/x"}
}

响应语义：

HTTP	场景	业务效果
202	验签通过且首次入队	返回 `{deliveryId, taskId, state:"queued"}`
200	重复 delivery、合法但忽略的事件	返回原 task 或 `{status:"ignored"}`
400	JSON/必需字段无法解析	不入队，记录 `invalid_payload`
401	HMAC 缺失或错误	不入队，不暴露内部原因
409	仓库被管理员停用且策略为拒绝	返回 `repository_disabled`，不创建运行任务
500/503	持久化不可用	Gitea 可重试；不得声称已入队

6.2 控制与查询 API（逻辑契约）

实现可映射到现有 cc-web 路由，但字段和幂等语义保持不变：

方法	逻辑路径	作用
GET	`/api/gitea-workflow/overview`	全局暂停、运行槽位、队列摘要
GET	`/api/gitea-workflow/tasks?repoKey=&resourceKey=&state=`	分页查询任务
GET	`/api/gitea-workflow/tasks/:taskId`	任务、turn、评论和错误详情
POST	`/api/gitea-workflow/control/pause` / `resume`	全局暂停/恢复；body 带 reason
POST	`/api/gitea-workflow/repos/:repoKey/disable` / `enable`	仓库停用/启用
POST	`/api/gitea-workflow/tasks/:taskId/cancel`	仅取消 queued/waiting_user
POST	`/api/gitea-workflow/tasks/:taskId/abort`	请求中止 running turn
GET	`/api/gitea-workflow/audit?...`	按关联 ID/时间范围查询审计

控制请求必须带操作者身份、幂等 requestId 和 reason；重复 requestId 返回首次结果，不重复发送取消或评论。API 不接收模型、MCP 工具参数或任意 Git 命令。

6.3 Codex App JSON-RPC 形状

初始化链路：

initialize → initialized(notification)
          → experimentalFeature/enablement/set(goals=true) [best effort]
          → collaborationMode/list [best effort]
          → thread/start

线程配置契约（示意）：

{
  "cwd": "/workspace/default/acme/widget",
  "collaborationMode": {
    "settings": {
      "model": "<固定配置>",
      "reasoning_effort": "<固定配置>",
      "developer_instructions": "<工作流系统约束>"
    }
  },
  "mcp_servers": {
    "gitea": {
      "command": "gitea-mcp",
      "args": ["-t", "stdio", "-H", "https://gitea.example"],
      "env": {"GITEA_ACCESS_TOKEN": "<secret-ref>"}
    }
  }
}

当运行时拒绝 collaborationMode 或返回 unknown field 时，记录一次 capability_downgrade，本轮退回普通 turn；不能因为 goals/list 探测失败而终止 app-server。使用 collaboration mode 时，turn/start 顶层不得再传 model 或 effort。

6.4 MCP 与 Gitea REST 回帖

起始/异常回执与最终回帖分离：起始 已收到 和必要的异常终态回执由 cc-web 通过 Gitea REST 发送，使用 commentKey=taskId:status:state 幂等；正常最终答案必须优先由官方 gitea-mcp 发出，REST 只允许作为确认失败后的最终正文兜底。这样既能让用户知道任务已接收，又不会用一串运行状态文本污染 Issue/PR 讨论串。

架构对官方 gitea-mcp 的具体工具名做一层逻辑适配，避免版本差异泄漏到任务状态：

{
  "operation": "gitea.comment.create",
  "resource": {"kind": "issue|pull_request", "number": 42},
  "body": "最终答案\n<!-- ccweb taskId=… turnId=… -->",
  "idempotencyKey": "task-uuid:turn_…"
}

适配器必须将工具返回映射为 {accepted, commentId, errorCode}，并再次查询确认。 REST 兜底使用 Bot Token 调用 Gitea 的对应 Issue/PR 评论接口，body 必须复用 taskId/turnId 标记；若 REST 返回 2xx 但查询不到，状态仍为 failed_reply，不能虚报成功。

7. 并发、租约与一致性

调度只依赖 repoKey 级 lease；没有全局 semaphore 或全局并发槽位。
仓库 lease 的键为 repoKey，TTL 必须短于 worker 心跳间隔的可容忍失联窗口；释放必须校验 leaseId，防止旧 worker 解锁新 worker 的租约。
领取任务采用 stateVersion CAS：queued → preparing 成功者才可继续。
任务状态、评论幂等记录和审计事件先写入，再执行外部调用；外部调用结果以 append-only 事件补写，重试读取最后已知结果。
进程内锁只作性能优化，正确性依赖持久 lease；单实例 MVP 仍按可恢复模型设计，以便未来横向扩展。

8. 失败场景矩阵

场景	检测	状态/动作	是否重试
HMAC 缺失/错误	常量时间校验失败	401、`rejected` 审计	否
delivery 重复	唯一键冲突	返回原结果、`duplicate`	否
payload 不完整	schema 校验失败	400、`invalid_payload`	否
仓库停用	`repositories.status=disabled`	拒绝新任务	否
clone/fetch 鉴权失败	Git exit code/HTTP 401	`retry_wait`，超过上限 `failed`	最多 1 次
工作区脏或冲突	git status/lock 检查	`blocked_workspace`，不 reset	管理员解除后 1 次
全局暂停	control CAS	保持 `queued`，不领取	恢复后
租约过期	TTL/心跳超时	释放资源并恢复扫描	最多 1 次
Codex App 不可达	JSON-RPC timeout	`retry_wait`	最多 1 次
gitea-mcp 命令缺失	启动前可执行文件检查失败	`failed` + 一条 `giteabot:` 失败结果回执	不重试，修复命令后重新触发
MCP 进程启动失败	stdio 子进程启动即退出	`failed` + 一条 `giteabot:` 失败结果回执	不重试，修复命令后重新触发
MCP initialize 握手失败/超时	stdio JSON-RPC `initialize` 无成功响应	`failed` + 一条 `giteabot:` 失败结果回执	不重试，修复命令后重新触发
turn 被重启中断	无活跃 worker	`retry_wait(interrupted_by_restart)`	最多 1 次
用户补充问题	stop reason/waiting 信号	`waiting_user`，保留 thread	新评论触发
管理员中止超时	cancel 无确认	`failed` 或 `aborted`，强制释放 lease 并审计	否
MCP 最终回帖缺失	查询无匹配评论	一次 `reply_retry` turn	仅 1 次
REST 兜底失败	非 2xx/查询不到	`failed_reply` + 告警	不自动重试
Bot 自评论回调	actor/login 匹配 Bot	`ignored`	否

错误码建议使用稳定小写值（如 invalid_signature、duplicate_delivery、 workspace_dirty、app_server_timeout、mcp_reply_missing），展示文本可本地化。

9. 安全与审计设计

9.1 信任边界

Webhook Secret 只在入口使用；Bot Token 只在 Gitea MCP/REST 出站边界使用； Codex App 收到的评论、Issue 描述、代码和 PR 内容全部视为不可信数据。系统提示明确禁止将这些内容解释为更改运行时权限、读取 Secret 或关闭审计的指令。

9.2 权限与凭据

官方 gitea-mcp 按已确认需求开放写权限，但通过固定实例 host、专用 Bot Token、运维暂停/中止和完整审计进行约束。
日志仅记录 hostRef/tokenRef，不记录 Authorization、完整命令环境或原始 Secret。
Git clone/fetch 的凭据使用短生命周期注入，完成后清理；remote URL 不含 Token。

9.3 审计完整性

每个外部副作用前写入 intent 事件，完成后写入 result 事件；事件不可更新，只能追加补偿或人工操作事件。审计关联链必须可由 deliveryKey → taskId → sessionKey/threadId → turnId → commentId 重建。

10. 验收与实现交接

实现方需按 PRD.md 的 AC-01～AC-13 编写协议 mock、状态迁移、重启、并发、回帖确认和安全测试。任何无法满足的契约必须在对应审计/错误码中显式降级，不得静默跳过。

实现已按本文边界落地；后续修改不得绕过验签、状态机、幂等键和回帖核验，也不得新增未审计的外部写操作。

24 KiB Raw Permalink Blame History Unescape Escape