25 KiB
CAD Web AI Agent 前端对接
本文描述已实现的后端接口和 makeCAD 网页端需要完成的适配。后端不运行 CAD 引擎,不执行工具,也不持久保存聊天。仅嵌入当前 makeCAD 网页构建不会自动启用 Agent:原有模型客户端、CLI Agent 和聊天入口受桌面编译条件限制,需要前端新增网页 ChatBackend、工具适配器及文档生命周期管理。
调用链:makeCAD 面板 → /api/cad/ai/chat → 豆包 → 浏览器执行工具 → 携带结果再次请求。一次 HTTP 请求只推进一次模型推理。设计文件的保存与续编仍使用 CAD 工作空间接口。
登录、启用和能力
全部接口复用平台 Authorization: Bearer <token>,不向网页下发方舟密钥或 Endpoint。推荐同源部署;iframe 使用受控宿主桥接时校验精确 origin、source 和请求关联编码,Token 不进入 URL。关闭、换账号或退出登录时取消旧请求并清理账号相关会话。
| 方法 | 路径 | 返回 |
|---|---|---|
| GET | /api/cad/ai/capabilities |
普通统一 JSON 包装,data 为能力 |
| POST | /api/cad/ai/chat |
text/event-stream,每个 data 使用统一包装 |
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; // 262144,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 当作回退。
平台助手输入区只保留一个别针附件入口,点击直接选择附件;在输入框中粘贴文字、图片或混合内容即可添加,不需要打开菜单或主动授权读取剪贴板。附件仍在读取时暂不发送,避免文字先发而图片遗漏。权限选择和“加入队列”按钮不展示;允许的当前文档操作默认执行,旧的本地权限配置不再触发确认。项目绑定、停止操作、账号鉴权及浏览器能力限制仍独立生效。
请求和历史类型
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 及注释:
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 后可以结束读取本步。
两步请求示例
第一步请求:
{
"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 为:
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:
{
"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 仓库根目录执行(两个仓库为相邻目录时):
node scripts/sync-cad-ai-skills.mjs ../community
node scripts/sync-cad-ai-skills.mjs --check ../community
产品文案使用 makeCAD,技能名使用 makecad-*。window.solidcraft 等既有桥接标识保留技术兼容。共享流程和技能一致不等于不同模型必然产生相同结果;模型、采样配置、上下文和引擎版本也需要对齐,并以实际工具结果验收。
工具循环、取消、重试和保存
每个文档同一时刻只运行一个 Agent 轮次。前端执行器需要:
- 固定当前文档实例、轮次、修订标记和撤销起点,开始累计模型调用数及修改命令数。
- 发出一步请求并显示文字及待执行卡片,收到完整 completed 后才交付工具。
- 检查文档与轮次仍然有效,按顺序串行执行;每次自身修改成功后更新预期本地修订。
- 用
(documentSessionCode,turnCode,callCode)缓存执行结果,重复收到同一调用返回缓存,不再次修改。 - 将本步 output 和完整结果加入历史,再推进下一步。达到能力限制时停止循环并提示用户继续发起新消息;batch 按实际修改命令数计入 24 条上限。
- 收到 stop 后结束本轮,合并为一个撤销组,显示可撤销的实际修改数量。
请求失败不自动重试。模型未发出 completed 前没有工具可执行,用户可重试该步;工具已经执行后,重试必须携带对应结果,不能重新发送执行前历史。执行状态不确定时先检查设计,不能假设失败并重放。工具结果已知失败可回传给模型,未知是否应用则停止本轮让用户处理。
取消、超时、切换文档或新聊天时废弃轮次,并取消网络及所有未执行任务。正在内核运行的单次命令可能无法立即中断,必须等其状态确定后才允许新轮次开始;迟到的模型回复不能进入新文档。保留已完成修改,不自动恢复旧快照。继续保留聊天时,给已交付但未执行的调用补齐 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 | 模型返回的工具名称或参数未通过协议校验;本次响应的工具均未执行,之前的修改保留。后端日志记录工具白名单名称、Schema 路径、规则及数量,不记录参数值 |
| 502 CAD_AI_OUTPUT_LIMIT | 单次模型输出达到预算,不执行不完整工具调用,保留设计;分阶段生成或提高 CAD_AI_MAX_OUTPUT_TOKENS |
| 503 CAD_AI_UNAVAILABLE / REDIS_UNAVAILABLE | 功能未开启、配置不全或依赖不可用 |
| 504 CAD_AI_TIMEOUT | 停止本轮,保留已完成修改 |
| SSE error 的其他 code | 展示 message,保留设计并停止本轮 |
SSE 已建立后的错误以 error 事件返回,HTTP 仍可能是 200。服务端在客户端断开、超时和关停时取消上游并关闭响应体;并发许可在工作线程退出后释放,避免上游未停就接入更多任务。
vibemake:
cad:
ai:
enabled: ${CAD_AI_ENABLED:false}
model: ${CAD_AI_MODEL:doubao-seed-2-1-lite-260915}
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}
连接复用 ARK_API_KEY、ARK_ENDPOINT,不增加 CAD 专用密钥或地址。CAD 开关独立于社区 AI 的 AI_ENABLED;设置 CAD_AI_ENABLED=true 后还必须具备有效共享配置。CAD 默认模型为 doubao-seed-2-1-lite-260915,可通过 CAD_AI_MODEL 覆盖;显式设为空字符串时沿用共享 ARK_MODEL。社区 AI 的模型默认值不变。上游采用 Responses API,设置 thinking.type=enabled、store=false,不显式传入 reasoning.effort,由模型服务使用默认思考强度(Lite 接口不支持 thinking.type=auto 或 reasoning.effort=auto;模型默认不等同于自适应自动思考),并请求 include=["reasoning.encrypted_content"],不依赖上游保存历史。助手 message 或 toolCall 可附带可选的 reasoning:[{id,encryptedContent}];网页只在当前对话历史中原样保留这些不透明字段,不展示、不解释,也不作为工具执行。后端续调时在对应可见输出之前还原 reasoning 项;用户 message 和 toolResult 不接受该字段。旧版网页的 JSON 历史已保留可选字段,无需修改聊天 UI。
单次模型输出预算默认为 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。部署前在已安全注入 ARK_API_KEY、可选 ARK_MODEL / ARK_ENDPOINT / CAD_AI_MODEL 的环境中显式运行(会产生模型调用费用):
另有显式开启的原生 MCP 联调:同时设置 VIBEMAKE_CAD_AI_MCP_LIVE_TEST=true 和 VIBEMAKE_CAD_AI_MCP_CLI(本机原生 CLI 绝对路径),可运行 configuredModelAndNativeMcpAcceptTheAlignedBatchAndQuerySchemas,验证真实模型发出的 25 步批量调用及分页查询由原生引擎接受。publicSheetMetalPromptUsesValidatedToolsAgainstAnIsolatedNativeDesign 使用公开钣金提示,在新的无界面设计中最多探测 20 次模型调用,仅用于协议排障,不代表最终几何或全部钣金要求验收通过;这些探测不读取或修改用户当前设计。
VIBEMAKE_CAD_AI_LIVE_TEST=true mvn -pl vibemake-service -am \
-Dtest=ArkCadAiLiveTest -Dsurefire.failIfNoSpecifiedTests=false test
这两项通过后,仍需完成浏览器内实际建模、撤销和云端保存联调。