Looper 代码实现原理:looper.py 编译器如何把 loop.yaml 编译成可执行规格
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 定义:
- 输入侧:schemas/loop.v1.schema.json
- 编译产物侧:schemas/loop.resolved.v1.schema.json(强制要求
compiled_at、source、criteria_by_id、council_by_id四个编译期注入字段)
🚀 第一步:读取与容错
编译器入口是 load_yaml,三个设计细节值得注意:
- 懒加载 PyYAML:只在真正需要时才
import yaml,缺失时给出清晰的安装指引而不是堆栈报错; utf-8-sig编码:兼容 Windows 编辑器留下的 BOM 头,跨平台零摩擦;- 顶层必须是 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 还可顺带渲染两份人类可读产物:
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
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_、Slackxox、AWSAKIA、以及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 编译的不是语法,而是意图与行为的一致性:
- 读——容错加载 YAML,坏语法在门口就被拦下;
- 校——引用完整性、类型分派、路径沙箱,让"你以为的规格"必须等于"运行时真实生效的规格";
- 补——所有默认值显式写回产物,消除"未写即未知"的隐式行为;
- 译——JSON 规格给运行器,
LOOP.md+ ASCII 预览给人,RUN_IN_SESSION.md给会话,三份产物同源生成、永不漂移; - 审——
lint把设计准则变成可进 CI 的静态检查器,用退出码 0/1/2 与工具链对话。
先设计、后运行,设计本身可校验、可版本化、可静态审查——这就是 Looper 编译器留给智能体循环工程的方法论答案。