# CAD 零件知识库：当前交接

更新日期：2026-11-12，Asia/Shanghai。先读本文及[类别补全工作方法](MAINTENANCE.md)，再核对实际文件、进程与队列。本文供维护者使用，不注入生成模型，不自动启动测试。临时PID不是永久配置。

## 1. 当前目标与用户确认

本轮补齐旧六样板中除齿轮外的五类：带孔安装板、台阶轴、简化外六角头螺栓、带筋轴承座裸座体、带盖薄壁壳体。用户另加人字齿，并明确确认**无槽连续人字齿、带中央退刀槽双斜齿两种均覆盖**，分别登记、不得互相替代。

保留原版17个通用Skill、原通用指令及模型/工具循环，仅由现有只读`knowledge_lookup`按需返回完整短规程。不新增分类Skill、第二个Agent、强制规划或前置读文步骤，不把旧六族长文/分类树/维护报告塞进上下文。社区聊天助手不接入增强。

模型试验由外部脚本调用正式网页助手，模型固定OpenAI `gpt-6.1-terra`/`high`；不在题目附规程、不人工修补被评分模型、不重发已执行生成、不覆盖历史失败。产品原300秒单次请求超时、262144字节文本预算保留，外部驱动无新增整轮截止。

## 2. 当前已证实结果

- 目录`catalog.json`为0.3.0，28类型、53属性；政策20份`experimental`、1份`retired`、0份`approved`。默认`off`，本机`pilot`允许候选，`enabled`只加载`approved`，当前不会加载实验正文。
- 七份新短规程均0.1.0，分别有当前引擎的标准参考、参数迁移、实际几何审计、多视图与原生设计；七个标准参考均完成一个关键原生参数的编辑传播检查。参考不计为模型成功，不能泛化为所有参数域。
- 原287条gear-routing-v8逐字保留；新增七类129条回归。112项针对性后端测试通过。明确使用JDK21路径；本机`/usr/libexec/java_home -v 21`不能可靠定位，不要回落JDK23。
- 正式登录取文接口108/108通过：101个路由响应及7个非法枚举的协议400拒绝分层核对。七文档版本、声明SHA与实际内容SHA全匹配。首次驱动误将非法枚举当普通路由返回而停止的记录保留，没有因此发送模型请求。
- 离线资料`check`、60/60固定案例及36项unittest通过；离线结果不替代Java路由或网页模型验证。
- **七对新正式网页A/B仍在本轮进行中。** 2026-11-12 15:56（Asia/Shanghai）核对：A七题已停止，B前五题结束、正在600无槽人字齿，随后700带槽双斜齿。每类各一对，同题、同JAR/引擎/前端/模型/预算；A关闭知识，B按需开放。以实际`trial-result.json`、`inventory-complete-v1.json`及审计为准，不从本页推断完成。
- 前五类A均通过；B除螺栓前端交互中断外均通过，座体及壳体明显更慢，不能宣称稳定效率收益。A无槽人字齿无实体；A带槽双斜齿12/18，原生半齿角与扭转参数错误，失败保留。
- B无槽人字齿的实际知识请求因“无中央退刀槽、中央槽宽0”被误判为冲突，未送达正文。真实红例已保存`reports/five-samples-herringbone-20261112/routing-failure-continuous-v1.json`。源码已准备局部冲突作用域修正、独立`sample-parts-routing-v2.json`26条回归和第3个`CadAiSampleKnowledgeTest`；**尚未测试/打包/部署，不属于本轮冻结v1**。v1的129条和gear-v8的287条原样保留。

本轮逐类成绩、原失败、参考图、证据与限制统一见[七类补全报告](../reports/five-samples-herringbone-20261112/README.md)、[任务单](../reports/five-samples-herringbone-20261112/PLAN.md)、[参考汇总](../reports/five-samples-herringbone-20261112/reference-summary.json)和[源码/取文验证](../reports/five-samples-herringbone-20261112/source-and-live-checks.json)。

## 3. 真实目录与职责

| 路径 | 用途 |
| --- | --- |
| `/Users/lk/Projects/vibemake相关项目/community` | 当前仓库，先读AGENTS.md；不reset已有大量工作区改动 |
| `community/knowledge/cad-parts` | 唯一正式知识源，不恢复旧独立路径或兼容链接 |
| `/Users/lk/Projects/vibemake相关项目/vibemake` | 实际网页宿主，知识桥接在`js/cad/app.js` |
| `/Users/lk/Projects/vibemake相关项目/solidcraft-main` | 当前引擎，不把其他基线目录当部署真源 |
| `/Users/lk/Projects/cad-generation-benchmark/experiments/five-samples-herringbone-20261112` | 本轮外部驱动、冻结包、题目、原生设计、截图与全部尝试 |
| `/Users/lk/Projects/cad-generation-benchmark/experiments/gear-family-expansion-20261111` | 历史齿轮v2/v3/v4/v5；本轮复用其只读网页驱动helpers，不覆盖旧文件 |

类型/属性真源为`generation/catalog.json`，准入真源为`generation/policy.json`；`CadAiKnowledge.java`只校验模型提交的结构化facts，没有自由文本尺寸抽取，也不会纠正错误对象的facts。原通用Skill位于`vibemake-service/src/main/resources/cad/ai/skills.json`，SHA256始终为`026284eff26c8b4be1f7864219921a54828338973317c291f7e862b1cc452ef7`。

Java显式类型不用var；不改SQL；不打印密钥/登录Token。浏览器沿用正常登录会话，不导出Token或复制登录存储。启动器`scripts/java-with-env.py`按字面读取`.env`，不能用shell source求值或回显配置。

## 4. 当前部署与运行现场

2026-11-12 15:10:42（Asia/Shanghai）的部署观察：旧8993 PID1577已正常退出，新PID19412监听8993；启动器从community工作目录启动本轮独立冻结JAR。先核对实际状态，不盲目按PID停进程。

```text
backend JAR: .../five-samples-herringbone-20261112/frozen-backend-samples-v1/vibemake-api-0.0.1-SNAPSHOT.jar
JAR SHA256: 177a1aad09e28fae2308f3cd4d8fd4f4d0cb9967229b95d9906c137b61f9f6b7
engine build: f3d62ce93f72db42f311a46e
provider/model/reasoning: openai / gpt-6.1-terra / high
web: http://localhost:8091/cad/
original browser driver observed PID: 23355
cohort: five-samples-herringbone-v1
```

启动文件是独立冻结包，不是已被打包替换的target路径；进程/监听/冻结哈希绑定见`frozen-backend-samples-v1/runtime.json`。`cohort-v1.json`还固定了完整题目、前端、引擎manifest、原12工具和预算哈希；每次生成前后核对。原17Skill与既有外直齿v2正文不变。

旧齿轮worker和本轮reference worker均已停止、各自队列为空；不要重启它们。当前新试验使用：

```text
cases-v1.json
cohort-v1.json
worker-formal-v1-{a,b}-r1.mjs
jobs-formal-v1-{a,b}/
worker-formal-v1-{a,b}-status.json
run-cohort-v1.py --lane a|b
live-routing-v1-r1-result.json
frozen-backend-samples-v1/{deployment,runtime,driver-freeze}.json
```

已启动的runner每次只提交一次登记题目，终态后采集原生设计/工具网络记录/多视图/实际边，最后写999停止任务。`inventory-complete`只表示采集完成，不是几何通过。读取队列先查对应`.result.json`，不要重复运行或attach已有在途worker。heartbeat只在调度间隔更新，生成中可能不更新，不能单凭旧heartbeat判定停止。

只读核对示例：

```bash
ps -p 19412,23355 -o pid,lstart,command
lsof -nP -iTCP:8993 -sTCP:LISTEN
```

在途期间不打包、部署新源码或重启后端。源码policy后续仅补证据也须说明与冻结运行包的差异；不要悄悄把最终报告版包当成已测二进制。

## 5. 下一步按此顺序继续

1. 先检查本轮两lane状态、已完成终态及采集文件，接续已有任务，不重复发送。`audit-formal-v1.py`只给尚无审计的已采集产物写新审计，不调用模型、不修形。
2. 用同一最终几何检查接受合法不同策略。实际body名按几何角色映射；人字齿允许统一全局相位，不容许错误螺旋手或不同中面相位。若审计器固定参数名，先核对原生参数/表达式/注释，再显式映射语义，保留旧误判，不改容差凑通过。
3. 将正文未送达、送达未遵循、最终几何错误、服务异常、产品预算分别记录。不能仅凭闭合单体或截图过关。需要补只读采样时必须核对保存设计身份；重载另存证据，不冒充原页面同revision。
4. 计划在正式生成完全停止后，对保存产物的独立副本做关键参数编辑传播；使用`prepare-formal-edits-v1.py`及`worker-edit-formal-v1.mjs`，先显式登记实际参数映射。该检查不得修补原被评分模型，也不发送新增模型请求；失败保留。未执行项明确写未验证。
5. 全部终态和采样收尾后更新本轮报告、policy evidence、本文及README入口。不能把单对并发耗时差当稳定提速，不能自动approved。若某类失败，本轮可以完整交付失败与改进方向，不必通过反复重跑制造全绿。
6. 独立副本改参仍在冻结v1上收尾，再验证待发布路由修正。必要打包只能在两正式lane和改参worker停止之后，另存`frozen-backend-samples-v2`；如部署，只重放真实知识接口、核对正文版本/哈希，**不再次提交这些模型题目**。v2取文通过不能改写v1的未送达/几何失败，也不构成新模型成功证据。

JDK21命令（必要源码变化后才执行，先确认没有在途）：

```bash
JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
mvn -q -pl vibemake-api -am \
  -Dtest=CadAiSampleKnowledgeTest,CadAiKnowledgeTest,CadAiProtocolTest,ArkCadAiClientTest,CadAiTest \
  -Dsurefire.failIfNoSpecifiedTests=false test
```

## 6. 本轮已定位且须保留的失败

- XZ草图局部第二坐标在当前引擎对应世界−Z，法向+Y。轴承座原始参考筋落到底板下，3个shell；r2改局部负坐标后通过。不得回退正文。
- 两种人字齿原始参考“先根圆芯再Join完整同根圆扫掠”触发重合圆柱面布尔失败。正确参考为下半完整齿廓new，再中面镜像合并；带槽者在镜像前连接半槽芯。原始失败目录全部保留。
- 齿轮v1/v2参考审计缺采孔/槽芯/纵向边，失败原样保留；补证原样重载design.sc，核对features/params后另存实际脚点，v3通过。反向β负对照应被拒绝。
- 项目创建限流只恢复未创建项目，不能把它当成重发模型的理由。首次接口重放驱动失败、JDK23环境失败日志均保留并分层解释。

测量语义不能混淆：`model.edges.mid/length`是显示折线信息，只作拾取；`inspect.curvature_comb`的`combs[].teeth[][0]`才是实际有限求值脚点。面面积/重心/平面法向也不能一概当精确曲面；解析cylinder可核对轴线半径。`measured_by=smlib`体积/重心按相应数值积分解释，bbox按对应tight bounds解释。有限采样不证明连续全域、共轭、加工或承载认证。

## 7. 历史齿轮阶段不重做

旧阶段9类单体＋4类机构，v2主对照及v3/v4/v5独立补测均已归档，旧worker已停止。蜗轮正文`worm-wheel-toroidal-throat`当前0.1.2，保留1.5m毛坯余量，不能按旧文档回退。

- [13类历史覆盖与缺口](../reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)
- [旧阶段总报告](../reports/gear-family-expansion-20261112/README.md)
- [v2主对照](../reports/gear-family-expansion-20261112/FORMAL-AB-V2.md)
- [v3补测](../reports/gear-family-expansion-20261112/FOLLOWUP-V3.md)、[v4补测](../reports/gear-family-expansion-20261112/FOLLOWUP-V4.md)、[v5蜗轮14/14](../reports/gear-family-expansion-20261112/FOLLOWUP-V5.md)
- [旧阶段收尾快照](../reports/gear-expansion-closeout-v5-20261112.json)

v4蜗轮10/14失败与v5的14/14成功分别保留；后续B-only不与旧A拼新对照，复杂机构仍有最终齿面、传播或服务缺口。原交接全文已保存至本轮报告目录的`handoff-before-this-stage.txt`，只作历史，不作为当前运行真源。
