夜雨聆风第三天，我没有继续只看代码。
我打开了接口文档。
这一步很关键。因为一个模块到底为什么这样写，光看代码是不够的。代码回答的是“怎么做”，接口文档回答的是“对外承诺了什么”。
我让 AI 同时看两类信息：
一类是容器管理代码里的创建、启动、停止、删除入口。
另一类是接口文档里的通用 header、同步 response、异步 JobNotify、CreateVM 这类协议。
然后我问它：
“从接口文档到容器模块，中间可能有哪些映射关系？”
它给出的第一版答案很简单：接口请求进入 Agent，Agent 根据 method 调用对应容器操作，执行完成后返回 response 或 JobNotify。
这句话没错，但太宽泛了。
于是我继续追问：
“哪些字段会影响代码执行分支？”
这次答案就有用了。
接口里的 rid、traceId、jobId、method、data，都不是装饰字段。
rid 用来标识资源。
traceId 用来串联日志。
jobId 决定这是同步任务还是异步任务。
method 决定路由到哪个能力。
data 里则包含真正的业务配置，比如镜像、容器列表、profile、网络、资源限制等。
我以前读接口文档时，容易把这些字段当成“协议格式”。但放到真实代码里，它们其实会影响系统行为。
尤其是 jobId。
文档里说，jobId 为空表示同步任务，非空表示异步任务。异步任务收到后，需要先回复已经收到，再通过 JobNotify 上报执行结果。执行时间长时，还需要上报进度。
这个设计背后有一个很现实的问题：创建容器、加载镜像、配置存储、启动环境，都可能很慢。如果接口调用方一直阻塞等待，系统会变得非常脆弱。
所以文档把“收到请求”和“任务完成”拆成了两件事。
这也是工程系统里一个很常见的模式：
命令接收是一件事。
任务执行是一件事。
结果上报又是另一件事。
我让 AI 帮我把这个模式画成文字流程：
第一步，管理端发送请求，带上 method、rid、traceId、jobId 和 data。
第二步，Agent 校验并接收请求。
第三步，如果是异步任务，先返回同步 response，表示命令已经收到。
第四步，Agent 在后台执行具体容器操作。
第五步，任务完成后通过 JobNotify 上报 success 或 fail。
第六步，服务端再 response 确认收到 JobNotify。
文档里还有一个细节很值得注意：为了解决服务端收不到 JobNotify 导致任务状态更新不及时的问题，最终执行结果可以通过 JobNotify request 形式发送，服务端再 response 确认。
这说明整体的系统设计中是考虑到理论之外的可能的。
实际运行中通知可能丢，状态可能不同步，所以增加了容错。
这就是接口文档里最值得看的东西：不是字段本身，而是字段背后的失败场景。
今天我还发现一个适合 AI 的用法：
让它做“文档和代码的对照表”。
比如：
文档里的 profile，在代码里会影响容器配置模板。文档里的 containerList，对应多个容器实例的创建或同步。文档里的 jobId，影响同步和异步处理方式。文档里的 traceId，应该进入日志链路。文档里的状态字段，应该能对应任务执行结果。
这种对照表对新人很有用，对老项目维护也很有用。
当然：AI 做出的对照表只能当作假设，不能当作结论。
最后必须回到代码里确认：
字段有没有真的被解析？
异常时有没有真的上报？
日志里有没有带 traceId？
文档里的进度字段和代码里的字段名是否一致？
接口文档不是代码之外的东西，它是代码实现前的契约。
读一个新项目时，不能只问“这个函数是怎么实现的”，要再详细点：
“这个函数到底对应接口文档中哪个API的实现？”
当把代码和接口协议放在一起看，很多复杂逻辑就会显得通顺了。
它们不是为了复杂而复杂，而是在处理真实系统里的慢任务、失败、重试、状态确认和跨服务协作。
今日英雄池：Oracle
