From 6e33bc0e11d0465afe69eafa4a8955f98be86119 Mon Sep 17 00:00:00 2001
From: Jerry <99706807@qq.com>
Date: Mon, 27 Jul 2026 17:52:42 +0800
Subject: [PATCH] docs: add comprehensive Chinese project guide

---
 README.md                          |    3 +
 docs/CADSET_PROJECT_GUIDE.zh-CN.md | 1124 ++++++++++++++++++++++++++++
 2 files changed, 1127 insertions(+)
 create mode 100644 docs/CADSET_PROJECT_GUIDE.zh-CN.md

diff --git a/README.md b/README.md
index 8321235..6197cc9 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,9 @@ CadSet 是一个面向机械零件的 STEP-first 参数化 CAD 系统。它覆
 
 系统的统一设计源是自有的 **DesignIR 2.0**。STEP 是主要交换与验收格式，但上传的源 STEP 只作为教师证据和验收真值，不作为重建时的几何依赖。
 
+完整的安装、使用、架构和蒸馏说明见
+[`docs/CADSET_PROJECT_GUIDE.zh-CN.md`](docs/CADSET_PROJECT_GUIDE.zh-CN.md)。
+
 ## 产品范围
 
 当前主线只包含三类工作流：
diff --git a/docs/CADSET_PROJECT_GUIDE.zh-CN.md b/docs/CADSET_PROJECT_GUIDE.zh-CN.md
new file mode 100644
index 0000000..6bf8c18
--- /dev/null
+++ b/docs/CADSET_PROJECT_GUIDE.zh-CN.md
@@ -0,0 +1,1124 @@
+# CadSet 项目完整指南
+
+> 面向自然语言、图文和 STEP 输入的参数化 CAD 生成、重建、修改与经验蒸馏系统。
+
+## 1. 项目信息
+
+- 项目浏览地址：<https://gitea.robotquan.com/xuyongjie/cadSet/src/branch/codex/remove-cadam/>
+- Git 仓库地址：<https://gitea.robotquan.com/xuyongjie/cadSet.git>
+- 当前开发分支：`codex/remove-cadam`
+- 主要输出格式：DesignIR 2.0 JSON、STEP
+- 建模后端：Build123d、SimpleCADAPI
+
+本文档面向三类读者：
+
+1. 想直接启动前端并生成 CAD 的使用者。
+2. 想批量蒸馏 STEP、进行参数化重建实验的研究人员。
+3. 想扩展 DesignIR、CAD Router、建模后端或验收系统的开发者。
+
+---
+
+## 2. CadSet 解决什么问题
+
+CadSet 的目标不是只生成一个“看起来像”的网格，也不是把上传的 STEP
+直接包装后宣称完成重建。系统希望得到同时满足以下条件的 CAD 模型：
+
+- 几何能够导出为标准 STEP。
+- 模型有明确的参数、基准、约束和特征顺序。
+- 后续可以修改孔径、厚度、孔距、数量等参数。
+- 修改后仍能稳定重建，而不是破坏模型。
+- 上传 STEP 的重建过程不依赖原 STEP 本体。
+- 从大量案例中学到的是通用建模方法，而不是某个零件的尺寸答案。
+
+当前产品主线包含三种工作流：
+
+1. **自然语言生成**：根据文字描述生成可编辑的参数化零件。
+2. **图文生成与修改**：结合参考图片和文字生成或修改零件。
+3. **上传 STEP 重建与修改**：把 STEP 作为教师真值，转换成自有
+   DesignIR，再独立重建和参数化修改。
+
+CadSet 当前优先面向规则机械零件，例如：
+
+- 法兰、端盖、轴和轴套；
+- 板件、支架、加强筋结构；
+- 带孔块、孔阵列、槽和凸台；
+- 基础壳体、连接件；
+- 齿轮、齿条、轴承和部分减速器结构。
+
+复杂自由曲面、多轨扫掠、高阶连续过渡面、缺陷 B-Rep 和大型装配仍属于
+需要继续扩展的能力边界。
+
+---
+
+## 3. 核心设计思想
+
+### 3.1 STEP 是几何真值，不是可编辑设计历史
+
+STEP 通常能够保存精确 B-Rep 几何、拓扑和装配信息，但并不可靠地保存原
+CAD 软件中的草图、特征树、尺寸名称和设计意图。
+
+因此，从 STEP 中无法唯一恢复原作者的真实建模历史。例如同一个法兰既可
+以通过“圆柱拉伸后打孔”得到，也可以通过“截面旋转后阵列切除”得到。
+
+CadSet 不声称恢复唯一的原始历史。它做的是：
+
+1. 从 STEP 提取确定性的几何证据。
+2. 推断一个合理、稳定、可编辑的参数化设计方案。
+3. 使用自有 DesignIR 表达这个方案。
+4. 在没有源 STEP 的环境中重新生成 STEP。
+5. 独立比较源 STEP 与重建 STEP。
+6. 扰动参数，验证模型是否真正可修改。
+
+### 3.2 DesignIR 2.0 是统一设计源
+
+DesignIR 是 CadSet 自有的、后端无关的参数化设计描述。它保存设计逻辑，
+而不是嵌入原始 B-Rep 或完整网格。
+
+一个 DesignIR 通常包含：
+
+| 字段 | 作用 |
+| --- | --- |
+| `coordinate_system` | 零件坐标系和轴方向。 |
+| `datums` | 中心点、主轴、安装面等设计基准。 |
+| `parameters` | 尺寸、角度、数量和比例参数。 |
+| `expressions` | 参数之间的派生关系。 |
+| `sketches` | 草图或轮廓语义。 |
+| `constraints` | 同心、对称、等间距等约束。 |
+| `features` | 拉伸、孔、凸台、阵列等有序特征。 |
+| `patterns` | 极坐标或线性重复关系。 |
+| `attachments` | 特征与主体、基准或安装面的连接关系。 |
+| `construction_stages` | 推荐的构造阶段和重建顺序。 |
+| `edit_interface` | 对外开放的可编辑参数与需保持的接口。 |
+| `validation_contract` | 几何不变量和参数扰动测试。 |
+
+完整 Schema：
+
+[`designir-pipeline/contracts/designir-2.0.schema.json`](../designir-pipeline/contracts/designir-2.0.schema.json)
+
+可运行示例：
+
+[`designir-pipeline/examples/raised_hub_flange.designir.json`](../designir-pipeline/examples/raised_hub_flange.designir.json)
+
+### 3.3 源 STEP 必须与重建环境隔离
+
+CadSet 明确禁止以下“伪重建”方式：
+
+- 在生成器中调用 `import_step(source.step)`。
+- 把原始 B-Rep、STEP 文本或完整三角网格塞进 JSON。
+- 把源 STEP 当作基础特征，再在上面做布尔修改。
+- 保存源模型的面 ID、边 ID 或运行时拓扑引用。
+- 重建时从隐藏路径重新读取教师 STEP。
+
+最直接的防作弊检查是：
+
+> 从重建运行环境中移走源 STEP，仅依靠 DesignIR 和编译器，仍然能够生成
+> 完整模型。
+
+---
+
+## 4. 系统架构
+
+```mermaid
+flowchart LR
+    U["文字 / 图片 / STEP"] --> UI["CAD Agent Studio"]
+    UI --> LLM["多模态或文本模型"]
+    LLM --> IR["DesignIR 2.0"]
+    IR --> R["CAD Router"]
+    R --> B["Build123d"]
+    R --> S["SimpleCADAPI"]
+    B --> STEP["重建 STEP"]
+    S --> STEP
+    STEP --> V["3D Viewer"]
+    STEP --> A["独立验收"]
+    A --> F["验收报告与反馈"]
+```
+
+对于上传 STEP，链路进一步分成教师侧和重建侧：
+
+```mermaid
+flowchart TD
+    T["源 STEP（教师真值）"] --> E["确定性几何证据提取"]
+    E --> RA["Agent A：重建"]
+    X["已晋升通用经验"] --> RA
+    RA --> D["自有 DesignIR"]
+    D --> C["隔离编译器"]
+    C --> R["重建 STEP"]
+    T --> AB["Agent B：独立验收"]
+    D --> AB
+    R --> AB
+    AB --> P["确定性晋升器"]
+    P --> X
+```
+
+关键点是：Agent A 和隔离编译器不能读取源 STEP；Agent B 可以读取源 STEP，
+但不能直接发布经验。
+
+---
+
+## 5. 仓库结构
+
+```text
+CadSet/
+├── cad-agent-studio/     Web 前端、对话、上传、任务和 3D 预览
+├── designir-pipeline/    DesignIR、双 Agent、重建、验收和经验蒸馏
+├── text-to-cad/          CAD Router、Build123d CAD 能力和 Viewer 运行时
+├── SimpleCADAPI/         第二建模后端和可重放操作图
+├── docs/                 项目级详细文档
+├── llm.config.yaml       共享 LLM 配置
+├── README.md             项目概览
+├── .gitignore            本地数据、依赖和生成物排除规则
+└── .gitattributes        文本换行和二进制格式属性
+```
+
+### 5.1 CAD Agent Studio
+
+[`cad-agent-studio/`](../cad-agent-studio/)
+
+这是面向最终使用者的 Next.js 前端：
+
+- 左侧：对话、图片/STEP 上传、模型供应商和模型选择。
+- 右侧：STEP 三维预览、选择、剖切、显示和编辑辅助工具。
+- 服务端：读取模型配置、调用 LLM、生成 DesignIR、调用 CAD Router 和编译器。
+- 任务数据：默认保存在 `cad-agent-studio/data/tasks/<taskId>/`。
+
+### 5.2 DesignIR Pipeline
+
+[`designir-pipeline/`](../designir-pipeline/)
+
+负责：
+
+- DesignIR Schema 和验证；
+- 防作弊检查；
+- Build123d / SimpleCADAPI 编译适配；
+- 教师隔离重建；
+- 几何与参数可编辑性验收；
+- STEP 批量证据提取；
+- 双 Agent 合同；
+- 经验候选验证和发布。
+
+### 5.3 text-to-cad
+
+[`text-to-cad/`](../text-to-cad/)
+
+负责：
+
+- CAD Router；
+- 通用 STEP-first 机械建模；
+- Build123d 运行时；
+- 几何检查和可视化；
+- CAD Viewer 相关能力。
+
+### 5.4 SimpleCADAPI
+
+[`SimpleCADAPI/`](../SimpleCADAPI/)
+
+这是基于 OCP/OpenCascade 的第二建模后端，适合：
+
+- 可重放操作图；
+- 参数表达式；
+- 语义标签和拓扑查询；
+- 齿轮、齿条、轴承等专用机械结构；
+- STEP、STL 和 FreeCAD 工作流。
+
+---
+
+## 6. 环境准备
+
+### 6.1 推荐环境
+
+- macOS 或 Linux；
+- Node.js 22 或更高版本；
+- Python 3.12；
+- Git；
+- 能够运行 OpenCascade / Build123d 的本地环境；
+- 支持 WebGL 的现代浏览器。
+
+### 6.2 克隆项目
+
+```bash
+git clone https://gitea.robotquan.com/xuyongjie/cadSet.git
+cd cadSet
+git switch codex/remove-cadam
+```
+
+如果已经存在本地仓库：
+
+```bash
+git fetch origin
+git switch codex/remove-cadam
+git pull --ff-only origin codex/remove-cadam
+```
+
+### 6.3 Python 环境
+
+前端默认查找：
+
+```text
+text-to-cad/.venv/bin/python
+```
+
+如果仓库中没有可用虚拟环境，可创建：
+
+```bash
+python3.12 -m venv text-to-cad/.venv
+source text-to-cad/.venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r text-to-cad/requirements-dev.txt
+python -m pip install -e SimpleCADAPI
+```
+
+也可以显式指定其他 Python：
+
+```bash
+export CAD_PYTHON=/absolute/path/to/python
+export CAD_EXPERIENCE_PYTHON=/absolute/path/to/python
+```
+
+### 6.4 前端依赖
+
+```bash
+cd cad-agent-studio
+npm install
+```
+
+依赖目录 `node_modules/` 不进入 Git。
+
+---
+
+## 7. LLM 配置
+
+默认配置文件位于仓库根目录：
+
+```text
+llm.config.yaml
+```
+
+前端按以下顺序寻找配置：
+
+1. `CAD_AGENT_STUDIO_CONFIG` 指定的绝对路径；
+2. 仓库根目录 `llm.config.yaml`；
+3. `cad-agent-studio/config/llm.config.yaml`；
+4. `cad-agent-studio/config/llm.config.yaml.example`。
+
+推荐使用环境变量保存密钥：
+
+```yaml
+defaultProvider: deepseek
+defaultModel: deepseek:deepseek-chat
+
+providers:
+  deepseek:
+    type: openai-compatible
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: https://api.deepseek.com
+    models:
+      default: deepseek-chat
+      reasoner: deepseek-reasoner
+
+uploads:
+  maxImageMB: 20
+  maxStepMB: 200
+  maxOtherMB: 50
+  allowed:
+    - image/png
+    - image/jpeg
+    - image/webp
+    - .step
+    - .stp
+
+cad:
+  taskRoot: ./data/tasks
+  viewer:
+    mode: iframe
+    allowedOrigins:
+      - http://127.0.0.1
+      - http://localhost
+```
+
+然后设置密钥：
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+```
+
+配置也支持直接写 `apiKey`，但不要把真实密钥复制到公开文档、日志或公开仓库。
+前端公开配置接口不会返回密钥和环境变量名称。
+
+---
+
+## 8. 启动项目
+
+```bash
+cd cad-agent-studio
+npm run dev -- -H 127.0.0.1 -p 53821
+```
+
+浏览器打开：
+
+<http://127.0.0.1:53821>
+
+生产构建：
+
+```bash
+npm run build
+npm run start -- -H 127.0.0.1 -p 53821
+```
+
+如果前端不在 CadSet 根目录的直接子目录，可以指定引擎根目录：
+
+```bash
+export CAD_ENGINE_ROOT=/absolute/path/to/CadSet
+```
+
+---
+
+## 9. 如何使用
+
+### 9.1 自然语言生成零件
+
+在对话框中尽量提供：
+
+- 零件类型；
+- 关键尺寸和单位；
+- 孔、槽、凸台、圆角等特征；
+- 阵列数量和分布方式；
+- 哪些尺寸需要后续编辑；
+- 是否有必须保持的安装界面。
+
+示例：
+
+```text
+生成一个半径 50 mm、厚度 4 mm 的法兰盘。
+中心孔直径 20 mm，中心孔外有一圈高 1 mm 的凸台。
+在直径 80 mm 的分度圆上均匀分布 8 个 M3 间隙孔。
+外径、厚度、孔径、孔数和分度圆直径都需要可编辑。
+```
+
+系统会：
+
+1. 让模型生成完整 DesignIR。
+2. 运行 CAD Router 选择后端。
+3. 执行 DesignIR Schema 与防作弊验证。
+4. 在隔离目录中生成 STEP。
+5. 生成 Viewer 所需预览数据。
+6. 在任务目录保存 DesignIR、STEP 和任务清单。
+
+### 9.2 根据图片和文字生成
+
+上传零件图片后，应补充图片无法可靠表达的信息：
+
+- 实际尺寸；
+- 对称关系；
+- 被遮挡特征；
+- 孔是否贯穿；
+- 板厚；
+- 圆角、倒角或拔模角；
+- 图片是透视图、正视图还是技术图。
+
+图像能力依赖所选模型。如果使用纯文本模型，例如不支持视觉输入的模型，
+它不能直接理解图片。此时应切换到支持视觉的 OpenAI-compatible 模型，或
+先把图纸尺寸和结构转成文字。
+
+### 9.3 上传 STEP 进行参数化重建
+
+在前端上传 `.step` 或 `.stp` 后，说明希望重建和开放的参数，例如：
+
+```text
+重建这个 STEP。识别主体、孔、槽、凸台和阵列关系。
+优先开放整体长度、板厚、孔径、孔距和孔数量。
+重建结果不能依赖原 STEP，并对这些参数分别做扰动测试。
+```
+
+处理原则：
+
+1. 上传 STEP 只作为教师和验收真值。
+2. 系统先读取确定性几何证据。
+3. 模型根据证据生成 DesignIR。
+4. 重建编译器不能访问教师 STEP。
+5. Agent B 比较教师 STEP 与重建 STEP。
+6. 参数扰动测试验证修改能力。
+
+STEP 没有完整建模历史，因此复杂零件不保证一次得到理想的参数化分解。
+系统应当对无法表达的特征明确输出
+`unsupported_feature_vocabulary`，而不是偷偷复用原几何。
+
+### 9.4 修改已生成模型
+
+选中已有任务后，可以使用自然语言修改：
+
+```text
+把 plate_thickness 从 4 mm 改成 6 mm，其他尺寸不变。
+```
+
+或者：
+
+```text
+孔数改为 10，保持分度圆直径和中心孔不变。
+```
+
+修改应优先作用于任务中记录的 `*.designir.json`。系统会为修改请求创建
+revision，保存 `edit-request.json`，然后重新生成 STEP 和 Viewer 资源。
+
+不要直接修改最终 STEP 作为长期设计源，否则参数语义和编辑接口会丢失。
+
+---
+
+## 10. CAD Router 的工作方式
+
+CAD Router 根据任务特征选择后端：
+
+### Build123d
+
+适合：
+
+- 通用机械零件；
+- 法兰、支架、轴、壳体和连接件；
+- 一般机加工特征；
+- 几何测量和验证；
+- 自定义特征组合。
+
+### SimpleCADAPI
+
+适合：
+
+- 齿轮、齿条、内齿圈；
+- 轴承、摆线结构和部分减速器；
+- 需要可重放操作图的任务；
+- 需要语义标签和拓扑查询的任务。
+
+查看路由决策：
+
+```bash
+text-to-cad/.venv/bin/python \
+  text-to-cad/skills/cad-router/scripts/route.py \
+  "生成一个带 8 个安装孔的法兰" \
+  --explain
+```
+
+强制指定后端：
+
+```bash
+text-to-cad/.venv/bin/python \
+  text-to-cad/skills/cad-router/scripts/route.py \
+  "生成一个参数化齿轮" \
+  --backend simplecadapi \
+  --explain
+```
+
+路由器可以读取已发布经验库：
+
+```text
+designir-pipeline/output/library.json
+```
+
+它不能读取 `designir-pipeline/input/` 或 `designir-pipeline/runs/` 中的私有
+教师数据和蒸馏过程。
+
+---
+
+## 11. DesignIR 命令行
+
+以下命令均在仓库根目录执行。
+
+### 11.1 验证 DesignIR
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py validate \
+  designir-pipeline/examples/raised_hub_flange.designir.json
+```
+
+### 11.2 防作弊检查
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py anti-cheat \
+  designir-pipeline/examples/raised_hub_flange.designir.json
+```
+
+如果同时有后端生成器：
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py anti-cheat \
+  part.designir.json \
+  --generator generator.py
+```
+
+### 11.3 编译 STEP
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py compile \
+  designir-pipeline/examples/raised_hub_flange.designir.json \
+  --output /tmp/raised_hub_flange.step \
+  --backend build123d
+```
+
+### 11.4 隔离重建
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py isolated-rebuild \
+  designir-pipeline/examples/raised_hub_flange.designir.json \
+  --output /tmp/raised_hub_flange.step \
+  --backend simplecadapi
+```
+
+SimpleCADAPI 后端还会在 STEP 旁生成可重放的
+`*.simplecad.model.json`。
+
+### 11.5 独立验收
+
+```bash
+text-to-cad/.venv/bin/python \
+  designir-pipeline/scripts/designir_pipeline.py accept \
+  --teacher /path/to/teacher.step \
+  --designir /path/to/part.designir.json \
+  --rebuilt /path/to/rebuilt.step \
+  --report /path/to/acceptance-report.json
+```
+
+---
+
+## 12. STEP 蒸馏系统
+
+### 12.1 简化后的数据目录
+
+```text
+designir-pipeline/
+├── input/                 原始 STEP/STP
+├── runs/                  全部蒸馏过程
+└── output/
+    └── library.json       最终发布经验库
+```
+
+Git 规则：
+
+| 数据 | 是否提交 |
+| --- | --- |
+| `input/*.step`、`input/*.stp` | 否 |
+| 提取的私有几何证据 | 否 |
+| Agent 草稿和中间 DesignIR | 否 |
+| 重建 STEP | 否 |
+| 验收报告和失败记录 | 否 |
+| `output/library.json` | 是 |
+| Schema、脚本、Agent 合同和测试 | 是 |
+
+`runs/` 中的目录由程序按需创建：
+
+```text
+runs/
+├── evidence/      STEP 提取的私有证据
+├── designir/      Agent A 输出
+├── rebuilt/       隔离重建 STEP
+├── acceptance/    Agent B 验收报告
+├── review/        语义批次和 LLM 草稿
+└── quarantine/    失败和能力缺口
+```
+
+### 12.2 放入蒸馏数据
+
+把所有目标 STEP/STP 直接放入：
+
+```text
+designir-pipeline/input/
+```
+
+无需再创建 `teacher/inbox` 等多层目录。
+
+### 12.3 批量提取证据
+
+```bash
+designir-pipeline/scripts/cad-experience extract-folder
+```
+
+默认读取：
+
+```text
+designir-pipeline/input/
+```
+
+默认写入：
+
+```text
+designir-pipeline/runs/evidence/
+```
+
+提取器会根据内容哈希跳过已处理的重复文件。私有证据可以包含精确尺寸、
+坐标、曲面类型、轴线、包围盒、体积和拓扑统计，但这些内容不能直接发布。
+
+### 12.4 准备语义蒸馏批次
+
+```bash
+designir-pipeline/scripts/cad-experience prepare
+```
+
+输出：
+
+```text
+designir-pipeline/runs/review/semantic-batch.json
+```
+
+这个批次会移除不适合公开的实例信息，并保留：
+
+- 零件家族；
+- 参数角色；
+- 基准角色；
+- 特征角色；
+- 关系角色；
+- 特征数量等级；
+- 推荐构造阶段；
+- 无量纲比例观察；
+- 验证目标；
+- 失败和修复候选。
+
+### 12.5 Agent 进行语义归纳
+
+调用 `cad-experience-builder`，让当前大模型完整阅读
+`semantic-batch.json`，输出：
+
+```text
+designir-pipeline/runs/review/experience-draft.json
+```
+
+大模型应该归纳：
+
+- 通用特征组合；
+- 约束和设计不变量；
+- 参数角色及依赖关系；
+- 家族级 reconstruction grammar；
+- 构造顺序；
+- 验证方法；
+- 可复用的失败修复策略。
+
+它不应该复制：
+
+- 某个零件的绝对尺寸；
+- 源文件路径和哈希；
+- 绝对坐标；
+- 面、边或拓扑 ID；
+- 完整实例参数字典；
+- 教师几何。
+
+### 12.6 确定性验证与发布
+
+```bash
+designir-pipeline/scripts/cad-experience publish \
+  --draft designir-pipeline/runs/review/experience-draft.json
+```
+
+发布器会重新核对私有语料中的支持数量和置信度，拒绝实例泄漏，只把通过
+验证的内容写入：
+
+```text
+designir-pipeline/output/library.json
+```
+
+审计：
+
+```bash
+designir-pipeline/scripts/cad-experience audit \
+  designir-pipeline/output/library.json
+```
+
+查询经验：
+
+```bash
+designir-pipeline/scripts/cad-experience query \
+  designir-pipeline/output/library.json \
+  --family flanged_hub_adapter \
+  --features base_flange,hollow_sleeve,counterbore
+```
+
+直接绕过 LLM 语义归纳进行纯统计 `distill` 会被阻止。原因是简单共现统计
+难以可靠地区分“设计方法”和“某批数据中的偶然尺寸模式”。
+
+---
+
+## 13. 双 Agent 的职责
+
+### Agent A：Reconstruction Agent
+
+输入：
+
+- `runs/evidence/` 中的单案例私有证据；
+- 用户修改目标；
+- 已晋升的通用经验；
+- DesignIR Schema 和支持的操作词汇。
+
+输出：
+
+- `runs/designir/*.designir.json`；
+- 需要隔离编译的重建请求；
+- 不确定项和缺失能力。
+
+禁止：
+
+- 读取源 STEP；
+- 导入 B-Rep；
+- 使用完整网格代替参数化模型；
+- 保存源拓扑引用；
+- 直接发布经验。
+
+### Agent B：Acceptance Agent
+
+输入：
+
+- `input/` 中的教师 STEP；
+- Agent A 生成的 DesignIR；
+- `runs/rebuilt/` 中的重建 STEP；
+- 修改测试合同。
+
+输出：
+
+- `runs/acceptance/` 中的机器可读报告；
+- `pass`、`fail` 或 `quarantine` 建议。
+
+Agent B 检查：
+
+- 实体和拓扑数量；
+- 包围盒；
+- 体积和质心；
+- 对称差体积；
+- 关键解析特征；
+- 参数扰动成功率；
+- 非目标区域保持情况；
+- 自交、零厚度、非流形和不稳定重建。
+
+Agent B 同样不能直接把经验写入正式库。最终发布由确定性程序执行。
+
+### 纯文本模型能否完成蒸馏和验收
+
+可以完成大量工作，但存在边界：
+
+- STEP 几何证据由程序提取后，纯文本模型可以阅读 JSON、归纳特征和生成
+  DesignIR。
+- 数值验收由几何程序完成，不要求模型直接看图。
+- 纯文本模型可以根据验收 JSON 分析失败和提出修复。
+- 对视觉外观、复杂曲面、特征语义歧义和图纸理解，多模态模型通常更强。
+
+因此 DeepSeek 等纯文本模型可以参与批量蒸馏闭环，但不应让模型自己“凭
+感觉”验收。验收真值必须来自确定性几何比较；关键失败案例可再交给多模态
+模型或人工复核。
+
+---
+
+## 14. 经验为什么会随着数据增加而变好
+
+蒸馏数据量增加后，系统可能提升：
+
+- 零件家族识别；
+- 特征分解；
+- 主参数发现；
+- 参数依赖推断；
+- 基准和约束识别；
+- 构造顺序选择；
+- 修改接口设计；
+- 常见失败修复；
+- 验收目标选择。
+
+但数据量不是唯一因素。能力增长受三个条件共同限制：
+
+1. **DesignIR 能否表达**：没有 sweep、loft、shell 或复杂孔词汇时，再多
+   数据也无法独立重建这类结构。
+2. **证据质量是否足够**：提取器必须提供可用于推断的曲面、轴线、关系和
+   截面证据。
+3. **验收是否严格**：如果只比较截图或包围盒，错误经验也可能被晋升。
+
+经验晋升必须同时满足：
+
+```text
+几何接近
+AND 特征语义合理
+AND 参数可编辑
+AND 修改后稳定
+AND 多个独立案例重复支持
+```
+
+当前默认晋升策略至少要求 3 个独立案例状态通过；经验归纳命令默认使用更
+保守的 `min_support=20` 和 `min_confidence=0.8`。两者用途不同：
+
+- `minimum_independent_cases=3` 是完整重建和回放状态的最低发布门槛。
+- `min_support=20` 是从批量语料归纳通用经验时的默认统计支持度。
+
+策略文件：
+
+[`designir-pipeline/config/promotion-policy.json`](../designir-pipeline/config/promotion-policy.json)
+
+---
+
+## 15. 验收指标
+
+不要把所有结果压缩成一个不透明的“相似度分数”。建议分别保存：
+
+### 几何一致性
+
+- 相对体积误差；
+- 包围盒各轴误差；
+- 质心误差；
+- 对称差体积比例；
+- 双向表面距离；
+- 关键截面误差。
+
+### 特征语义
+
+- 特征召回率；
+- 特征准确率；
+- 孔、槽、筋和凸台数量；
+- 轴线、半径、同心和阵列关系；
+- 是否生成多余特征。
+
+### 参数化能力
+
+- 关键尺寸参数覆盖率；
+- 参数扰动成功率；
+- 修改目标准确率；
+- 非目标区域保持率；
+- 约束保持率；
+- 编辑接口稳定性。
+
+### 几何有效性
+
+- 是否为闭合实体；
+- 是否为空；
+- 是否自交；
+- 是否出现零厚度；
+- 是否出现非流形几何；
+- 重复执行是否确定。
+
+当前策略中的主要默认阈值包括：
+
+- 相对体积误差不超过 `1%`；
+- 质心误差不超过 `0.1 mm`；
+- 包围盒各轴误差不超过 `0.1 mm`；
+- 对称差比例不超过 `2%`；
+- 参数扰动成功率要求 `100%`。
+
+这些阈值是当前工程默认值，不是所有零件和制造场景的通用标准。
+
+---
+
+## 16. 任务产物
+
+前端任务默认保存在：
+
+```text
+cad-agent-studio/data/tasks/<taskId>/
+```
+
+典型产物包括：
+
+```text
+<taskId>/
+├── cad-task.json
+├── model.designir.json
+├── model.step
+├── model.simplecad.model.json    可选
+├── acceptance-report.json       STEP 重建时可选
+├── revisions/
+│   └── <revisionId>/
+│       └── edit-request.json
+└── Viewer 预览资源
+```
+
+职责划分：
+
+- `model.designir.json`：可编辑设计源。
+- `model.step`：主要几何交换结果。
+- `cad-task.json`：路由、后端、产物和验证记录。
+- `*.simplecad.model.json`：SimpleCADAPI 的可重放操作图。
+- `acceptance-report.json`：教师与重建件的独立验收结果。
+- `revisions/`：后续修改请求记录。
+
+`cad-agent-studio/data/` 是本地运行数据，不提交 Git。
+
+---
+
+## 17. 测试与质量检查
+
+### 前端测试
+
+```bash
+cd cad-agent-studio
+npm test
+npm run build
+```
+
+### DesignIR、经验库和 Router 测试
+
+在仓库根目录执行：
+
+```bash
+text-to-cad/.venv/bin/python -m unittest \
+  designir-pipeline/tests/test_designir_pipeline.py \
+  designir-pipeline/tests/test_experience_library.py \
+  text-to-cad/tests/python/skills/cad-router/test_route.py
+```
+
+### 经验库审计
+
+```bash
+designir-pipeline/scripts/cad-experience audit \
+  designir-pipeline/output/library.json
+```
+
+### Git 数据边界检查
+
+确认没有 STEP 输入和蒸馏过程被跟踪：
+
+```bash
+git ls-files designir-pipeline/input \
+  designir-pipeline/runs \
+  designir-pipeline/output
+```
+
+正常情况下只应看到：
+
+```text
+designir-pipeline/input/.gitkeep
+designir-pipeline/output/library.json
+```
+
+---
+
+## 18. 常见问题
+
+### 前端提示找不到 Python
+
+确认以下文件存在并可执行：
+
+```text
+text-to-cad/.venv/bin/python
+```
+
+或者设置：
+
+```bash
+export CAD_PYTHON=/absolute/path/to/python
+```
+
+### 前端提示找不到 LLM 配置
+
+确认仓库根目录存在：
+
+```text
+llm.config.yaml
+```
+
+或者：
+
+```bash
+export CAD_AGENT_STUDIO_CONFIG=/absolute/path/to/llm.config.yaml
+```
+
+### 模型可以对话但不能生成 STEP
+
+检查：
+
+1. Python 环境是否包含 Build123d/OCP 或 SimpleCADAPI。
+2. `CAD_ENGINE_ROOT` 是否指向 CadSet 根目录。
+3. DesignIR 是否通过 Schema 验证。
+4. DesignIR 是否使用了当前不支持的 operation。
+5. Router 选择的后端是否在当前 Python 环境可用。
+
+### 上传图片后模型仍说看不到
+
+当前所选模型可能不支持视觉输入。更换支持图片的模型，或把图片中的结构
+和尺寸转换成文字描述。
+
+### STEP 重建几何接近但不好修改
+
+这通常表示参数化分解不合理，例如：
+
+- 所有尺寸都被写成固定常量；
+- 孔和阵列没有独立参数；
+- 基准选择不稳定；
+- 特征顺序导致参数变化后布尔失败；
+- 修改合同没有覆盖关键参数。
+
+应优先改进 DesignIR 和特征分解，而不是放宽几何验收。
+
+### 为什么不直接修改上传的 STEP
+
+直接在源 STEP 上做布尔操作可以快速得到几何结果，但无法建立稳定、通用
+的参数化设计能力，也不能随着蒸馏数据增加而学习更好的重建方法。CadSet
+把源 STEP 限定为教师和验收真值，是为了让系统真正学会独立重建。
+
+### 为什么过程数据不提交 Git
+
+原始 STEP、证据 JSON、重建件和验收报告会快速增长，而且可能包含私有
+实例尺寸。仓库只提交经过净化和验证的经验库结果，以及复现管线所需的代码、
+Schema、合同和测试。
+
+---
+
+## 19. 扩展项目
+
+### 新增 DesignIR 操作
+
+至少需要同步更新：
+
+1. `designir-2.0.schema.json` 的 operation 词汇；
+2. Build123d 编译适配；
+3. SimpleCADAPI 编译适配，或明确标记仅支持某后端；
+4. anti-cheat 检查；
+5. 参数扰动和几何验收；
+6. 示例与测试；
+7. CAD Router 能力表。
+
+### 新增后端
+
+新后端应满足：
+
+- 接收显式 DesignIR 和输出路径；
+- 不隐式扫描整个工作区；
+- 不读取教师 STEP；
+- 输出标准 STEP；
+- 保留可编辑的后端源或操作图；
+- 返回明确的成功/失败状态；
+- 记录后端名称和版本；
+- 接入统一验收合同。
+
+### 扩展蒸馏能力
+
+推荐按失败聚类驱动扩展：
+
+1. 收集 `runs/quarantine/` 中的失败。
+2. 区分证据不足、词汇不足、推断错误和编译错误。
+3. 对高频缺口新增 DesignIR 操作或几何证据。
+4. 加入针对性重建和参数扰动测试。
+5. 在 held-out STEP 上验证。
+6. 通过后再允许经验晋升。
+
+---
+
+## 20. 当前边界与研发建议
+
+CadSet 当前已经形成了完整的工程骨架：
+
+- 独立 Web 前端；
+- 统一 DesignIR；
+- 双建模后端；
+- STEP 隔离重建；
+- 双 Agent 职责边界；
+- 参数扰动验收；
+- 批量经验蒸馏；
+- 防实例泄漏发布器；
+- 运行数据与 Git 结果隔离。
+
+下一阶段最值得投入的方向：
+
+1. 扩展 DesignIR 的扫掠、放样、薄壁、倒角、圆角和复合孔词汇。
+2. 增强 STEP 解析中的特征关系、关键截面和对称性识别。
+3. 建立按零件家族分层的数据集和 held-out 测试集。
+4. 增加表面双向距离和局部非目标区域保持指标。
+5. 将失败案例自动聚类为“证据不足、词汇不足、编译失败、参数失稳”。
+6. 为大规模数据增加任务队列、断点续跑、并发控制和状态看板。
+7. 对高价值复杂案例加入多模态复核，但继续以确定性几何验收为最终依据。
+
+CadSet 的核心原则可以概括为：
+
+> STEP 只做教师，DesignIR 才是设计源；模型必须独立重建，经验必须经过
+> 多案例和修改测试验证后才能进入生产。
+