34 KiB
文字 / 图片自动生成机器人(前端联调)
服务地址默认 http://127.0.0.1:8991。本流程接收用户文字、图片,自动理解需求、选件并校验装配,完成响应直接包含机器人方案。无需追问、确认或接受降级后才能显示。所有 JSON 接口和 SSE 事件数据沿用 {code, message, data, requestId}。
1. 前端调用顺序
- 创建会话,保存
conversationId。 - 有图片时先上传到该会话,保存
attachmentId;仅文字可跳过。 - 发送消息,使用 POST + fetch 接收 SSE;后端在同一任务中完成需求理解、自动选件和装配校验。
- 收到
analysis.completed,直接读取data.match。当match.assembly.status=ready时,使用match.components的资源及match.assembly.connections加载并拼装;partial也可直接显示有效的已有组合。 - 简短展示
warnings、缺件及未满足/未验证项;不弹出追问、确认或必须接受降级的页面。assembly.status=blocked或status=no_match时展示具体原因,不伪造连接位姿。 - 用户需要调整时,在同一会话发送新消息,例如“改成右臂扭矩至少30N·m”,后端生成新版本并返回新方案。
浏览器需要保留后端设置的 HttpOnly Cookie,所有调用均设置 credentials:"include"。不需要读写 Cookie 值,也不传 userId、模型 Key 或系统提示词。当前按匿名浏览器访客隔离对话和图片,清除 Cookie 后不能访问之前记录。生产使用 HTTPS;前后端通过同站点 /api 代理接入。开发跨端口需后端配置具体允许域名,并使用一致的主机名(不要混用 localhost 与 127.0.0.1)。
接口清单
| 方法 | 路径 | 请求 | 返回 |
|---|---|---|---|
| POST | /api/robot-conversations |
无请求体 | 会话编码、初始版本、有效期 |
| POST | /api/robot-conversations/{conversationId}/attachments |
multipart file |
图片编码、预览地址 |
| GET | /api/robot-conversations/{conversationId}/attachments/{attachmentId} |
无 | 私有原图,需要 Cookie |
| 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 展示,仍需携带 Cookie。
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 表示无图 |
文字和图片不能同时为空。相同编号但不同内容返回 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(conversationId, message, onEvent, signal) {
const response = await fetch(`/api/robot-conversations/${conversationId}/messages`, {
method: "POST",
credentials: "include",
headers: { "Content-Type": "application/json", "Accept": "text/event-stream" },
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 和 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"
}
}
]
},
"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"
}
],
"questions": [],
"warnings": [
"整机拼装固定一个躯干,已补入torso_0作为基础组件。"
],
"catalogVersion": "2026-10-14-auto-assembly",
"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"
}
],
"images": [],
"keywordEvidence": [
{
"term": "右臂",
"evidenceIds": [
"e1"
]
}
],
"schemaVersion": "multimodal-v1.2-auto-assembly",
"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": "所选组件的登记参数满足该条件"
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:torso_0",
"matrixLayout": "column-major",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:arm_r",
"childFrame": "ARM_ROOT",
"childRootLink": "ARM_ROOT",
"parentRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.1,
0,
0,
1
],
"childRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1
],
"childRootRelativeToParentRoot": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.1,
0,
0,
1
]
}
],
"issues": []
},
"components": [
{
"instanceId": "DM-33333333333333333333333333333333:torso_0",
"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",
"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": [],
"assembly": {
"mountingFrame": "ARM_ROOT",
"pairingConvention": "coincident_frames"
}
},
"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": []
},
{
"category": "arm_r",
"items": []
}
]
}
},
"requestId": "frontend-demand-001"
}
| 字段 | 说明 |
|---|---|
status |
新流程为 processing / ready / failed / cancelled / superseded;ready 表示本次方案已生成,具体能否装配看 match.assembly.status。needs_clarification 仅可能存在于旧记录 |
canSubmit |
旧客户端兼容字段,新流程 ready 时为 true;无需展示确认按钮,不代表所有要求达标 |
questions |
新生成结果固定为 [],不发起追问 |
warnings |
来源、推断或能力承载方面的说明,供核对 |
result.request |
规范化五字段需求;未提供的约束不会补成 0 |
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 个兼容替代项,见下文 |
requirementChecks[] |
对应 intentId,状态 satisfied / unmet / unverified;前端关联解析中的详细需求 |
unmetRequirements |
字段差距,包括偏好差距;硬要求判定以详细校验为准 |
totals |
组件标称参数求和;不重复统计 BOM。质量未知时 massKg=null,knownMassKg 为已知部分 |
missingParts |
缺失角色和原因,仅提示完整性,不阻塞已有组件装配;没有可用躯干时返回 no_match,其他现存角色可标记 NO_TORSO;仍是 HTTP 200 |
searchLimited |
候选或搜索被截断,本方案不是已证明的全局最优 |
degradationAcceptanceRequired |
新生成方案及替代候选固定为 false;缺件和未满足/未验证项作为结果说明,不要求先接受 |
assembly.status |
ready:已有组件的安装与资源校验通过,可应用返回的连接位姿;blocked:展示 issues,不自动拼装。与需求是否完整达标分别判断 |
公开组件字段与 组件详情 一致,不包含数据库主键和独立 OSS 对象键。urdfMainPath 与资源清单中的 relativePath 保留目录层级,使用 resources[].url 加载模型和 mesh。公开资源 expiresAt=null,不是临时签名;version 表示组件版本。
躯干优先规则
拼装仅检索同时具备非空 step_object_key 和已上传 URDF 主文件(非空 urdf_main_object_key)的组件;消息自动生成和替代候选使用同一筛选规则。仅上传 STEP 的组件不会参与拼装。候选仍须满足 urdfInfo.rootLink、frames 及现有连接元数据规则,装配阶段继续校验安装基准和资源清单。
整机结果始终以 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"
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:torso_0",
"matrixLayout": "column-major",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:arm_r",
"childFrame": "ARM_ROOT",
"childRootLink": "ARM_ROOT",
"parentRootToInterface": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1],
"childRootToInterface": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
"childRootRelativeToParentRoot": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 0, 0, 1]
}
],
"issues": []
}
}
前端加载 components[] 中已有的模型并应用上述连接,提示“缺少头部”,同时保留降级接受入口。展示模型无需先接受降级,展示不等于用户已经接受。仅有有效躯干时也可返回 ready,此时 connections=[],前端显示躯干本身。
缺失角色不返回占位组件或伪造连接。totals 仍是已有组件的标称参数之和;所需组件未齐全时,整机总量要求仍可能为 unverified。替代候选遵循同一规则。没有可用躯干、安装基准缺失、连接图异常或资源清单不完整仍返回 blocked;新结果的 assembly.issues 不再包含 MISSING_PARTS 或 DEGRADATION_NOT_ACCEPTED。
替代项示例
下面是 alternatives[].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": [],
"assembly": {
"mountingFrame": "ARM_V2_ROOT",
"pairingConvention": "coincident_frames"
}
},
"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": "所选组件的登记参数满足该条件"
}
],
"assembly": {
"status": "ready",
"rootInstanceId": "DM-33333333333333333333333333333333:torso_0",
"matrixLayout": "column-major",
"connections": [
{
"parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
"parentFrame": "J_ARM",
"parentLink": "BASE",
"childInstanceId": "DM-33333333333333333333333333333333:arm_r",
"childFrame": "ARM_V2_ROOT",
"childRootLink": "ARM_V2_ROOT",
"parentRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.1,
0,
0,
1
],
"childRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1
],
"childRootRelativeToParentRoot": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.1,
0,
0,
1
]
}
],
"issues": []
},
"degradationAcceptanceRequired": false
}
替代结果以当前默认方案为基准,包含重新计算的汇总、校验和装配信息。前端切换时替换对应实例的组件与资源并应用该替代项的连接信息。躯干替代项表示替换当前唯一躯干,不能作为第二个躯干追加。多个替代项同时切换不能直接叠加各自预览;当前没有多项替换后的服务端校验/方案保存接口,降级接受接口仅针对服务器保存的默认方案。
5. 装配连接与加载
assembly.connections[] 示例(属于躯干 + 右臂方案):
{
"parentInstanceId": "DM-33333333333333333333333333333333:torso_0",
"parentFrame": "J_ARM",
"parentLink": "MID",
"childInstanceId": "DM-33333333333333333333333333333333:arm_r",
"childFrame": "MOUNT",
"childRootLink": "ARM_ROOT",
"parentRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.1,
0,
0,
1
],
"childRootToInterface": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.02,
0,
0,
1
],
"childRootRelativeToParentRoot": [
1,
0,
0,
0,
0,
1,
0,
0,
0,
0,
1,
0,
0.08,
0,
0,
1
]
}
矩阵为 16 个数字,column-major,位移单位 m,角度来源为 rad。childRootRelativeToParentRoot 是子组件 root 相对父组件 root 的变换;父接口可能位于中间 link,后端已累积路径,不能再次叠加帧原始 xyz/rpy。前端世界变换为 父组件世界矩阵 × childRootRelativeToParentRoot。
parentRootToInterface、childRootToInterface 分别是两件组件自身根到安装接口的矩阵;连接计算遵循 父根到接口 × inverse(子根到接口)。childFrame 可以是指定 link 或 joint,childRootLink 保留文件原名。
每件子组件通过 urdfInfo.assembly 明确基准:
{
"mountingFrame": "ARM_ROOT",
"pairingConvention": "coincident_frames"
}
此对象嵌在 urdfInfo.assembly 中,安装帧须存在于文件图中。前端不根据草图生成机械坐标。缺少基准、多个同类父接口未配对、连接图异常、活动关节缺状态、资源清单不完整等都会返回 assembly.status=blocked。
加载模型时保留 URDF 相对路径目录;不要只取文件名,否则 meshes/... 引用会失效。OSS/CDN 须允许前端 CORS,组件资源直接加载公开 URL;用户需求图片走私有预览接口,不能复用模型公开域名。
6. 结果刷新与错误
已保存方案是本次生成时的快照。调整需求、组件版本变化、补齐资源或需要重新选件时,在同一会话发送新的 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 |
查询最新生成结果并使用其版本;重复消息编号内容须一致 |
409 COMPONENT_REVISION_CONFLICT |
组件已变化,发送新消息重新生成 |
409 DEMAND_ATTACHMENT_MISSING |
原图已失效,重新上传并发送新消息 |
429 DEMAND_BUSY |
暂无解析容量;查询状态后稍后 retry |
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 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。