Looper 代码实现原理:looper.py 编译器如何把 loop.yaml 编译成可执行规格

原创2026-11-01 15:43:311,712 阅读

Looper 代码实现原理:looper.py 编译器如何把 loop.yaml 编译成可执行规格

Looper 是一款为 Claude Code 设计**审阅门禁式智能体循环(agent loop)**的开源工具。本文拆解其脚手架侧编译器 scripts/looper.py 的实现原理:它如何把人类编写的 loop.yaml 意图文件,编译成机器可执行的规格 loop.resolved.json,并顺带渲染出人类可读的 LOOP.md 与 ASCII 流程预览。读懂这套流水线,你就能理解"先设计、后运行"的智能体循环是如何被静态校验、规范化和安全化的。

⚙️ 编译流水线全景:loop.yaml 如何变成可执行规格

Looper 把"设计循环"与"运行循环"彻底分离。looper.py 属于脚手架侧(scaffolding side):它可以探测 CLI、登记调用元数据、编译 loop.yaml、渲染文档,但绝不调用模型 CLI 去做循环工作——这是源码 docstring 里写死的职责边界。

compile 子命令(cmd_compile)的完整流水线如下:

flowchart TD
    A["loop.yaml(人写的意图)"] --> B["load_yaml 容错读取<br/>YAML 语法校验 + BOM 兼容"]
    B --> C["normalize_spec 规范化<br/>校验字段 / 补默认值 / 解析路径"]
    C --> D["loop.resolved.json<br/>可执行规格(确定性输出)"]
    C -. 校验失败 .-> E["looper: error: ...<br/>退出码 2"]
    D --> F["LOOP.md 人类摘要<br/>+ ASCII 流程预览"]
    D --> G["RUN_IN_SESSION.md<br/>会话执行提示词"]
    D --> H["looper lint<br/>设计准则静态检查器"]

looper.py 共提供 5 个子命令,编译是核心:

子命令 作用 源码位置
detect-models 探测已安装的模型 CLI(claude / codex / gemini / llm / ollama) scripts/looper.py
register-model 登记自定义模型调用元数据(拒绝密钥写入) scripts/looper.py
compile 编译 loop.yaml → loop.resolved.json scripts/looper.py
lint 把设计准则变成静态检查器 scripts/looper.py
session-prompt 从已编译规格渲染会话执行提示词 scripts/looper.py

📖 输入与输出:loop.yaml 和 loop.resolved.json 是什么

输入 loop.yaml 是一份"意图声明",用人类友好的 YAML 描述循环的全部要素:目标、上下文来源、验证标准、评审委员会(council)、两道门禁(plan gate / delivery gate)、循环控制与预算、隐私出口等。以示例 examples/ai-workflow-mapping/loop.yaml 为例,核心部分长这样:

goal:
  statement: >
    Produce an agent workflow map ...
  verification:
    - id: required-sections
      type: programmatic
      check: ["python", "scripts/check-loop-doc.py", "loop-workspace/delivery-1.md"]
      expect: exit_zero
    - id: covers-goal
      type: judge
      rubric: >
        Every part of the goal statement is addressed ...

host:
  cli: codex
  invoke: ["codex", "exec", "--model", "gpt-5"]

输出 loop.resolved.json 则是"可执行规格":所有字段已校验、所有默认值已补全、所有引用已解析成查找表。完整示例见 examples/ai-workflow-mapping/loop.resolved.json。它的结构契约由两份 JSON Schema 定义:

🚀 第一步:读取与容错

编译器入口是 load_yaml,三个设计细节值得注意:

  1. 懒加载 PyYAML:只在真正需要时才 import yaml,缺失时给出清晰的安装指引而不是堆栈报错;
  2. utf-8-sig 编码:兼容 Windows 编辑器留下的 BOM 头,跨平台零摩擦;
  3. 顶层必须是 mapping:YAML 语法合法但顶层是列表/标量,会直接报 must contain a YAML mapping 错误。

🏗️ 核心步骤:normalize_spec 如何把意图"规范化"

cmd_compile 的心脏是 normalize_spec(约 170 行),它一次性完成三件事:结构校验 → 默认值补全 → 语义解析。任何一步失败都抛出 LooperError,最终以 looper: error: ... 打印到 stderr 并返回退出码 2——保证坏规格永远进不了运行阶段。

版本门禁与目标校验

version 必须等于 1(向前兼容的钩子);goal.statement 与 goal.definition_of_done 为必填非空字符串——"目标"和"完成的定义"缺一不可,这正是 Looper "先设计后运行"理念的代码化。

context_sources:file 与 cmd 二选一

每个上下文来源必须恰好声明 file 或 cmd 之一(normalize_spec):

  • file 走 validate_relative_path:禁止绝对路径、禁止 .. 段——上下文只能取自循环目录内部,天然形成路径沙箱;
  • cmd 经 normalize_argv 规范化为 argv 数组,timeout_sec 默认 60 秒。

verification:三种类型的验证标准

criteria_by_id 对 goal.verification 中的每条标准做类型分发,这是"程序化优先、评审次之、人工兜底"验证哲学的落点:

类型 必填字段 编译器行为
programmatic check、expect check 字符串经 shlex.split 规范化为 argv 数组;timeout_sec 默认 300;expect 限为 exit_zero / exit_nonzero / stdout_contains 三选一
judge rubric 必须是字符串,供评审模型按评分标准打分
human prompt 人类签核提示词

同时强制 id 非空且全局唯一,为后续的查找表构建和门禁引用打基础。

host 与 council:模型调用元数据

  • host(干活的模型):cli 必填,invoke 规范化为 argv 数组,timeout_sec 默认 600;
  • council(评审委员会):validate_member 要求每个成员有 id、role(reviewer 或 judge)、cli,并自动补默认值——scope 默认 [plan, delivery],local 默认为"cli 是 ollama"(本地模型不触发跨厂商隐私审查)。

gates:门禁引用完整性检查

validate_gate 对 plan_gate 与 delivery_gate 做交叉引用校验:

  • verdict_policy 限为 revise_until_clean(改到干净为止)或 fixed_passes(固定通过轮数);
  • criteria 里的每个 id 必须已在 verification 中定义;members 里的每个 id 必须已是 council 成员;
  • 若策略是 revise_until_clean,verdict_source 必须是角色为 judge 的成员(且必须列在 members 里),或者是 human——"reviewer 不能给自己打分"被写进了编译器。

loop_control 与其余区块的默认值补全

normalize_spec 还负责"补全即安全":budget.wall_clock_min 默认 30、no_progress 默认"卡住 2 轮即 stop"并附三条停滞信号、execution.mode 限三种模式、observability 默认 state.json + run-log.md、workspace.layout 会自动把状态文件与运行日志并入布局(normalize_spec)、privacy.egress 默认附带 .env、secrets/** 等脱敏 glob。

🔍 查找表生成:可执行规格的关键增量

编译产物相比源文件多出两个按 id 索引的字典——这是"编译"二字的实质:

"criteria_by_id": { "required-sections": { ... }, "covers-goal": { ... } },
"council_by_id":  { "reviewer-1": { ... } }

运行器(runner)无需再做线性扫描,gate.criteria<a href="https://link.gitcode.com/i/766f9aeba646b4e54f4038532cc5f6dc" target="_blank">0] 一个下标就能取到完整标准定义。这两个键连同 compiled_at(UTC 时间戳)和 source(源文件路径)一起被注入([normalize_spec),正是 loop.resolved.v1.schema.json 强制要求的四个字段。

输出阶段同样讲究确定性:write_json 使用 sort_keys=True + 固定缩进,write_text_lf 强制 LF 换行——同一份 loop.yaml 在任何平台编译出的产物字节级一致,可以像代码一样做 diff 审查。

🖨️ 渲染产物:LOOP.md、ASCII 流程预览与 RUN_IN_SESSION.md

编译不只是输出 JSON。compile 还可顺带渲染两份人类可读产物:

  1. LOOP.md——render_loop 生成目标、验证标准、委员会、门禁、预算的摘要文档,并嵌入 render_ascii_diagram 动态拼出的终端友好流程图。示例产物见 examples/ai-workflow-mapping/LOOP.md:
+--------------------------------+
| 1. Goal + context              |
| read sources                   |
+--------------------------------+
               |
               v
+--------------------------------+
| 2. Draft plan.md               |
| state -> state.json            |
+--------------------------------+
               |
               v
+--------------------------------+
| 3. Plan gate                   |
| verdict: reviewer-1            |
+--------------------------------+
               | needs work -> revise <= 3 -> step 2
  1. RUN_IN_SESSION.md——render_session_prompt 把已编译规格"翻译"成 12 步操作员指令,告诉当前会话从哪一步开始、何时写 state.json、何时追加 run-log.md、预算不够时如何停下询问。这是"会话内运行"这条默认执行路径的驱动文件。

两者共享同一个输入(resolved 规格),保证了机器规格与人类文档永不漂移。

✅ looper lint:把设计准则变成静态检查器

lint_spec 是本文最值得学习的模式:Looper 把references/ 目录下的设计准则(验证、委员会、控制三份 rubric)直接固化成约 22 条静态反模式检查。

严重级契约(源码注释中明确定义,scripts/looper.py):

  • error——规格在运行时的行为会与阅读时的理解不符,必须修复;
  • warning——设计辅导,能跑但有已知陷阱。

几条典型检查逻辑:

检查项 级别 抓的是什么
judge-criterion-unreachable error fixed_passes 策略下列了 judge 标准——评审器永远不会运行,评分标准形同虚设(scripts/looper.py)
unscoped-egress error 非本地评审成员没有 privacy.egress 声明——项目内容将未经声明地离开本机
all-vibe-verification warning 全部验证标准都是 judge/human,没有一个程序化检查能客观拦截
same-family-judge warning judge 与 host 同厂商同模型家族——自批盲区
unreferenced-council-member warning 成员没被任何门禁引用——死配置,永远不会被调用
unresolved-placeholders warning 模板 {{TOKEN}} 占位符未填(PLACEHOLDER_PATTERN),防止半成品模板被误运行

一个精妙的实现细节:normalize_spec 会原地修改输入(把字符串 check 重写成 argv 列表),所以 cmd_lint 先对原始 spec 做 deepcopy,让 shell-string-check 这类需要"编译前形态"的检查能看到真实形状。

退出码契约(CI 友好):0 = 无发现;1 = 有 error(或 --strict 下任何 warning);2 = 规格编译失败。可以直接写进 CI 对 PR 里的 loop.yaml 把关,就像 lint 代码一样。

🔒 安全设计:拒绝密钥、路径沙箱与确定性输出

looper.py 的安全意识贯穿编译全程:

  • 密钥零落盘:SECRET_PATTERNS 预置了 5 组正则(sk-、ghp_、Slack xox、AWS AKIA、以及 api-key/token/secret/password: 键值对形态),register-model 登记调用元数据前先过 reject_secret_material——"模型注册表永远不存凭证"被做成硬性拦截,而不是文档约定;
  • 路径沙箱:context_sources.file 与 workspace.dir 只接受循环目录内的相对路径,杜绝规格文件指到仓库外;
  • 脱敏默认值:任何 privacy.egress 条目自动获得 .env、.env.*、secrets/**、**/*.key 的默认脱敏 glob(DEFAULT_REDACTIONS);
  • 确定性输出:排序键 + LF 换行,产物可审计、可 diff。

🧪 动手编译一次:命令与产物对照

在仓库内对示例规格执行编译(只读操作,产物落在临时路径):

python3 scripts/looper.py compile examples/ai-workflow-mapping/loop.yaml \
  --out /tmp/loop.resolved.json \
  --render /tmp/LOOP.md

编译成功后输出 Wrote /tmp/loop.resolved.json,得到与 examples/ai-workflow-mapping/loop.resolved.json 同构的规格:criteria_by_id 里 required-sections 的 check 已是 argv 数组、timeout_sec 已补为 300;council_by_id 里 reviewer-1 的 scope 与 timeout_sec 均已显式化。

再跑一次 lint 验证设计质量:

python3 scripts/looper.py lint examples/ai-workflow-mapping/loop.yaml

📁 关键源码文件索引

文件 说明
scripts/looper.py 编译器主体:compile / lint / 渲染
templates/loop.yaml 空白模板:一份 loop.yaml 的全部字段
templates/loops/ 5 个预设计模板(code-review、bug-hunt 等)
schemas/loop.v1.schema.json 输入规格的结构契约
schemas/loop.resolved.v1.schema.json 编译产物的结构契约
examples/ai-workflow-mapping/loop.yaml / loop.resolved.json 输入 → 输出对照示例
references/verification-rubric.md、references/control-rubric.md、references/council-rubric.md 被 lint 固化的三份设计准则
RUNNER-CONTRACT.md 运行器如何消费编译产物的契约
conformance/check_runner.py 程序化标准(programmatic check)的符合性检查

小结:这套"编译器"到底编译了什么

looper.py 编译的不是语法,而是意图与行为的一致性:

  1. 读——容错加载 YAML,坏语法在门口就被拦下;
  2. 校——引用完整性、类型分派、路径沙箱,让"你以为的规格"必须等于"运行时真实生效的规格";
  3. 补——所有默认值显式写回产物,消除"未写即未知"的隐式行为;
  4. 译——JSON 规格给运行器,LOOP.md + ASCII 预览给人,RUN_IN_SESSION.md 给会话,三份产物同源生成、永不漂移;
  5. 审——lint 把设计准则变成可进 CI 的静态检查器,用退出码 0/1/2 与工具链对话。

先设计、后运行,设计本身可校验、可版本化、可静态审查——这就是 Looper 编译器留给智能体循环工程的方法论答案。

登录后查看全文
looper