第 15 章详细 Outline：Observation 与状态感知

章节契约

• 读者完成后能够： 为行动定义观察点；区分动作返回、事件、快照与验收；判断观察的关联、来源、新鲜度和推进性；把未知效果留在阻塞路径；为 UI 自动化设计点击后重新观察的最小闭环。
• 核心问题： 执行中的成功、失败、漂移、等待和副作用怎样变成可靠的可读信号，而不是最后一句模型文本？
• 非目标： 不实现真实监控、追踪、日志、浏览器、质量评估、故障恢复或生产告警。
• 前置依赖： 第 07 章 Memory、第 10 章 Workflow、第 11 章 Tool Use、第 12 章 Environment、第 14 章 Human-in-the-loop。
• 后续交接： 第 16 章使用观察轨迹形成可检验的反思；第 17 章决定观察是否足以接受结果；第 18 章再决定能否重试或恢复。

分节蓝图

15.1 从“已执行”到“已观察”

• 要回答的问题： 为什么调用没有抛错、页面接收点击与任务目标满足不是同一个事实？
• 论证路径： 先给出提交表单场景；列出四个不可合并的事件：请求发出、动作层返回、页面状态变化、业务验收；指出每一步需要不同证据。
• 必须出现的边界： 观察不是评估；观察到状态不是解释其根因；动作成功不证明外部效果。
• 交付物： “信号不能互换”对照表。

15.2 观察记录（Observation Record）与快照契约（Snapshot Contract）

• 要回答的问题： 哪些字段能使后续执行者知道“这是对哪个对象、何时、从哪里看到的什么”？
• 核心字段： correlationId、target、source、observedAt、state、evidenceStatus、freshness、fingerprint、可选 effectStatus。
• 论证路径： 字段逐一回答的问题 → 对应不可以推出的结论 → 缺字段时的保守出口。
• 本书模型声明： 字段名和状态码不是 Trace Context、OpenTelemetry 或浏览器工具 API。
• 交付物： 字段/用途/不可推导结论表。

15.3 信号分工：事件、日志、快照、指标与轨迹

• 要回答的问题： 何时需要一条事件，何时需要当前状态，何时需要趋势或因果路径？
• 来源锚点： 用 CH15-REF-01 说明 OpenTelemetry 官方文档中有多类信号；不为它们规定本书实现。
• 论证路径： 用“回答的问题”而非“存储产品”区分：事件记录发生、日志解释局部上下文、快照报告当前观察、指标指出趋势、轨迹关联多个步骤。
• 风险： 把日志当状态、把指标当单次动作证据、把趋势当个体结果、把截屏或模型摘要当无条件事实。
• 交付物： 观察点清单。

15.4 关联、新鲜度与推进性

• 要回答的问题： 为什么同一个目标的旧快照不能确认新行动？
• 来源锚点： CH15-REF-02 只作为关联上下文可传播的标准实例；隐私限制也进入安全边界。
• 论证路径： 关联错配 → 目标错配 → 过期 → 同一关联/目标中的未推进 → 未识别状态；另一个关联或目标的同名指纹不能参与推进判断。各自进入 blocked、needs_evidence 或 not_observed，不猜测故障原因。
• 交付物： 判断顺序表与快照质量等级。

15.5 UI 场景：点击之后的重新观察

• 要回答的问题： 如何避免“点击调用没有报错”被写成“表单已提交”？
• 来源锚点： CH15-REF-03 的 actionability 与 CH15-REF-04 的 web-first assertion 均限于 Playwright 文档。
• 论证路径： 点击前条件 → 点击请求 → 等待明确目标状态 → 重新读取目标 → 将观察交给评估；说明自动等待不等于业务验收。
• 案例限制： 不在本章运行浏览器，不伪造截图、DOM、网络响应或 UI 成功结果。
• 交付物： 受限 UI 测试 Agent 案例表。

15.6 最小示例与逐步增强

• 教学函数： assessObservationSnapshot。
• 输入： 注入的 action、observationContract、snapshot、可选 previousSnapshot。
• 输出： observed、not_observed、needs_evidence、blocked；只表达教学对象的判断。
• 测试： 十二条互不重复的路径，覆盖完整观察、关联/目标错配、缺字段、陈旧、推测、未知效果、同一观察对象的未推进、跨行动/跨目标同指纹、已知未匹配与未知状态。
• 增强触发： 需要真实 UI 才接入第 25 章的浏览器验证；需要业务完成判断才接入第 17 章；需要恢复才接入第 18 章。

15.7 工程案例、错误与安全边界

• 工程案例： 虚构提交页面：关联点击行动与状态区域快照；pending 是观察而非失败原因，submitted 是观察而非最终验收。
• 常见错误： 以点击返回代替状态、复用旧快照、没有目标/关联、把推测标为观察、用任意 sleep、让状态记录携带敏感数据。
• 安全边界： 关联标识不得夹带凭证/个人数据；快照最小化；未知效果不能由重试或模型推测覆盖。
• 交付物： 错误表、安全检查表、练习与来源说明。

图示规范

• 文件： diagrams/mermaid/chapter-15-observation-feedback-loop.mmd。
• 问题： 一次行动如何经由目标重新观察、快照契约和解释边界进入后续决策？
• 关键箭头： Action Request → Target（候选行为，不代表效果）；Target → Observation Point（重新读取）；Observation Point → Snapshot Contract（字段校验）；Snapshot Contract → Decision（解释）；字段缺失/陈旧/未推进 → 刷新证据或缩小范围 → Re-observe；未知效果/错配 → Blocked → 停止或升级。
• 禁止表达： 图不能暗示真实浏览器、日志平台、权限、审批、外部系统、完成验收或自动重试已经发生。

预计交付物与验收

工件	路径	完成条件
正文	15-observation-and-state-awareness.md	原创正文包含目标、案例、边界、引用、图示、示例和练习。
Research Brief	15-observation-and-state-awareness.research.md	来源事实与本书模型分离，动态资料有重查要求。
局部来源	15-observation-and-state-awareness.references.md	URL、用途、外推禁区和全局集成需求明确。
示例	examples/agent/observation-snapshot-assessment.*	无副作用、可运行、12 条测试路径和演示均有真实结果。
图示	chapter-15-observation-feedback-loop.*	Mermaid 源、SVG/PNG、正文图块和读图说明一致。
审查	.memory/reviews/2026-07-16-chapter-15-*.md	技术、示例、图示、语言、事实和终审边界完整。