Codex /goal 长任务 | 防跑偏省成本

你敢不敢让它跑很久？

不要把 /goal 当成“夜间代写代码”。
要把它当成一个长任务飞行控制系统。

方向明确，步骤很多，人工做很烦，机器做很合适。

持久目标 + 可验证停止条件。

/goal 帮我优化这个项目。
/goal 把代码质量提高一下。
/goal 做一个更好的管理后台。
/goal 把这个工具打磨到能用。

/goal 按 docs/goal.md 完成模型 provider 重构。
停止条件：
1. 所有 LLM 调用统一经过 packages/llm/provider.ts
2. 现有测试通过
3. 新增 provider fallback 测试通过
4. README 和 .env.example 已更新
5. status.md 记录最终变更和未解决问题

docs/goal-run/
  goal.md
  scope.md
  plan.md
  todo.md
  verify.md
  budget.md
  stop.md
  status.md
  decision-log.md

# Goal

## Objective

完成 [具体任务]。

## Done Means

- [ ] 条件一
- [ ] 条件二
- [ ] 条件三
- [ ] 文档已更新
- [ ] 测试已通过
- [ ] status.md 已写最终总结

## Not In Scope

- 不做 A
- 不做 B
- 不引入新依赖，除非先说明原因
- 不改动无关模块

## First Files To Read

- AGENTS.md
- docs/goal-run/scope.md
- docs/goal-run/todo.md
- docs/goal-run/verify.md

## Stop When

- 所有 Done Means 勾选完成
- 或 stop.md 中任一停机条件触发
- 或连续 3 次验证失败且原因相同

- 重构 provider
- 支持 4SAPI
- 补测试
- 更新文档

# Todo

## 1. 统一 LLM Provider 配置

### Task

把模型 base_url、api_key、model 从环境变量读取，统一放到 `packages/llm/config.ts`。

### Acceptance

- [ ] `.env.example` 包含 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`
- [ ] 代码中没有硬编码 API key
- [ ] 单元测试覆盖缺少环境变量时的错误提示

### Verify

```bash
pnpm test packages/llm/config.test.ts

pnpm test packages/llm/provider.test.ts

这类 todo 有两个好处。

第一，Codex 不会只凭感觉说“做完了”。

第二，你早上验收时，不用从一堆 diff 里猜它做了什么。

直接看勾选和验证命令。

## 5. `verify.md`：把验收变成闸门

`/goal` 最应该依赖的不是自信，而是验证。

OpenAI 官方提示里也强调，Codex 在能验证工作时输出质量更高。要提供复现步骤、验证命令、lint、pre-commit 检查。

所以你需要一个 `verify.md`。

模板：

```md
# Verification Gates

## Gate 1: Static Checks

```bash
pnpm lint
pnpm typecheck

pnpm test

pnpm build

pnpm dev

如果任务是大模型 API 中转站接入，建议再加一个中转站专用闸门：

```md
## Gate 6: LLM Gateway Check

- [ ] `LLM_BASE_URL` 支持 OpenAI-compatible `/v1`
- [ ] `LLM_MODEL` 可配置
- [ ] 401 有清晰提示
- [ ] 429 有清晰提示
- [ ] 5xx 有重试或降级策略
- [ ] 日志只记录 request_id、model、latency、status
- [ ] 不记录 API key、完整 prompt、用户隐私

不是让 Codex 长跑，而是让 Codex 过闸。

token 会烧钱。

# Budget

## Time Budget

- Soft limit: 2 hours
- Hard stop: 4 hours

## Token Budget

- Soft limit: 1,000,000 tokens
- Hard stop: 2,000,000 tokens

## File Change Budget

- Expected changed files: <= 12
- Hard stop changed files: > 25

## Scope Budget

Allowed directories:

- packages/llm/
- apps/web/src/chat/
- docs/

Disallowed directories:

- billing/
- auth/
- database/migrations/

## Cost Rules

- Do not repeatedly read large generated files
- Do not inspect `node_modules`
- Prefer targeted `rg` searches over whole-repo dumps
- Run full test suite only after focused tests pass
- If blocked by same error 3 times, stop and write status.md

什么情况下必须停。

# Stop Conditions

Stop and report if any condition occurs:

## Safety

- Need to delete or rewrite more than 3 existing user-authored files
- Need to modify `.env`, secrets, credentials, billing, auth, or production config
- Need network access not already approved
- Need to upload files or logs to external services

## Scope

- Required changes touch directories outside allowed scope
- Task requires product decision not defined in goal.md
- Implementation conflicts with AGENTS.md

## Validation

- Same test fails 3 times with same root cause
- Build failure seems unrelated to current task
- Cannot run required verification commands

## Cost

- Changed files exceed budget
- Runtime exceeds hard time limit
- Need to inspect very large files repeatedly

## Output

When stopping, write:

- what was completed
- what remains
- exact blocker
- suggested next human decision
- current git diff summary

# Status

## Current Phase

Phase 2: Provider implementation

## Completed

- [x] Read AGENTS.md
- [x] Added env config loader
- [x] Updated .env.example

## In Progress

- [ ] Add gateway provider tests

## Failed Checks

- `pnpm test packages/llm/provider.test.ts`
  - reason: mock response schema mismatch
  - next action: update fixture

## Next Step

Fix provider fixture and rerun focused test.

# Decision Log

## 2026-xx-xx 22:40

Decision: Keep existing OpenAI SDK wrapper instead of replacing with raw fetch.

Reason:

- Less code churn
- Existing streaming path depends on SDK
- Easier rollback

Risk:

- Need to verify custom base_url works with current SDK version

Verification:

- Add provider test for custom base_url

我准备把下面这个任务交给 /goal 长跑。
请你先不要改代码，只做目标审查。

请检查：
1. 目标是否只有一个
2. 停止条件是否可验证
3. todo 是否每条都有验收标准
4. verify.md 是否能跑
5. stop.md 是否覆盖高风险场景
6. budget.md 是否合理
7. 哪些信息还缺失

请反问我所有必须澄清的问题。

/goal 按 docs/goal-run/goal.md 完成长任务。
每个阶段开始前先读取 docs/goal-run/ 下的相关文件。
每完成一个 todo，更新 status.md。
每做关键技术选择，更新 decision-log.md。
每通过一个验证闸门，记录命令和结果。
触发 stop.md 任一条件时立即停止并汇报。
持续推进，直到 Done Means 全部完成或触发停机条件。

你有一个聊天应用，原来直连 OpenAI。
现在想接入 4SAPI 这类大模型 API 中转站，支持 Claude、GPT、Gemini 的统一路由。

/goal 帮我接入 4SAPI。

# Goal

## Objective

将当前项目的大模型调用改造成 OpenAI-compatible gateway provider，使其可以通过 4SAPI 这类大模型 API 中转站调用 Claude、GPT、Gemini。

## Done Means

- [ ] 现有聊天功能可用
- [ ] 新增 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`
- [ ] 旧 provider 可回滚
- [ ] provider 测试覆盖成功、401、429、5xx
- [ ] 日志不记录 API key 和完整 prompt
- [ ] README 和 `.env.example` 更新
- [ ] `pnpm lint`、`pnpm test`、`pnpm build` 通过

## Not In Scope

- 不改登录系统
- 不改计费系统
- 不改数据库 schema
- 不重写 UI
- 不引入新生产依赖，除非先写入 decision-log.md

## 1. Locate LLM calls

Acceptance:

- [ ] 列出所有模型调用文件
- [ ] 标注当前 SDK / HTTP 客户端
- [ ] 标注是否支持自定义 base_url

Verify:

```bash
rg -n "openai|anthropic|chat/completions|responses|LLM|model" .

pnpm test packages/llm/config.test.ts

pnpm test packages/llm/provider.test.ts

这类任务非常适合 `/goal`。

原因是：

- 范围清楚
- 文件可定位
- 测试可运行
- 文档可更新
- 回滚可设计
- 成本和风险可控

它不是探索性产品需求。

它是工程体力活。

## 11. 用中转站做 LLM-as-a-judge，不要让同一个模型自嗨

长任务还有一个新玩法：

```text
让 Codex 写代码，让另一个模型做验收评审。

Codex 执行实现
测试脚本做硬验证
另一个模型做软评审
人做最终决策

# Review Prompt

请审查当前 diff 是否满足 goal.md。

重点检查：

1. 是否超出 scope.md
2. 是否违反 stop.md
3. 是否遗漏 verify.md 中的验证项
4. 是否存在 API key 泄露风险
5. 是否记录了完整 prompt 或用户隐私
6. 是否有无关依赖变化
7. 是否有可回滚方案

输出：

- 阻塞问题
- 非阻塞建议
- 需要人工确认的问题

不只是帮 Codex 找模型。
而是帮长任务建立多模型质检层。

如果一个任务需要连续推进到完成，用 /goal。
如果一个方法需要反复复用，做 Skill。
如果一个动作需要定期发生，做 Automation。

git status
git switch -c codex/goal-llm-gateway
git add .
git commit -m "checkpoint before goal run"

git status
git diff --stat
git diff
git log --oneline -5

/goal 按 docs/goal-run/goal.md 完成本次长任务。

运行规则：

1. 开始前读取：
   - AGENTS.md
   - docs/goal-run/goal.md
   - docs/goal-run/scope.md
   - docs/goal-run/todo.md
   - docs/goal-run/verify.md
   - docs/goal-run/budget.md
   - docs/goal-run/stop.md

2. 按 checkpoint 工作：
   - 每次只完成一个 todo
   - 每完成一个 todo，运行对应 Verify
   - 通过后更新 status.md
   - 关键技术选择写入 decision-log.md

3. 验证规则：
   - 优先运行 focused test
   - focused test 通过后再跑全量测试
   - 不能运行的验证项要写明原因

4. 成本规则：
   - 不读取 node_modules、dist、build、coverage
   - 不重复读取大文件
   - 使用 rg 精确搜索
   - 超出 budget.md 任何硬限制时停止

5. 安全规则：
   - 不修改 secrets、billing、auth、production config
   - 不删除文件
   - 不上传日志或源码到外部服务
   - 不记录 API key 和完整用户隐私

6. 停止规则：
   - Done Means 全部完成则停止
   - stop.md 任一条件触发则停止
   - 同一错误连续失败 3 次则停止

最终输出：

- 完成项
- 未完成项
- 验证结果
- 风险
- 回滚方式
- 建议下一步

1. status.md 是否完整
2. decision-log.md 是否记录关键选择
3. todo.md 是否每项都有验证结果
4. git diff 是否只改了允许范围
5. 是否新增或修改了敏感文件
6. 是否有 API key、token、secret
7. lint/test/build 是否真的跑过
8. 前端页面是否真的打开验证过
9. README 和 .env.example 是否同步
10. 是否有回滚方案

pnpm lint
pnpm test
pnpm build

能写出验收标准，就可以考虑 /goal。
写不出验收标准，就先别长跑。

我说一步，AI 做一步。

我定义目标、边界、验证和停机线。
AI 按控制台执行。

让 Codex 跑一整夜以后，第二天你还能看懂、验收、回滚、复盘。

/goal 负责持续推进，外置记忆负责不跑丢，验证闸门负责不自嗨，中转站负责把模型调用变得可统计、可路由、可治理。