1079 lines
57 KiB
Markdown
1079 lines
57 KiB
Markdown
# 文字 / 图片自动生成机器人(前端联调)
|
||
|
||
服务地址默认 `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` 解析接口可恢复状态和已生成的完整装配方案;当前未提供整个会话列表与消息历史列表接口。
|