Raindrop Workshop 完整指南:AI Agent 自修复闭环如何让 Claude Code 自动写 Eval 并修 Bug
Raindrop Workshop 完整指南:AI Agent 自修复闭环如何让 Claude Code 自动写 Eval 并修 Bug
Raindrop Workshop 是一个本地 Agent 调试器,也是构建 AI Agent 自修复闭环的关键工具:它把 Claude Code 的每一个 token、每一次工具调用、每一个决策实时流式呈现出来,并让 Claude 直接读取 trace、针对你的代码库编写 Eval(评估断言),再自动修复 Bug——写 Eval、跑 Agent、看失败、改代码、重跑,直到每条断言都通过。整个过程不需要人工盯守,形成一条完整的自修复闭环。
为什么你需要 AI Agent 自修复闭环?
如果你的 Agent 在生产中出了问题(比如工具调错、提示词失效),传统流程是:
- 翻日志找错误 → 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
/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 的自修复闭环,流程是:
- 看现场:Claude 用
get_run_outline+search_run找到那个错误的工具调用 span,用get_span_payload拿到完整输入输出作为证据。 - 标注:用
annotate在错误 span 上贴一个issue标注,写明"应调用 search_docs 却调用了 fetch_url"。 - 写 Eval:Claude 针对你的代码库写一条可执行断言(Eval),例如"当 query 涉及文档时,工具调用必须是
search_docs"。 - 修代码:Claude 修改 Agent 的系统提示词或工具选择逻辑。
- 自动重跑:调用
replay_run,Workshop 自动拉起回放 server、用原 trace 的上下文发起一次新 run,把新 trace 流回 Workshop。 - 断言检查: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 到底为什么出错"困扰的开发者来说,这是目前最轻量的自诊断方案之一。

