1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | agent-observability-replay-trace-datadog-labs-agent-skills |
| 作者/维护者 | Datadog（datadog-labs 官方组织） |
| 来源链接 | https://github.com/datadog-labs/agent-skills/tree/main/agent-observability/agent-observability-replay-trace |
| 许可证 | MIT（GitHub API 获取，仓库级） |
| GitHub Stars / Forks | 合集仓库整体 146 / 19（GitHub API 获取；该数字属整个 agent-skills 合集，不代表本技能自身热度，取证方式见第 7 章） |
| 最新版本 | SKILL.md 未声明版本号；子目录最近一次提交为 2026-07-21（GitHub API 获取） |
| 安装方式 | npx skills add 命令行安装（详见第 10 章） |
2. 功能介绍与亮点
针对一条“输出不满意”的生产 trace，提供一个可反复迭代的本地调试循环：取出该 trace 的原始输出作为基线，按需修改本地代码，重新运行同一入口生成新 trace，再给出新旧输出的简明对比，如此往复直到满意为止——全程无需起本地服务器或打开浏览器。
- 交互式选择器把关，而非一路狂奔：每次提出代码改动后、每次看完 diff 后都会停下来给出选项（继续改 / 重放 / 到此为止），不会替用户擅自连续执行
- 重放前显式风险提示：文档明确写明重放会真实重跑用户自己的 agent 代码，可能产生真实的模型调用花费以及数据库、邮件、队列等真实副作用，要求首次重放前必须获得用户确认
- 比“跑一次完整实验”更轻量：区别于同仓库的实验评分流程，本技能不需要额外的 App Key，也不绑定 Python 专属的 Experiments SDK，理论上可用于任意已埋点语言
- 隶属 Datadog 官方 Agent Observability 技能家族——该家族于 2026-06-30 通过官方博客与文档站正式介绍；本技能是家族中较新加入的成员，子目录最近一次提交为 2026-07-21
3. 适用场景
所属分类：DevOps 与基础设施
适合已用 ddtrace / LLM Obs 完成埋点、生产环境正在产生 trace 数据的 AI 应用开发者：当某条 trace 的输出不符合预期，想在编码 agent 对话里直接“改代码 → 重放 → 看差异”来验证修复是否生效，而不必手动复制 trace 输入、另写脚本、肉眼比对新旧输出。
4. 跨 Agent 兼容性
- Claude Code：原生支持——官方文档站专文 “Analyze LLM Applications with Claude Code Skills” 即以 Claude Code 为例给出安装与调用方式
- Codex：官方支持——仓库 README 顶部明确写 “Datadog skills for Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, OpenCode, and other AI agents”
- OpenClaw：未验证——抓取材料未点名
- Hermes Agent：未验证——抓取材料未点名
5. 推荐理由
把“这条 trace 输出不对 → 改代码 → 重新跑一遍 → 对比新旧结果”这个开发者原本要手动来回折腾的循环，做成有确认节点、每步可控的 agent 工作流，比人工凭肉眼在两段 trace 输出之间找差异更系统，也更不容易漏看重放可能带来的真实副作用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Datadog 官方出品（datadog-labs），所属 Agent Observability 家族在官方博客（2026-06-30）与文档站均有正式介绍；但本技能自身子目录目前仅 2 次提交、单一作者，暂无独立于官方渠道的第三方讨论 |
| 可用性 | 8 | 需预先完成 ddtrace/LLM Obs 埋点、连接 datadog-llmo MCP 并配置 DD_API_KEY/DD_SITE，非纯离线开箱即用；但 SKILL.md 文档详尽（完整分步 workflow、故障排查、示例触发短语），子目录最近一次提交为 2026-07-21，维护很新 |
| 安全性 | 8 | 见下方检查清单 |
| 综合 | 7.7 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 不执行任意 shell 命令，而是运行按模板生成的 runner 脚本重新调用用户自己项目的入口函数，属于在用户自有开发环境里重跑自己代码，用途明确 |
| ② 联网外发 | 通过 datadog-llmo MCP 读写用户自己 Datadog 账号下的 trace 数据，目标透明，未见第三方外发地址 |
| ③ 凭据存储 | 依赖 DD_API_KEY/DD_SITE 及模型厂商密钥，走用户现有环境变量配置，技能本身不要求粘贴明文凭据、不落盘存储 |
| ④ 可疑指令 | 抓取的 SKILL.md 全文未发现提示注入或隐蔽指令；相反文档明确要求“重放前必须先取得用户确认”这类保护性设计 |
| ⑤ 作者信誉 | Datadog 为知名上市可观测性公司，datadog-labs 为其官方 GitHub 组织 |
| ⑥ License | MIT，明确（仓库级） |
| ⑦ 维护时间 | 本技能子目录最近一次提交为 2026-07-21，所属家族其余成员在 2026-07-21～23 期间有密集提交 |
7. 跟同类 Skills 相比的优势
| 方案 | 定位 | 差异 |
|---|---|---|
| agent-observability-replay-trace（本技能） | Agent skill：本地重放 + diff 迭代循环，每步选择器确认 | 直接在编码 agent 对话里发起，自动生成 runner 脚本、自动轮询新 trace 到达、自动给出前后差异摘要 |
| agent-observability-trace-rca（同仓库姊妹技能） | Agent skill：对失败 trace 做根因分析报告 | 只诊断、出报告，不修改代码也不重放，无法验证“改完是否真的修好了” |
| LangSmith / Langfuse 的 “Compare Runs” 功能 | LLM 可观测性平台内置网页 UI | 需要打开浏览器手动选取两次运行做对比，不是 agent skill，无法从编码 agent 对话内直接发起“改代码 - 重放 - 看差异”的迭代循环 |
8. 用户评价
该技能是 Datadog Agent Observability 家族中较新加入的成员，目前在第三方平台尚无独立的具名用户评价。
9. 其他补充
同一 agent-observability/ 目录下还有 trace-rca（根因分析）、session-classify（会话满意度分类）、eval-bootstrap（从生产 trace 生成评估器）等姊妹技能，可按需单独安装。
10. 安装使用方式
# 前置：目标 AI 应用需已用 ddtrace / LLM Obs 完成埋点并正在产生 trace
# 连接 Datadog 官方 MCP（读取/搜索 trace 数据需要）
claude mcp add --scope user --transport http datadog-llmo-mcp \
'https://mcp.datadoghq.com/v1/mcp?toolsets=llmobs'
# 安装本技能
npx skills add datadog-labs/agent-skills \
--skill agent-observability-replay-trace \
--full-depth -y安装后无需重启；在编码 agent 对话中输入 /agent-observability-replay-trace <trace-id> [想测试的改动] 即可触发，agent 会读取该 trace 的原始输出、按需修改代码、重放并给出前后差异摘要。
11. 注意事项
- 必须先有
DD_API_KEY/DD_SITE及已埋点的 LLM Obs 应用，纯离线或未接入 Datadog 的项目无法使用 - 重放会真实重跑用户自己的 agent 代码，可能产生真实的模型调用花费及数据库、邮件、队列等真实副作用，技能本身会在首次重放前提示确认
- 目前对 Python（
ddtraceSDK）支持最完整，其他语言需要 agent 临场学习该语言的构建/运行方式，存在一定不确定性 - OpenClaw / Hermes Agent 兼容性未见官方声明，跨 agent 使用前建议自行验证