
把一个需求丢给编码 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。