#实战案例

本章给出由浅入深的端到端场景，展示桌面应用、AGENTS.md、沙箱、Skills 与 MCP 如何组合。

#案例 0：桌面应用的可视化工作流

背景： 你刚装好桌面应用，想用「规划 → 执行 → 审查」的方式给现有页面加一个深色模式。

#步骤

1. 添加项目：侧边栏 Add project 选中仓库目录

2. 只读规划：把权限设为 Read-only，发：

   分析当前的主题/样式实现，给出加深色模式的方案与要改的文件清单，先不要改代码。

3. 切换执行：方案 OK 后改为 Default / Auto，发：

   按上面的方案实现深色模式切换，沿用现有 CSS 变量约定。完成后在应用内浏览器打开预览。

4. 可视化验证：用应用内浏览器打开本地预览，在渲染元素上直接评论问题让它修

5. 审查与提交：右侧 Diff 面板逐行确认 → 顶部 Commit；不满意点 Undo

要点： 桌面应用让「分阶段 + 可视化审查 + 即时预览」一气呵成，是相比纯 CLI 的核心增量。

#案例 1：遗留模块重构

背景： legacy/billing.js 单文件 2000 行，无测试。

#步骤

1. 分支与 AGENTS.md

git checkout -b refactor/billing-module

在 legacy/AGENTS.md：

# legacy/AGENTS.md
- 重构时保持对外 export 名称不变
- 每拆出一个模块必须补对应单元测试
- 测试命令：`npm test -- legacy/billing`

2. 只读探索（可选 Subagent 或首轮只读）

codex --sandbox read-only --ask-for-approval on-request

分析 legacy/billing.js 的职责边界， propose 拆分为 payment、invoice、tax 三个模块的文件树，不要改文件。

3. 实施重构

codex --sandbox workspace-write --ask-for-approval on-request

按上一步方案拆分 legacy/billing.js，补测试，运行 npm test -- legacy/billing 直到通过。

4. 审查

git diff --stat
npm test
# 或使用 Codex 本地 code review 能力

要点： 探索与实施 分阶段 + 目录级 AGENTS.md 约束行为。

#案例 2：自动化 Code Review Skill

目标： 每次 PR 前用固定清单审查 staged diff。

#创建 Skill .agents/skills/pre-commit-review/SKILL.md

---
name: pre-commit-review
description: 审查 git staged diff。用户提到 review、提交前检查、PR 自检时使用。
---

1. 运行 `git diff --cached` 获取变更。
2. 检查：是否有 debug 语句、密钥、过大文件、缺少测试。
3. 按严重程度输出：BLOCKER / WARN / INFO。
4. 不要修改文件，仅输出报告。

#使用

git add -p
codex

$pre-commit-review

扩展： 结合 GitHub MCP，在 Skill 中增加「对比 base 分支 diff」步骤。

#案例 3：Issue → 分支 → PR（Cloud + 本地混合）

背景： 团队在 GitHub 用 Issue 跟踪，希望 Codex Cloud 异步实现，本地只做验收。

#Cloud 侧

1. 在 chatgpt.com/codex 连接 GitHub 仓库
2. 选择环境（Node 版本、测试命令与 AGENTS.md 一致）
3. 发起任务：「Fix #42: 登录超时未刷新 token」

#本地侧

git fetch
git checkout codex/issue-42-fix
npm test
codex --sandbox read-only "对照 Issue #42 验收标准做 checklist"

#PR 评论

在 PR 中 @codex add regression test for token refresh 追加迭代。

要点： AGENTS.md 在 Cloud 与 CLI 同源，避免环境漂移。

#案例 4：CI 中生成 Release Notes

# .github/workflows/release-notes.yml（示意）
- name: Codex release notes
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    codex exec \
      --sandbox read-only \
      --ask-for-approval never \
      --output-last-message \
      "根据 git log $(git describe --tags --abbrev=0)..HEAD 生成用户向 changelog，Markdown 格式" \
      > RELEASE_NOTES.md

要点： CI 用 read-only + 无审批，且 checkout 应限制写权限。

#反模式（避免）

#下一步

• 工作流与 Worktrees：把多案例并行起来
• Agent Skills：把案例 2 打包成 Plugin
• 资源与延伸阅读：官方文档与社区