# Gitea Codex 工作流会话与回执实施计划

## 目标

新增独立的 Codex App/Gitea 工作流适配模块，覆盖线程级官方 gitea-mcp 注入、turnId 关联、waiting_user 连续评论、回执确认、一次补触发和 REST 兜底；以最小挂接点接入 server.js，并用协议 mock 与单测验收。

## 步骤

- [x] 定位现有 Codex App 线程、turn、MCP 配置和通知路由挂接点
- [x] 冻结独立模块 API 与隐藏 turnId/Bot 自评论标记协议
- [x] 实现线程级 gitea-mcp 配置、waiting_user 评论串联和回执状态机
- [x] 增加 server.js 最小挂接示例与可复制的接入说明
- [x] 编写协议 mock 和模块单元测试，覆盖补触发/REST 兜底
- [x] 运行语法检查、单测和现有回归并记录结果

## 完成记录

- 线程级 `mcp_servers.gitea`、隐藏标识、Bot 过滤、waiting_user 连续评论、一次补发和
  REST 兜底已接入 `server.js`。
- 回帖校验允许历史补发标识集合；查询 `unknown` 时保守失败，不自动重复写操作。
- `node scripts/gitea-workflow-codex-unit.js`、Gitea 专项回归和全量 `npm run regression`
  均通过。

## 验收约束

- 隐藏标识采用版本化 HTML 注释，编码后的 payload 必须包含 `taskId`、`turnId` 和 `resourceKey`，解析失败时不得误判为本轮回执。
- Bot 自评论优先按稳定 user id 判定；未配置 id 时才回退到大小写无关 login；带有效 ccweb 隐藏标识的评论始终不触发新任务。
- 回执确认严格区分 `confirmed`、`missing` 和 `unknown`；查询异常为 `unknown`，禁止据此重复执行代码修改。
- 正常回执未确认时最多创建一个 `reply_retry`，且必须复用原 `threadId`；补触发提示词只允许补发回执，不允许修改代码。
- 补触发后仍非 `confirmed` 才允许 REST 兜底；REST 成功或最终失败后不得再次补触发。
- gitea-mcp 只能出现在 `thread/start.config.mcp_servers.gitea`，host/token 经该线程的 args/env 注入，禁止写入 app-server 进程全局环境。
- `server.js` 仅增加 require、配置合并、turn started/completed/user-input 信号等薄挂接；工作流逻辑必须留在独立模块。
- 单测必须断言线程配置形状、标记往返/Bot 过滤、waiting_user 同线程投递、查询异常、单次补触发和 REST 兜底次数。

## 错误记录

| 错误 | 尝试 | 处理 |
|---|---:|---|
| planning-with-files catchup 脚本路径不存在 | 1 | 记录后改为直接读取现有规划文件并继续 |