日期: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 均已完成端到端验证。
当日完整榜单
🎯 适用场景
如果团队已经使用编程 Agent,却缺少统一的交付流程,LoopForge 值得考虑。典型任务是反复出现的小缺陷修复:复现、实现、独立评审、测试、验收有稳定先后关系,失败也能明确退回哪一步。流程越能写出可检查的产物与命令,平台的价值越容易体现。
需要非开发角色参与验收时,它也有意义。产品或测试同事可以看报告和预览,在固定关口决定继续还是退回,而不必从几百条 CLI 输出里猜测模型做了什么。前提是团队真的安排了负责人,人工节点本身不会解决无人响应的问题。
个人随手改几行代码时,完整部署可能不划算。平台增加了 MySQL、容器、运行工作区和凭据管理的维护成本;若只需要内置开发流程,可先了解 Local 版本,而不是把两种形态全部安装一遍。
对不可信用户开放的执行服务、涉及强项目隔离的组织,以及要求外部副作用严格恰好一次的业务,都不适合直接套用默认部署。前者需要重新设计隔离与授权,后者需要业务层自己的事务和幂等机制。工作流状态写得清楚,不代表系统外部的世界也能自动回滚。
💡 总结
LoopForge 最有参考价值的部分,是把编码 Agent 的交付拆成不同责任:模型提交判断,文件契约约束产物,命令验证客观条件,人工操作承担例外决策。返工会改变图中一组节点的状态,批准与重试也各有语义。
它适合希望把既有 CLI 用法沉淀成团队 SOP 的开发者。开始之前,先确认共享工作区的并发写入、审批含义和 Docker 权限边界;流程能够恢复、能够留下记录以后,再扩大自动化范围。