Files
2026-10-27 16:49:51 +08:00

1079 lines
57 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 文字 / 图片自动生成机器人(前端联调)
服务地址默认 `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 <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` 和组件详情保留,均需登录,见 [组件接口文档](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` 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。