Raindrop Workshop 完整指南:AI Agent 自修复闭环如何让 Claude Code 自动写 Eval 并修 Bug

原创2026-10-16 06:53:35693 阅读

Raindrop Workshop 完整指南:AI Agent 自修复闭环如何让 Claude Code 自动写 Eval 并修 Bug

Raindrop Workshop 是一个本地 Agent 调试器,也是构建 AI Agent 自修复闭环的关键工具:它把 Claude Code 的每一个 token、每一次工具调用、每一个决策实时流式呈现出来,并让 Claude 直接读取 trace、针对你的代码库编写 Eval(评估断言),再自动修复 Bug——写 Eval、跑 Agent、看失败、改代码、重跑,直到每条断言都通过。整个过程不需要人工盯守,形成一条完整的自修复闭环。

Raindrop Workshop 项目横幅:本地 Agent 调试器标语

为什么你需要 AI Agent 自修复闭环?

如果你的 Agent 在生产中出了问题(比如工具调错、提示词失效),传统流程是:

  1. 翻日志找错误 → 2. 复现问题 → 3. 手写测试 → 4. 修代码 → 5. 重跑验证

每一步都要人肉操作,Agent 自己却无法"看见"自己的运行过程。

Workshop 的思路是反过来:让 Claude Code 既是被调试的 Agent,也是调试者本身。它通过 MCP(Model Context Protocol)工具读取本地 trace 数据库,看到自己的每一次 LLM 调用和工具执行,于是能:

  • 📖 看懂自己的失败现场(哪个 span 出错、输入输出是什么)
  • ✍️ 写出针对代码库的 Eval 断言("这次修复后必须通过")
  • 🔁 自动重跑(Local Replay),修一行代码再验一次
  • 🛡️ 标注(Annotation)关键证据,留档可查

这就是"自修复闭环"(Self-healing eval loop):Claude 写 Eval → 跑 Agent → 看到失败 → 修代码 → 重跑,直到每条断言通过。

三步上手:最快配置方法

第一步:一键安装 Workshop

无需 clone 仓库、无需构建,一行命令即可:

curl -fsSL https://raindrop.sh/install | bash

该命令安装 raindrop CLI,之后 raindrop workshop 即可启动本地守护进程并在浏览器打开 UI(默认端口 5899)。如果你正在用 Claude Code,直接把这条命令告诉它执行即可。

💡 若只想体验本地 Workshop 而不连云,拒绝安装流程最后一步的 Raindrop Cloud 提示即可。

第二步:给你的 Agent 埋点(Raindrop Tracing)

在你的 Agent 仓库里打开 Claude Code,运行内置技能命令:

/instrument-agent

这一步会调用 skills/instrument-agent/SKILL.md 中定义的技能:它先扫描你的仓库,识别语言/运行时/SDK(TypeScript、Python、Go、Rust 均支持),然后自动安装对应版本的 raindrop-ai SDK,在 Agent 入口注入最小的埋点,最后启动一次真实调用验证 Workshop 里能看到数据。

技能文档里明确要求"最小改动 + 可见进度"——不会为了埋点重写你的遥测体系,也不会悄悄装完依赖就宣布成功,必须真的在 UI 里看到一次 run 才算完成。

Workshop 内置的像素风 Agent 聊天助手形象

第三步:让 Workshop 能回放你的 Agent

/setup-agent-replay

这一步由 skills/setup-agent-replay/SKILL.md 驱动,会:

  • 在项目根目录写入 .raindrop/agents.yaml(声明回放端口、命令、输入结构)
  • 按你的语言约定生成一个最小的回放 server(暴露 GET /health 与 POST /replay)
  • 运行 raindrop replay register 把项目注册到本地注册表
  • 验证一次测试回放,确认 trace 真的流回 Workshop

完整机制可以在设计文档 app/replay-plan.md 里看到:Workshop 守护进程会通过本地注册表找到你项目的回放 server,必要时自动拉起,并把 trace 上下文(用户消息、系统提示、模型、上下文变量)预填进去再发起回放。

自修复闭环全景:Claude Code 如何"看见"自己

安装完成后,Workshop 会自动向 Claude Code 注入一组 MCP 工具(定义见 src/mcp/tools.ts)。Claude 在调试时不需要人肉翻日志,它直接调用这些工具:

MCP 工具 作用 典型使用场景
get_current_run 拿到当前 UI 聚焦的那次 run 和选中的 span 用户说"这条 trace 怎么回事"
query_traces 对本地 SQLite trace 库执行只读 SQL 统计、过滤、发现可疑 run
get_run_outline 拿 run 的骨架:span 类型分布、工具调用、错误短列表 快速理解一次 run 的形状
search_run 在 span 输入/输出、live event 里做子串或正则搜索 定位"报错字符串到底在哪出现"
get_span_payload 读取单个 span 的完整输入/输出 payload 拿到证据级细节
annotate 在 run/span 上留下 issue/good/note 标注 给关键证据贴标签、留档
replay_run 触发本地回放:启动回放 server、预填上下文、等它跑完 闭环核心——修完代码后自动重跑验证
ask_agent 让被捕获的 Agent 上下文自己解释/续跑 拿到"第一视角"的调试结论

这些工具全部通过后端 HTTP 接口(src/replay.ts 中的 runReplay 等)与 Workshop 守护进程通信,不依赖云端服务,本地即可完成整条链路。

一个完整的自修复循环长什么样?

假设你的 Agent 在生产上出了个 Bug:应该调用 search_docs 工具却调用了 fetch_url。用 Workshop 的自修复闭环,流程是:

  1. 看现场:Claude 用 get_run_outline + search_run 找到那个错误的工具调用 span,用 get_span_payload 拿到完整输入输出作为证据。
  2. 标注:用 annotate 在错误 span 上贴一个 issue 标注,写明"应调用 search_docs 却调用了 fetch_url"。
  3. 写 Eval:Claude 针对你的代码库写一条可执行断言(Eval),例如"当 query 涉及文档时,工具调用必须是 search_docs"。
  4. 修代码:Claude 修改 Agent 的系统提示词或工具选择逻辑。
  5. 自动重跑:调用 replay_run,Workshop 自动拉起回放 server、用原 trace 的上下文发起一次新 run,把新 trace 流回 Workshop。
  6. 断言检查:Claude 再用 MCP 工具读新 run,验证 Eval 是否通过。没通过就回到第 3 步,直到全部断言通过。

整个过程不需要人肉复制粘贴日志、也不需要手动写测试脚本——Eval 由 Agent 自己写、失败由 Agent 自己看、修复由 Agent 自己改、验证由 Replay 自动跑。

与常见 AI 可观测方案的差别

维度 传统 APM / LLM 观测平台 Raindrop Workshop
运行位置 云端 SaaS 本地守护进程,trace 不出本机
谁在调试 人 Claude Code 通过 MCP 工具自己调试
能否回放 通常只能"看" 可以拉起真实 Agent 代码重跑
闭环能力 需人工写测试 Agent 自动写 Eval 并迭代到通过
语言覆盖 多依赖 SDK TypeScript / Python / Go / Rust 全栈

Workshop 兼容几乎所有主流 SDK 与编码 Agent(Claude Code、Codex、Cursor、OpenCode 等),支持 AWS Bedrock、Azure OpenAI、Vertex AI 等 Provider,因此自修复闭环可以覆盖你现有的技术栈,无需大改。

常见问题(FAQ)

Q1:Workshop 会不会把我的 trace 传到云端? 默认不会。本地模式下,trace 只写入本机 SQLite(默认 ~/.raindrop/raindrop_workshop.db),MCP 工具也全部访问本地后端。只有你主动执行 raindrop cloud setup 才会连接 Raindrop Cloud。

Q2:我已经有一套 OpenTelemetry / Sentry,会不会冲突? 不会。/instrument-agent 技能明确要求"尊重现有遥测归属",优先走 SDK 提供的"外部 OpenTelemetry"接入方式,不会重复创建全局 TracerProvider。

Q3:回放会不会写我的生产数据库? 不会。/setup-agent-replay 技能明确要求回放 server 尽量无副作用——优先用依赖注入、dry-run 标志、事务回滚或 no-op 适配器,避免写业务库、计费、队列、邮件等。

Q4:Claude 写出来的 Eval 可靠吗? Eval 是针对你代码库的可执行断言,会在 Replay 中真实执行。你可以随时用 annotate 把不满意的 Eval 标为 issue,让 Claude 重写。闭环本身就是"跑一次验一次",所以不靠谱会立即被暴露。

关键源码与文档索引

路径 说明
skills/instrument-agent/SKILL.md 埋点技能完整工作流(分 Phase 0/1/2)
skills/setup-agent-replay/SKILL.md 回放 server 生成与注册规范
src/mcp/tools.ts 暴露给 Claude Code 的全部 MCP 工具定义
src/replay.ts 本地回放调度入口(runReplay)
app/replay-plan.md 回放系统设计文档(含时序图)
examples/README.md 12 个端到端示例:OpenAI / AI SDK / Python / Go / Rust 等
examples/shared/workshop.ts 示例项目共享的 Workshop 连接层

小结

Raindrop Workshop 把"看 trace"这件事从人的活儿变成了 Claude Code 的活儿,再叠加 Local Replay,就拼出了一条完整的 AI Agent 自修复闭环:读 trace → 写 Eval → 修代码 → 重跑验证 → 断言通过。你只需要在 Agent 仓库里敲两次斜杠命令(/instrument-agent 和 /setup-agent-replay),剩下的闭环由 Claude 自己完成。对于正在做生产级 AI 功能、又被"Agent 到底为什么出错"困扰的开发者来说,这是目前最轻量的自诊断方案之一。

登录后查看全文
workshop