13. 可观测性

Observability 描述 FlowNex 如何观测一次 Agent 任务从入口、编排、运行时、工具、知识、文件到最终结果的完整链路。

企业级 Agent 平台必须具备可解释和可排障能力。一次 Agent 回答不应只是“模型说了什么”，还应能回答“系统为什么这样做”。

13.1 日志规范

日志应覆盖所有核心服务：

  1. ai-claw-gateway。
  2. ai-app-runtime-gateway。
  3. ai-app-service。
  4. control-center。
  5. agent-domain-service。
  6. user-domain-service。
  7. agent-runtime-gateway。
  8. share-harness。
  9. AGFS Server。
  10. AGFS Metadata Service。

日志字段建议统一：

  1. traceId。
  2. tenantCode。
  3. userId。
  4. conversationId。
  5. taskId。
  6. messageId。
  7. runtimeInstanceId。
  8. eventType。
  9. errorCode。
  10. durationMs。
  11. capabilityCode。
  12. providerCode。
  13. adapterCode。

日志级别建议：

  1. INFO：关键业务事件。
  2. WARN：可降级异常、重试、权限裁剪、超时。
  3. ERROR：任务失败、状态不一致、数据持久化失败。
  4. DEBUG：开发环境详细上下文。

13.2 Trace 链路

Trace 用于串联跨服务请求。

核心 trace 头：

  1. X-Trace-Id。
  2. X-User-Id。
  3. 租户标识。
  4. Dubbo attachment 中的 trace 和 user 上下文。

一轮任务至少应串联：

ai-claw-gateway main request / ai-app-runtime-gateway application request
  -> control-center main interaction / ai-app-service application interaction
  -> control-center create task or invoke capability
  -> agent-domain-service persistence
  -> agent-runtime-gateway infer
  -> share-harness run
  -> runtime callback
  -> SSE push

Trace 不只用于技术排障，也用于审计和任务回放。

13.3 Runtime 事件

Runtime 事件是观察 Agent 执行过程的核心。

建议事件类型：

  1. task.started。
  2. planner.started。
  3. planner.completed。
  4. skill.recalled。
  5. skill.loaded。
  6. tool.started。
  7. tool.completed。
  8. knowledge.search.started。
  9. knowledge.search.completed。
  10. file.created。
  11. file.updated。
  12. checkpoint.created。
  13. checkpoint.rollback。
  14. task.completed。
  15. task.failed。

Runtime 事件有两类消费者：

  1. SSE 展示。
  2. 后台持久化和指标统计。

13.4 任务执行指标

任务执行指标用于观察 Agent 系统整体健康度。

建议指标：

  1. 任务总数。
  2. 成功任务数。
  3. 失败任务数。
  4. 取消任务数。
  5. 平均任务耗时。
  6. P95 / P99 任务耗时。
  7. 平均 Task Step 数。
  8. 平均模型调用次数。
  9. 平均工具调用次数。
  10. 平均 token 消耗。

按维度聚合：

  1. 租户。
  2. 用户。
  3. Agent。
  4. Skill。
  5. 渠道。
  6. 模型。
  7. 任务类型。

13.5 知识命中指标

知识命中指标用于判断知识库是否有效。

建议指标：

  1. 知识检索次数。
  2. 知识命中次数。
  3. 无命中次数。
  4. 检索超时次数。
  5. 平均检索耗时。
  6. 命中文档数。
  7. 最终引用片段数。
  8. 因权限裁剪的知识数。
  9. 因 Skill FORBIDDEN 裁剪的知识数。
  10. REQUIRED 知识缺失次数。

这些指标可以帮助管理员发现：

  1. 哪些知识库没人用。
  2. 哪些知识库经常无召回。
  3. 哪些 Skill 绑定知识过窄。
  4. 哪些知识权限配置不合理。
  5. 哪些知识需要更新或归档。

13.6 Skill 使用指标

Skill 使用指标用于运营企业 Agent 能力。

建议指标：

  1. Skill 曝光次数。
  2. Skill 命中次数。
  3. Skill 实际使用次数。
  4. Skill 任务成功率。
  5. Skill 任务失败率。
  6. 平均执行耗时。
  7. 平均 token 消耗。
  8. 关联知识命中率。
  9. 用户点赞率。
  10. 用户点踩率。

这些指标可以指导：

  1. 哪些 Skill 值得推广。
  2. 哪些 Skill 需要下线。
  3. 哪些 Skill 需要补充知识。
  4. 哪些 Skill 需要优化提示词或工具链。

13.7 AGFS 文件指标

AGFS 指标用于观察 Agent 文件系统健康度。

建议指标：

  1. 文件读次数。
  2. 文件写次数。
  3. 目录查询次数。
  4. 文件版本创建次数。
  5. checkpoint 创建次数。
  6. rollback 次数。
  7. Shadow Dir 命中次数。
  8. Version Tree 命中率。
  9. Metadata Service QPS。
  10. Object Storage 上传下载耗时。
  11. FUSE mount 成功率。
  12. 多 Agent 文件同步延迟。

AGFS 指标直接影响 Agent 任务体验。目录查询慢、文件同步延迟高、checkpoint 失败都会影响多 Agent 协作质量。

13.8 多 Agent 协作指标

多 Agent 指标用于观察复杂任务协作质量。

建议指标：

  1. Task Graph 创建数。
  2. 平均子任务数。
  3. 子任务成功率。
  4. 子任务重试次数。
  5. Handoff 次数。
  6. Reviewer 驳回次数。
  7. Synthesizer 合并失败次数。
  8. checkpoint rollback 次数。
  9. 多 Agent 总耗时。
  10. 多 Agent 相比单 Agent 的成功率提升。

这些指标用于判断多 Agent 是否真的提升了复杂任务完成质量，而不是增加系统复杂度。

13.8.1 接入能力的调用观测与质量评估

业务线 AI 应用和原子化 AI 能力接入后，FlowNex 需要新增按能力维度的观测体系。

能力调用 Trace 至少应覆盖：

  1. capabilityCode。
  2. capabilityVersion。
  3. providerCode。
  4. adapterCode。
  5. tenantCode。
  6. agentCode。
  7. skillCode。
  8. toolCode。
  9. 输入 Schema 版本。
  10. 输出 Schema 版本。
  11. 调用状态。
  12. 错误码和错误映射。
  13. 耗时。
  14. 重试次数。
  15. 降级策略。
  16. 成本或计量信息。

能力运营指标建议按以下维度聚合：

维度 指标
业务线 调用量、成功率、P95 耗时、错误分布、成本
能力 调用量、成功率、平均耗时、Schema 失败率、降级次数
Provider 可用率、超时率、重试次数、SLA 达成率
租户 开通能力数、使用活跃度、调用成本、失败 Top 能力
Agent / Skill 调用了哪些原子能力、对任务成功率的贡献、失败原因

对于高价值或高风险能力，还应接入自动回归测试：

  1. 维护标准输入输出样例。
  2. 在 Provider 或 Adapter 变更后自动回放。
  3. 对关键字段准确率、格式稳定性、耗时和错误率做评估。
  4. 将回归结果作为能力发布、灰度和回滚依据。

这样可以避免业务线能力“接进来了但不可运营”，也能帮助平台判断某个 Agent 失败到底来自模型、Skill、知识、Tool 还是外部 Capability。

13.8.2 Coze Loop 观测落地形态

FlowNex 在线运行观测可以结合 Coze Loop 产品落地，重点覆盖三类能力：

  1. 线上运行日志查询：通过 traceId 按入口串联 ai-claw-gateway 或 ai-app-runtime-gateway，并继续关联 ai-app-service、control-center、agent-runtime-gateway、share-harness 和 Provider 调用日志。
  2. 监控统计：按应用、租户、能力、Provider、模型、Agent、Skill 统计调用量、成功率、耗时、错误分布和成本。
  3. 自动回归测试：沉淀高价值任务和能力调用样例，在 Prompt、Skill、Provider Adapter 或模型配置变更后自动回放，辅助发布验收和回滚决策。

Coze Loop 观测闭环

将生产 Trace、指标看板和评测数据集组织成一条持续改进链路：线上问题可定位、能力质量可量化、发布变更可回归。

运行日志查询按 traceId、应用、能力和 Provider 定位调用详情。
监控统计聚合成功率、耗时、错误、成本和调用趋势。
自动回归测试将线上样例沉淀为评测集，支撑灰度和回滚。
Coze Loop 运行日志与 Trace 详情
运行日志与 Trace 详情用于查询线上任务、能力调用、Provider 请求和错误映射。
Coze Loop 监控统计看板
监控统计看板用于观察调用量、成功率、延迟分布、错误 Top 和能力运营趋势。
Coze Loop 自动回归测试数据集
自动回归测试数据集用于沉淀线上样例，并在模型、Skill、Adapter 变更后执行质量回放。

13.9 告警与排障

建议配置告警：

  1. Runtime 实例不可用。
  2. SSE 连接异常升高。
  3. 任务失败率异常。
  4. 模型调用超时。
  5. Tool 调用失败率异常。
  6. 知识检索超时。
  7. AGFS Metadata Service 延迟异常。
  8. AGFS checkpoint 失败。
  9. RocketMQ 消费堆积。
  10. MySQL 慢查询。

排障入口应支持按以下字段检索：

  1. traceId。
  2. taskId。
  3. conversationId。
  4. messageId。
  5. userId。
  6. skillCode。
  7. knowledgeAssetId。
  8. agfsFileId。