mcpField
O
oodle-o11y-context

oodle-o11y-context

github.com/oodle-ai云与 DevOps0112 次安装3 周前更新
代码仓库

关于 oodle-o11y-context

此技能定义 PR 描述中的 O11y Change Context 清单格式，用于记录变更类型、涉及服务、遥测意图和风险线索。它作为编写、审查和告警排查阶段之间的共享约定。

主要功能

  1. 01定义结构化变更上下文清单
  2. 02记录变更类型、服务和遥测信号
  3. 03说明遥测信号的用途
  4. 04通过生命周期连接审查与告警排查
  5. 05规定字段名称和格式稳定性

适用场景

  1. 01为相关 PR 添加可解析的观测性背景
  2. 02在变更审查时核验遥测和告警覆盖
  3. 03告警触发后依据近期变更线索排查

MCP 相关

清单可在排查阶段通过 GitHub 或 Linear MCP 读取 PR 描述；没有 GitHub MCP 时，可使用 `gh` CLI。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oodle-ai/agent-skills --skill oodle-o11y-context

安装后在 Claude Code 中输入/oodle-o11y-context确认已加载。

详细介绍

O11y 变更上下文 — 清单主干

此技能只定义一件事：O11y 变更上下文清单，这是一个小型结构化区块，由编写 Agent 写入拉取请求描述。它是可观测性闭环的连接纽带——左侧的审查者 (oodle-o11y-review) 会对其进行补充，右侧的分诊流程 (oodle-triage) 则会在告警触发时读取它。此技能不涉及如何埋点；它是其他两个技能引用的共享约定。

仅在确有必要时编写此区块（参见相关性判断）。 它的价值在于，让变更的可观测性意图从编写之时一直保留到它在生产环境中出问题之时。

区块

将此围栏区块放入 PR 描述中。## O11y Change Context 标题和字段键必须完全按原样保留——下游 Agent 会根据这种格式定位并解析区块。

## O11y Change Context
type: perf, bugfix                 # bugfix | perf | feature | critical-path | refactor | infra
touches: checkout-svc, order-repo  # deploy/service units changed
telemetry:
  + span checkout.place_order {attr: tenant, order_id}   — trace slow orders per tenant
  ~ metric checkout_latency_seconds (histogram)          — widened buckets; guards SLO
  - metric checkout_legacy_timer                          — removed; duplicate of above
guarded-by: SLO checkout-p99, monitor HighCheckoutLatency  # existing alerts over touched code
watch: N+1 on order lookup under load; cache hit-rate regression
gaps: no per-item span in the loop — deferred (cardinality); triage can't attribute per-SKU
  • telemetry 行以 +（新增）、~（变更）或 -（移除）开头， 后接信号和简短的用途。如果无法说明某个信号的用途，它很可能就不该存在。
  • 仅当字段确实没有内容时才省略（例如，没有 gaps）。 绝不要重命名字段。

字段参考

字段含义填写者对下游的重要性
type变更性质作者决定审查和分诊的审查力度。critical-path 会触发最深入的审查。
touches变更涉及的部署／服务单元作者分诊时会将触发的告警所对应的服务与此处的近期变更相匹配。
telemetry新增／变更／移除的信号及其用途作者（起草）、审查（核实）确保“每个信号都有用途，且没有重复项”。
guarded-by覆盖所涉及代码的现有告警／SLO审查（从后端解析）在分诊时确认告警↔代码的关联；标记高风险变更。
watch部署后需要关注的风险假设作者 + 审查分诊会首先查看此项——优先假设已预先写好。
gaps有意未添加的遥测数据审查告知分诊哪些问题无法通过数据回答，从而避免继续追查。

生命周期

  1. 作者起草——在创建 PR 时填写 type、touches、telemetry 和 watch。
  2. 审查补充——oodle-o11y-review 从实时后端解析 guarded-by，追加 gaps；如果所涉及的代码受关键 SLO 覆盖，还可以将 type 升级为 critical-path。
  3. 合并——此区块会保留在 PR 历史中。
  4. 分诊读取——触发告警时，oodle-triage 会查找近期触及告警服务的 PR，并读取其清单：watch 和 type 会聚焦调查方向，guarded-by 会确认告警↔代码的关联，而 gaps 则会解释缺失的证据。

相关性判断

当变更涉及已埋点代码或服务代码，或者其 type 为 perf、critical-path 或 bugfix 时，编写此区块。纯文档、纯配置外观调整或其他琐碎变更可以跳过——空洞的例行区块只会带来噪声。 审查技能会对相关性作出最终判断；如有疑问，宁可写一个简短区块，也不要完全不写。

承载位置

在 v1 中，清单仅存放在 PR 描述中，并在分诊时通过 GitHub 或 Linear MCP 读取；如果没有 GitHub MCP，则通过 gh CLI（gh pr list、gh pr view）读取。持久化的 git commit trailer 和纳入版本控制的仓库内清单文件会被有意暂缓处理——仅当分诊经常无法找到已部署提交对应的 PR 时再重新考虑。

稳定性约定

## O11y Change Context 标题和字段键 （type、touches、telemetry、guarded-by、watch、gaps）构成解析约定。其他技能和未来的自动化会根据它们进行匹配——不要重命名字段，也不要调整字段顺序。 添加新的可选字段是安全的；重命名现有字段则属于破坏性变更。

评论

支持 Markdown