ADPS 企业 Agent 系统蓝皮书 · 模式实践切片
G4 · 可观测性 Observability Harness · 东方屹腾执行型 Agent
模型、路由、工具和状态变化统一为语义事件，并按执行时间线关联。
证据边界：本页是完整案例的模式切片，记录特定系统约束下的实现选择。案例方提供的实现与效果信息未经过独立审计，不构成通用性能承诺。
| 字段 | 值 |
|---|---|
| 主模式 | G4 可观测性 Observability Harness（治理 × 编排） |
| 结合模式 | G5 钩子流水线 Hook Pipeline |
| 案例 | 上海东方屹腾科技 · HR/薪酬 SaaS · 服务 2 万+ 企业 · 执行型 Agent |
| 对应白皮书 | /zh/patterns/g4-observability-harness/ |
| 源 | 梁博 AICon 逐字稿第二章、PPT 7–8 页；第三章 Orchestrator、PPT 12 页 |
| 工程结论 | 把一次会话中的模型调用、路由、工具执行和状态变化统一为语义事件，并按时间线展示；控制流与界面呈现分开。 |
场景约束
一次执行型 Agent 请求会经过意图识别、网关路由、链式推理、ReAct、工具调用、记忆写入和回复合成。若系统只记录用户输入和最终回复，开发者无法判断偏差产生于哪个步骤。
东方屹腾在接通基本对话和附件上传后，即建设运行时事件与时间线，再增加后续能力。这样，每个新增模块都必须同时定义业务接口和观测接口。
本切片讨论的是系统运行过程对开发者和运维人员可见，与 Agent 对外部世界的感知属于不同概念。
事件模型
系统使用 Activity 表示有业务语义的运行步骤，Frame 表示步骤中的具体调用和状态变化。
Activity
activity_id
session_id
type
status
started_at
ended_at
frames[]
Frame
frame_id
model_or_tool
input_ref
output_ref
state_delta_ref
latency
token_or_cost
Activity 类型包括意图识别、意图网关路由、链式推理、ReAct 轮次、工具调用、审批等待和回复合成。事件使用统一 ID 关联 SessionNarrative、SessionState 和 Workspace 的变化。
时间线与权限
Web 界面按时间顺序显示 Activity，并允许展开 Frame。开发环境可以查看模型实际输入、接口输出、耗时和成本；生产环境按角色进行脱敏，只显示必要进度。提示词、业务参数和个人数据不应无差别暴露给终端用户。
用户侧可以看到长任务的阶段进度，并在允许的节点暂停。开发者侧可以查看完整调用链和状态变化。两种视图复用同一事件源，但字段权限不同。
控制与呈现分离
Orchestrator 只发布结构化活动事件，不处理 SSE、界面组件或打字机效果。外层 MessageHandler 订阅事件，并转换为流式输出。东方屹腾使用 Go 协程和通道实现发布订阅。
这种边界允许控制逻辑和展示逻辑独立演进。新增界面或输出协议不改 Orchestrator，新增能力只需发布符合契约的事件。
案例运行
薪资组配置请求的时间线可以依次显示：
意图识别
-> resolve 路由
-> Skill 召回
-> 模板匹配工具
-> 快照任务
-> 导入任务
-> 验收与回复
若结果异常，开发者可以检查意图信号、ReasonContext、工具参数来源、业务回执和节点验收结果。问题定位落到具体 Activity 和 Frame。
失效信号
- 只有原始日志，没有稳定的事件类型和关联 ID；
- 模型调用可见，工具和状态变化不可见；
- Orchestrator 同时处理编排和界面渲染；
- 开发视图与生产视图没有权限边界；
- 日志包含未脱敏的薪酬、身份或鉴权数据；
- 失败事件没有输入引用、输出引用或状态差异；
- 审批等待与恢复不在同一调用链中。
验证指标
- 运行步骤的语义事件覆盖率；
- Activity 到 Frame、状态变化和业务回执的关联完整率；
- 异常任务的平均定位时间；
- 无关联原始日志占比；
- 开发与生产字段权限测试通过率；
- 单次任务的观测存储成本和保留周期；
- 展示协议变更对 Orchestrator 的代码影响。
与白皮书的对应
G4 白皮书要求通过 Trace 还原完整执行链。东方屹腾以 Activity/Frame 作为事件抽象，以 MessageHandler 和 SSE 作为展示实现。G5 钩子流水线可在执行边界产生事件，G4 负责统一采集、关联和查询。
迁移条件
请求跨多个模型、工具和状态模块，且错误需要定位到具体步骤时，应在项目早期建立语义事件时间线。单步内容生成可以先使用平台 Trace，但仍应保留请求、模型版本、成本和错误信息。