Communitygithub.com

Loop Goal Runner(循环目标执行器)

为 Codex、Claude Code 和 AI 智能体提供有状态的目标模式技能,包含 STATE.md 记忆、关卡和停止规则。

Loop Goal Runner(循环目标执行器) 是什么?

Loop Goal Runner 是一个专门用于将开放式任务转化为可控、有状态的循环执行流程的技能。它的核心价值在于防止 AI 智能体(如 Codex、Claude Code)在执行复杂任务时漫无目的或无限循环,通过强制定义清晰的目标(Goal)、持久化状态(State)、客观验证关卡(Gate)和明确的停止规则(Stop Rule),确保每次执行都可评估、可跟踪。该技能支持主流的 AI 代码编辑器,其工作流程包括任务适用性检查、状态文件定位与创建、目标格式化、单次循环执行、子智能体与工作树决策,以及完成或升级上报机制。通过使用包含在 skill 中的 STATE.md 模板和 AGENTS.md 提示片段,开发者和用户可以可靠地触发该技能,从而将一次性任务转化为可重复、可审计的自动化流程,特别适合日常重构、数据验证、长期维护等需要状态记忆的作业。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add AgentPilotLab/loop-goal-runner

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Loop Goal Runner(循环目标执行器) 是做什么的?

使用此技能将一个开放式的 Codex 任务转化为一个小型、有状态的循环。该循环必须具有清晰的目标、持久化的状态、一个客观的验证关卡以及一个停止规则。保持默认路径的轻量级;仅当任务证明需要额外成本时,才添加子智能体或工作树。

核心契约

每次循环运行必须维护以下四个工件或决策:

  1. 目标(Goal):当前的用户目标及其完成标准。
  2. 状态(State):一个持久的 STATE.md 文件或一个明确指定的外部状态系统。
  3. 关卡(Gate):测试、lint 检查、类型检查、构建、数据验证、截图检查或其他客观的验证命令。
  4. 停止规则(Stop Rule):成功、遇到阻塞、达到最大尝试次数、达到最大运行时间、达到预算限制或需要人工审批的边界。

在没有新鲜的验证证据之前,不要声称完成。如果没有客观的验证关卡,请将工作保持在建议/手动模式,并说明这不是一个好的循环候选。

工作流

1. 运行循环适配性检查

在构建或继续一个循环之前,检查任务是否适合:

  • 每周至少重复一次,或者任务持续时间足够长,使得持久化状态有意义。
  • 拥有可以拒绝不良输出的客观验证关卡。
  • 可以在当前可用环境中执行。
  • 有一个硬性的停止条件。
  • 不需要对架构、认证、支付、生产部署或不可逆操作进行无监督的判断。

如果其中一项检查未通过,请说明失败的条件,并使用常规的一次性工作流,除非用户明确要求继续。

2. 定位或创建状态

默认情况下,视状态为作用域于目标的。每个不同的目标都应该有自己的持久化状态文件,除非用户明确要求重用现有的状态文件,或者现有文件显然属于同一个活跃目标。

状态路径优先级:

  1. 使用用户指定的确切状态文件路径(如果有)。
  2. 如果正在继续一个已有目标,且其先前的状态路径已知,则重用同一个文件。
  3. 如果目标创建或主要修改一个任务仓库或工件目录,则使用该任务根目录下的 STATE.md。
  4. 否则,在当前工作空间的 .codex/goals/<目标-slug>/STATE.md 下创建一个特定于目标的状态文件。
  5. 仅当工作空间本身即为目标,或用户明确选择时,才使用工作空间根目录下的 STATE.md。

在重用任何现有的 STATE.md 之前,检查其“目标(Goal)”和“当前状态(Current Status)”部分。如果它们描述了一个不同的目标,请不要覆盖或重新利用它。而是创建一个新的、作用域于目标的状态文件,并简要提及此分离。

如果选定的状态文件不存在且允许文件编辑,则从 references/state-template.md 创建它。如果不允许编辑,则在回复中起草初始状态并请用户放置它。

每次循环运行开始时:

  • 在规划之前,读取选定的、作用域于目标的状态文件。
  • 当可用时,读取最近的 AGENTS.md 或等效的项目指令。
  • 提取上次运行、当前状态、未解决的阻塞、下一步行动、验证历史、经验教训以及状态文件路径。

每次循环运行结束时:

  • 仅更新选定的、作用域于目标的状态文件,记录实际采取的行动。
  • 记录验证命令及其结果。
  • 记录下一步行动或停止原因。
  • 保留应在压缩或未来运行中保留的经验教训。
  • 除非用户明确要求,否则不要移动、归档或重写无关目标的状态。

3. 塑造目标

对于 Codex 的目标模式(Goal mode),将目标编写得可衡量:

/goal <目标>。完成条件:<客观验证关卡通过>。约束:每次运行更新选定的、作用域于目标的状态文件;在发生 <N> 次失败尝试后或需要人工判断时停止。

如果目标已经激活,除非用户更改,否则使用当前目标作为事实来源。如果没有激活的目标,则从用户请求中推断一个可行的目标并简要陈述。

4. 执行一次循环迭代

使用以下迭代模式:

  1. 读取状态和指令。
  2. 选择下一个最小且有价值的行动。
  3. 执行该行动。
  4. 运行相关的验证关卡,或解释为何无法运行。
  5. 审查差异(diff)或输出。
  6. 更新选定的、作用域于目标的状态文件。
  7. 决定:继续、停止或升级。

保持变更范围受限。在安排自动化之前,优先进行一次可靠的手工运行。

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 调用此技能。

相关技能