优化流程

docs/README.md

@@ -2,3 +2,5 @@
 
 Architecture decisions, API contracts, engine usage, data formats, and
 development notes belong here.
+
+- [CDSL format structure](cdsl-format.md)

docs/cdsl-format.md

@@ -0,0 +1,71 @@
+# 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`；它记录导出状态，实际能否重建仍取决于当前引擎预检。