block-insert

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

一、最小：定义 + 插入

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 字段速查

MCP 参考：vjcad/doc/entity/insert-ent.md、vjcad/example/entity/block/02insert.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