EYwALINK logo EYWA·LINK
EN
开源 · Loop Engineering Factory

从架构到可交付软件，在一个受治理的循环里

独立编码代理出代码快——但不解释过程。Loop Engineering Factory 保留一个编码代理（BUILD 委托给 OpenHands），并将其包进一个 LangGraph 状态机，让过程 可见、可控、自我改进——你设计的架构由此变成已验证、已交付的软件，跑在你自己的基础设施上，人仍留在审批回路里。

为什么包一层

裸代理给不了你的可见性与控制

工厂不是 OpenHands 的对手。它是围绕它的受治理、可观测、可暂停工作流——差别在于代理没有的那部分。

维度 独立代理 Loop Engineering Factory
可见性 流式聊天文本；结果在最后才出现 每个阶段都发出结构化产物与审计记录，实时推送到仪表盘
控制 一次性或临时引导；没有结构化暂停点 确定性的人机协同 interrupt() 关口：审查、带反馈驳回、暂停或中止
状态 临时的——代理上下文随会话消亡 AsyncSqliteSaver 为每个阶段做检查点；任意关口都可恢复
验证 代理自证它完成了工作 确定性 VERIFY 关口运行可机器校验的验收测试——绝不靠"我说了算"
改进 跨运行无改进 REFLECT 将模式存入 ChromaDB；下一轮周期起点更聪明

流水线

九个阶段，两种关口

DISCOVER → DEFINE → PLAN → ARCH_REVIEW → BUILD → SEED_DATA → VERIFY → SHIP → REFLECT。 两处人机协同暂停（DISCOVER、ARCH_REVIEW）与一处确定性关口（VERIFY）决定交付。

1

DISCOVER

HIL ×2

初始化与结构化访谈。若存在 ArcKit 预扫描结果，则按 schema 校验的产物自动填充项目字段；两处人机协同暂停（项目设置 + 访谈）。

2

DEFINE

生成规格说明与 API 契约。两次 LLM 调用（source-driven + api-design）经 asyncio.gather() 并行执行；ArcKit 咨询上下文同时附加到两者。

3

PLAN

实施计划、疑点消解与四张架构图。架构图并行生成——每个用例额外一次 LLM 调用。

4

ARCH_REVIEW

HIL ×1

人工审查规格、计划与架构图。通过 → BUILD；驳回 → 带反馈回到 PLAN。

5

BUILD

gates

经 Gateway API 委托给 OpenHands 编码代理；写入机器可读的 build_report.json 清单。代理不可达时回退到内联 LangGraph 子图。

6

SEED_DATA

加载测试夹具。存在 ArcKit 数据模型时走模型驱动；否则为直通占位。模型驱动路径不调用 LLM。

7

VERIFY

gate

确定性关口。运行从规格解析出的可机器校验验收测试；置 verify_status = pass 或 fail。LLM 评述仅 advisory。

8

SHIP

部署打包并推进到 REFLECT：可观测性、上线清单、版本标记。

9

REFLECT

自我改进：将本周期指标与习得模式写入 ChromaDB，并为下一轮输出结构化的配置/护栏 diff。

BUILD 阶段

委托构建——有底线，不靠猜

BUILD 经 Gateway API 交给 OpenHands 编码代理。代理必须交回机器可读的 build_report.json 清单。清单缺失或格式错误是硬失败—— 工厂绝不用自由文本去猜。代理不可达或超时时，由内联 LangGraph 子图接管。

步骤 实现 说明
健康检查 GET /health 任何失败都路由到内联回退
创建会话 POST /api/conversations OpenHands Gateway API（容器 :8000，宿主机 :43005）
轮询 GET /api/conversations/{id} 5s 间隔、1h 超时；超时则走内联回退
解析清单 build_report.json 推导状态 pass / partial / fail；清单缺失或非法是硬失败，而非猜测
质量关口 edges.py 的 route_phase() 安全发现、UAT 通过率、评审轮次决定前向路由

重试预算有界——至多两次 BUILD → BUILD 循环，之后运行停到 ERROR。它从不靠"放弃"跳过 SHIP。

决策关口

VERIFY 是确定性的——绝不靠"我说了算"交付

VERIFY 是质量关口，它运行从规格解析出的可机器校验验收测试——而非模型写给自己的评语。LLM 评述仅 advisory；决策由测试做出。

通过 → SHIP

所有验收检查通过 → 运行推进到 SHIP 与 REFLECT。

失败 → BUILD（有界）

某项检查失败则带失败的测试 id 回到 BUILD。至多两次循环。

预算耗尽 → ERROR

超过循环预算则运行停到 ERROR。它不会悄悄交付坏代码。

自我改进

REFLECT 让每轮起点更聪明

REFLECT 将本周期指标与习得模式写入 ChromaDB，并为下一轮输出结构化的配置与护栏 diff。低风险变更自动应用；涉及安全的须人工确认。 循环在学习，而非只是重复。

护栏

逐阶段强制的质量阈值

  • min_spec_confidence ≥ 0.9 DEFINE
  • max_arch_uncertainty ≤ 0.8 PLAN
  • max_security_findings = 0 BUILD
  • max_review_revisions ≤ 2 BUILD
  • min_uat_pass_rate ≥ 0.95 VERIFY

安全敏感关键词（auth、payment、credential、secret 等）强制人工审批——见 config/guardrails.yaml。

以构造取信

LLM 失败时会怎样

自我改进的循环，好坏取决于它的失败处理。LEF 把 LLM 错误当作类型化、有界、且对工作流非致命的。

类型化错误，不用哨兵值

LLM 失败抛出 LLMError（致命）或 _LLMTimeout（可重试）——从不出现泄露进状态的魔数。

有界指数退避

瞬时 5xx、超时与连接错误按退避重试（base 1.0s、cap 15s、至多 2 次）。401/403/404 与模型未故障不重试。

优雅降级

致命 LLM 错误耗尽后，调用返回 None——活动路径节点将 None 强制转为带告警的空结果，而非让工作流崩溃。

组件总览

各部分在哪里

组件 职责 配置键
main.py CLI 入口——无人值守自动通过 workflow.auto_approve
frontend/backend/app.py FastAPI 后端——工作流 API :48011 services.loop_api.*
graph/main.py LangGraph StateGraph 定义（9 个阶段） workflow.hil_mode
graph/edges.py 经 route_phase() 的条件路由——关口、循环上限、前向路径 —
graph/executor.py WorkflowRunner——带 HIL 暂停地编排执行 —
graph/checkpointer.py AsyncSqliteSaver——任意关口恢复运行 —
tools/llm.py 带界重试与上下文压缩的 LLM 调度 services.llm.*
tools/loader.py 技能注册表发现与热重载 workflow.skill_registry_path
feedback/chroma_client.py ChromaDB 模式存取 services.chroma.*
service/evaluator.py LLM-as-judge 对阶段产物打分 → Phoenix UI services.otel.*

所有外部参数集中在一个三级优先级下——环境变量、然后 config/config.yaml、再内置默认值。生产代码零硬编码 URL 或端口。

快速上手

三种运行方式

一个 Docker Compose 栈、一个 OpenAI 兼容 LLM 端点、一个编码代理。完整周期约 25–40 次 LLM 调用。

CLI（无人值守，自动通过）

# 构建并启动完整流水线，无人工介入
docker compose up -d --build loop
docker compose logs -f loop
curl http://localhost:48081/health

Web UI（人机协同）

# 同一套栈，交互式仪表盘 + HIL 关口
docker compose up -d --build loop
# 前端    → http://localhost:4080
# API     → http://localhost:48011
# 健康    → http://localhost:48081

指向你的 LLM

# 任何 OpenAI 兼容端点（例如本地 SGLang 模型）
export LLM_BASE_URL="http://host.docker.internal:8080/v1"
export LLM_MODEL="Qwen3.8-27B"
export LOG_LEVEL="info"

一个能读、能暂停、能证明的构建循环

Loop Engineering Factory 是开源的——状态机、关口、代理交接与自我改进循环全部可检视。无供应商锁定，跑在你自己的基础设施上。

在 GitHub 上看 Loop Engineering Factory 可执行企业架构 →