# 文字 / 图片自动生成机器人(前端联调) 服务地址默认 `http://127.0.0.1:8991`。本流程接收用户文字、图片,自动理解需求、选件并校验装配,完成响应直接包含机器人方案。无需追问、确认或接受降级后才能显示。所有 JSON 接口和 SSE 事件数据沿用 `{code, message, data, requestId}`。 本文已按当前后端代码核对(2026-10-26),新生成结果的 `result.analysis.schemaVersion` 为 `multimodal-v1.6-component-replacement`。新方案的类别和实例编码使用[完整16类大写编码](api.md#36-角色映射),足部使用 `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.change` | 对话替换结果:`applied` 已替换,`unchanged` 已保留原方案;普通生成及历史结果可不包含 | | `data.match.missingParts[]` | 包含期望、实际、缺少数量;缺件时仍可展示已有连通组合 | | `data.result.request.templatePartGroups[]` | 默认人形的四组部位合计要求,由后端生成 | | `data.match.missingPartGroups[]` | 模板部位合计缺口;不会将同组未选类别逐一报为缺件 | 历史快照不会自动升级,联调新协议时请使用新的 `messageId` 生成结果。 ## 1. 前端调用顺序 1. 创建会话,保存 `conversationId`。 2. 有图片时先上传到该会话,保存 `attachmentId`;仅文字可跳过。 3. 发送消息,使用 POST + fetch 接收 SSE;后端在同一任务中完成需求理解、自动选件和装配校验。 4. 收到 `analysis.completed`,直接读取 `data.match`。当 `match.assembly.status=ready` 时,按 `instanceId` 加载 `match.components` 的资源,再根据 `match.assembly.connections` 定位双方接口并由前端摆放;`partial` 也可直接显示有效的已有组合。 5. 简短展示 `warnings`、缺件及未满足/未验证项;不弹出追问、确认或必须接受降级的页面。`assembly.status=blocked` 或 `status=no_match` 时展示具体原因,不伪造连接位姿。 6. 用户需要调整时,在同一会话发送新消息。例如“改成右臂扭矩至少30N·m”生成新方案;“换个左臂”基于本会话最近保存成功的服务端方案,只替换指定目标并生成新版本,见下文“对话局部替换”。 7. 需要长期保留时,将当前 `analysisId` 作为 `analysisCode` 调用[保存为我的项目](project-api.md)。项目可上传 OSS 封面、发布到广场或被其他用户 fork;保存后不随需求会话过期清理。 先完成[邮箱与图片验证码登录](auth-api.md),所有业务请求头携带 `Authorization: Bearer `,不再依赖匿名 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` 和组件详情保留,均需登录,见 [组件接口文档](api.md)。本流程的状态为小写,与既有接口的 `MATCHED/FALLBACK/PARTIAL/NO_MATCH` 分开使用。 ## 2. 创建会话与上传图片 `POST /api/robot-conversations`,无请求体。返回示例: ```json { "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。 ```json { "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`;示例见[登录文档](auth-api.md#2-前端调用与需求归属)。 文字与图片可在同一条消息中提交,服务端会分别保留来源。`observations.kind=user_text` 的内容须是对应用户文字的连续原文,展示结果中的 `imageId=""`、`region=[]`;模型给真实文字附加了同消息的图片编号或定位框时,后端验证归属后清除这些多余标记,不中断生成。图片 OCR/视觉观察仍须关联正确的附件和所属消息;未知图片、错误消息、伪造原文和重复证据编号继续拒绝。模型请求的 Schema 按本轮真实消息和附件编码限定来源范围;校验失败日志包含具体字段、`reasonCode` 和观察序号,不记录图片或完整对话。 ## 3. 发送消息并直接生成 `POST /api/robot-conversations/{conversationId}/messages`,请求示例: ```json { "messageId": "m1", "text": "我要一个右臂,扭矩至少20N·m", "attachmentIds": [] } ``` 图文消息示例: ```json { "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](api.md)。 文字和图片不能同时为空。相同编号但不同内容返回 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` 均为空。 事件格式示例: ```text 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): ```javascript 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}` 使用同一数据结构: ```json { "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-27-hexapod-connectors", "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.6-component-replacement", "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}`;不作为消息或结构化匹配入参 | | `result.request.optionalParts` | 模板允许按需使用的连接部位编码;无可选连接件时省略,不作为消息或结构化匹配入参 | | `match.missingPartGroups` | 部位合计缺口,每项含 `family`、`categories`、`reason`、`expectedQuantity`、`actualQuantity`、`missingQuantity`;有缺口时为 `partial` | | `result.analysis.schemaVersion` | 新生成结果为 `multimodal-v1.6-component-replacement`;旧快照可能仍为旧协议 | | `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` | 公开组件字段与 [组件详情](api.md) 一致,不包含数据库主键和独立 OSS 对象键。`components[].component.rotationAxis` 和 `alternatives[].items[].component.rotationAxis` 返回 `X`、`Y`、`Z` 或 null;旋转轴非必填,null 表示组件未设置,不能默认成某个轴或覆盖 URDF 中的关节 axis。`urdfMainPath` 与资源清单中的 `relativePath` 保留目录层级,使用 `resources[].url` 加载模型和 mesh。公开资源 `expiresAt=null`,不是临时签名;`version` 表示组件版本。 ### 躯干优先规则 新生成方案及替代候选仅使用启用状态(`status=ENABLED`)的组件;禁用组件仍可按编码查询详情,历史生成结果和已保存项目继续保留。生成结果和资源回查发现组件已禁用时,沿用 `COMPONENT_REVISION_CONFLICT` 业务错误;SSE 返回 `analysis.failed` 事件,需要发送新消息重新生成方案。 拼装仅检索同时具备非空 `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`,不会偷偷补入躯干;同款组件支持多个独立实例,躯干始终固定一个。 躯干先按自身硬条件、数值差距、偏好、整机功能文本与关键词相关性排序。关键词先比较命中的不同需求数量,再比较字段权重,因此说明中匹配六足需求的躯干不会被只命中泛称“机器人”的普通躯干压过;这些条件相同后优先选择能接更多所需角色的接口集合,最后按编码稳定排序。整机自由度和质量目标在后续组合阶段评价,不直接当作躯干单件的数值要求。 选定躯干后不因其他躯干能多接几件或更接近整机总量而自动换根。其他组件须能通过现有接口路径连接到这个躯干;例如右手通过右臂连接,允许沿链匹配。模板可通过后端生成的 `request.optionalParts` 允许必要的连接部件,例如六足腰部;仅在连接件具有可连接缺少部位的其他接口时使用,同类可选连接件最多一个,并遵守明确排除项。目录未允许的部位仍不自动补入。达标搜索和降级搜索沿用同一个躯干。缺件时返回该躯干及可连接的部分方案;无可用躯干时返回 `no_match`,不会用头部或手臂代替根。 ### 缺件时展示已有组合 `status=partial` 可以同时有 `assembly.status=ready`。例如需要躯干、右臂和头部,库存只有能连接的躯干与右臂,且两件具有匹配接口,返回如下片段: ```json { "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 而阻塞。 ### 对话局部替换 请求仍使用消息接口和原有 `messageId`、`text`、`attachmentIds`,不增加客户端方案或目标字段。例如: ```json {"messageId":"m2","text":"换个左臂","attachmentIds":[]} ``` - “换个头”替换现有头部;“换个腿”替换整组 LEG 实例,包括左右及中性组件;“脚”对应 FOOT,不联动替换。 - 纯换件沿用已保存的有效需求,不把模型重新描述的历史要求或“未指定新头部材质、尺寸”等说明当作新增条件;只有当轮明确附带的新要求才参与新增约束校验。 - “加上左手”“补上左手”“装上右脚”等属于补充部件需求,走普通生成(`operation.type=generate`),不按替换排除现有组件。即使当前方案已经包含该部位,也不能擅自理解为“换成另一个”。 - 换件动作仅在当轮执行,不累计历史目标。例如先“换个头”、再“单独换个左臂”,第二轮只更换左臂;模型重复输出的历史目标会在来源校验后移除,没有当轮有效目标时拒绝执行。 - “换个左臂”只替换左侧全部实例,不为外观配套自动更换右臂;“换第二个左臂”只替换该侧按序号排列的第二个实例。也可在文字中明确当前完整实例编码。 - 多个目标一起选件和校验,排除目标组原组件编码;固定其他组件和父子拓扑,不增加组件,不丢弃原有子组件。新增硬参数必须满足且可验证,已有缺件和未验证项保留,不允许新增硬条件违例或扩大既有数值偏差。 - 任一目标没有替代件、连接不兼容、要求不满足或搜索达到上限时,整组保留原组合及原有效需求,仍保存新版本;未执行的新条件不会自动成为后续有效约束。后续替换可以继续基于该保留版本。 - 本会话没有可用历史装配时,通过 `analysis.failed` 返回 `DEMAND_BASE_PLAN_UNAVAILABLE`,需先生成方案。模型、网络故障及主动停止继续沿用原有失败/停止流程。 替换响应新增可选 `match.change`: ```json { "status": "applied", "baseAnalysisId": "DN-22222222222222222222222222222222", "targetInstanceIds": ["DM-33333333333333333333333333333333:ARM_L:1"], "reasonCode": "", "message": "已替换指定组件,其余组件保持不变" } ``` `status=unchanged` 时仍返回完整保留方案,`warnings` 和 `change.message` 说明原因。`reasonCode` 可为 `TARGET_NOT_FOUND`、`NO_REPLACEMENT_CANDIDATE`、`NO_COMPATIBLE_CONNECTION`、`REQUIREMENTS_NOT_SATISFIED`、`COMPONENT_REVISION_CONFLICT`、`SEARCH_LIMIT` 或 `INVALID_BASE_PLAN`。候选和搜索有界,不能把未找到替代件解释为整个库存绝对不存在替代件。组件已变化时保留的是历史快照,需重新生成后再继续替换。 每轮使用新的分析、匹配及实例编码,连接和候选引用同步更新。前端应用返回的完整方案;不能把未更换组件继续绑定到上一轮实例编码。旧版本继续为 `superseded`。新解析结果的 `result.analysis.operation` 记录 `generate/replace`、目标选择条件和当轮来源证据,仅为服务端解析结果,不是消息请求字段。 ### 默认同型号优先 默认生成和替代候选优先保持 ARM、HAND、LEG、FOOT 各部位族的型号一致。在组件齐全、接口兼容和明确需求优先的前提下,型号一致性优先于普通关键词相关性。只归一化名称中的明确方向标记,不通过模糊相似度猜型号,例如“臂_L_臂3自由度左”和“臂_R_臂3自由度右”视为同型号;3 自由度和 4 自由度不会混为同一型号。没有可靠配套名称时不保证外观一致,同一中性组件可以重复用于不同实例。 同型号是软偏好,不覆盖用户明确指定的参数或型号,也不扩大单侧替换范围。该规则仅影响新计算结果,不回写历史快照。 ### 替代项示例 下面是一个完整的 `alternatives[]` 分组示例,`instanceId` 指定被替换的右臂实例,`items[]` 是可替换它的候选组件。没有可用替代项时该分组的 `items=[]`: ```json { "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 由实际接口决定,不强制分成左右各三。`request.optionalParts=["WAIST_0"]` 允许按需连接具有六个足接口的腰部,不要求所有六足方案都装腰部,不默认添加头、臂、手或尾。该字段由后端生成,不作为消息或结构化匹配入参。未说明形态的需求仍沿用默认双足模板。 六足/六足机器人/hexapod 等同义词会参与名称与说明匹配。例如说明“六足蜘蛛机器人躯干”可命中“六足机器人”,随后沿该躯干的六个足部接口分别生成实例;相同 child 的三个左足接口和三个右足接口各自独立占用。六足分组使用现有 `templatePartGroups`、`missingPartGroups` 结构,没有新增消息参数。目录版本为 `2026-10-27-hexapod-connectors`,历史方案须通过新的 `messageId` 重新生成。 名称或说明中的六足标注用于候选相关性;六足模板与接口连接不证明行走速度、载荷或稳定性达标,这类要求继续单独核对。 “六足构型”这类整机构型条目按实际连接的 LEG、FOOT 数量及模板缺件情况校验,`requirementChecks.field=templatePartGroups`,不要求组件另填同名的 `shape`。“1台/一台/一个机器人”的单台数量可验证;只有形成完整所需组合后才标记满足,尚有缺件时保留未验证。多台整机仍不支持,不会把整机数量分摊到每个部件,也不要求组件备注包含“数量1台”。 ### 默认人形与中性组件 默认人形的 `requiredParts` 为 `TORSO_0/HEAD_0/WAIST_0`,其余部位由 `templatePartGroups` 表达。四组均允许同一部位的 L/R/0,`minimumQuantity=2`;不会把所有候选类别都当成必须各装一个。 ```json { "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`: ```json { "missingPartGroups": [ {"family": "ARM", "categories": ["ARM_L", "ARM_R", "ARM_0"], "reason": "NO_COMPATIBLE_CONNECTION", "expectedQuantity": 2, "actualQuantity": 1, "missingQuantity": 1} ] } ``` 明确类别和参数要求仍单独生效,同一实例可同时计入具体类别与所属组,但总质量和自由度只累计一次。`partRequirements[].quantity` 限制该具体类别的数量;模板不能突破这个限制,有冲突时保留组缺口。明确排除项从组候选中移除,整个部位被排除时移除该默认组。自动增补仍受参数条件和24实例上限约束,默认不加入尾部。 ### 数量入参与多实例返回示例 消息接口的数量仍用自然语言提交: ```json { "messageId": "m-four-arms", "text": "拼一个躯干和4个右臂", "attachmentIds": [] } ``` 后端在 `data.result.request.partRequirements[]` 中生成右臂的数量条件,例如下面这个条目: ```json { "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、资源及其他方案字段: ```json { "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[]`,详见 [结构化接口文档](api.md)。 ## 6. 结果刷新与错误 已保存方案是本次生成时的快照;本次升级不回写历史结果,旧矩阵格式或旧阻塞状态需要发送新 messageId 重新生成。调整需求、组件版本变化、补齐资源或需要重新选件时,在同一会话发送新的 `messageId`,例如“按原需求重新生成”,后端重新理解当前有效需求并生成新方案。旧版本查询返回 `superseded`,不会继续返回旧 `match`。重发原消息编号仅恢复原任务或结果,不触发刷新。 `retry` 只用于失败或已停止的当前任务;`processing` 时查询或重订阅原消息,`ready` 时直接显示结果。部分方案无需接受降级;`degradationAcceptanceRequired`、`degradationAccepted` 为兼容字段,新生成结果均为 false。安装基准、坐标或资源异常仍通过 `assembly.issues` 返回,不把未满足或未验证的需求标成已达标。 错误响应示例: ```json { "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` 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。