Agent harness 的验证不能只靠一次 live demo。

Live demo 能证明某条路径曾经跑通，但它不能证明产品能被安装、能在干净项目中工作、能加载 runtime skills、能找到 bridge files、能生成 trace、能处理 host application blocker。

SAH 这类产品需要分层验证。

为什么 headless smoke 必要

SketchUp 是桌面软件。每次验证都要求打开 live SketchUp，会让开发、CI 和回归检查变得很慢。

所以大部分产品逻辑应该能 headless 验证：

  • 项目初始化；
  • schema 和 manifest 校验；
  • project state inspection；
  • design rules 合并；
  • component metadata 读取；
  • bridge trace planning；
  • import manifest 和 evidence 结构；
  • release package 中的 runtime assets 是否存在。

Headless smoke 不是替代 live bridge，而是把“无需宿主软件也能验证的部分”尽量前移。

Live bridge 验证解决另一类问题

有些问题只有 live host application 能发现。

例如 SketchUp bridge 是否真的被加载，local bridge transport 是否可用，SketchUp 是否停在欢迎页、账号提示、更新提示或 license blocker，Ruby bridge 是否能执行 geometry operation，operation response 是否包含 entity ids 和 spatial delta，rollback 或 error 是否能结构化返回。

这类测试环境成本高，所以不应该承担所有验证。但它必须存在，否则产品可能只在 headless 世界里正确。

Source checkout 通过不等于用户可用

很多本地 agent 工具在源码目录里能跑，但打包安装后失败。

原因通常不是核心逻辑，而是边界资产：

  • runtime skills 不在包里；
  • Ruby bridge 文件没有被包含；
  • plugin manifest 指向源码路径；
  • templates 或 static assets 丢失；
  • CLI entry points 在 installed package 里不可用；
  • startup check 依赖维护者目录结构。

如果产品承诺设计师不需要 clone source repo，那么 installed package path 才更接近真实用户路径。

Release smoke 应该覆盖安装形态

Release smoke 的目标不是证明每个功能都完美，而是证明产品发布包没有破坏用户会触达的关键路径。

对 SAH 这类产品，至少要覆盖 package build、CLI entry points、packaged runtime skills、packaged Ruby bridge、plugin metadata、project initialization、headless validation、bridge install dry run、release check 和 installed package check。

这比单元测试更靠近用户体验。

Product facts 仍以 repo 为准

这篇不是命令教程，所以不列完整命令。具体命令、参数和运行环境应以产品 repo 当前 README、DEVELOPMENT 和 capability map 为准。

原因是验证命令变化很快。一旦写成 tutorial，就必须实际从当前产品状态跑一遍，否则 publication 会变成过时安装指南。

在 developer architecture 文章里，更重要的是让读者理解验证分层：

unit / contract
-> headless smoke
-> bridge install dry run
-> live bridge integration
-> release smoke
-> installed package smoke

这个模式可以复用

任何本地 agent harness 只要包含 runtime skills、plugins、host bridge、templates、CLI entry points，就会遇到类似问题。

源码可用只是维护者路径。安装可用才是用户路径。

如果一个产品的最大卖点是“用户在自己的项目目录里启动 agent”，那验证就必须从用户项目目录和安装包视角看，而不是只从源码仓库视角看。

Source trace