| name | delegation-guardrails |
| description | "委托机制加固的两条硬规则：①「只叙述不落盘」是模型路由故障信号（不是 worker 偷懒）——只叙述不改文件 = 错误/不可达模型端点返回空内容，禁止 blind retry，必须跑 5 步诊断序列；② 终验波次子代理结论矛盾时，编排者用直接测量（read/grep/wc/stat）仲裁，不信报告质量。当 spawned worker 只叙述不改文件、委托返回空内容、subagent 没落盘、终验子代理结论矛盾、或需要跑 delegation preflight 时使用。Triggers on: 只叙述不落盘, narrate-without-edit, 委托故障, delegation failure, subagent 没落盘, delegation preflight, 终验矛盾, final verification wave, direct measurement, 空内容, empty content, model routing fault, model-scheduler, 调度器。" |
0. 两条规则概览
| 规则 | 触发信号 | 强制动作 |
|---|
| 规则一：只叙述不落盘 = 模型路由故障信号 | spawned worker 返回计划式叙述但 ZERO 文件改动 | 禁止 blind retry 同一委托路径；跑 §1 的 5 步诊断序列 |
| 规则二：终验矛盾用直接测量仲裁 | 并行终验子代理对同一产物报告矛盾结论（一个 PASS、一个 NOT CLOSED） | 直接测量产物（read/grep/wc/stat）定案；禁止按报告质量选边 |
下面的规则不是建议。 每一条都来自 start-work 的硬规则（L196-197），是对真实委托事故的固化。
1. 规则一：只叙述不落盘 = 模型路由故障信号
信号定义
一个 spawned worker 返回了计划式叙述（plan-style narration），但对目标文件零改动。
这不是 worker 偷懒，这是模型路由故障信号：被派发的模型端点大概率不可达或返回空内容
（empty-content response）——worker 拿到的是空 prompt 响应，只能叙述不能执行。
禁止动作
不要 blind retry 同一条委托路径。 同一个坏端点重试多少次都是空内容，
只会浪费时间并掩盖根因。正确动作是转诊断。
强制动作：5 步诊断序列
① 读配置 read opencode.json 的 provider/agent 模型绑定
（provider.omlxc + agent.*.model）
② 端点冒烟 curl 目标模型端点：omitted-model vs with-model 对照
③ 路由核对 grep litellm-config.yaml 的 model_list（网关路由）
④ 跑工具 bin/delegation-alias-check.py + bin/delegation-preflight.py
⑤ 查调度器 git -C ~/.config/opencode log
—— scripts/model-scheduler.sh 是权威写入者
关键环境事实（冒烟与核对用）
| 端点 | 端口 | 行为 |
|---|
| omlx-server | 8000 | 接受 model 字段 |
| mlx_lm | 8092 | 拒绝 model 字段 |
| gateway | 100.96.126.35:4000 | litellm 网关，model_list 定义路由 |
注意：~/.config/opencode 是独立 git 仓库。调度器（scripts/model-scheduler.sh）
是模型绑定的权威写入者，用 git -C ~/.config/opencode log 看它最近改了什么
——不要凭印象判断当前生效的是哪个模型。
工具状态
bin/delegation-alias-check.py 和 bin/delegation-preflight.py 由 PR #1128
（delegation-infra-reliability）交付主仓。合并前这两个文件只在 worktree 里：
引用时说明「随 PR #1128 落主仓」，不要假设主仓 bin/ 已有。
完整 runbook
诊断细节、4 层故障分类、端口语义见
.omo/_knowledge/patterns/delegation-infra-diagnosis-pattern.md（PR #1128 合入后可用）。
2. 规则二：终验矛盾用直接测量仲裁
信号定义
并行 final-verification wave 的多个子代理对同一产物报告矛盾结论
（一个 PASS，另一个 NOT CLOSED）。例如一个说文件已落盘，另一个说文件不存在。
禁止动作
永远不要按报告质量选边。 子代理报告只是某一时刻的视图
（a view at a moment in time）——并发写入会让它立刻过期；
报告写得漂亮与否和产物真实状态无关。
强制动作：直接测量产物
read <artifact> # 读文件本体
grep <pattern> <artifact>
wc -l <artifact> # 行数/字节
stat <artifact> # mtime/size，判断写入时间与并发窗口
以测量结果定案：文件在不在、内容对不对、时间戳合不合理。
证据优先于任何子代理的自述。
3. 何时触发
- spawned worker 返回计划式叙述但文件零改动 → 规则一
- 委托结果疑似空内容 / endpoint 不可达 → 规则一
bin/delegation-preflight.py 报错、或需要跑诊断工具 → 规则一- 终验波次子代理结论矛盾（PASS vs NOT CLOSED）→ 规则二
- 任何「我该信哪个子代理」的时刻 → 规则二，直接测量
4. 一句话总则
叙述不改文件 = 先查路由，不要重试；结论打架 = 先量产物，不要选边。
