第 15 章 Research Brief：Observation 与状态感知

研究目标

建立“行动已经发出”与“目标状态已被重新观察”之间的工程边界。读者需要知道：日志文本、工具返回、页面点击成功、计数器变化和外部状态快照都是不同类型的信号；Harness 不能只根据最后一段自然语言就宣布目标完成。

本章会提出原创的观察记录（Observation Record）与快照契约（Snapshot Contract）模型。它们用于审查一次观察是否关联正确对象、字段是否完整、证据是否真的来自观察、是否足够新鲜、是否在行动后推进，以及观察到的状态是否能被当前任务解释。它们不是 OpenTelemetry、W3C Trace Context、Playwright 或任一监控平台的数据模型。

本章要回答的问题

1. 为什么“工具没有报错”“按钮已点击”和“业务目标完成”是三种不能互换的陈述？
2. 一个可用于下一步决策的观察最少要绑定哪些对象、时间与来源信息？
3. 如何区分事件日志、当前状态快照、历史轨迹、指标与最终验收证据？
4. 新鲜度、推进性和关联性各自阻止什么错误？为什么只有时间戳不足以证明重新观察？
5. 观察到预期外状态时，系统应如何保留未知与异常，而不是替模型猜测原因或直接重试？
6. 哪些问题应交给第 16 章反思、第 17 章评估、第 18 章恢复，而不能由观察记录假装解决？

一手来源与允许用途

ID	来源明确表达的内容	本章允许用途	禁止外推
CH15-REF-01	OpenTelemetry 的 Signals 文档列出 traces、metrics、logs、baggage 与 profiles 等不同类别，并分别链接其概念说明。	用作“系统信号并非单一日志文本”的一手生态例子；说明信号类别应被区分、带来源并按用途解释。	不把 OpenTelemetry 分类、字段、采样、导出、时钟、存储或可用性写成所有 Agent 的默认实现。
CH15-REF-02	W3C Trace Context 定义了用于传播分布式追踪上下文的标准 HTTP 头和值格式；traceparent 描述请求在追踪图中的位置，并有关于敏感信息和关联风险的注意事项。	用作“跨边界的观察需要可关联标识，且标识与敏感数据处理须分离”的限定实例。	不把本书的 correlationId 说成 traceparent，也不把关联、追踪或日志保留视为身份验证、授权或完整审计。
CH15-REF-03	Playwright 说明它会在操作前进行 actionability 检查；例如 locator.click() 会等待唯一元素、可见、稳定、接收事件和启用条件。	用作 UI 场景的限定例子：动作获得执行前条件并不等于业务目标状态已发生，点击后还需要独立观察。	不把产品默认等待行为外推为业务验收、所有浏览器工具的规则、固定超时或完整端到端成功。
CH15-REF-04	Playwright 的异步 web-first 断言会反复获取元素并检查条件，直至成功或断言超时；文档当前写明默认断言超时为 5 秒。	用作“观察可以是有超时边界的重复读取，而不是任意 sleep”的产品限定例子。	不采用 5 秒作为全书默认值，不将一次断言成功写成外部副作用、数据持久化或业务质量已被接受。

详细 URL、访问日期、动态复核要求与全局引用集成需求见 候选参考资料。

来源陈述与本书模型的分界

来源可支持的最小事实

• OpenTelemetry 的文档将 trace、metric、log 等呈现为不同信号类别；它不主张仅凭一种信号就能判定每一个业务结果。
• W3C Trace Context 提供一种跨服务传播追踪上下文的标准实例，也明确关联信息的存储与传播可能带来敏感信息和安全风险。
• Playwright 对操作前可执行条件与异步断言的重试检查有明确文档；这些行为都限定在该产品与相应 API 语境中。

本书工程扩展：Observation Record 与 Snapshot Contract

本书建议每个会影响下一步决策的观察都显式记录：

1. 关联（Correlation）： 此观察对应哪一次行动、哪个目标和哪段工作流，而不是只保留一行“成功”文本。
2. 来源（Source）： 它来自工具回读、受控测试断言、环境探针、人工输入还是推测性摘要；来源决定它能支持什么判断。
3. 快照（Snapshot）： 观察到的状态、最小证据摘要和可比较指纹。快照描述“此刻看到什么”，不替代完整历史轨迹。
4. 新鲜度（Freshness）： 该证据是否仍适合当前决定。新鲜度规则由任务与环境定义，不能从任一 SDK 默认超时推导。
5. 推进性（Advancement）： 行动之后是否真的获得新的、不同的可解释观察。单纯复制旧快照或重新展示旧日志不是行动后的确认。
6. 解释边界（Interpretation Boundary）： 观察到 pending、未知效果或未识别状态时，函数应保留结果和缺口，而不自行编造根因、授权重试或宣布失败已修复。

Observation Record、Snapshot Contract、fingerprint、freshness 与本文的状态码均为本书模型；具体系统可以采用事件流、数据库、浏览器断言、API 回读或人工审查等不同介质。

章节范围与非目标

本章讨论观察点选择、状态快照、关联、新鲜度、噪声抑制、未知效果与信号解释边界。它不：

• 部署 OpenTelemetry、Prometheus、日志平台、浏览器驱动、截图服务、追踪后端或真实监控告警；
• 调用 Playwright、浏览器、网络、文件、数据库、模型、Tool、云平台、消息队列、密钥或真实应用；
• 定义第 17 章的任务验收、质量评分、评估基准或“完成”结论；
• 定义第 18 章的重试次数、退避、补偿、回滚或升级策略；
• 以 Trace Context、关联 ID、状态文本或测试绿灯替代第 12 章权限、第 14 章审批、真实外部状态或安全审计。

计划正文结构

1. 从“动作已发出”到“状态已观察”： 分开动作前条件、动作请求、动作返回、目标观察和评估接受。
2. 观察记录与快照契约： 定义关联、目标、来源、观察状态、证据状态、新鲜度、指纹和未知效果。
3. 多类信号如何协作： 说明事件、日志、快照、指标和轨迹各回答什么；不创建“万能日志”。
4. 新鲜度、推进性与噪声： 防止用过期、重复、无关或推测性的信号推进工作流。
5. UI 场景：点击之后重新观察： 以 Playwright 文档作为限定参照，说明操作前可执行检查与点击后业务状态确认的边界。
6. 工程案例：提交表单后的状态确认： 以纯教学状态解释观察、等待、异常、未知效果和交接。

拟议图示、示例与验证边界

• 图示： 行动请求、受控目标、观察点、快照契约、决策器与下一步之间的反馈回路。图中必须显示：动作返回 不是 目标状态；字段缺失、陈旧或未推进只能在刷新证据或缩小范围后重新观察；未知效果、错配和未知状态会阻塞并停止或升级。
• 最小示例： 纯内存 assessObservationSnapshot，输入行动、观察契约、当前快照和可选前一快照；输出 observed、not_observed、needs_evidence 或 blocked。它不读取真实时间、UI、浏览器、日志或外部系统。
• 计划测试： 覆盖预期状态、关联或目标不匹配、字段缺失、过期状态、推测性证据、未知效果、同一观察对象的重复快照、跨行动/跨目标同指纹、已知但未匹配状态和未知状态。测试只证明教学函数的确定性输入输出。
• 计划案例： UI 测试 Agent 在点击提交按钮后，只有观察到关联且新鲜的状态快照才进入后续评估；案例不包含真实页面、截图、用户数据、请求或网络响应。

风险、待核验事项与写作要求

• TODO(verify)： OpenTelemetry 与 Playwright 网页是持续维护的资料。任何后续改写涉及 API、默认值、版本、断言、采样、导出、存储或支持范围时，必须重读当前官方页面。
• TODO(verify)： 若接入真实浏览器自动化，需按第 25 章和项目 E2E 规则运行浏览器交互；本章纯内存示例绝不替代 UI 验证。
• TODO(verify)： 若观察数据包含身份、请求参数、页面内容、日志或追踪头，需先定义数据最小化、脱敏、保留与访问控制；本章不提供合规结论。
• 任何无法关联、不能判定来源、无法说明新鲜度或效果仍未知的信号，都应保留为不确定性，而不是变成“成功”的措辞。

Research 完成检查

• [x] 研究问题、来源事实、本书模型与相邻章节边界已经分开。
• [x] 每项来源都记录了限定用途、访问日期与禁止外推范围。
• [x] 图示、教学示例、测试和 UI 案例均定义了不接触真实外部系统的边界。
• [x] 已把动态资料、真实 UI 验证和数据治理标记为后续重新核验项目。