> **本文回答**：块的标准流程是 `doc.blocks.itemByName(name)` 找现有 / `doc.blocks.add(name)` 新建定义，给 `blockDef.basePoint` 与 `blockDef.addEntity(...)` 加内容；插入用 `new InsertEnt()` + `blockId / insertionPoint / scaleFactor / rotation`。块属性、块炸开、`COUNTBLOCK`、`REPLACEBLOCK` 都有现成示例。

## 一、最小：定义 + 插入

```js
const doc = Engine.currentDoc;
const blockName = 'DemoBlock';

let blockDef = doc.blocks.itemByName(blockName);
if (!blockDef) {
  blockDef = doc.blocks.add(blockName);
  blockDef.basePoint = [0, 0];

  const l1 = new LineEnt([-15, 0], [15, 0]);
  const l2 = new LineEnt([0, -15], [0, 15]);
  const c  = new CircleEnt([0, 0], 10);
  l1.setDefaults(); l2.setDefaults(); c.setDefaults();
  blockDef.addEntity(l1);
  blockDef.addEntity(l2);
  blockDef.addEntity(c);
}

const ins = new InsertEnt();
ins.blockId         = blockDef.blockId;
ins.insertionPoint  = [x, y];
ins.scaleFactor     = 1.5;
ins.rotation        = 0;
ins.setDefaults();
ins.color = 5;
Engine.addEntities(ins);
```

MCP 参考：`vjcad/example/entity/all/01entities.js`、`vjcad/example/entity/block/01create.js`、`02insert.js`。

## 二、`InsertEnt` 字段速查

| 字段 | 说明 |
|---|---|
| `blockId` | 引用的 `BlockDefinition.blockId` |
| `insertionPoint` | 插入点 |
| `scaleFactor` | 等比缩放（⚠️ vjcad@1.0.16 无 `xScaleFactor / yScaleFactor` 分轴字段，只有统一 `scaleFactor`） |
| `rotation` | 旋转（弧度） |

MCP 参考：`vjcad/doc/entity/insert-ent.md`、`vjcad/example/entity/block/02insert.js`。

## 三、块炸开 / 计数 / 替换（内置命令）

| 操作 | 命令 / API | 来源 |
|---|---|---|
| 炸开块为独立实体 | `EXPLODE` 或 `Engine.editor.executerWithOp('EXPLODE')` | `vjcad/example/entity/block/03explode.js` |
| 块统计 | `COUNTBLOCK` | `vjcad/example/entity/block/05countblock.js`、`vjcad/doc/entity/index.md` |
| 块替换 | `REPLACEBLOCK` | `vjcad/example/entity/block/06replaceblock.js`、`vjcad/doc/entity/index.md` |
| 块属性文字（属性定义 + 属性值） | 见 `vjcad/example/entity/block/04attribute.js` | 同上 |

## 四、查询 / 遍历

```js
const all = Engine.currentDoc.blocks.items;             // 所有块定义
const def = Engine.currentDoc.blocks.itemByName('X');   // 按名查找
```

MCP 参考：`vjcad/example/entity/all/01entities.js`、`vjcad/doc/entity/block-entities.md`。

## 反例

- 给 `InsertEnt.blockId` 赋了错误的值（例如直接是 `blockName` 字符串）：实际应是 `blockDef.blockId`。
- 创建块时忘记 `basePoint`：插入点的对齐参考会乱。
- 在 `addEntity(...)` 之前没 `setDefaults()`：块内实体丢图层 / 颜色信息。

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/entity/block-entities.md`、`vjcad/doc/entity/insert-ent.md`、`vjcad/doc/entity/index.md`
- 示例：`vjcad/example/entity/block/01create.js` ~ `06replaceblock.js`、`vjcad/example/entity/all/01entities.js`