01项目定位POSITIONING
Minimal Agent Loop 是一个教学项目，不是框架也不是产品。它回答一个具体问题：把"Agent"这个词剥到最薄，剩下的工程骨架长什么样。答案是近百行的循环，加上四样不能省的东西——工具权限边界、逐步 trace、失败重试与熔断、独立于生成的验证器。
它服务两类读者：想入门的人可以克隆即跑（离线确定性模式不需要任何 API key）；想检验本站方法论的人可以对照 F-001 的循环解剖和 N-010 的闭环清单，逐条在代码里找到对应物。
02它演示什么WHAT IT SHOWS
一个完整闭环：任务提交（带完成标准的 JSON）→ 循环决策 → 受审计的工具执行 → trace 逐步留痕 → 失败重试与熔断 → 产物落盘 → 独立验证器复核。每次运行产出一个独立目录，工作区、轨迹、终态俱全。
决策器可插拔是刻意的教学设计：规则决策器与 LLM 决策器共用同一接口。循环结构不变、决策来源可换——这正是"Agent 的骨架是循环和边界，模型只是决策器"这个判断的可运行证明。
03已实现能力IMPLEMENTED
- 观察→决策→执行→更新的完整循环，含步数上限与连续失败熔断。
- 工具注册表：三个文件工具，路径全部限制在 workspace 内，越界拒绝。
- trace.jsonl 逐步记录决策与执行，成功失败都留痕。
- 工具失败自动重试一次，重试仍败交还循环处理。
- 独立验证器：不问 Agent，自己重新核对完成标准。
- 规则决策器（离线）与 OpenAI 兼容 LLM 决策器（可选）。
- 五个单元测试覆盖闭环、留痕、边界、上限、熔断。
04不声称什么NOT CLAIMED
不声称是通用规划器——规则决策器只会解示例任务这一类；不声称生产可用——没有权限分级、人工审核门、成本控制和可观测性层；不涉及多 Agent、并发与队列。它是概念的可运行最小证明，不是可交付系统。
05可验证方式HOW TO VERIFY
- 克隆仓库，跑一次任务。`python3 run.py tasks/count-lines.json`，无需任何配置。
- 打开 trace。runs/ 目录下的 trace.jsonl 逐步可读，对照 README 的循环解剖。
- 跑独立验证。`python3 verify.py runs/<目录>`——它自己重新数一遍，不信 Agent 的自我宣布。
- 跑测试。`python3 -m unittest discover -s tests`，五个测试对应五个结构问题。
- 试着攻击边界。让工具写 `../` 外的路径，看它怎么拒绝。
06边界声明BOUNDARY
本项目为纯教学用途，基于公开知识与标准库编写，不包含任何来自任何公司的内部代码、架构或数据。仓库刻意不提供 shell 与网络工具——工具清单即权力边界，这本身就是它要教的第一课。