Loop Goal Runner(循环目标执行器) 是做什么的?
使用此技能将一个开放式的 Codex 任务转化为一个小型、有状态的循环。该循环必须具有清晰的目标、持久化的状态、一个客观的验证关卡以及一个停止规则。保持默认路径的轻量级;仅当任务证明需要额外成本时,才添加子智能体或工作树。
核心契约
每次循环运行必须维护以下四个工件或决策:
- 目标(Goal):当前的用户目标及其完成标准。
- 状态(State):一个持久的
STATE.md文件或一个明确指定的外部状态系统。 - 关卡(Gate):测试、lint 检查、类型检查、构建、数据验证、截图检查或其他客观的验证命令。
- 停止规则(Stop Rule):成功、遇到阻塞、达到最大尝试次数、达到最大运行时间、达到预算限制或需要人工审批的边界。
在没有新鲜的验证证据之前,不要声称完成。如果没有客观的验证关卡,请将工作保持在建议/手动模式,并说明这不是一个好的循环候选。
工作流
1. 运行循环适配性检查
在构建或继续一个循环之前,检查任务是否适合:
- 每周至少重复一次,或者任务持续时间足够长,使得持久化状态有意义。
- 拥有可以拒绝不良输出的客观验证关卡。
- 可以在当前可用环境中执行。
- 有一个硬性的停止条件。
- 不需要对架构、认证、支付、生产部署或不可逆操作进行无监督的判断。
如果其中一项检查未通过,请说明失败的条件,并使用常规的一次性工作流,除非用户明确要求继续。
2. 定位或创建状态
默认情况下,视状态为作用域于目标的。每个不同的目标都应该有自己的持久化状态文件,除非用户明确要求重用现有的状态文件,或者现有文件显然属于同一个活跃目标。
状态路径优先级:
- 使用用户指定的确切状态文件路径(如果有)。
- 如果正在继续一个已有目标,且其先前的状态路径已知,则重用同一个文件。
- 如果目标创建或主要修改一个任务仓库或工件目录,则使用该任务根目录下的
STATE.md。 - 否则,在当前工作空间的
.codex/goals/<目标-slug>/STATE.md下创建一个特定于目标的状态文件。 - 仅当工作空间本身即为目标,或用户明确选择时,才使用工作空间根目录下的
STATE.md。
在重用任何现有的 STATE.md 之前,检查其“目标(Goal)”和“当前状态(Current Status)”部分。如果它们描述了一个不同的目标,请不要覆盖或重新利用它。而是创建一个新的、作用域于目标的状态文件,并简要提及此分离。
如果选定的状态文件不存在且允许文件编辑,则从 references/state-template.md 创建它。如果不允许编辑,则在回复中起草初始状态并请用户放置它。
每次循环运行开始时:
- 在规划之前,读取选定的、作用域于目标的状态文件。
- 当可用时,读取最近的
AGENTS.md或等效的项目指令。 - 提取上次运行、当前状态、未解决的阻塞、下一步行动、验证历史、经验教训以及状态文件路径。
每次循环运行结束时:
- 仅更新选定的、作用域于目标的状态文件,记录实际采取的行动。
- 记录验证命令及其结果。
- 记录下一步行动或停止原因。
- 保留应在压缩或未来运行中保留的经验教训。
- 除非用户明确要求,否则不要移动、归档或重写无关目标的状态。
3. 塑造目标
对于 Codex 的目标模式(Goal mode),将目标编写得可衡量:
/goal <目标>。完成条件:<客观验证关卡通过>。约束:每次运行更新选定的、作用域于目标的状态文件;在发生 <N> 次失败尝试后或需要人工判断时停止。
如果目标已经激活,除非用户更改,否则使用当前目标作为事实来源。如果没有激活的目标,则从用户请求中推断一个可行的目标并简要陈述。
4. 执行一次循环迭代
使用以下迭代模式:
- 读取状态和指令。
- 选择下一个最小且有价值的行动。
- 执行该行动。
- 运行相关的验证关卡,或解释为何无法运行。
- 审查差异(diff)或输出。
- 更新选定的、作用域于目标的状态文件。
- 决定:继续、停止或升级。
保持变更范围受限。在安排自动化之前,优先进行一次可靠的手工运行。
5. 决定是否使用子智能体
默认使用单个智能体。仅当至少满足以下一种情况时,才使用子智能体:
- 独立的调查可以并行运行。
- 制造/检查(maker/checker)分工能显著降低风险。
- 任务包含几个不相关的故障、子系统或文档。
- 用户明确要求使用并行智能体或子智能体。
当使用子智能体时,应用以下模式:
- 制造/检查(Maker/checker):一个智能体负责实现或调查,另一个负责审查规范合规性和代码质量。
- 并行分发(Parallel dispatch):每个独立的问题域分配一个智能体。
- 验证者(Verifier):一个新的智能体审查证据,而不是隐藏的推理。
不要将子智能体的意见视为硬性关卡。客观验证仍然具有决定性。
6. 决定是否使用工作树(Worktrees)
当多个智能体或长时间运行的分支可能同时写入时,为代码变更使用工作树。跳过用于只读研究、文档分析、小型单文件编辑或非仓库工作空间的工作树。
如果需要工作树,当可用时,优先使用 Codex 原生的工作树支持。否则,仅在使用 Git 工作树之前,确认目标仓库并确保工作树目录不会被意外提交。
7. 完成与升级
在以下情况下,停止并清晰报告:
- 验证关卡通过且目标条件满足。
- 达到最大尝试次数、运行时间或预算限制。
- 需要所需的权限、凭证、外部服务或人工判断。
- 在连续三次循环轮次中出现相同的阻塞点。
- 循环需要在没有明确人工批准的情况下触及架构、认证、支付、生产部署、密钥或广泛权限。
最终响应必须包括当前状态、验证证据以及推荐的下一步行动。
触发可靠性
技能触发基于描述。为了使此技能在未来目标模式使用中自动运行,请将 references/agents-snippet.md 中的代码片段添加到一个全局或项目的 AGENTS.md 中。
参考资料
references/state-template.md:新的STATE.md文件的模板。references/agents-snippet.md:可选的持久化指令,用于在用户开始或讨论一个目标时让 Codex 调用此技能。