Files
community/docs/cad-part-knowledge.md
2026-11-12 20:40:21 +08:00

110 lines
16 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# CAD 助手知识库
知识源与后端代码在 community 一起维护,目录为 [knowledge/cad-parts](../knowledge/cad-parts/README.md)。旧独立路径已删除。保留原版17个通用Skill与原模型工具循环,社区聊天助手不接入此增强。
2026-11-12按用户最新要求,网页助手改为**自主选文档、按ID直接读文件**。本页前半部分说明当前读取契约;后面的版本试验均为历史记录,不作为当前读取门槛。实际发布与验证状态见[交接](../knowledge/cad-parts/generation/HANDOFF.md)。
## 运行方式
1. 模型的`knowledge_lookup`工具说明包含[阅读目录](../knowledge/cad-parts/generation/reading-catalog.json)的短摘要:文档ID、名称与用途,不预加载正文。
2. 原助手根据需求、建模步骤和装配体中的部件,自行选择文档。
3. 后端按目录ID读取存在的Markdown并返回原文。没有关键词、分类冲突、参数、文档状态、部署构建或预登记哈希的拒读门槛。
4. 助手结合正文理解适用边界、参数约束和近似限制;没有适用知识时继续原通用Skill,保留用户的结构要求,不能据此把齿轮降为无齿圆柱。
只提供一个读取工具,不增加分类模型调用、检索服务或强制分步审批。行星机构可按需读取机构、外直齿轮和内齿轮三个文档。读取目录不是CAD能力白名单,运动链接也不是已生成轮齿的证据。
当前阅读目录登记17份正文:15份齿轮与相关机构文档、1份XZ造筋方向提示、1份球轴承结构规程。`ball-bearing`摘要覆盖“轴承/bearing、球轴承/ball bearing、滚珠轴承、深沟球轴承”和机构内的球轴承,正文明确内置标准件仅有包络圆环,完整结构须包含内外圈、滚道、独立滚珠和保持架;轴套、滚子和裸座体由助手结合需求区分。名称供原助手自主选文,不增加后端正则或强制读取。恢复的齿轮正文保留。普通板、轴、螺栓、座体和壳体继续使用原通用Skill。目录与正文由维护者编辑;`generation/catalog.json`分类字典和`generation/policy.json`旧准入记录供离线维护与历史复现,生产读取器不使用它们进行语义判断或筛选。
同一轮有效上下文按文档标识和实际内容去重,正文被裁剪后可重新读取;新用户轮次按原机制处理过期引用。返回的SHA256由实际文件计算,只用于内容身份与去重,不与登记值比较以拒读。
## 工具与接口
模型只需提交:
```json
{"document_id":"planetary-gear-mechanism"}
```
`document_id`对应阅读目录的`id`,例如`involute-spur-gear`、`internal-spur-gear`。不再提交`query`、`type_id`或`facts`申请读取。工具Schema只有一个必需字符串参数,不使用ID枚举阻止未知ID到达读取器。
读取成功返回`status=matched`及`documents`,每项为`{id, version, sha256, text}`;目录没有该ID或文件不可读取时返回`status=not_found`及空文档列表。这里的`id`是目录中保留的原文档标识,`version`是维护元数据,二者不构成读取审批。
网页宿主继续使用正常登录和项目绑定访问`POST /api/cad/ai/knowledge`。请求为`{cadProjectCode, documentSessionCode, arguments}`,可选诊断字段`engineBuild`;`arguments`即上述模型工具参数。读取器不比较前端、后端或引擎版本,前后端可以分别更新。正常网页由动态capabilities取得工具说明与Schema,无需为读取契约重新编译CAD引擎。
`CAD_AI_KNOWLEDGE_MODE=off`保留为A/B开关,关闭时不向模型提供知识工具;`pilot`和`enabled`均展示同一阅读工具。这个开关不对已请求的目录文件设置状态或参数门槛。
## 维护与验证
Maven将阅读目录和Markdown打包到`cad/ai/knowledge/`;不依赖本机Python服务或任意文件路径。新增知识时维护一条目录记录和对应Markdown即可。参数条件、表示精度与检查要求写在正文里,不需要补正则、兼容构建白名单或准入条件。具体规范见[维护方法](../knowledge/cad-parts/generation/MAINTENANCE.md)。
正文质量依靠参考实例、真实助手测试、原生设计、截图与独立几何检查持续改进;文件可读不等于生成结果已验证。旧路由固定用例和源码作为历史保留,不能把它们算作新直读接口已通过的评测。
在JDK21下运行当前后端回归:
```bash
mvn -q -pl vibemake-api -am \
-Dtest=CadAiKnowledgeTest,CadAiKnowledgeUtilityTest,CadAiSampleKnowledgeTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
-Dsurefire.failIfNoSpecifiedTests=false package
```
离线分类资料仍可执行`python3 -m cad_knowledge check`、`evaluate`及`python3 -m unittest discover -s tests -v`。历史Python `generation-context`是旧政策的离线维护/复现接口,不是网页助手的读取器,其状态或哈希筛选不控制生产读取。当前源码测试、实际发布、文件送达和模型生成效果分别记录。
## 历史试验记录
下述记录描述当时的申请式检索、准入条件与运行环境,原样保留。其`experimental`、`approved`、`compatible_builds`、`needs_conditions`等描述均不恢复为当前读取门槛。
## 首轮真实网页结果
固定 OpenAI `gpt-6.1-terra` / `high`、引擎 `fc4e47a8db81e633cafe8e63`、同一后端 JAR 和原通用工具。外部脚本驱动正式网页,不向题目追加规程,不修补模型生成的几何:
- 同题 20 齿完整结构:A 关闭知识,132.8 秒结束,未生成实体;B 按需读取一次正文,155.9 秒完成轮毂、孔、键槽及齿形,独立几何复核通过。
- 20 齿加独立同轴轴:232.2 秒,按部件查询一次,两实体及齿形复核通过。
- 较早后端的 24 齿圆孔、无轮毂、无键槽样例复核通过,作为补充证据,不混入最终同版本 A/B。
每个有效齿轮样例独立采样 2028 点,最大渐开线采样偏差小于 0.002 mm;不等同于全曲线严格误差证明或制造认证。A 的未完成耗时不能与 B 的完成耗时构成速度收益结论。两次接入设置失败保留原始记录,不能只展示补跑成功。完整题目、截图、版本指纹、传输情况和复核限制以[实测报告](../knowledge/cad-parts/reports/gear-integration-20261111/README.md)为准。
首轮继续使用 `experimental` / `pilot`。重复读取、上下文裁剪后重读和新轮次失效已做程序测试;首轮未完成模型多轮类型切换实测,也未验证其他齿制的生成效果。完整设计和后续验收范围见[实施方案](../knowledge/cad-parts/plans/cad-assistant-knowledge-integration-plan-20261111.md)。
首轮 15/15 个真实只读接口诊断通过;但当时斜齿模型实测向 `facts` 提交了 Schema 外字段,被协议拒绝并直接结束,未执行查询和预期的原助手回退。不能把接口 `uncovered` 通过写成该端到端场景通过。该历史失败继续保留。
后续源码已改为由统一属性字典生成可选事实字段,按每份规程的条件决定缺参;原有安全恢复链可将非法工具参数作为可重试诊断交回模型,不增加第二套服务端模型循环,不返回部分可执行 CAD 调用。该契约修正已有后端回归测试记录,见[属性契约记录](../knowledge/cad-parts/reports/gear-query-contract-20261111.json)。另已增加有符号角绝对值范围及内齿、斜齿试点的派生半径边界检查,79 项服务测试通过(含 72 个固定路由样例),见[派生边界源码测试](../knowledge/cad-parts/reports/gear-query-contract-20261112.json)。这些检查仅在相应类型规程声明了完整依赖条件且无缺参或冲突时执行,不将外直齿的齿根关系套到其他齿制。源码测试、打包部署和真实网页恢复验证必须分开:没有新部署和网页复测证据时,不能把这次修正写成已修复线上斜齿生成。
## 齿轮扩展阶段(2026-11-12)
目录版本为 0.2.0,现有 13 份 `experimental` 规程:9 类单体(外直齿、内直齿、斜齿圆柱、直齿锥齿、螺旋锥齿、直齿条、斜齿条、ZA 蜗杆和示意蜗轮)及 4 类静态机构。其他齿传动暂不扩展。所有启用条件、正文哈希和精确构建兼容仍以 `policy.json` 为准。
本轮新构建 `f3d62ce93f72db42f311a46e` 修复了“旧知识引用出现在重新读取的完整正文前面时,错误压掉完整正文”的上下文去重问题;原 17 个通用 Skill 及其正文未变。13 类参考构造已在实际网页编辑器完成回放和对应几何审计;这只证明规程构造可在当前工具下实现。复杂锥齿与蜗轮保留明确的非制造级近似声明,静态机构审计不证明全周期接触或运动。
扩展阶段 v1 通过 100 项定向后端测试(81 项服务、19 项 API)与 140 条固定路由评测。正式调用暴露的查询契约问题随后在统一 v2 部署修正:104 项定向测试(85 项服务、19 项 API)、152 条固定路由评测通过,原 17 Skill 和 13 规程正文未变。v2 外直齿与齿轮副已观察到正文真实交付,内齿复合中文表述仍有实际路由缺口;不能把程序评测通过写成所有真实查询都成功。离线资料本轮 36 项单测通过。
后续 v5/v6 仅修改待发布源码:内外啮合复合名称、禁止替代语句作用域、机构短名及齿条属性说明的回归已通过(v6:222 条固定路由样例、88 项服务测试)。源码记录见 [v6 检查报告](../knowledge/cad-parts/reports/gear-routing-v6-source-20261112.json)。**当前正式 v2 测试仍使用冻结的原 JAR,未部署这些修正**;参考部件与当前部件的区分、部分限定词词序仍有已知缺口。维护时必须分别记录源码检查、实际部署和正式模型产物,不能由其中一个状态推断另外两个。
当前源码收尾复查的 **107 项针对性后端测试**(知识31、协议26、客户端31、API19)全部通过,仅运行 `test` 阶段,未重打包或重启;冻结运行 JAR 与原17个Skill的哈希再次核对未变,见[最终检查](../knowledge/cad-parts/reports/gear-source-final-check-20261112.json)。正式模型主对照的题目、原始产物链接、并排截图及独立补测见[截图与证据索引](../knowledge/cad-parts/reports/gear-family-expansion-20261112/FORMAL-AB-V2.md),补测不替换主对照中的失败。
参考回放、历史失败与补采、v1/v2部署指纹及正式同JAR模型A/B结果见[测试结果与流程评估](../knowledge/cad-parts/reports/gear-family-expansion-20261112/README.md)。本轮13对、26次主尝试已收尾:25次自然终态、1次测试中断;另3次独立补测与只读精度补证分别保存。各worker已暂停,无待执行模型。B组仅6次实际取得正文;上游模型异常、知识送达、静态几何与完整参数传播分别记录,不能由程序测试或参考回放推断总体生成收益。
源码政策的过时证据占位已更新为本轮实际入口,仅修改证据字段;13份候选继续`experimental`,没有升级为`approved`,正文、适用条件和兼容构建不变。运行JAR仍冻结,未部署后续路由源码修复或此次索引更新。证据与更新后检查见[索引收尾](../knowledge/cad-parts/reports/gear-evidence-index-closeout-20261112.json)、[源码检查](../knowledge/cad-parts/reports/gear-family-expansion-20261112/final-source-check.json)及[离线检查](../knowledge/cad-parts/reports/gear-family-expansion-20261112/final-offline-check.json)。
### 后续 v7 源码与独立 v3 运行版本
上述 v2 冻结记录属于历史试验,未被覆盖。后续 v7 修复参考对象、生成否定和局部限定词词序,澄清蜗杆/参考蜗杆的属性归属;不从自由文本抽取尺寸,不自动填值。109 项针对性后端测试和 268 条固定路由通过,既有 222 条样例逐字保留。斜齿圆柱、斜齿条及 ZA 蜗杆的检查说明改为 0.1.1,纠正显示折线字段与实际曲线采样的区别,构造公式和步骤不变,旧正文保留。见 [v7 源码与打包检查](../knowledge/cad-parts/reports/gear-routing-v7-source-20261112.json)。
本机随后单独部署 v3:JAR SHA256 为 `bb49b26788b4707d301abd1a523a2e30c1ebcbb06e7673da3ce1ead08c7b37b4`,引擎、OpenAI `gpt-6.1-terra` / `high`、原 17 个 Skill 和 12 个通用工具不变。登录后通过正式网页宿主重放 59 条查询全部符合预期,并核对 13 类正文的版本和哈希;见 [v7 实接口记录](../knowledge/cad-parts/reports/gear-routing-v7-live-20261112.json)。
新一轮七题为 B-only 独立补测,不能与旧 v2 A 组组成新的同版本 A/B,也不替代其失败。实际生成仍由正式网页助手完成,外部脚本不附加提示、不修补几何。当前所有候选继续 `experimental`,本机继续 `pilot`;源码、取文、实体、具体几何和完整编辑传播的状态分别记录。
### 当前收尾状态:路由v8、运行v5
后续先保存“直齿小齿轮”实测未命中的回归,再补充15个明确齿制的中英文别名;普通“小齿轮”仍不自动定类。110项针对性后端测试、287条固定路由通过,v4登录后的32条实接口重放及13类正文哈希核对通过。见 [v8源码](../knowledge/cad-parts/reports/gear-routing-v8-source-20261112.json)、[v8实接口](../knowledge/cad-parts/reports/gear-routing-v8-live-20261112.json)。蜗轮0.1.1以明确派生点防止根部圆弧抄写错误;0.1.2再明确保留原有1.5m毛坯余量,避免模型误换1.25m。原几何方法、类型条件、引擎与通用Skill未变。
v3七次、v4两次及v5一次补测都独立保留;每次正式网页均实际取得正文,无服务异常提示。v3有5个单体样例通过,蜗轮和机构失败;v4齿轮齿条通过,蜗轮仍因余量公式失败;v5蜗轮通过全宽喉部、体积和实际曲线/曲面采样等14项检查。旧失败不由补测覆盖,后续B不与旧A组成跨版对照。所有题目、原图、原生文件、检查限制见 [当前覆盖清单](../knowledge/cad-parts/reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)。
上述为齿轮v5阶段的历史部署:JAR SHA256 `66330cc022931791bfb1c64973e422a4358d770c7a40d20c18dca4eb28dc4012`,13份`experimental`、0份`approved`。该期worker与队列已收尾,不重发旧题。
2026-11-12用户另行授权五个样板和两种人字齿的新阶段。目录0.3.0,共28类型、53属性,政策20份`experimental`、1份`retired`、0份`approved`。正式v1使用独立冻结JAR `177a1aad09e28fae2308f3cd4d8fd4f4d0cb9967229b95d9906c137b61f9f6b7`、OpenAI `gpt-6.1-terra`/`high`及引擎`f3d62ce93f72db42f311a46e`,14次A/B已结束。五类样板均有通过产物,关键参数的独立副本改参5/5通过;两种人字齿正式生成未通过,原失败、正文未送达和前端中断分开保留。见[正式v1](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/FORMAL-V1.md)与[副本改参](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/EDITS-V1.md)。
后续修正板/壳的否定特征、无槽人字齿的零槽宽误拒,并将用户确认的齿轮副名称合并一并验证发布。最终114项后端测试及501条固定例通过,登录后的真实接口193/193符合预期:183个路由响应、10个非法枚举400拒绝。两份人字齿正文为0.1.1,实际文本哈希一致;只澄清已有参考命令,模型效果仍未验证,没有重发正式题目。由于共享8091已切换到另一任务的新引擎,用户确认本轮在独立8092/8994保留原引擎部署v2,JAR SHA256为`4b7aaa5bd886ccba1ea34b1be1be0789592ebc66ebb1c04f176f0dcab1b7185a`。原Skill、指令、工具循环及预算保持,仍无准入升级。见[路由/正文独立发布](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/ROUTING-V2.md)、[本轮总报告](../knowledge/cad-parts/reports/five-samples-herringbone-20261112/README.md)和[带时间交接](../knowledge/cad-parts/generation/HANDOFF.md)。共享8091/8993由其他任务管理,后续操作须核对实际状态。
后端仅对已声明的适用条件及少量必要派生数值域进行拦截,包括内/外齿半径关系、锥齿缩比、蜗杆齿根和长度、蜗轮喉部定义域。孔槽、全局干涉、复杂齿面接触等仍需按规程检查,`matched` 不代表模型几何已通过验收。