# CAD 知识库扩展：新对话交接

更新日期：2026-11-12，时区 Asia/Shanghai。本文是项目现场索引，配合[类别补全工作方法](MAINTENANCE.md)阅读。**不是 CAD 模型提示词，不自动启动测试，也不作为运行状态真源。** 先核对文件和实际进程，再继续工作；后续更新应替换本页的当前状态，详细历史留在报告里。

## 1. 用户要什么，以及已经确定的边界

目标：优化 community 中 CAD 网页助手的实际生成质量或速度。通过分类找到少而有效的工具构造规程，不是给所有类别写百科长文，也不为每个类别创建一个 Skill。

用户已确定：

- 知识库属于 community，放在其仓库内；旧独立路径不兼容、不恢复。
- 原版 17 个通用 Skill、原通用指令和工具循环全部保留。按需通过一个只读 `knowledge_lookup` 取得当前部件所需短规程；不另建 Agent 或强制多步前置流程。
- 社区聊天助手不接入本增强，仅 CAD 编辑器助手使用。
- 复杂结构后来明确需要齿轮时也应能命中；“做减速装置但未定方案”继续沿用原助手，不另做方案决策。
- 类型明确但暂无适用规程：说明缺口，原助手继续尝试，结果待验证。
- 生成测试用外部脚本调用正式网页助手，不经 Codex 内部生成，不追加规程到题目，不人工修形后冒充模型结果。
- 当前固定模型为 OpenAI `gpt-6.1-terra` / `high`。历史配置还有豆包、DeepSeek 支持，不在试验途中切换模型或设置。
- 不新增整轮生成截止。现有产品仍有 300 秒单次模型请求超时、262144 字节文本预算；这与测试脚本无整轮超时分别披露。
- 复杂齿面沿用结构/参数/可编辑层次，允许明确近似；不声称制造级共轭齿面、全周期无干涉或承载能力。

首轮扩展范围固定为 **9 类单体 + 4 类静态机构**：外/内直齿、斜齿圆柱、直齿/螺旋锥齿、直/斜齿条、ZA 蜗杆、示意蜗轮；固定轴齿轮副、齿轮齿条、蜗轮蜗杆、行星机构。人字齿、摆线、双曲面、面齿轮、非圆齿轮、谐波等以后再做，不因新对话自行扩大。

## 2. 实际仓库与工作目录

| 位置 | 用途 |
| --- | --- |
| `/Users/lk/Projects/vibemake相关项目/community` | 当前业务仓库、后端与知识库；先读这里的 `AGENTS.md` |
| `/Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts` | 唯一知识源；短规程在 `generation/`，旧长文在 `references/` |
| `/Users/lk/Projects/vibemake相关项目/vibemake` | 实际网页宿主；知识桥接在 `js/cad/app.js` |
| `/Users/lk/Projects/vibemake相关项目/solidcraft-main` | 实际改造版引擎；上下文管理在 `apps/solidcraft-web/src/agent_tools.rs` |
| `/Users/lk/.codex/worktrees/cad-original-baseline/solidcraft-main` | 干净原版基线；不是当前 community 工作目录，不在这里改增强或写中文维护文档 |
| `/Users/lk/Projects/cad-generation-benchmark/experiments/gear-family-expansion-20261111` | 外部网页驱动、冻结二进制、题目、原生设计和试验证据；不是第二套正式产品 |

community 的代码要求：Java 显式类型、不用 `var`；不改 SQL；不打印凭据。其他仓库遵守各自 `AGENTS.md` 和技能，不把本页当成绕过仓库规则的授权。

API Key 与登录凭据不写入本文、不输出 `.env`、不复制到证据。原浏览器持有登录会话，不导入/导出登录 Token。服务启动器 `community/scripts/java-with-env.py` 按字面读取本地配置后执行 Java，不用 shell `source .env` 求值。

## 3. 已建立的结构，不要重新设计

运行链：

```text
用户需求
  → 原网页助手、原 Skill 和工具循环
  → 当前部件需要时调用 knowledge_lookup
  → 同一次调用完成类型、条件、精确构建兼容与正文筛选
  → 返回一份完整短规程，或缺参/歧义/能力缺口
  → 原助手继续构造和检查
```

目录与属性真源：`generation/catalog.json`；准入真源：`generation/policy.json`。源码 `CadAiKnowledge.java` 负责检索与资源/条件校验。属性只处理模型提交的结构化 `facts`，**没有自由文本尺寸抽取**。模型给错对象的尺寸，描述澄清不等于服务能自动纠正。

同轮按文档 ID、版本和 SHA256 去重；新用户轮次在发送副本中使旧正文失效；裁剪后允许重读。保留原始工具配对和供应商推理状态。不能为了交接或扩类别把本页、完整分类树和所有规程一起注入模型。

模式：默认 `off`，本机 `pilot` 可加载实验候选，`enabled` 仅加载 `approved`。当前政策有 **13 experimental、1 retired、0 approved**；不能因文档齐全、参考通过或单次成功自动批准。

旧 203 类目录和六族长文属于离线资料。离线 60 条评测与网页生成路由是不同体系；旧六族 CLI 有独立模型循环，不能拿来代替正式网页助手测试。

## 4. 版本如何对上

“源码路由版本”和“运行试验 cohort”是两套编号，不要混同。

| 层次 | 当前/历史版本 | 已核对的证据 |
| --- | --- | --- |
| 当前目录 | `catalog.json` 0.2.2 | 15 个有明确齿制限定的中文/英文小齿轮别名加入既有类型 |
| 当前源码评测 | routing v8 | 287 条固定案例；保留 v7 的 268 条原样；110 项针对性后端测试通过 |
| 历史主对照 | cohort v2 | 13 对、26 次；25 自然终态、1 测试中断；B 仅 6 次得到正文 |
| 独立补测 | cohort v3 | 7 次 B-only；全有正文、服务均无异常提示；5 类的限定几何检查通过，蜗轮及齿轮齿条失败保留 |
| 独立补测 | cohort v4 | 2 次 B-only；取文重放 32/32；齿轮齿条通过，蜗轮 10/14 未通过，原失败保留 |
| 当前运行 | cohort v5 | 只复测蜗轮，B-only；取文重放 32/32、13 类正文哈希通过；蜗轮 14/14，worker 已停止 |

v5 当前冻结信息：

```text
model: gpt-6.1-terra
provider: openai
reasoning: high
engine build: f3d62ce93f72db42f311a46e
backend JAR SHA256: 66330cc022931791bfb1c64973e422a4358d770c7a40d20c18dca4eb28dc4012
original 17-Skill SHA256: 026284eff26c8b4be1f7864219921a54828338973317c291f7e862b1cc452ef7
established external-spur v2 body SHA256: 70cf10a008e7f4183456579201d1f42fbc04511f4cb573a8afd784e2d730ab2d
```

当前蜗轮正文是 `worm-wheel-toroidal-throat` 0.1.2，文件 `candidates/worm-wheel-toroidal-throat-illustration-v1-2.md`，SHA256 为 `1fcabff0be24057233055578f72401d3ca3237ff0ef97d1c23448995edfba314`。路由仍为 v8、目录仍为 0.2.2；v5 只明确保留已有 1.5m 毛坯余量公式并加入试点尺寸核对，没有改变几何方法、条件、引擎或原通用 Skill。

v2、v3、v4、v5 JAR 均另存 `frozen-backend-expansion-vN/`，不要覆盖。新 B-only 与旧 A 不组成新 A/B，也不比较跨版本耗时来宣称提速。

## 5. 当前现场：接手时优先检查

截至 **2026-11-12 本次收尾核对**，v3、v4、v5 的 6 条 worker 全部记录 `stopped`，46 个已排任务均有对应完成记录，没有待执行的生成或采样任务。当前服务继续保留供用户使用，不再追加模型测试。各期终态、原生设计、原图和专项审计均已归档；最新机器快照见 [本轮收尾记录](../reports/gear-expansion-closeout-v5-20261112.json)。**状态可能继续变化，下面不是永久运行保证。**

| 项目 | 当前已观察状态 | 结论边界 |
| --- | --- | --- |
| `B-mechanism-rack-pinion20-12-v4` | 215.3 秒、19 次模型请求、5 次知识请求、2 实体、无服务异常提示；机构/齿轮/齿条正文均送达；静态 20/20，小齿轮最终端面工作齿侧采样 4/4（80 条齿侧、5200 脚点） | 有限端面采样不代表全齿面、动态接触或完整改参传播 |
| `B-single-worm-wheel32-v4` | 356.5 秒、1 实体、无终态服务错误；专项审计 10/14，整体未通过。已定位模型把原毛坯公式 `pitchRadius+1.5*wheelModule` 换成 1.25m 余量，得到34.5而非35，喉部只切到中段 | 原失败完整保留；不由后续成功覆盖，也不由单实体判通过 |
| `B-single-worm-wheel32-v5` | 401.0 秒、21 次模型请求、2 次知识请求、1 实体、无服务异常提示；蜗轮 0.1.2 正文送达；14/14 通过。2028 源曲线点、5000 实际交线脚点、300 喉面点、600 齿侧点；两端各64个标志，全7mm齿宽覆盖 | 限定示意模型和有限采样通过；不是共轭蜗轮、全域证明或制造认证 |

本次收尾只核对并整理文档和证据，没有新增生成请求、重启服务、改模型参数或修补被测几何。目标状态应查询工具获取，不从旧交接文字推断，也不另建重复目标。九类单体均有有限正确样例，四类机构的通过与缺口分别记录，不能将阶段收尾解释为所有机构已经通过。

进程与服务的**本次观察值**：外部 Node 驱动 PID 23355 仍在，6 条补测 worker 已停止；8993 后端 PID 1577；网页 `http://localhost:8091/cad/`。PID 不能作为新对话的固定事实。先用 `ps`、`lsof` 和当期 runtime/指纹核对，避免误停其他 Java 或另起一份服务。

运行队列与脚本均在上述实验目录：

```text
followup-cohort-v{3,4,5}.json
frozen-backend-expansion-v{3,4,5}/{deployment.json,runtime.json,...}
jobs-followup-v3-{parts,complex,worm}/
jobs-followup-v4-{parts,worm}/
jobs-followup-v5-worm/
worker-followup-v*-status.json
worker-followup-v4-{parts,worm}-1.mjs
worker-followup-v5-worm.mjs
run_followup_cohort_v{3,4,5}.py
sample_followup_v{3,4,5}.py
attach_worker.mjs
web_helpers-v3.mjs
```

`-1.mjs` 是修正测试驱动 import 后的实际入口，仍复用 `web_helpers-v3.mjs`；不是新的模型循环。不要把 v4 的编号替换误改成不存在的 `web_helpers-v4.mjs`。`attach_worker.mjs` 复用原 Node 进程的 Playwright context，不复制凭据；**已有 worker 运行时不要重复 attach**。

检查队列只需读取：`.json` 是已排队任务，相应 `.result.json` 是完成记录；`trial-result.json` 表示生成终态，`native-inventory-complete-vN.json` 仅表示采集完成，不是几何验收。`request-*-failed.json` 中的 `ERR_ABORTED` 有时来自工具流正常中断，不能单独当 HTTP 502 或整题失败，结合真实终态判断。

安全读取示例（不启动生成）：

```bash
cd '/Users/lk/Projects/cad-generation-benchmark/experiments/gear-family-expansion-20261111'
python3 - <<'PY'
import json
from pathlib import Path
for state in sorted(Path('.').glob('worker-followup-v*-status.json')):
    print(state.name, json.loads(state.read_text()))
for folder in sorted(Path('.').glob('jobs-followup-v*')):
    pending = [p.name for p in folder.glob('*.json')
               if not p.name.endswith('.result.json')
               and not p.with_name(p.stem + '.result.json').exists()]
    print(folder.name, 'pending jobs:', pending)
PY
```

不要重跑已完成的 `run_followup_cohort_v*.py` 或重新 attach 已停止的队列。v5 冻结过程中只因共享 v8 重放输入已存在而拒绝覆盖；冻结本身完整，已保存 `frozen-backend-expansion-v5/preparation-note.json`，无需重做。后续如用户授权新测试，使用新的独立编号和证据，不覆盖旧目录。若需补只读采样，须绑定实际设计并核对身份；页面关闭后可原样重载，不能人工改几何。

## 6. 已知结果与重要教训

v3 的完整题目、原图和机器记录已经归档在 [FOLLOWUP-V3.md](../reports/gear-family-expansion-20261112/FOLLOWUP-V3.md)：

| 类别 | 已有局部生成证据 | 不要扩大解释 |
| --- | --- | --- |
| 外直齿 | 首轮同版 A/B 和后续 B 补测有正确完整实例 | 不能推断所有齿数/模型都稳定提升 |
| 内直齿圈 | v3 正常完成，11/11 主体/源曲线，另4/4最终齿廓检查通过；160条端面工作齿廓、10400脚点 | 不等于全参数范围与完整编辑传播 |
| 斜齿圆柱 | v2 独立补测正常完成；之后原样重载实际曲线采样补证 | 旧显示中点精度结论曾更正，不能复用旧误读 |
| 直/螺旋锥齿 | v3 分别 15/15，通过明确缩放截面/输运近似检查 | 不等于制造级锥齿共轭面 |
| 直齿条 | v2 同版 A/B 均有有效最终几何 | 单次耗时差不能作为稳定加速比 |
| 斜齿条 | v3 21/21，108 边、7020 实际脚点 | 有限采样不是连续全域证明 |
| ZA 蜗杆 | v3 19/19，实际曲面采样及错误旋向负对照 | 未证明完整参数编辑范围或配对共轭 |
| 示意蜗轮 | v3 开口草图失败；v4 毛坯余量错误、10/14；v5 已14/14通过 | 只证明限定示意几何；不替换历史失败、不证明配对共轭 |
| 固定轴齿轮副 | v2 静态 20/20，但服务异常 | 缺严格完整最终齿廓证据 |
| 齿轮齿条 | v3 17/20 失败；v4 已有静态与最终齿廓通过记录 | 仍需审查检查范围，不作为统计收益 |
| 蜗轮蜗杆机构 | v2 B 静态 19/19、服务正常 | 没有完整最终齿面/动态接触/完整编辑传播证明 |
| 行星机构 | v2 B 45/48，文本预算终止、太阳轮检查失败 | 不因六实体齐全视为成功 |

真正发现的瓶颈：

1. **未送达正文**：参考对象、否定、类型词序、常见小齿轮称谓、内部表示 ID 和缺参会造成反复查询。v7/v8 针对真实失败修复；不是把整段题目硬编码成别名。
2. **送达后执行出错**：v3 蜗轮把根部圆弧端点 `rootRadius*cos/sin(...)` 错写成 `rootX/rootY*cos(...)`，留下约 2.024 mm 缺口；0.1.1 增加明确下一扇区端点和短 JSON。v4 又把1.5m毛坯余量改成1.25m；0.1.2 明确禁止该替换并给试点核对值，v5 限定实例通过。修订针对真实错误，不增加百科背景；原失败均保留。
3. **诊断与上下文**：重复命令目录、命令说明、拓扑/草图大结果占很大预算，不能把所有上下文问题归因知识正文。v3 蜗轮完整检查曾返回 465721 字节，被单次工具结果上限拒绝。
4. **机构接口与检查**：参数存在或相位看似正确不证明完整形状、跨部件编辑传播或动态接触。

## 7. 几何测量不能再混淆

- `model.edges.mid/length` 来自显示折线，不能当精确曲线内点和弧长。可以定位拾取，但检查需用实际曲线求值。
- `inspect.curvature_comb` 的 `combs[].teeth[][0]` 才是实际边/面求值脚点；只采草图只能证明源曲线，不能自动证明最终实体工作面。
- `model.faces` 面积、重心、平面法向属于显示近似，不据此单独声称精确曲面；解析 cylinder 描述可以支持轴线/半径检查。
- `measured_by=smlib` 的体积/重心按对应曲面数值积分解释，bbox 为相应实现的 tight bounds；不能一律叫 mesh，也不能声称符号精确。
- 任意有限采样都不能证明连续全域误差、共轭接触或制造认证。
- 旧“斜齿根部约 0.0585 mm 真实弦段缺陷”结论已经撤回，来自显示字段误读；不要再次写入规程。
- 原审计文件保留，语义更正另写；名称映射或检查器设置错误与模型几何失败分开。

## 8. 下一位助手的工作顺序

1. 先读本页及 `MAINTENANCE.md`，核对 community `AGENTS.md`、实际目录、Git 改动与运行队列。已有改动很多，不 reset、不清空、不批量恢复。
2. 阅读 [当前覆盖清单](../reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)。本轮文档、参考构造、网页生成尝试、后续专项审计和报告已收尾，无待执行队列；不要重复旧题。
3. 需要追溯时按期阅读 `FOLLOWUP-V3.md`、`FOLLOWUP-V4.md`、`FOLLOWUP-V5.md` 和对应 observations，不用最新成功抹去旧失败。
4. 如用户授权下一阶段，优先选择明确缺口：完整参数修改传播、重复同版 A/B、固定轴/蜗轮蜗杆机构最终齿面及行星失败；不是默认继续扩人字齿等本轮范围外类型。
5. 使用同样的最终几何检查，保留失败与负对照。若审计器仅接受参考体名，显式映射实际 body，不改位置/容差来凑通过。
6. 保持 `experimental/pilot`；单次样例通过不能升 `approved`，也不能宣称总体成功率或稳定速度提升。
7. 后续继续按 `MAINTENANCE.md` 维护同一套流程。没有新的生成授权时只报告状态，不自行再排模型任务或重启服务。

完整参数修改传播与多次重复 A/B 仍未充分完成。若本轮停在这里，应明确交付层次和待办，不把它们暗中改成已通过。

## 9. 按需读取的证据入口

- [项目接线、构建与配置](../../../docs/cad-part-knowledge.md)
- [长期类别补全规范](MAINTENANCE.md)
- [扩展阶段总报告](../reports/gear-family-expansion-20261112/README.md)
- [当前13类覆盖、证据与缺口](../reports/gear-family-expansion-20261112/CURRENT-COVERAGE.md)
- [v2 主 A/B 题目与并排截图](../reports/gear-family-expansion-20261112/FORMAL-AB-V2.md)
- [v3 B-only 七题与截图](../reports/gear-family-expansion-20261112/FOLLOWUP-V3.md)
- [v4 B-only 两题、截图及审计](../reports/gear-family-expansion-20261112/FOLLOWUP-V4.md)
- [v5 B-only 蜗轮、截图及审计](../reports/gear-family-expansion-20261112/FOLLOWUP-V5.md)
- [本轮收尾记录](../reports/gear-expansion-closeout-v5-20261112.json)
- [v7 源码与打包检查](../reports/gear-routing-v7-source-20261112.json)
- [v7 正式取文验证](../reports/gear-routing-v7-live-20261112.json)
- [v8 源码与打包检查](../reports/gear-routing-v8-source-20261112.json)
- [v8 正式取文验证](../reports/gear-routing-v8-live-20261112.json)
- [蜗轮0.1.2源码与打包检查](../reports/gear-wheel-allowance-source-20261112.json)
- [v5正式取文验证](../reports/gear-wheel-allowance-live-20261112.json)

实验目录中，`cases-v2.json` 是现有逐字题目；`followup-cohort-vN.json` 是各期冻结绑定。`audit_*` 和 `sample_*` 脚本很多，只打开对应对象所需文件，不跑一遍全部历史脚本。

## 10. 用户在新对话中可以粘贴

```text
继续 community CAD 零件知识库的工作。
先读取：
/Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts/generation/HANDOFF.md
/Users/lk/Projects/vibemake相关项目/community/knowledge/cad-parts/generation/MAINTENANCE.md

先核对实际进程、队列和现有产物，复述当前进度与下一步；不要重复提交已经执行的模型测试，不要在在途试验中打包或重启。保留原版通用 Skill 和工具循环，只维护少而有效的按需构造规程；具体授权与范围以本条消息和我后续要求为准。
```
