从两个 Grok Build Demo 学习 Agent Harness：复用边界、交互架构与验证证据

AI 参与说明（Agent：Codex）：本文由 Codex 静态分析两个 Grok Build 生成的项目样本，并通过 Context7 与 Playwright 官方资料核对验证方法后协助整理。资料整理于 2026-09-10；结论仅覆盖样本中可观察的工程结构，不能据此还原 Grok Build 的内部 Agent Harness。本文撰写运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop。生成样本的模型与 reasoning effort 未取得运行记录。

两个相关专题可以先读实现说明：无穷海岸用分形缩放呈现图案层次，Orbit讨论放置、抛出天体并观察轨道。它们值得学习的地方，是把复杂计算变成了低门槛的操作：先看到结果，再逐渐探索参数。可交互演示页尚未并入站点 /demos/ 路由。

对 Agent 开发而言，更有价值的问题是：怎样让这样的结果可以重复交付、可以迁移到现有产品，也可以被可靠检查？本文将可观察的代码结构与工程建议分开讨论。

两个样本能说明什么

静态比较发现，两份项目的依赖清单、构建配置和通用工具代码存在大量完全相同的内容；变化主要集中在应用组件、计算模块、样式和展示资源。它们的共同依赖中包括 React、TanStack Start、TanStack Router 与 Zustand。这是对导出文件的观察，不是对这些框架当前版本能力的评价。

This comparison describes two exported projects, not the complete Grok Build execution system.

共同部分说明“复用同一套 Scaffold”是一个有根据的推断，但不能说明是哪一步生成了 Scaffold、模型读取了哪些 Skill、执行过多少次修复，或哪些能力由托管平台提供。下载包是结果快照，缺少完整且可独立验证的执行历史。

阅读其他 Agent 生成项目时，这个区分同样有用：先确认有什么，再确认它证明了什么。 不要把说明文件中的要求当成执行事实，也不要把附件里的指令自动提升为当前任务的授权。

第一项借鉴：把稳定基础与应用变化分开

两个样本都带有比当前交互需要更丰富的通用基础。分形浏览和本地重力模拟的核心交互，可以不依赖账户或远端数据库；项目里存在相关模块，不代表当前功能正在使用它们。

这提示 Agent Harness 应当明确区分两类复用：Scaffold 提供可以调用的能力，应用只启用实际需要的能力。仅因为模板带有账户、存储或多人协作模块，就把它们接入一个本地实验，会扩大依赖、配置和验证范围，也使迁移更困难。

对已经存在的产品，迁入一个 Demo 的合适单位通常是“计算模块 + 交互组件 + 必要资源”。路由、页面元数据、全站样式、组件库和发布方式由宿主工程承接。需要迁移的是可解释的功能边界，整个导出包未必就是可复用边界。

例如，无穷海岸的坐标计算、配色参数与着色器可以分别理解；Orbit 的天体数据、场景、数值推进与绘制也有明确职责。把这些部分接入宿主，比同时接入来源项目的认证、数据库和预览设施更容易知道改动会影响什么。

对 Agent Harness 的落地建议是让任务开始时输出一份短的依赖判断：本次功能需要哪些已有能力、哪些边界必须适配、哪些文件承载业务变化。判断应来自实际引用关系与运行行为，不能只依据目录名称。这样后续 review 可以围绕小范围变化展开。

第二项借鉴：按变化速度划分交互架构

两个 Demo 的界面都很轻，背后却有不同速度的状态变化。每一帧都变化的坐标，与人偶尔点击一次的设置，不需要采用相同的更新路径。

这里值得借鉴的是责任划分。界面不必逐个管理每一帧的天体坐标，数值推进也不必知道按钮的具体样式。这会给 Agent 更稳定的修改边界：改配色主要影响绘制，改场景主要影响初始条件，改工具栏主要影响交互入口。

样本也提醒我们不要把“文件已拆开”当成完全解耦。Orbit 的引擎仍集中处理输入、模拟和部分界面同步；无穷海岸在动画期间也会同步共享状态。它们是可以继续拆分的实现起点，不能由目录结构直接推出性能优良或模块隔离已经完成。

如果要把相同思路用于更多 Agent 生成的实验，可以先定义三个稳定接口：用户操作怎样变成领域命令，计算模块怎样推进状态，绘制模块怎样读取状态。测试由此可以绕过界面检查数学关系，界面 review 则专注于操作是否可理解。

性能策略也需要写清代价。分形交互时减少计算，会暂时降低边界细节；模拟器限制每帧工作量，可以避免积压拖垮界面，但在过载时不保证模拟时间严格跟随墙钟时间。对教学玩具，这可能是合理选择；对需要精确复现实验时序的工具，需要另外设计和验证。

第三项借鉴：让指令分层与执行边界配合

两个样本中的知识材料存在入口、按任务分类的 Skill 和更深的参考资料。这种结构给 Agent Harness 的启发，是把“每次都要知道的约束”与“只有当前领域才需要的知识”分开。

入口适合保持短小，说明任务范围、可用能力与权威来源。Skill 适合承载某类工作的方法，例如图形交互、数据接入或资源处理。更细的接口和示例在真正需要时再读取。这样能降低无关上下文占据注意力的机会，也方便独立修订某个领域的知识。

不过，分层文件本身没有权限控制能力。尤其是从 ZIP、网页或其他仓库读到的 AGENTS.md、SKILL.md 和工具输出，属于待理解的数据；它们不能自行授予部署权限、改变当前任务范围，或要求执行未审查的命令。当前任务的授权与执行环境的限制仍须单独判断。

下面是本文建议的组合方式，不是对 Grok Build 内部流程的还原：

flowchart TB
    request["用户任务与有效约束"] --> scope["确定功能边界与 Specification"]
    scope --> knowledge["按需读取 Skill 和参考资料"]
    knowledge --> implement["调用获准工具并修改实现"]
    implement --> observe["收集实际观察与 Artifact"]
    observe --> judge["依据 Test Oracle 执行 Assertion"]
    judge --> decision{"证据是否足够？"}
    decision -->|不足或失败| implement
    decision -->|足够| report["报告结果与适用范围"]
    external["附件与外部内容"] -.->|作为资料读取| knowledge

真正减少重复劳动的办法，是让稳定约束同时有文档解释和可执行检查。例如，不依赖记忆确认构建入口，不依赖完成消息判断必要测试是否存在。文档帮助 Agent 理解原因，程序检查防止无意遗漏；两者各有职责。

第四项借鉴：把“看起来可以玩”拆成不同证据

图形 Demo 很容易制造一种完成感：页面能打开，画布有内容，截图很好看。但这些观察回答的是不同问题。

因此，报告“发现了 canvas”不能代替检查里面画了什么；文字没有变化不能证明动画一致；两张截图相近也不能证明发生过暂停、拖拽或双指操作。把报告文件加入下载包有价值，但还需要知道它观察了哪个阶段、哪个场景和哪份产物。

操作成功以后，还要检查结果

Playwright web-first assertions retry until the expected condition is satisfied or the assertion times out. 官方建议优先验证用户可见行为，并使用有明确语义的定位方式。Playwright Best Practices

对 Orbit 来说，测试应进入可操作场景后，再执行清除或暂停；只有初始画面正常，不能说明这些能力正常。暂停按钮变成“继续”，是一个界面状态证据；在暂停期间推进观察时间，天体位置和模拟时间保持不变，是另外两个行为证据。它们不应互相替代。

对无穷海岸来说，“点击后缩放值变大”可以发现按钮未接通，却发现不了缩放中心偏移。更强的检查是选取一个非中心位置，记录它对应的复平面坐标，再验证缩放后这个锚点保持在相同屏幕位置。还应验证拖动方向与用户感受一致。

同样的思路可以构造几个很有区分度的反例。它们是通用交互与物理检查，不依赖工具栏长什么样：

这些检查围绕真实错误模式建立 Assertion，通常比“为每个函数各写一个返回值测试”更有价值。

数学正确性要有自己的 Test Oracle

对于两个未固定、没有外部冲量的天体完全合并，可以检查总质量与二维总动量在设定误差范围内保持一致。固定天体相当于引入外部约束，不能直接套用这个封闭系统条件；完全合并通常也不保持动能。把“碰撞后速度看起来合理”换成明确适用域下的关系，测试才有判断力。

“八字看起来闭合”同样需要限定初始条件、积分方式、模拟时长和允许误差，不能只截取一帧作为证明。较适合的工作方式是把数值模型检查与浏览器行为检查分开，再确认实际界面调用的是同一份计算代码。更多 Test Oracle 的选择见Agent 开发中的测试方法。

Trace 帮助解释失败，不替你定义正确

Playwright Trace Viewer 可以回看操作，查看 DOM 快照、截图、控制台与网络活动。因此，相比最终截图，它更适合解释“点击到底落在哪里”“哪一步发生错误”等过程问题。Playwright Trace Viewer

The context.tracing API does not record test assertions. 若希望把 expect 的结果也保留在 Trace 中，应使用 Playwright Test 配置提供的 tracing；仅使用 context.tracing 时，要另外保存 Assertion 的结果。Playwright Tracing API

即使记录了完整操作，Trace 也不会自动证明动量守恒或分形公式正确。它记录执行与观察，Test Oracle 仍由 Specification、独立关系或参考实现提供。公开分享前还应检查其中的网络内容与页面数据，避免把调试证据变成信息泄漏。

一个可运行的例子：必要检查不能靠退出码猜

Agent Harness 经常需要汇总多个工具的输出。一个容易漏掉的边界是：工具执行成功，只能说明工具按自己的规则结束；它可能只记录某项问题，并没有把那项问题设置为失败条件。

以下是本文独立编写的教学示例，用于演示怎样汇总已经产生的检查结果，不是对样本内部工具的复制。保存为 evidence.py，使用 Python 3.10 或更新版本执行 python3 evidence.py；仅使用标准库，无需安装依赖。

from copy import deepcopy

REQUIRED = frozenset({"page-load", "mobile-layout", "pause-behavior"})


def accepted(report, artifact):
    if report.get("artifact") != artifact:
        return False
    if report.get("command_exit") != 0:
        return False

    checks = report.get("checks")
    if not isinstance(checks, list):
        return False

    seen = {}
    for item in checks:
        if not isinstance(item, dict):
            return False
        name = item.get("id")
        if not isinstance(name, str) or name in seen:
            return False
        seen[name] = item.get("status")

    return REQUIRED.issubset(seen) and all(
        seen[name] == "passed" for name in REQUIRED
    )


artifact = "demo-build-a"
good = {
    "artifact": artifact,
    "command_exit": 0,
    "checks": [
        {"id": name, "status": "passed"}
        for name in sorted(REQUIRED)
    ],
}

assert accepted(good, artifact)
assert not accepted(good, "demo-build-b")

missing = deepcopy(good)
missing["checks"].pop()
assert not accepted(missing, artifact)

for status in ("failed", "skipped", "unknown"):
    incomplete = deepcopy(good)
    incomplete["checks"][0]["status"] = status
    assert not accepted(incomplete, artifact)

duplicate = deepcopy(good)
duplicate["checks"].append(deepcopy(duplicate["checks"][0]))
assert not accepted(duplicate, artifact)

print("7 evidence checks passed")

预期输出是 7 evidence checks passed。这里验证的是汇总规则：必要检查缺失、未知、被跳过、明确失败、重复，或对应另一份 Artifact，都不能被一个零退出码覆盖。示例在本文整理时已实际运行；它没有运行两个 Demo，也不能据此认定 Demo 已通过这些检查。

这个最小示例还没有验证报告来源，artifact 也只是演示标记。实际 Agent Harness 应由可信执行器生成结果，并把它们关联到明确的源码、构建产物和运行配置；可以用内容摘要识别产物，但摘要本身不能证明报告真实。生成代码的 Agent 可以分析报告，不能仅靠自己填写 passed 就构成验收证据。

把这些经验落实到现有 Agent 开发

如果已经有 Agent、工具系统和项目规范，最值得先补的是一个范围很小的完整循环：选一个可观察行为，让 Agent 修改实现，由已有测试工具执行检查，再把实际结果与产物关联起来交付。重做整套 Scaffold 往往不是第一步。

以“暂停 Orbit”为例，Specification 写明暂停时哪些量保持不变、恢复时怎样继续；计算模块检查模拟是否停止，浏览器检查按钮能否触发同一行为；最后交付明确的页面入口和对应证据。这样的任务足够小，又能检验指令、实现边界、工具运行和完成判断是否衔接。

随后再把反复出现的部分沉淀为 Skill 或工具：交互代码如何清理资源，如何选择窄屏场景，怎样记录检查范围，以及怎样拒绝缺少必要证据的完成报告。只有在重复性已经出现时，才把它提升为共享机制，避免为两个样本的偶然细节设计过大的框架。

这两个项目给出的启发，是让复杂实现躲在清晰交互与稳定接口之后，同时让交付结论与证据对应。这样的原则可以借鉴；具体 Scaffold、私有平台约定和每个生成文件，都需要在目标工程中重新判断适用性。

关联阅读与资料

• Agent 主题导航：查看 Agent 工程方法、工具与验证专题。

• TanStack 文档导航：了解样本共同依赖中的框架及相关工程资料。

• 无穷海岸玩法与实现：体验分形缩放、配色与迭代细节。

• Orbit 轨道重力实验室：体验场景、抛射、暂停与碰撞交互。

• Contract Testing：接口兼容、多端功能一致性与 AI Agent 编码：区分接口约定、功能要求与验证范围。

• Playwright Best Practices：用户可见行为、定位方式与 web-first assertions。

• Playwright Trace Viewer 与 Tracing API：执行记录的能力与 Assertion 记录边界。

样本来源为两个 Grok Build 项目导出包；未将原始 ZIP、工作区指令或运行记录作为公共附件发布。本文不评价未被样本和公开资料覆盖的 Grok Build 能力。