Codex App / Gitea Workflow 挂接说明

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

线程级 gitea-mcp

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

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

codexAppThreadConfig() 会将其合并为：

{
  "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 注释：

<!-- 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 形成循环。

3.5 KiB Raw Permalink Blame History Unescape Escape

Codex App / Gitea Workflow 挂接说明

线程级 gitea-mcp

turn 生命周期

回执与 waiting_user

3.5 KiB

Raw Permalink Blame History