二途序

八月月报：把质量装进流程 —— 软建议与硬约束

覆盖范围：8.3 / 8.10 / 8.17 / 8.24 / 8.31 五周（8.31 周含 9 月初日期）。本月工作背景一句话：多 agent PPT 生成流水线（ppt-pipeline-swarm）从调优走向收尾交付，个人知识库项目 OpsMind 一周连发三版、自建 agent 基座。

本月方法地图

mindmap
  root((八月方法))
    质量约束
      QA 产物硬约束
      渲染后校验实际尺寸
      参考项与校验项分清
      纯净审计每 diff
    交互设计
      HITL 显式化
      降级优于多选一
      允许犯错 快速反馈
    观测与隔离
      只读旁路 trace
      并行子 agent 隔离防幻觉
    选型与提示词
      框架选型看它不支持的
      提示词是操作手册
      看起来完整≠真的能用

原理深读：质量不能靠自觉，只能靠不可绕过的流程

是什么：凡是 "必须成立" 的质量属性，都要落成不可跳过的流程约束（硬约束）；凡是 "仅供参考" 的信息，要明确标为建议（软建议）。两者绝不能混在同一层。

为什么成立：生成过程是逐项进行的，而质量要求是全称命题 ——"每一页都对"，不是一个 "平均大多数对"。本月有个真实案例：某页跳过了校验、没有 QA 产物，最终 PPTX 该页元素重叠。事故的根因不是模型能力，而是 校验可以被跳过：任何可以跳过的步骤，在时间压力下终将被跳过 —— 无论执行者是模型还是人。所以质量必须物化为流程中的强制关卡，而不是产出之后的期望。

这条原理在本月反复得到验证：

  • QA 硬约束闭环：生成单页 HTML → QA 校验 → 失败回修 → 通过才下一页。校验产物本身成为下一环节的硬输入。
  • 渲染后校验实际尺寸：生成 HTML 不等于渲染正确。截断、覆盖、字体缺失、公式溢出，根因全部是 "渲染后没校验最终产物"。源码正确 ≠ 产物正确，检查必须放在有损转换的 下游。
  • HITL 显式化：人机交互靠模型 "自觉" 必然被跳过，显式 ask_user（把等待确认做成固定触发项）才构成真正的介入点。
  • 纯净审计进 diff：文档纯净（无溯源残留、无死内容）不是写完后的补救，而是每改一处保持局部纯净，全局自然纯净。审计从 "阶段" 变成 "每次提交的伴随动作"。

配套的一条是 参考项与校验项分清：给 agent 的上下文里，"建议参考" 和 "必须满足" 如果混排，agent 就会无所适从 —— 该硬的不硬，该软的不软。分类本身也是流程设计的一部分。

机理小结：把质量要求从 "对模型的期望" 翻译成 "对流程的约束"，本质是把质量控制点从模型内部（不可控）移到流程外部（可控、可审计、可复现）。

边界在哪：

  • 硬约束有成本：每一道关卡都拖慢流程、增加 token。只对 "错误代价不可逆" 的环节设硬约束，其余交给抽查。
  • 硬约束依赖校验器本身正确：校验规则错了，闭环会把系统锁死在错误标准上（本月 <p> 不能有 border 这类规则就需要先验证再固化）。
  • 快速反馈是前提：允许 agent 犯错、犯错后即时纠正，比追求一次做对更现实 —— 但前提是校验闭环足够快，否则 "允许犯错" 就变成 "放任犯错"。

业界对照：Anthropic 在多 agent 系统实践中同样强调全程可观测 ——"加上全量生产追踪后，才能系统性地诊断 agent 为何失败"；其 agent 设计指南建议 agent"在检查点或遇到阻塞时暂停等人反馈"—— 与 "校验不可跳过" 是同一原则在模型和人两侧的落实。

原理清单

  • 只读旁路观测：trace 不能改变被观测对象的行为，否则 trace 不可信。实现上：阶段边界旁路落盘每个 agent 的完整返回，trace 落 workspace（产物区）不落 skill 目录（只读区），多场景复跑互不污染。卡住时看最后写的 trace 文件即可定位。
  • 并行子 agent 的本质是隔离：不只是快。防止主上下文爆满、反复压缩丢失信息、产生幻觉 —— 隔离才是主要收益。
  • 降级优于多选一：让用户在多个启动参数里选，是把复杂度推给用户。默认一个、失败降级到下一个，报错信息作为上下文返回。提示词同理：渐进披露，不一次给全部选项。
  • 框架选型看它不支持的：Eino（字节开源 Go LLM 框架）不支持真异步工具，SubAgent 异步派发做不了 —— 弃用自建。框架的能力边界就是你能表达的问题边界，选型期就该排查 "缺失清单"，而不是上线后打补丁。
  • 提示词是 agent 的操作手册：分析 21 家厂商 421 份系统提示词后确认，成熟 agent 的提示词密度远超想象：工具描述五要素（功能、何时调、何时不调、参数、输出）、诚实契约置顶、输出规范缺一不可。手册含糊，执行者就会自由发挥。
  • "看起来完整"≠"真的能用"：skill 包自评出五类短板，最大缺口是零实战验证 ——Steps 写得再规范，没在真实项目跑过就只是最佳实践陈述。改进方向：从 "写 Steps" 转向 "跑过再提炼"。
  • 思维链过长是执行风险：GLM 模型下子 agent 卡在 "想完没做"，根因是思维链堆到一定长度被截断（官方文档确认 "达到生成上限，输出可能被截断"；思维链是否计入上限文档未明说，但长准备期思考抬高截断概率的因果成立）。对策：控制链长，或把准备性思考拆成显式步骤。
  • 修 bug 追到机制层：解析器出问题挖到 "如何解析" 这一层，而不是堆条件分支绕过。与 7 月 vanilla 对照组定位法同源：先找到正确的归属层，再动手。

反例与边界

  • 多选一启动参数（反例）：把选择负担推给用户，已被 "首选 + 降级" 替代。
  • 隐式 HITL（反例）：默认自动推断用户意图、不设固定确认点，等于没有人工介入。
  • 纯净原则的适用边界：面向 "当前读者" 的文档适用；面向 "演进史读者" 的材料（CHANGELOG、决策记录）恰恰要保留时间线 —— 先分清文档服务谁。

参考资料