实战工具:用 LoopForge 把编码 Agent 的交付做成可审批 SOP

把一个需求丢给编码 Agent 之后,常见的别扭并不在「它会不会写代码」,而在交付过程本身:同一种修法下次很难原样再走一遍,做到一半缺少明确的人审节点,事后也不容易说清当时改了什么、谁放的行。结果往往是对话记录、临时脚本和一次成功的提交散落各处,团队很难把它变成可重复的交付方法。

LoopForge 是腾讯开源的自主部署工作台,用来和编程 Agent 一起交付软件。官方中文说明把它概括成:在对话里把需求告诉 Main Bot ,由它按需打开沙箱、分派项目角色并提交 PR;某种做法被验证有效后,再存成 SOP ------由 Agent、脚本和人工关口组成的标准交付流程,让下一个需求按同样的方式走完评审和验收。干活的仍是编程 Agent CLI(CodeBuddy、Codex、Claude Code、OpenCode、Cursor CLI、Antigravity、Kimi Code、Pi、DeepSeek Harness、ZCode 等);LoopForge 负责它们外面的角色、沙箱、检查点和留痕。许可证为 MIT(腾讯 2026 版权声明,并另列第三方组件)。

官网 loopforge.cn 把这件事说得更短:「把团队的交付方法,变成 Agent 可执行的 SOP。」这个仓库并不是很久以前的项目:GitHub 记录它创建于 2026 年 7 月,查询日前一天刚发布正式版 v0.4.0 。需要同时分清两条线:自托管平台的当前正式版是 v0.4.0 ;在本机把工作流装进编程助手的 npm 包 loopforge-cli ,查询时最新正式版仍是 0.2.2,不要把 CLI 写成 0.4.0。

相关入口(查询日:2026-11-18,Asia/Shanghai):

  • 仓库:Tencent/LoopForge(GitHub API 于 2026-11-18 09:28 Asia/Shanghai 返回 3,178 stars、442 forks。仓库创建于 2026-07-28T03:51:01Z,合 2026-07-28 11:51 Asia/Shanghai;最近一次 push 为 2026-11-17T17:57:53Z,合 2026-11-18 01:57 Asia/Shanghai。查询时官方 GitHub Trending · Today 将该仓库列在第 4,页面显示 591 stars today;该日榜页面于 2026-11-18 09:30 Asia/Shanghai 核对)
  • 官网:loopforge.cn
  • 中文 README:README.zh-CN.md
  • 部署说明:docs/deployment.md
  • 本地工作流:docs/local/usage.zh-CN.md
  • npm 包:loopforge-cli(本次实测 0.2.2 ,发布于 2026-09-16T09:57:17.949Z,合 2026-09-16 17:57 Asia/Shanghai;许可证 MIT,bin 为 loopforge)
  • 许可证:MIT
  • 本次对照的平台版本:v0.4.0(GitHub Release 由 github-actions 发布于 2026-11-17T14:30:43Z,合 2026-11-17 22:30 Asia/Shanghai)

本文只记录本地 Linux x86_64 上的一次有边界的实测。本机没有 Docker,因此没有执行 ./start.sh,没有创建管理员账号,也没有跑官方提供的免 API Key 体验 SOP「平台验收 · 脚本与审批」。实际做了两件事:把官方仓库浅克隆并钉死在 v0.4.0 ,核对其 compose.yaml 钉住的镜像标签,以及在不拉取镜像层的前提下读取 GHCR 清单 digest;然后在项目目录里安装 loopforge-cli 0.2.2 ,运行 version / --help / editions / doctor / plan,再把 Portable 工作流安装进一个隔离的示例目录。没有配置任何模型密钥,也没有打开编码助手去执行 /devflow 或完整交付。下文不声称已经把自托管平台跑起来,或已经走完一次带审批的 SOP 交付。

一、原理与流程

官方把日常使用分成两种方式,它们挂在同一套需求上,但节奏不同。

和 Main Bot 对话,适合探索、快速修复,以及和 Agent 反复迭代:Main Bot 按需打开带项目仓库的对话工作区,把项目角色当作子 Agent 调用,交付物通常是 PR/MR,也可以直推共享分支。运行 SOP 则适合阶段固定、需要签字确认的可重复交付:引擎按顺序执行 Agent、脚本、人工关口、子 SOP 和预览构建,每次运行有独立沙箱,人可以在关口审批、打回或从指定节点重跑。

SOP 里这几类节点的分工很清楚。Agent 节点对应一个角色(提示词、执行器、模型、规则、Skills、MCP 工具),负责设计、实现、评审或测试;脚本节点是确定性的 Shell 步骤,用来构建、测试、Lint 或生成报告,不需要模型的地方就不用模型;人工关口会暂停运行,等人检查产物后放行或打回;子 SOP 用来复用另一条流程;预览构建则把静态站点归档给评审查看。官方也写明:新注册账号会加入体验项目,其中有一条只包含脚本和人工审批的 SOP,不需要 API Key 就能走完「脚本写报告 → 停在审批 → 放行后继续到最终产物」;对话和 Agent 步骤才需要所选执行器的 Key。这条体验路径依赖已经启动的自托管平台,本次没有执行。

不想部署服务端时,可以用 LoopForge Local :把内置的 Classic 或 Portable 工作流安装到正在使用的编程助手里。Classic 是默认版,入口一般是 /start-devflow;Portable 基于 Agent Skills,Cursor / Claude Code / CodeBuddy 的入口是 /devflow。真正跑这些工作流,仍然需要相应的宿主和模型凭据。官方还说明:平台 SOP 导出后在本地独立执行尚未实现。

可以把这次实测看成四步:钉死平台仓库 v0.4.0 并核对镜像标签与 digest;在项目目录安装 loopforge-cli 0.2.2;用只读的 plan 看清将写入哪些文件;再把 Portable 工作流装进隔离示例目录,确认安装状态和 doctor 检查通过。后面两步都不需要 Docker,也不需要模型密钥。

二、安装配置

环境:Linux x86_64,Git 2.47.3,Python 3.13.5,Node.js v24.22.1,npm 11.21.1。本机没有 docker 命令,当前用户也不在 docker 组,因此走不通官方默认的自托管路径,下面只把它作为对照写出来,并如实记录本次实际采用的 Local CLI 安装。

平台的安装方式在 Release 和中文 README 里是一致的:先准备 Git,再克隆指定版本并执行 ./start.sh。安装脚本会检查 Docker、Compose、Python 3 和 curl;默认拉取 compose.yaml 中 pin 的 GHCR 发布镜像,不在本地构建。服务默认监听 0.0.0.0:8090。模型 API Key 和 GitHub 授权是启动之后再配置的事。国内拉取 ghcr.io 不稳定时,可以把 MIRROR 设成镜像站主机名,例如:

bash 复制代码
git clone --branch v0.4.0 https://github.com/Tencent/LoopForge.git
cd LoopForge
./start.sh
# 或:MIRROR=ghcr.nju.edu.cn ./start.sh

本次没有运行 ./start.sh。为了核对版本,只做了浅克隆,并把工作树留在项目目录里,没有改上游文件:

bash 复制代码
git clone --branch v0.4.0 --depth 1 https://github.com/Tencent/LoopForge.git LoopForge
git -C LoopForge describe --tags --exact-match
git -C LoopForge rev-parse HEAD

实际结果:标签为 v0.4.0,提交为 e89cda9804643d3631e77652d1bca47a079adb69(提交时间为 2026-11-17 21:49 +08,工作区干净,共 3,412 个文件)。compose.yaml 里平台服务和隔离沙箱镜像都钉在同一标签上:

yaml 复制代码
image: ${LOOPFORGE_IMAGE:-ghcr.io/tencent/loopforge:0.4.0}
# ...
AGENTFLOW_ISOLATED_IMAGE: ${LOOPFORGE_IMAGE:-ghcr.io/tencent/loopforge:0.4.0}

这与 Release 声明的平台镜像 ghcr.io/tencent/loopforge:0.4.0 一致。compose.yaml 本身没有写 digest;Release 给出的摘要是 ghcr.io/tencent/loopforge@sha256:87b6a3e3cba201d03f8f8d22929881f576021fc78c7c42e82f78329abbf4bda4。在没有 Docker、也没有拉取镜像层的前提下,向 GHCR 读取 0.4.0 的 OCI 索引清单,响应头里的 docker-content-digest 与上述摘要一致。这只证明查询时该标签的清单 digest 对得上,并不等于本机已经保存或启动过这个镜像。

Local CLI 按官方文档需要 Node.js 20+ 和 Python 3.8+。本次不使用 npm install -g,而是在项目目录里钉死已经发布的 loopforge-cli@0.2.2:

bash 复制代码
mkdir cli-pkg && cd cli-pkg
npm init -y
npm install loopforge-cli@0.2.2 --save-exact

实际安装结果(耗时 0.430 秒,退出码 0):npm 报告 added 1 package, and audited 2 packages in 374ms,npm ls 显示 loopforge-cli@0.2.2,包的 bin 为 loopforge,许可证为 MIT。需要留意一个版本差:v0.4.0 源码树里 local/package.json 写的是 0.2.3,但 npm 上查询时的 latest 仍是 0.2.2,目录中也没有 0.2.3 这个正式版本。本次只按已经发布的 0.2.2 实测,不把源码里的 0.2.3 当成已安装版本。

三、完整代码与实跑输出

3.1 先确认 CLI 版本与命令

安装完成后,用项目目录里的本地二进制核对版本和帮助信息:

bash 复制代码
./node_modules/.bin/loopforge --version
./node_modules/.bin/loopforge --help
./node_modules/.bin/loopforge editions

--version 实际输出为 0.2.2(耗时 0.096 秒,退出码 0)。--help(耗时 0.063 秒,退出码 0)列出的命令包括 install、update、skills、editions、plan、status、uninstall 和 doctor,并把自身概括成「安装和维护 DevFlow Classic / Portable 工作流」。editions(耗时 0.059 秒,退出码 0)给出的对照如下:

text 复制代码
portable: Agent Skills based portable workflow
  sources: skills/
  entries: codebuddy=/devflow, codex=$devflow, cursor=/devflow, claude=/devflow
classic (default): Full host-native workflow derived from .codebuddy behavior
  sources: .codebuddy/, .codex/, .cursor/, .claude/
  entries: codebuddy=/start-devflow, codex=$devflow-codex, cursor=/start-devflow, claude=/start-devflow

doctor 会检查 CLI 自带的安装资产是否完整,并核对这些资产安装到目标项目后有没有被改动或缺失。在尚未安装工作流的包装目录上运行 loopforge doctor --project-root ./cli-pkg(耗时 0.060 秒,退出码 0),输出为 OK: assets and installations are healthy,说明 0.2.2 包里的资产是完整的。

3.2 用 plan 只读预览将写入的文件

官方文档建议在安装前先跑 loopforge plan,它只读取安装资产,不修改目标项目。对 Cursor 分别预览 Classic 和 Portable:

bash 复制代码
loopforge plan cursor
loopforge plan cursor --edition portable

第一条实际输出开头为(耗时 0.082 秒,退出码 0):

text 复制代码
edition=classic host=cursor source=.cursor/ entry=/start-devflow files=85

第二条为(耗时 0.098 秒,退出码 0):

text 复制代码
edition=portable host=cursor source=skills/ entry=/devflow files=84

Classic 默认会写入以 .cursor/ 为根的完整宿主包,入口是 /start-devflow;Portable 从 skills/ 生成 84 个文件,入口是 /devflow。对 Claude Code 再跑一次默认的 Classic 预览,结果同样是 85 个文件,根目录换成 .claude/,入口仍是 /start-devflow(耗时 0.074 秒,退出码 0)。plan 本身不接受 --project-root,因为它并不往项目里写文件。

3.3 把 Portable 工作流装进隔离示例目录

为了避免改动本机真实的 ~/.cursor 或其他全局配置,新建了一个只用于安装的示例目录,并用 --project-root 明确指定安装位置:

bash 复制代码
loopforge skills install cursor --project-root ./samples/demo-project

实际输出(耗时 0.113 秒,退出码 0):

text 复制代码
OK: skills install host=cursor project=/workspace/csdn-loopforge/samples/demo-project written=84 unchanged=0
Next: reopen Cursor and run /devflow <你的需求>

随后的状态检查与 doctor 结果如下:

bash 复制代码
loopforge skills status cursor --project-root ./samples/demo-project
loopforge doctor --project-root ./samples/demo-project

skills status(耗时 0.065 秒,退出码 0)输出 skills/cursor: files=84 changed=0 missing=0。doctor(耗时 0.063 秒,退出码 0)再次给出 OK: assets and installations are healthy。安装前后对照本机 $HOME/.cursor 和 $HOME/.codex 的文件清单与 SHA-256,没有新增、删除或改动;写入范围只在这个示例目录里。

示例目录里实际出现的文件,比 written=84 多出两份:原来的 README.md,以及安装器生成的 .devflow/install-state.json。工作流文件主要落在这些位置:

  • .cursor/agents/:devflow-research-helper.md、devflow-stage-executor.md
  • .cursor/skills/devflow/:Skill 正文、命令、路由配置、各宿主适配器、规则、脚本和产物模板
  • .cursor/skills/devflow-clarify-requirements/:需求澄清 Skill
  • .cursor/skills/manifest.json:声明 Portable 技能集为 devflow 与 devflow-clarify-requirements
  • .devflow/install-state.json:记录 edition、包版本和每个托管文件的 SHA-256

install-state.json 开头可以确认,这次写入的是 0.2.2 的 Portable / Cursor 安装,而不是平台的 0.4.0:

json 复制代码
{
  "version": 1,
  "installer_version": "0.2.2",
  "installations": {
    "portable:cursor": {
      "host": "cursor",
      "edition": "portable",
      "package_version": "0.2.2"
    }
  }
}

工作流自己的路由配置写在 .cursor/skills/devflow/config/workflow.json。它规定小改动走 SOLO → SUMMARY,中大型任务走需求、设计、实现、审查、测试,再到可选的知识沉淀和交付汇总;需求阶段是必要的审批关口,设计、审查和测试则是可手工确认的门禁:

json 复制代码
{
  "version": "2.0",
  "max_stage_failures": 2,
  "max_batch_tasks": 3,
  "required_approval_gates": ["REQUIREMENT"],
  "manual_gates": ["DESIGN", "REVIEW", "TEST"],
  "optional_stages": ["KNOWLEDGE"],
  "routes": {
    "small": ["SOLO", "SUMMARY"],
    "medium": ["REQUIREMENT", "DESIGN", "IMPLEMENT", "REVIEW", "TEST", "KNOWLEDGE", "SUMMARY"],
    "large": ["REQUIREMENT", "DESIGN", "IMPLEMENT", "REVIEW", "TEST", "KNOWLEDGE", "SUMMARY"]
  }
}

这也说明 Local 工作流同样把「先确认边界,再进入后续阶段」写进了配置,而不是只靠口头约定。但这些文件被写进目录,并不等于已经在 Cursor 里跑过 /devflow。要真正执行工作流,还需要打开相应宿主并提供模型凭据;本次没有进行这一步。

四、适用与限制

适合在这些情况下先看 LoopForge:希望把已经验证过的交付步骤(角色分工、脚本检查、人工签字)固化成可重复的 SOP;或者还不必部署平台,只想先把 Local 工作流装进现有的 Cursor / Claude Code / Codex / CodeBuddy。本次的仓库钉选、镜像 digest 核对,以及 loopforge-cli 的 version、editions、plan、隔离目录安装和 doctor,都不需要账号或模型密钥。官方也明确,自托管平台上那条「脚本 + 人工审批」的体验 SOP 可以不带 API Key 试用------只是这条路径本次没有实际跑到。

需要同时看到这些限制:

  • 本机没有 Docker,因此没有启动 ./start.sh,没有创建管理员账号,没有打开 0.0.0.0:8090 的工作台,也没有跑体验项目里的「平台验收 · 脚本与审批」
  • 没有配置任何模型或执行器密钥,没有在 Cursor 或其他宿主里执行 /devflow、/start-devflow,因此没有得到一次真实的需求澄清、代码改动、审查意见或测试报告
  • 没有验证 Main Bot 对话、提交 PR、定时同步 GitHub Issue、运行复盘,以及把改进写回 SOP
  • 官方列出的多种编程 Agent CLI,本次都没有安装,也没有作为执行器调用
  • Local 目前只提供内置 Classic / Portable 工作流;平台 SOP 导出后在本地独立执行,官方说明尚未实现
  • v0.4.0 源码里的 loopforge-cli 版本号是 0.2.3,与 npm 上已发布的 0.2.2 不一致。本次只验证了 0.2.2,没有从源码安装 0.2.3
  • 镜像 digest 是通过读取 GHCR 清单确认的,没有在本机拉取或运行 ghcr.io/tencent/loopforge:0.4.0
  • 本次只在 Linux x86_64 上验证了上述命令,没有测试 Windows / macOS,也没有验证全局安装 npm install --global loopforge-cli
  • 许可证以仓库中的 MIT 为准,第三方组件见 THIRD_PARTY_NOTICES.md

五、小结

LoopForge 把「编码 Agent 负责写和改」和「流程、关口与留痕由工作台编排」分成了两层。平台侧用 Main Bot 对话和可审批 SOP 覆盖团队交付,Local 侧则把内置工作流装进现有助手。本次在 Linux 上浅克隆并钉死了官方仓库 v0.4.0,确认 compose.yaml 中的镜像标签与 Release、GHCR 清单 digest 一致;又在项目目录安装 loopforge-cli 0.2.2,用 plan 看清 Classic / Portable 将写入的文件,并把 Cursor 的 Portable 工作流装进隔离示例目录,doctor 显示资产与安装状态正常。它适合先把交付步骤和人工关口固化下来,但不能单靠这一次冒烟,就当成已经验证过自托管平台,或已经带着编码 Agent 走完一次完整 SOP。如果主要需求是先在本机看清 Local 工作流会写进项目的哪些文件,再决定是否部署平台或配置执行器,这条 CLI 已经够用来把前半段跑起来。

入口再列一次(查询日:2026-11-18,Asia/Shanghai):Tencent/LoopForge、loopforge.cn、中文 README、v0.4.0、loopforge-cli。

相关推荐
小七-七牛开发者5 天前
PACE:代码通过率从 42% 到 97%, 让长程 Agent 在有限 KV Cache 下用好历史 Token
大模型·claude·token·工作流·长程agent
小七-七牛开发者6 天前
周 1 上线 | DSH 喜提原神进场动画,Anthropic 启动 IPO 路演;黄仁勋辞任;微软全球大宕机超 24 小时
ai·大模型·agent·token·工作流·claudecode·ai coding
顾鸟6 天前
ComfyUI 使用 LLaMA-Factory 微调的 Qwen3.5:从模型导出到工作流出图--晨羽算力平台
llama·comfyui·工作流·qwen3.5
VIP_CQCRE9 天前
WorkBuddy 接入 Maestro 后,如何把一句需求变成可验收的视频任务
工作流·ai视频·maestro·mcp·workbuddy
进击的雷神11 天前
我用 second-brain-skills 把 Claude Code 升级成了“第二大脑”:PPT、品牌手册、SOP 一人搞定
ai·claude·ppt·sop
VIP_CQCRE14 天前
视频任务显示‘已提交’之后:别让异步生成变成黑盒
异步任务·工作流·ai视频·mcp
終不似少年遊*17 天前
【安全业务Agent】从场景到编排
python·react.js·ai·langchain·agent·安全架构·工作流
lucas_AI17 天前
腾讯混元 Hy4 正式版:1/8 的价格摸到 Opus 5.5,能看图能开电脑,就差权重没放
腾讯
奈落2418 天前
Codex 并进 ChatGPT 之后,“编程智能体“是变浅了还是变顺了:从官方概览页的功能分工到五家公司开发者反馈,读一次产品化合并的得与失
人工智能·chatgpt·工作流·ai 编程