Files
likang 678058c940
CI / Select checks (push) Has been cancelled
CI / Format and repository checks (push) Has been cancelled
CI / Compile RISC-V (manual) (push) Has been cancelled
Docker / image (push) Has been cancelled
Generated files / Regenerate and commit (push) Has been cancelled
Kernel rig / Select the rig areas (push) Has been cancelled
Lists / Design format changes merge cleanly (push) Has been cancelled
Lists / Lists are sorted one item per line (push) Has been cancelled
Packaging lint / lint (push) Has been cancelled
Pages / build (push) Has been cancelled
CI / Dependency advisories (push) Has been cancelled
CI / Quick compile (push) Has been cancelled
CI / Native Linux Clippy (push) Has been cancelled
CI / Build tests (push) Has been cancelled
CI / Native Linux tests (push) Has been cancelled
CI / GPU path tests (1/4) (push) Has been cancelled
CI / GPU path tests (2/4) (push) Has been cancelled
CI / GPU path tests (3/4) (push) Has been cancelled
CI / GPU path tests (4/4) (push) Has been cancelled
CI / Action matrix (1/16) (push) Has been cancelled
CI / Action matrix (10/16) (push) Has been cancelled
CI / Action matrix (11/16) (push) Has been cancelled
CI / Action matrix (12/16) (push) Has been cancelled
CI / Action matrix (13/16) (push) Has been cancelled
CI / Action matrix (14/16) (push) Has been cancelled
CI / Action matrix (15/16) (push) Has been cancelled
CI / Action matrix (16/16) (push) Has been cancelled
CI / Action matrix (2/16) (push) Has been cancelled
CI / Action matrix (3/16) (push) Has been cancelled
CI / Action matrix (4/16) (push) Has been cancelled
CI / Action matrix (5/16) (push) Has been cancelled
CI / Action matrix (6/16) (push) Has been cancelled
CI / Action matrix (7/16) (push) Has been cancelled
CI / Action matrix (8/16) (push) Has been cancelled
CI / Action matrix (9/16) (push) Has been cancelled
CI / Action matrix determinism (push) Has been cancelled
CI / Property tests (many cases) (push) Has been cancelled
CI / Doc tests (push) Has been cancelled
CI / Reference tests (push) Has been cancelled
CI / Windows D3D12 FXC shaders (push) Has been cancelled
CI / Windows app startup (push) Has been cancelled
CI / ci (push) Has been cancelled
CI / Compile WebAssembly (push) Has been cancelled
CI / Nightly alert (push) Has been cancelled
Kernel rig / Build the CLI (push) Has been cancelled
Kernel rig / Kernel rig (${{ matrix.shard }}) (push) Has been cancelled
Kernel rig / kernel-rig (push) Has been cancelled
Pages / deploy (push) Has been cancelled
优化skill
2026-11-16 11:32:34 +08:00

16 KiB
Raw Permalink Blame History

VibeMake CAD Web 助手

使用方式

  1. 在桌面浏览器登录 VibeMake,打开一个 CAD 云项目。
  2. 点击顶部右侧的助手图标,或使用原版助手快捷键。
  3. 在“首选项 → 助手”添加智能体,选择 OpenAI 兼容或 Anthropic 兼容协议,填写名称、服务地址和模型名称。没有模型列表也可以手动填写模型。
  4. 按服务要求填写 API Key,点击测试连接。测试会调用一次模型,并请求一个不修改工程的工具。测试可能产生模型服务费用。
  5. 使用“每次询问”模式开始对话。读取工程可直接执行;修改工程需先批准。也可在原版权限设置中选择“自动允许模型编辑”或“全部”。
  6. 检查修改结果,需要时撤销;确认后使用正常云保存。助手不会自动把模型修改保存到云端。

服务地址填写 API 基址,例如服务文档定义的 /v1,不要填写单个 /chat/completions 或 /messages 请求地址。界面沿用原版服务预设,也支持自定义地址;预设仅帮助填写,不能视为已经通过浏览器认证。“兼容协议”表示请求形状,不能保证任意服务支持浏览器、图片或全部工具。修改协议或服务预设时,旧密钥不会随之发送到新地址。

“已安装”和“自定义命令”保留原版位置,当前置灰并说明需要助手服务或本地连接程序。独立系统窗口入口同样说明 Web 限制;左右停靠、调整宽度、最小化和新建对话继续使用原版交互。

The composer has an Upload attachment button beside Attach view, Attach selection and Pick context. The existing + menu also offers a file picker and clipboard pictures; clipboard access requires browser permission. Files can also be dropped onto the assistant. Supported images are PNG, JPG/JPEG, GIF, WebP, BMP and TIF/TIFF. Hosted CAD AI converts GIF/WebP/BMP/TIFF to PNG; animated images use the first frame when converted. Supported UTF-8 text files are SVG source, TXT, MD/Markdown, JSON, CSV/TSV, YAML/YML, TOML, XML, LOG, INI and CFG. A message accepts up to eight files, each image up to 40 MiB and each text file up to 256 KiB. Images are resized to a longest edge of at most 2048 pixels; backend limits may reduce them further. Attachments are sent with the next message. PDF, Office documents, CAD files, audio, video and local path references are unavailable as web chat attachments; use File import for CAD files.

数据与凭据

  • 浏览器直接请求该模型服务,不经过 VibeMake 模型代理,也不发送 VibeMake token 或 Cookie。
  • 对话会按需包含当前工程摘要、选择与工具查询结果。视图截图和图片/文本文件由用户主动附加;不默认上传完整 .sc。
  • CAD 文件继续使用文件菜单导入,不能在聊天中绕过工程绑定和导入确认。
  • 对话仅在当前页面会话内存在;刷新后清空。普通智能体配置、默认项、权限和授权记录按账号保存。
  • API Key 默认仅存在当前页面内存,刷新后需重新填写。勾选“在本浏览器记住”才保存到账号独立的 IndexedDB。
  • 取消记住、删除密钥或清除本账号已记住密钥,会删除持久化副本。浏览器存储失败时提示“未记住”,当前页面仍可使用内存中的密钥。
  • 浏览器存储不是系统钥匙串;同源脚本可访问。更换服务地址时必须重新填写密钥,不自动传递旧密钥。
  • 退出或换账号清空内存中的凭据和任务;主动记住的凭据仍属于原账号。多个设备或浏览器不会同步密钥。

权限和取消

设置 规则
每次询问(初始值) 读取直接执行,修改先审批
自动允许模型编辑 普通建模修改直接执行,其他原版需确认操作继续询问
全部 当前 Web 平台允许的工具自动执行

单智能体覆盖和“允许一次 / 始终允许 / 拒绝”沿用原版。所有模式都禁止助手替换当前云项目、访问本机文件、执行终端、退出账号或绕过平台锁定。用户在轮次中修改模型会使旧审批失效,需要基于最新模型继续。

停止会取消网络和尚未执行的工具,已经完成的修改保留并可撤销。正在运行的同步几何计算不能保证立即中断。登录失效、宿主锁定、项目释放和上下文切换同样取消未完成任务。工具失败、拒绝或参数无效时,以失败状态保留工具记录并将错误反馈给模型,供其解释或修正;后续工具仍逐项通过相同审批和工程检查。

连接排错

现象 检查方法
401 / 403 检查模型服务自己的 Key、权限和配额;这不会退出 VibeMake
429 模型服务限流或额度限制,稍后重试并检查服务控制台
网络失败 检查服务地址、HTTPS、网络、服务状态、浏览器本机网络权限与跨域配置;不能只凭浏览器的通用错误断定是 CORS
CORS 拒绝 模型服务必须允许当前网站源、所需请求方法和请求头;前端不能绕过服务端拒绝
跳转失败 带 Key 的请求不自动跟随重定向,请填写最终 API 基址
请求超时 检查服务状态,或调整智能体请求超时;停止可取消请求与响应读取
响应无效 检查所选协议、服务基址及非流式 JSON 兼容性;超出 16 MiB 的响应会被拒绝
仅支持聊天 模型能回答但未通过工具调用探针;不会标记为可操作 CAD,需更换支持工具调用的模型
模型列表失败 可以手动输入模型名称,再测试真实模型请求
密钥未记住 检查浏览器 IndexedDB、隐私模式、配额和网站存储权限;不等于密钥无效
助手要求引擎更新 主站和独立引擎版本不匹配,需发布含助手能力的新引擎

默认允许 HTTPS;本机地址遵循已有严格 loopback 规则。HTTP localhost 能否从线上网站访问仍由浏览器安全策略决定,不能保证所有浏览器可用。

实现位置

  • crates/ui-egui/src/agent_chat/:原版 UI、共享协议、权限、轮次和文档检查。
  • apps/solidcraft-web/src/agent.rs:Fetch、AbortController、模型探针、双协议回合及浏览器附件。
  • apps/solidcraft-web/src/agent_tools.rs:无子进程的 MCP 工具适配;只派发尚未执行的控制请求。
  • apps/solidcraft-web/src/agent_storage.rs:账号配置、内存密钥和可选 IndexedDB。
  • apps/solidcraft-web/src/platform.rs:能力声明、上下文、锁定与生命周期。
  • VibeMake 的 js/cad/app.js:应用栏入口、账号/工程上下文同步与取消。

自动化验证

生产代码没有新增模型代理。vibemake/tests/cad/assistant-model.mjs 仅为自动化测试提供可控的本机模型接口,不能部署成公共服务。

在 VibeMake 仓库启动测试 API,再使用已构建的 SMLib 引擎启动站点:

node tests/cad/mock-server.mjs
PORT=8094 API_TARGET=http://127.0.0.1:8092 node scripts/server.mjs

另一个终端:

VM_CAD_BASE_URL=http://localhost:8094 \
VM_CAD_ARTIFACT_DIR=/absolute/path/to/artifacts \
npm run test:cad:assistant

npm run test:cad:browser 还会执行已有 CAD 集成回归和助手用例。真实 HTTPS 部署、实际模型服务及不同浏览器的兼容范围必须另外实测;本机可控接口通过不能当作商业模型服务已认证。

最新一轮前端还原、最终构建、46 项 CAD 浏览器回归(含 26 项助手专项)及截图,参见 前端还原验收记录。此前的 38 项浏览器回归、完整 CI 的失败及未验收边界保留在 上一轮 Web 助手验收记录。

下一阶段服务接口和原版事件映射,参见 后端接入交接。该文档描述待实现服务,不代表当前已接入后端。

Hosted tool result delivery

Hosted discovery defaults to an index of all matching commands: id, label, tab, panel, enabled, disabled_reason and planned wherever present. Only parameter documentation, icons and shortcuts are omitted. describe_command still provides the complete parameter documentation and schema before execution. Filters and command order are unchanged. Explicit fields or compact always take precedence; compact:false requests full entries for one call. Direct list_commands steps inside batch use the same default, without changing modification steps. Use a standalone catalog call for byte-bounded paging. Native MCP, CLI and direct browser API assistants keep their defaults.

The account-scoped Load command details on demand preference defaults to true. ui.prefs {"agent_compact_catalog": false} restores full entries for subsequent calls. Existing history is unchanged. This reduces catalog bytes, not a guaranteed percentage of an entire task's input tokens; precise schemas remain available when requested.

The hosted assistant honours the backend's positive toolResultTextBytes limit without changing a CAD command or removing requested result fields. When a JSON text result is too large, it first removes only whitespace outside strings. Number tokens, strings, coordinates, object identifiers, errors and sketch contents remain unchanged. This does not enable MCP's compact mode, which also changes sketch inspection defaults.

If a successful list_commands result still exceeds the limit and the advertised tool schema supports offset, the browser returns complete command entries as a byte-bounded page. Every requested field remains in each entry. total, offset and next_offset identify the remaining matches; next_arguments preserves the original query conditions for the next call. The assistant may describe and use a command already found without loading unrelated pages, but must read the remaining pages before claiming exhaustive results or that a command is absent. Result formatting never reruns the tool or modifies the design.

Other tools are not silently summarised. A command entry that cannot fit whole, an unsupported paging schema or another result that remains too large retains the explicit delivery error and the existing prohibition on replaying modifications. Missing or zero limits do not introduce a frontend quota. Normal MCP and CLI output remains unchanged.

Hosted model response recovery

The hosted assistant retries only model generation when a temporary provider failure, network interruption, timeout or invalid model tool response occurs. Each model request gets at most two retries, after one and two seconds; the whole task has a maximum of six retries. The task stays busy during recovery. Stop, account/project changes and manual design edits cancel recovery through the existing turn generation and document checks.

Every retry preserves the complete request, history, reasoning state, pictures and model settings. Tool validation failures add only a bounded context.modelRecovery diagnostic (tool, rule, path), so the model can correct the failed response. No tool from that response has run. The diagnostic is kept across network retries and cleared at the next successful model step. It contains no raw arguments or rejected response text. When it cannot fit the advertised request limits, the original request is retried without deleting any existing information. Recovery never compacts semantic data or restarts the CAD tool loop. Previously completed tool calls and their results remain in history. Failed attempts are not committed to history or the transcript. Text deltas update a separate preview for the current attempt immediately; tool announcements are published only after the complete response passes validation. Each retry clears the previous preview, and completed.output supplies the one confirmed answer. Stop and terminal failure also clear unconfirmed text. The account-scoped agent_stream_preview preference defaults to true; ui.prefs {"agent_stream_preview": false} restores completed-only display. Desktop Event::Text handling is unchanged. The existing working indicator remains visible while the response is being validated.

The backend adds data.retryable to SSE error events without changing error codes. CAD_AI_TIMEOUT, CAD_AI_INVALID_MODEL_TOOL and explicitly transient CAD_AI_PROVIDER_FAILURE errors can recover. Invalid model tool arguments, malformed argument JSON, unknown tools and duplicate/reused call IDs are rejected before execution and regenerated with safe schema feedback. Local output validation errors also enter this path; document/turn/request identity checks remain terminal. Older generic provider failures without the flag remain terminal because they also cover authentication, output limits and refusals. Authentication, denied access, gateway rate/concurrency limits, invalid input history, incompatible protocol, output limits and stale contexts are not retried. Deploy the host frontend, engine and backend changes together. Upstream HTTP 408, 429 and 5xx responses carry an explicit transient flag; gateway CAD_AI_RATE_LIMITED and CAD_AI_BUSY remain terminal. The host preserves the document revision for the same request object; the backend provides explicit failure classification. General transport retries remain in the browser. Only the native Chat Completions HTTP-400 compatibility path can resend once with reasoning_effort=none when the provider names that parameter and no explicit effort is configured. Responses and explicit settings never take this path; the original request deadline still applies.

The account-scoped agent_model_recovery preference defaults to true. Setting it to false restores immediate termination on a failed request; it can be set through ui.prefs {"agent_model_recovery": false}. Turning it off during backoff prevents another attempt. No automatic recovery saves or rolls back the design.

Hosted history budgets

The browser meters text using the gateway contract: message and tool-result text, the complete tool-call envelope without opaque reasoning, and the host context. The estimate includes the host's engine identifier, revision hash and nullable record fields. The backend remains authoritative; its limits are not increased.

Before each model request, only a wire copy of history is compacted. Valid JSON tool-result text loses whitespace outside strings. Exact duplicate Skill requests and unchanged bodies keep one full copy. If the request still exceeds a text or request-byte limit, already delivered command catalogues are replaced first by requery receipts, then older command schemas. The latest tool-call group stays complete. A receipt records the original query and requires a fresh description before relying on omitted parameters; it never implies that geometry ran again.

At the start of each new user turn, the effective history is trimmed to a target of 240 items, or a lower positive backend historyItems limit. Whole oldest user turns are removed, never part of a tool group. The current user turn and the visible transcript are retained even when that turn alone is larger than the target. Only the latest two images remain, subject to a lower backend image limit; earlier images become the native explanatory text. If the per-request history-item limit is reached during a turn, only old successful catalogue/schema call and result pairs may be removed. Screenshots from an earlier user turn may be omitted from the wire to make room for a new screenshot; user reference images remain. Within the retained turns, the original user goal, all user messages, CAD execution and inspection results, and the complete visible transcript are retained. If these conservative steps cannot satisfy a backend limit, the task stops explicitly rather than discarding the original goal or replaying CAD modifications.

Native text bounds and retained extensions

Ordinary single-block prose tool results are bounded at 20,000 UTF-8 bytes with the native truncation marker. Knowledge, Skills, structured JSON and mixed content keep the existing complete-result protection and paging rules. Each completed tool result is saved before the next tool runs. A later cancellation keeps completed pairs and drops unanswered calls, without replaying operations or rolling the design back.

The knowledge_lookup extension, cad-knowledge-v1, catalogue, Markdown bodies and permissions remain unchanged. Knowledge deduplication uses the effective history actually sent to the model. When trimming removes a body, the model can read it again. No summary service, persistence, web search or additional agent framework is introduced. Oversized single turns still stop with an explicit resource-limit error.