存储SDK Agent：规划·检索·验证·修复的交付闭环

火山引擎存储团队正在把大模型从「代码补全工具」推向「可交付的工程系统」。他们在对象存储 SDK 场景中构建的 Agent，不是一次性生成代码的脚本，而是一条包含规划、检索、沙箱验证与反思修复的流水线。这条流水线的价值不在于角色数量，而在于每个环节都能为上一环节的缺口提供可解释、可复查的证据。

多语言 SDK 维护的一致性难题

对象存储面向 Java、Python、Go、C++、Rust 等十余种主流语言提供 SDK，接口持续迭代，文件存储的文件操作还包含复杂业务逻辑。维护者需要保证相同能力在不同语言里行为一致，又符合各语言的编码习惯；一旦代码与文档出现偏差，理解和排错的成本最终由使用者承担。

这里的核心难题是多种一致性同时存在。工程上的解法是把任务拆成接口语义、语言实现和配套文档三个维度，分别确定验收依据，避免「文件已经生成了」就被当成交付完成。

为什么模板工具不够用

团队调研了常见接口生成工具、面向服务的定义语言，以及内部基于接口描述的模板化工具。这些工具擅长生成数据结构和基础请求，但暴露出两个痛点：固定模板可能缺少目标语言的自然写法；特殊业务规则往往需要修改全局模板，影响难以控制。

模板在结构确定的地方仍有优势，文章要补充的是业务语义与灵活适配能力。对象存储向量接口的打标签例子很能说明问题：该接口并非直接透传存储桶名，而是需要把地域、账号标识和向量存储桶名组合为特定格式的资源路径参数。模板版本把桶名直接放入请求内容，模型实现则先构造资源标识再放入标签请求的路径。这说明接口定义之外还存在决定调用行为的业务约定——不能只验证参数名是否齐全，还要检查编码位置和组装规则。

文中提到的“面向服务的定义语言”通常指 OpenAPI、gRPC 的 Protocol Buffers 等用来描述接口契约的规范。它们能统一描述请求方法、参数类型和返回结构，再借助代码生成器产出各语言客户端骨架。其局限在于描述的是接口的“形状”而非“语义”：诸如资源路径如何拼接、鉴权字段放在哪里这类业务约定，往往不在规范覆盖范围内，生成结果正确但行为不一定正确。多语言 SDK 场景中，这类规范适合作为结构基线，而语言习惯写法与业务规则仍需额外的知识来源和验证环节来补齐。

从全量提示词到规划执行分离

架构并非一开始就完整。最初团队把全量文档放进提示词，遇到窗口限制与幻觉；随后引入边推理边调用工具的方式连接外部知识，但复杂任务仍缺少全局安排；于是把规划和执行分开，让规划者先拆任务；进一步实践又暴露出代码不一定可用，因此加入沙箱验证和反思修复，最后用图编排组织这些环节。

这条演进路径说明：知识可获取不等于流程完整，流程完整不等于产物可运行。每增加一层，都应能说清楚它补上了哪一个缺口。

规划者负责理解用户意图，把任务指向预设流程，例如新接口生成或已有接口迭代，自身不承担具体代码编写。执行过程中它持续关注任务状态与上下文，接收反馈再推进下一环节。这种分工避免一个角色同时处理所有细节而丢失全局。执行层面存在两种选择：动态生成任务更灵活，但可能因模型判断不稳定遗漏重要节点；预定工作流则事先确定必要步骤。SDK 交付的工作模式相对固定，团队选择预定工作流——这是场景取舍，而不是所有 Agent 都应采用同一种形式。

知识库、沙箱与静态评估各司其职

基础设施与记忆是上层执行的共同支撑。知识库为模型提供可靠上下文和高质量范例代码，沙箱提供隔离环境检查生成代码能否运行、是否通过单元测试。两者解决的是不同问题：知识帮助决定「应该怎样写」，沙箱帮助观察「写出的东西实际怎样表现」。静态评估又补充语法、规范和文档要求。把这几类依据区分开来很重要——检索到相似例子不能替代运行测试，测试成功也不能证明文档完整。

知识库处理设计文档、历史代码和纠错记录等分散信息。文章给出一个周期性运行的数据流水线：脚本扫描指定来源，模型对原始文档分析、提取和转换，清洗后的知识进入向量存储，上层按需检索。这样业务知识能持续进入执行上下文，而不只是一次性写进提示词。

检索链路中，团队把知识清洗阶段提取的信息作为向量检索的元数据过滤条件，让召回不止依据语义相似，还能结合业务属性筛选。看起来相似的两段代码未必适用于同一个产品或任务，贸然复用会把错误带进新实现。至于为什么选择对象存储向量能力，团队主要考虑持续写入、长期保存和按需检索的访问模式；存算解耦、按存储量和检索量计费的方式更契合这种负载特征，文件与向量能力原生结合也简化了数据管理。这属于基于具体工作负载的成本判断，查询频率或延迟目标不同时需要重新比较。

沙箱是隔离的临时运行环境，通常配置好目标语言的运行时、依赖和测试框架，让生成的代码在其中编译、执行单元测试或发出模拟请求，而不影响生产系统。对 Agent 而言，它的价值是把“代码看起来对”变成“代码实际能跑”，输出的是可复查的通过或失败结果及日志。需要注意的是，沙箱里的测试覆盖有限，通过测试只说明已检查的路径正确，不能替代静态规范检查和文档审阅；反过来，静态检查也无法发现运行时才暴露的路径错误。因此三类证据各自回答不同问题，验收时应并列使用。

反思循环：让失败证据驱动修复

评估层负责静态质量把控，依据预定规则、规范和静态分析工具检查 SDK 代码、文档中的示例代码以及文档内容规范。这类检查不需要真正运行业务请求，适合尽早发现低成本可修复的问题。但语法正确的请求仍可能调用错误路径，规范完整的文档也可能解释错参数，所以静态评估只是一类具体证据。把检查结果关联到文件位置和违反的要求，才更容易支持下一轮精确修复。

当静态检查发现问题或单元测试等动态验证失败时，反思机制被激活：读取失败日志、错误信息和评估报告，分析根因和修复计划，指导执行者下一轮修改。关键在于证据传递——只有一句「失败了」，执行者容易凭猜测调整；保留实际错误和验证条件，才有机会针对问题修复。修复后应重新执行相关检查，确认原失败消失，同时观察是否引入新问题。

文章采用执行者与评估者两个角色：执行者完成任务，评估者按预定义的多维标准审查打分并给出可操作的改进建议，循环持续到达到质量阈值或触及最大次数。文中举出的 95 分阈值是示例，不代表每种任务都应使用这个数字。独立角色的价值在于职责分离，但若两者依赖同样错误的信息也可能共同误判，因此评估标准应尽量连接实际代码规范和运行结果，并保留循环上限。

这里的反思机制属于“自我修复”式 Agent 模式：模型基于失败反馈重新规划并修改产物，而不是简单地重试生成。它与一次性生成的本质区别在于引入了外部信号——编译错误、测试断言失败、静态检查报告等——作为下一轮修改的依据，使迭代方向受证据约束。常见失效模式有两种：一是反馈信息过于笼统，模型反复猜测性修改；二是评估者与执行者共享同一错误假设，循环收敛到错误结果。因此实践中通常保留完整错误日志、限定最大循环次数，并在修复后重跑相关检查，确认原问题消失且未引入回归。

观测与度量：从轨迹到质量门禁

SDK Agent 链路长、交互多，零散日志很难还原任务经历了什么。团队基于日志服务建立观测能力，采集全生命周期信息并串联为执行轨迹，支持长上下文记录、兼容开放遥测协议、提供仪表盘模板，用于稳定性监控、性能分析、问题排查和迭代。记录内容多只是基础，还需要把同一任务的各阶段对应起来，才看得出某次评估失败发生在何处、后续修复针对了哪一个产物。

文章展示的一次任务轨迹带来三个具体发现：首次代码生成失败是因为没有通过单元测试，轨迹保留了报错效果；时间轴显示代码沙箱占据主要耗时，因此优化方向并不只在模型生成速度；能看到评估失败后触发反思并完成代码修复的过程。这些都是单次任务的观测结果，不代表所有任务的瓶颈都在沙箱。可迁移的方法是先沿轨迹区分等待、执行与验证，再决定优化对象。

为了验收提示词调整和架构升级，团队又建设了标准化的静态自动评估流水线，在代码生成、文档编写等环节设置质量门禁，并用覆盖多种场景的数据集检验结果。这与单次执行中的反思循环职责不同：反思帮助当前任务修复，统一评估则观察一次系统改动是否带来整体收益。

开放遥测协议（OpenTelemetry）是一套跨语言的观测数据标准，统一了链路追踪、指标和日志的采集与导出格式。在 Agent 场景中，它可以把一次任务拆成规划、检索、生成、验证、反思等 span，记录各阶段耗时、输入输出与状态，从而还原完整执行轨迹。采用标准协议的好处是能接入既有监控后端和仪表盘，避免自建一套孤立的埋点体系。不过追踪数据本身只描述发生了什么，要判断质量是否改善，还需与质量门禁结果和评估数据集结合分析，才能把“变慢”或“变差”定位到具体环节。

效果数据与解读边界

团队报告生成代码与文档的质量评分处于 90-95 分区间，代码无需人工修改的平均采纳率为 93.84%。这两个口径应当区分：评分来自团队自己的评估体系，采纳率描述实际采用时是否修改，都不等于已经证明不存在缺陷。文章没有给出完整分母、样本分布与长期故障情况，因此这些数字适合说明团队看到的效果，不能直接预测另一个产品的表现。

交付规模方面，文章报告对象存储累计完成 100 多个接口和 180 多份配套文档，日志服务补齐 170 多个接口并修复 80 多个存量接口问题，人工介入率低于一成，累计节省 300 多人天。这些结果分别包含新增、能力补齐和问题修复，不能简单相加成同一种工作量；节省人天也依赖原先流程的估算基线。

文章还提到一个头部车企项目，称借助该能力将迭代周期从月级压缩到周级。这是项目案例描述，缺少详细的工作范围、基线和外部调整的计算方式，不能换算成统一的倍数提升。对工程团队更有用的是同时记录交付周期、产物质量和人工介入原因，再结合轨迹、质量门禁和采纳记录，理解改善究竟来自减少重复生成、缩短排错，还是让多语言与文档更同步地推进。

可迁移的落地建议

这条交付链的主线可以概括为：规划者选择预设流程，执行者结合知识生成代码与文档，静态检查和沙箱发现问题，评估者给出具体反馈，反思机制推动修复，轨迹和标准化数据集帮助团队持续改进。对自建 SDK 或代码生成场景，可以先挑一个带有特殊参数规则的接口，把知识来源、实际请求和验收条件全部跑通，再逐步增加语言与任务类型，让扩展建立在能够解释、复查和对比的证据之上。