deepseek-harness/docs/rfc/proposed/feature/2026-07-16-harness-level-loop.zh.md

RFC: harness 层 goal-based loop

Status: proposed

English | 中文

问题

packages/core/agent-loop 只跑 inner loop：一次 turn 内推理加工具循环，模型返回 end_turn 就结束。其 README 明确写「No built-in turn budget」——预算是它自己承认的 gap。跨轮次调度落在 harness 层：跑到测试全绿、按 rubric 反复改稿、把 PRD 拆成 bead 逐个推进、无人值守跑一整晚。这几类任务今天都没有一等公民的实现。

现有代码里有三种「能凑合跑」的替代，都不够用：

替代	问题
packages/workflow 脚本表达 while (!done)	README 明写「No token-budget vocabulary」和「No journaling or resume」；父 turn 阻塞到脚本 settle。能跑几分钟的编排，跑不了几小时的长期任务
外部 shell while :; do dsh …; done	Ralph 风格的调度今天就能这么写。缺共享的 stop condition、budget、evaluator 词汇，每个使用者各自重发明；循环本身没有持久化对象可供事后诊断或恢复
packages/subagent seam 的 sendMessage/resume	README 明写「Runtime steering and continuation are seam-only capabilities」。没有 model-facing consumer，模型只能起 fresh 子会话

典型使用场景有三类。自动化修复：面前一个失败的测试套件，希望一个进程持续修改代码、跑测试、根据失败信息再修改，直到全绿或触达预算上限。按 rubric 迭代改稿：一份文档、代码或翻译需要满足打分标准，循环反复调整、独立评估者打分、直到达标或耗尽轮数。无人值守长跑：例如通宵把一个仓库从一种技术栈移植到另一种，下班前启动第二天回来看结果，全程只有预算兜底。三类共同的形态：几分钟到几小时、evaluator 决定成败、预算是硬约束、跑完还需要能回看和恢复。

提案

Loop 有四种触发形态，按谁在什么时候启动一轮划分：

形态	谁触发	何时触发	现有对标	本 RFC
turn-based	用户在会话里发一条消息	每一轮用户回复	packages/core/agent-loop 现有一次 turn 内的推理与工具循环	不覆盖，已有实现
goal-based	用户或 agent 明确指定「跑到某条件为止」	一次启动，evaluator 判停	Claude Code 的 /goal、Codex 的 /goal、Ralph 家族	本 RFC 覆盖
time-based	scheduler	按 cron 或时间间隔	Claude Code 的 /loop（周期性）、/schedule	延后到 dsh-schedule RFC
proactive	agent 自己	agent 在推理中意识到需要开一个 loop 时	Anthropic ClaudeDevs 4 类分类里的 proactive 档	本 RFC 自然包含（agent 调 loop tool 就是 proactive）

本 RFC 只新增 capability seam packages/loop/ 处理 goal-based 一种。proactive 复用同一 loop tool，agent 主动调用即触发，无需额外机制。time-based 需要独立的 scheduler package，属于另一份 RFC 的事情；本 RFC 只在 cordis leaf 触发面预留跟未来 dsh-schedule 联动的钩子。

三个包：

• @deepseek-ai/dsh-loop：类型、LoopDriver service、StopCondition 判别联合、四个内置 service 定义（Evaluator / BudgetPolicy / RoundHandoff / GoalReflector）、事件 schema
• @deepseek-ai/dsh-loop-driver：默认 driver 实现
• @deepseek-ai/dsh-loop-tool：model-facing loop tool + CLI dsh loop

设计围绕四个具体问题展开，每个问题对应一条独立的 cordis service seam：

1. 长跑 loop 出问题后缺诊断和恢复手段。loop 作为独立 session 解决。
2. loop 结束时的 PASS 是否可信决定几小时工作是否作废。同一个 LLM 既生成又自评的架构本身就不可信。Evaluator 与 Budget 做成 service seam 解决。
3. 短任务和长任务需要的记忆策略相反，硬编一种模式会让另一类场景不可用。RoundHandoff 做成 service seam 解决。
4. 用户初始给的 goal 未必始终正确。agent 沿着错的目标蛮干会耗尽预算做错事。GoalReflector 做成 service seam 解决。

四条 seam 之外还有一条贯穿全文的原则：一个 loop 只处理一个原子目标。大目标拆成若干小 loop 串联，不塞进一个 loop 让 evaluator 判定多件事。判定 granularity 是否合适的经验规则：如果 loop 跑完说不清它到底做完了什么，granularity 就太大，应当拆。Phase 2 补 loop_split model-facing tool 让 agent 收到过大 goal 时能自己拆。

术语约定：inner loop 指 packages/core/agent-loop 一次 turn 的推理与工具循环；harness loop 指本 RFC 引入的外层调度器，围绕 inner loop 反复迭代。本 RFC 不改 agent-loop，符合 AGENTS.md「Plugins, not loop changes」。

StopCondition 是 discriminated union，assertNever 收口：

interface EvaluatorReport { criteria: readonly { name: string; pass: boolean; evidence: readonly string[] }[] }

type StopCondition =
  | { kind: 'goal-met'; evidence: EvaluatorReport }
  | { kind: 'budget-cap'; scope: 'usd' | 'tokens' | 'rounds' }
  | { kind: 'stuck'; pattern: 'repeat-action' | 'no-progress' | 'error-loop' }
  | { kind: 'approval-required'; reason: string }
  | { kind: 'user-cancel' }

export {}

Loop 作为独立 session

长跑 loop 一旦出错，用户没有系统的诊断手段。跑几小时后失败，只能翻散落的日志文件。发现中间某一轮走偏想倒回去重跑，只能从头开始。agent 想参考自己过去 loop 的经验也没有可用的 API。

Driver 为每个 loop 开一个独立的 loop-session（新的 session id）。每轮的输入、inner-loop 结果、evaluator 报告、stop 决策都作为 session event 落盘，复用 packages/session-persistence 的 SQLite backend。得到三种能力。

• 从任意轮恢复：发现第 78 轮偏航，从第 77 轮拉起，换 prompt 或换 evaluator 重跑，不必从头
• 事后诊断：通过 sqlite-session-query-provider 查「哪一轮 evaluator 开始一直挂在同条 criterion 上」定位卡点
• 元循环学习：agent 开新 loop 前查自己过往同类 loop 的经验——「我以前 fix 过类似的 bug 吗？失败在哪一轮？」

Claude Code、Codex 的 /goal 是一次性对象：跑完就丢，agent 下次遇到同类问题从零开始。

存储与依赖。每轮几 KB events，100 轮 loop 约 100–500 KB；跑几千个 loop 会到 GB 级。logDetail: 'summary' | 'full' 配置缓解，默认 full，长跑用户可切 summary。中间态全持久化会把生成过的 key、密码一并落盘，跟普通 session 是同一类风险但量放大 10–100 倍，README 明确提示。最关键的一条：本节能力硬依赖尚未落地的 sqlite-session-query-provider RFC。若该 RFC 未落地，任意轮 resume 与查询能力会降级为「只能翻 JSONL 文件」。若 Phase 1 交付时该 RFC 还未 merge，本 Phase 只保证 event 结构正确，query 面延后到 Phase 2。

可插拔的 Evaluator 与 Budget

loop 的价值最终取决于结束时的 PASS 是否可信。如果 evaluator 会被 hack 或幻觉 PASS，前面几小时的工作全部作废。同一个 LLM 既生成又自评的架构本身就不可信：模型有条件说服自己 PASS。即便让独立 subagent 做 evaluator，只要 evaluator 还是 LLM，就仍然对同类内容有系统性偏好——独立 subagent 只是缓解不是根治。

真正可信的评估必须是完全非 LLM 的硬检查：shell exit code、静态分析、外部服务。LLM 物理上碰不到评估过程。但硬检查只有用户自己知道该跑什么：不同项目 pytest 命令不同、公司有私有合规检查器、有些团队还要跑内部 lint。主库无论内置几种都覆盖不全。所以 evaluator 必须做成用户可以自己接入的 seam。

预算方面同理：产品级的花费护栏是黑盒，无法按团队策略调整（个人卡、团队分摊、按 PR 结算）。

Evaluator 和 BudgetPolicy 都作为 cordis service seam 暴露。Goal 必须携带一个明确档位的 EvaluatorSpec，driver 拒绝启动没有 evaluator 配对的 loop——含糊的目标（"把代码写好"）不能进入 loop 系统：

interface RubricItem { name: string; description: string }
interface EvaluatorContract { readonly name: string }

type EvaluatorSpec = {
  tier:
    | { kind: 'single-metric'; check: string }              // "pytest -q && ruff check"、"exit code == 0"
    | { kind: 'rubric'; criteria: RubricItem[] }             // 若干独立 criterion，各自 pass/fail + evidence
    | { kind: 'contract'; interface: EvaluatorContract }     // 结构化合约（如 API sig 校验）
    | { kind: 'llm-judge'; rubric: string; model: string }   // 兜底档，仅软目标
  /**
   * 主 agent 不可写的路径（通常是 evaluator 会读的测试文件、评估配置）。
   * 违规写会被 packages/fs policy gate 拒绝，记 loop/hack-attempt session event。
   * 这是防 reward hacking 的核心机制——把「改测试让 evaluator 通过」这条路封死。
   */
  protectedPaths?: readonly string[]
}

export {}

为什么分档，而不是让用户传自由函数？ 档位强制用户在启动时明确「用哪一档强度判成败」。自由函数看起来灵活，实际让 evaluator 强度隐性下沉——用户以为在做严格判定，实际写的是 LLM-judge 那种模糊的语义匹配。长跑场景下代价是几小时白跑。

四档从上到下可信度依次降低。前三档都是完全非 LLM 的硬检查。llm-judge 是最弱一档，仅用于确实无硬信号的软目标（改稿、翻译质量）。文档明确标注「此档不能挡定向对抗，长跑无人值守场景需至少一档硬检查配合」。

Driver 强制五条硬约束，不下放给 Evaluator 实现。它们分别对付三类不同的攻击面：

防「同一个 agent 既生成又自评」：

1. fresh subagent：evaluator 每轮开 fresh subagent（用 dsh-subagent 的 spawn），不继承主循环 context

防主 agent 通过修改 evaluator 输入来 reward hack：

2. protectedPaths 硬隔离：EvaluatorSpec 声明的路径（通常是测试文件、评估配置）由 packages/fs 已有的 policy gate 拒绝主 agent 的写请求，记 loop/hack-attempt session event。这是 Phase 1 真正挡 reward hacking 的一层——直接封死「改测试让 evaluator 通过」这条路

防 evaluator subagent 自身被 subverted：

3. 只读工具集：evaluator 的 tool set 被 driver 剥离到只保留读类工具，写类工具禁用（复用 SubagentProvider 的 toolFilter）。它防的不是主 agent 的 reward hacking，而是 evaluator 读到被 evaluate 的代码里 embed 的 prompt injection 时不会被诱导去改状态

防 evaluator 报告本身欺骗 driver：

4. PASS 只能由 evaluator 报告翻转：goal-met StopCondition 只能来自 evaluator，driver 或主 agent 都不能直接构造
5. Default-FAIL：driver 内部维护每个 criterion 的 pass 状态默认 false，只有 evaluator 报告里带非空 evidence 才允许翻 true；evaluator 无法通过返回 {pass: true} 而不给 evidence 让 driver 接受

五条一起决定 evaluator 结论只能靠证据推动，无法靠自信推动，也无法靠主 agent 悄悄改测试推动。

Phase 1 内置三个 backend：

• loop-evaluator-shell 实现 single-metric：跑 shell 命令，exit 0 = pass
• loop-evaluator-rubric-judge 实现 llm-judge：预写 rubric + LLM 打分，仅软目标
• loop-budget-preflight：每轮启动前估 (promptTokens + overhead + estOutputTokens) / 1M × pricePerMTok，超 perRoundUsd 拒绝启动。估算模型来自 MartinLoop policy.ts:551-596

PricingProvider 服务注入 pricing 表，test seam 可覆盖，不硬编到 driver 里（AGENTS.md「No hardcoded tunables in plugins」）。rubric 与 contract 档 Phase 2 补内置实现，Phase 1 只暴露类型让第三方插件先接。

局限：evaluator subagent 拿到的"只读工具"仍是同一进程的 shell 与 fs 读，理论上仍可能被 prompt injection 绕过。挡定向对抗需要两容器方案（evaluator 定义文件对主 agent 完全不可访问，Anthropic patch.py 走的就是这条路），本 RFC Phase 3 才做。见 风险。

可插拔的 RoundHandoff

每轮之间如何传递 context 是一个两难。完整保留之前对话（continue）连续性好，但对话会持续增长最终撞上 context 上限，且上一轮的错误信息会污染后续每一轮。每轮从零开始（fresh）避免污染，但每次需要重新理解上下文。跑 3 轮改稿与跑 80 轮 overnight 修 bug 需要的策略是相反的。Claude Code、Codex 都硬编一种模式，用户没法按任务类型切换。

做成 service seam：

interface RoundContext { loopId: string; round: number }
interface NextRoundSpec { mode: 'fresh' | 'continue' }

interface RoundHandoff {
  buildNextRound(prev: RoundContext): NextRoundSpec
}

export {}

Phase 1 内置三个 backend：

Backend	场景	机制
handoff-fresh-with-summary（默认）	长跑、无人值守	每轮开 fresh subagent，只注入一段 progress 摘要作 system prompt 附加段
handoff-continue-with-compaction（推荐中间档）	5–20 轮的中等长度	整段对话保留到 token 阈值，超了复用 packages/compact 压缩，摘要 + 最近 K 轮作起点
handoff-continue-raw（专业档）	≤5 轮短任务、测试	纯连续对话不裁剪

为什么默认 fresh？ 所有实际跑成的长跑 loop（repomirror、Kimi ralph-loop、autoresearch）用的都是 fresh。把重要 loop 状态放在 context window 外由 driver 管理是长跑的正确姿势。handoff-continue-raw 违反这条经验，README 明写长跑不适用。

为什么中间档只有我们能做？ handoff-continue-with-compaction 依赖 compaction seam——竞品都没有，只有本仓库 packages/compact 提供了这个基础设施。

为什么做成 seam 而不是三选一 flag？ 用户可以写 20 行插件表达「前 5 轮 continue、之后 fresh」这类混合策略，或表达「context 到 50% 自动 compact 一次」，不用等主库支持。

局限：continue-with-compaction 依赖 packages/compact 的压缩质量，压缩本身可能把幻觉信息写进摘要传下去；README 建议长跑首选 fresh。三个 backend 的边界会让新用户不知道选哪个；dsh loop CLI 默认用 fresh，用户在遇到具体问题前不需要理解这些差别。

可插拔的 GoalReflector

用户在启动 loop 时给的目标不一定准确。可能基于错误假设（让 agent 用某个已经废弃的 API 实现功能），可能不够清晰（agent 在做的过程中才发现需要澄清），也可能被后来的信息证伪。现在的循环执行框架把 goal 当作启动时冻结的合约，agent 只能沿着原路蛮干，结果是在错的方向上耗尽预算。

做成 service seam，与 Evaluator 职责分离：evaluator 问「是否达成目标」，reflector 问「目标是否还是那个目标」。

interface RoundContext { loopId: string; round: number }
interface GoalConcern { concern: string; severity: 'low' | 'medium' | 'high' }

interface GoalReflector {
  reflect(ctx: RoundContext, concerns: GoalConcern[]): Promise<GoalReflection>
}

type GoalReflection =
  | { kind: 'continue' }                              // goal 仍有效
  | { kind: 'revise'; newGoal: string; why: string }  // 建议修正 goal
  | { kind: 'stop-for-human'; reason: string }        // 需要人拍板

export {}

concern 有三种触发来源，Phase 1 实现前两种：

• agent 主动：通过 model-facing tool loop_flag_concern({ concern, severity })。agent 在调研中意识到「用户假设的那个库已经废弃」时可以直接 raise
• driver 启发式：预算过 50% 且零 criterion pass 时，driver 自动 raise no-progress-toward-goal concern
• 周期性 reflector subagent（Phase 2）：每 N 轮独立跑一个只读 subagent 复审 goal 有效性，与 evaluator 独立性遵循同一思路

响应策略通过 onGoalConcern 配置项。这四种配置对应不同的 loop 使用哲学，用户按团队协作方式选，driver 不预设立场：

• 'stop'（Phase 1 默认）：任何 concern 都触发 StopCondition: approval-required，人拍板。loop 在遇到任何不确定性时都不应自己往下走，适合谨慎风格团队与影响面较大的 loop 场景
• 'notify-continue'（Phase 1）：记 loop/goal-concern session event（高优先级）加 ACP 显式提示，继续跑，人在结束时集中审阅。loop 内部不打扰，适合无人值守长跑
• 'reflect'（Phase 2）：调 GoalReflector 决定 continue、revise 还是 stop。委派一个独立 agent 代替人做初步判断，适合中等自主度的团队
• 不注册 GoalReflector 且 onGoalConcern 未设 = 最放手档，loop 只在传统 stop condition 触发时停

为什么默认选 stop？ 无人值守场景下宁可多停一次也不要在错方向上跑几小时。用户明确要无人值守可切 notify-continue。

concern 本身就是普通 session event，跟前文的持久化 session 能力天然协同：resume 时可以从 concern 出现的那一轮拉起，换 goal 重跑，前 N 轮的工作不丢。

滥用与丢失防护。agent 可能每轮都 raise concern；缓解是 severity 字段和 driver 侧的最小 rate limit（同一 concern 30 秒内去重）。这种滥用的代价是 agent 卡住自己无法推进，动机不强。goal 被 revise 后原始 goal 会丢失；每次 revise 落 loop/goal-revised session event 带 rationale，resume 时可选任意历史 goal 版本。

用户面

四个触发面共享同一个 driver：

• agent 侧 tool：loop({ goal, evaluator, maxRounds, maxUsd, onGoalConcern }) 启动嵌套 harness loop。正在跑的 loop 内部 agent 可用 loop_flag_concern({ concern, severity }) 主动发起 concern。ACP 渲染意图为 generic。agent 自主发起就是 proactive 触发，无需额外机制
• CLI：dsh loop <prompt> --stop <shell-cmd> --max-rounds N --max-usd X --handoff fresh。人类主导启动，最典型的 Ralph 风格用法
• cordis leaf：cordis.yml 里以 leaf 形式声明常驻循环，配合未来的 dsh-schedule RFC 可做周期性触发
• ACP slash command：/loop <goal>（还有 /loop-flag-concern）在编辑器/客户端的当前会话里直接启动。语义等价于人类在 CLI 里敲 dsh loop，但发生在正在进行的 ACP session 上下文中，允许 loop 结果直接注入会话

ACP slash command 的依赖：packages/ui/acp 的 available_commands_update 面目前是 unbuilt 状态（acp-feature-support.md）。等 harness 的 slash command 基础设施落地，/loop 与 /loop-flag-concern 只需在该基础设施里注册；driver 与 tool 接口不变。本 RFC 保留名字并给出参数 shape，但不承诺基础设施本身——那属于独立的 ACP 补齐 RFC。

默认 system prompt 里有两条硬约束，随所有内置 loop tool 一起分发：

1. 不允许写 TODO、FAKE、PLACEHOLDER 占位符让 evaluator 表面通过
2. 不允许写空的 try/except 或 catch(_) 让 evaluator 忽略错误

这两条不是 seam 层能拦的，是 prompt 层的约定。用户可以自定义 system prompt 但内置约束保留。

与仓库现有代码的关系

直接复用无需修改：

• packages/subagent 的 spawn provider、toolFilter、persona——loop 每轮起 subagent、evaluator 只读工具集
• packages/session-persistence 的 SQLite backend——loop-session 落盘
• packages/compact——handoff-continue-with-compaction 的实现基础
• packages/todo——单会话 continue 模式下作为可选 progress 表达
• 若 ToolExecution.reportProgress 先落地，loop tool 可用它逐轮 UI 更新

不动：packages/core/agent-loop（inner loop 语义保持）；packages/workflow（DAG 编排 vs. 迭代同 goal 是 orthogonal 关系，两个 README 在「Related」段互链说明边界）。

依赖尚未落地的两处：

• sqlite-session-query-provider——见 Loop 作为独立 session 局限段的缓解方案
• ACP slash command 基础设施（available_commands_update 面）——见 用户面。基础设施落地前，slash command 触发面缺席，其它三个触发面照常工作

唯一涉及现有代码的改动可延后到 Phase 2：给 packages/subagent-tool 增加「续跑已有 subagent」的参数暴露，用于 handoff-continue-* 两个 backend。底层 SubagentRun.sendMessage 与 resume 已作为 seam 能力存在，缺的只是 tool 层的参数入口。若 Phase 1 只上 handoff-fresh-with-summary，完全不动 subagent-tool；Phase 2 再补。

分阶段

Phase 1（本 RFC 承诺范围）：三包 seam；StopCondition；EvaluatorSpec 四档类型 + protectedPaths 硬隔离（复用 packages/fs policy gate），其中 single-metric 与 llm-judge 有内置实现，rubric 与 contract 类型开放待接；Default-FAIL 强制；3 个内置 evaluator/budget/handoff backend；loop_flag_concern tool；no-progress 启发式；onGoalConcern: 'stop' | 'notify-continue' 二档；CLI；tool；默认 system prompt 硬约束。不含：session-query 面、ACP slash command 触发面（依赖 available_commands_update 基础设施）、subagent-tool 续跑改动、stuck 检测器、Reflector subagent、loop_split tool、rubric 与 contract 档的内置实现。

Phase 2：query 面；stuck 检测器（复现 OpenHands 5 种模式）；subagent-tool 续跑改动（解锁 continue 两档 handoff）；Reflector subagent；onGoalConcern: 'reflect' 档；loop_split model-facing tool；rubric 与 contract 档的内置实现。

Phase 3：agent fleet（同 goal 派 N 个并行 loop 取最优）；与 dsh-schedule 集成；两容器 evaluator 隔离（evaluator 定义文件对主 agent 完全不可访问，防 reward 反向优化）。

备选方案

扩 packages/core/agent-loop：给 inner loop 加「iterate on end_turn until goal」开关。拒绝——AGENTS.md「新行为走文档化扩展 seam；改 agent-loop 需要更新 docs/architecture.md」。harness loop 需要跨 session、跨 agent 的状态，塞进 inner loop 会把 session 语义拧成两层混合。

只做一个 slash command /loop（Claude Code 复刻）：实现最简。拒绝——slash-command 层不解决 harness/inner 边界；四条设计要点（可查询 session、分档 evaluator、可插拔 handoff、可插拔 goal reflector）在 slash-command 层没有承载点，本 RFC 承诺的能力全部丢失。

全权外包给 packages/workflow：把 loop 表达成带回边的 workflow 节点。拒绝——workflow 缺 iteration、StopCondition、Evaluator 的一等公民语义。硬用会把 evaluator 冒充成一个 phase，违反 evaluator 独立于 producer 的架构隔离要求；预算护栏在 workflow 是 phase-level 而非 round-level，粒度对不上。

A（fresh）vs. B（continue）硬编二选一：Ralph 派和 LoopTroop 派各自都有强场景。拒绝——可插拔的 RoundHandoff 提出 seam + 三档内置 backend 涵盖两派并允许 hybrid。

不做 evaluator seam，内置几种够用：更轻。拒绝——可插拔的 Evaluator 与 Budget 的核心价值是团队或私有 evaluator 可扩展。写死后长跑无人值守场景的用户只能改主库。

接受不带 EvaluatorSpec 档位的自由函数：允许用户传任意 (result) => boolean。拒绝——档位强制用户在启动时明确「用哪一档强度判成败」，是防止不知不觉滑到弱档的关键。自由函数看起来灵活，实际让 evaluator 强度隐性下沉，长跑场景代价大。

引入独立记忆引擎（Beads / dex-style）：外部化状态的成熟做法。拒绝——packages/session-persistence + sqlite-session-query-provider 已能提供等效能力；新引擎收益远小于维护成本。

goal reflection 塞进 Evaluator seam（让 evaluator 返回「criteria 不可能满足」）：拒绝——混淆「是否成功」和「目标是否正确」两个正交问题。Evaluator 应保持独立、只读、简单。

goal-concern 只做 event 不做 seam：更轻。拒绝——响应策略族（stop / notify / reflect）明确，各团队会想插自己的，seam 化投资小于收益。

Phase 1 就上完整 Reflector subagent：更全。拒绝——loop_flag_concern tool + no-progress 启发式 + 二档 policy 覆盖 80% 场景；每轮跑独立 subagent 成本高，Phase 2 按需引入更合理。

不做 loop_split，用户自己拆：Phase 1 已经如此。Phase 2 加是因为长跑场景发现 agent 收到过大 goal 会直接跑而不是自己拆，需要显式工具引导。

验收标准

• packages/loop/{loop,loop-driver,loop-tool} 三包按 capability seam 建成；dsh-loop 只导 types 与 registry
• StopCondition 判别覆盖所有分支（单元），assertNever 编译期收口
• Evaluator、BudgetPolicy、RoundHandoff、GoalReflector 四条 service 都能被外部插件替换（fixture：注入 mock 实现，driver 正确调用）
• EvaluatorSpec 四档类型编译期收敛；driver 拒绝启动没有 evaluator 配对的 loop（fixture：loop({ goal, evaluator: undefined }) 立即返回配置错误）
• Default-FAIL fixture：evaluator 报告返回 {criterion, pass: true, evidence: []} 时 driver 拒绝该 criterion 翻转、记 evaluator/invalid-report session event
• 三个内置 handoff backend 都有单元 + 一个 e2e：fresh-with-summary（跑到 pass）、continue-with-compaction（跑超 token 阈值触发 compact）、continue-raw（跑 3 轮）
• dsh loop CLI e2e：给定 goal + 3 轮上限 + 一个 shell evaluator，通过与耗尽两条路径都返回结构化 stop cause 并 exit code 语义化
• Evaluator 独立性 fixture：主 agent 有 fs.write，evaluator subagent 的 tool set 里没有；试图调 fs.write 被 registry 拒绝
• protectedPaths fixture：EvaluatorSpec.protectedPaths: ["tests/**"] 声明后，主 agent 尝试写 tests/foo.py 被 packages/fs policy gate 拒绝并记 loop/hack-attempt session event，evaluator 侧读该路径正常
• Preflight 护栏 fixture：注入 mock pricing 表构造超 perRoundUsd 的场景，driver 拒绝启动该轮且 emit budget-cap StopCondition
• Goal concern fixture：loop_flag_concern 可从主 agent 调用并产出 loop/goal-concern session event；onGoalConcern: 'stop' 下 emit approval-required StopCondition；'notify-continue' 下继续跑且事件带 ACP 高优先级标记；no-progress 启发式在预算超 50% 且零 pass 时自动触发一次（rate-limit 去重）
• 默认 system prompt 硬约束（无 TODO/FAKE/PLACEHOLDER、无空 catch）随内置 loop tool 一起分发，snapshot 覆盖 prompt 内容
• 每轮的 prompt、inner-loop 结果、evaluator report、stop 决策都以 session event 出现；Phase 2 补 query 面时可按 loopId 检索
• packages/loop/README.md 和 packages/workflow/README.md 的「Related」段互链清楚「何时用 workflow、何时用 loop」的边界
• 单元 100% / snapshot / e2e / doc-sync / verify-module-graph / build / hygiene 全绿；新增 tool 的 ACP 渲染意图（generic）有 snapshot

风险

依赖 sqlite-session-query-provider 落地。Loop 作为独立 session 的用户可见价值（任意轮 resume + 元循环学习）需要它。缓解在该节局限段；Phase 1 不硬绑，Phase 2 才交付 query 面。

packages/workflow 与 loop 的边界是持续答疑热点。「多轮是 loop 还是 workflow」两个 README 必须写清楚：workflow 是「步骤已知、agent 未定、并串行编排」；loop 是「agent 已定、轮数未定、evaluator 判停」。文档不清晰会让用户混用错档。

evaluator 反向优化（reward hacking）。足够长的 loop 里 agent 有条件识别 evaluator 的模式并针对性优化，例如发现「只要测试文件里出现 assert True 就 PASS」从而绕过实质完成。Phase 1 靠 protectedPaths 挡多数 case：evaluator 的输入文件（测试、评估配置）通过 packages/fs policy gate 声明为主 agent 不可写，直接从「改测试让 evaluator 通过」这条路上封死。但仍无法阻止 agent 学出 evaluator 的模式做实质规避（比如写符合表面 pattern 但语义错的代码）。对抗强度高的用户需要 Phase 3 的两容器方案：evaluator 的整个运行时（二进制、rubric、依赖库）都在主 agent 完全不可访问的容器里，Anthropic patch.py 走的就是这条路。

占位符伪造与过度防御码。agent 有时会写 # TODO: implement 让测试勉强通过，或写大量 try/except: pass 让 evaluator 表面 PASS。这些不属于 evaluator 层的问题，而是 agent 生成阶段的 prompt 与训练问题。缓解走 用户面 段那两条默认 system prompt 硬约束；用户自定义 evaluator 时若加入「静态检查禁止 TODO 与空 catch」这类规则更稳妥。这类问题不是 seam 层能根治的。

预算估算漂移。pricing 表是常量，模型调价后估算会飘。护栏保守方向的近似不算 bug，但 README 说明「真实计费以 usage 事件为准，preflight 仅保护单轮爆炸」。

长跑 loop 日志膨胀。跑 100 轮 loop 单 session 上 MB 级。logDetail: 'summary' 兜底但 Phase 1 默认 full，Phase 2 再补 summary 语义。

pre-release 允许直接演进。SESSION_FORMAT_VERSION=0，LoopRoundEvent schema 可随时改；后端拒收旧格式而非兼容，与 AGENTS.md 顶部 pre-release stance 一致。