cobusgreyling/loop-engineering

Loop Engineering – 设计、运行和评分自主 AI 代理循环

是什么 – 一个由 CLI 驱动的框架，帮助您将手动提示替换为可重复的“循环”，该循环能发现工作、将任务交给基于 LLM 的代理（Claude、Grok、Codex、Opencode 等），验证输出并记录状态。它自带一个预设的 模式 库（每日排查、PR 哺育者、CI 清扫者等），可轻松接入任何代码仓库，并在本地或 GitHub Actions 中运行。

为何重要 – 构建可靠的 AI 代理流水线很困难：您需要决定循环何时运行、如何评分自身工作，以及如何控制成本。Loop Engineering 提供结构化检查清单、STATE.md 文件以追踪循环的知识状态，以及 L1–L3 的评分系统，帮助您判断何时可从“仅报告”过渡到完全无人值守的自动化。

---

核心概念

概念	说明
模式	预定义的工作流（例如 daily-triage），指定执行频率、初始安全级别（L1–L3）和预期成本。
工具	代理所用的基础 LLM（默认为 claude，也支持 grok、codex、opencode）。
STATE.md	一个 Markdown 文件，用于持久化循环的学习状态；CLI 会在首次运行时引导您创建它。
循环就绪评分	一个数值评分，反映循环设计的完善程度（最近的运行权重更高）。
级别	L1 = 仅报告，L2 = 辅助，L3 = 无人值守。必须在连续一周验证正确后才能升级。

---

快速入门（5 分钟）

# 在当前仓库初始化一个循环
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# 运行健康检查
npx @cobusgreyling/loop doctor .

# 查看所选模式的成本估算
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

如果省略 --tool，CLI 默认使用 Claude。

该命令会创建一个 STATE.md 文件和一组配置文件，描述循环将监控的内容（问题、CI、依赖项等）。第一周结束后，您将获得一个 L1 报告，显示循环本应执行的操作。当验证器持续正确时，您可以提升级别，让循环自动执行。

---

主要模式（任选一个开始）

模式	执行频率	第一周输出	典型成本
每日排查	1 天 – 2 小时	仓库健康状况的 L1 报告	低
PR 哺育者	5–15 分钟	新 PR 的 L1 监控	高
CI 清扫者	5–15 分钟	L2 谨慎修复不稳定的 CI	非常高
依赖项清扫者	6 小时 – 1 天	L2 仅限补丁更新	中
变更日志起草者	1 天 或 标签创建时	L1 变更日志草稿	低
合并后清理	1 天 – 6 小时	L1 非高峰时段的维护	低
问题排查	2 小时 – 1 天	L1 仅建议处理问题	低

每个模式位于 patterns/ 目录中，包含 Markdown 描述和 patterns/registry.yaml 中的 YAML 条目。互动式选择器可在展示网站上使用。

---

示例工作流

• Claude Code – 使用 Claude 生成代码变更，并包含 VS Code 插件。
• Grok 每日排查 – 在新仓库上运行 Grok 驱动的排查循环。
• GitHub Actions 轻量循环 – 仅需一个工作流文件即可添加到仓库，无需额外 STATE.md。

所有示例均在 examples/ 目录中，可使用相同的 CLI 命令运行。

---

安全与操作指南

• 失败模式 – 在 docs/failure-modes.md 中记录（例如：令牌使用失控、幻觉修复）。
• 反模式 – 参见 docs/anti-patterns.md，了解过度自动化而无验证等常见陷阱。
• 安全检查清单 – docs/loop-design-checklist.md 引导您在升级到更高级别前验证循环。
• 故事 – 真实世界中的成功与失败案例收集在 stories/ 中，帮助您从社区经验中学习。

该项目强调，循环会放大人类判断；无人值守的循环可能造成高成本错误，因此 L1→L2→L3 的逐步推进是强制性的。

---

社区与贡献

• 采用者列表 – 通过“add-adopter”问题模板添加您的项目。
• 新手友好问题 – 标记为适合初学者；维护者承诺 48 小时内响应。
• 配套仓库 – 可选扩展如 memory-engineering、outerloop 等，适用于循环证明可靠后的后续阶段。

---

许可证

MIT – 可自由使用、修改和分发。

---

核心要点 – Loop Engineering 是一个实用的、基于模式的工具包，可将 LLM 代理转化为围绕代码库的可重复、可审计的自动化循环。它提供清晰的入门路径、安全支撑结构和评分系统，帮助您判断何时可信任循环自主行动。