Files
community/docs/frontend-cad-ai-agent.md
T

25 KiB
Raw Blame History

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 轮次。前端执行器需要:

  1. 固定当前文档实例、轮次、修订标记和撤销起点,开始累计模型调用数及修改命令数。
  2. 发出一步请求并显示文字及待执行卡片,收到完整 completed 后才交付工具。
  3. 检查文档与轮次仍然有效,按顺序串行执行;每次自身修改成功后更新预期本地修订。
  4. 用 (documentSessionCode,turnCode,callCode) 缓存执行结果,重复收到同一调用返回缓存,不再次修改。
  5. 将本步 output 和完整结果加入历史,再推进下一步。达到能力限制时停止循环并提示用户继续发起新消息;batch 按实际修改命令数计入 24 条上限。
  6. 收到 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

这两项通过后,仍需完成浏览器内实际建模、撤销和云端保存联调。