Files
cadworld/cadworld-api/docs/robot-demand-api.md
T

51 KiB
Raw Blame History

文字 / 图片自动生成机器人(前端联调)

服务地址默认 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. 前端调用顺序

  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 调用保存为我的项目。项目可上传 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 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。