agent-loop

平台无关的 agent 控制环：默认继续，但不允许未 review 的计划、旧 revision 或未验证证据继续驱动任务。

Goal → Plan → Human Review
                   │
                   ▼
     ┌──► worker   ：Run → Verify（锁定 verifier）
     │                     │ VERIFIED
     │ continue            ▼
     └─── reviewer ：读落盘证据 → 纠正结论 → 改写下一个 task
                           │
                           └─ ask_human / stop ─► human

     human 纠偏随时可 pause；plan revision 不一致时拒绝继续

worker + reviewer

像实验室里的研究员和导师：研究员把实验做完、数据落盘；导师不看过程，只看数据，决定下一个实验做什么。 导师拿不准方向时，才去找出资人（human）。

角色	推荐配置	在哪跑	负责	不做
worker	Opus 5	Cursor agent	执行、自修、重试、跑 verifier	给自己的下一步拍板
reviewer	gpt-6	Codex CLI（经 WSL）	核对结论、改写下一个 task、给出 continue / ask_human / stop	改代码、跑实验
调度	Harness 状态机	stop hook + runner	决定什么时候叫谁	任何判断
human	项目 owner	—	定 Goal、批 plan、回答 ask_human	—

模型不写死，原则是 reviewer 强于 worker。reviewer 是项目里的一条命令，init 前写进 .agent-loop/reviewer.json；不写这个文件，就是只有 worker 的单 agent 模式。.harness/review/prompt.md 由 Harness 在每次 review 前按当前项目生成，不需要自己写；下面这份配置各项目通用：

{
  "argv": ["wsl.exe", "--", "bash", "-lc",
           "codex exec -s workspace-write 'Read .harness/review/prompt.md and follow it exactly.'"],
  "timeout_seconds": 1800
}

一轮交接：verify 通过 → stop hook 要 worker 跑 agent-loop-harness review → reviewer 只读证据， 改写 task.md 并写决策 → continue 时 worker 只能以事实错误异议一次，否则直接做下一个 task。

人不在电脑前

需要 human 的检查点可以经 tools/pager（pip install -e tools/pager）发到手机：plan 待批、reviewer 选 ask_human、reviewer 连续失败、预算用尽时，worker 不停下，而是跑 agent-loop-harness page 发邮件并挂着等回复； reviewer 选 stop 时只发通知。init 前写 .agent-loop/pager.json：

{"argv": ["python", "-m", "pager"], "project": "my-project", "address": "you@example.com"}

回复 OK 批准当前检查点，DO <文字> 作为 human 纠偏交给 worker（改 plan 后再发一次待批）， NO / STOP 停下。pager 不能唤醒已退出的 agent，所以电脑、网络和 agent 会话都要保持在线。

架构

核心分三层：

• Stable Kernel：状态、事件、转移和 guard；
• Policies：planning、task、experiment、memory、stop；
• Adapters：platform codecs、runner、verifier、git 与 execution journal。

完整边界与扩展规则见 design.md。

安装

git clone https://github.com/ZJLi2013/agent-loop.git
cd agent-loop
python -m pip install -e .

核心 CLI 与项目 runtime 不依赖宿主。当前仓库另提供 Cursor enforced adapter：

powershell -ExecutionPolicy Bypass -File scripts/sync-to-cursor.ps1

脚本幂等，将 rules、skills、Harness 与 Cursor codec 链接到 ~/.cursor/。完成后重启 Cursor； 仓库移动、skill 增删改名后重跑。

Cursor adapter 会创建 user-level junction，并让本地 Python hook 在所有 workspace 运行。 请先审阅并固定可信 commit；完整边界见 SECURITY.md。

卸载只移除 agent-loop 自己的 links 与 hook entries，不删除备份：

powershell -ExecutionPolicy Bypass -File scripts/uninstall-from-cursor.ps1

支持范围

Component	Status
Platform-neutral Harness CLI	Python 3.11 / 3.13; Windows and Ubuntu CI tested
Cursor enforced adapter	Windows + PowerShell 5.1 installer supported
macOS/Linux installer	Roadmap；当前需手动 symlink

新项目

初始化项目自己的 memory：

mkdir .agent-loop\memory
$agentLoopRepo = "C:\path\to\agent-loop"
copy "$agentLoopRepo\skills\agent-memory\templates\*.md" .agent-loop\memory\

然后直接描述 Goal。agent 会：

1. 先写一份 plan document 与最近 1–2 个 📝 proposed task；
2. 等待 approve / revise / continue automatically；
3. 每次只推进一个未验证假设；
4. 用独立 verifier 决定是否完成。

要启用 Harness，plan document 写：

Plan Revision: 1
Plan Review: approved

task.md 的 rev 列绑定同一个 r1，然后初始化：

agent-loop-harness init --task t1 --plan-doc docs\plan.md `
  --timeout 300 --max-attempts 3 -- python -m pytest -q

运行中需要人工纠偏：

agent-loop-harness pause --require-revision --reason "Goal changed"
# 更新 plan revision / review 与 task rN
agent-loop-harness resume

默认每 3 次 action、60 分钟、失败或 context compact 后触发 Goal Review；用 goal-review --decision continue|replan|stop --evidence "<结论>" 处理。

要让 reviewer 接管 task 边界，init 前放好 .agent-loop/reviewer.json（见上文「worker + reviewer」）。

最小可运行样例见 examples/minimal-project/。

边界

• Harness 只硬控显式交给 runner 的命令；其它 host tool call 仍由宿主管理。
• task.md 是 backlog 唯一真相源；.harness/ 只存有界 runtime evidence。
• .agent-loop/task.md 与 .agent-loop/memory/ 是项目本地 runtime；旧 .cursor/ 路径只读兼容。
• checkpoint / rollback 复用 git，不自动覆盖用户工作树。
• 没有 lifecycle hooks 的宿主属于 portable mode，不能强制 completion gate；外部进程掌握 agent 生命周期时可评估 BOUND。

文档

文档	内容
design.md	当前架构、状态机、归属与扩展规则
study/harness.md	runner、journal、Verifier 与边界
study/planning-contract.md	渐进计划、review 与人工纠偏
study/memory.md	facts / episodes / lessons 的检索设计
study/multi_agent.md	现有 multi-agent loop 对比与 worker / reviewer 分工
case_study/robojev-nox.md	一天 11 个 task 边界的跨模型纠偏记录
skills/README.md	Policy 索引与唯一 owner
CONTRIBUTING.md	贡献流程、新 feature 准入与测试
AI_POLICY.md	AI-assisted contribution 披露
SECURITY.md	安全边界与私密报告渠道
CHANGELOG.md	用户可感知变化
ROADMAP.md	Now / Next / Later

Apache-2.0 licensed. Security issues must use private vulnerability reporting, not public Issues.