二途序

多 agent 工作流卡住怎么办：给 skill 加一层只读 trace

问题：多 agent 工作流是个黑盒

在九问 jiuwenswarm 上落地 PPT 专家 agent，跑起来后发现一个硬痛点：看不见里面发生了什么。

PPT 生成是典型的多步骤协作 ——researcher 出大纲、designer 定设计、presenter 生成、critic 评审、reviser 修订、exporter 导出，中间还夹着 HITL（human-in-the-loop，人介入审批）环节。

环节一多，黑盒就完全不可调试：

  • workflow 卡住，不知道停在哪一步、哪个 agent
  • 子 agent 返回什么、审批是否触发、串行还是并行，只能靠最终产物反推
  • 没有审计抓手

本周其他进展

  • 深挖 workflow 原语（agent()、agent_session()）实现机理，确认 swarmflow 是薄封装
  • 修复解析器，追根溯源到」如何解析」这一层
  • 联通三个 skill 跑通，Deepsearch agent 设计验证完成

深入：给 skill 加一层只读 trace

核心方案是在 skill 的每个阶段边界、每个 agent 调用后，旁路写一份 trace 文件到 {workspace}/.trace/。

flowchart LR
    A[skill run 9 阶段] --> B[阶段边界 write_trace]
    B --> C[.trace/ 目录]
    C --> D[manifest.json 审计汇总]
    C --> E[按阶段编号子目录]
    E --> F[每个 agent 完整返回 JSON]

trace 目录按阶段编号落盘，结构清晰：

{workspace}/.trace/
├── 00_init.json                      # Init: tier/viewport/cfg
├── 01_research.json                  # Researcher 完整返回
├── 02_outline_approval.json          # HITL 审批结果
├── 03_design.json                    # Designer 返回
├── 04_generation/
│   ├── presenter_serial.json         # 串行模式
│   └── presenter_01_04.json          # 并行 chunk
├── 05_review.json                    # Review 汇总
├── 06_revision/                      # 每轮每页复检
├── 07_export_approval.json           # HITL
├── 08_export.json                    # Exporter 返回
└── manifest.json                     # 完整审计汇总

实现上有两条硬约束：

  1. 只读旁路：write_trace 只写文件，不改变任何控制流、schemas、原语调用。观测不能改变被观测对象的行为，否则 trace 不可信。
  2. trace 写 workspace，不写 skill 目录：skill 目录是只读的技能定义，workspace 才是运行时产物区。每次跑用不同 workspace，trace 互不污染。

效果：validator 0 error；stubbed 测试全过。卡住时 ls {workspace}/.trace/ 看最后写的文件，一眼定位停在哪一步哪个 agent。

沉淀

可观察性是多 agent 工作流从」能跑」到」可调」的分水岭。而可观察性设计本身有一条铁律：只读旁路，不改控制流。trace 是观测窗口，不是执行路径 —— 这条边界划对了，后面才敢放心加观测点。

参考资料