loop-engineering/README.md

Loop Engineering 方法论 — 从外部文章到可工作系统的落地流程

2026-06-19, ailab. 本次会话完整走通，记录为可复用模式。

流程（5 步，闭环比 open-loop 重要）

1. 消化，不照抄

外部文章给出概念框架（loop / skill / orchestrator / review loop），但实现必须对接到现有技术栈。

• Inngest → 不需要他们的云服务。140 行 Python + JSON 文件就是 orchestrator。
• Quant → IC/ICIR/half-life 对 16 条查询的 eval 不适用。先扩容数据集。
• Sub-agent → 不需要 Opus/Haiku/Sonnet 模型分层。我们有 qwen3.6:27b + DeepSeek。

原则：提取通用模式，丢掉厂商绑定。

2. 设计 → 用 sub-agent 冷审查

写的设计文档自己审不了——同一个 session 建起来的计划，AI 天然偏向通过。

• 把设计文档交给 plan-reviewer agent（read-only, 独立上下文）
• 关键发现：eval 的 check_primary_collection() 恒真。自己审不出来。
• "the same session that built it can't review it honestly" 是真的。

原则：设计完成后，必须过 sub-agent 冷审。每次。

3. 实现 → 三件套（库 + 集成 + 仪表盘）

• 通用库：loop_state.py（140 行，CLI: save/last/get/clear/show）
• 集成：每个脚本接 checkpoint，保护最昂贵的步骤
  • service-guardian v3: per-phase checkpoint
  • handoff-compress v3: Ollama 输出 checkpoint
  • workspace-audit v2: per-workspace checkpoint
• 仪表盘：loop-status（一眼看清所有 loop 的运行状态）

原则：一个通用库 + N 个集成 + 1 个仪表盘。不搞每个脚本手写 checkpoint 逻辑。

4. 测试 → 模拟真实崩溃

不是 dry-run。不是 happy path。是：

• 造 checkpoint，删 phase 文件，跑恢复，验跳过逻辑
• 造 compressed checkpoint，跑恢复，验 Ollama 调用被跳过
• 每个脚本至少走一次 crash→recover→success 循环

原则：崩溃恢复的正确性靠测试验证，不靠代码审查。

5. 部署 → 修到验证通过

• 发现 _collection 缺失 → 修 query() → 发现 query_hybrid() 也要修 → scp 部署 → 重启 → 12 个 primary_collection 检查添加 → 30/30 重新验证
• 不满足于 "找到问题了，记 TODO"

原则：链不要断。发现→分析→修复→部署→验证，走完。

反模式（不要做的）

• 统计方法过度：16 条数据不需要 ICIR 和 half-life
• 手动造 checkpoint 忘了保留 phase 文件：恢复需要中间产物
• 只 dry-run 不 crash-test：dry-run 测不了恢复逻辑

适用条件

• 多步 cron 脚本，任一步可能因 Ollama 超时/SSH 断连/API 故障而失败
• 有 LLM 调用的工作流（token 成本值得保护）
• 按需调用的 skill（storm-research）优先级低于定时 cron

核心文件

~/bin/loop_state.py          # 通用 checkpoint 库
~/bin/loop-status            # 全集群 loop 仪表盘
~/.claude/agents/plan-reviewer.md   # 冷审查 sub-agent
~/.claude/agents/log-diagnostician.md  # 廉价日志分析 sub-agent