426 lines
16 KiB
Markdown
426 lines
16 KiB
Markdown
# 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 节提示词，再继续使用该工作流。
|