CX-11 Codex Web / Cloud 辅助指南：什么时候离开 App

选择仓库和分支
  -> 创建或复用 Cloud environment
  -> 运行 setup script 安装依赖
  -> 移除 setup-only secrets
  -> 进入 agent phase 执行任务
  -> 产出分支、PR、评论或报告
  -> 回到 App / GitHub Review

仓库/分支：owner/repo 的 feature/login-mobile 分支。
目标：修复登录页移动端按钮溢出。
范围：只改 src/pages/login.tsx、src/styles/login.css 和相关测试。
环境：使用 pnpm install --frozen-lockfile；验证 pnpm test -- login 和 pnpm lint。
限制：不要改认证逻辑，不要新增依赖，不要接触 secrets。
交付：打开 PR 或更新现有 PR，PR 描述包含 Summary / Verification / Risk。

npm ci
npm run build

corepack enable
pnpm install --frozen-lockfile
pnpm build

npm install
echo $PRIVATE_TOKEN
read -p "continue?"
open http://localhost:3000

Secrets
  -> setup 阶段用于安装私有依赖或拉取私有资源
  -> agent 阶段前移除
 
Environment variables
  -> setup 和 agent 阶段都可用
  -> 适合非敏感配置或经过风险评估的运行参数

App 中发现问题
  -> 本地确认范围
  -> 创建 GitHub issue / PR
  -> Cloud 接手长时间修复或 CI 修复
  -> 回到 App 拉取分支
  -> App Review 最终检查

基于当前 Cloud 分支 diff，逐文件解释：
1. 为什么这个文件必须改
2. 对应任务交接包里的哪一条
3. 运行了哪些验证
4. 哪些风险还没有覆盖
不要继续修改文件。

仓库/分支：owner/repo 的 feature/login-mobile 分支。
目标：修复登录页移动端按钮溢出。
范围：只改 src/pages/login.tsx、src/styles/login.css 和相关测试。
环境：使用 pnpm install --frozen-lockfile；验证 pnpm test -- login 和 pnpm lint。
限制：不要改认证逻辑，不要新增依赖，不要接触 secrets。
交付：更新现有 PR 或打开新 PR，PR 描述包含 Summary / Verification / Risk。

pnpm install --frozen-lockfile
pnpm build

Issue：
目标：
影响范围：
不改范围：
分支：
验证命令：
是否需要网络：
是否需要 secret：
交付方式：

回到 App：
1. 拉取 Cloud 分支
2. 看 Review 文件列表
3. 看单文件 diff
4. 本地运行关键验证
5. 对照 PR 描述
6. 修正 Verification / Risk
7. 决定继续 App 修、Cloud 修，还是人工处理

选择仓库、分支或 commit
  ↓
创建容器并 checkout 代码
  ↓
运行 setup script
  ↓
应用网络设置
  ↓
agent 循环执行任务、编辑、检查
  ↓
展示最终回答和 diff
  ↓
人决定 PR、回流或继续追问

set -euo pipefail
 
corepack enable
 
if [ -f pnpm-lock.yaml ]; then
  pnpm install --frozen-lockfile
elif [ -f package-lock.json ]; then
  npm ci
fi
 
if [ -f pyproject.toml ]; then
  poetry install --with test
fi
 
echo "Setup complete"

export API_BASE_URL=https://staging.example.com
npm ci
npm test

我的 Codex Cloud setup script 失败了。
请先不要修改业务代码。
请根据 setup 日志判断：
1. 是依赖安装失败、系统工具缺失、网络问题还是脚本语法问题
2. 哪条命令最先失败
3. 是否有 secret 或环境变量缺失的迹象
4. 最小 setup script 修复建议是什么

这个 Cloud 任务的 agent 阶段没有互联网。
请只使用仓库内文件、setup 后已有依赖和任务描述中的上下文。
如果你需要外部资料，请说明缺少什么，不要猜最新 API 行为。

这个 Cloud 任务允许有限网络访问。
只能访问官方文档和项目允许的服务。
不要把 secrets 打印到日志。
如果外部请求失败，请降级为基于仓库代码的分析。

# Cloud Handoff
 
## Goal
 
Fix the failing checkout retry test on this branch.
 
## Branch / Commit
 
Use branch: fix/checkout-retry
 
## Known Failure
 
`pnpm test tests/checkout-retry.spec.ts` fails with timeout after retry state change.
 
## Relevant Files
 
- src/checkout/retry.ts
- tests/checkout-retry.spec.ts
- docs/checkout.md
 
## Constraints
 
- Keep public API unchanged.
- Do not refactor unrelated checkout code.
- Do not update lockfiles.
 
## Suggested Verification
 
- Run the targeted checkout test.
- Run the package lint command if dependencies are installed.

请把当前本地发现的问题整理成 Codex Cloud 交接包。
不要修改文件。
交接包要包括：
- 目标
- 分支或 commit
- 已知失败
- 相关文件
- 不能做的事
- 建议运行的命令

1. 读 Cloud 的最终回答。
2. 看 changed files。
3. 看 diff 是否只覆盖任务范围。
4. 看 Cloud 是否运行了命令。
5. 如果开了 PR，在 App 里看 PR context。
6. 如果 apply 到本地，用 Review 面板看 uncommitted changes。

请复盘这个 Cloud task 的结果。
先不要继续修改。
回答：
1. 它改了哪些文件
2. 它声称解决了什么问题
3. 它运行了哪些命令
4. 哪些风险仍需本地 App Review
5. 我是否应该开 PR、继续追问，还是回本地处理

我已经把 Cloud 任务的改动带回本地。
请在 App Review 视角帮我检查：
1. diff 是否和 Cloud 任务目标一致
2. 是否有本地未提交改动混入
3. 是否需要补充本地验证
4. PR 描述应该提到哪些风险

Fix the failing CI test described below.
 
Scope:
- Make the smallest code change that addresses the failure.
- Do not refactor unrelated modules.
- Do not update dependencies.
 
Failure:
- Test file: tests/payment/retry.spec.ts
- Error: retry state never returns to idle after provider timeout.
 
Expected:
- Add or update one regression test if needed.
- Run the targeted test.
- Summarize changed files and remaining risks.

Node: 根据项目 .nvmrc 或 package engines 固定
Python: 根据 pyproject 或 runtime.txt 固定
Package manager: 根据 lockfile 固定
System tools: 在 setup script 明确安装

set -euo pipefail
 
if [ -f pnpm-lock.yaml ]; then
  pnpm install --frozen-lockfile
fi
 
if [ -f pyproject.toml ]; then
  poetry install --with test
fi

用 secret 安装私有依赖。
不要在 agent prompt 里粘贴 secret。
不要在 setup script 里 echo secret。
不要让测试把 secret 打到失败日志。
agent 阶段如果需要长期配置，用 environment variable，而不是 setup export。

如果 Cloud 任务需要调用 staging API：
1. 使用专门的测试账号和测试数据。
2. 限制网络范围。
3. 在 prompt 里说明哪些请求可以发。
4. 失败时返回诊断，不要重试到制造噪音。

请从安全角度复盘这个 Cloud task。
检查：
1. 是否可能把 secret 打进日志
2. 是否在 agent 阶段依赖了不该有的 secret
3. 是否访问了任务之外的网络资源
4. 是否修改了超出目标的文件
5. 是否需要在 PR 里说明环境限制

请根据这次 Cloud 失败输出，判断重跑是否有意义。
如果失败是配置问题，请给 setup 或环境修复建议。
如果失败是任务描述问题，请给更窄的 prompt。
如果失败是缺少权限，请说明需要哪类权限。

App:
  发现问题、复现问题、写交接包
 
Cloud:
  在远端分支上做可复现修复
 
Review:
  看 diff、处理 PR 评论
 
Automation:
  后续周期检查同类问题是否复发

1. App 中发现 checkout 测试 flaky。
2. App 整理 Cloud handoff。
3. Cloud 修复并开 PR。
4. App Review 面板检查 PR diff。
5. Automation 每天检查相关测试是否再次失败。

请把当前 CI 失败整理成 Codex Cloud handoff。
不要修改文件。
包括：
- 目标
- 分支或 commit
- 失败测试
- 相关文件
- 不允许做的事
- 建议验证命令

Fix the CI failure in `tests/payment/retry.spec.ts`.
 
Scope:
- Make the smallest change needed to fix the failing retry behavior.
- Do not refactor unrelated payment code.
- Do not update dependencies or lockfiles.
 
Known failure:
- Retry state does not return to idle after provider timeout.
 
Expected:
- Add or update one regression test if needed.
- Run the targeted test.
- Summarize changed files, commands run, and remaining risks.

我已经拿到 Cloud task 的 diff。
请从 App Review 视角检查：
1. 是否只解决 CI 失败
2. 是否有无关重构
3. 是否需要本地补充验证
4. PR 描述应该怎样写

npm install
npm test
export API_BASE_URL=https://staging.example.com

- `npm install` 可能不尊重 lockfile。
- 全量 test 放 setup 阶段会拖慢每次任务。
- `export` 不会让 agent 阶段持久获得变量。

set -euo pipefail
 
if [ -f package-lock.json ]; then
  npm ci
elif [ -f pnpm-lock.yaml ]; then
  corepack enable
  pnpm install --frozen-lockfile
fi
 
echo "Dependencies installed"

请审查这个 Codex Cloud setup script。
重点看：
1. 是否尊重 lockfile
2. 是否把测试放错阶段
3. 是否错误依赖 export
4. 是否可能打印 secret
5. 是否能更快、更稳定

让 Cloud 修复我本机浏览器登录后的 UI bug。

让 Cloud 修复一个 CI 中可复现的单元测试失败。

让 Cloud 自动重构整个支付系统。

我在本地分支 `fix/auth-redirect` 上看到 `auth redirect` 测试失败。
失败命令：
`npm test -- auth-redirect`
 
已知现象：
- 登录后没有回到原目标页面。
- 失败集中在 redirect 参数保留逻辑。

请在 Cloud 环境中只处理这个测试失败。
 
允许：
- 读取相关 auth 路由、redirect helper、测试文件。
- 修改最小必要代码和对应测试。
- 运行相关测试。
 
不要：
- 重构整个 auth 模块。
- 修改登录 UI 文案。
- 新增外部依赖。
- 处理无关失败。

完成后请返回：
1. 改动摘要。
2. 修改文件列表。
3. 失败原因判断。
4. 运行过的命令和结果。
5. 没有覆盖的风险。

请只读审查 Cloud 返回的 diff。
 
重点判断：
1. 是否只解决 auth redirect 测试。
2. 是否引入新依赖或扩大范围。
3. 验证命令是否足够。
4. 哪些行为需要我本地再跑一遍。

Fix the tests.

- 哪个测试。
- 哪个分支。
- 已知失败。
- 相关文件。
- 禁止事项。
- 验证命令。

Fix the failing auth redirect test on branch `fix/auth-redirect`.
 
Known failure:
 
- `pnpm test tests/auth/redirect.spec.ts`
- Expected fallback redirect, got blank path.
 
Scope:
 
- Keep public route names unchanged.
- Do not update dependencies.
- Do not refactor unrelated auth helpers.
 
Verification:
 
- Run the targeted test.
- Summarize changed files and remaining risk.

Cloud run failed.
Could not install dependencies.
pnpm not found.
No tests were run.

The previous Cloud task failed before running tests because `pnpm` was not available.
 
Please focus only on environment setup diagnosis.
 
Return:
1. What setup command is missing.
2. Whether package manager is declared in the repo.
3. Suggested setup script change.
4. Do not modify application code.

Cloud ran the targeted test but it still failed.
Failure narrowed to:
- expected redirect path: /dashboard
- actual redirect path: /
Changed files:
- src/auth/redirect.ts
- tests/auth-redirect.test.ts

Continue from the previous Cloud result.
 
The environment works and the targeted test runs.
Focus only on the remaining redirect path mismatch:
- expected /dashboard
- actual /
 
Do not change setup script.
Do not refactor auth module.
Inspect only redirect helper and test expectation first.
If you need another file, explain why.

Previous Cloud result changed too many unrelated files.
 
Please do not continue implementation.
Instead, produce a rollback plan:
1. Which files are directly related to auth redirect.
2. Which files are unrelated.
3. Which changes should be discarded or split out.
4. What local Review steps I should take.

npm install
npm test

- 不知道项目实际包管理器。
- setup 阶段不应该默认跑完整测试。
- 失败时很难知道卡在哪一步。
- 依赖版本和缓存策略不清楚。

corepack enable
pnpm install --frozen-lockfile

corepack enable
pnpm install --frozen-lockfile
pnpm run generate

After setup, run:
pnpm test tests/auth/redirect.spec.ts

# Cloud Environment Note
 
## Runtime
 
Node:
Package manager:
 
## Setup Script
 
Commands:
 
## Environment Variables
 
Used during setup:
Not available during agent phase:
 
## Common Failures
 
- package manager missing
- lockfile mismatch
- generated files missing
- test browser dependency missing
 
## Last Updated
 
...

请只读审查 Cloud 返回的 changed files。
判断：
1. 哪些文件和目标直接相关。
2. 哪些文件可能是顺手改动。
3. 是否新增依赖或改配置。
4. 是否需要拆 PR。

请阅读 Cloud 返回的命令记录。
判断：
1. 是否运行了目标测试。
2. 是否只运行了 setup 而没有验证行为。
3. 是否有失败命令被忽略。
4. 我本地应该补跑什么。

请基于 Cloud diff 起草 PR 描述。
 
要求：
1. Summary 只写真实改动。
2. Verification 只写 Cloud 或本地实际运行过的命令。
3. Risk 说明需要本地人工确认的路径。
4. 不要写“all tests passed”，除非有证据。

Please clean up the whole auth module and fix tests.

- 范围过大。
- 不知道哪些测试失败。
- 容易重构。
- 很难 Review。
- 成功或失败都不好判断下一步。

Cloud Task 1：只读诊断
- 找 auth 模块当前失败测试和高风险区域。
- 不修改文件。
- 输出建议拆分。
 
Cloud Task 2：最小修复
- 只修 auth redirect regression。
- 只改 helper 和测试。
- 返回 diff 和命令。
 
Cloud Task 3：文档同步
- 根据已合并行为更新 auth docs。
- 不改业务代码。

Analyze the auth module without modifying files.
 
Return:
1. Failing or fragile tests.
2. Areas with highest regression risk.
3. A recommended first small fix.
4. Files that should not be touched in the first fix.

Fix only the auth redirect regression identified in the previous analysis.
 
Scope:
- redirect helper
- matching regression test
 
Do not:
- refactor auth module
- update dependencies
- change UI copy
 
Return changed files, commands run, and remaining risk.

Update auth documentation to match the merged redirect behavior.
 
Scope:
- docs/auth.md
- README auth section if present
 
Do not:
- change source code
- invent behavior not visible in code or tests

- 三个独立文档更新。
- 多个只读调查。
- 不同平台的失败复现。
- 两个互不重叠的小 bug。

- 同一个核心模块的多个实现方案同时写。
- 多个任务都可能改同一组测试。
- 你没有时间 Review 多个结果。
- 每个任务都需要不断人工选择方向。

请判断这个任务是否适合拆成多个 Cloud task。
 
输出：
1. 可以并行的子任务。
2. 不能并行的原因。
3. 每个子任务的文件范围。
4. 回收顺序。
5. 最先应该跑的只读任务。

请把并行任务限制到最多 2 个。
优先选择文件范围不重叠、Review 成本最低的任务。