51 KiB
文字 / 图片自动生成机器人(前端联调)
服务地址默认 http://127.0.0.1:8991。本流程接收用户文字、图片,自动理解需求、选件并校验装配,完成响应直接包含机器人方案。无需追问、确认或接受降级后才能显示。所有 JSON 接口和 SSE 事件数据沿用 {code, message, data, requestId}。
本文已按当前后端代码核对(2026-10-16),新生成结果的 result.analysis.schemaVersion 为 multimodal-v1.5-neutral-components。新方案的类别和实例编码使用完整16类大写编码,足部使用 LEG_L/LEG_R/LEG_0;旧小写及 pedal_l/pedal_r 仅作为兼容输入,原始 URDF 数据保持不变。本次对接变化如下:
| 位置 | 当前约定 |
|---|---|
| 消息请求体 | 仍只有 messageId、text、attachmentIds;数量等需求写在自然语言中 |
data.result.request.partRequirements[] |
后端解析出的部位条件,新增可选 quantity;它不是消息接口的请求体字段 |
data.match.components[] |
保留组件包装结构,外层 instanceId 区分同款组件的多个实例 |
data.match.assembly.connections[] |
双方实例编码、共同 interfaceChild 和双方原始 frames 下标;不再返回摆放矩阵及连接中的 xyz/rpy |
data.match.alternatives[] |
按目标 instanceId 分组,切换时只替换该实例 |
data.match.missingParts[] |
包含期望、实际、缺少数量;缺件时仍可展示已有连通组合 |
data.result.request.templatePartGroups[] |
默认人形的四组部位合计要求,由后端生成 |
data.match.missingPartGroups[] |
模板部位合计缺口;不会将同组未选类别逐一报为缺件 |
历史快照不会自动升级,联调新协议时请使用新的 messageId 生成结果。
1. 前端调用顺序
- 创建会话,保存
conversationId。 - 有图片时先上传到该会话,保存
attachmentId;仅文字可跳过。 - 发送消息,使用 POST + fetch 接收 SSE;后端在同一任务中完成需求理解、自动选件和装配校验。
- 收到
analysis.completed,直接读取data.match。当match.assembly.status=ready时,按instanceId加载match.components的资源,再根据match.assembly.connections定位双方接口并由前端摆放;partial也可直接显示有效的已有组合。 - 简短展示
warnings、缺件及未满足/未验证项;不弹出追问、确认或必须接受降级的页面。assembly.status=blocked或status=no_match时展示具体原因,不伪造连接位姿。 - 用户需要调整时,在同一会话发送新消息,例如“改成右臂扭矩至少30N·m”,后端生成新版本并返回新方案。
- 需要长期保留时,将当前
analysisId作为analysisCode调用保存为我的项目。项目可上传 OSS 封面、发布到广场或被其他用户 fork;保存后不随需求会话过期清理。
先完成邮箱与图片验证码登录,所有业务请求头携带 Authorization: Bearer <token>,不再依赖匿名 Cookie 或 credentials:"include"。会话和图片归属服务端认证的用户,同账号换设备登录后仍可通过原业务编码访问;其他账号访问返回 404。历史匿名会话不自动认领,保留至过期清理。不传 userId、用户编码、模型 Key 或系统提示词。生产使用 HTTPS;开发跨端口需配置具体允许域名。
接口清单
| 方法 | 路径 | 请求 | 返回 |
|---|---|---|---|
| POST | /api/robot-conversations |
无请求体 | 会话编码、初始版本、有效期 |
| POST | /api/robot-conversations/{conversationId}/attachments |
multipart file |
图片编码、预览地址 |
| GET | /api/robot-conversations/{conversationId}/attachments/{attachmentId} |
无 | 私有原图,需要 Bearer Token |
| POST | /api/robot-conversations/{conversationId}/messages |
消息 JSON | SSE 生成阶段、完整需求及装配方案 |
| GET | /api/robot-analyses/{analysisId} |
无 | 当前生成状态、需求及装配方案 |
| POST | /api/robot-analyses/{analysisId}/retry |
无请求体 | SSE,仅重试失败或停止的当前版本 |
| DELETE | /api/robot-analyses/{analysisId} |
无 | 停止后的解析状态 |
AI 对话拼装仅保留以上 7 个接口。原 confirm、rematch、按 matchId 查询和 accept-degradation 接口已删除,访问返回 HTTP 404;前端不再调用这些接口。生成结果统一从消息完成事件或 GET /api/robot-analyses/{analysisId} 的 data.match 获取。
正常文字生成只需调用“创建会话 → 发送消息”两个接口;图片生成再增加上传接口。预览、状态查询、重试和停止按实际交互调用。
既有结构化 POST /api/robot-matches 和组件详情保留,均需登录,见 组件接口文档。本流程的状态为小写,与既有接口的 MATCHED/FALLBACK/PARTIAL/NO_MATCH 分开使用。
2. 创建会话与上传图片
POST /api/robot-conversations,无请求体。返回示例:
{
"code": "OK",
"message": "success",
"data": {
"conversationId": "DC-11111111111111111111111111111111",
"revision": 0,
"expiresAt": "2026-10-20T02:00:00Z"
},
"requestId": "frontend-demand-001"
}
会话默认最近一条新用户消息后 7 天过期,过期后返回 404。conversationId 等名称中的 Id 都是业务编码,不是数据库主键。
上传:POST /api/robot-conversations/{conversationId}/attachments,multipart/form-data,字段名 file。每次上传一张 PNG/JPEG/WebP,每张最大 8MiB。浏览器传 FormData,不要手动填写 multipart Content-Type。
{
"code": "OK",
"message": "success",
"data": {
"attachmentId": "DA-44444444444444444444444444444444",
"mimeType": "image/png",
"sizeBytes": 12450,
"previewUrl": "/api/robot-conversations/DC-11111111111111111111111111111111/attachments/DA-44444444444444444444444444444444"
},
"requestId": "frontend-demand-001"
}
图片仅能用于所属会话,一个附件只能绑定一条新消息。重复发送同一 messageId 无需重复上传;后续图片消息请重新上传附件。原图通过返回的 previewUrl 用 fetch 携带认证头获取 Blob,再使用 URL.createObjectURL 展示,释放时调用 URL.revokeObjectURL;示例见登录文档。
3. 发送消息并直接生成
POST /api/robot-conversations/{conversationId}/messages,请求示例:
{
"messageId": "m1",
"text": "我要一个右臂,扭矩至少20N·m",
"attachmentIds": []
}
图文消息示例:
{
"messageId": "m2",
"text": "以草图为参考,右臂扭矩至少20N·m",
"attachmentIds": [
"DA-44444444444444444444444444444444"
]
}
| 字段 | 类型 | 必填 | 限制 |
|---|---|---|---|
messageId |
string | 是 | 1–80 位字母、数字、下划线、短横线;同一会话内保持唯一;网络重发使用原编号 |
text |
string | 是 | 最多 20000 字符;仅图片时传空字符串 |
attachmentIds |
string[] | 否 | 最多 4 张,不重复;省略/null 表示无图 |
部位、数量、材质等要求直接写入 text,例如“拼一个躯干和4个右臂”。后端会把明确数量写入返回的 data.result.request.partRequirements[].quantity。消息请求体无需增加 quantity、requiredParts 或 partRequirements;直接提交结构化条件请使用 POST /api/robot-matches。
文字和图片不能同时为空。相同编号但不同内容返回 409。历史由后端保存,不传 role、messages、客户端解析结果。最多 40 条历史消息(旧会话可能包含历史助手消息,新流程不写入追问);图片原始字节总量最多 30MiB,编码后的模型请求最多 40MiB;超限时新建会话。
SSE 事件
| 事件 | data 内容 |
前端处理 |
|---|---|---|
analysis.progress |
{analysisId, revision, stage, message} |
更新阶段提示,记录解析编码和版本 |
analysis.completed |
完整 AnalysisView,包含 match |
直接加载可装配机器人并展示说明 |
analysis.failed |
code 为错误码,data=null |
停止加载,按错误码显示重试入口 |
| 心跳注释 | 无 JSON 数据 | 忽略 |
阶段依次为 validating_input、analyzing_requirements、validating_result、assembling_robot;最后一阶段包含自动选件和装配校验。阶段提示不是模型逐字输出,不用于计算完成百分比。只有需求与匹配快照一起保存成功后才发送完成事件;自动选件期间 GET 仍返回 processing,result 和 match 均为空。
事件格式示例:
event:analysis.progress
data:{"code":"OK","message":"success","data":{"analysisId":"DN-22222222222222222222222222222222","revision":1,"stage":"analyzing_requirements","message":"正在分析需求"},"requestId":"frontend-demand-001"}
使用 fetch 接收 POST SSE(EventSource 不支持 POST):
async function sendMessage(token, conversationId, message, onEvent, signal) {
const response = await fetch(`/api/robot-conversations/${conversationId}/messages`, {
method: "POST",
headers: { "Content-Type": "application/json", "Accept": "text/event-stream", "Authorization": `Bearer ${token}` },
body: JSON.stringify(message),
signal
});
if (!response.ok) throw await response.json();
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
function consume() {
let end;
while ((end = buffer.indexOf("\n\n")) >= 0) {
const block = buffer.slice(0, end);
buffer = buffer.slice(end + 2);
let event = "message";
const lines = [];
for (const line of block.split("\n")) {
if (line.startsWith("event:")) event = line.slice(6).trim();
if (line.startsWith("data:")) lines.push(line.slice(5).trimStart());
}
if (lines.length) onEvent(event, JSON.parse(lines.join("\n")));
}
}
try {
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
consume();
}
buffer += decoder.decode();
consume();
} finally {
reader.releaseLock();
}
}
后端发送 LF 分隔的事件,网络读取可能把一个事件拆成多块,需保留 buffer。主动停止调用 DELETE;SSE 意外断开不会取消任务,后端继续生成至完成或超时。连接中断后先 GET 查询状态,processing 时可间隔 1.5–2 秒查询;ready 时直接使用返回的 match;failed/cancelled 才提供 retry。不要重发新消息或把查询成功称为 SSE 连接恢复。SSE 开始前的校验错误使用 HTTP 错误响应;开始后模型失败通过 analysis.failed 通知。
重发同一消息以恢复订阅时,已结束任务可能通过 analysis.completed 返回最终状态,其中也可能是 failed、cancelled 或 superseded。前端必须检查 data.status,只有 ready 且 match 非空时才进入方案展示,再根据 match.assembly.status 判断能否装配;不能仅凭事件名称判断生成成功。
消息完成与状态查询响应
analysis.completed 和 GET /api/robot-analyses/{analysisId} 使用同一数据结构:
{
"code": "OK",
"message": "success",
"data": {
"analysisId": "DN-22222222222222222222222222222222",
"conversationId": "DC-11111111111111111111111111111111",
"revision": 1,
"status": "ready",
"canSubmit": true,
"summary": "右臂扭矩至少20N·m",
"questions": [],
"warnings": [
"整机拼装固定一个躯干,已补入TORSO_0作为基础组件。"
],
"result": {
"request": {
"userInput": "我要一个右臂,扭矩至少20N·m",
"requirements": [
"右臂"
],
"requiredParts": [
"TORSO_0",
"ARM_R"
],
"robotRequirements": {},
"partRequirements": [
{
"category": "ARM_R",
"torqueNm": 20,
"operators": {
"torqueNm": "gte"
},
"quantity": 1
}
],
"templatePartGroups": []
},
"analysis": {
"summary": "右臂扭矩至少20N·m",
"keywords": [
{
"term": "右臂",
"source": "explicit",
"reason": "用户指定部件",
"negated": false,
"evidence": "我要一个右臂,扭矩至少20N·m"
}
],
"robotTypes": [],
"partCategories": [
{
"category": "ARM_R",
"source": "explicit",
"reason": "用户指定部件",
"evidence": "我要一个右臂,扭矩至少20N·m"
}
],
"excludedCategories": [],
"unmodeled": [],
"constraints": [
{
"scope": "part",
"categories": [
"ARM_R"
],
"field": "torqueNm",
"value": "20N·m",
"upperValue": "",
"operator": "gte",
"evidence": "我要一个右臂,扭矩至少20N·m"
},
{
"scope": "part",
"field": "quantity",
"value": 1,
"upperValue": "",
"operator": "eq",
"evidence": "我要一个右臂,扭矩至少20N·m",
"categories": [
"ARM_R"
]
}
],
"questions": [],
"warnings": [
"整机拼装固定一个躯干,已补入TORSO_0作为基础组件。"
],
"catalogVersion": "2026-10-16-hexapod-template",
"observations": [
{
"id": "e1",
"messageId": "m1",
"imageId": "",
"kind": "user_text",
"content": "我要一个右臂,扭矩至少20N·m",
"clarity": "clear",
"region": []
}
],
"intentItems": [
{
"id": "r1",
"dimension": "performance",
"subject": "右臂",
"requirement": "扭矩至少20N·m",
"priority": "must",
"source": "explicit",
"evidenceIds": [
"e1"
],
"evidence": "我要一个右臂,扭矩至少20N·m"
},
{
"id": "r2",
"dimension": "quantity",
"subject": "右臂",
"requirement": "一个右臂",
"priority": "must",
"source": "explicit",
"evidenceIds": [
"e1"
],
"evidence": "我要一个右臂,扭矩至少20N·m"
}
],
"images": [],
"keywordEvidence": [
{
"term": "右臂",
"evidenceIds": [
"e1"
]
}
],
"schemaVersion": "multimodal-v1.5-neutral-components",
"canSubmit": true,
"status": "ready",
"defaultTemplate": ""
}
},
"match": {
"analysisId": "DN-22222222222222222222222222222222",
"revision": 1,
"matchId": "DM-33333333333333333333333333333333",
"status": "complete",
"rootCategory": "TORSO_0",
"searchLimited": false,
"degradationAcceptanceRequired": false,
"degradationAccepted": false,
"totals": {
"degreesOfFreedom": 4,
"massKg": 3.2,
"knownMassKg": 3.2,
"massComplete": true
},
"unmetRequirements": [],
"unmatchedKeywords": [],
"missingParts": [],
"requirementChecks": [
{
"intentId": "r1",
"priority": "must",
"status": "satisfied",
"field": "torqueNm",
"expected": 20,
"actual": 25,
"reason": "所选组件的登记参数满足该条件"
},
{
"intentId": "r2",
"priority": "must",
"status": "satisfied",
"field": "quantity",
"expected": 1,
"actual": 1,
"reason": "所选组件实例数量满足条件"
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:ARM_R:1",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
}
],
"issues": []
},
"components": [
{
"instanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"component": {
"componentCode": "CW-TORSO-001",
"componentName": "铝合金躯干",
"category": "TORSO_0",
"description": "机器人躯干",
"material": "铝合金",
"massKg": 2,
"degreesOfFreedom": 0,
"rotationAxis": null,
"functionDescription": "支撑",
"shape": "宽躯干",
"size": "中型",
"torqueNm": 0,
"bomList": [
{
"partCode": "FRAME-01",
"quantity": 1
}
],
"urdfInfo": {
"robotName": "躯干",
"rootLink": "BASE",
"frames": [
{
"name": "J_ARM",
"kind": "joint",
"type": "fixed",
"parent": "BASE",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"originExplicit": true,
"xyz": [
0.1,
0,
0
],
"rpy": [
0,
0,
0
],
"axis": [
0,
0,
0
],
"limits": {}
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-TORSO-001/step/batch-a/torso.step",
"urdfUrl": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/robot.urdf"
},
"urdfMainPath": "robot.urdf",
"resources": [
{
"relativePath": "robot.urdf",
"url": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/robot.urdf",
"version": 1,
"expiresAt": null
},
{
"relativePath": "meshes/torso.stl",
"url": "https://models.example.com/cadworld/components/CW-TORSO-001/urdf/batch-a/meshes/torso.stl",
"version": 1,
"expiresAt": null
}
],
"resourceIssues": []
},
{
"instanceId": "DM-33333333333333333333333333333333:ARM_R:1",
"component": {
"componentCode": "CW-ARM-001",
"componentName": "标准右臂",
"category": "ARM_R",
"description": "机器人右臂",
"material": "铝合金",
"massKg": 1.2,
"degreesOfFreedom": 4,
"rotationAxis": null,
"functionDescription": "抓取",
"shape": "长条",
"size": "小型",
"torqueNm": 25,
"bomList": {
"parts": [
{
"partCode": "MOTOR-01",
"quantity": 4,
"specification": {
"ratedTorqueNm": 25
}
}
]
},
"urdfInfo": {
"robotName": "右臂",
"rootLink": "ARM_ROOT",
"frames": [
{
"name": "INCOMING_arm_r",
"kind": "joint",
"type": "fixed",
"parent": "ARM_ROOT",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"xyz": [
0,
0,
0
],
"rpy": [
0,
0,
0
]
}
]
},
"version": 2,
"stepUrl": "https://models.example.com/cadworld/components/CW-ARM-001/step/batch-a/arm.step",
"urdfUrl": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/robot.urdf"
},
"urdfMainPath": "robot.urdf",
"resources": [
{
"relativePath": "robot.urdf",
"url": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/robot.urdf",
"version": 2,
"expiresAt": null
},
{
"relativePath": "meshes/arm.stl",
"url": "https://models.example.com/cadworld/components/CW-ARM-001/urdf/batch-a/meshes/arm.stl",
"version": 2,
"expiresAt": null
}
],
"resourceIssues": []
}
],
"alternatives": [
{
"category": "TORSO_0",
"items": [],
"instanceId": "DM-33333333333333333333333333333333:TORSO_0:1"
},
{
"category": "ARM_R",
"items": [],
"instanceId": "DM-33333333333333333333333333333333:ARM_R:1"
}
],
"missingPartGroups": []
}
},
"requestId": "frontend-demand-001"
}
| 字段 | 说明 |
|---|---|
status |
新流程为 processing / ready / failed / cancelled / superseded;ready 表示本次方案已生成,具体能否装配看 match.assembly.status。needs_clarification 仅可能存在于旧记录 |
canSubmit |
旧客户端兼容字段,新流程 ready 时为 true;无需展示确认按钮,不代表所有要求达标 |
questions |
新生成结果固定为 [],不发起追问 |
warnings |
来源、推断或能力承载方面的说明,供核对 |
result.request |
规范化需求及后端生成的 templatePartGroups;未提供的约束不会补成 0 |
result.request.partRequirements[].quantity |
部位实例数量,整数 1–24;省略/null 表示按可匹配接口填充,躯干固定一个;第 5 节给出多实例示例 |
result.request.templatePartGroups |
后端生成的模板要求数组,每项为 {family, categories, minimumQuantity};不作为消息或结构化匹配入参 |
match.missingPartGroups |
部位合计缺口,每项含 family、categories、reason、expectedQuantity、actualQuantity、missingQuantity;有缺口时为 partial |
result.analysis.schemaVersion |
新生成结果为 multimodal-v1.5-neutral-components;旧快照可能仍为旧协议 |
result.analysis.intentItems |
逐项需求,must 硬要求、prefer 偏好、context 参考;用于结果说明和逐项核对 |
result.analysis.defaultTemplate |
没有可匹配类型或部位时使用的默认模板编码,目前为 biped;没有采用默认模板时为空字符串 |
match |
已保存的完整机器人方案,包含组件资源、装配连接、缺件和逐项校验;处理未完成或已失效时为空 |
result.analysis.observations |
用户原文 / 图片 OCR / 视觉描述及所属消息、图片 |
result.analysis.images |
图片类型、用途和不确定点;不包含图片数据 |
evidenceIds |
关联 observation 的编码;region=[] 表示无可靠定位框 |
新流程 ready 同时返回 result 和 match;其他状态两者为空、canSubmit=false。旧版记录可能仍含 needs_clarification,发送新消息即可按新流程生成;旧版 ready 若没有 match,发送新消息生成方案;不再提供补确认入口。图像视觉推断只保留参考,不自动成为确定尺寸、材质、数值或能力。展示整机功能“跑步”等时应标明文本相关性,不能据此展示真实能力已验证。
自动生成示例:用户说“右臂扭矩至少30”但缺单位时,后端直接选取躯干和右臂,忽略无法验证的数值筛选条件,并把原要求保留为 unverified,不会默认单位或追问。用户后来主动补充“单位是N·m”时,结合真实用户历史生成版本 2;旧版本变为 superseded,旧方案不再应用。未提供机器人形态或部位时按默认双足模板生成参考方案并说明;不支持的四足、飞行等要求仍保留差异,不宣称默认方案已满足。
4. 机器人方案
消息完成事件及状态查询的 data.match 包含同一份已保存方案。第 3 节示例只指定右臂,后端补入一个躯干作为装配根,同时返回两件组件的资源和接口连接关系。示例编码与资源域名均为演示值。
| 字段 | 说明 |
|---|---|
status |
complete:所需类型及明确数量齐全且硬要求已验证满足;partial:缺件、数量不足、硬要求未满足或未验证;no_match:没有可用躯干,或明确排除躯干而无法生成组合 |
components[] |
稳定实例编码 + 完整公开组件 DTO,保留原始 bomList 和 urdfInfo JSON |
alternatives[] |
每个已选实例最多 5 个兼容替代项,以 instanceId 区分,见下文 |
requirementChecks[] |
对应 intentId,状态 satisfied / unmet / unverified;前端关联解析中的详细需求 |
unmetRequirements |
字段差距,包括偏好差距;硬要求判定以详细校验为准 |
totals |
按实例累计组件标称参数,同款组件安装 4 次就累计 4 次;不重复统计 BOM。质量未知时 massKg=null,knownMassKg 为已知部分 |
missingParts |
缺失角色和原因,仅提示完整性,不阻塞已有组件装配;没有可用躯干时返回 no_match,其他现存角色可标记 NO_TORSO;仍是 HTTP 200 |
searchLimited |
候选或搜索被截断,本方案不是已证明的全局最优 |
degradationAcceptanceRequired |
新生成方案及替代候选固定为 false;缺件和未满足/未验证项作为结果说明,不要求先接受 |
assembly.status |
ready:已有连通组合可展示,连接关系已生成;位姿由前端处理,issues/resourceIssues 为提示,不阻止展示。没有可用躯干/组件时为 blocked |
公开组件字段与 组件详情 一致,不包含数据库主键和独立 OSS 对象键。components[].component.rotationAxis 和 alternatives[].items[].component.rotationAxis 返回 X、Y、Z 或 null;旋转轴非必填,null 表示组件未设置,不能默认成某个轴或覆盖 URDF 中的关节 axis。urdfMainPath 与资源清单中的 relativePath 保留目录层级,使用 resources[].url 加载模型和 mesh。公开资源 expiresAt=null,不是临时签名;version 表示组件版本。
躯干优先规则
拼装仅检索同时具备非空 step_object_key 和已上传 URDF 主文件(非空 urdf_main_object_key)的组件;消息自动生成和替代候选使用同一筛选规则。仅上传 STEP 的组件不会参与拼装。接口以合法 interfaceType 确定目标 category,缺失或无效时从 child 的 LINK_ 后解析现有类别;只连接用户需求涉及的装配角色,双方原始 frames[].child 必须非空:完全相等时可连接;ARM/HAND/LEG/FOOT 的父 L/R 接口还可连接同部位的 0 接口,父 0 只接 0,L/R 不能互接。新增兼容仅替换标准编码末尾方向位(支持大写 L/R、小写 l/r),其余字符区分大小写保持一致。name 不参与兼容性判断。无法识别类型或无有效 child 的接口跳过并提示,不阻塞已有组合。
整机结果始终以 TORSO_0 为根,默认方案中的躯干只有一个。用户未单独提出躯干时,后端在规范化的 requiredParts 中补入 TORSO_0 并返回说明;原始对话和提取的用户条目保持其来源。明确要求“不要躯干”时保留排除项,返回 no_match、missingParts.reason=EXCLUDED_TORSO,不会偷偷补入躯干;同款组件支持多个独立实例,躯干始终固定一个。
躯干先按自身硬条件、数值差距、偏好、整机功能文本与关键词相关性排序。关键词先比较命中的不同需求数量,再比较字段权重,因此说明中匹配六足需求的躯干不会被只命中泛称“机器人”的普通躯干压过;这些条件相同后优先选择能接更多所需角色的接口集合,最后按编码稳定排序。整机自由度和质量目标在后续组合阶段评价,不直接当作躯干单件的数值要求。
选定躯干后不因其他躯干能多接几件或更接近整机总量而自动换根。其他组件须能通过现有接口路径连接到这个躯干;例如右手通过右臂连接,允许沿链匹配,但不自动补入未要求的中间连接件。达标搜索和降级搜索沿用同一个躯干。缺件时返回该躯干及可连接的部分方案;无可用躯干时返回 no_match,不会用头部或手臂代替根。
缺件时展示已有组合
status=partial 可以同时有 assembly.status=ready。例如需要躯干、右臂和头部,库存只有能连接的躯干与右臂,且两件具有匹配接口,返回如下片段:
{
"status": "partial",
"rootCategory": "TORSO_0",
"degradationAcceptanceRequired": false,
"degradationAccepted": false,
"missingParts": [
{
"category": "HEAD_0",
"reason": "NO_COMPONENT",
"expectedQuantity": 1,
"actualQuantity": 0,
"missingQuantity": 1
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:ARM_R:1",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
}
],
"issues": []
},
"missingPartGroups": []
}
前端直接加载 components[] 中已有的模型并应用上述连接,提示“缺少头部”,不展示降级接受入口。仅有有效躯干时也可返回 ready,此时 connections=[],前端显示躯干本身。
缺失角色不返回占位组件或伪造连接。totals 仍是已有组件的标称参数之和;所需组件未齐全时,整机总量要求仍可能为 unverified。替代候选遵循同一规则。只有没有可展示的躯干/组件时才返回 blocked;安装基准、位姿、活动关节和资源清单问题仅提示。新结果不要求 urdfInfo.assembly,不会因缺少 mountingFrame 而阻塞。
替代项示例
下面是一个完整的 alternatives[] 分组示例,instanceId 指定被替换的右臂实例,items[] 是可替换它的候选组件。没有可用替代项时该分组的 items=[]:
{
"category": "ARM_R",
"instanceId": "DM-33333333333333333333333333333333:ARM_R:1",
"items": [
{
"component": {
"componentCode": "CW-ARM-002",
"componentName": "大扭矩右臂",
"category": "ARM_R",
"description": "机器人右臂",
"material": "铝合金",
"massKg": 1.5,
"degreesOfFreedom": 4,
"rotationAxis": null,
"functionDescription": "抓取",
"shape": "长条",
"size": "小型",
"torqueNm": 30,
"bomList": {
"parts": [
{
"partCode": "MOTOR-01",
"quantity": 4,
"specification": {
"ratedTorqueNm": 25
}
}
]
},
"urdfInfo": {
"robotName": "大扭矩右臂",
"rootLink": "ARM_V2_ROOT",
"frames": [
{
"name": "INCOMING_arm_r",
"kind": "joint",
"type": "fixed",
"parent": "ARM_V2_ROOT",
"child": "LINK_arm_r",
"interfaceType": "ARM_R",
"xyz": [
0,
0,
0
],
"rpy": [
0,
0,
0
]
}
]
},
"version": 1,
"stepUrl": "https://models.example.com/cadworld/components/CW-ARM-002/step/batch-a/arm.step",
"urdfUrl": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/robot.urdf"
},
"resources": [
{
"relativePath": "robot.urdf",
"url": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/robot.urdf",
"version": 1,
"expiresAt": null
},
{
"relativePath": "meshes/arm.stl",
"url": "https://models.example.com/cadworld/components/CW-ARM-002/urdf/batch-a/meshes/arm.stl",
"version": 1,
"expiresAt": null
}
],
"resourceIssues": [],
"urdfMainPath": "robot.urdf",
"totals": {
"degreesOfFreedom": 4,
"massKg": 3.5,
"knownMassKg": 3.5,
"massComplete": true
},
"unmetRequirements": [],
"unmatchedKeywords": [],
"requirementChecks": [
{
"intentId": "r1",
"priority": "must",
"status": "satisfied",
"field": "torqueNm",
"expected": 20,
"actual": 30,
"reason": "所选组件的登记参数满足该条件"
},
{
"intentId": "r2",
"priority": "must",
"status": "satisfied",
"field": "quantity",
"expected": 1,
"actual": 1,
"reason": "所选组件实例数量满足条件"
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:ARM_R:1",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_V2_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
}
],
"issues": []
},
"degradationAcceptanceRequired": false
}
]
}
替代结果以当前默认方案为基准,包含重新计算的汇总、校验和装配信息。前端切换时按候选组 instanceId 替换对应实例的组件与资源并应用该替代项的连接信息。躯干替代项表示替换当前唯一躯干,不能作为第二个躯干追加。多个替代项同时切换不能直接叠加各自预览;当前没有多项替换后的服务端校验或方案保存接口。需要重新生成方案时,在同一会话发送新的用户消息。
5. 实例、接口连接与加载
组件包装与实例标识
同一 componentCode 可以出现多次,表示同款组件的不同实例。AI 实例标识格式为 {matchId}:{装配角色}:{序号},序号从 1 开始;前端必须使用外层 components[].instanceId 区分模型,不能按组件编码去重。实例标识在当前方案内唯一,新方案的 matchId 和实例标识会变化。
data.match.components[] 的字段如下;完整示例见第 3 节:
| 字段 | 类型 | 说明 |
|---|---|---|
instanceId |
string | 当前实例标识;连接和替代分组均引用此值 |
component |
object | 完整公开组件 DTO,包含 componentCode、category、rotationAxis、原始 urdfInfo 等;不嵌套短实例标识 |
urdfMainPath |
string | URDF 主文件在资源包中的相对路径,保留目录层级 |
resources[] |
object[] | 每项包含 relativePath、url、version、expiresAt,供前端加载 URDF 和 mesh |
resourceIssues[] |
object[] | 当前组件的资源清单提示,每项含 code、category、componentCode、message |
0 组件承担指定侧时,component.category 保留真实类别,实例标识和替代分组使用装配角色。例如 {matchId}:ARM_L:1 可以对应 category=ARM_0,仍按左臂的数量和参数条件检查;每个实例只计入一个角色,部位分组及整机汇总不重复计算。候选沿用现有评分和编码排序。显式排除同时约束真实类别与装配角色,不能通过中性兼容绕过。0 组件的其他接口不因安装侧而改写。新规则不回写历史方案,使用新的 messageId 重新生成。
六足模板
目录支持 biped(默认人形/双足)和 hexapod(六足)。明确说“拼一个六足机器人”时选择 hexapod,不会回退到双足模板。六足模板只必需一个 TORSO_0,并生成 LEG、FOOT 两组各至少6个实例的要求;L/R/0 由实际接口决定,不强制分成左右各三,也不默认添加头、腰、臂、手或尾。未说明形态的需求仍沿用默认双足模板。
六足/六足机器人/hexapod 等同义词会参与名称与说明匹配。例如说明“六足蜘蛛机器人躯干”可命中“六足机器人”,随后沿该躯干的六个足部接口分别生成实例;相同 child 的三个左足接口和三个右足接口各自独立占用。六足分组使用现有 templatePartGroups、missingPartGroups 结构,没有新增消息参数。目录版本为 2026-10-16-hexapod-template,历史方案须通过新的 messageId 重新生成。
名称或说明中的六足标注用于候选相关性;六足模板与接口连接不证明行走速度、载荷或稳定性达标,这类要求继续单独核对。
默认人形与中性组件
默认人形的 requiredParts 为 TORSO_0/HEAD_0/WAIST_0,其余部位由 templatePartGroups 表达。四组均允许同一部位的 L/R/0,minimumQuantity=2;不会把所有候选类别都当成必须各装一个。
{
"requiredParts": ["TORSO_0", "HEAD_0", "WAIST_0"],
"templatePartGroups": [
{"family": "ARM", "categories": ["ARM_L", "ARM_R", "ARM_0"], "minimumQuantity": 2},
{"family": "HAND", "categories": ["HAND_L", "HAND_R", "HAND_0"], "minimumQuantity": 2},
{"family": "LEG", "categories": ["LEG_L", "LEG_R", "LEG_0"], "minimumQuantity": 2},
{"family": "FOOT", "categories": ["FOOT_L", "FOOT_R", "FOOT_0"], "minimumQuantity": 2}
]
}
以上是后端规范化结果的摘录,不能直接提交到消息接口或结构化匹配接口。单部位未说明左右时,AI 默认推断为 _0;明确左右则保留 L/R。物理接口按父到子的方向判断:LINK_ARM_L 可接 LINK_ARM_L/0,LINK_ARM_R 可接 LINK_ARM_R/0,LINK_ARM_0 只接 LINK_ARM_0,手、足、脚同理。明确左右需求可由安装到该侧接口的 0 类组件满足。
两个 ARM_0 实例或一个 ARM_L 加一个 ARM_0 实例均可满足 ARM 组;同款组件实例独立计数。接口不足时,例如只有一个可连接的臂,缺口如下,方案状态为 partial:
{
"missingPartGroups": [
{"family": "ARM", "categories": ["ARM_L", "ARM_R", "ARM_0"], "reason": "NO_COMPATIBLE_CONNECTION", "expectedQuantity": 2, "actualQuantity": 1, "missingQuantity": 1}
]
}
明确类别和参数要求仍单独生效,同一实例可同时计入具体类别与所属组,但总质量和自由度只累计一次。partRequirements[].quantity 限制该具体类别的数量;模板不能突破这个限制,有冲突时保留组缺口。明确排除项从组候选中移除,整个部位被排除时移除该默认组。自动增补仍受参数条件和24实例上限约束,默认不加入尾部。
数量入参与多实例返回示例
消息接口的数量仍用自然语言提交:
{
"messageId": "m-four-arms",
"text": "拼一个躯干和4个右臂",
"attachmentIds": []
}
后端在 data.result.request.partRequirements[] 中生成右臂的数量条件,例如下面这个条目:
{
"category": "ARM_R",
"quantity": 4
}
quantity 为 1–24 的 JSON 整数;省略或为 null 表示先覆盖各个所需类型,再填满这些类型的可匹配剩余接口。自动填充以可验证的硬要求为前提,不为多装组件而破坏本可满足的整机质量或自由度条件;明确数量不足或硬条件无法满足时保留差异。每个物理接口只能连接一个实例;同 child 的多个 frames 元素是不同接口,不合并。新增 ARM_0/HAND_0/LEG_0/FOOT_0 后,默认人形以部位分组要求各至少两个实例,具体类型按单向兼容接口连接选择;六足另使用 hexapod 模板的 LEG/FOOT 各至少六个实例要求。
双足模板直接使用 LEG_L/LEG_R。腰部的 LINK_LEG_L/R 接口可安装同侧或 LINK_LEG_0 的足部组件;装配角色保留 LEG_L/LEG_R,公开 component.category 返回实际选中的 LEG_L/LEG_R/LEG_0,原始 urdfInfo 不变。旧 pedal_l/pedal_r 兼容输入会归一化为 LEG_L/LEG_R。部署类型统一修复后,旧方案需要发送新的 messageId 重新生成。
下面为独立的四实例场景:假设躯干 CW-TORSO-004 有四个原始接口 frames[0] 至 frames[3],它们的 interfaceType=ARM_R、child=LINK_arm_r,name 均为 J_ARM;每个右臂实例均使用自身的 frames[0] 接入,其 child 同样为 LINK_arm_r。躯干质量 2kg,每个右臂质量 1.2kg、4 个自由度。
以下仅摘录该场景的 data.match 中与多实例有关的字段;component 仅展示编码和类别,实际仍返回上述完整 DTO、资源及其他方案字段:
{
"status": "complete",
"rootCategory": "TORSO_0",
"searchLimited": false,
"totals": {
"degreesOfFreedom": 16,
"massKg": 6.8,
"knownMassKg": 6.8,
"massComplete": true
},
"components": [
{
"instanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"component": {
"componentCode": "CW-TORSO-004",
"category": "TORSO_0"
}
},
{
"instanceId": "DM-55555555555555555555555555555555:ARM_R:1",
"component": {
"componentCode": "CW-ARM-001",
"category": "ARM_R"
}
},
{
"instanceId": "DM-55555555555555555555555555555555:ARM_R:2",
"component": {
"componentCode": "CW-ARM-001",
"category": "ARM_R"
}
},
{
"instanceId": "DM-55555555555555555555555555555555:ARM_R:3",
"component": {
"componentCode": "CW-ARM-001",
"category": "ARM_R"
}
},
{
"instanceId": "DM-55555555555555555555555555555555:ARM_R:4",
"component": {
"componentCode": "CW-ARM-001",
"category": "ARM_R"
}
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"connections": [
{
"parentInstanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-55555555555555555555555555555555:ARM_R:1",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 0,
"childFrameIndex": 0
},
{
"parentInstanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-55555555555555555555555555555555:ARM_R:2",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 1,
"childFrameIndex": 0
},
{
"parentInstanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-55555555555555555555555555555555:ARM_R:3",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 2,
"childFrameIndex": 0
},
{
"parentInstanceId": "DM-55555555555555555555555555555555:TORSO_0:1",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-55555555555555555555555555555555:ARM_R:4",
"childFrame": "INCOMING_arm_r",
"childRootLink": "ARM_ROOT",
"interfaceChild": "LINK_arm_r",
"parentFrameIndex": 3,
"childFrameIndex": 0
}
],
"issues": []
},
"missingParts": [],
"missingPartGroups": []
}
四个右臂共用组件编码与资源 URL,但前端创建四个模型实例。双方接口均按 (instanceId, frameIndex) 记录占用:四个连接分别使用躯干下标 0–3;四个右臂的下标虽然都是 0,但属于不同实例,不会冲突。躯干和组件原始 frames 数组不重排、不改写。
missingParts[] 包含 category、reason、expectedQuantity、actualQuantity、missingQuantity。明确要求 4 件但只能连接 2 件时,后三项分别为 4、2、2;接口不兼容或接口数量不足沿用 NO_COMPATIBLE_CONNECTION。单次最多 24 个实例(含唯一躯干),达到实例、候选或搜索上限时 searchLimited=true,保留已有组合并通过 assembly.issues 提示。
连接字段与前端定位
data.match.assembly 包含 status、rootInstanceId、connections[]、issues[]。每个 connections[] 对象的字段如下:
| 字段 | 类型 | 说明 |
|---|---|---|
parentInstanceId |
string | 父实例标识,对应 components[].instanceId |
parentFrameIndex |
integer | 父组件原始 component.urdfInfo.frames 的零起始下标 |
childInstanceId |
string | 子实例标识,对应 components[].instanceId |
childFrameIndex |
integer | 子组件原始 component.urdfInfo.frames 的零起始下标 |
interfaceChild |
string | 父接口原始 child,非空;子接口 child 可以是同部位的 0 |
parentFrame |
string | 父接口原始 name,缺失时可为空字符串;仅作辅助信息 |
parentLink |
string/null | 父接口原始 parent,缺失时为 null |
childFrame |
string/null | 子接口原始 name,缺失时为 null;仅作辅助信息 |
childRootLink |
string/null | 子组件原始 rootLink,缺失时为 null |
前端先按实例标识找到两个组件,再分别用 parentFrameIndex、childFrameIndex 读取各自的原始 frame;父 frame 的 child 等于 interfaceChild;子 frame 的 child 按兼容规则可不同,例如父 LINK_ARM_L 对应子 LINK_ARM_0,不能假设双方 child 相等。frame 名称可以重复或缺失,不能用名称代替实例与下标定位。
后端只返回连接关系,不返回 matrixLayout、parentRootToInterface、childRootToInterface、childRootRelativeToParentRoot 或连接摆放用的 xyz/rpy。前端加载每个实例的 URDF 后,根据双方原始 frames 或模型信息决定摆放。原始 urdfInfo 中已有的 xyz/rpy、axis、limits 等仍完整保留;旧的 urdfInfo.assembly 可以存在,不是必填项,不参与连接资格判断。
接口元数据、坐标和资源清单异常通过 assembly.issues / resourceIssues 提示,已有组合仍可为 ready。元数据提示可包含 instanceId 和 frameIndex,无法定位具体实例或下标时可能为 null;合并进 assembly.issues 的资源提示仍为上述四字段结构。ready 仅表示连接关系已生成,不证明安装坐标、承载或运动能力通过验证。
替代候选组包含目标 instanceId;仅替换对应实例,应用该候选返回的完整 assembly、totals 和校验结果。多个同类型实例分别有替代组,不按 category 整批替换;多个替代预览不能直接叠加。第 4 节提供包含分组外层的完整示例。
加载模型时保留 URDF 相对路径目录;OSS/CDN 须允许前端 CORS。每个实例都独立摆放,资源 URL 可以复用或缓存;用户需求图片继续使用需要 Bearer Token 的私有预览接口。
AI 接口与结构化 POST /api/robot-matches 共用选件连接规则,但返回包装不同:AI 使用 components[].instanceId={matchId}:{装配角色}:{序号} 和 assembly.connections[];结构化接口使用 parts[].instanceId={装配角色}:{序号} 和顶层 connections[],详见 结构化接口文档。
6. 结果刷新与错误
已保存方案是本次生成时的快照;本次升级不回写历史结果,旧矩阵格式或旧阻塞状态需要发送新 messageId 重新生成。调整需求、组件版本变化、补齐资源或需要重新选件时,在同一会话发送新的 messageId,例如“按原需求重新生成”,后端重新理解当前有效需求并生成新方案。旧版本查询返回 superseded,不会继续返回旧 match。重发原消息编号仅恢复原任务或结果,不触发刷新。
retry 只用于失败或已停止的当前任务;processing 时查询或重订阅原消息,ready 时直接显示结果。部分方案无需接受降级;degradationAcceptanceRequired、degradationAccepted 为兼容字段,新生成结果均为 false。安装基准、坐标或资源异常仍通过 assembly.issues 返回,不把未满足或未验证的需求标成已达标。
错误响应示例:
{
"code": "DEMAND_REVISION_CONFLICT",
"message": "需求版本已更新,请查看最新生成结果",
"data": null,
"requestId": "frontend-demand-001"
}
| HTTP / 错误码 | 前端处理 |
|---|---|
422 INVALID_REQUEST / DEMAND_INPUT_TOO_LARGE |
修正输入或新建会话 |
404 DEMAND_NOT_FOUND |
无记录、已过期或不属于当前用户;新建会话 |
409 DEMAND_REVISION_CONFLICT |
查询最新生成结果并使用其版本;重复消息编号内容须一致 |
SSE COMPONENT_REVISION_CONFLICT |
生成期间组件已变化,发送新消息重新生成 |
409 DEMAND_ATTACHMENT_MISSING |
原图已失效,重新上传并发送新消息 |
429 DEMAND_BUSY |
暂无解析容量;已有 analysisId 时查询状态后稍后 retry,未取得编码时用原 messageId 和原内容重发取得任务状态,再按返回编码重试 |
503 DEMAND_UNAVAILABLE / DEMAND_ATTACHMENT_UNAVAILABLE |
暂不可用,稍后 retry 或重传 |
SSE DEMAND_TIMEOUT / DEMAND_PROVIDER_FAILURE / DEMAND_INCOMPLETE / DEMAND_INVALID_OUTPUT |
生成失败且没有可用新方案,可重试 |
SSE DEMAND_CANCELLED |
已停止;当前版本可 retry |
网关对 SSE 关闭缓冲,超时应长于后端解析超时加 30 秒(默认超过 210 秒)。模型通常不是即时返回,等待期间保留停止入口。GET 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。