当 Agent 自己做 SRE：详解 ArkClaw 自动化可观测体系的工程实践

一、核心痛点：缺失的不单是图表，而是"观测设计"

对于熟悉 Grafana 大盘的研发同学而言，以下场景应该并不陌生：

接到稳定性需求后，翻阅 PRD 以提取 SLI，逐层查找代码接口与指标平台，之后手动拼写 PromQL 并反复调参，然而在上线后却发现一半图为空；
服务完成拆分后，原有 dashboard 迅速失效，难以实现复用；
事故排查时面对数十张监控图表，难以快速找出异常链路、故障层级，无法确定是否与近期发布有关。

这不是"不会用 Grafana"的问题，而是整个可观测体系缺少一条工程化主线。

当前大多数"AI 一键生成 Grafana"方案，往往仅聚焦于"将 PromQL 封装为 JSON"这一局部问题。而火山引擎所希望解决的，是以下五类系统性挑战：

因此，单纯生成 dashboard 并非最终目的，而是应该构建起一条从"产品语义 --- 架构链路 --- 指标语义 --- 面板 --- 告警 --- 治理"的完整闭环。

二、整体架构设计

火山引擎 ArkClaw 将上述体系划分为 8 个核心 Skill 模块，各层之间具备明确的输入、输出与契约规范：

1. SLI 建模层 ------ 从产品文档 / OpenAPI / 事故复盘里生成结构化 SLI Spec。

2. 架构链路建模层 ------ 从代码 + 配置 + API + 依赖联合提取拓扑与路径。

3. 数据源语义层 ------ 把 SLI 概念映射到真实 metric / query / datasource。

4. Dashboard 设计层 ------ 先做 IA（信息架构），再编译 Panel Spec，最后生成 Grafana JSON。

5. Dashboard 装配联调层 ------ 自动连数据源、跑 query、识别空图、自动修复、出验收报告。

6. 持续治理层 ------ Drift 检测、资产登记、Stale panel 清理，确保体系不"一次性"。

整套体系以产品能力为起点、以架构链路为骨架、以指标语义为桥梁、以 dashboard 和 alert 为落点、以持续治理为闭环。

三、8 层 Skill 体系详解

Skill 1：SLI 建模

结构化 SLI Spec 不仅包含 SLI 名称，更需明确目标、阈值、优先级、口径与适用范围等关键字段。

技能： sli-modeling-skill

输入： PRD / OpenAPI / 用户旅程 / 稳定性目标 / 事故复盘 / SLA 承诺

输出（SLI Spec 字段）：

为对齐火山引擎等业内实践，Skill 内置三项子能力：SLI 归一化 （避免不同文档生成重复 SLI）、SLI 分层 （用户体验 / 控制面 / 数据依赖三层）、Error Budget 预算分配。

💡 技能指南 byted-sol-stability-sli-modeling：

github.com/bytedance/a...

User

ruby 复制代码

给arkclaw设计服务SLI，参考87732下面所有子页面，确保user story覆盖率，比如文档
  https://www.volcengine.com/docs/87732/2272974

Agent

markdown 复制代码

按你要求做了 87732 子页面覆盖导向 的 SLI 设计。
已完成结果：
  - 覆盖版总文件（17 条 SLI）
  ~/sli-modeling-skill/output-arkclaw-coverage/arkclaw.sli-spec.coverage.all.json
  - 覆盖映射说明（user story ↔ 页面）
  ~/sli-modeling-skill/examples/arkclaw.story.coverage.mapping.md
  - 每条 user story 都有独立目录（含 sli-spec.json + sli-report.md）在
  ~/sli-modeling-skill/output-arkclaw-coverage/

  这 17 条覆盖了核心旅程：
  - 开通激活、任务发起与执行、任务延迟
  - 快捷指令/技能、会话检索
  - 文件上传处理/网盘、数据新鲜度
  - 协作项目成员
  - 云电脑/云浏览器
  - 联网搜索与外部依赖
  - 升级/重启/诊断/修复恢复
  - 备份恢复
  - 安全审计日志
  - 消息渠道与反馈
  - 计费续费生命周期
  - 配置治理（模型/技能/工具/插件）

实跑案例：

针对 ArkClaw 全量产品文档（87732 子页面共 17 个核心 user story），系统覆盖了开通激活、任务发起执行、文件上传、协作、云电脑、联网搜索、备份恢复、安全审计、计费续费等全部核心旅程。

Skill 2：架构链路建模

旨在将 SLI 与系统组件路径建立关联，通过代码 + 配置 + API + 依赖联合建模 ，输出三类链路：

👤 用户链路： 登录鉴权 → 创建空间 → 创建 Agent → 调用模型 → 执行工具 → 返回结果
🛠️ 控制面链路： 配置变更 → 资源下发 → 权限校验 → 限流配额 → 审计
📡 数据面链路： Ingress -> ECS -> OpenClaw gateway -> Lane Queue -> Agent Runtime -> Model Gateway → Tool Gateway

技能： architecture-path-extractor-skill

输入： 代码、API、配置、依赖、文档五类信号

输出： 组件粒度的拓扑与路径模型，覆盖六个维度

💡 技能指南 byted-sol-stability-architecture-path-extractor：

github.com/bytedance/a...

User

arduino 复制代码

架构链路提取，不用到代码行级，组件粒度即可，用于全链路观测大盘。先把源码下载下来https://github.com/openclaw/openclaw

Agent

markdown 复制代码

按组件粒度给你可直接做"全链路观测大盘"的版本：

  核心用户链路（同步主路径）
  1. 接入层（Ingress）
    - HTTP/WS 入口与升级
    - Gateway 启动主流程
  2. 鉴权与安全层（Auth/Security）
    - 网关鉴权与连接授权
    - 控制面限流与审计上下文
  3. 协议适配层（API Surfaces）
    - OpenAI/OpenResponses/Tools/Models
    - Tools invoke 适配
  4. 控制面层（Control Plane）
    - method 注册与 control-plane write
    - 配置写入触发重启/审计
  5. 执行调度层（Scheduler / Queue）
    - Lane queue 核心
    - Lane 并发配置（Main/Subagent/Cron）
    - Cron 入队
  6. Agent 运行层（Orchestration Runtime）
    - embedded agent 执行与 lane 绑定
  7. 插件与扩展层（Plugin Runtime）
    - 插件注册中心
    - 插件查找表/启动计划
    - gateway启动插件装载
  8. 通道层（Channels）
    - channel manager 生命周期
    - channel 归一化与 registry lookup
  9. 配置与状态层（Config/State）
    - runtime config
    - 启动配置快照与 auth surface 诊断
    - daemon/service 运行托管
  10. 可观测性层（Observability）
  - 启动/重启 trace
  - event loop 健康
  - diagnostics 扩展
  11. 任务与后台作业层（Task/Async Ops）
  - task registry/retention/store

  12. 生态扩展层（Extensions / Apps / SDK）
  - provider/channel/tool 扩展：extensions/*
  - SDK 契约：packages/plugin-sdk, packages/sdk
  - 终端侧 App：apps/ios, apps/android, apps/macos

  异步链路（lane queue 主体）
  - Producer：gateway methods / cron enqueue / agent nested tasks
  - Queue Core：command-queue（priority、warn-after、timeout、drain、clear/reset）
  - Lane 隔离：Main / Subagent / Cron / CronNested / Nested
  - Consumer：embedded runner、cron task executor、subagent
  execution
  - Backpressure/恢复：gatewayDraining、lane
  timeout、wait-for-active、reset-all-lanes

  控制面链路
  - 配置变更请求 → 控制面权限校验 → 控制面限流预算 → 审计记录 → 运行态更新/广播

  关键依赖组件（大盘依赖视图）
  - Gateway runtime（单点入口）
  - Command Queue / Lane Scheduler（异步核心）
  - Session/Config 持久化
  - Plugin registry & channel runtime
  - 外部模型/工具提供方
  - OTel 导出端点（如启用）

  主要风险点（组件级）
  - Gateway 单点风险：入口故障即全链路受影响
  - Lane 堵塞风险：队列积压、lane timeout、draining期间新任务拒绝
  - 鉴权/配对风险：rate limit 或 pairing 升级流导致连接失败峰值
  - 插件阶段降级风险：plugin stage 报错后跳过，可能"部分功能可用"但难感知
  - 外部依赖抖动：provider/tool慢导致主lane被占用

  观测埋点现状与缺口（用于大盘设计）
  - 已有：startup/restart trace、lane enqueue/dequeue/wait日志、安全审计日志、health/ready
  - 缺口（建议补齐为指标+追踪）：
    a. Gateway RED 指标：按接口族统计 RPS/错误率/延迟
    b. Lane 指标：lane depth、active count、wait p95、timeout count、clear/reset count
    c. 端到端 Trace：ingress → method dispatch → lane enqueue/start → model/tool invoke → response
    d. 异步时延拆分：enqueue-to-start、run duration、retry/timeout阶段
    e. 控制面审计结构化：权限决策/配置写入统一结构化事件而非仅文本日志
    f. 依赖健康：provider调用成功率与延迟、OTel导出成功率

实跑案例：

以 OpenClaw 仓库实跑结果为例，Skill 自动识别出接入层 → 鉴权安全层 → 协议适配层 → 控制面 → 调度队列层（Lane queue）→ Agent 运行层 → 插件运行时 → 通道层 → 配置状态层 → 可观测层 这条主路径，并定位到 src/gateway/server-http.ts:473、src/process/command-queue.ts:418 这种具体组件文件作为埋点锚点。

同时，系统主动识别埋点缺口，如：Gateway RED 指标缺失、Lane depth/wait p95 缺失、端到端 Trace 没有打通、控制面审计仍是文本日志而非结构化事件等问题，为 dashboard 设计前置补齐提供依据。

Skill 3：Dashboard 设计

dashboard 设计的核心在于信息架构，而非 JSON 格式本身。整体拆分为三层：

📑 Dashboard IA： 总览 / 核心链路 / 服务分层 / 依赖资源 / 错误分析 / 变更灰度容量
🧱 Panel Spec： 标题 / 图表类型 / 指标公式 / 维度 / 阈值 / drill-down / SLI 关联
📄 Grafana JSON： 最终格式输出

总览页需回答四个关键问题：

grafana-dashboard-design-skill 强约束输出 6 个固定页面：

总览页（Overview） ------ 必须回答 4 个问题：系统是否健康？哪条链路异常？异常来自哪个层？是否与发布/容量有关？
详情页 ------ 核心链路页 / 服务分层页 / 依赖资源页 / 错误分析页 / 变更灰度容量页

总览页布局模板化，参考火山引擎内部多个产品大盘最佳实践沉淀：

💡 技能指南 byted-sol-stability-grafana-dashboard-design：

github.com/bytedance/a...

实跑案例：

ArkClaw 大盘从初始 11 个 panel 逐步演进至 44 个 panel，涵盖 KPI、SLI 趋势、TopN、事件表与分层诊断，validation_passed 验证通过。

User

javascript 复制代码

给arkclaw服务做可观测大盘. sli和架构链路参考目录 ~/sli-modeling-skill/output-arkclaw-coverage~/architecture-path-extractor-skill/output-openclaw/openclaw/

Agent

markdown 复制代码

arkclaw 大盘已经生成好了。

  产物目录：~/grafana-dashboard-design-skill/output/openclaw

  包含 6 个文件：
  - dashboard-ia.json
  - panel-specs.json
  - grafana-dashboard.json
  - traceability.json
  - validation-report.json
  - evidence-index.enriched.json

  本次运行结果：
  - page_count = 6
  - panel_count = 11
  - validation_passed = true（errors=0, warnings=0）

  另外我顺手修了一个阻塞点：SLI 输入原先只支持dict，arkclaw.sli-spec.coverage.all.json 是 list，已在做兼容（支持 list payload + sli_name/target_slo/measurement/capability字段）。这样后续同类覆盖文件都能直接跑。

DashBoard 静态页预览：

Skill 4：dashboard 评审

生成 dashboard 只是第一步，如何量化其质量？ArkClaw 单独拆出一个 grafana-dashboard-review Skill，把火山稳定性团队多年沉淀的实践经验转化成覆盖 7 大维度、24 个细项、满分 100 分的量化评分体系：

评级： 🟢 A ≥ 90（样板级）/ 🟡 B 75--89 / 🟠 C 60--74 / 🔴 D < 60

💡 技能指南 byted-sol-stability-grafana-dashboard-review：

github.com/bytedance/a...

实跑案例：

ArkClaw SLI Dashboard 评审得分 82.5 / 100，评级 B。主要待优化项包括：2 个面板 PromQL 为占位 / 复制错误、缺少客户 / 集群模板变量、下钻跳转能力不足。建议优先完成以上优化后正式上线。

User

javascript 复制代码

评审grafana监控大盘，dashboard json如下~/Downloads/dashboard.final.json

Agent

javascript 复制代码

⏺  Grafana 大盘评审报告：ArkClaw SLI Dashboard

  • 链接：本地 JSON ~/Downloads/dashboard.final.json
  • 大盘 UID / Title： arkclaw-sli-v1  / ArkClaw SLI Dashboard
  • 评审时间：2026-05-29
  • 配置维度评分（§3A）：82.5 / 100  等级：B
  • 事故视角评分（§3B，基于配置推断）：9 / 10  等级：B

  --------

  ## 一、整体结论

  骨架与分层做得不错（顶部 SLI/SLO 摘要 + 异动事件 + 自身核心 + 强依赖两大主线、量率结合、变更 annotation、TOPN 视角齐全），目前存在三处待优化点，完善后体验与实用性还能进一步提升：
  (1) 2 个面板（约 5%）的 PromQL是占位/复制粘贴错误，需修正保证数据准确性；
  (2) 缺少客户、集群相关模板变量，现有TOPN租户维度实际按实例聚合，维度命名与统计口径需对齐优化；
  (3) 下钻跳转能力有待补充，建议增加跳转至日志中心、二级看板、Explore 的链接入口。
建议优先完成以上三点优化，打磨细节后即可正式上线。

Skill 5：数据源指标对接

该模块负责将"SLI 概念"映射至"真实指标源"，例如：

arduino 复制代码

请求成功率 = ?
  ├─ http_requests_total{code!~"5.."} ?
  ├─ 业务自定义 counter ?
  └─ gateway metric ?

Agent 执行延迟 = ?
  ├─ E2E latency ?
  ├─ orchestrator latency ?
  ├─ 模型响应 latency ?
  └─ tool execution latency ?

输出 Metric Mapping Spec：

💡 技能指南 byted-sol-stability-grafana-metric-explorer：

github.com/bytedance/a...

实跑案例：

ArkClaw 17 条 SLI 全部映射成功，置信度可量化，errors=0。低置信度项自动回写至"埋点缺口"清单，避免硬塞假 query 进 dashboard。

User

javascript 复制代码

探索grafana指标，完成arkclaw grafana 指标对接、测试、修复skill
- sli spc ~/sli-modeling-skill/output-arkclaw-coverage
- 稳定性指标说明文档 https://www.volcengine.com/docs/86845/2227894
- architecture spec目录 ~/architecture-path-extractor-skill/output-openclaw/openclaw/
- dashboard json ~/grafana-dashboard-design-skill/output/openclaw/grafana-dashboard.json

Agent

ini 复制代码

我先用你给的 arkclaw 输入跑一遍，定位失败点后直接修复并回归测试。

⏺ 我先核对你给的路径并把这些输入映射成可执行参数，然后直接跑起来定位问题。
⏺ 我先把你给的目录里可直接喂给 grafana-metric-explorer-skill的输入文件对齐出来，再立即跑一轮并修复报错。
⏺ 我先把你给的本地输入整合成可运行的 metric-explorer输入集，然后直接跑 skill、根据报错修复并复测。
⏺ 我先把你给的 arkclaw 资料转换成 metric-explorer可直接运行的输入集，然后跑联调测试并按结果修复 skill。
⏺ 我先补齐缺失输入文件并跑一次 arkclaw 的 metric-explorer，全程把失败点修到可用。

当前可交付结果已完成：Arkclaw 全量运行
  validation_passed=true，mapping_count=17，errors=0（output/arkclaw/validation-report.json）。

  已落地的关键修复：
  - 低置信度不再误标 missing_gap=none（gap_diagnoser.py）。
  - latency SLI 优先选 tempo/span 指标（semantic_mapper.py）。
  - correctness/availability 选型规则已加强（semantic_mapper.py）。
  - 回归测试已补并通过（test_semantic_mapper.py、test_gap_diagnoser.py，最近一次 8/8 通过）。

Skill 6：装配联调

实施环节采用 5 步流水线，确保 dashboard 真正"跑起来"：

💡 技能指南 byted-sol-stability-grafana-dashboard-assembly：

github.com/bytedance/a...

实跑案例：ArkClaw 联调结果 ------ panel_count=44 / target_count=44 / overall_pass=true / success_rate=1.0 / empty_panels=0 / error_query=0。

User

javascript 复制代码

完成arkclaw grafana dashboard装配与联调
- sli spc ~/sli-modeling-skill/output-arkclaw-coverage
- metrics spce目录 ~/grafana-metric-explorer-skill/output/arkclaw
- architecture spec目录 ~/architecture-path-extractor-skill/output-openclaw/openclaw/
- dashboard json ~/grafana-dashboard-design-skill/output/openclaw/grafana-dashboard.json

Agent

markdown 复制代码

已完成装配与联调，跑通了grafana-dashboard-assembly-skill。

  结果：
  - 输出目录：~/grafana-dashboard-assembly-skill/output/arkclaw
  - 运行结果：panel_count=44，target_count=44，overall_pass=true
  - 验收报告：acceptance-report.json 显示
    - success_rate: 1.0
    - empty_panels_count: 0
    - error_query_count: 0
    - overall_pass: true
  - 校验报告：validation-report.json 显示 errors:0，warnings: 0

  产物文件已生成齐全：
  - dashboard-assembled.json
  - validation-report.json
  - autofix-report.json
  - acceptance-report.json
  - traceability.json
  - evidence-index.enriched.json

Skill 7：发布验收

通过 BUA / Janus 验证 dashboard JSON 在 Grafana 中是否可访问、可查询、可过滤、可告警、可下钻。标准验收流程包括：

rust 复制代码

1. 使用 BUA / Janus 打开页面
2. 点击"+添加按钮"->"Import"->"upload Json file" 导入 dashboard
3. 获取 dashboard_url
4. 自动检查页面加载、变量、Panel 数据、报错状态
5. 切换时间范围与变量过滤
6. 校验 annotation / alert / drilldown
7. 生成验收报告
8. 失败时回传给 Dashboard 实现 Skill 自动修复

实跑案例：- 因定制化 Grafana 7.5 暂未开源

让每一次上传都有迹可循、让每一项坑都不必再踩第二次。

同时沉淀已知问题清单，确保经验可复用：

⚠️ #fileUpload 是唯一靠谱上传入口
⚠️ React Select 必须通过 fiber 找到 onMenuOpen 直接调
⚠️ Agent (Linux) 与 Chrome (macOS) 分离，必须用 Mac 绝对路径

User

javascript 复制代码

使用dashboard import经验把~/workspace/dashboard.final.json上传到https://<your-grafana-host>/dashboard/import，Prometheus那里填写cn-beijing-ArkClaw，然后overwrite

Agent

arduino 复制代码

验收grafana dashboard https://<your-grafana-host>/arkclaw-sli-dashboard 检查页面能否打开、变量是否有效、Panel 是否报错、空白、无数据、查询失败、过滤器是否失效。

编辑

Skill 8：持续治理

需要解决以下三类问题：

代码变更后 dashboard 如何同步更新： 服务拆分 / 新接口 / 旧 metric 下线 / label 漂移
新需求如何自动增量更新： 新增能力 → 自动补齐 SLI → 链路 → panel
dashboard 自身如何治理： 长期空图 / 长期重复 / 指标口径冲突

observability-asset-governance-skill 五项治理能力：

💡 技能指南 byted-sol-stability-observability-asset-governance：

github.com/bytedance/a...

实跑案例：

一次治理运行产出 total_findings=513（warnings 46），并输出 governance-summary.json 与 incremental-update-plan.json，每条增量动作均附带置信度，低置信度项自动转人工复核。

User

javascript 复制代码

完成可观测资产治理，grafana dashboard json 路径~/Downloads/dashboard.final.json --sli-spec ~/sli-modeling-skill/output/openclaw-api-stability/sli-spec.json

Agent

ini 复制代码

本次治理结果：

  - 输出目录：~/observability-asset-governance-skill/output/arkclaw-sli-dashboard
  - 汇总：governance-summary.json:1
    - total_findings=513
    - warnings=46
    - usage_analysis=1（这次有 1 条 usage 发现）
    - total_assets=168
    - total_incremental_actions=1
  - 增量动作：incremental-update-plan.json:1
    - 仅 1 条动作，SLI 为 OpenClaw API stability
  latency
    - 推荐
  query：sum(rate(request_success_total[5m]))
    - confidence=0.4（置信度偏低，建议人工复核）

四、核心价值

为什么这件事必须由 Agent 来做？不是因为"AI 火"，而是因为传统工具链根本做不到这件事：

跨语义对齐： 将 PRD 中的"会话创建可用率"对齐至代码中的 request_success_total 及指标平台中的 PromQL，是 LLM 特有的语义理解能力。
跨系统编排： 从代码仓 → 配置中心 → 指标平台 → Grafana → BUA → 告警平台，Skill 编排相较传统脚本具备更优的可演进性与可治理性。
跨时间持续演进： 代码、架构、产品、指标天天在变，唯有 Agent 才能在每次变更时自动刷新整套观测资产。
跨组织复用： 一套 Skill 体系，不同团队、不同产品都能直接复用，避免每个团队各搞一套监控规范。

传统监控解决"系统能不能被看到"，AI Agent 解决"系统能不能自己说出自己怎么了"。后者，是稳定性工程走向智能化的关键一步。