用途:为代码、工作流或 AI 执行路径设计跨领域的可观测性埋点,定义应存在哪些信号及其结构,而非搭建运行时仪表盘。适用于需要持久遥测契约的场景:应用事件与结构化日志、关键边界的指标与追踪、AI 执行遥测(技能调用、runner 执行、模型用量、token 计量),以及跨阶段交接的工作流级可观测性。
主要能力:先明确需要被观测的边界与运维/产品问题,再定义小型、带版本的事件 schema,包括事件类型、公共必填字段、模型与 token 计名字段、不可用数据的 null 规则及版本演进规则。AI 执行遥测建议使用规范字段名 model_name、token_input、token_output、token_total;runner 无法提供用量时记录 null 并说明来源限制,不得编造 token 值。
使用方式:在共享入口点埋点,优先用包装器、装饰器、中间件或上下文管理器,而非在各调用点散落日志;候选位置包括模型 runner 适配器、技能分发/调用边界、基准或评测执行包装器、工作流编排接缝。技能系统需区分两类信号:来自提供商或 runner 的真实模型用量,以及技能加载或延迟内容的精确字节/字符测量,二者不可混用。将信号采集与消费分离,本技能只定义并发出结构化事件,下游运维技能负责消费事件做分诊与告警。
输出与验证:产出 observability-spec(边界定义)与 execution-event-schema(带版本的事件定义)。仓库当前执行契约使用仅追加的 execution-observability.jsonl 产物,并由 scripts/summarize_execution_observability.py 定期汇总。完成前需验证评审者能回答:运行了哪个技能、用了哪个模型与 runner、消耗多少 token、加载或延迟了多少技能上下文字节与字符、时间花在哪里、链路在哪里失败或停止。
限制与反模式:避免指标堆砌、到处内联日志、把埋点与仪表盘混为一谈、编造用量数据、不做 schema 版本化、未测量先优化。安装面为 skills/.curated,规范源为 skills/cross-cutting/observability/SKILL.md,支持 npx skills add/update,打包与能力就绪度均为 beta。具体收费、价格与平台支持暂未提供。