BioTender · 手搓实录
真实记录——用Claude Code手搓一个蛋白设计智能体
从RFDiffusion到Boltz-2，手搓一套零点击蛋白设计全自动Pipeline的完整踩坑记录
从RFDiffusion到Boltz-2，手搓一套零点击蛋白设计全自动Pipeline的完整踩坑记录
凌晨两点，指令只有一句话："帮我设计一个能结合锌离子的蛋白，用4个骨架，每个骨架6条序列。"六分钟后，屏幕上跳出一排pLDDT数字，全部超过93，极高置信度。中间没有人点过一次"下一步"。RFDiffusion 吐出骨架，ProteinMPNN 自动把候选序列跑了个遍，Boltz-2 挨个验证，Qwen3.6-27B 挑出前三名并写好了改进建议。整条链路，从骨架到结构验证，零点击。
这不是调用哪家公司的蛋白质设计 API。这是一套完全长在自己内网 HPC 集群里的东西，代号 BioTender Assistant，是用 Claude Code 一行一行"手搓"出来的。这篇文章记录它是怎么被搭起来的——包括那些让人半夜想砸键盘的 bug，以及最后是怎么被 Claude Code 揪出来的。
动手之前先想清楚一件事：让语言模型"自己设计蛋白质"，本质上不是训练一个新模型，而是把一堆各自独立的专业工具，用一个会规划、会调度的大脑串起来。工作台最终长这样——一个大脑，四件称手的工具：
硬件是三台通过 Tailscale 组内网的机器：一台 CPU 服务器 master 跑 FastAPI 后端和 API 路由；gpu01（RTX 4090）专职跑四个计算工具的推理；gpu02（A100 80GB）专门给 Qwen3.6-27B 用 vLLM 撑起一个 OpenAI 兼容接口。没有花哨的编排框架，三台机器靠最朴素的 SSH/SCP/HTTP 接起来，够用就是好架构。
Qwen3.6-27B 本身不知道什么是 RFDiffusion。要让它"会用"这些工具，第一步是把每个工具包装成 OpenAI 格式的 function calling 定义：
后端用 FastAPI 撑起一组对应的接口。每个任务都扔进 BackgroundTasks 异步执行，状态存在内存字典 JOBS 里，前端轮询 /api/status/{job_id} 拿进度，完事之后用 /api/result/{id} 下载 PDB 文件。整套设计的哲学很朴素：后端只管把重活甩给 GPU 节点，脏活累活留给大脑去调度。
光有工具还不够，真正的难点是让 AI 在拿到一个结果后，自己判断"接下来该干什么"，而不是每一步都要人点一下"继续"。
这靠两轮对话接口撑起来：/api/chat 负责第一轮，Qwen 决定调用哪个工具；/api/chat/resume 负责把工具结果喂回去，让 Qwen 决定是链式调用下一个工具还是收工写总结。一条完整的自动流程长这样：
generate_backbonedesign_sequencesvalidate_structure
这条链路能不能真的"自动"跑下去，几乎全靠一份写得够狠的 SYSTEM_PROMPT。三条硬约束缺一不可：第一，先解释后执行——调工具前必须先说明设计意图和参数选择理由；第二，链式自动调用——拿到工具结果之后立刻调下一步，不等用户确认；第三，批量验证指引——明确要求从序列结果里挑 score 最低的三条，作为列表传进验证工具。没有这三条约束，模型要么调用一次就停下来等指令，要么一次只验证一条序列，整条流水线根本跑不完。
AI 说完计划就立刻触发骨架生成，对话区弹出工具完成卡片，mol* viewer 同步渲染骨架的 3D 结构：
拿到骨架 job_id 之后，AI 在 thinking 里推断参数含义，随即自动调用 design_sequences，112 条候选序列全局按 score 排序，界面展示来源骨架编号：
Boltz-2 批量验证 top-3 序列：
AI 输出综合分析，发现问题并主动给出改进方向：
全程耗时约 6 分钟，零次点击，最优候选 Sequence 1 的 pLDDT 达 93.8。
| 步骤 | 工具 | 输出 | 耗时 |
|---|---|---|---|
| 骨架生成 | RFDiffusion | 4 个 100aa 骨架 PDB | ~90秒 |
| 序列设计 | ProteinMPNN | 112 条候选，全局按 score 排序 | ~40秒 |
| 批量验证 | Boltz-2 | top-3 pLDDT：93.8 / 93+ / 93+ | ~3分钟 |
| 综合分析 | Qwen3.6-27B | 候选推荐 + Motif Scaffolding 改进建议 | ~30秒 |
把这套系统从"能跑通一次"改造成"零点击全自动"，中间踩的坑比想象中密集。以下六个是最典型的——每一个都靠 Claude Code 逐层排查日志、对照代码、定位到具体行才解决。记下来是因为它们背后的教训比 bug 本身更值钱。
现象：用了 CDN 上 highlight.js 的 CommonJS 格式（lib/core.min.js），浏览器里直接报 module is not defined。渲染 Markdown 时抛出异常被外层 try-catch 悄悄吞掉，后续工具调用逻辑根本没被触发——骨架生成完之后，流水线就这么没声没息地停了，连报错都看不见。
解法：换成 cdnjs 上的浏览器版本 highlight.min.js，再在高亮调用外套一层 try-catch 做降级保护。
现象：SFTP 写文件时，split('\n') 里的转义序列被写成了真实的 0x0A 字节，JS 字符串字面量里混进真换行符，整个 <script> 块解析失败——所有前端函数全部变成 undefined，页面彻底罢工，连点击都没反应。
解法：上 Python 做字节级搜索替换，把误写进去的 [0x0a] 精确换回 [0x5c, 0x6e]（转义序列本身）。
现象：pip install openfold 装到的只是 0.0.1 占位包，真正能用的 openfold 需要现场 CUDA 编译，在现有环境里根本装不起来，验证工具一调用就报 ModuleNotFoundError。
解法：不再纠结装环境，直接把 run_esmfold() 函数体换成调用 run_boltz()——输出同样是 pLDDT，接口完全兼容，改一个函数体，问题就没了。
现象：Qwen 在 thinking 模式下把调工具前的说明文字写进 <think>...</think> 标签里，后端硬编码返回 text: ""——"先解释后执行"这条约束表面上生效了，用户却完全看不到 AI 说了什么。
解法：把完整内容取出来，用正则去掉 think 标签，剩下的纯文字部分才是真正要展示的说明。
现象：骨架生成跑完之后，前端会在对话区插入一个"下一步：ProteinMPNN 设计序列"的按钮，得等用户手动点一下才触发——这跟"零点击自动流程"的设计目标直接矛盾。
解法：把这个按钮插入逻辑整个删掉，骨架生成完成后直接把结果传给下一层处理函数，自动继续走下一步。
现象：验证工具参数是单数 sequence，AI 只能选一条去验证；往上查，run_mpnn() 只取第一个骨架，四个骨架跑完 RFDiffusion 之后，只有第一个真正被 ProteinMPNN 设计了序列。
解法：两处一起改：工具参数从单数改成列表 sequences，后端逐条调用 Boltz-2 按 pLDDT 降序返回；run_mpnn() 改成遍历所有骨架，每条序列标注 backbone_idx，全局按 score 排序。
这六个 bug 有个共同点——没有一个是模型不够聪明导致的，全部出在"胶水层"：CDN 版本、字节编码、依赖安装、字段解析、交互逻辑、参数形状。用 Claude Code 手搓 agent 的大部分时间，其实花在这些看起来最不起眼的接缝上；调度大脑越"聪明"，越需要胶水层稳，一处松动就会让整条链路在用户完全无感的情况下悄悄断掉。
回头看这套系统最值钱的部分，可能不是四个工具本身，而是那条把它们串起来的、写得足够狠的 SYSTEM_PROMPT，和六个被 Claude Code 一个一个揪出来的胶水层 bug。工具会变——RFDiffusion 换成别的骨架生成模型，Boltz-2 换成下一代结构预测器，架构本身几乎不用动。这大概就是"手搓 agent"和"调用别人 API"最大的区别：前者踩完坑之后，坑是自己的经验；后者出了问题，只能等别人发公告。