# Codex App / Gitea Workflow 挂接说明

本文件对应 `lib/gitea-workflow-codex.js` 的独立协议适配器，以及 `server.js`
中保持薄层的三个挂接点。

## 线程级 gitea-mcp

Webhook runner 为每个任务创建工作区和 token 后，将如下对象随本轮消息传入：

```js
{
  giteaWorkflow: {
    taskId: task.taskId,
    kind: 'normal',
    mcp: { host: 'https://gitea.example', accessToken: token },
  },
}
```

`codexAppThreadConfig()` 会将其合并为：

```json
{
  "mcp_servers.gitea": {
    "type": "stdio",
    "command": "gitea-mcp",
    "args": ["-t", "stdio", "-H", "https://gitea.example"],
    "env": {
      "GITEA_HOST": "https://gitea.example",
      "GITEA_ACCESS_TOKEN": "<线程级凭据>"
    }
  }
}
```

token 不写入 app-server 进程环境，也不通过 dynamicTools 注入。使用
`collaborationMode` 时，模型与推理参数仍只放在 `settings`。

`gitea-mcp` 二进制随 cc-web 交付，源码部署默认查找
`<cc-web>/bin/gitea-mcp`，single-exe 部署默认查找
`<发布目录>/bin/gitea-mcp`。只有需要替换官方版本时才配置
`CC_WEB_GITEA_MCP_COMMAND` 指向本机绝对路径；不要求每个服务各自安装一份。
命令不可执行时，任务在启动 Codex App 前以 `gitea_mcp_not_found` 快速失败，不会
让对话长期停留在 `running`。

在启动 Codex App 前，cc-web 还会用同一份线程级 command/args/env 做一次最小
stdio `initialize` 预检。预检只验证进程能启动并返回 JSON-RPC initialize 响应，
不调用 Gitea 工具；进程启动失败、返回 MCP error 或在
`CC_WEB_GITEA_MCP_STARTUP_TIMEOUT_MS`（默认 8 秒）内无响应时，分别记录
`gitea_mcp_start_failed`、`gitea_mcp_handshake_failed` 或
`gitea_mcp_handshake_timeout`，任务进入 `failed`，并由统一队列监听发送一条
`giteabot: 任务失败：...` 回执。cc-web 不会自动下载或安装 gitea-mcp。

## turn 生命周期

- `startCodexAppTurn()` 在 `turn/start` 返回后调用适配器的
  `handleTurnStarted({ taskId, threadId, turnId, kind })`。
- `handleCodexAppTurnComplete()` 保留原有消息落盘和生命周期广播，并让既有
  Gitea waiter 调用 `settleGiteaWorkflowTurn()` 做回执查询、一次隐藏补触发和
  REST 兜底。
- 运行时通知可用 `extractTurnId()` / `extractThreadId()` 兼容
  `params.turnId`、`params.turn.id`、`params.item.turnId` 等形状。

## 回执与 waiting_user

`buildWorkflowMarker()` 生成版本化 HTML 注释：

```html
<!-- ccweb-gitea v="1" taskId="..." turnId="..." resourceKey="..." kind="final" -->
```

只有同时匹配资源、taskId、turnId（含补发轮次允许的历史标识集合）和 Bot 身份的评论才算
`confirmed`。查询异常为 `unknown`，不得据此再次执行修改、补发或 REST 覆盖；只有确认
评论缺失才允许同一 thread 发起一次 `reply_retry`，其提示词只允许补发上一轮最终文本，
仍未确认才进入 REST 兜底。

Agent 需要澄清或报告阻塞时使用同一标识结构但将 `kind` 设为 `waiting_user`。cc-web
确认该标识后直接把任务置为 `waiting_user`，不触发回帖补发；用户再次 `@ccweb-bot`
时创建新 turn，并复用原 Issue/PR 的 session/thread。

`queueWaitingUserComment()` 为用户的后续评论创建新 task/turn，但复用父任务的
`sessionKey` 与 `threadId`；Bot 自评论按稳定 user id 优先、login 兜底过滤。
带有完整 `ccweb-gitea` 隐藏标记的评论即使作者身份字段缺失，也按自身回执忽略，
避免回执 Webhook 形成循环。