模式目录/横切工程面/X1
ADPS 横切工程面规范
X1 · Observability · 可观测性
以事件、因果、版本、状态差异和外部回执建立 Agent 证据链。
X1 用统一事件、因果标识、版本引用、状态差异和外部回执，把一次运行组织成可以查询、评测和归因的证据链。
位置
可观测性贯穿七个认知功能、六种执行拓扑和完整生命周期，不占用双轴矩阵格位。旧编号 G4 仅作为历史入口保留，当前规范编号为 X1。
从日志到证据
| 观察面 | 需要保留的事实 | 用途 |
|---|---|---|
| 输入与上下文 | 来源、版本、准入和丢弃原因 | 还原 Agent 当时能看到什么 |
| 决策与计划 | 目标、步骤、路由、候选和裁决摘要 | 分析漂移、路由和计划错误 |
| 动作与控制 | 工具、参数来源、身份、策略、审批和配额 | 审计与调用级归因 |
| 状态与结果 | 状态差异、外部回执、业务验收与人工修订 | 识别假成功和真实影响 |
| 运行基础 | 模型、提示词、Skill、知识、工具和策略版本 | 版本比较与回归定位 |
结构化决策摘要、候选、引用、工具调用和状态变化适合作为运行证据。完整隐式推理既不稳定，也会扩大敏感信息风险。
因果与身份链
principal → agent → workload → session → run → intent
→ approval → model/tool/sub-agent span → resource → outcomeTrace Context 负责跨进程传播，业务对象仍需要稳定 ID。一次重试可以产生新 span，不能因此生成新的业务意图或重复副作用。
生命周期中的证据
| 阶段 | 重点 |
|---|---|
| 登记与设计 | 负责人、能力版本、事件合同、敏感字段与保留周期 |
| 评测与灰度 | 样本、轨迹、版本差异、拒绝与回滚原因 |
| 运行 | 调用链、状态变化、外部结果、延迟、成本与策略裁决 |
| 复验与演进 | 故障簇、修改预测、回归结果、升降级与退役证据 |
常见失效
- 记录大量文本，却没有对象 ID、版本和状态差异；
- 把 HTTP 200 或 exit code 0 当成业务成功；
- 跨 Agent、队列和回调断链；
- 采样集中在简单任务；
- 敏感 prompt 和凭证无限留存；
- 把 X2 的评分判断混入 X1 的观测事实。
验证
检查 trace 连续性、身份与版本完整度、有副作用动作的外部结果确认、孤儿写操作、证据时延、采样偏差和敏感证据访问。覆盖跨进程、重试、恢复、模型 fallback、schema 升级和 collector 故障。
公开实现
DeerFlow Guardrail展示身份、授权裁决、RunJournal 与工具执行之间的公开代码路径。业务状态差异和外部结果由接入方补充。