# Codex 双模型审核与执行工作流

> 更新日期：2026-07-16  
> 适用项目：`frontend-miniapp` 及其他已登记到 Codex App 的本地项目  
> 工作模式：`gpt-5.6-sol / xhigh` 审核，`gpt-5.6-terra / medium` 执行
> 文档版本：1.1（禁止子代理上下文分叉）

---

## 1. 文档目的

本说明用于处理需要先深入审核、再自动启动独立执行线程实施修复的开发任务。

推荐流程：

```mermaid
flowchart LR
    A["整理真实需求"] --> B["手动创建 sol / xhigh 审核线程"]
    B --> C["源码审核与浏览器复现"]
    C --> D["生成实施级修复方案"]
    D --> E["自动创建 terra / medium 执行线程"]
    E --> F["修改、测试与浏览器验收"]
    F --> G["检查执行报告"]
```

这种方式适合以下任务：

- 问题涉及多个页面、状态管理、异步流程或渲染器生命周期。
- 需要先确认问题是否真实存在，不能直接按用户猜测修改。
- 希望高推理模型负责根因分析，由成本和速度更平衡的模型负责实施。
- 希望分析线程与修改线程职责分离，减少分析过程中误改文件的风险。

简单文案调整、单文件确定性修改或无需调查的小任务通常不需要使用该流程。

---

## 2. 当前环境能力

本机当前已验证的 Codex App 能力：

- `codex_app__list_projects`：获取 Codex App 已登记项目及 `projectId`。
- `codex_app__create_thread`：创建带初始提示词的新线程，并立即启动任务。
- `codex_app__read_thread`：读取新线程状态，确认任务是否已接收和执行。
- 创建线程时可以指定项目、运行环境、模型和推理强度。

### 2.1 必须区分的两类机制

| 机制 | 典型工具 | 是否用于本流程 | 原因 |
| --- | --- | --- | --- |
| 协作子代理 | `spawn_agent`、`fork_turns` | 禁止 | 需要分叉当前线程上下文，可能触发 Responses Lite 的上下文枚举兼容错误 |
| 独立 Codex 线程 | `codex_app__create_thread` | 必须 | 使用完整、自包含的初始提示词启动独立项目会话，不依赖子代理上下文分叉 |
| 历史线程分叉 | `codex_app__fork_thread` | 禁止 | 会复制线程历史，本流程不需要继承上下文，且不能替代明确的模型化执行线程 |

本流程中的“执行线程”始终指 `codex_app__create_thread` 创建的独立 Codex App 项目线程，不是 `spawn_agent` 创建的子代理。

已知错误：

```text
X-OpenAI-Internal-Codex-Responses-Lite requires ***.context to be all_turns.
```

该错误发生在子代理上下文分叉请求进入模型执行之前。即使公开参数传入 `fork_turns: "all"`，部分 Codex App/协作工具版本仍可能没有将其正确转换为内部要求的 `all_turns`。这不是项目源码、Git、目标业务模型或测试命令报错。

本流程的处理原则是彻底绕过该路径：

- 当前审核线程独立完成审核，不启动任何子代理。
- 不设置或传递 `fork_turns`。
- 不使用 `codex_app__fork_thread` 复制上下文。
- 审核完成后只调用 `codex_app__create_thread`。
- 将审核证据完整写入新线程的初始提示词，使执行线程不依赖父线程上下文。
- `create_thread` 不可用或失败时如实报告阻塞，不得回退到 `spawn_agent`。

当前验证可用的组合：

| 阶段 | 模型 | 推理强度 | 创建方式 |
| --- | --- | --- | --- |
| 审核 | `gpt-5.6-sol` | `xhigh`（界面显示为“极高”） | 用户手动创建 |
| 执行 | `gpt-5.6-terra` | `medium`（界面显示为“中”） | 审核线程自动创建 |

注意：模型 ID、推理档位和线程工具属于当前 Codex App 运行环境能力，升级 Codex 后应重新确认。在线 Codex 手册在本文编写时因 HTTP `403` 无法获取，因此上述能力以本机实际暴露的工具定义为准。

---

## 3. 提问前准备

每个新需求至少整理以下信息：

1. 项目绝对路径。
2. 用户实际操作步骤。
3. 当前实际结果。
4. 预期正确结果。
5. 已知影响范围。
6. 不允许修改的内容或架构约束。
7. 可以执行的测试和验收方式。

推荐使用以下需求结构：

```text
业务场景：
[用户在什么状态下执行什么操作]

复现步骤：
1. [步骤一]
2. [步骤二]
3. [步骤三]

实际结果：
[当前发生了什么]

预期结果：
[正确行为是什么]

补充约束：
[H5/小程序范围、性能、兼容性、禁止重构区域等]
```

不要只写“功能有问题，请分析并修复”。缺少操作路径和预期结果时，审核模型可能只能根据源码猜测产品意图。

---

## 4. 标准操作步骤

### 4.1 创建审核线程

在 Codex App 中手动新建项目会话：

1. 选择目标项目。
2. 模型选择 `gpt-5.6-sol`。
3. 推理强度选择“极高”，对应 `xhigh`。
4. 粘贴第 5 节的通用提示词。
5. 替换其中的项目路径、需求、预期结果和约束。

### 4.2 审核线程职责

审核线程必须只进行以下工作：

- 检查工作区和项目规则。
- 审核源码调用链和状态变化。
- 对比正常路径与异常路径。
- 通过 H5 浏览器或测试复现。
- 判断问题是否真实存在。
- 输出根因、文件位置、修复步骤、测试矩阵和验收标准。

审核线程不得修改、格式化、暂存、提交或回滚项目文件。

审核线程还必须遵守以下工具路由限制：

- 禁止调用 `spawn_agent` 或任何等价的协作子代理工具。
- 禁止传递 `fork_turns`，无论其值是 `all`、`none` 还是其他值。
- 禁止调用 `codex_app__fork_thread`。
- 禁止为了并行审核创建专家子代理；所有审核由当前主线程完成。

### 4.3 自动创建执行线程

审核完成后，审核线程必须在当前回合结束前实际执行：

1. 调用 `codex_app__list_projects`。
2. 使用项目绝对路径匹配正确的 `projectId`。
3. 调用 `codex_app__create_thread`。
4. 指定 `environment.type` 为 `local`。
5. 指定模型为 `gpt-5.6-terra`。
6. 指定推理强度为 `medium`。
7. 将完整审核证据和修复方案放入新线程的初始提示词。
8. 调用 `codex_app__read_thread` 检查一次启动状态。

本阶段只允许使用 `codex_app__list_projects`、`codex_app__create_thread` 和 `codex_app__read_thread` 完成交接。不得使用 `spawn_agent`、`fork_turns` 或 `fork_thread` 作为替代方案。

核心创建参数应符合：

```json
{
  "target": {
    "type": "project",
    "projectId": "<通过 list_projects 解析出的真实 ID>",
    "environment": {
      "type": "local"
    }
  },
  "model": "gpt-5.6-terra",
  "thinking": "medium",
  "prompt": "<完整审核证据、修复方案、测试矩阵和验收标准>"
}
```

`codex_app__create_thread` 的初始提示词会启动新线程。不能只在回复中展示上述 JSON，也不能要求用户再手动复制修复方案。

### 4.4 执行线程职责

执行线程应：

- 直接按照审核结论实施，避免重新进行宽泛分析。
- 保护用户已有未提交修改。
- 优先修复共享状态、数据或架构边界，不使用页面级临时标志掩盖问题。
- 增加与风险匹配的单元测试、集成测试和浏览器流程测试。
- 执行项目要求的类型检查、lint、测试和构建命令。
- 报告修改文件、验证结果和剩余风险。

### 4.5 验收交接

审核线程最终回复至少应提供：

- 审核结论和根因摘要。
- 修复方案摘要。
- 新执行线程 ID。
- 执行模型和推理强度。
- 新线程启动状态。
- 创建失败时的真实错误。

执行线程最终回复至少应提供：

- 实际修改的文件。
- 实施内容和关键设计决策。
- 测试命令及结果。
- 浏览器验证步骤及结果。
- 未完成项和剩余风险。

---

## 5. 新需求通用提示词

将下面的内容粘贴到手动创建的 `gpt-5.6-sol / xhigh` 线程，并替换方括号内容。

```text
这是一个新的开发任务，请按照“高模型审核 -> 新线程执行”的双阶段流程完成。

最高优先级工具路由约束：

1. 本任务禁止使用任何协作子代理或子 Agent。
2. 禁止调用 spawn_agent、followup_task、send_message 或其他 collaboration 子代理工具。
3. 禁止设置、传递或重试 fork_turns，包括 fork_turns="all"。
4. 禁止调用 codex_app__fork_thread。
5. 当前主线程必须独立完成全部审核，不得为了并行分析创建专家子代理。
6. 审核完成后的执行任务，只能通过 codex_app__create_thread 创建独立 Codex App 项目线程。
7. create_thread 不可用或调用失败时，必须如实报告阻塞；不得回退到 spawn_agent。
8. 新执行线程必须获得完整、自包含的初始提示词，不能依赖父线程上下文继承。

项目目录：
[项目绝对路径]

需求/问题：
[真实业务场景、复现步骤和异常现象]

预期行为：
[正确结果和验收标准]

补充约束：
[不能修改的模块、运行端范围、数据来源、性能要求等]

第一阶段：当前线程只审核

1. 当前线程只进行源码审核、问题复现和修复方案设计，不修改文件。
2. 先检查项目规则、AGENTS.md、相关 SKILL.md、架构文档和未提交修改。
3. 不要直接接受我的根因判断，必须通过源码证据和实际运行验证问题是否存在。
4. 对比正常路径和异常路径，追踪完整调用链、状态变化、异步请求和生命周期。
5. 尽可能通过浏览器或项目测试复现；不能复现时标记为“仅源码风险”。
6. 输出实施级方案，包括根因、文件/函数/行号、修改步骤、测试矩阵和验收标准。

第二阶段：强制创建并启动独立 Codex App 执行线程

用户明确授权你通过 codex_app__create_thread 创建和启动一个新的独立 Codex 项目线程执行修改。该线程不是协作子代理。

完成审核方案后，不得直接结束当前回合，必须：

1. 实际调用 codex_app__list_projects，解析上述项目的 projectId。
2. 实际调用 codex_app__create_thread 创建新线程。
3. 新线程必须使用 environment.type=local。
4. 新线程模型必须使用 gpt-5.6-terra。
5. 新线程推理强度必须使用 medium。
6. 新线程初始提示词必须完整嵌入复现证据、根因、文件位置、修复步骤、测试矩阵和验收标准。
7. 不能只输出线程创建参数或交接提示词，必须实际调用工具。
8. 创建后使用 codex_app__read_thread 检查一次，确认新线程已经收到任务并开始执行。
9. 不得重复创建多个执行线程。
10. 不得调用 spawn_agent、fork_turns 或 codex_app__fork_thread；失败时不得切换到子代理方案。

执行线程必须：

1. 直接实施已经审核完成的方案，不重新开始宽泛分析。
2. 保留用户已有未提交修改，不回滚无关变更。
3. 修复真正的共享逻辑或架构边界，避免临时标志和数据特例。
4. 增加与风险相匹配的测试。
5. 运行项目规定的类型检查、lint、测试和构建命令。
6. 对实际用户操作路径进行浏览器验证。
7. 报告修改文件、测试结果、浏览器证据和剩余风险。

当前审核线程最终回复必须包含：

- 审核结论。
- 根因和修复方案摘要。
- 新执行线程 ID。
- 执行模型和推理强度。
- 新线程启动及首次状态检查结果。
- 创建失败时的真实错误。
```

---

## 6. 本项目追加要求

在 `frontend-miniapp` 中使用该流程时，建议在提示词中继续加入：

```text
开始前完整阅读并遵循：

- .agents/skills/shenzhen-natural-museum-dev/SKILL.md
- 与本任务相关的 references 文档

默认只处理移动端 H5，不处理 mp-weixin，除非需求明确提出。

验证基线至少包括：

- pnpm type-check
- pnpm lint
- 相关单元测试
- pnpm build:h5
- 受影响用户路径的移动端浏览器验证
```

涉及室内模型初始状态、楼层切换、POI 聚焦或详情返回时，还必须阅读：

```text
.agents/skills/shenzhen-natural-museum-dev/references/guide-model-state-baseline.md
```

---

## 7. 常见问题

### 7.1 出现 Responses Lite `context` / `all_turns` 错误

错误示例：

```text
X-OpenAI-Internal-Codex-Responses-Lite requires ***.context to be all_turns.
```

这表示流程错误地调用了 `spawn_agent` 或其他需要分叉上下文的协作工具。它不是项目代码故障，也不表示子代理已经开始执行。

处理步骤：

1. 停止重试 `spawn_agent`，不要继续传递 `fork_turns: "all"`。
2. 由当前主线程直接完成剩余审核。
3. 审核完成后使用 `codex_app__create_thread` 创建独立执行线程。
4. 把审核结果完整写入 `create_thread.prompt`，不要依赖上下文继承。
5. 如果仍然发生该错误，检查实际工具调用记录；正确的流程中不应出现 `spawn_agent` 或 `fork_turns`。
6. 更新或重启 Codex App 后可重新验证子代理能力，但本工作流仍不需要子代理。

错误发生在模型执行前，因此通常不会修改项目文件或 Git 状态。仍应通过 `git status` 确认工作区没有其他线程产生的变化。

### 7.2 Codex 只输出了修复方案，没有创建线程

通常是提示词没有明确授予创建新线程的权限，或者只要求“生成交接提示词”。

必须明确写出：

```text
用户明确授权你实际调用 codex_app__list_projects 和 codex_app__create_thread。
不能只输出参数或建议，必须在当前回合结束前创建并启动线程。
```

### 7.3 新线程没有拿到完整上下文

新线程不会可靠地自动获得父线程尚未完成的全部分析过程。审核线程必须把关键证据直接写入 `create_thread.prompt`，不能只写“按照父线程方案执行”。

### 7.4 创建到了错误项目

不要猜测 `projectId`。必须先调用 `list_projects`，再根据规范化后的项目绝对路径匹配。

### 7.5 执行线程模型或推理强度不正确

创建线程时显式设置：

```text
model: gpt-5.6-terra
thinking: medium
```

如果 Codex App 升级后不再支持该组合，应以工具返回的可用模型和推理档位为准，并向用户说明差异。

### 7.6 执行线程覆盖了用户修改

提示词必须要求两个线程先检查工作区状态。审核线程保持只读；执行线程只能在任务范围内工作，不得回滚、覆盖或格式化无关改动。

### 7.7 为什么使用 local 而不是 worktree

`local` 让执行线程在已登记项目的当前工作目录中工作，可以看到用户现有未提交修改。使用它时必须避免多个修改线程同时编辑同一文件。

只有在明确需要隔离开发、并且已经决定从哪个 Git 状态开始时，才选择 `worktree`。

### 7.8 线程已经创建，是否等于开始执行

带初始 `prompt` 的 `codex_app__create_thread` 会创建并启动线程。仍应使用 `codex_app__read_thread` 检查一次，确认任务已被接收。不要高频轮询没有变化的线程状态。

---

## 8. 执行前检查清单

- [ ] 已提供项目绝对路径。
- [ ] 已写清复现步骤、实际结果和预期结果。
- [ ] 已填写任务范围与禁止修改项。
- [ ] 手动审核线程为 `gpt-5.6-sol / xhigh`。
- [ ] 提示词明确要求当前线程只审核、不修改。
- [ ] 提示词明确禁止 `spawn_agent`、`fork_turns` 和 `codex_app__fork_thread`。
- [ ] 当前审核由主线程独立完成，不创建专家子代理。
- [ ] 提示词明确授权实际创建新线程。
- [ ] 执行线程指定为 `gpt-5.6-terra / medium`。
- [ ] 执行环境指定为 `local`。
- [ ] 要求把完整审核证据嵌入新线程提示词。
- [ ] 要求创建后读取一次线程状态。
- [ ] 已定义测试命令和浏览器验收路径。
- [ ] 已要求保护用户未提交修改。

---

## 9. 版本维护

Codex App 升级后，建议重新确认：

1. `codex_app__list_projects` 是否仍可用。
2. `codex_app__create_thread` 的参数结构。
3. `codex_app__read_thread` 的状态读取方式。
4. `gpt-5.6-sol` 和 `gpt-5.6-terra` 是否仍可选。
5. `xhigh` 和 `medium` 是否仍受对应模型支持。
6. 工具调用记录中是否意外出现 `spawn_agent`、`fork_turns` 或 `fork_thread`。

如果能力发生变化，应先更新本文第 2 节和第 5 节提示词，再继续使用该工作流。