完善讲解配置与H5构建校验

docs/CODEX_DUAL_MODEL_WORKFLOW.md

@@ -0,0 +1,425 @@
+# 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 节提示词，再继续使用该工作流。