> **本文回答**：创建图层推荐 `Engine.createLayer(name, opts)`（自动命名传 `Engine.createLayer()`）；切当前图层 `Engine.setCurrentLayer(name)`；删除 `Engine.currentDoc.layers.remove(name)`（图层 0 不能删）。

## 一、创建图层

### 方式 1：`Engine.createLayer`（推荐）

```js
// LayerCreateOptions 只有 { layerOn, color, lineType, isFrozen, isLocked }
const layer = Engine.createLayer('标注层', {
  color:      1,           // 红色
  lineType:   'CONTINUOUS',
  layerOn:    true,
  isFrozen:   false,
  isLocked:   false
});
layer.lineWeight = 25;     // 线宽要创建后单独设（0.25mm，单位 0.01mm）
```

### 方式 2：`doc.layers.addlayer`

```js
const doc = Engine.currentDoc;
if (!doc.layers.itemByName('辅助线层')) {
  doc.layers.addlayer('辅助线层', true, 3);    // (name, layerOn, color)
}
```

### 方式 3：`doc.layers.add`（带选项的重载）

```js
if (!doc.layers.has('标注层')) {
  doc.layers.add('标注层', {
    color:    3,
    lineType: 'CONTINUOUS',
    layerOn:  true,
    frozen:   false       // 注意：这里是 frozen（isFrozen 的别名）
  });
}
```

### 自动命名

```js
const auto = Engine.createLayer();      // '图层1' / '图层2' / ...
console.log(auto.name);
```

MCP 参考：`vjcad/example/layer/01create.js`、`vjcad/doc/layer/layers.md`。

## 二、切换当前图层

```js
Engine.setCurrentLayer('墙体');

// 不等价的底层写法：直接设置文档变量（CLAYER 是图层**名字符串**，不是 Layer 对象）
// ⚠️ 不记 undo、不刷新界面；图层不存在时静默设为 '0'（setCurrentLayer 则返回 false 且不改）
Engine.currentDoc.CLAYER = '墙体';

// 读取
const cur = Engine.getCurrentLayer();    // 返回当前图层名
```

MCP 参考：`vjcad/example/layer/02switch.js`、`vjcad/doc/layer/layers.md`。

> **注意**：`Engine.CLAYER` **不存在**——正确写法是 `Engine.currentDoc.CLAYER`（d.ts `get CLAYER(): string`，返回图层名字符串；要 Layer 对象用 `Engine.getLayerByName(name)`）。

## 三、修改图层属性

```js
const layer = Engine.getLayerByName('墙体');
layer.color    = 5;
layer.lineType = 'DASHED';
layer.lineWeight = 50;
```

## 四、删除图层

```js
// remove 收 Layer 对象，不是名字
const tmp = Engine.currentDoc.layers.itemByName('临时图层');
if (tmp) Engine.currentDoc.layers.remove(tmp);
```

> ⚠️ **`doc.layers.remove` API 层没有任何防护**：`Layers.remove()` 只发可取消的 `LayerDeleting` 事件就直接 `splice`——**"0" 图层和当前图层都能被直接删掉**，删掉 0 层后实体图层查找失败：**`EntityBase.setDefaults()` 立即抛 `TypeError: undefined.name`**（新建实体没法再赋默认属性），而 `addEntities`/`eraseEntities`/`exportEntitiesToImage` 仍能跑——破坏面集中在"读当前层名"的路径，不只 `regen()`。"0 层不能删/当前层不能删"的约束只在**命令层**存在（`LayerCommand.purgelayer` 会过滤 `"0"!==name` 与当前层）。用 API 删层前先自行判断 `layer.name !== '0'` 且 `layer.name !== Engine.getCurrentLayer()`。
>
> ⚠️ 删层后实体**不是被"移到"0 层**：实体的 `layerId` 保持悬空（仍指向已删图层 id），只是 `entity.layer` getter 查不到图层时回退返回 `"0"`。要真正迁移需遍历实体改 `layerId`。

MCP 参考：`vjcad/doc/layer/layers.md`。

## 反例

- `doc.layers.add('A')` 不带选项又不检查重名：抛错或被忽略，先用 `has(name)` / `itemByName(name)` 判断。
- 写 `Engine.CLAYER`：该静态不存在，读出来是 `undefined`；正确是 `Engine.currentDoc.CLAYER`（字符串）。
- 删了"当前图层"：命令层会拒绝，但 `doc.layers.remove` API **不会**拒绝——先 `Engine.setCurrentLayer('0')` 再删。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/layer/layers.md`、`vjcad/doc/layer/index.md`
- 示例：`vjcad/example/layer/01create.js`、`vjcad/example/layer/02switch.js`