docs: refresh project architecture and repository rules
This commit is contained in:
Jerry
@@ -1,24 +1,197 @@
|
||||
# CadSet
|
||||
|
||||
CAD Router provides three STEP-centered workflows:
|
||||
CadSet 是一个面向机械零件的 STEP-first 参数化 CAD 系统。它覆盖自然语言与图文生成、上传 STEP 的独立参数化重建、模型修改、几何验收，以及从批量 STEP 案例中蒸馏可复用建模经验。
|
||||
|
||||
- Generate editable CAD from natural-language requests.
|
||||
- Generate or modify editable CAD from text plus reference images.
|
||||
- Reconstruct uploaded STEP files into editable DesignIR 2.0 and modify them.
|
||||
系统的统一设计源是自有的 **DesignIR 2.0**。STEP 是主要交换与验收格式，但上传的源 STEP 只作为教师证据和验收真值，不作为重建时的几何依赖。
|
||||
|
||||
For every request, CAD Router selects either text-to-cad or SimpleCADAPI as
|
||||
the execution backend. The persistent contract is DesignIR 2.0 plus STEP.
|
||||
## 产品范围
|
||||
|
||||
## Project layout
|
||||
当前主线只包含三类工作流：
|
||||
|
||||
- `cad-agent-studio/`: standalone web frontend.
|
||||
- `designir-pipeline/`: role-separated reconstruction, acceptance, and
|
||||
experience-promotion system.
|
||||
- `text-to-cad/`: CAD Router, Build123d generation skill, Viewer, and shared
|
||||
CAD runtime.
|
||||
- `SimpleCADAPI/`: the second CAD execution backend.
|
||||
- `llm.config.yaml`: private, Git-ignored provider configuration shared by the
|
||||
standalone frontend.
|
||||
1. 根据自然语言生成可编辑 CAD。
|
||||
2. 根据文字和参考图片生成或修改可编辑 CAD。
|
||||
3. 将上传的 STEP 重建为 DesignIR，独立生成新的 STEP，并继续参数化修改。
|
||||
|
||||
The uploaded teacher STEP is evidence only. A reconstruction must compile from
|
||||
DesignIR after the teacher file has been removed from the build environment.
|
||||
CAD Router 会在两个执行后端之间选择：
|
||||
|
||||
- **text-to-cad / Build123d**：通用机械零件、特征建模、几何验证和 STEP 输出。
|
||||
- **SimpleCADAPI**：可重放操作图、语义化机械结构和专用机械零件能力。
|
||||
|
||||
## 系统架构
|
||||
|
||||
```text
|
||||
┌────────────────────┐
|
||||
Text / Image / STEP ──> │ CAD Agent Studio │
|
||||
└─────────┬──────────┘
|
||||
│
|
||||
┌─────────▼──────────┐
|
||||
│ CAD Router │
|
||||
└──────┬───────┬─────┘
|
||||
│ │
|
||||
┌───────────▼─┐ ┌─▼──────────────┐
|
||||
│ Build123d │ │ SimpleCADAPI │
|
||||
└───────────┬─┘ └─┬──────────────┘
|
||||
└────┬────┘
|
||||
│
|
||||
DesignIR 2.0 + STEP
|
||||
│
|
||||
┌───────────▼───────────┐
|
||||
│ Viewer / Acceptance │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
上传 STEP 的重建链路使用严格的教师隔离：
|
||||
|
||||
```text
|
||||
Teacher STEP
|
||||
-> private geometry evidence
|
||||
-> Reconstruction Agent
|
||||
-> DesignIR 2.0
|
||||
-> isolated compiler without Teacher STEP access
|
||||
-> rebuilt STEP
|
||||
-> independent Acceptance Agent
|
||||
-> deterministic experience promotion
|
||||
```
|
||||
|
||||
## 仓库结构
|
||||
|
||||
| 路径 | 职责 |
|
||||
| --- | --- |
|
||||
| [`cad-agent-studio/`](cad-agent-studio/README.md) | 独立 Next.js 前端，负责对话、图片与 STEP 上传、任务管理和模型预览。 |
|
||||
| [`designir-pipeline/`](designir-pipeline/README.md) | DesignIR Schema、双 Agent、隔离编译、验收和经验晋升。 |
|
||||
| [`text-to-cad/`](text-to-cad/README.md) | CAD Router、Build123d CAD Skill、CAD Viewer 和共享 CAD 运行时。 |
|
||||
| [`SimpleCADAPI/`](SimpleCADAPI/README.md) | 第二建模后端，提供可重放操作图和机械建模 API。 |
|
||||
| [`llm.config.yaml`](llm.config.yaml) | 前端共享的模型供应商、模型和密钥配置。 |
|
||||
|
||||
依赖目录、虚拟环境、构建缓存和批量运行数据不会进入 Git。锁文件、源码、Schema、Agent 定义和确定性测试会进入版本控制。
|
||||
|
||||
## DesignIR 2.0
|
||||
|
||||
DesignIR 保存设计意图，而不是复制 STEP 的 B-Rep 或三角网格。主要结构包括：
|
||||
|
||||
- coordinate systems 与 datums
|
||||
- editable parameters 与 expressions
|
||||
- sketches 与 constraints
|
||||
- ordered features、patterns 与 attachments
|
||||
- construction stages
|
||||
- edit interface
|
||||
- validation and perturbation contracts
|
||||
|
||||
Schema 位于：
|
||||
|
||||
[`designir-pipeline/contracts/designir-2.0.schema.json`](designir-pipeline/contracts/designir-2.0.schema.json)
|
||||
|
||||
当前两个后端共同支持的首批操作包括：
|
||||
|
||||
- `extrude_circle`
|
||||
- `extrude_rectangle`
|
||||
- `add_cylinder`
|
||||
- `through_hole`
|
||||
- `polar_hole_pattern`
|
||||
|
||||
不支持的几何必须显式进入 quarantine，并记录缺失能力；系统禁止使用源 STEP、嵌入 B-Rep、完整网格替身或源拓扑引用绕过重建。
|
||||
|
||||
## STEP 蒸馏与验收
|
||||
|
||||
将待处理的 STEP/STP 文件放入：
|
||||
|
||||
```text
|
||||
designir-pipeline/workspace/teacher/inbox/
|
||||
```
|
||||
|
||||
完整运行目录：
|
||||
|
||||
| 阶段 | 路径 |
|
||||
| --- | --- |
|
||||
| 教师 STEP 输入 | `workspace/teacher/inbox/` |
|
||||
| 私有几何证据 | `workspace/teacher/evidence/` |
|
||||
| Reconstruction Agent 输入 | `workspace/reconstruction/inbox/` |
|
||||
| 参数化重建结果 | `workspace/reconstruction/designir/` |
|
||||
| 独立重建 STEP | `workspace/reconstruction/output/` |
|
||||
| Acceptance Agent 输入 | `workspace/acceptance/inbox/` |
|
||||
| 验收报告 | `workspace/acceptance/reports/` |
|
||||
| 经验候选 | `workspace/promotion/candidates/` |
|
||||
| 跨案例回放验证 | `workspace/promotion/replay_validated/` |
|
||||
| 正式经验库 | `workspace/promotion/promoted/library.json` |
|
||||
| 失败与能力缺口 | `workspace/quarantine/` |
|
||||
|
||||
详细说明见 [`designir-pipeline/workspace/README.md`](designir-pipeline/workspace/README.md)。
|
||||
|
||||
批量提取教师证据：
|
||||
|
||||
```bash
|
||||
designir-pipeline/scripts/cad-experience extract-folder \
|
||||
--input designir-pipeline/workspace/teacher/inbox \
|
||||
--output designir-pipeline/workspace/teacher/evidence
|
||||
```
|
||||
|
||||
蒸馏得到的经验必须同时通过几何一致性、特征语义、参数可编辑性和修改稳定性验收。两个 Agent 都无权直接发布经验，最终晋升由确定性策略执行。
|
||||
|
||||
## 本地开发
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Node.js 22+
|
||||
- Python 3.12
|
||||
- OpenCascade/Build123d 所需的本地运行依赖
|
||||
|
||||
### 启动前端
|
||||
|
||||
```bash
|
||||
cd cad-agent-studio
|
||||
npm install
|
||||
npm run dev -- -H 127.0.0.1 -p 53821
|
||||
```
|
||||
|
||||
打开 `http://127.0.0.1:53821`。
|
||||
|
||||
前端默认读取仓库根目录的 `llm.config.yaml`。也可以通过 `CAD_AGENT_STUDIO_CONFIG` 指向其他配置文件。
|
||||
|
||||
### DesignIR 命令
|
||||
|
||||
```bash
|
||||
text-to-cad/.venv/bin/python \
|
||||
designir-pipeline/scripts/designir_pipeline.py validate \
|
||||
designir-pipeline/examples/raised_hub_flange.designir.json
|
||||
|
||||
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 build123d
|
||||
```
|
||||
|
||||
`simplecadapi` 后端还会在 STEP 旁生成可重放的 `*.simplecad.model.json`。
|
||||
|
||||
## 验证
|
||||
|
||||
前端：
|
||||
|
||||
```bash
|
||||
cd cad-agent-studio
|
||||
npm test
|
||||
npm run build
|
||||
```
|
||||
|
||||
DesignIR、经验库与 CAD 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
|
||||
text-to-cad/.venv/bin/python \
|
||||
designir-pipeline/skills/cad-experience-builder/scripts/cad_experience.py \
|
||||
audit designir-pipeline/workspace/promotion/promoted/library.json
|
||||
```
|
||||
|
||||
## 当前边界
|
||||
|
||||
DesignIR 当前优先覆盖规则机械零件，例如法兰、板件、支架、轴套、带孔块和基础壳体。自由曲面、多轨扫掠、复杂铸造过渡和高阶连续曲面仍需要扩展特征词汇。
|
||||
|
||||
工作区已经具备批量证据提取、角色隔离、独立重建、验收和经验晋升能力；批处理目前由命令或 Agent 任务触发，尚未提供常驻目录监听服务。
|
||||
|
||||
Reference in New Issue
Block a user