技能介绍

解决什么问题

Agent 调试一直有个痛点：它出错时，你面对的往往是「模型输出不对」这种最终结果，而中间发生了什么——哪一层推理耗时暴涨、为什么某条候选路径被否决、是否陷入了重复循环——全部黑盒。传统日志只能告诉你「调用失败了」，无法回答「在认知链路的哪一层、以什么节奏失败的」。这个技能面向七层认知架构，把 Agent 的执行过程拆成可追踪的 span 链，让每一层都有时间戳、状态和父子关系。

核心能力

它由五个模块组成：

SpanTracer：全链路 span 追踪。在 L1→L7 每一层埋点，记录耗时与状态，维护父子 span 关系，输出瀑布图时间线，并给出耗时 Top-N 的瓶颈定位。
DecisionRecorder：记录决策路径——推理过程、备选方案、最终选择，以及每个被弃选项的否决理由和置信度分数，支持节点级上下文回放。
MetricsCollector：基于 100 条滑动窗口计算 P50/P95/P99 延迟、成功/错误/阻塞率、token 消耗和工具调用频率热力图。
AnomalyDetector：按基线触发异常告警。内置规则包括死循环检测（同层连续相同操作 > 5 次，Critical）、延迟超过基线 3 倍、错误率翻倍，以及静默失败（总耗时 < 10ms 且 span 少于 3 个）。
TraceExporter：导出 JSON 结构化日志和 OpenTelemetry OTLP 兼容格式（traceId / spanId / parentSpanId），并自动生成追踪报告。

使用时可以直接跑自检脚本验证环境，也可以通过编程 API 嵌入现有 Agent 代码，或使用 CLI 模式做一次性分析。

适用边界

纯 Python 标准库实现（sqlite3、json、time、math、uuid、dataclasses），零外部依赖，但也意味着它面向 Python Agent 生态。
异常检测基于统计基线，冷启动阶段基线未建立前告警阈值参考意义有限，需要先积累足够样本。
静默失败规则（< 10ms、< 3 spans）针对快速失败场景，如果业务本身存在合法的短任务，需要自行调整触发条件。