85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# 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 形成循环。
|