长时自主运行手册｜Agent 长时自主交付

我的方案 · 机制来自多源交集

01｜双环、三角色、一个默认失败契约

把控制流和判断权分开。外环负责预算、权限、检查点和退出；内环只完成一个可验证切片。角色可以由不同模型、不同会话或人机组合承担，关键是上下文与权限隔离。

ROLE 1Planner冻结目标、边界、criterion、预算与恢复策略。

ROLE 2Builder选择一个失败条目，实现最小切片并提交证据。

ROLE 3Evaluator从新上下文亲自运行 oracle，不能写业务代码。

CONTROLController只依据机器状态决定继续、重试、升级或停止。

完成条件不是“Agent 说 done”，而是：所有 mandatory criterion 经指定 grader 变为 PASS，最终 receipt 完整，工作区满足收尾不变量。

为何默认 FAIL

缺少截图、日志或退出码时，最安全的含义是“尚未证明”，而不是“看起来应该没问题”。

为何只做一个切片

缩短故障定位与回滚半径，也让 fresh session 能读懂上一轮发生了什么。

为何分离评价

构建者天然会沿自己的实现假设找证据；只读新上下文更容易发现遗漏和投机。

为何仍需人

价值判断、需求歧义、破坏性动作、权限扩大和高风险发布不能由循环自行授权。

可恢复状态

02｜上下文会消失，任务状态不能消失

文件名可以适配现有项目，职责不要混在一个无限膨胀的提示词里。AGENTS.md 只做导航；验收条件与运行证据应成为独立、可审查的仓库对象。

repo/
├─ AGENTS.md                  # 入口地图：架构、命令、禁区、文档链接
├─ docs/
│  ├─ PLANS.md               # 可恢复执行计划 / ExecPlan 规范
│  └─ ACCEPTANCE.md          # 人可读、冻结的验收契约
├─ .agent/
│  ├─ acceptance.json        # 机器可读 criterion，初始全 FAIL
│  ├─ PROGRESS.md            # 已做/下一步/基线/失败签名
│  ├─ DECISIONS.md           # 关键选择、替代方案、责任人
│  ├─ STEER.md               # 人类非破坏性引导入口
│  ├─ STOP                   # 存在即优雅停机
│  └─ evidence/              # 命令、日志、截图、轨迹与索引
└─ RUN_RECEIPT.md            # 最终范围、结果、风险、回滚点

交接文件最小内容

仓库当前基线及它是否在修改前就失败。
本轮只处理了哪一个 criterion，改了什么，尚未证明什么。
可复现的失败签名、已尝试方案与不得重复的死路。
下一条最小动作，以及准确工作目录和命令。

Progressive gates

03｜八道门：便宜检查在前，昂贵验证在后

每轮不必跑完整回归，但不能跳过与当前切片匹配的证据。批次结束再做集成门，防止局部 PASS 拼成全局失败。

契约就绪

任务可解、边界可识别、每条 criterion 有 oracle、证据要求、grader 和默认状态。

开工前

基线可归因

在任何修改前运行最小冒烟/复现；保存原有失败，避免把历史问题算到本轮。

每个新工作区

切片完整

一个 criterion 对应一组紧凑改动；禁止顺手扩展范围、无关重构或隐性依赖。

每轮

确定性检查

编译、类型、lint、定向测试、schema/结构不变量与安全扫描。退出码、命令、版本都入证据。

每轮

真实路径 + 负向控制

运行实际应用/API/数据库/浏览器；同时证明非法输入会失败、旧 bug 测试在修复前会失败。

用户路径变化时

独立评价

只读 evaluator 打开产物、运行 oracle，逐条给 PASS / NEEDS_WORK / BLOCKED / INCONCLUSIVE。

每个 criterion

批次集成

完整回归、跨切片不变量、脏工作区/孤儿文件、性能与构建产物检查。

每批或合并前

最终回执

完成/未完成、运行过的检查、证据索引、风险、回滚点和需要人工决定的事项。

退出前

Evidence ladder

04｜证据等级：文本声明只能算 E0

不同任务可以规定最低等级。高风险功能通常至少需要 E3；涉及安全、账务、数据迁移或发布，应到 E4 并保留人工批准。

等级	证据	能证明什么	不能证明什么
E0	Agent 自述、计划或代码解释	意图与假设	实际可运行、正确
E1	静态 diff、类型/lint、结构检查	语法与部分不变量	真实运行路径
E2	定向自动测试、退出码、可复现实验	已覆盖输入下的行为	测试没写错或没被弱化
E3	真实应用/API/数据库/浏览器路径 + 负向控制	关键端到端结果与失败路径	所有边界、主观质量
E4	独立评价 + 全量回归 + 人工风险批准	多源交叉验证与治理条件	未来环境永不变化

反投机检查

测试、fixture、snapshot、mock 或阈值被修改时自动升级审查。
真实路径必须经过新增代码；用 coverage/trace/日志确认，而非仅看页面存在。
给 grader 一个应当失败的样本；如果仍 PASS，说明判定器失真。
证据绑定 commit、环境、命令与时间，避免拿旧结果证明新代码。

Mechanical exit

05｜停止是控制面，不是失败

只有 controller 决定是否继续。Builder 可以报告完成或受阻，但不能扩大预算、权限或成功定义。

成功停止

全部 mandatory PASS；receipt 完整；工作区与集成门通过；无人类待决项。

预算停止

达到时长、轮次、token/成本、磁盘或 API 限额；保存检查点后退出。

停滞停止

连续 2 轮无有效 diff，或同一失败签名连续 3 次且没有新诊断。

边界停止

需要未授权权限、破坏性动作、外部协调、关键歧义，或 grader 只能给 INCONCLUSIVE。

while budget.remaining and not STOP.exists:
    criterion = first_mandatory_false()
    builder.run_one_slice(criterion)
    deterministic_gates.run()
    evaluator = fresh_readonly_context()
    evaluator.verify(criterion)          # PASS / NEEDS_WORK / BLOCKED / INCONCLUSIVE
    controller.check_progress_signature()
    checkpoint_state_and_evidence()

exit_only_if(success | budget_hit | stalled | authority_boundary | human_stop)

这段是控制协议伪代码，不是建议无限执行的 shell 命令。实际 runner 还要有进程树清理、锁、心跳、超时、磁盘上限与秘密隔离。

Independent grading

06｜评价器要“做检查”，不是“评论代码”

好的 evaluator 输出可证伪判断：它看到什么、运行了什么、为何达到阈值。证据不足就返回 INCONCLUSIVE，不能替构建者补故事。

输入：冻结的 acceptance.json、目标 commit、只读工作区、允许的工具
禁止：修改业务代码、修改 criterion、读取 Builder 的主观结论作为证据

对每条 criterion：
1. 检查任务是否可判定；不可判定 → INCONCLUSIVE
2. 运行指定 oracle，并记录命令、版本、退出码和产物
3. 运行至少一个 negative control
4. 检查证据是否来自目标 commit 且覆盖真实路径
5. 返回状态、按维度理由、证据 URI、最小复现与置信边界

硬规则：任一 mandatory 低于阈值，整体不得 PASS。

LLM grader 何时合适

视觉质量、研究论证、交互清晰度等难以完全确定性判定时使用；先用少量人工金标准样本标定，给出维度化 rubric、正反例和 Unknown 选项。安全、权限、退出码、schema、金额等优先由确定性程序判定。

Reliability, not vibes

07｜真正该追踪的不是“跑了多久”

先建立 20–50 个代表性任务回放集，记录每次试验的环境与轨迹。回归集应接近 100% 通过；能力集要保留未饱和难题。

False-pass rate被判 PASS 但人工复核失败的比例；比一般失败更危险。

pass@1 / pass^k单次成功率与连续 k 次都成功的概率，区分偶尔成功和稳定交付。

Human interventions每任务需要多少次澄清、授权、纠偏和接管。

Verified progress / cost每小时或每成本单位新增多少已独立通过的 criterion。

No-progress cycles无有效 diff、重复错误或只改计划不改结果的轮数。

Recovery time中断、上下文重置或失败合并后恢复到可验证状态的时间。

示意：若每轮都有 95% 的独立正确率，20 个相互依赖切片全部正确的朴素概率仅约 35.8%；即使每轮 99%，也约 81.8%。这不是实测成功率，而是说明长链会放大小误差，因此需要中间验证、回滚和独立门禁。

Task-specific oracles

08｜三类任务，三种“真实路径”

通用结构相同，但 oracle 不应强行统一。把领域内真正能证伪结果的动作放进验收。

功能 / 缺陷

修复前复现与修复后回归
运行中应用的端到端路径
错误输入与权限拒绝
既有行为全量回归

重构 / 迁移

前后行为差分
架构不变量与依赖方向
性能、资源与兼容阈值
双写/回滚/数据核对

调研 / 内容

主张—来源矩阵
原始来源与检索截止日
数字、日期、引用交叉核验
反例、分歧和未知清单

Preflight

09｜启动前 15 项检查

用户结果能由第三方观察，而非只描述内部实现。
任务范围、禁区、可写路径和外部系统边界已列明。
每个 mandatory criterion 初始为 FAIL，并有唯一 ID。
每条 criterion 指定 oracle、证据、grader 与阈值。
基线测试和原故障复现已在修改前保存。
真实用户路径可在隔离环境中执行。
至少一个 negative control 能揭露失真的 grader。
测试删除、断言弱化与 mock 增加会触发升级审查。
Builder 与 Evaluator 的上下文或权限已隔离。
时间、轮次、成本、磁盘和 API 预算已固定。
无进展和重复失败签名的阈值已固定。
存在人工 STOP/STEER 通道与安全检查点。
高风险动作需要人工批准，且批准范围不会被推断扩大。
最终 receipt 字段已定义，不会只输出“完成”。
先在低风险代表任务上回放并测 false-pass，再逐步提高自治。

打开验收契约生成器 →　查看 34 个来源与视频 →