Agent 工作流的 Preview & Trajectory 渐进式披露

Agent 工作流的 Preview & Trajectory 渐进式披露

概述

在 Agent 操作软件的长工作流中（如 3D 建模、视频编辑、CAD 设计），渐进式披露（Progressive Disclosure）模式让 Agent 在执行过程中逐步发布中间视觉/检查状态，支持人类实时监控进度和 Agent 自我检查结果正确性。

1. 核心问题

Agent 操作软件完成复杂任务时存在信息不对称：

• 人类不知道：Agent 正在做什么、做到哪一步了、中间结果看起来对不对
• Agent 不知道：当前结果是否符合预期，是否需要调整策略
• 事后检查太晚：30 分钟渲染完成后才发现第一步就错了

解决：让 Agent 在关键步骤后发布 Preview 快照，形成可追溯的 Command → Preview 轨迹。

2. Producer vs Consumer 角色分离

关键原则：

角色	命令	职责
Producer	cli-anything-<software> preview ...	与后端对话、执行渲染、发布 Bundle
Consumer	cli-hub previews ...	读取已发布的状态、提供 inspect/html/watch/open

Consumer 不渲染、不回放、不合成预览制品——它只是读取 Producer 已发布的状态。

3. 三层持久化模型

Preview 状态由三个独立对象组成：

3.1 Bundle Directory（不可变快照）

• 实现 preview-bundle/v1 协议的目录
• 包含：渲染产物（PNG/MP4/JSON）、清单文件、源指纹
• 不可变：一旦发布，不再修改
• 每个 capture 命令生成一个新 bundle

3.2 session.json（可变当前头）

• Live Preview 会话的当前状态
• 指向最新的 bundle
• 包含：会话目录路径、活跃状态、最后发布原因

3.3 trajectory.json（追加式历史）

• 命令到 Preview 的完整历史记录
• append-only：只追加，不修改已有条目
• 支持回放：重现 Agent 的完整操作轨迹
• 每条记录包含：命令、时间戳、bundle 路径、源指纹

4. 推荐 CLI 表面

如果 Harness 支持有意义的 Previewable 状态，应至少暴露：

命令	用途
preview recipes	列出可用的 Preview 配方
preview capture	执行新鲜渲染/导出，发布新 Bundle
preview latest	返回最新已有 Bundle，不渲染新的

根据软件语义可扩展：

命令	用途
preview diff	发布不可变的对比 Bundle
preview live start	创建 Live 会话并发布初始 Bundle
preview live push	向已有 Live 会话添加新 Bundle
preview live status	只读状态探测（Agent 高频调用）
preview live stop	停止发布，不删除已有历史

5. Agent-Cheap JSON 合约

所有 Preview 命令必须支持 --json。

5.1 preview capture --json 返回

{
  "_bundle_dir": "/path/to/bundle_003",
  "_manifest_path": "/path/to/bundle_003/manifest.json",
  "summary_path": "/path/to/bundle_003/summary.json",
  "artifacts": ["render.png", "scene.json"],
  "command": "object add-mesh --type sphere",
  "timestamp": "2026-05-31T10:30:00Z"
}

5.2 preview live status --json 返回

{
  "active": true,
  "session_dir": "/path/to/session_001",
  "session_path": "/path/to/session_001/session.json",
  "current_bundle": "bundle_007",
  "publish_reason": "mutation",
  "trajectory_summary": {
    "total_commands": 42,
    "latest": {
      "command": "render execute",
      "bundle": "bundle_007",
      "timestamp": "2026-05-31T10:45:00Z"
    }
  },
  "viewer_hints": {
    "inspect": "cli-hub previews inspect session_001",
    "html": "cli-hub previews html session_001",
    "watch": "cli-hub previews watch session_001",
    "open": "cli-hub previews open session_001"
  }
}

设计要点：trajectory_summary 让 Agent 无需读取整个 trajectory.json 即可理解当前状态。

6. 真实性原则

Preview 制品必须是对真实项目状态的诚实视图：

• 优先使用：真实后端的渲染/导出/检查路径
• 可用时：原生离屏导出或回放
• 禁止：用 Python 伪造渲染结果
• 禁止：屏幕抓取 GUI 窗口制造类图像产物
• 如果注入临时相机/灯光：在 Bundle 状态中标注并说明限制

核心理念：真实的 Preview 比好看的 Preview 更重要。Agent 需要可信赖的中间状态来决定下一步操作。

7. Live Preview 语义

Live Preview 是持续发布 Preview 的模式：

持久化保证：

• session.json 作为可变当前头
• 不可变的 Bundle 目录保存每个快照
• trajectory.json 作为追加式永久历史

8. 陷阱与对策

陷阱	对策
Agent 频繁读取 trajectory.json 浪费 Token	preview live status --json 返回紧凑 trajectory_summary
_bundle_dir 被当作永久身份使用	稳定回放锚定 session_dir + trajectory.json
Consumer 被误用为渲染路径	文档和示例中严格分离 Producer/Consumer 角色
Preview 伪造导致 Agent 误判	坚持真实性原则，所有 Preview 来自真实后端
Live 会话无状态探测开销大	preview live status 是轻量只读调用
缓存失效导致旧 Preview 误导	源指纹变化时强制重新 capture

9. 与其他模式的关联

• 与 面向 Agent 的 CLI 接口规范 关联：Preview 命令同样需要 --json 支持
• 与 Agent-Native 软件设计范式 关联：Preview 是 Agent-Native 设计中的可选但推荐的附加层
• 与 渐进式披露策略（common/context-management 中的 05-progressive-disclosure-strategy.md）关联：Preview Bundle 是上下文渐进式披露在视觉工作流中的具体应用