mcpField
A
agent-loop

agent-loop

github.com/joelhooksAgent 工作流6541 次安装1 天前更新
代码仓库

关于 agent-loop

agent-loop 是基于 Inngest 运行持久化编码循环的技能，面向按 PRD 故事推进实现的 Agent 工作流。它依次执行规划、实现、独立评审和裁定，并要求在启动前为每项工作准备可复现的验证路径。

主要功能

  1. 01按故事执行规划、实现、评审与裁定
  2. 02通过 Inngest 运行并追踪各步骤
  3. 03失败后按配置重试并反馈
  4. 04支持取消、状态查询和遥测
  5. 05启动前检查验证与隔离方案

适用场景

  1. 01按 PRD 逐项实现和验证功能
  2. 02运行可追踪的多故事编码循环
  3. 03为自主实现任务补齐可复现检查

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/joelhooks/joelclaw --skill agent-loop

安装后在 Claude Code 中输入/agent-loop确认已加载。

详细介绍

Agent Loop

通过 Inngest 运行持久化的 PLANNER→IMPLEMENTOR→REVIEWER→JUDGE 编码循环。PRD 中的每个故事都会独立实现、测试并评判。即使发生崩溃也能继续。每个步骤都是可追踪的 Inngest 运行记录。

**硬性门槛：**验证优先于循环吞吐量。如果 Agent 无法在不需要 Joel 手动盯着的情况下证明工作正确，就不要启动自主循环。应先补齐缺失的可复现检查、浏览器/控制工具、质量标准或可复用技能，让未来的 Agent 能验证自己的输出。

来源说明：lauren / @poteto 的 X 文章《Loops You Can Trust》（2026-06-24）指出，验证是限制因素：缺乏可信验证的循环会不断累积劣质产出，而可复用的技能/工具能将人类经验转化为 Agent 的能力。

启动循环后，使用 loop-nanny 技能进行监控、分诊、循环后清理，并判断何时需要介入。

验证预检

在执行 joelclaw loop start 之前，确认每个故事都具备：

  • **证明路径：**Agent 可运行的确切命令、测试、浏览器操作流程、API 回读、截图/视频、日志查询或源码检查。
  • **质量标准：**说明“良好”的定义、失败表现，以及不可接受的取巧方式。
  • **前后证据：**说明 Agent 如何捕捉问题修复前/旧状态，并证明修复后/新状态。
  • **隔离方案：**当并行 Agent 可能发生冲突时，隔离工作树、端口、浏览器状态、应用实例、数据库或测试夹具。
  • **可复用验证器：**如果验证方法目前只存在于某个人的脑海中，应先编写技能/工具，让未来的 Agent 也能使用。

如果预检未通过，下一项任务不是“运行循环”，而是“教会 Agent 验证这类工作”。

快速开始

# Start a loop
joelclaw loop start --project /path/to/project --prd prd.json --max-retries 2

# Check status
joelclaw loop status [LOOP_ID]

# Cancel
joelclaw loop cancel LOOP_ID

joelclaw CLI 是主要接口。从 monorepo 根目录运行 bun run packages/cli/src/cli.ts loop start ...。

PRD 格式

在项目根目录创建一个 prd.json：

{
  "title": "Feature Name",
  "description": "What we're building",
  "stories": [
    {
      "id": "S1",
      "title": "Short title",
      "description": "What to implement. Be specific about files, patterns, behavior.",
      "acceptance_criteria": [
        "Criterion 1 — must be verifiable by automated test",
        "Criterion 2 — must be checkable by typecheck/lint"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

编写故事的技巧：

  • 验收标准必须可由机器验证（测试、类型检查、lint）
  • 在标准中写明验证方法或产物，而不只是期望的行为
  • 如果某项标准需要人工判断，先将这种判断转化为可复用的评审清单、技能、测试夹具或工具
  • 优先级数字越小，越先运行
  • 故事应保持小而独立——每个故事只关注一件事
  • 尽可能在描述中包含文件路径
  • JUDGE 批准后，passes 会变为 true；达到最大重试次数仍未通过时，会添加 skipped: true
  • 运行时预检会将旧版别名（acceptance、acceptanceCriteria）规范化为 acceptance_criteria，但格式错误的故事仍会因明确的架构错误而快速失败——PRD 应保持规范格式。

流水线流程

joelclaw loop start → agent/loop.start event
  → PLANNER reads prd.json, finds next unpassed story
    → IMPLEMENTOR spawns codex/claude/pi, commits changes
      → REVIEWER writes tests from acceptance criteria (independently — does NOT read implementation)
        → JUDGE: all green? → mark passed, next story
                 failing?   → retry with feedback (up to maxRetries)
                 exhausted? → skip, flag for human review, next story
  → All done → agent/loop.complete

progress.txt

在项目根目录创建一个 progress.txt，并在顶部添加 ## Codebase Patterns 部分。实现者会读取此部分以了解项目背景，评判者则会在每个故事完成后追加内容。这样可避免全新的 Agent 实例丢失上下文。

## Codebase Patterns

- Runtime: Bun, not Node
- Tests: bun test
- Key files: src/index.ts, src/lib/...

## Progress

(stories will be appended here)

基础设施

  • 规范源码：~/Code/joelhooks/joelclaw/packages/system-bus/（monorepo）
  • Inngest 函数：agent-loop-plan、agent-loop-implement、agent-loop-review、agent-loop-judge、agent-loop-complete、agent-loop-retro
  • **Inngest 服务端：**运行在 localhost:8288 的 k8s StatefulSet
  • **Loop 的 --project 目标：**使用请求指定的绝对目标项目。system-bus 包负责循环运行时代码；它并非所有工作负载的目标项目。
  • 应用工作进程变更：~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh
  • 验证函数：joelclaw functions
  • 查看运行记录：joelclaw runs -c
  • 检查运行记录：joelclaw run RUN_ID
单一源部署流程

monorepo 是循环函数代码的事实来源。循环相关函数的更改合并后，从 monorepo 部署 worker：

  1. 运行 ~/Code/joelhooks/joelclaw/k8s/publish-system-bus-worker.sh
  2. 等待滚动更新完成：kubectl -n joelclaw rollout status deployment/system-bus-worker --timeout=180s
  3. 刷新注册：joelclaw refresh

事件架构

所有事件都携带 loopId，用于追踪。关键事件：

事件用途
agent/loop.start启动循环（loopId、project、prdPath、maxRetries、maxIterations）
agent/loop.plan规划器重新进入（查找下一个故事）
agent/loop.implement分派给实现者（storyId、tool、attempt、feedback？）
agent/loop.review分派给审查者（storyId、commitSha、attempt）
agent/loop.judge分派给评判者（testResults、feedback、attempt）
agent/loop.complete循环完成（summary、counts）
agent/loop.cancel停止循环
agent/loop.story.pass故事通过
agent/loop.story.fail达到最大重试次数后跳过故事

工具分配

默认情况下，使用 codex 实现，使用 claude 审查。可通过启动事件中的 toolAssignments 覆盖每个故事的设置：

{
  "toolAssignments": {
    "S1": { "implementor": "claude", "reviewer": "claude" },
    "S2": { "implementor": "codex", "reviewer": "pi" }
  }
}

已知注意事项

  • 并发键使用 CEL 表达式（event.data.project），而不是 {{ }} 模板
  • loop 在 CEL 中是保留字，不要在并发键字符串中使用
  • 查看 codex exec --help 以了解当前调用标志。使用已配置的沙盒和审批策略；不要在任务分派过程中放宽这些限制。
  • Worker 更改需要部署到 k8s（k8s/publish-system-bus-worker.sh）
  • Inngest 服务端需要 Docker 正在运行（open -a OrbStack）
  • 大型工具输出使用 claim-check 模式（写入 /tmp/agent-loop/{loopId}/）

遥测与回执

故事尝试必须能通过循环状态、Inngest 运行记录／事件和规范 OTel 进行查看。使用以下内容查询：

joelclaw loop status <loop-id> -v
joelclaw otel search "story-pass|story-retry|story-skip|build-complete" --hours 24

原有的 slog 写入路径已停用。仅在 Brain .svx 中记录持久的循环决策或行为变更；不要重新创建只追加的日志。

源文件

文件用途
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/client.ts事件类型定义
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/utils.tsPRD 解析、git、取消、claim-check
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/plan.ts规划器
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/implement.ts实现者
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/review.ts审查者
~/Code/joelhooks/joelclaw/packages/system-bus/src/inngest/functions/agent-loop/judge.ts评判者
~/Code/joelhooks/joelclaw/packages/system-bus/src/serve.tsWorker 注册
~/Code/joelhooks/joelclaw/packages/cli/src/cli.tsjoelclaw CLI（循环子命令）

评论

支持 Markdown