确定性绘制的技术主题封面

✦ 01｜能力在，工具不在

起点很朴素：吾码后端已经有 MiniMax 生图路由，接口名、参数名、返回结构都写得清楚，用脚本直接调用也能拿到图片。但换到一个 AI 编程助手里，回答很干脆——没有这个工具。

这句话其实没有错。AI 助手调用外部能力时，并不遍历你的后端有哪些 HTTP 路由，它看的是这次会话里挂载的工具清单。清单里没有条目，参数契约里没有字段，它既不知道能不能做，也不知道该传什么。

于是问题从“模型会不会生图”变成了“工具层是否完整”。而工具层至少由三段组成：后端路由提供能力，客户端封装提供调用，工具注册提供名字、参数与执行策略。任何一段缺失，外部表现都是同一句话。

调用链解释图（确定性渲染），依据当前实现梳理。

✦ 02｜为什么“文档里有”不等于“现在能用”

排查的第一步是确认能力到底在哪一层，而不是立刻改代码。我们先做只读核对：路由常量、返回结构，以及模型清单端点。

结果一半是好消息，一半不是。生图路由与返回契约稳定存在；但用于枚举媒体模型的查询端点，在本环境按当前调用方式返回了 404。这说明能力清单本身也需要回执验证：文档描述与实际端点允许的调用方式，可能并不一致。

这类差异很容易被误判成“平台不支持”。更稳妥的顺序是：先证明后端能用，再判断客户端封装是否可用，最后才补工具注册。

四种“看起来失败”的状态（确定性渲染），它们的处置方式并不相同。

✦ 03｜工具注册应该补什么

补齐工具注册，不是把 HTTP 路径抄一遍。它至少要回答四个问题：工具名是什么、参数怎么传、什么时候允许真正执行、失败之后怎么恢复。

参数层面的关键，是把后端会拒绝的错误尽量拦在本地。例如精确尺寸要求宽度与高度同时给出，只写宽度在本地就该失败，不必占用一次远端生成额度。

执行策略层面，默认应当是只读试算：只有显式确认才真正提交。这既是安全边界，也让“查询”与“生成”在回执上可以区分。

{
  "requestId": "promotion.image.20260916.01",
  "prompt": "冷青蓝机房长廊，湿地面反射灯带，无人物、无文字",
  "width": 1200,
  "height": 1600,
  "confirmExecution": "promotion.image.20260916.01"
}

恢复层面，生图是异步任务：提交返回排队状态，查询要始终使用同一个任务标识。同一请求标识重复提交时，平台会回放同一个任务而不是新建一个，这一点对重试安全很重要。

✦ 04｜一次可复核的实测

改完之后没有停在编译通过。先用类型检查与单元测试确认契约，再把产物投放到运行时，用真实租户发起一次生成。

运行时回执显示：任务进入后台队列，随后状态变为成功，图片写入当前租户 HDFS 并返回持久地址。整个过程只用一个请求标识、一个任务标识。

本地与运行时验证记录（确定性渲染）。

✦ 05｜把边界写清楚

值得写清楚的边界有三条：第一，编译与单元测试通过，只证明契约一致；第二，运行时成功，证明的是当前租户与当前模型；第三，工具是否对助手可见，要在会话侧确认，因为这决定了助手能不能发现它。

另一个容易被忽略的边界是提示词长度。远端对图片描述有明确上限，超限会直接返回失败而不是静默截断。把它写成工具层的本地校验，比事后排查更省事。

这套顺序同样适用于其它能力：后端就绪只是第一段，工具层完整，才是助手真正可用的开始。

• 能力存在：后端路由与返回契约可核对。
• 调用可用：客户端封装能读取任务状态与结果地址。
• 工具可见：清单里有名字、有参数、有执行策略。
• 回执可查：同一任务标识能查到终态与持久地址。

✦ 06｜恢复顺序：先看回执，再决定要不要重投

异步能力的失败有四种面孔，处置方式完全不同。把它们混在一起，最常见的错误是用一个新标识重投一个其实还在排队的任务。

1. 仍在排队：继续查询同一个任务标识，不新建请求，也不重复占用额度。
2. 本地被拦：修正入参后重新提交，此时还没有产生远端任务。
3. 明确终态失败：保留回执，查清原因后再提交，且只提交一次。
4. 结果不确定：先核实失败发生在哪一层，必要时调用恢复接口，仍然使用同一个任务标识。

{
  "states": [
    { "status": "Pending",   "action": "继续查询同一个任务标识，不新建请求" },
    { "status": "Succeeded", "action": "取持久地址并登记回执" },
    { "status": "Failed",    "action": "保留回执，修正原因后只重新提交一次" },
    { "status": "Uncertain", "action": "先核实失败层级，必要时调用恢复接口" }
  ]
}

把这段顺序固化下来，Microi吾码AI 的工具层才算闭环：能力可以被发现，任务可以被追踪，失败也可以被解释。

内容说明：文中已标注的概念图由AI生成；源码与实测证据均来自当前工作区。竖卡的准确文案由确定性排版叠加，封面、调用链图、状态边界图与实测图均由确定性程序绘制，图注已分别说明。