fedora-ai
06f2f53326
5-step closed-loop methodology derived from session 2026-06-19: 1. Digest, don't copy — extract generic patterns, drop vendor lock-in 2. Cold-review with sub-agent — same session can't review itself 3. Implement as library + integrations + dashboard 4. Test real crash recovery, not just happy path 5. Deploy, verify, close the loop Includes: - loop-engineering-methodology.md: full reference (also on NAS) - agents/: plan-reviewer and log-diagnostician templates Co-Authored-By: Claude <noreply@anthropic.com>
73 lines
3 KiB
Markdown
73 lines
3 KiB
Markdown
# 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
|
||
```
|
