# CAD Web AI Agent 前端对接 本文描述已实现的后端接口和 makeCAD 网页端需要完成的适配。后端不运行 CAD 引擎,不执行工具,也不持久保存聊天。**仅嵌入当前 makeCAD 网页构建不会自动启用 Agent**:原有模型客户端、CLI Agent 和聊天入口受桌面编译条件限制,需要前端新增网页 `ChatBackend`、工具适配器及文档生命周期管理。 调用链:makeCAD 面板 → `/api/cad/ai/chat` → 豆包 → 浏览器执行工具 → 携带结果再次请求。一次 HTTP 请求只推进一次模型推理。设计文件的保存与续编仍使用 [CAD 工作空间接口](frontend-cad-workspace.md)。 ## 登录、启用和能力 全部接口复用平台 `Authorization: Bearer `,不向网页下发方舟密钥或 Endpoint。推荐同源部署;iframe 使用受控宿主桥接时校验精确 origin、source 和请求关联编码,Token 不进入 URL。关闭、换账号或退出登录时取消旧请求并清理账号相关会话。 | 方法 | 路径 | 返回 | | --- | --- | --- | | GET | `/api/cad/ai/capabilities` | 普通统一 JSON 包装,data 为能力 | | POST | `/api/cad/ai/chat` | `text/event-stream`,每个 data 使用统一包装 | ```ts interface CadAiCapabilities { enabled: boolean; protocolVersion: 'cad-agent-v1'; model: string; tools: Array<{ name: string; description: string; parameters: object }>; limits: { requestBytes: number; // 4194304,仅 chat 请求 imageBytes: number; // 1048576,单图解码后字节 imageMaxEdge: number; // 2048 imagesPerRequest: number; // 2,包含全部历史中的图片 textBytes: number; // 524288(512 KiB),UTF-8 文本及结构化上下文 toolResultTextBytes: number; // 32768,单份工具结果的文字合计 historyItems: number; // 256 maxModelCallsPerTurn: number; // 默认 12 maxChangesPerTurn: number; // 默认 24 requestTimeoutSeconds: number;// 默认 300 requestsPerMinute: number; // 默认 30,工具续调同样计数 }; } ``` 先读能力,再启用面板中的平台 Agent。功能关闭或基础配置不完整时 `enabled=false`,能力接口仍返回 200;聊天接口返回 503。界面使用平台指定模型,隐藏本地 Agent、API Key、任意服务地址、模型切换及不受限权限选项。能力不兼容时要求更新网页构建,不能把原生桌面 Agent 当作回退。 平台助手输入区只保留一个别针附件入口,点击直接选择附件;在输入框中粘贴文字、图片或混合内容即可添加,不需要打开菜单或主动授权读取剪贴板。附件仍在读取时暂不发送,避免文字先发而图片遗漏。权限选择和“加入队列”按钮不展示;允许的当前文档操作默认执行,旧的本地权限配置不再触发确认。项目绑定、停止操作、账号鉴权及浏览器能力限制仍独立生效。 ## 请求和历史类型 ```ts type Content = | { type: 'text'; text: string } | { type: 'image'; mimeType: 'image/png' | 'image/jpeg'; data: string }; // image.data 是纯标准 Base64,不包含 data:image/... 前缀,不接受外链或 file_id。 type HistoryItem = | { type: 'message'; role: 'user' | 'assistant'; content: Content[] } | { type: 'toolCall'; callCode: string; name: string; arguments: object } | { type: 'toolResult'; callCode: string; isError: boolean; content: Content[] }; interface CadAiRequest { protocolVersion: 'cad-agent-v1'; documentSessionCode: string; turnCode: string; cadProjectCode?: string; history: HistoryItem[]; context: { documentRevision: string; selection?: object[] }; } ``` - `documentSessionCode`、`turnCode` 为前端生成的 1~64 位字母、数字、下划线或短横线编码。每次打开文档生成文档实例编码;一条用户消息的全部工具循环共用轮次编码。 - `cadProjectCode` 可省略,未保存的空白设计也能使用。提供时必须是当前账号未删除项目;其他人、不存在或已删除统一 404。 - `documentRevision` 是当前浏览器设计的修订标记,1~128 字符。它用于前端判断迟到结果,**不是云端保存的 version**,两者不能互换。 - `selection` 最多 64 个对象,采用 makeCAD 原生上下文描述,包含实体、特征或几何元素的稳定引用及必要尺寸;不发送全部 CAD 文件、整个网格或 OSS 链接。 - 文字内容不能为空字符串。单条 content 最多 16 块;助手 message 只接受文字,用户消息和工具结果可包含图片。角色不能为 system/developer。 - 每种 history 类型只填写对应字段。工具名称、参数 Schema 以能力接口为准,前端不能提交自己的工具定义、系统指令或模型配置。 历史必须以用户消息开头,发送时以本次用户消息或全部已配对的工具结果结尾。助手文字后可以连续出现多个 `toolCall`,其结果必须按调用顺序全部回填;`callCode` 在保留的历史内唯一,不允许缺失、重复或错配。 正常顺序示例:`用户 → 助手文字(可选) → 调用 A → 调用 B → 结果 A → 结果 B → 助手 → 新用户`。工具可以只有调用而没有说明文字;一次调用失败仍回填 `isError=true`,不要删除关联调用。 完整历史由前端持有,刷新或关闭页面后不恢复。超过总量、图片数或条目数时,裁剪最早的**完整用户轮次**,不单独删除调用或结果。当前轮次本身超限时停止并提示开启新聊天。图片限制覆盖历史图片:保留当前轮次需要的图片,必要时清理整轮旧历史。 ## SSE 事件和执行边界 每个事件的 data:`{code,message,data,requestId}`。成功 code 为 `OK`;心跳是 SSE 注释,不带 JSON。事件中的 data 均携带 `documentSessionCode` 和 `turnCode`。 | event | data 其他字段 | 前端行为 | | --- | --- | --- | | `text_delta` | `text` | 追加助手显示文本 | | `tool_call` | `callCode,name,arguments` | 展示待执行卡片,暂不执行 | | `completed` | `finishReason,output,usage` | 本步成功终态;output 是规范化 HistoryItem[] | | `error` | 无其他字段,错误在包装的 code/message | 停止本轮,保留设计;不执行待确认工具 | `completed.finishReason` 为 `stop` 或 `tool_calls`。`usage` 为 `{inputTokens,outputTokens,totalTokens}`,上游未提供时为 null。本步 `output` 是历史回填的唯一来源,不再把 text_delta 或 tool_call 额外拼进历史,避免重复。 **只有完整收到 `completed` 且 `finishReason=tool_calls` 后,才按 output 中的调用顺序执行。** 所有工具参数在上游完整结束后才会被后端验证和交付。截断、参数损坏、未知工具、拒绝、超时或断流不会产生成功 completed;显示过的文字不是执行依据。不要将模型自然语言中的伪工具调用作为命令运行。 使用带 Authorization 的 POST fetch 读取 SSE,不能使用只支持 GET 的原生 EventSource。下面的读取器处理 UTF-8 分片、跨包事件、CRLF、多行 data 及注释: ```ts async function* readSse(response: Response) { if (!response.ok) throw await response.json(); if (!response.headers.get('content-type')?.includes('text/event-stream') || !response.body) throw new Error('CAD AI 未返回 SSE'); const reader = response.body.getReader(); const decoder = new TextDecoder('utf-8', { fatal: true }); let buffer = ''; try { for (;;) { const { value, done } = await reader.read(); buffer += decoder.decode(value, { stream: !done }); if (buffer.length > 2 * 1024 * 1024) throw new Error('SSE 事件过大'); for (;;) { const boundary = /\r?\n\r?\n/.exec(buffer); if (!boundary) break; const block = buffer.slice(0, boundary.index); buffer = buffer.slice(boundary.index + boundary[0].length); let event = 'message'; const data: string[] = []; for (const line of block.split(/\r?\n/)) { if (line.startsWith('event:')) event = line.slice(6).trimStart(); if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); } if (data.length) yield { event, envelope: JSON.parse(data.join('\n')) }; } if (done) break; } } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); } } ``` 调用方还必须验证 requestId、文档和轮次关联编码,并要求成功终态;EOF 不等于完成。每次请求使用新的 AbortController,停止时 abort。读取 completed 后可以结束读取本步。 ### 两步请求示例 第一步请求: ```json { "protocolVersion": "cad-agent-v1", "documentSessionCode": "document-abc", "turnCode": "turn-001", "history": [{"type":"message","role":"user","content":[{"type":"text","text":"把宽度参数设为 40 mm"}]}], "context": {"documentRevision":"7","selection":[]} } ``` 假设本步 SSE 为: ```text event:tool_call data:{"code":"OK","message":"成功","data":{"documentSessionCode":"document-abc","turnCode":"turn-001","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}},"requestId":"req-a"} event:completed data:{"code":"OK","message":"成功","data":{"documentSessionCode":"document-abc","turnCode":"turn-001","finishReason":"tool_calls","output":[{"type":"toolCall","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}}],"usage":null},"requestId":"req-a"} ``` 确认文档仍然有效后执行 `set_parameter`,将 completed.output 和结果依次加入原 history,再次 POST: ```json { "protocolVersion":"cad-agent-v1", "documentSessionCode":"document-abc", "turnCode":"turn-001", "history":[ {"type":"message","role":"user","content":[{"type":"text","text":"把宽度参数设为 40 mm"}]}, {"type":"toolCall","callCode":"call_a","name":"set_parameter","arguments":{"name":"width","value":40}}, {"type":"toolResult","callCode":"call_a","isError":false,"content":[{"type":"text","text":"{\"name\":\"width\",\"value\":40,\"errors\":[]}"}]} ], "context":{"documentRevision":"8","selection":[]} } ``` 下一步可能继续调用工具,也可能回复并以 `finishReason=stop` 结束。工具文字结果可以是 JSON 字符串,保留实际错误;不得把失败改成成功。截图结果使用 image 块,同一 callCode 可以附带简短文字说明和图片。 ## makeCAD 网页工具适配 能力接口给出的 parameters 是版本化工具 Schema 的来源。现有 `window.solidcraft` 提供 `commands()`、`execute(command,params)`、`inspect(params)` 和 `request(method,params)`。这些是底层控制入口,**不能直接把模型指定的方法名传给 request**,必须经过固定工具适配器和原生 gate。 | 工具 | 输入概要 | 网页实现及结果要求 | | --- | --- | --- | | `list_commands` | `filter?,prefix?,panel?,compact?,fields?,limit?,offset?` | 按原生规则筛选命令目录,支持精简字段和分页,避免超大查询结果 | | `describe_command` | `id` | `execute('engine.describe',{command:id})`;id 是引擎命令编码,不是数据库 ID | | `inspect_design` | `measure?,sketches?,joints?` | 基于 inspect,按原生 MCP 语义补齐所需草图及关节详情;不能只透传这些标记给 inspect 后宣称完整实现 | | `execute` | `command,params?,verbose?,expect?` | 执行前核验命令与参数;支持原生 compact 结果和 expect 测量断言,断言失败不自动回滚设计 | | `batch` | `commands,rollback?,coalesce_parameters?,timings?,profile?,verbose?,expect?` | 使用原生 batch 映射和 checkpoint/回滚逻辑,最多 10000 步,与原生 MCP 上限一致;请求正文和工具结果仍受字节配额限制;支持可映射的 set_parameter、measure 等步骤;不允许嵌套 batch | | `measure` | `body?,items?,names_only?,summary?` | 复用 `inspect.measure` 及原生筛选/精简逻辑,items 最多两个;返回尺寸、体积、面积、包围盒等 | | `body_topology` | `body,faces?` | 读取 model.edges/model.faces;faces=cylinders 时按原生逻辑合并圆柱面,不能直接返回全部面假冒合并结果 | | `set_parameter` | `name,value或expression,unit?,comment?` | 映射 parameters.change,value/expression 为别名;返回求值和重建错误 | | `check_parameters` | `set,report?` | 按原生 MCP 的试值、检查、精确恢复逻辑实现,包含 undo 历史;返回 restored,恢复失败必须标为错误并停止本轮 | | `screenshot` | `view或camera?,width?,height?,source?,grid?,axes?` | 只捕获 CAD 画布或模型视图;不捕获平台页面/聊天栏,不写磁盘;压缩为 PNG/JPEG content,view/camera 二选一 | | `undo` | `{}` | 只能撤销本轮已经完成的修改,不能越过本轮起点 | | `skill_reference` | `skill,file?` | 从浏览器 WASM 内置资源读取技能,默认 `SKILL.md`;技能和文件必须成对存在于打包目录,拒绝任意文件路径;只读,不放入 batch | 原生工具实现可参考 makeCAD 的 `crates/mcp/src/tools.rs` 和 `crates/ui-egui/src/agent_chat`,但桌面的 CLI/MCP 进程和系统钥匙串不能搬进浏览器。网页 `ChatBackend` 要使用异步 fetch 和事件队列,不阻塞绘制;面板的文本、工具卡和停止操作继续接入现有事件模型。 后端拒绝已知的文件、设置、跨文档命令,并验证工具外层参数;它没有浏览器的实时命令注册表,因此**前端仍须检查 execute/batch 的每一条实际命令及其嵌套参数**。只允许当前文档内的建模、检查、参数和视图操作,禁止文件路径、打开/替换设计、导出保存、跨文档和应用设置;几何 path 与文件路径按原生规则区分,无法确定时拒绝。直接 execute edit.undo 等命令也必须遵守撤销边界。 ### 共享生成流程与技能资源 MCP、桌面助手和网页托管助手共用 CAD 仓库的 `skills/agent-workflow.md` 生成流程:先理解意图和已有设计,读取相关技能,计算参数、位置及阶段预期值,再分批建模、测量、检查参数变化,最后报告实际验证结果。模糊需求的处理依照共享流程;只有会实质改变用途或几何结果的缺失信息才需要澄清,其余使用明确说明的合理假设。 `skills/` 中的 17 个技能全部可通过 `skill_reference` 读取,并在系统指令中提供名称、用途和可用文件目录。技能按任务渐进加载,不把全部正文塞进每次请求:新零件读取 `makecad-modeling`,改现有设计读取 `makecad-editing`,建模和修改配合 `makecad-checking`,装配和运动读取 `makecad-mechanisms`;开发、排障、测试等任务读取相应技能。开发类技能中的终端、文件或发布示例不会扩大浏览器权限。 后端打包资源为 `vibemake-service/src/main/resources/cad/ai/skills.json`,由 CAD 仓库的 `scripts/sync-cad-ai-skills.mjs` 从相同源文件生成,包含共享流程、全部技能文件及修订摘要。更新源技能后重新同步,并用该脚本的 `--check` 模式检查后端资源是否一致,然后同时构建后端和 WASM。后端启动时验证资源结构,输出技能修订摘要和数量日志;资源缺失或非法时启动失败,避免静默退回无技能模式。能力接口仍使用 `cad-agent-v1`,新增只读工具后共 12 个工具;允许的技能名和文件由打包资源生成 Schema,后端还校验二者的对应关系。 在 CAD 仓库根目录执行(两个仓库为相邻目录时): ```sh node scripts/sync-cad-ai-skills.mjs ../community node scripts/sync-cad-ai-skills.mjs --check ../community ``` 产品文案使用 makeCAD,技能名使用 `makecad-*`。`window.solidcraft` 等既有桥接标识保留技术兼容。共享流程和技能一致不等于不同模型必然产生相同结果;模型、采样配置、上下文和引擎版本也需要对齐,并以实际工具结果验收。 ## 工具循环、取消、重试和保存 每个文档同一时刻只运行一个 Agent 轮次。前端执行器需要: 1. 固定当前文档实例、轮次、修订标记和撤销起点,开始累计模型调用数及修改命令数。 2. 发出一步请求并显示文字及待执行卡片,收到完整 completed 后才交付工具。 3. 检查文档与轮次仍然有效,按顺序串行执行;每次自身修改成功后更新预期本地修订。 4. 用 `(documentSessionCode,turnCode,callCode)` 缓存执行结果,重复收到同一调用返回缓存,不再次修改。 5. 将本步 output 和完整结果加入历史,再推进下一步。达到能力限制时停止循环并提示用户继续发起新消息;batch 按实际修改命令数计入 24 条上限。 6. 收到 stop 后结束本轮,合并为一个撤销组,显示可撤销的实际修改数量。 The browser can recover a failed model request within the current task: at most two retries per request and six retries per task, after one and two seconds. The backend never retries internally. `CAD_AI_TIMEOUT`, explicitly transient `CAD_AI_PROVIDER_FAILURE`, and `CAD_AI_INVALID_MODEL_TOOL` errors are recoverable. Stop, account/project changes and manual design edits still cancel recovery. Authentication, denied access, input/protocol incompatibility, stale context, rate/concurrency limits and output limits remain terminal. For a rejected model tool response, SSE `data.retryable` is `true` and `data.correction` contains bounded validator data, for example `{"tool":"batch","rule":"required","path":"$.commands[0].params"}`. The next request may carry this object as `context.modelRecovery`. `tool` matches `[A-Za-z][A-Za-z0-9_]{0,63}`, `rule` matches `[a-z][a-z0-9_]{0,63}`, and `path` is at most 256 characters with only `$`, dot-separated property identifiers, `.*` and numeric array indices. Unknown or unsafe diagnostics fall back to `{"tool":"unknown","rule":"invalid_tool","path":"$"}`. No raw arguments or model text are returned in diagnostics. Recovery adds controlled correction guidance to the provider prompt without changing model settings or dropping history, reasoning, images or successful tool results. Only a fully validated response can execute tools. Rejected calls do not enter committed history, and previously completed calls are never replayed. An uncertain execution outcome must be inspected before continuing. Disable the account-scoped engine preference `agent_model_recovery` to restore immediate failure. 取消、超时、切换文档或新聊天时废弃轮次,并取消网络及所有未执行任务。正在内核运行的单次命令可能无法立即中断,必须等其状态确定后才允许新轮次开始;迟到的模型回复不能进入新文档。保留已完成修改,不自动恢复旧快照。继续保留聊天时,给已交付但未执行的调用补齐 `isError=true` 的“本轮已停止,未执行”结果;实际执行状态不确定的结果明确标记,禁止自动继续。 用户手动建模造成修订变化时停止当前轮次,避免在旧上下文上继续修改。停止后可撤销本轮修改;如果之后已经有手动或新 AI 修改,禁用旧消息的“撤销这些更改”,使用正常撤销历史处理。 AI 修改后只标记为未保存。执行本轮期间暂停云端保存,正常结束或停止后使用既有 `.sc` 上传、确认接口,确认成功才显示云端已保存。保存过程中的版本冲突仍按工作空间规则处理。401 后保留本地设计,登录恢复后核对账号和项目归属再继续。 ## 错误和部署配置 | HTTP / code | 处理 | | --- | --- | | 400 BAD_REQUEST / CAD_AI_INVALID_HISTORY / CAD_AI_INVALID_TOOL | 修复请求、历史对应关系、图片或工具参数 | | 401 UNAUTHORIZED | 保留设计,恢复登录;清理其他账号的请求与会话 | | 404 NOT_FOUND | 项目不存在、非本人或已删除,停止对该项目继续请求 | | 409 CAD_AI_PROTOCOL_MISMATCH | 更新编辑器与工具适配器 | | 413 REQUEST_TOO_LARGE / CAD_AI_INPUT_TOO_LARGE | 压缩截图、精简工具查询或裁剪完整历史轮次 | | 429 CAD_AI_RATE_LIMITED / CAD_AI_BUSY | 按 Retry-After 等待,不自动重放建模 | | 502 CAD_AI_PROVIDER_FAILURE | 模型输出或服务异常,保留设计和已知执行结果 | | 502 CAD_AI_INVALID_MODEL_TOOL | Recoverable model tool validation failure; no tool from this rejected response ran. Preserve prior modifications and send `data.correction` as `context.modelRecovery` on the next model request. | | 502 CAD_AI_OUTPUT_LIMIT | 单次模型输出达到预算,不执行不完整工具调用,保留设计;分阶段生成或提高 CAD_AI_MAX_OUTPUT_TOKENS | | 503 CAD_AI_UNAVAILABLE / REDIS_UNAVAILABLE | 功能未开启、配置不全或依赖不可用 | | 504 CAD_AI_TIMEOUT | Recover the model request within the task's retry budget; preserve completed modifications. | | SSE error 的其他 code | 展示 message,保留设计并停止本轮 | SSE 已建立后的错误以 error 事件返回,HTTP 仍可能是 200。服务端在客户端断开、超时和关停时取消上游并关闭响应体;并发许可在工作线程退出后释放,避免上游未停就接入更多任务。 ```yaml vibemake: cad: ai: enabled: ${CAD_AI_ENABLED:false} provider: ${CAD_AI_PROVIDER:doubao} model: ${CAD_AI_MODEL:} request-timeout: ${CAD_AI_REQUEST_TIMEOUT:300s} max-output-tokens: ${CAD_AI_MAX_OUTPUT_TOKENS:16384} heartbeat-interval: 10s max-concurrent: ${CAD_AI_MAX_CONCURRENT:4} requests-per-minute: ${CAD_AI_REQUESTS_PER_MINUTE:30} max-model-calls-per-turn: ${CAD_AI_MAX_MODEL_CALLS_PER_TURN:12} max-changes-per-turn: ${CAD_AI_MAX_CHANGES_PER_TURN:24} ``` CAD 模型连接使用独立的 `vibemake.cad.ai.providers` 配置,不读取或修改社区助手的 `AiProperties`。本地在 `.env` 中设置 `CAD_AI_PROVIDER=openai|doubao|deepseek` 后重启后端,并刷新 CAD 页面、开始新对话。前端仍使用平台指定的模型,Key 只保留在后端,浏览器不能指定任意服务地址。社区助手继续使用原有 `AI_*` 和 `ARK_*` 配置。 | CAD 配置 | OpenAI | 豆包 | DeepSeek | | --- | --- | --- | --- | | Key | `CAD_AI_OPENAI_API_KEY` | `CAD_AI_DOUBAO_API_KEY` | `CAD_AI_DEEPSEEK_API_KEY` | | 模型 | `CAD_AI_OPENAI_MODEL` | `CAD_AI_DOUBAO_MODEL` | `CAD_AI_DEEPSEEK_MODEL` | | 完整请求地址 | `CAD_AI_OPENAI_ENDPOINT`,以 `/responses` 结尾 | `CAD_AI_DOUBAO_ENDPOINT`,方舟 `/responses` | `CAD_AI_DEEPSEEK_ENDPOINT`,以 `/chat/completions` 结尾 | | 思考程度 | `CAD_AI_OPENAI_REASONING_EFFORT`,默认 `high` | `CAD_AI_DOUBAO_REASONING_EFFORT`,默认 `default` | `CAD_AI_DEEPSEEK_REASONING_EFFORT`,默认 `default` | | 思考开关 | 由所选模型支持的 effort 决定 | `CAD_AI_DOUBAO_THINKING=enabled|disabled` | `CAD_AI_DEEPSEEK_THINKING=enabled|disabled` | `default` 表示不发送思考程度参数,其余值必须由实际模型支持,后端不自动降级或回退服务。OpenAI 发送 `reasoning.effort`,不发送方舟专用的 `thinking`;豆包默认保持原有 `thinking.type=enabled`;DeepSeek 发送 Chat Completions 的 `thinking` 与可选 `reasoning_effort`。可选的 `CAD_AI_OPENAI_USER_AGENT` 仅用于兼容需要特定 HTTP 客户端标识的网关,不影响社区助手。未设置独立豆包 Key 时,配置文件为旧部署保留 `ARK_API_KEY` 环境变量的读取兼容;其他两个服务不使用此回退。建议给三个 CAD profile 均填写独立 Key。旧的 `CAD_AI_MODEL` 仍作为 CAD 专用覆盖项保留;使用 profile 模型时应移除或留空,空值不会再沿用社区 `ARK_MODEL`。 OpenAI 和豆包保持原来的 Responses 工具、系统文本、17 个技能和浏览器循环,`store=false`,并请求 `include=["reasoning.encrypted_content"]`。`reasoning:[{id,encryptedContent}]` 用于无状态续调;DeepSeek 则使用可选 `reasoningContent` 保留同一对话的工具续调状态。两者均不作为可见回复或工具解释;用户 message 和 toolResult 不能注入这些字段。供应商状态不兼容时返回 `CAD_AI_PROVIDER_HISTORY_MISMATCH`,需要开始新对话。 DeepSeek 默认文本模型不支持图片,因此不在其能力目录中提供 `screenshot` 工具;带图片的旧历史或附件返回 `CAD_AI_IMAGE_UNSUPPORTED`,不会静默丢掉图片。OpenAI、豆包的图片能力仍取决于所配置模型和网关。能力接口增加 `provider`、`reasoningEffort`、`thinking` 和 `maxOutputTokens`,便于核对实际后端配置,绝不返回地址或 Key。 单次模型输出预算默认为 16384 token,可通过 CAD_AI_MAX_OUTPUT_TOKENS 配置(1024–65536,所选模型还必须支持该值)。该预算包含思考 token 和可见输出,与 300 秒请求超时独立。输出触顶的 response.incomplete 不作为成功,也不执行其中的不完整工具调用。 频率限制通过 Redis 共享,每次推理请求(含续调)计数;模型并发上限按后端实例计算。12 次推理和 24 条修改是网页执行器每个用户轮次的限制,后端能力接口提供该值,不持久跟踪浏览器的整轮操作。日志仅记录关联编码、模型、耗时、用量及错误,不能增加完整聊天或 Base64 调试输出。 网关仅对该 POST 接口允许 4 MiB 请求体,关闭 SSE 缓冲及缓存,读取超时大于模型请求超时并留出余量(默认建议 330 秒)。后端设置 X-Accel-Buffering:no,并每 10 秒发送心跳;具体网关仍需对应配置。其他接口正文配额不变,不改 OSS 或数据库。 上线顺序:部署后端且 CAD_AI_ENABLED=false → 前端适配 → 测试环境启用并完成真实模型联调 → 验收后生产启用。关闭开关会拒绝新请求;已经开始的请求按原有超时或客户端停止结束。必须使用已开通且支持工具调用和图片理解的模型。 ## 联合验收清单 - 同一平台账号进入空白设计或本人项目,可以连续聊天、建模和修改参数,其他用户和删除项目不可访问。 - 工具卡显示真实结果,截图和选区能够进入模型上下文;工具执行前必须等到成功终态。 - 一条消息对应一个撤销组;停止后无后续排队命令,后续编辑不会被旧消息撤销覆盖。 - 切换文档、断流、请求重试和重复事件不会执行到错误文档或重复建模。 - 手动保存后刷新并重新打开 `.sc` 仍能编辑;聊天不恢复;AI 失败与登录过期不丢失本地修改。 - 浏览器构建及 API 响应中没有模型密钥;真实豆包工具调用、识图和流式输出均验证通过。 自动化模型替身和 HTTP 模拟服务覆盖后端协议及故障场景,不代表上述 makeCAD 网页适配已经完成,也不替代真实模型、撤销和云端保存联调。 后端提供默认跳过的 `ArkCadAiLiveTest`,验证当前配置模型的原生工具调用,以及 screenshot 图片结果回填后的识图。它只发送公开提示和生成的红色矩形图片,不读取真实 CAD。部署前安全注入 `CAD_AI_PROVIDER` 和所选 profile 的 `CAD_AI__API_KEY/MODEL/ENDPOINT/REASONING_EFFORT` 后显式运行(会产生模型调用费用;图片测试仅适用于支持图片的模型): 另有显式开启的原生 MCP 联调:同时设置 `VIBEMAKE_CAD_AI_MCP_LIVE_TEST=true` 和 `VIBEMAKE_CAD_AI_MCP_CLI`(本机原生 CLI 绝对路径),可运行 `configuredModelAndNativeMcpAcceptTheAlignedBatchAndQuerySchemas`,验证真实模型发出的 25 步批量调用及分页查询由原生引擎接受。`publicSheetMetalPromptUsesValidatedToolsAgainstAnIsolatedNativeDesign` 使用公开钣金提示,在新的无界面设计中最多探测 20 次模型调用,仅用于协议排障,不代表最终几何或全部钣金要求验收通过;这些探测不读取或修改用户当前设计。 ```sh VIBEMAKE_CAD_AI_LIVE_TEST=true mvn -pl vibemake-service -am \ -Dtest=ArkCadAiLiveTest -Dsurefire.failIfNoSpecifiedTests=false test ``` 这两项通过后,仍需完成浏览器内实际建模、撤销和云端保存联调。