每天一个开源项目#160 LoopForge:把Agent交付拆成可退回的验收流程

日期:2026-11-18 GitHub Trending 日榜第 4 位;榜单采集时间:16:00(UTC+08:00)

代码 Agent 说"修好了",距离团队能接收这次改动,还有几件具体的事:测试在哪台机器跑的,评审看的是不是最后一版,产物缺失要不要退回,审批时那个执行进程是否还在写文件。

把这些问题写进提示词,能约束一次对话;把它们变成工作流状态,才能在失败、暂停和重跑之后继续追踪。Tencent 的 LoopForge 选择了后一条路:保留现有编程 CLI,在外面增加角色、工作区、脚本检查和人工关口。下面重点看它的 SOP 引擎,尤其是"通过""返工"和"继续"各自意味着什么。

📋 项目概览

项目 内容
主仓库 Tencent/LoopForge
定位 可自主部署的编码 Agent 协作与软件交付工作台
两种入口 与 Main Bot 对话;运行由角色、脚本、人工关口和子 SOP 组成的流程
平台实现 Go 后端、Web 工作台;MySQL 保存业务数据
执行方式 编程 CLI 配合 Docker 工作区或连接的执行机器
许可证 MIT;第三方组件保留各自声明
本文重点 DAG 调度、结构化终态、产物契约、返工范围和人工控制

平台版与 LoopForge Local 是不同的运行方式。前者管理团队共享的流程和运行记录;后者把内置工作流安装到编程助手中。不要把 Local 的宿主集成当成完整平台引擎,也不要认为平台上的任意 SOP 已经能导出为本地独立流程。项目文档明确把后一项列为后续方向。

🔥 为什么值得关注

很多多 Agent 演示止步于"让一个 Agent 写、另一个 Agent 评"。真正麻烦的是评审否决以后:该重新问评审者,还是退回实现者?旧的测试结果还能用吗?原先并行运行的分支要不要停?

LoopForge 的返工不是追加一句"请再试一次"。引擎会找出返工目标及其下游节点,把相应状态重置,再按依赖关系重新推进。这样才能表达"实现改了,评审和测试都需要重做",而不是只重跑最后那个报错的步骤。

另一个值得注意的选择是:Agent 的结论与客观检查分开。模型需要提交结构化终态,但提交 pass 之后仍然可能因产物缺失或验证命令失败而停下。这比在最终回复中搜索"完成"可靠,也保留了人在关键位置接手的空间。

这些设计并不保证模型一定改对代码。它们解决的是更基础的问题:流程到底执行到了哪里,以及下一次该从哪里开始。

🏗️ 核心特性

角色负责判断,脚本负责可执行检查

角色定义包含提示词、执行器、模型、规则、Skills、MCP 工具和验收配置。同一角色可以出现在 SOP 节点中,也能作为对话子 Agent 使用。编程 CLI 仍然承担实际编码,平台组织外围流程,而非自己实现另一个代码生成模型。

脚本节点可以使用 Shell 或 Python。构建、格式检查、单元测试和固定报告生成,适合放在这类节点里。能用命令确定的条件没有必要让模型再解释一次;需要需求理解或代码判断的部分,则留给角色。

产物是声明过的文件,不只是一段聊天记录

节点的 artifactOutputs 描述名称、相对路径、媒体类型和是否必需。角色的默认产物契约还可以由具体 SOP 节点细化。引擎会检查产物,再收集节点结果;成功收集的产物带有大小与 SHA-256 等信息,便于区分不同执行留下的版本。

例如,评审报告存在与否可以成为确定性条件,但报告里的结论是否正确仍取决于评审者。文件契约验证的是交付形式,不能代替内容审查。字段定义见项目的 工作流领域模型。

人工介入有不止一种语义

一个普通审批节点会进入等待状态;角色也能在无法判断时主动请求人工确认。除此以外,操作员还可以暂停运行、补充上下文、退回上游或选择节点重放。

这里最容易误用的是"批准"和"重试":批准接受现有结果,不再执行该节点;重试则启动新的执行。审批界面上的一次操作,必须与团队真正想承担的责任一致。

🔬 技术架构深度解析

从模板到一次具体运行

下面画的是平台 SOP 的主路径,不包含 Main Bot 的全部对话能力:

text 复制代码
Web / HTTP 入口
       │ 选择 SOP、输入需求、绑定仓库和责任人
       ▼
startWorkflowDefinition
       │ 校验图和环境,生成 WorkflowSnapshot
       │ 建立 Run、NodeRun,并持久化
       ▼
MySQL 中的运行状态 ◄────────── 人工审批 / 暂停 / 退回请求
       │                             │
       ▼                             │
拥有 lease 的 Worker                 │
       │ readyNodes:前置节点全部 succeeded
       ├─────────────┬───────────────┘
       ▼             ▼
Agent / 脚本节点    人工审批节点
       │             └── waiting_approval
       ▼
本次 Run 的工作区 / 远端 Runner 工作区
       │ CLI 输出、产物、验证结果
       ▼
状态提交栅栏 → 节点结果持久化 → 解锁后续节点

startWorkflowDefinition 会检查工作流及沙箱要求,把图和解析后的沙箱信息放进 Run 的快照,再创建各节点的 pending 状态。正常推进优先使用这份快照,因此编辑模板不会直接把正在运行的依赖图换掉。对应实现是 运行创建 与 工作流图处理。

但"冻结快照"不能理解为任何重放配置永远不变。人工返工、重试路径会调用更新节点绑定的逻辑,选择性带入最新配置。复盘一次失败时,既要看初始 Run,也要看后来的控制操作。

依赖满足即可执行,不按整批等待

readyNodes 的条件很直接:节点本身是 pending,并且所有入边来源都已 succeeded。execute 为就绪节点启动 goroutine,同时用 inflight 记录正在执行的节点;节点结束后唤醒调度循环。它不会等同一批最慢的节点结束,再统一启动下一批。

假设文档检查和代码检查同时启动,文档检查先完成,只依赖它的汇总节点可以先往下走;依赖两者的发布节点则继续等待。依赖图决定先后关系,不能用画布上的左右位置替代真正的边。

并行也有成本。平台路径中,节点引用同一个 Run 拥有的工作区,而不是每个角色都自动得到独立 Git worktree。初始化有锁,同一角色的 CLI 调用也会串行,但不同角色仍可能对共享文件产生竞争。团队应当用依赖关系避免两个节点同时改同一片代码,不能从"多角色"推导出写入隔离。调度和工作区复用可沿着 节点执行主链 阅读。

一次 Agent 执行要经过哪些验收

对于配置了相关检查的正常 pass 路径,顺序可以概括为:

text 复制代码
运行编程 CLI
    ↓
读取 submit_gate_result 的结构化终态
    ↓ pass
验证 artifactOutputs 契约
    ↓
执行自动验证命令 / MR 交付检查
    ↓
收集并记录产物
    ↓
若有 required manual gate,等待人工确认
否则标记节点 succeeded

submit_gate_result 接受 pass、rework、fail、human 四类决策,要求给出 reason;human 还必须填写 actionRequired,说明到底需要人决定什么。引擎读取的是结构化结果,不是模型最终回答中的关键词。具体校验位于 gate_submit.go。

如果结果缺失或无效,引擎在有可恢复 CLI Session 时会要求同一会话补交;仍拿不到有效结果,则转人工等待。Session 丢失还有重新调用的回退,所以不能把这个机制描述成"任何故障都绝不重复任务"。

还有一个重要例外:rework、fail、human 会短路后面的产物验证和自动门禁,并留下相应事件。看到人工等待,不代表自动测试已经跑过;人批准继续,也不是暗中补跑这些检查。流程记录应当区分"检查失败"和"根本没有执行检查"。

重做的范围与预算

机制 触发与范围 需要注意
角色内部自修正 门禁失败策略为 loop,受角色循环轮数约束 在同一工作区接受失败反馈,不是无限循环
节点自动 attempt 一般执行错误且还有 MaxAttempts 预算 验证类错误、轮次耗尽等有排除规则
上游返工 明确 rework 且配置了 rejectTo 重置目标及全部后代,而非只重复当前评审
人工定点重放 操作员从已停止的运行中选择节点 保留成功上游;已耗尽预算时只增加额外一次机会

显式 rework 会绕过当前节点的普通自动重试,避免评审者重复讨论一个本就应交给实现者的问题。若没有返工目标,这个决策会降为失败处理,不会凭空猜测该退回谁。

返工的重置集合来自图的后代遍历。目标和后代重新变成 pending,当前输出、错误和子 Run 引用被清理,返工目标拿到反馈。受影响且仍在跑的并行执行会被取消。shouldCommitNodeOutcome 再检查 generation、节点在途状态和失败 attempt,避免旧结果回来后把已重置的节点覆盖掉。它是运行状态的写入防护,不是对外部副作用的"恰好一次"保证。

当显式 Agent 返工耗尽预算时,当前节点可以转到 waiting_approval,交由人决定是否接受现有上游结果。普通脚本失败走 reject 的超限路径不一定如此,仍可能直接失败。源码对这两类情况有不同处理,不能简化成"失败一定自动修,修不好一定找人"。这部分主要在 节点结果处理 和 运行控制操作 中。

暂停与批准不能混为一谈

Approve 把等待审批的节点标记为成功并推进下游;它不是再次执行。Retry 则重置选中节点及后代,并检查上游是否已完成。用户暂停后的恢复又有区别:Agent 可以恢复会话并接收补充信息,脚本则从头开始,不是从任意 Shell 指令的断点接着跑。

对于多 Worker 部署,暂停和取消先把意图写进仓库,再通知实际持有运行的 Worker。引擎执行期间续租;续租失败或发现控制请求时取消执行上下文。收尾前要等待在途节点退出。API 接受了暂停请求,只能说明请求已记录,不等于远端命令已经停止。

这种实现对追踪和恢复有帮助,但不会替应用设计幂等性。一个脚本如果先调用外部接口、再因为断连而未记录成功,重跑时仍可能再次调用接口。付款、发消息、发布版本之类操作,应在业务脚本里增加幂等键或独立回执。

MR 门禁也有明确覆盖范围

交付检查关注的是远端工作分支:对可写且相对目标分支有新增提交的仓库,确认存在覆盖当前已推送 tip 的 MR/PR。已合并但不包含本轮 tip 的旧 MR,不能拿来充当本次交付证明。

边界同样值得保留:如果提交还只在本地、根本没推送,这个检查不会因此要求 MR;托管平台不返回 open MR 的 head 时,当前实现也允许接受它。查询能力或授权不足时,流程会请求人工确认,而不是让模型盲目"修"一个权限故障。因此它是特定的交付覆盖检查,不是"所有代码都已推送、审查并合并"的总保证。详细条件见 gate_mr.go。

📖 README 核心内容摘要

阅读项目说明时,最有用的是先分清部署、执行器与账号边界。

平台可以直接与 Main Bot 对话,也能运行有固定阶段的 SOP。仓库内提供后端、前端、缺陷修复和产品方案模板,适合作为开始配置的蓝图,而不是对所有项目都合适的标准答案。产品方案或新项目生成可以先不绑定 GitHub;修改已有仓库并交付 PR,才需要相应仓库授权。

执行器适配不代表每个功能都能自由混用同一组模型。项目说明列出多种编程 CLI,但它们的凭据方式、安装方式以及能出现的入口存在区别。尤其不要把"支持某 CLI"理解成每个后台 AI 功能都使用它,部署时应按具体入口确认。

默认安装走 Compose:MySQL 与平台服务分开,start.sh 默认拉取 compose.yaml 中指定的发布镜像,而非编译当前检出的 Go 代码;需要构建源码时有单独的 dev 路径。当前配置中的平台镜像标签为 0.4.0。镜像标签是部署选择,不能拿来替代运行时实际版本检查。

最需要认真对待的是 Docker socket。平台通过挂载宿主机 Docker socket 创建执行容器,因此平台获得了控制宿主机 Docker 的权限。容器把任务环境组织起来,并不自动形成面向不可信租户的安全边界。项目还明确说明:这是可信团队场景,登录用户可以读取实例内各项目数据。想把它当成公网多租户 Agent 托管服务,需要额外设计权限和隔离。

这些部署细节可以对照 Compose 配置 与 部署指南,而不是只看首页功能列表。

🚀 快速上手

先用发布镜像跑通脚本与审批

准备 Git、Python 3、Docker 和 Compose,并确认 Docker 可用。安装脚本可能询问补装依赖或 Docker 访问方式;它不是单纯下载网页资源的无副作用命令。适合先在自己能控制访问范围的开发机或测试服务器上部署。

bash 复制代码
git clone https://github.com/Tencent/LoopForge.git
cd LoopForge
./start.sh

默认端口映射是宿主机 8090 到容器 8080,默认监听所有网卡。按安装输出打开页面并创建首个管理员账号。模型 Key 和仓库授权随后再配,不要为了体验脚本节点先给平台接入生产凭据。

不需要模型额度的第一条路径是:进入"LoopForge 体验项目",打开"平台验收 · 脚本与审批",运行流程,查看报告,在"待我确认"批准,然后观察后续产物。这个例子先验证脚本、状态推进、产物与人工关口,避免把模型 API 故障混进平台部署问题。

服务管理使用启动脚本已有的子命令:

bash 复制代码
# 以下命令仍在 LoopForge 仓库根目录执行
./start.sh logs
./start.sh stop
./start.sh restart

stop 保留容器与数据;restart 重启平台容器。默认启动不构建源码,若要开发当前 checkout,可用 ./start.sh dev,代价是本地构建时间和依赖准备。子命令分支可以直接在 start.sh 中确认。

给脚本节点一个可检查的小产物

在流程设计器中新建 Python 脚本节点,将执行范围设为运行工作区,脚本内容可以用下面这个纯本地例子。它不调用模型,不访问网络,只生成一份 JSON 报告:

python 复制代码
from pathlib import Path
import json

cases = [(2, 3, 5), (0, 0, 0), (-2, 2, 0)]
for left, right, expected in cases:
    assert left + right == expected

report = Path("reports/smoke.json")
report.parent.mkdir(parents=True, exist_ok=True)
report.write_text(
    json.dumps({"passed": len(cases), "status": "ok"}),
    encoding="utf-8",
)
print(report.read_text(encoding="utf-8"))

给它声明一个必需产物:名称 smoke、路径 reports/smoke.json、媒体类型 application/json。然后接一个人工审批节点,要求批准者打开产物确认。三个加法断言只是演示确定性产物链,不代表验证了真实项目;接到自己的仓库后,应换成真实构建和测试。

对应字段片段如下,表示脚本节点的配置内容,不是单独可提交的完整 SOP,也不是新的 CLI 命令:

json 复制代码
{
  "type": "script",
  "scriptLanguage": "python",
  "executionScope": "run",
  "artifactOutputs": [
    {
      "name": "smoke",
      "path": "reports/smoke.json",
      "mediaType": "application/json",
      "required": true
    }
  ]
}

试用时可以故意把声明路径改成不存在的文件,观察它是否阻断后续审批;再恢复路径,观察正常产物是否可读。这能帮助团队弄清楚自己配的是"文件存在条件",还是更具体的内容验收。需要检验 JSON 字段值时,应再增加对应验证脚本。

最后再接入模型与代码仓库,从一个可复现的小缺陷开始,把实现、独立评审、测试和人工验收连起来。不要先让多个角色并行修改同一目录,也不要把审批通过自动等同于允许推送默认分支。

📊 增长速度与社区热度

11 月 18 日的日榜中,LoopForge 位于第 4。它与多种技能包、代码审查工具和 Agent 交互项目同时出现,能看出这一天开发者工具类项目的集中度较高;这只是当日榜单观察,不能据此推导某个项目的采用规模。

对 LoopForge,更值得持续观察的是执行器兼容、暂停恢复与交付验证能否在真实任务里保持一致。项目已有针对结构化终态和返工预算的测试,例如 TestSubmitReworkBudgetExhaustedWaitsForHuman 明确断言:预算耗尽后等待人工,批准才继续。这样的边界用例比单看首页罗列多少功能更有参考价值,但测试断言不能直接当成所有模型和远端 Runner 均已完成端到端验证。

当日完整榜单

排名 仓库
1 elementalsouls/Claude-BugHunter
2 mvanhorn/last30days-skill
3 alibaba/open-code-review
4 Tencent/LoopForge
5 dream-num/univer
6 getarcaneapp/arcane
7 google-labs-code/stitch-skills
8 cursor/plugins
9 obra/superpowers
10 ag-ui-protocol/ag-ui
11 backnotprop/plannotator
12 sveltejs/svelte
13 affaan-m/ECC
14 jingyaogong/minimind
15 google-research/paper-orchestra

🎯 适用场景

如果团队已经使用编程 Agent,却缺少统一的交付流程,LoopForge 值得考虑。典型任务是反复出现的小缺陷修复:复现、实现、独立评审、测试、验收有稳定先后关系,失败也能明确退回哪一步。流程越能写出可检查的产物与命令,平台的价值越容易体现。

需要非开发角色参与验收时,它也有意义。产品或测试同事可以看报告和预览,在固定关口决定继续还是退回,而不必从几百条 CLI 输出里猜测模型做了什么。前提是团队真的安排了负责人,人工节点本身不会解决无人响应的问题。

个人随手改几行代码时,完整部署可能不划算。平台增加了 MySQL、容器、运行工作区和凭据管理的维护成本;若只需要内置开发流程,可先了解 Local 版本,而不是把两种形态全部安装一遍。

对不可信用户开放的执行服务、涉及强项目隔离的组织,以及要求外部副作用严格恰好一次的业务,都不适合直接套用默认部署。前者需要重新设计隔离与授权,后者需要业务层自己的事务和幂等机制。工作流状态写得清楚,不代表系统外部的世界也能自动回滚。

💡 总结

LoopForge 最有参考价值的部分,是把编码 Agent 的交付拆成不同责任:模型提交判断,文件契约约束产物,命令验证客观条件,人工操作承担例外决策。返工会改变图中一组节点的状态,批准与重试也各有语义。

它适合希望把既有 CLI 用法沉淀成团队 SOP 的开发者。开始之前,先确认共享工作区的并发写入、审批含义和 Docker 权限边界;流程能够恢复、能够留下记录以后,再扩大自动化范围。

相关推荐
Allen36682 小时前
给博客和秘书加上 HTTPS 之后的一点记录
github
laoyeye8313 小时前
手写 vLLM 分页 KV Cache(二):深入物理块分配、Block Table 与 Slot Mapping
github
Summer-Bright5 小时前
企业落地智能体,供应链签名还是空白:1862 个 MCP 服务器无认证裸奔
服务器·人工智能·github·mcp
一条Go5 小时前
Pod 终端与日志:为什么浏览器建连要先换一张 60 秒的票
后端·架构·github
一条Go5 小时前
开源新生代雷达 · 第 14 期
github
徐小夕8 小时前
万字拆解:零向量库、无模型微调,SAG2 凭什么刷新多跳问答 SOTA
前端·vue.js·github
黑土豆8 小时前
用 drawink 给业务页面加一层画板:从网页批注到无限板书
前端·javascript·github
dong_junshuai1 天前
每天一个开源项目#159 Plannotator:把Agent审阅做成异步消息
github
bysking1 天前
GitHub Actions 快速入门+场景实践案例
前端·后端·github