# CDSL 格式说明

CDSL（`cad.cdsl.llm.v1`）是描述**单个零件建模历史**的 JSON 格式。当前版本为
`1.1.0`：先定义草图，再按依赖顺序定义基体、切除、孔和修饰等特征。

## 基本结构

```text
根对象
|- 身份信息：schema、schema_version、kind、part_id、meta
|- geometry.sketches：二维草图及其三维工作平面
`- features：按依赖顺序执行的建模特征
```

下面的示例创建一个半径 20 mm、高 8 mm 的圆柱：

```json
{
  "schema": "cad.cdsl.llm.v1",
  "schema_version": "1.1.0",
  "kind": "part",
  "part_id": "cylinder-001",
  "meta": {"unit": "mm"},
  "geometry": {
    "sketches": [
      {
        "id": "sk_base",
        "workplane": {
          "origin_mm": [0, 0, 0],
          "x_dir": [1, 0, 0],
          "normal": [0, 0, 1]
        },
        "profile": {
          "type": "circle",
          "center": [0, 0],
          "radius_mm": 20
        }
      }
    ]
  },
  "features": [
    {
      "id": "base_add",
      "atomic_id": "extrude_add_blind",
      "depends_on": [],
      "sketch_id": "sk_base",
      "params": {"distance_mm": 8},
      "execution_status": "supported"
    }
  ]
}
```

## 字段说明

| 部分 | 关键字段 | 含义 |
| --- | --- | --- |
| 根对象 | `part_id`、`meta.unit` | 零件 ID；v1.1 的单位固定为 `mm`。 |
| 草图 | `id`、`workplane`、`profile` | 草图 ID、所在平面和二维轮廓。工作平面使用三维坐标与方向；轮廓可为 `circle`、`polygon` 或 `analytic_contours`。 |
| 特征 | `id`、`atomic_id`、`params` | 特征 ID、操作类型及其尺寸/参数。 |
| 引用 | `sketch_id`、`depends_on` | `sketch_id` 引用草图；`depends_on` 指向必须先完成的特征。 |
| 拓扑选择 | `selectors` 或参数内的选择器 | 对已有面、边、轴或基准面进行孔、圆角、倒角等操作时使用。 |

常见 `atomic_id`：`extrude_add_blind`（拉伸增加）、`extrude_cut_blind`（拉伸切除）、`revolve_add` / `revolve_cut`（旋转）、`hole_blind`（孔）、`fillet`（圆角）、`chamfer`（倒角）、`pattern_linear` / `pattern_mirror`（阵列）。

## 编写规则

- 所有长度字段使用 mm；二维点为草图平面坐标 `[u, v]`，三维点/方向为 `[x, y, z]`。
- 草图和特征 ID 必须唯一。特征必须在其 `depends_on` 所引用的特征之后出现。
- 拉伸和旋转需要 `sketch_id`；孔、圆角、倒角等操作通常需要选择已有的面或边。
- `execution_status` 写 `supported` 或 `deferred`；它记录导出状态，实际能否重建仍取决于当前引擎预检。