Coding agent 需要先知道什么叫完成。
如果每个混乱的开发需求，都能在 Codex 动手前先变成一个有边界、可验收的目标合同呢？
SuperGoal 是一套给 Codex goal mode 用的工作流工具：一个 macOS 菜单栏 App，加两个本地 Codex Skill。
AI coding agent 失败，不只是因为代码写得差。很多时候，是因为没人先定义什么叫做完成。
它不是把 prompt 写长。它会把粗糙、情绪化、例子很多、边界不清的需求，整理成验收优先的 goal contract：目标、范围、非目标、停止条件、subagent 子目标、SuperDev 架构门禁和最终验证方式。
最后得到的不是一段更漂亮的 prompt，而是一个更知道怎么工作的 coding agent：
- 知道必须证明什么结果；
- 知道哪些东西不在范围内；
- 知道什么时候应该派 subagent；
- 知道什么时候应该停止；
- 知道说“完成”之前需要留下什么证据。
Goal mode 很强，但长任务经常失败在一开始：agent 把用户随口说的一段需求当成执行计划，直接开始改文件。SuperGoal 让主 Codex agent 先成为 dispatcher 和 acceptor，再成为 implementer。
| 失败模式 | SuperGoal 的做法 |
|---|---|
| 需求很散、很情绪化、例子很多 | 先转成可观察的验收标准和停止条件 |
| agent 没定范围就开始实现 | 生产代码前必须先有 parent Goal Contract |
| 长任务变成一个巨大单线程 | 把独立工作拆成 bounded child Goal Contracts 派给 subagent |
| subagent 只返回结论，没有生命周期证据 | 要求 child goal 创建、完成或阻塞证据 |
| “完成”只是改了文件 | 由 parent agent 亲自做最终验证 |
| 实现过程中架构漂移 | 配合 SuperDev 的 SPEC.md / PLAN.md 架构门禁 |
粗需求
-> 验收标准 / 停止条件
-> parent Goal Contract
-> subagent 机会扫描
-> bounded child Goal Contracts
-> SuperDev 架构门禁
-> 实现 / 集成
-> 最终验证
-> complete 或 blocked
SuperGoal 围绕三件事设计：
- 验收优先：先定义停止时必须为真的结果，而不是先猜实现步骤。
- 父 agent 负责制：主 Codex agent 负责范围、派工、合并决策、最终验证和是否完成。
- 有边界的子目标：subagent 收到的是明确 child contract，包括允许范围、禁止事项、停止指标、输出格式和生命周期要求。
plugin/supergoal.app-src：macOS 菜单栏 App，可以把 Codex 输入框中选中的粗需求直接替换成结构化 goal prompt。skills/supergoal：把自然语言需求整理成有边界的 parent / child goal contracts。skills/superdev：让长期仓库开发遵守 SPEC / PLAN 架构门禁。
SuperGoal 是目标编译器和编排器，SuperDev 是架构门禁。它们适合一起使用：
Use $supergoal and $superdev.
App 会出现在 macOS 右上角菜单栏，是一个很小的黑白键盘图标。
在 Codex 里使用：
- 在输入框写一段粗需求。
- 选中这段文字。
- 按 SuperGoal 快捷键。
- 等待小键盘动效。
- 选中文字会被替换成更清晰的 goal-mode prompt。
- 直接发送给 Codex。
功能：
- 直接替换 Codex 输入框里选中的文字。
- 默认快捷键：
Control + Option + Command + G。 - 支持自定义快捷键。
- 支持配置 API key、Base URL 和 model。
- 支持自定义 prompt 优化提示词，适配不同开发习惯。
- 支持 OpenAI-compatible 网关。
- 未填写自定义 prompt 时，默认使用内置
$supergoal和$superdev逻辑。
从最新 GitHub Release 下载 macOS 包：
下载 .dmg 文件，例如：
SuperGoal-v0.1.2.dmg
打开磁盘镜像，把 supergoal.app 拖到 Applications，然后启动。
注意：当前 App 是 ad-hoc 签名，还没有做 Apple notarization。第一次打开时，macOS 可能要求你在“隐私与安全性”里手动确认。
- 打开
supergoal.app。 - 点击右上角菜单栏里的键盘图标。
- 打开
Settings...。 - 配置：
- API key
- Base URL
- model
- 快捷键
- 如需个性化，打开
Custom Compiler Prompt...，写入你自己的 prompt 优化提示词。
Base URL 示例：
https://api.openai.com
https://api.openai.com/v1
https://api.openai.com/v1/responses
https://your-gateway.example.com/v1
https://your-gateway.example.com/v1/chat/completions
https://your-gateway.example.com/v1/responses
如果 Base URL 是根地址或 /v1，SuperGoal 会优先尝试 OpenAI-compatible chat completions，再回退到 responses。
内置 prompt 是给 Codex goal mode 设计的，默认会使用：
$supergoal
$superdev
如果 Custom Compiler Prompt... 留空，就使用内置逻辑。
如果你填写了自定义 prompt，SuperGoal 会优先使用你的配置。这个适合有自己开发习惯的人，比如更偏好某种验收标准、测试方式、代码风格或任务结构。
克隆仓库后，把两个 skill 复制到 Codex skills 目录：
mkdir -p ~/.codex/skills
cp -R skills/supergoal ~/.codex/skills/
cp -R skills/superdev ~/.codex/skills/之后就可以在 Codex 里这样引用：
Use $supergoal and $superdev.
要求：
- macOS
- Xcode Command Line Tools
- Swift compiler
构建：
cd plugin/supergoal.app-src
./build.sh本地安装：
./install.sh
open /Applications/supergoal.app生成 release 用的磁盘镜像：
./package_dmg.sh生成结果在：
plugin/supergoal.app-src/release/
- 仓库里不包含任何 API key。
- API key 存在本机 macOS keychain。
- Base URL、model、快捷键和自定义 prompt 存在本机。
- 选中的文本只会发送到你配置的 Base URL。
- 不要把真实 API key 或私有项目内容提交到仓库。
MIT. See LICENSE.