# Gitea Workflow × Codex App 集成地图

> 分析日期：2026-08-24
>
> 范围：只读分析 Codex App 的 `thread/start` MCP 配置、会话创建、消息处理、turn 完成、后台运行、重启恢复和现有回归入口。未修改 `server.js`、`lib/`、`public/`。

## 证据与方法

- codebase-memory 项目：`home-cc-web`，`list_projects` 返回根目录 `/home/cc-web`，节点 6670、边 15041；`index_status` 为 `ready`。
- 使用 `get_architecture(aspects=["all"])` 确认 `server`、`codex-app-runtime`、`regression`、`codex` 等模块边界。
- 使用 `search_graph`、`get_code_snippet`、`trace_path(mode="calls")` 定位函数和调用关系；再以 `rg -n`/`nl -ba` 交叉核对行号。
- 图谱无法把回调赋值完整表示出来：`handleCodexAppNotification` 的调用者列表为空，但源码显示它在 `getCodexAppClient()` 作为 `onNotification` 回调传入客户端，再由 JSONL 客户端转发。因此下图的“回调边”以源码为准。

## 端到端运行链路

```text
WebSocket message (server.js:7706-7766)
  -> handleMessage (server.js:9852-10190)
  -> handleCodexAppMessage (server.js:11888-11960)
     -> activeCodexAppTurns + persistCodexAppTurnState(immediate)
     -> startCodexAppTurn (server.js:11962-12022)
        -> getCodexAppClient (server.js:11782-11845)
           -> createCodexAppServerClient (lib/codex-app-server-client.js:6-223)
              initialize -> initialized -> postInitialize
        -> thread/start 或 thread/resume (threadParams)
           -> codexAppThreadConfig -> mcp_servers.* / web_search
        -> turn/start (collaborationMode)
  -> app-server stdout JSONL
     -> client.handleMessage (lib/codex-app-server-client.js:78-111)
        -> onNotification(handleCodexAppNotification)
           -> findCodexAppRouteByRuntime (server.js:11050-11066)
           -> codexAppRuntime.processCodexAppNotification (lib/codex-app-runtime.js:865-1040)
           -> persist state; turn/completed -> handleCodexAppTurnComplete
```

### 1. 线程级 MCP 配置和环境

| 位置 | 行号 | 当前行为 | Gitea 扩展建议 |
|---|---:|---|---|
| `server.js` `buildCcwebMcpRuntimeConfig` | 2709-2753 | 生成内置 `ccweb` MCP；HTTP 模式把来源会话/跳数放入 URL，stdio 模式生成命令及 env。 | Gitea MCP 应作为同级线程配置注入，不要改 app-server 进程全局 env。 |
| `server.js` `listRuntimeMcpServerConfigs` | 2755-2772 | 合并项目 `.codex/config.toml` MCP 与内置 `ccweb`，按规范化 server 名去重。 | 增加 workflow 专属配置的明确入口（建议由 `mcpContext`/工作流配置传入），并定义与项目同名时的优先级。 |
| `server.js` `codexAppCcwebMcpEnv` | 11680-11691 | 输出 `CC_WEB_SOURCE_SESSION_ID`、`CC_WEB_CROSS_HOP_COUNT`、内部 token 等。 | Gitea 仓库/任务 ID 应随 `thread/start.config.mcp_servers.gitea.env` 下发；不要写入 `buildCodexAppClientSpec().env`。 |
| `server.js` `codexAppThreadConfig` | 11693-11702 | 把 runtime 配置映射为 `config["mcp_servers.<server>"]`，并设置 `web_search`。 | 这是最直接的 `gitea-mcp` 注入扩展点；应保证每个线程拿到独立 host/token/workflow 上下文。 |
| `server.js` `codexAppThreadParams` | 11857-11868 | 组装 cwd、model、权限和 `config`，用于 start/resume。 | Gitea 任务必须从这里同时覆盖 `thread/start` 和 `thread/resume`，避免重试/恢复丢 MCP。 |
| `server.js` `buildCodexAppClientSpec` | 11735-11780 | 构造单例 app-server 进程的 command/args/env/signature；会剥离敏感环境变量。 | 不要把仓库 token 放此处；若新增全局配置，需纳入 signature 并评估活跃 turn 的复用策略。 |

当前 `codexAppCcwebMcpEnv` 已证明“来源上下文线程级下发”可行。Gitea 方案应沿用这一模式，例如 `mcp_servers.gitea` 的 `command/args/env` 或 streamable HTTP 配置，而不是 dynamic tools。

### 2. 会话创建、turn 启动和协作参数

| 位置 | 行号 | 当前行为 | Gitea 扩展建议 |
|---|---:|---|---|
| `server.js` WebSocket 分发 | 7706-7766 | `message` 进入 `handleMessage`；slash 先经 `handleSlashCommand`。 | Webhook 不应伪造 WebSocket；工作流服务可调用同一内部处理函数或抽取“创建/投递消息”服务层。 |
| `server.js` `handleMessage` | 9852-10190 | 校验输入、创建/加载 JSON 会话、持久化用户消息；Codex App 分支调用 `handleCodexAppMessage`。`ws` 可为 null，`wsSend` 会安全忽略。 | 后台 Gitea 任务可复用会话创建逻辑，但应显式传 workflow 元数据、固定 agent=`codexapp`/yolo，并避免前端 slash 语义污染。 |
| `server.js` `handleCodexAppMessage` | 11888-11960 | 建立 `activeCodexAppTurns` entry，记录 `mcpContext`/retry 信息，立即写 state，然后异步启动 turn。 | 在 entry/retry state 中保留不可变的 Gitea workflow/task/repository correlation；该信息不能只存在内存。 |
| `server.js` `startCodexAppTurn` | 11962-12022 | 复用单例客户端；有 threadId 则 resume，否则 start；校验恢复线程 ID；保存 runtime thread ID；发送 turn/start。 | Gitea 首次任务走 start，后续评论/重试走同一 thread resume；将 gitea MCP 配置传入 `codexAppThreadParams`，并在 mismatch 时按任务失败处理。 |
| `server.js` `codexAppCollaborationMode` / `codexAppTurnParams` | 11704-11712、11870-11886 | collaboration mode 总是存在，`plan` 映射 plan，否则 default；model/reasoning_effort/developer instructions 放 settings，顶层不重复 model/effort。 | 后台固定 yolo 会得到 mode=default；不要为 Gitea 任务再传顶层 model/effort，避免回到非原生协作路径。 |
| `server.js` `codexAppPostInitialize` | 11714-11733 | initialize 后 best-effort 探测 goals 和 `collaborationMode/list`，失败只记日志。 | Gitea 集成不应依赖探测成功；可在能力缺失时记录降级并继续普通 turn。 |

### 3. JSON-RPC 客户端、通知、服务端请求

| 位置 | 行号 | 当前行为 | Gitea 扩展建议 |
|---|---:|---|---|
| `lib/codex-app-server-client.js` `handleMessage` | 78-111 | 以 `id` 区分 pending response/server request；无 `id` 的 method 交给 `onNotification`。 | 回执监听应基于 turn/thread ID，不要解析 UI 文本；保留未知 method 日志。 |
| `lib/codex-app-server-client.js` `start` | 140-190 | 启动 stdio app-server，绑定 readline，initialize/initialized，再运行 `postInitialize`；退出 reject 所有 pending。 | gitea-mcp 子进程由 app-server 按线程配置管理；不要另起一套 app-server 连接。 |
| `server.js` `getCodexAppClient` | 11782-11845 | 全局单例 `codexAppClient`；配置 signature 变化时若有其他活跃 turn 会复用旧客户端，否则失败残留并重启。 | 队列不能通过频繁改全局 config 切换仓库；每个任务使用线程 config，避免触发 singleton stale-config 分支。 |
| `server.js` `handleCodexAppNotification` | 11105-11155 | 先处理 compact/Goal/MCP startup，再按 parent/child/磁盘恢复路由；runtime 返回 done 时进入完成处理。 | Gitea 回执监听应挂在此处或其下游的领域事件，而不是监听 WebSocket `done`；需识别 `turn/completed` 的 status/error。 |
| `server.js` `handleCodexAppServerRequest` | 11572-11608 | 处理 approval、user input、dynamic tool；未知请求按保守策略拒绝。 | gitea-mcp 是 MCP server，不应新增 dynamic tool 旁路；若需要用户确认，明确映射到工作流 waiting_user。 |
| `server.js` `handleCodexAppServerExit` / `handleCodexAppTurnFailure` | 11610-11637、12165-12170 | app-server 退出会使所有 active Codex App turn 失败；失败统一进入完成清理和重试判定。 | Gitea 任务需把此类失败映射为可恢复状态，防止一次 singleton 退出同时丢失多个仓库任务。 |

### 4. turn 完成、后台运行与持久化恢复

| 位置 | 行号 | 当前行为 | Gitea 扩展建议 |
|---|---:|---|---|
| `server.js` `handleCodexAppTurnComplete` | 12024-12163 | 去重并持久化 assistant/toolCalls；处理 transient retry；删除 active entry、清理 run dir；有 ws 发 `done`，无 ws 则广播 `background_done` 并调用通知。 | 在删除 entry/清理目录前写入 workflow completion/outbox；回执确认、补触发和 REST 兜底必须幂等。建议发领域事件，避免依赖 `sendNotification`。 |
| `server.js` `handleCodexAppSteerMessage` | 12189-12419 | 运行中用 `turn/steer`；遇到 no-active-turn 会先收敛旧输出，再复用消息启动新 turn。 | Gitea 连续评论可转为 steer，但要用任务级 message/delivery ID 去重，避免 steer fallback 重复修改仓库。 |
| `server.js` `handleCodexAppAbortSession` | 12421-12451 | 发送 `turn/interrupt`，超时后强制完成；无可用 client 直接以 interrupted 完成。 | 工作流取消/仓库停用可复用，但状态机需区分用户取消、运维中止、app-server 崩溃。 |
| `server.js` `writeCodexAppTurnState` / `persistCodexAppTurnState` / `loadCodexAppTurnState` | 5039-5059、5061-5082、5093-5116 | state 原子写入、延迟 flush、大小保护；序列化当前 turn 文本/toolCalls/usage/error。 | 必须把 workflow/task/repository correlation 和回执状态纳入独立持久化（或扩展 state schema），不能只依赖 `entry.mcpContext`。 |
| `server.js` `recoverCodexAppTurnState` | 5137-5226 | 重启后恢复 partial assistant/toolCalls，写 interrupted system message，清理 run dir；不自动继续 turn。 | `queued`/`waiting_user`/`running` 的 Gitea 状态恢复应在工作流队列层实现；running 只能标为 interrupted 后按策略最多重试一次。 |
| `server.js` `recoverProcesses` + 启动调用 | 7398-7490、12950 | 启动扫描 `*-run`；Codex App state 优先走 `recoverCodexAppTurnState`，普通进程走 JSONL tail/replay。 | 工作流恢复入口应在此生命周期之后加载 durable queue，再决定是否重新投递；不要在 `recoverProcesses` 中直接执行 Gitea 网络副作用。 |
| `server.js` `updateSessionRuntimeThreadIndex` / `saveSession` | 3443-3456、4497-4520 | 保存会话时维护 thread→session O(1) 索引；未知线程有负缓存，避免通知热路径反复扫盘。 | Gitea 任务必须持久化稳定 session/thread 映射；删除仓库/会话时同步清理映射，避免跨仓库通知串线。 |
| `server.js` `findCodexAppRouteByRuntime` | 11050-11066 | parent active entry → 已知 child thread → 磁盘 adopt；child 先于 parent adoption。 | Gitea MCP 可能产生 child/collab activity，工作流回执只认 parent turn；需保留 child 事件但禁止把 child completion 当最终回执。 |

无 WebSocket 的后台路径是可行的：`handleMessage(null, ...)` 的 `wsSend` 为空安全，`handleCodexAppTurnComplete` 会走 `background_done`/通知分支。但该分支目前没有 Gitea 专属完成回调，必须增加可持久化的领域事件或 outbox。

## 建议的最小扩展边界

1. 新增独立 Gitea Workflow 服务/存储模块：Webhook 验签、delivery 去重、仓库/任务状态机、同仓库锁、全局并发上限、outbox/审计。不要把队列逻辑塞进 `handleMessage` 或 app-server 客户端。
2. 为 Codex App 调用增加“线程级 MCP 配置”参数（沿用 `mcpContext` 传递），在 `listRuntimeMcpServerConfigs` → `codexAppThreadConfig` → `codexAppThreadParams` 形成单向注入；官方 `gitea-mcp` 使用 stdio 或明确的 streamable HTTP 配置，token 只放线程 env/安全存储。
3. 将 workflow correlation（实例、owner/repo、issue/PR、评论 delivery、turn ID）写入独立任务记录，并在 turn state 中保存最小引用，保证进程重启和自动重试可恢复。
4. 在 `handleCodexAppNotification`/`handleCodexAppTurnComplete` 旁增加内部领域事件适配器：先 durable commit，再确认 Gitea 评论；缺失回执只允许一次补触发，最后 REST 兜底。
5. 后台任务通过现有 Codex App 单例运行，但由 Gitea 队列决定何时调用；不要修改 `buildCodexAppClientSpec` 的全局环境来切换仓库。

## 潜在冲突与风险

- **单例 app-server 与多仓库并发**：`getCodexAppClient` 只有一个 client，退出会影响全部 active turns；队列必须在 client 层之上做并发/重试隔离。
- **线程配置与进程环境边界**：`buildCodexAppClientSpec` 的 env 是进程级，不能承载某个仓库的 Gitea token；否则并发任务会串凭据。
- **恢复丢失 MCP 上下文**：`adoptCodexAppUnroutedTurn`（`server.js:10379-10423`）新建 entry 时 `mcpContext: {}`；`recoverCodexAppTurnState` 也只恢复输出，不恢复 workflow 上下文。必须把上下文放独立任务记录或 state schema。
- **完成清理时序**：`handleCodexAppTurnComplete` 在 12087-12088 删除 active entry/清理 run dir，之后才通知后台客户端；回执 outbox 必须在清理前落盘。
- **自动重试副作用**：`shouldRetryCodexTransientFailure` 路径会重新启动 turn；若模型已修改仓库或已发评论，需用任务/评论/turn 幂等键防止重复写入。
- **通知路由与未知线程**：当前有 O(1) index、磁盘 adoption 和负缓存；Gitea 不能只依赖内存 active map，否则重启后通知会变成 unrouted。
- **现有运行保护**：`handleMessage` 会拒绝 active turn/Goal/compaction；工作流必须先做同仓库串行和取消策略，不能靠重复调用绕过保护。
- **协作模式形状**：启用 collaborationMode 时顶层不得重复 `model`/`effort`；gitea workflow 的 yolo 固定策略应保持 `mode=default` + settings。
- **安全边界**：Webhook HMAC、Bot 自评论过滤、delivery 去重、token 脱敏、remote URL 不落 token，需要在 Gitea 层完成，不能依赖 Codex App MCP 工具自行保证。

## 必须补的测试

### Codex App 协议/单元回归

- `thread/start` 首次任务与 `thread/resume` 重试都包含 `mcp_servers.gitea`，且每个 session 的 host/token/workflow env 隔离；项目 MCP、ccweb MCP、gitea MCP 同时存在时不丢失/不误去重。
- collaborationMode 仍把 model/reasoning_effort/developer instructions 放在 `settings`，顶层没有重复 model/effort；yolo 固定为 default。
- `handleMessage(null, ...)` 能创建后台 Codex App 会话；无 ws 完成时仍持久化 assistant/toolCalls，并触发可断言的 workflow completion/outbox，而不是只依赖 push notification。
- turn state 原子写入/重启恢复包含 workflow correlation；恢复后 parent thread、gitea MCP 配置和回执状态不丢失；未知线程 adoption 不得把 child 事件当 parent 最终完成。
- app-server 退出、transient capacity/reconnect、thread resume mismatch、steer no-active-turn 均只产生一次工作流状态转移和一次回执动作。

### Gitea Workflow 业务回归

- Webhook HMAC 正确/错误、重复 delivery、Bot 自评论、非 Issue/PR 普通评论过滤。
- 首次合法触发自动接入仓库、clone/fetch 失败恢复、同仓库串行、不同仓库并行及全局并发上限。
- 评论→session 映射稳定（`gitea + owner/repo + type + number`），连续评论 steer/resume 不重复用户消息或仓库修改。
- turn 完成后 MCP 回帖确认：正常一次；缺失时仅一次“只补回执”隐藏 turn；再次失败才 REST 兜底；重启/重复 webhook 不重复评论。
- running 中断、waiting_user 保留、queued 恢复、仓库暂停/全局暂停/取消排队/中止 turn 的状态机和审计日志。
- token 不出现在日志、错误消息、session JSON、git remote URL；Webhook 重放和跨仓库 thread/child 通知不能串任务。

### 现有可复用测试入口

| 入口 | 行号 | 已覆盖内容 |
|---|---:|---|
| `scripts/regression.js` `assertCodexAppRuntimeSubAgentActivityContract` | 2276-2500 | runtime 通知到工具/子代理卡片的归一化。 |
| `scripts/regression.js` `assertCodexAppTransientReconnectContract` | 2501-2542 | reconnect 进度不结束 turn，终态错误结束 turn。 |
| `scripts/regression.js` `assertCodexAppStaleRunningRecoveryContract` | 4038-4058 | stale steer 替换 turn 的持久化/flush 约束。 |
| `scripts/regression.js` `runCodexAppRuntimeImageSteerRegression` | 4233-4365 | 后台/运行中 steer 真实 WebSocket 流程。 |
| `scripts/regression.js` `runCodexAppStaleRunningRegression` | 4367-4558 | app-server 缺失终态通知后的恢复及消息去重。 |
| `scripts/regression.js` `assertCodexAppChildToolRoutingContract` | 4867-5074 | child thread 与父卡片路由隔离。 |
| `scripts/regression.js` `assertCodexAppUnroutedNotificationRoutingContract` | 5076-5113 | thread 索引、负缓存、磁盘 adoption。 |
| `scripts/regression.js` `main --target` | 6032-6173 | 可增加 `gitea-workflow-codexapp` 独立目标，避免每次跑完整回归。 |
| `scripts/regression.js` Codex App 集成段 | 7239-7622 | mock app-server 下的 session、MCP config、collaboration、retry、Goal、runtime warning、工具调用。 |
| `scripts/mock-codex-app-server.js` `ensureThread`/`completeMcpToolTurn`/`startTurn`/`handleRequest` | 91-114、670-737、863-1023、1066-1250 | 可扩展为断言 gitea MCP 配置、thread/start/resume 和 turn/completed。 |
| `package.json` `regression` script | 8 | 统一执行 `node scripts/regression.js`。 |

建议新增 mock 行为：在 `completeMcpToolTurn` 输出 gitea server 的 `type/command/args/env`（token 脱敏），在 `thread/start`/`thread/resume` 记录 config fingerprint；新增回归目标仅断言协议形状和状态机，不调用真实 Gitea。

## 当前验证结果

- `node scripts/regression.js --target codexapp-retry-runtime`：通过。
- `node scripts/regression.js --target codexapp-unrouted-routing`：通过。
- `node scripts/regression.js --target codexapp-stale-running`：通过。
- 本任务没有修改 `server.js`、`lib/` 或 `public/`；仅新增本分析文件（以及临时计划 CSV，完成后删除）。校验时工作区已存在其他并行任务对 `server.js`/`lib` 的改动，本任务未触碰、未回退这些改动。