@tmagic/editor 1.8.0-beta.23 → 1.8.0-beta.24

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.23",
+  "version": "1.8.0-beta.24",
   "name": "@tmagic/editor",
   "type": "module",
   "sideEffects": [
@@ -58,11 +58,11 @@
     "moveable": "^0.53.0",
     "serialize-javascript": "^7.0.7",
     "sortablejs": "^1.15.7",
-    "@tmagic/design": "1.8.0-beta.23",
-    "@tmagic/stage": "1.8.0-beta.23",
-    "@tmagic/utils": "1.8.0-beta.23",
-    "@tmagic/table": "1.8.0-beta.23",
-    "@tmagic/form": "1.8.0-beta.23"
+    "@tmagic/design": "1.8.0-beta.24",
+    "@tmagic/form": "1.8.0-beta.24",
+    "@tmagic/utils": "1.8.0-beta.24",
+    "@tmagic/stage": "1.8.0-beta.24",
+    "@tmagic/table": "1.8.0-beta.24"
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
@@ -75,8 +75,8 @@
     "monaco-editor": "^0.55.1 ",
     "type-fest": "^5.2.0",
     "typescript": "^6.0.3",
-    "vue": "^3.5.40",
-    "@tmagic/core": "1.8.0-beta.23"
+    "vue": "^3.5.41",
+    "@tmagic/core": "1.8.0-beta.24"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/fields/CodeSelectCol.vue

@@ -15,7 +15,7 @@
         :prop="prop"
       ></MFormContainer>
       <MSelect
-        v-else
+        v-else-if="!silentMode"
         class="select"
         :config="selectConfig"
         :name="name"
@@ -27,7 +27,7 @@
 
       <!-- 查看/编辑按钮：对比模式为只读，不展示 -->
       <TMagicButton
-        v-if="!isCompareMode && model[name] && hasCodeBlockSidePanel"
+        v-if="!isCompareMode && !silentMode && model[name] && hasCodeBlockSidePanel"
         class="m-fields-select-action-button"
         :size="size"
         @click="editCode(model[name])"
@@ -65,6 +65,7 @@ import {
   createValues,
   type FieldProps,
   filterFunction,
+  FORM_SILENT_MODE_KEY,
   type FormItemConfig,
   type FormState,
   MContainer as MFormContainer,
@@ -83,6 +84,7 @@ defineOptions({
 });
 
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 const { codeBlockService, uiService } = useServices();
 const eventBus = inject<EventBus>('eventBus');
 const emit = defineEmits<{

package/src/fields/DataSourceFieldSelect/Index.vue

@@ -6,7 +6,7 @@
     }"
   >
     <FieldSelect
-      v-if="isSelectValid"
+      v-if="isSelectValid && !silentMode"
       :model-value="model[name]"
       :disabled="disabled"
       :size="size"
@@ -18,7 +18,7 @@
     ></FieldSelect>
 
     <component
-      v-else
+      v-else-if="!silentMode"
       :is="tagName"
       :config="config.fieldConfig"
       :model="model"
@@ -33,7 +33,7 @@
     ></component>
 
     <TMagicTooltip
-      v-if="config.fieldConfig && !disabledDataSource && !mForm?.isCompare"
+      v-if="!silentMode && config.fieldConfig && !disabledDataSource && !mForm?.isCompare"
       :disabled="showDataSourceFieldSelect"
       content="选择数据源"
     >
@@ -57,6 +57,7 @@ import {
   type ContainerChangeEventData,
   type DataSourceFieldSelectConfig,
   type FieldProps,
+  FORM_SILENT_MODE_KEY,
   type FormState,
   getFormField,
 } from '@tmagic/form';
@@ -104,6 +105,7 @@ watch(
 
 const { dataSourceService, propsService } = useServices();
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 
 const dataSources = computed(() => dataSourceService.get('dataSources') || []);
 const disabledDataSource = computed(() => propsService.getDisabledDataSource());

package/src/fields/DataSourceFields.vue

@@ -8,6 +8,7 @@
     </div>
 
     <FloatingBox
+      v-if="!silentMode"
       :body-style="{ padding: '0 16px' }"
       v-model:visible="addDialogVisible"
       v-model:width="width"
@@ -30,6 +31,7 @@
     </FloatingBox>
 
     <FloatingBox
+      v-if="!silentMode"
       :body-style="{ padding: '0 16px' }"
       v-model:visible="addFromJsonDialogVisible"
       v-model:width="width"
@@ -60,6 +62,7 @@ import {
   type ContainerChangeEventData,
   type DataSourceFieldsConfig,
   type FieldProps,
+  FORM_SILENT_MODE_KEY,
   type FormConfig,
   type FormState,
   MFormBox,
@@ -89,6 +92,7 @@ const emit = defineEmits<{
 
 const { uiService } = useServices();
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 
 /** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
 const isCompare = computed(() => Boolean(mForm?.isCompare));
@@ -379,6 +383,8 @@ provide(
 );
 
 onMounted(() => {
+  if (silentMode) return;
+
   const path = editingFieldPath.value;
   if (!path.length) return;
 

package/src/fields/DataSourceMethodSelect.vue

@@ -2,6 +2,7 @@
   <div class="m-fields-data-source-method-select">
     <div class="data-source-method-select-container">
       <MCascader
+        v-if="!silentMode"
         class="select"
         :config="cascaderConfig"
         :model="model"
@@ -13,7 +14,7 @@
       ></MCascader>
 
       <TMagicTooltip
-        v-if="model[name] && isCustomMethod && dataSourceSidePanel && !isCompare"
+        v-if="!silentMode && model[name] && isCustomMethod && dataSourceSidePanel && !isCompare"
         :content="notEditable ? '查看' : '编辑'"
       >
         <TMagicButton class="m-fields-select-action-button" :size="size" @click="editCodeHandler">
@@ -48,6 +49,7 @@ import {
   type DataSourceMethodSelectConfig,
   type FieldProps,
   filterFunction,
+  FORM_SILENT_MODE_KEY,
   type FormItemConfig,
   type FormState,
   MCascader,
@@ -67,6 +69,7 @@ defineOptions({
 
 const { dataSourceService, uiService } = useServices();
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 const eventBus = inject<EventBus>('eventBus');
 
 const emit = defineEmits(['change']);

package/src/fields/DataSourceMethods.vue

@@ -9,7 +9,7 @@
     </div>
 
     <CodeBlockEditor
-      v-if="codeConfig"
+      v-if="codeConfig && !silentMode"
       ref="codeBlockEditor"
       :disabled="disabled"
       :content="codeConfig"
@@ -26,7 +26,13 @@ import { cloneDeep } from 'lodash-es';
 
 import type { CodeBlockContent } from '@tmagic/core';
 import { TMagicButton, tMagicMessageBox } from '@tmagic/design';
-import type { ContainerChangeEventData, DataSourceMethodsConfig, FieldProps, FormState } from '@tmagic/form';
+import {
+  type ContainerChangeEventData,
+  type DataSourceMethodsConfig,
+  type FieldProps,
+  FORM_SILENT_MODE_KEY,
+  type FormState,
+} from '@tmagic/form';
 import { type ColumnConfig, MagicTable } from '@tmagic/table';
 
 import CodeBlockEditor from '@editor/components/CodeBlockEditor.vue';
@@ -43,6 +49,7 @@ const props = withDefaults(defineProps<FieldProps<DataSourceMethodsConfig>>(), {
 const emit = defineEmits(['change']);
 
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 
 /** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
 const isCompare = computed(() => Boolean(mForm?.isCompare));
@@ -170,6 +177,8 @@ const editingMethodName = inject<ComputedRef<string | undefined>>(
 );
 
 onMounted(() => {
+  if (silentMode) return;
+
   const methodName = editingMethodName.value;
   if (!methodName) return;
 

package/src/fields/DataSourceMocks.vue

@@ -7,6 +7,7 @@
     </div>
 
     <FloatingBox
+      v-if="!silentMode"
       :body-style="{ padding: '0 16px' }"
       v-model:visible="addDialogVisible"
       v-model:width="width"
@@ -34,7 +35,14 @@ import { computed, inject, Ref, ref } from 'vue';
 
 import type { MockSchema } from '@tmagic/core';
 import { TMagicButton, tMagicMessageBox, TMagicSwitch } from '@tmagic/design';
-import { type DataSourceMocksConfig, type FieldProps, type FormConfig, type FormState, MFormBox } from '@tmagic/form';
+import {
+  type DataSourceMocksConfig,
+  type FieldProps,
+  FORM_SILENT_MODE_KEY,
+  type FormConfig,
+  type FormState,
+  MFormBox,
+} from '@tmagic/form';
 import { type ColumnConfig, MagicTable } from '@tmagic/table';
 import { getDefaultValueFromFields } from '@tmagic/utils';
 
@@ -57,6 +65,7 @@ const emit = defineEmits(['change']);
 
 const { uiService } = useServices();
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 
 /** 对比模式下隐藏新增/编辑/删除等操作按钮，仅保留只读展示。 */
 const isCompare = computed(() => Boolean(mForm?.isCompare));

package/src/fields/EventSelect.vue

@@ -85,7 +85,7 @@ import { Delete } from '@element-plus/icons-vue';
 import { Plus } from '@element-plus/icons-vue';
 import { has } from 'lodash-es';
 
-import { ActionType } from '@tmagic/core';
+import { ActionType, MNode } from '@tmagic/core';
 import { TMagicButton } from '@tmagic/design';
 import type {
   CodeSelectColConfig,
@@ -327,8 +327,8 @@ const tableConfig = computed(
           name: 'method',
           label: '动作',
           type: compActionConfig.value.type,
-          options: (mForm: FormState, { model }: any) => {
-            const node = editorService.getNodeById(model.to);
+          options: (mForm: FormState, { model, formValue }: any) => {
+            const node = editorService.getNodeById(model.to) || (formValue as MNode);
             if (!node?.type) return [];
 
             return eventsService.getMethod(node.type, { targetId: model.to, node }).map((option: any) => ({

package/src/fields/KeyValue.vue

@@ -44,7 +44,7 @@
     </div>
 
     <MagicCodeEditor
-      v-if="config.advanced && showCode"
+      v-if="config.advanced && showCode && !silentMode"
       editor-custom-type="m-fields-key-value"
       language="javascript"
       :init-values="model[name]"
@@ -60,7 +60,7 @@
     ></MagicCodeEditor>
 
     <TMagicButton
-      v-if="config.advanced && !isCompare"
+      v-if="config.advanced && !isCompare && !silentMode"
       size="default"
       :disabled="disabled"
       link
@@ -75,7 +75,7 @@ import { computed, inject, ref, watchEffect } from 'vue';
 import { Delete, Plus } from '@element-plus/icons-vue';
 
 import { TMagicButton, TMagicInput } from '@tmagic/design';
-import type { FieldProps, FormState, KeyValueConfig } from '@tmagic/form';
+import { type FieldProps, FORM_SILENT_MODE_KEY, type FormState, type KeyValueConfig } from '@tmagic/form';
 
 import CodeIcon from '@editor/icons/CodeIcon.vue';
 import MagicCodeEditor from '@editor/layouts/CodeEditor.vue';
@@ -93,6 +93,7 @@ const emit = defineEmits<{
 }>();
 
 const mForm = inject<FormState | undefined>('mForm');
+const silentMode = inject(FORM_SILENT_MODE_KEY, false);
 
 /** 对比模式下隐藏增删/代码切换等操作按钮，仅保留只读展示。 */
 const isCompare = computed(() => Boolean(mForm?.isCompare));

package/src/hooks/use-compare-form.ts

@@ -23,7 +23,6 @@ import { type FormConfig, type FormState, type FormValue, MForm } from '@tmagic/
 
 import type { CompareFormBaseProps } from '@editor/type';
 import { getCodeBlockFormConfig } from '@editor/utils/code-block';
-import { removeStyleDisplayConfig } from '@editor/utils/props';
 
 export interface UseCompareFormReturn {
   config: Ref<FormConfig>;
@@ -107,9 +106,7 @@ export const useCompareForm = (props: CompareFormBaseProps): UseCompareFormRetur
         if (!props.type) {
           return [];
         }
-        return removeStyleDisplayConfig(
-          await props.services.propsService.getPropsConfig(props.type, { node: props.value as unknown as MNode }),
-        );
+        return props.services.propsService.getPropsConfig(props.type, { node: props.value as unknown as MNode });
       }
       case 'data-source': {
         const config = props.services.dataSourceService.getFormConfig(props.type || 'base');

package/src/plugin.ts

@@ -21,7 +21,7 @@ import { type App } from 'vue';
 import type { DesignPluginOptions } from '@tmagic/design';
 import designPlugin from '@tmagic/design';
 import type { FormInstallOptions } from '@tmagic/form';
-import formPlugin, { registerTypeMatchRules } from '@tmagic/form';
+import formPlugin, { registerSilentLeafFieldTypes, registerTypeMatchRules } from '@tmagic/form';
 import tablePlugin from '@tmagic/table';
 
 import Code from './fields/Code.vue';
@@ -68,6 +68,14 @@ export default {
     app.use(formPlugin, opt || {});
     app.use(tablePlugin);
     registerTypeMatchRules(editorTypeMatchRules);
+    registerSilentLeafFieldTypes([
+      'vs-code',
+      'ui-select',
+      'cond-op-select',
+      'page-fragment-select',
+      'data-source-select',
+      'data-source-input',
+    ]);
 
     app.config.globalProperties.$TMAGIC_EDITOR = option;
     setEditorConfig(option);

package/src/services/editor.ts

@@ -56,6 +56,7 @@ import type {
   StepValue,
   StoreState,
   StoreStateKey,
+  UpdateOptions,
 } from '@editor/type';
 import { canUsePluginMethods, LayerOffset, Layout } from '@editor/type';
 import {
@@ -83,6 +84,10 @@ import { beforePaste, getAddParent } from '@editor/utils/operator';
 
 type MoveItem = { node: MNode; parent: MContainer; pageForOp: { name: string; id: Id } | null };
 
+/** 历史插回时把记录的下标收敛到 [0, length]，越界（含未记录）一律追加到末尾 */
+const clampIndex = (index: number | undefined, length: number): number =>
+  typeof index === 'number' && index >= 0 && index <= length ? index : length;
+
 /**
  * 把「变更前后节点快照」列表归一成 update 类型的 {@link StepDiffItem} 列表，供 {@link StepValue.diff} 使用。
  * `changeRecords` 来自 form 端的 propPath/value 列表，撤销/重做时只对这些 propPath 做局部更新；
@@ -126,6 +131,11 @@ class Editor extends BaseService {
    * 普通操作不会读取它，调用前由 *AndGetHistoryId 重置为 null。
    */
   private lastPushedHistoryId: string | null = null;
+  /**
+   * 上一次 doAdd 的插入记忆：nodeId 为插入的节点，selectedId 为当时的选中节点。
+   * 仅在选中节点未变化时复用（连续 add / doNotSelect / 批量粘贴），选中变化后自动失效，无需手动清理。
+   */
+  private lastAdded: { selectedId: Id; nodeId: Id } | null = null;
 
   constructor() {
     super(
@@ -404,7 +414,7 @@ class Editor extends BaseService {
     this.set('highlightNode', null);
   }
 
-  public async doAdd(node: MNode, parent: MContainer): Promise<MNode> {
+  public async doAdd(node: MNode, parent: MContainer, _options: DslOpOptions = {}): Promise<MNode> {
     const root = this.get('root');
 
     if (!root) throw new Error('root为空');
@@ -418,13 +428,16 @@ class Editor extends BaseService {
       throw new Error('app下不能添加组件');
     }
 
-    if (parent.id !== curNode.id && !isPageOrFragment(node)) {
-      const index = parent.items.indexOf(curNode);
-      parent.items?.splice(index + 1, 0, node);
-    } else {
-      // 新增节点添加到配置中
-      parent.items?.push(node);
-    }
+    // 连续 add 时接在上一个新增节点之后，否则接在当前选中节点之后；
+    // 锚点节点可能已不在 items 中（被删 / DSL 整体替换），回退到当前选中节点，都不在则追加到末尾
+    const anchorId = this.lastAdded?.selectedId === curNode.id ? this.lastAdded.nodeId : curNode.id;
+    const anchorIndex = isPageOrFragment(node)
+      ? -1
+      : Math.max(getNodeIndex(anchorId, parent), getNodeIndex(curNode.id, parent));
+    const insertIndex = anchorIndex < 0 ? parent.items.length : anchorIndex + 1;
+
+    parent.items.splice(insertIndex, 0, node);
+    this.lastAdded = { selectedId: curNode.id, nodeId: node.id };
 
     const layout = await this.getLayout(toRaw(parent), node as MNode);
     node.style = getInitPositionStyle(node.style, layout);
@@ -434,6 +447,7 @@ class Editor extends BaseService {
       parent: cloneDeep(parent),
       parentId: parent.id,
       root: cloneDeep(root),
+      index: insertIndex,
     });
 
     const newStyle = fixNodePosition(node, parent, stage);
@@ -452,24 +466,23 @@ class Editor extends BaseService {
    * 向指点容器添加组件节点
    * @param addConfig 将要添加的组件节点配置
    * @param parent 要添加到的容器组件节点配置，如果不设置，默认为当前选中的组件的父节点
-   * @param options 可选配置
-   * @param options.doNotSelect 添加后是否不更新当前选中节点（默认 false，添加后会选中新增的节点）
-   * @param options.doNotSwitchPage 添加后是否不切换当前页面（默认 false；新增页面 / 跨页新增时为 true 会跳过会引发页面切换的选中操作）
-   * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
+   * @param options 可选配置，见 {@link DslOpOptions}
    * @returns 添加后的节点
    */
   public async add(
     addNode: AddMNode | MNode[],
     parent?: MContainer | null,
-    {
+    options: DslOpOptions = {},
+  ): Promise<MNode | MNode[]> {
+    this.captureSelectionBeforeOp();
+
+    const {
       doNotSelect = false,
       doNotSwitchPage = false,
       doNotPushHistory = false,
       historyDescription,
       historySource,
-    }: DslOpOptions = {},
-  ): Promise<MNode | MNode[]> {
-    this.captureSelectionBeforeOp();
+    } = options;
 
     const stage = this.get('stage');
 
@@ -485,17 +498,15 @@ class Editor extends BaseService {
       addNodes.push(...addNode);
     }
 
-    const newNodes = await Promise.all(
-      addNodes.map((node) => {
-        const root = this.get('root');
-        if (isPageOrFragment(node) && root) {
-          return this.doAdd(node, root);
-        }
-        const parentNode = parent ?? getAddParent(node);
-        if (!parentNode) throw new Error('未找到父元素');
-        return this.doAdd(node, parentNode);
-      }),
-    );
+    // 必须串行：每个节点的插入位置依赖上一个已插入的节点，并行时插入顺序会受
+    // doAdd 前置耗时（如异步 beforeDoAdd 插件钩子）影响而错乱
+    const newNodes: MNode[] = [];
+    for (const node of addNodes) {
+      const root = this.get('root');
+      const parentNode = isPageOrFragment(node) && root ? root : (parent ?? getAddParent(node));
+      if (!parentNode) throw new Error('未找到父元素');
+      newNodes.push(await this.doAdd(node, parentNode, options));
+    }
 
     if (newNodes.length > 1) {
       // 多选时只要任一新增节点位于非当前页面，触发的 multiSelect 就会引起页面切换
@@ -654,16 +665,8 @@ class Editor extends BaseService {
    * @param options.doNotSwitchPage 删除后是否不切换当前页面（默认 false；删除页面 / 页面片段时为 true 会跳过自动切换到首个剩余页面）
    * @param options.doNotPushHistory 是否不写入历史记录（默认 false）
    */
-  public async remove(
-    nodeOrNodeList: MNode | MNode[],
-    {
-      doNotSelect = false,
-      doNotSwitchPage = false,
-      doNotPushHistory = false,
-      historyDescription,
-      historySource,
-    }: DslOpOptions = {},
-  ): Promise<void> {
+  public async remove(nodeOrNodeList: MNode | MNode[], options: DslOpOptions = {}): Promise<void> {
+    const { doNotPushHistory = false, historyDescription, historySource } = options;
     this.captureSelectionBeforeOp();
 
     const nodes = Array.isArray(nodeOrNodeList) ? nodeOrNodeList : [nodeOrNodeList];
@@ -690,7 +693,7 @@ class Editor extends BaseService {
       }
     }
 
-    await Promise.all(nodes.map((node) => this.doRemove(node, { doNotSelect, doNotSwitchPage })));
+    await Promise.all(nodes.map((node) => this.doRemove(node, options)));
 
     // 删除节点时同步清理其（含子树）的校验错误记录；置于 pushOpHistory 之前，使历史快照与本次删除对齐。
     this.removeInvalidNodesBySubtree(nodes);
@@ -720,12 +723,9 @@ class Editor extends BaseService {
 
   public async doUpdate(
     config: MNode,
-    {
-      changeRecords = [],
-      historySource,
-      replace = false,
-    }: { changeRecords?: ChangeRecord[]; historySource?: HistoryOpSource; replace?: boolean } = {},
+    data: UpdateOptions = {},
   ): Promise<{ newNode: MNode; oldNode: MNode; changeRecords?: ChangeRecord[] }> {
+    const { changeRecords = [], historySource, replace = false } = data;
     const root = this.get('root');
     if (!root) throw new Error('root为空');
 
@@ -804,34 +804,10 @@ class Editor extends BaseService {
    * 更新节点
    * update后会触发依赖收集，收集完后会掉stage.update方法
    * @param config 新的节点配置，配置中需要有id信息
-   * @param data 额外数据
-   * @param data.changeRecords 单节点 form 端变更记录（多节点场景下被忽略，使用 changeRecordList）
-   * @param data.changeRecordList 多节点 form 端变更记录列表，按 config 数组同序对应每个节点；优先级高于 changeRecords
-   * @param data.doNotPushHistory 是否不写入历史记录（默认 false）
-   * @param data.historyDescription 入栈时附带的人类可读描述，用于历史面板展示（不影响 undo/redo 行为）
-   * @param data.replace 是否整节点替换：为 true 时跳过 mergeWith / toggleFixedPosition / setChildrenLayout，直接用传入配置覆盖（默认 false）
+   * @param data 额外数据，见 {@link UpdateOptions}
    * @returns 更新后的节点配置
    */
-  public async update(
-    config: MNode | MNode[],
-    data: {
-      changeRecords?: ChangeRecord[];
-      changeRecordList?: ChangeRecord[][];
-      doNotPushHistory?: boolean;
-      historyDescription?: string;
-      historySource?: HistoryOpSource;
-      /**
-       * 为 true 时不做深合并等变换，直接用传入配置整节点替换现有节点。
-       * 适用于源码编辑、历史整节点快照回放等「完整 DSL」场景；默认 false（局部属性更新走 merge）。
-       */
-      replace?: boolean;
-      /**
-       * 属性面板提交时携带的校验错误信息，在写入历史记录之前落库，
-       * 使历史快照与本次变更对齐，从而 undo/redo 能正确还原错误标记。
-       */
-      invalidInfo?: { id: Id; source: NodeInvalidSource; error?: string };
-    } = {},
-  ): Promise<MNode | MNode[]> {
+  public async update(config: MNode | MNode[], data: UpdateOptions = {}): Promise<MNode | MNode[]> {
     this.captureSelectionBeforeOp();
 
     const {
@@ -840,7 +816,6 @@ class Editor extends BaseService {
       changeRecords,
       historyDescription,
       historySource,
-      replace = false,
       invalidInfo,
     } = data;
 
@@ -851,7 +826,7 @@ class Editor extends BaseService {
     const updateData = await Promise.all(
       nodes.map((node, index) => {
         const recordsForNode = changeRecordList ? (changeRecordList[index] ?? []) : (changeRecords ?? []);
-        return this.doUpdate(node, { changeRecords: recordsForNode, historySource, replace });
+        return this.doUpdate(node, { ...data, changeRecords: recordsForNode });
       }),
     );
 
@@ -1360,14 +1335,7 @@ class Editor extends BaseService {
   /** 等价于 {@link update}，并额外返回本次写入历史记录的 uuid 列表（未入栈时 historyIds 为 `[]`）。 */
   public async updateAndGetHistoryId(
     config: MNode | MNode[],
-    data: {
-      changeRecords?: ChangeRecord[];
-      changeRecordList?: ChangeRecord[][];
-      doNotPushHistory?: boolean;
-      historyDescription?: string;
-      historySource?: HistoryOpSource;
-      replace?: boolean;
-    } = {},
+    data: UpdateOptions = {},
   ): Promise<DslOpWithHistoryIdsResult<MNode | MNode[]>> {
     this.lastPushedHistoryId = null;
     const result = await this.update(config, data);
@@ -1987,17 +1955,15 @@ class Editor extends BaseService {
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent?.items) {
               const addedNode = cloneDeep(newSchema);
-              if (typeof index === 'number' && index >= 0 && index < parent.items.length) {
-                parent.items.splice(index, 0, addedNode);
-              } else {
-                parent.items.push(addedNode);
-              }
+              const insertIndex = clampIndex(index, parent.items.length);
+              parent.items.splice(insertIndex, 0, addedNode);
               addedNodes.push(addedNode);
               await stage?.add({
                 config: cloneDeep(newSchema),
                 parent: cloneDeep(parent),
                 parentId: parent.id,
                 root: cloneDeep(root),
+                index: insertIndex,
               });
             }
           }
@@ -2016,13 +1982,15 @@ class Editor extends BaseService {
             const parent = this.getNodeById(parentId, false) as MContainer | null;
             if (parent?.items) {
               const addedNode = cloneDeep(oldSchema);
-              parent.items.splice(index ?? parent.items.length, 0, addedNode);
+              const insertIndex = clampIndex(index, parent.items.length);
+              parent.items.splice(insertIndex, 0, addedNode);
               addedNodes.push(addedNode);
               await stage?.add({
                 config: cloneDeep(oldSchema),
                 parent: cloneDeep(parent),
                 parentId,
                 root: cloneDeep(root),
+                index: insertIndex,
               });
             }
           }

package/src/type.ts

@@ -1464,6 +1464,29 @@ export interface DslOpOptions extends HistoryOpOptions {
 }
 // #endregion DslOpOptions
 
+// #region UpdateOptions
+/**
+ * {@link EditorService.update} / {@link EditorService.doUpdate} 的额外数据
+ * - changeRecords: 单节点 form 端变更记录（多节点场景下被忽略，使用 changeRecordList）
+ * - changeRecordList: 多节点 form 端变更记录列表，按 config 数组同序对应每个节点；优先级高于 changeRecords
+ * - replace: 为 true 时跳过 mergeWith / toggleFixedPosition / setChildrenLayout，直接用传入配置整节点替换
+ * - invalidInfo: 属性面板提交时携带的校验错误信息，在写入历史记录之前落库
+ */
+export interface UpdateOptions extends HistoryOpOptionsWithChangeRecords {
+  changeRecordList?: ChangeRecord[][];
+  /**
+   * 为 true 时不做深合并等变换，直接用传入配置整节点替换现有节点。
+   * 适用于源码编辑、历史整节点快照回放等「完整 DSL」场景；默认 false（局部属性更新走 merge）。
+   */
+  replace?: boolean;
+  /**
+   * 属性面板提交时携带的校验错误信息，在写入历史记录之前落库，
+   * 使历史快照与本次变更对齐，从而 undo/redo 能正确还原错误标记。
+   */
+  invalidInfo?: { id: Id; source: NodeInvalidSource; error?: string };
+}
+// #endregion UpdateOptions
+
 /** 差异对话框的入参 */
 export interface DiffDialogPayload {
   /** 表单类别 */