Files
community/docs/cad-ai-native-parity-20261113.md
likang 6b96ca1eb0 修复 CAD AI 响应协议兼容和有限恢复
完善 Responses 与 Chat Completions 的响应校验、错误分类和安全诊断,保留知识库及现有模型配置。补充回归测试、行为对照和部署说明,记录全量构建结果及尚未查清的 SSE 偶发测试失败。
2026-11-13 18:18:40 +08:00

16 KiB
Raw Permalink Blame History

CAD AI 原版行为迁移实施记录(2026-11-13)

范围与固定基线

本轮在当前未提交工作区上局部修改,没有重置既有改动。Java 仍执行单次模型推理,浏览器仍负责 CAD 工具循环。没有引入 Deep Agents、LangGraph、Python/Rust 服务、新数据库、联网搜索、语义摘要或任务持久化。没有修改 SQL、CAD 内核、社区 AI 实现、云端保存流程、鉴权规则或业务接口路由。

仓库 开始时 HEAD 说明
community aeecacef6d24183601dbefb6bc9449e6e888a1f9 原有知识交接及报告目录改动保留
solidcraft-main 2cdf535fd1c6d74a85adf51ddbee9d6303a75f0f 原有助手、知识库、恢复、MCP、Skills 等未提交改动保留
vibemake 27eb30e42805d7b1f14f517ae3be20f9d5f75ed8 本轮仅修改两个既有 CAD 浏览器测试文件,业务 JS 未修改

基准是本地当前源码,包含其当时尚未提交的实现,并非只按 HEAD 推断。初始采集目录为 /private/tmp/cad-ai-native-parity-ayjhp740/,长期副本位于 target/cad-ai-native-parity-20261113/baseline/。其中 baseline.json 包含关键文件及知识库 SHA-256,*-before.diff 保存开始时的工作区差异,implementation-only.diff 单独列出本轮改动。无关已有 tracked diff 已逐块核对,保持不变。

原版文件 基线 SHA-256
crates/ui-egui/src/agent_chat/api_client.rs 2404fcedd706cd31dd384db5f2014ecd6052053038e05487e9c6710df68429e2
crates/ui-egui/src/agent_chat/api_wire.rs 9521a4144fb8f674544100faedc1d6a4a47f9e3da36546b2f9c6dbf47cf65877

这两个原版文件在本轮保持基线内容未变,既有的未提交修改也被保留。

行为对照与代码落点

原版行为 网页原有行为/风险 本轮落地 主要回归
新用户轮次清理旧历史 只有请求预算压缩,完整旧轮次可能持续累计 agent_tools::trim_history_at_turn_start 在加入用户消息后,以 240 或更低后端有效上限删除完整旧轮次;当前轮次保留,界面记录保留 native_history_trimming_preserves_complete_turns_and_current_requirements
保留最近两张图片 已有按截图预算清理旧参考的保守策略 新轮次用原版说明文字替换更早图片;继续服从厂商图片能力与后端更低上限 native_history_images_and_plain_text_bounds_preserve_knowledge_and_json
普通工具文本限制 20,000 字节 仅后端预算和结构化结果交付保护 单块纯文本按 UTF-8 边界截断并附 …(cut);JSON、混合内容、知识和 Skill 继续走已有完整结果保护 同上及既有工具分页测试
顺序调用、完整配对 已有工具白名单、Schema 和 completed 校验 每完成一个工具立即保存已配对历史;后续取消/失败时丢弃未回答调用,保留成功 CAD 修改 历史裁剪测试、模型恢复和浏览器保护回归
空参数视为空对象再校验 Responses 要求 arguments 字符串,空字符串可能被错误拒绝 Java 接受缺失/空白参数及对象形式参数,再执行原有 Schema 校验;损坏 JSON、重复键和非对象仍拒绝 nativeEmptyArgumentsAreValidatedAsObjectsWithoutAcceptingCorruptJson
可选元信息不否定有效输出 缺少加密 reasoning 或部分 usage 字段会整步失败 没有可续接状态则忽略该 reasoning 元数据;缺失 usage 数字补 0,非法值仍拒绝;Chat 可缺省 choice.index,非零或越界仍拒绝 optionalReasoningAndUsageMetadataDoNotDiscardValidResponses
Chat 特定参数兼容重发 未做原版 reasoning_effort 兼容 仅当前 Chat 路径、默认 effort、HTTP 400 明确提及 reasoning_effort 时,重发一次 none;显式配置和 Responses 不变 nativeReasoningCompatibilityRetryNeverChangesExplicitEffortOrResponsesProtocol
错误有可辨原因 多种情况都显示模型响应异常 内部枚举区分 JSON、SSE 类型、断流、连接、拒绝、续接状态、usage、HTTP;截断保持原有 OUTPUT_LIMIT providerFailureMessagesDistinguishHttpRefusalJsonAndStreamWithoutRawDetails
桌面流式文字沿原行为显示 网页已读 delta,但完成校验前没有正文 独立 Event::TextPreview 与 AgentChat.preview;attempt 开始/失败/结束清理预览;正式文本只来自校验成功的 output UI preview 单元测试、真实连接的 browser preview 场景
取消和迟到结果隔离 已有代次、修订和宿主绑定;真实连接取消可能泄漏拒绝 Promise 保留代次与绑定;每次流读取 await 后核对代次;等待并消费 reader.cancel 的拒绝,再释放锁 既有停止/账号/项目/文档修订回归

保留的网页扩展与差异

  • 原有浏览器有限恢复保持:每次模型请求最多重试两次,间隔 1 秒、2 秒;整轮最多六次恢复。重试冻结同一份模型请求,不重跑已经完成的 CAD 操作。Java 不执行通用网络重试。
  • Chat 的 reasoning_effort=none 兼容只在单次请求内生效,不像桌面工作器那样缓存为后续会话状态;每个新请求仍以服务端显式配置为准,总 deadline 不延长。
  • 维持各厂商原配置:OpenAI/豆包使用 Responses,DeepSeek 使用 Chat Completions;没有自动协议或厂商回退。更换到不兼容推理协议仍要求新聊天。
  • 本轮不模仿桌面钥匙串、ACP Agent 或本机 MCP 进程启动。
  • 网页继续严格拒绝不完整终态、非法工具、重复调用编码和损坏参数。原版宽容的非关键字段不等于放行执行所必需的数据。
  • 240 是新轮次历史条目目标,不是 token 保证。当前单轮如果本身超过请求、文本或响应资源限制,仍明确结束;已完成设计不回滚。
  • 账户偏好 agent_stream_preview=false 保留仅显示完整回复的旧行为,控制通道为 ui.prefs。平台助手设置区也有对应标签和说明。桌面现有 Event::Text 未改。

知识库与接口兼容

阅读目录 generation/reading-catalog.json 和其 17 份 Markdown 正文均与基线 SHA-256 完全一致。资源仍通过 vibemake-service/pom.xml 原有 Maven resources 打包,未修改正文或目录规则。

保留 knowledge_lookup(document_id)、cad-knowledge-v1、knowledgeMode、读取接口、权限校验、未知文档 not_found、旧调用兼容、模型自主选文档,以及以实际有效历史为依据的去重。裁剪后正文不在模型上下文时可以重新读取。知识正文不经过本轮普通文本 20,000 字节裁剪。

通用 Skills 同步检查仍为 17 个,revision 为 d563936cf58580fc0da2203d30708c4869a5a5956140221e717a53d5723b6efe。

保留 /api/cad/ai/capabilities、/api/cad/ai/chat、/api/cad/ai/knowledge,版本仍为 cad-agent-v1、cad-knowledge-v1。SSE 事件、包装、请求字段、retryable 和安全 correction 格式不变。text_delta 只作界面预览;completed.output 仍是正式历史与工具执行授权来源。没有新增数据库主键输出、任务接口、检查点或事件回放。

错误日志包含请求编码、文档/轮次编码、厂商、固定阶段/类别、可用的 HTTP 状态及耗时。日志不记录 Authorization、密钥、完整设计、原始推理或未经处理的上游错误正文。解析调用位置和有界异常类型链仍可用于排查。

构建与测试命令

本机 Maven 默认 JDK 与系统 java 可能不同,重编译需显式使用 JDK 21。集成测试的 HTTP mock 需要允许本机监听。全量测试必须在隔离配置下关闭没有配置的外部服务默认开关;测试自身显式启用的 mock 仍按其测试属性运行:

JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
AI_ENABLED=false OSS_ENABLED=false GIT_ENABLED=false CAD_AI_ENABLED=false \
mvn -pl vibemake-api -am test

定向测试和 Java 打包:

JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
AI_ENABLED=false OSS_ENABLED=false GIT_ENABLED=false CAD_AI_ENABLED=false \
mvn -pl vibemake-api -am \
-Dtest=ArkCadAiClientTest,CadAiProtocolTest,CadAiKnowledgeTest,CadAiSampleKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiTest \
-Dsurefire.failIfNoSpecifiedTests=false package

Rust 与网页在各自仓库运行:

cargo test -p solidcraft-web
cargo test -p solidcraft-ui-egui agent_chat
node scripts/sync-cad-ai-skills.mjs --check ../community
VIBEMAKE_CAD_ENGINE_OUT=/private/tmp/cad-native-parity-engine node scripts/build-vibemake-cad.mjs

主站 CAD 测试和独立构建:

npm run test:cad
VIBEMAKE_CAD_ENGINE_DIST=/private/tmp/cad-native-parity-engine \
VIBEMAKE_CAD_PACKAGE_DIR=/private/tmp/cad-native-parity-release/cad \
VIBEMAKE_CAD_PACKAGE_ZIP=/private/tmp/cad-native-parity-release/cad.zip \
npm run build:cad

本轮测试服务使用独立端口 19091/19092,不重启既有共享服务。浏览器测试以 VM_CAD_BASE_URL=http://127.0.0.1:19091 运行现有 test:cad:platform-agent,通过真实 HTTP 流的 gate 在 completed 之前检查中文正文预览;覆盖成功、断流后恢复、停止、关闭预览四种场景。测试 mock 的释放接口只存在于 tests/cad,没有新增业务 API。

已完成的验证记录

检查 当前结果 证据
Java 全量 reactor(common/service/security/api) 635 项,0 失败、0 错误、13 项外部环境用例跳过 /private/tmp/cad-native-parity-java-full-isolated.log
CAD 定向测试及 Java JAR 打包 110 项通过,BUILD SUCCESS /private/tmp/cad-native-parity-java-package.log
Rust UI 助手 312 项通过,含正文预览与桌面原行为回归 /private/tmp/cad-native-parity-rust-ui.log
Rust 浏览器纯逻辑 63 项通过 /private/tmp/cad-native-parity-rust-web.log
主站 CAD Node 测试 75 项通过 /private/tmp/cad-native-parity-site-unit.log
新 WASM 完整 Chromium 回归 59 项检查通过,pageerror 为空;含真实 SSE 的成功、恢复、停止、关闭预览 交付目录 browser-result.json,原始日志 /private/tmp/cad-native-parity-browser.log
独立 WASM 与 CAD ZIP 构建 release 构建成功;9 项引擎资源与 ZIP 的尺寸、SHA 和 manifest 全部一致 交付目录 release-manifest.json、SHA256SUMS.txt
原生 UI 助手生产库 clippy --no-deps --lib -D warnings 通过 /private/tmp/cad-native-parity-clippy-ui.log
本轮 Rust 文件格式 rustfmt --check 通过 /private/tmp/cad-native-parity-rust-format.log
三个仓库差异与保护检查 git diff --check 通过;与初始工作区相比,无关已有 tracked diff 未变 交付目录 implementation-only.diff、baseline/
源码知识目录与正文 18 个文件 SHA 与基线一致(目录 1 + 正文 17) 基线 baseline.json
Java JAR 中的知识目录与正文 18 个打包条目 SHA 与基线一致 BOOT-INF/lib/vibemake-service-0.0.1-SNAPSHOT.jar
通用 Skills 17 个一致 sync 脚本 check,revision 见上

严格 WASM 全依赖 clippy 的 -D warnings 被未改动的 crates/io/src/safe_write.rs:298(drop_non_drop)阻断。仅检查网页包时还发现未改动的 apps/solidcraft-web/src/files.rs:679(useless_conversion)。本轮已修改的流解析文件中的 needless_borrow / while_let_loop 已修正;cargo clippy --no-deps -p solidcraft-web --target wasm32-unknown-unknown -- -D warnings -A clippy::useless_conversion 已通过。此豁免仅用于到达本轮代码,不表示整仓严格 CI 已通过,也没有为清理无关告警扩大业务修改。

初次全量测试未设置隔离环境开关,部分与本轮无关的 Spring 上下文因默认开启而没有外部 OSS/Git/社区 AI 凭据,配置校验失败。没有修改生产默认值或测试代码来规避;用命令行 AI_ENABLED=false OSS_ENABLED=false GIT_ENABLED=false CAD_AI_ENABLED=false 隔离后,全量通过。真实模型 opt-in 测试保持跳过。

真实浏览器回归发现并修复了 Stop 后未消费 reader.cancel() 拒绝 Promise 的问题,新构建在预览场景后立即断言无 pageerror,并完成全套回归。另将旧的“新用户轮次删除全部旧图片”测试预期对齐为保留文字、完整工具配对和预算允许的最近图片;现有图片预留逻辑释放一个位置,未删除整段历史。连续长轮次实际完成 16 次模型调用和 30 次设计修改,已成功操作没有因模型请求恢复而重复执行;这仍不意味着单轮可以无限增长。

独立 CAD ZIP 已生成于 target/cad-ai-native-parity-20261113/cad.zip,SHA-256 为 4919c1e449bb159c7535c7d44ba06a3cc15974a3444834220218c035d1e654f7。页面 buildId 为 mwemkwjv,engineBuildId 为 6eb2b6d46259828ad2ef139f;9 项引擎资源的尺寸、SHA 及 ZIP 内的目录与 manifest 已验证。ZIP 根即 /cad/ 部署内容,不能再套一层 cad 目录。

实时预览截图为交付目录中的 browser-stream-preview.png,是在 completed 释放前通过浏览器捕获,已人工查看。正文位于现有助手面板中;没有独立弹层或额外外框。

已生成 Java JAR:target/cad-ai-native-parity-20261113/vibemake-api-0.0.1-SNAPSHOT.jar,SHA-256 为 7b7382ce409ea18df420bdc67d8b2c758b0d8e7eb865ecc94f392ca1c5698c4d。同目录提供 release-manifest.json、SHA256SUMS.txt、verification.json、browser-result.json、verify-artifacts.py 和本轮源码差异;二进制位于被 Git 忽略的 target/ 下,没有加入版本控制。运行 python3 target/cad-ai-native-parity-20261113/verify-artifacts.py 可离线复核两个发布产物、9 项引擎资源和 18 个知识条目,不需要模型凭据。

发布、验证与回退

  1. 先在独立测试环境发布 Java JAR,再合并部署完整 CAD 包至网站的 /cad/。本轮没有执行生产部署。
  2. 原有模型 endpoint、model、thinking、effort、输出上限、密钥及知识开关保持原配置,凭据只存于服务端。
  3. 核对代理 SSE 缓冲关闭,例如 Nginx proxy_buffering off;连接读取超时覆盖模型 deadline 与心跳周期,不能提前切断仍正常生成的流。
  4. 核对 /cad/build-info.json 中的 engineBuildId 与 engine.json 一致,WASM MIME 为 application/wasm。HTML、manifest 和控制 JS 使用重新验证缓存;_assets/<buildId>/ 可 immutable。
  5. 保留旧 _assets 目录,避免正在打开的编辑器丢失旧构建资源。使用新会话检查中文实时正文、一次工具成功后断流恢复、停止及知识读取;不要只看 HTTP 200。
  6. 后端仍兼容旧请求/事件结构,新前端也可使用旧后端。回退使用上一份已验证 Java JAR 和完整 CAD 包;同步核对缓存和构建号。无需数据库回退。
  7. 回退代码时按本轮文件差异恢复,不要 reset 整个工作区;基线中的未提交修改属于此前工作。

已知限制与真实模型验收

受控 mock 证明协议、流解析、恢复边界和工具执行安全,不能等同于商业模型真实任务成功率。用户已明确选择“先交付代码和模拟回归结果”,本轮不执行真实模型对照。当前隔离测试进程未注入默认豆包模型所需的密钥,未读取 .env 或桌面密钥,未执行付费模型调用。后续真实模型对照必须使用同一厂商、模型、思考参数、输出上限和固定公开小样例;不得用不同模型结果推断迁移效果。

已有 ArkCadAiLiveTest 需显式 VIBEMAKE_CAD_AI_LIVE_TEST=true;CAD/MCP 长任务还需单独开关及隔离 CLI 路径。可以在已配置凭据的测试环境再执行。网络持续失败、服务端不可用、模型拒绝或当前单轮过大仍可能结束,且本轮没有服务端断点续跑和刷新恢复能力。