one-design-next 0.0.114 → 0.0.115

package/dist/composer/editor.d.ts

@@ -122,6 +122,19 @@ export interface ComposerEditorRef {
      * 配合浮层"用户选了某个 skill"的回调使用。
      */
     replaceTriggerWithChip: (data: ChipData) => void;
+    /**
+     * 在内容末尾插入 raw value + chips（`ComposerRef.insertContent` 的编辑器实现）。
+     *
+     * 与粘贴 / 草稿还原共用 `insertSerializedAtRange`：一次 mutation 只抛一次
+     * onChange，派生 hint / 高度 / trigger 也只重算一次。
+     *
+     * - `focus: false`：不聚焦、不滚动，也不主动改写 selection（后台预填草稿）
+     */
+    insertSerializedAtEnd: (value: string, chips: ChipData[], options?: {
+        focus?: boolean;
+    }) => void;
+    /** 当前 raw value（含 marker，DOM 实时值；不依赖 React state 是否已 flush） */
+    getValue: () => string;
     /** 主动取消当前触发态（不修改 DOM，只清状态 + 抛 onTriggerChange(null)）。 */
     cancelTrigger: () => void;
     /** 取最新的 trigger rect，便于浮层在滚动 / resize 时刷新位置。 */

package/dist/composer/editor.js

@@ -23,13 +23,13 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import ScrollArea from "../scroll-area";
-import { caretBeforeHintIn, caretRangeFromPoint, findChipHostBeforeCaret, getCurrentLine, isCaretBeforeHint, isCaretOnHintLine, isPointOnHint, isPositionAfterHint, mergeLineIntoPreviousAtCaretStart, normalizeCollapsedCaretAtChipBoundary, normalizeCollapsedCaretBeforeHint, resolveCaretMove, splitLineAt, wouldArrowCrossHint } from "./caret";
+import { caretBeforeHintIn, caretRangeFromPoint, findChipHostBeforeCaret, getCaretBeforeHint, getCurrentLine, isCaretBeforeHint, isCaretOnHintLine, isPointOnHint, isPositionAfterHint, mergeLineIntoPreviousAtCaretStart, normalizeCollapsedCaretAtChipBoundary, normalizeCollapsedCaretBeforeHint, resolveCaretMove, splitLineAt, wouldArrowCrossHint } from "./caret";
 import { buildClipboardPayload, COMPOSER_CLIPBOARD_MIME, parseClipboardPayload, plainTextFromClipboardPayload, remapClipboardPayload } from "./clipboard";
 import { useChipManager } from "./hooks/useChipManager";
 import { useChipSelectionMarker } from "./hooks/useChipSelectionMarker";
 import { chipHasEditableParams, ComposerInlineRef } from "./inline-ref";
 import { resolveHintTarget } from "./segments";
-import { COMPOSER_HINT_ATTR, createLineRoot, createLineRootWithText, ensureLineRoots, getPlainText, isEditorEmpty, LINE_ATTR_NAME, normalizeEditorDom, probeTrigger, stripInvisibleChars, ZWSP } from "./utils";
+import { COMPOSER_HINT_ATTR, createLineRoot, createLineRootWithText, ensureCaretAnchorAfter, ensureLineRoots, getPlainText, isEditorEmpty, isLineRoot, LINE_ATTR_NAME, normalizeEditorDom, probeTrigger, stripInvisibleChars, ZWSP } from "./utils";
 
 /** Composer editor 触发态对外信号——告诉父组件该弹浮层选 skill 了。 */
 
@@ -82,6 +82,109 @@ var scrollCaretIntoView = function scrollCaretIntoView(viewport) {
     viewport.scrollTop -= viewportRect.top - rect.top + 4;
   }
 };
+
+/** insertContent 的目标行：最后一个行容器；没有行模型时退回 editor 本身。 */
+var resolveEndLine = function resolveEndLine(editor) {
+  var last = editor.lastElementChild;
+  return isLineRoot(last) ? last : editor;
+};
+
+/** 行内直接子节点的派生 hint（不是正文，插入必须落在它之前）。 */
+var findDirectHint = function findDirectHint(line) {
+  for (var _i = 0, _Array$from = Array.from(line.children); _i < _Array$from.length; _i++) {
+    var child = _Array$from[_i];
+    if (child.hasAttribute(COMPOSER_HINT_ATTR)) return child;
+  }
+  return null;
+};
+
+/**
+ * insertContent 的插入点：最后一个行容器的内容末尾。
+ *
+ * 不能直接 `selectNodeContents(editor).collapse(false)`：
+ * - 行尾的派生 hint 不是内容：落在 hint 之前，避免内容插到灰字后面
+ * - 行尾的占位 `<br>` 不是换行：插到它前面。插到后面会让它从「占位」变成
+ *   真实换行，`getPlainText` 就会凭空多输出一个 '\n'
+ */
+var resolveEndRange = function resolveEndRange(editor) {
+  var line = resolveEndLine(editor);
+  var range = document.createRange();
+  var hint = findDirectHint(line);
+  if (hint) {
+    var before = getCaretBeforeHint(hint);
+    if (before) {
+      range.setStart(before.node, before.offset);
+      range.collapse(true);
+      return range;
+    }
+  }
+  var offset = line.childNodes.length;
+  while (offset > 0) {
+    var node = line.childNodes[offset - 1];
+    if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'BR') {
+      offset -= 1;
+      continue;
+    }
+    break;
+  }
+  range.setStart(line, offset);
+  range.collapse(true);
+  return range;
+};
+
+/**
+ * insertContent 之后把 caret 落到新内容末尾。
+ *
+ * 行尾是 chip 时补一颗不进 value 的 ZWSP 锚点（与 insertChip 一致）：
+ * 只靠元素偏移落位时，部分浏览器会把 caret 带到结构块之后。
+ * 行尾有派生 hint 时仍落在 hint 之前（hint 之后不是合法插入点）。
+ */
+var placeCaretAtEnd = function placeCaretAtEnd(editor) {
+  var sel = window.getSelection();
+  if (!sel) return;
+  var line = resolveEndLine(editor);
+  var target;
+  var hint = findDirectHint(line);
+  var beforeHint = hint ? getCaretBeforeHint(hint) : null;
+  if (beforeHint) {
+    target = beforeHint;
+  } else {
+    var offset = line.childNodes.length;
+    while (offset > 0) {
+      var node = line.childNodes[offset - 1];
+      if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'BR') {
+        offset -= 1;
+        continue;
+      }
+      break;
+    }
+    var tail = offset > 0 ? line.childNodes[offset - 1] : null;
+    if ((tail === null || tail === void 0 ? void 0 : tail.nodeType) === Node.TEXT_NODE) {
+      var _tail$textContent;
+      target = {
+        node: tail,
+        offset: ((_tail$textContent = tail.textContent) !== null && _tail$textContent !== void 0 ? _tail$textContent : '').length
+      };
+    } else if (tail instanceof HTMLElement && tail.hasAttribute('data-odn-composer-chip-host')) {
+      var _anchor$textContent;
+      var _anchor = ensureCaretAnchorAfter(tail);
+      target = {
+        node: _anchor,
+        offset: ((_anchor$textContent = _anchor.textContent) !== null && _anchor$textContent !== void 0 ? _anchor$textContent : '').length
+      };
+    } else {
+      target = {
+        node: line,
+        offset: offset
+      };
+    }
+  }
+  var range = document.createRange();
+  range.setStart(target.node, target.offset);
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
+};
 var LINE_HEIGHT = 24;
 /** 与 SCSS `padding: 2px … 0` 对齐。10 行 = 10 * 24 + 2 = 242px。 */
 var EDITOR_PADDING_BLOCK = 2;
@@ -536,6 +639,33 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         onTriggerChange === null || onTriggerChange === void 0 || onTriggerChange(null);
         _insertChip(data, el);
       },
+      insertSerializedAtEnd: function insertSerializedAtEnd(value, nextChips, options) {
+        var el = editorRef.current;
+        if (!el || !value) return;
+        ensureLineRoots(el);
+        var range = resolveEndRange(el);
+        var shouldFocus = (options === null || options === void 0 ? void 0 : options.focus) !== false;
+        /* 拿不到 Selection 时仍要把内容插进去，只是不主动落 caret。 */
+        var sel = shouldFocus ? window.getSelection() : null;
+        if (sel) {
+          sel.removeAllRanges();
+          sel.addRange(range);
+        }
+        insertSerializedAtRange(value, nextChips, range, el, {
+          focus: shouldFocus,
+          caret: !!sel
+        });
+        if (!shouldFocus) return;
+        placeCaretAtEnd(el);
+        if (sel && sel.rangeCount > 0) {
+          lastEditorRangeRef.current = sel.getRangeAt(0).cloneRange();
+        }
+        requestScrollCaretIntoView();
+      },
+      getValue: function getValue() {
+        var el = editorRef.current;
+        return el ? getPlainText(el) : '';
+      },
       cancelTrigger: function cancelTrigger() {
         if (!triggerRef.current) return;
         triggerRef.current = null;
@@ -558,7 +688,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         return editorRef.current;
       }
     };
-  }, [onChange, _insertChip, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
+  }, [onChange, _insertChip, insertSerializedAtRange, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
 
   /* ─────────────────────────────────────
    * 监听 selection 变化：方向键 / 鼠标点击移位都要重算 trigger

package/dist/composer/hooks/useChipManager.d.ts

@@ -35,9 +35,13 @@ export interface UseChipManagerReturn {
      * `focus: false` 时插入后不把焦点交给编辑器。
      * 首屏还原 defaultValue / defaultChips 必须传 false：默认 focus() 会把
      * 页面滚动到编辑器（浏览器「聚焦元素进入视口」），导致进页面就跳位置。
+     *
+     * `caret: false` 时不主动改写 selection（后台预填用，避免抢走用户
+     * 在别处的光标）。单行路径由调用方传自己的 range，不受影响。
      */
     options?: {
         focus?: boolean;
+        caret?: boolean;
     }) => void;
     /** 移除已从 DOM 摘下的 chip 状态（cut / 选区删除后）。 */
     syncChipsAfterDomMutation: (editor: HTMLElement) => void;

package/dist/composer/hooks/useChipManager.js

@@ -16,7 +16,7 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
  */
 
 import { useCallback, useRef, useState } from 'react';
-import { createLineRoot, ensureLineRoots, forEachMarkerSegment, getCurrentLineRoot, LINE_ATTR_NAME, stripInvisibleChars, ZWSP } from "../utils";
+import { createLineRoot, ensureCaretAnchorAfter, ensureLineRoots, forEachMarkerSegment, getCurrentLineRoot, LINE_ATTR_NAME, stripInvisibleChars } from "../utils";
 
 /** chip 在 React 状态中的形态：data + 对应的 DOM host。 */
 
@@ -27,24 +27,6 @@ function createChipHost(data) {
   host.setAttribute('data-odn-composer-chip-host', '');
   return host;
 }
-
-/**
- * 在 host 后面垫一个「不进 value」的 ZWSP 文本锚点并返回它。
- *
- * chip 后面没有正文时（行尾 / 后面只剩派生 hint / 后面紧跟着另一个 chip），
- * caret 若只靠「元素偏移」落位，部分浏览器会把它带到结构块之后；垫一个只含
- * ZWSP 的文本节点，caret 始终有真实文本落点，而 `getPlainText` 会把整段剔掉，
- * 因此不会进 value / segments / 剪贴板。已有锚点直接复用，避免越积越多。
- */
-function ensureCaretAnchorAfter(host) {
-  var _tail$textContent, _tail$textContent2;
-  var parent = host.parentNode;
-  var tail = host.nextSibling;
-  var reusable = (tail === null || tail === void 0 ? void 0 : tail.nodeType) === Node.TEXT_NODE && ((_tail$textContent = tail.textContent) !== null && _tail$textContent !== void 0 ? _tail$textContent : '') !== '' && stripInvisibleChars((_tail$textContent2 = tail.textContent) !== null && _tail$textContent2 !== void 0 ? _tail$textContent2 : '') === '' ? tail : null;
-  var anchor = reusable !== null && reusable !== void 0 ? reusable : document.createTextNode(ZWSP);
-  if (!reusable) parent.insertBefore(anchor, tail);
-  return anchor;
-}
 function createCaretAnchorAtBoundary(parent, offset) {
   var _parent$childNodes, _parent$childNodes$sa;
   var len = parent.childNodes.length;
@@ -255,7 +237,7 @@ onAfterMutate) {
         }
 
         // caret 落「拼回点」——粘贴段末尾、原 caret 后内容的起点。
-        var sel = window.getSelection();
+        var sel = (options === null || options === void 0 ? void 0 : options.caret) === false ? null : window.getSelection();
         if (sel && lastLine) {
           var r = document.createRange();
           r.setStart(lastLine, caretBoundaryChildCount);
@@ -271,7 +253,7 @@ onAfterMutate) {
           _line.appendChild(lineFrags[_i]);
           editor.appendChild(_line);
         }
-        var _sel = window.getSelection();
+        var _sel = (options === null || options === void 0 ? void 0 : options.caret) === false ? null : window.getSelection();
         var _lastLine = editor.querySelector(":scope > [".concat(LINE_ATTR_NAME, "]:last-of-type"));
         if (_sel && _lastLine) {
           var _r = document.createRange();

package/dist/composer/index.d.ts

@@ -2,8 +2,10 @@ import React from 'react';
 import type { Attachment, ChipData, ComposerSegment, SendMeta, SkillItem } from '../_genui-types';
 import type { IconName } from '../icon';
 import { type SkillSlotProps } from '../skill-slot';
+import { type ComposerInsertOptions, type ComposerInsertPart, type ComposerInsertResult } from './insert';
 import type { ComposerParamPanelContext } from './param-panel';
 import './style';
+export type { ComposerInsertOptions, ComposerInsertPart, ComposerInsertResult, } from './insert';
 export type { ComposerParamPanelContext } from './param-panel';
 export type ComposerTool = 'attachment' | 'webSearch' | 'skill';
 export type ComposerVariant = 'full' | 'lite';
@@ -48,6 +50,38 @@ export interface ComposerRef {
      * 返回插入的 chip 实例 id，可用于后续 `updateChipData` 更新状态。
      */
     insertSkill: (skill: SkillItem) => string;
+    /**
+     * 命令式：插入一段内容，支持文本 / skill / 自定义 chip 混合，且只触发一次 onChange。
+     *
+     * 插入位置由 `options.position` 显式声明（当前仅支持 `'end'`）：忽略 caret，
+     * 始终落在已有内容末尾——适合 Welcome Card / 建议项 / 外部面板「把东西塞进
+     * 输入框」的场景。与 `insertSkill`（依赖当前 caret）互补。
+     *
+     * `parts` 也接受单个 part 或一个字符串（等价于单个 text part）。
+     *
+     * 约定：
+     * - **不自动补空格**：文本与 chip 的间隔由业务在 text part 里显式写。
+     * - `skill` 走与菜单插入相同的 chip 结构（含 `hint` / `initialState`）；
+     *   `initialState: 'pending'` 且提供 `renderParamPanel` 时自动打开参数面板
+     *   （`focus: false` 的后台预填不打开）。
+     * - `chip` 是逃生舱：mention / 自定义 kind / 已存草稿都可以直接传。
+     * - chip id 与编辑器已有 chip 冲突时自动换新 id，以返回的 `chipIds` 为准。
+     * - 受控 `value` 场景请在 onChange 内回写，与手动输入一致（否则一帧后会被
+     *   controlled sync 拉回旧值）。
+     *
+     * @example
+     * ```ts
+     * composerRef.current?.insertContent(
+     *   [
+     *     { type: 'text', text: '请基于这份数据' },
+     *     { type: 'skill', skill: reportSkill },
+     *     { type: 'text', text: '生成复盘报告' },
+     *   ],
+     *   { position: 'end' },
+     * );
+     * ```
+     */
+    insertContent: (parts: ComposerInsertPart | ComposerInsertPart[] | string, options: ComposerInsertOptions) => ComposerInsertResult;
     /**
      * 更新编辑器内指定 chip 的数据（partial merge）。
      * 典型用法：`updateChipData(chipId, { state: 'pending' })` 将 chip 置为待补充态。

package/dist/composer/index.js

@@ -1,9 +1,9 @@
 import _extends from "@babel/runtime/helpers/esm/extends";
 import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
-import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
 import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
 import _regeneratorRuntime from "@babel/runtime/helpers/esm/regeneratorRuntime";
 import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import _toConsumableArray from "@babel/runtime/helpers/esm/toConsumableArray";
 import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { SKILL_CATEGORY_ICON } from "../_genui-inline-ref";
@@ -18,23 +18,10 @@ import SkillSlot from "../skill-slot";
 import Tooltip from "../tooltip";
 import { COMPOSER_EDITOR_MAX_ROWS_PX, ComposerEditor } from "./editor";
 import { chipHasEditableParams, isMentionChip } from "./inline-ref";
+import { buildInsertPayload, createSkillChipData } from "./insert";
 import { rawValueToSegments, segmentsHasContent } from "./segments";
 import "./style";
 import { COMPOSER_SKILL_MENU_DENSITY_CAP_PX, filterSkillsByQuery, resolveComposerSkillMenuMaxHeight, resolveComposerSkillMenuWidth, shouldOpenSlashTriggerMenu } from "./utils";
-function createInvocationChipData(skill) {
-  return {
-    id: "skill-".concat(skill.id, "-").concat(Date.now().toString(36), "-").concat(Math.random().toString(36).slice(2, 6)),
-    label: skill.label,
-    icon: skill.icon,
-    kind: 'invocation',
-    state: skill.initialState,
-    refId: skill.id,
-    payload: {},
-    /* 提示文案随 chip 快照下来（而不是渲染时回查技能目录）：
-     * 草稿用 defaultValue + defaultChips 还原时，目录可能已经变了。 */
-    hint: skill.hint
-  };
-}
 var TOOL_BTN_ACTIVE = 'color-mix(in srgb, var(--odn-color-brand-6) 10%, transparent)';
 var DEFAULT_ACCEPT = 'image/*,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.txt,.md,.csv,.json,.xml,.html,.css,.js,.ts,.jsx,.tsx,.py,.java,.go,.rs,.c,.cpp,.zip,.rar,.7z';
 function formatSizeMb(bytes) {
@@ -322,12 +309,49 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       },
       insertSkill: function insertSkill(skill) {
         var _editorRef$current8, _editorRef$current9;
-        var data = createInvocationChipData(skill);
+        var data = createSkillChipData(skill);
         (_editorRef$current8 = editorRef.current) === null || _editorRef$current8 === void 0 || _editorRef$current8.insertChip(data);
         (_editorRef$current9 = editorRef.current) === null || _editorRef$current9 === void 0 || _editorRef$current9.focus();
         if (skill.initialState === 'pending') openParamPanel(data.id);
         return data.id;
       },
+      insertContent: function insertContent(parts, options) {
+        var editor = editorRef.current;
+        if (!editor) return {
+          chipIds: [],
+          value: ''
+        };
+
+        /* 类型层 position 目前只开 'end'；这里兜住 JS / any 调用方，
+         * 避免未来扩 'caret' 前被静默当成末尾处理。 */
+        var position = options === null || options === void 0 ? void 0 : options.position;
+        if (process.env.NODE_ENV !== 'production' && position && position !== 'end') {
+          // eslint-disable-next-line no-console
+          console.warn("[Composer] insertContent \u5F53\u524D\u4EC5\u652F\u6301 position: \"end\"\uFF0C\u6536\u5230\u300C".concat(position, "\u300D\uFF0C\u5DF2\u6309\u672B\u5C3E\u63D2\u5165\u5904\u7406\u3002"));
+        }
+        var payload = buildInsertPayload(parts, editor.getChips());
+        if (!payload) {
+          return {
+            chipIds: [],
+            value: editor.getValue()
+          };
+        }
+        editor.insertSerializedAtEnd(payload.value, payload.chips, options);
+
+        /* 与 insertSkill 对齐：pending skill 插入后自动打开参数面板。
+         * 一次 insertContent 可能带多个 pending，只开最后一个（用户最后看到的那块）。
+         * `focus: false` 是后台预填语义，不主动弹面板。 */
+        var pendingChip = _toConsumableArray(payload.chips).reverse().find(function (chip) {
+          return chip.state === 'pending' && !isMentionChip(chip);
+        });
+        if (pendingChip && (options === null || options === void 0 ? void 0 : options.focus) !== false) {
+          openParamPanel(pendingChip.id);
+        }
+        return {
+          chipIds: payload.chipIds,
+          value: editor.getValue()
+        };
+      },
       updateChipData: function updateChipData(id, patch) {
         var _editorRef$current10;
         return (_editorRef$current10 = editorRef.current) === null || _editorRef$current10 === void 0 ? void 0 : _editorRef$current10.updateChipData(id, patch);
@@ -644,7 +668,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
    * source = 'trigger' → editor.replaceTriggerWithChip 替换 `/` + query 整段
    * 任一入口选完后都关闭对应 menu。chip data 用 skill.id + 一次性实例 id。 */
   var handleSelectSkill = useCallback(function (skill, source) {
-    var data = createInvocationChipData(skill);
+    var data = createSkillChipData(skill);
     if (source === 'trigger') {
       var _editorRef$current16;
       (_editorRef$current16 = editorRef.current) === null || _editorRef$current16 === void 0 || _editorRef$current16.replaceTriggerWithChip(data);

package/dist/composer/insert.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Composer · 命令式插入内容（insertContent）
+ *
+ * 业务场景：Welcome Card / 建议项 / 外部面板希望在「已有输入内容的末尾」一次性
+ * 塞入文本、skill chip 等，而不是依赖当前 caret（用户可能停在任意位置）。
+ *
+ * 职责边界：
+ * - 本模块只把 parts 编成 `{ value, chips }`（含 marker 的 raw value + 新 chip
+ *   快照），真正的 DOM 插入由 editor 的 `insertSerializedAtEnd` →
+ *   `insertSerializedAtRange` 完成——与粘贴 / 草稿还原共用同一条链路，
+ *   因此 onChange / 派生 hint / 高度 / trigger 只会重算一次。
+ * - **不自动补空格**：文本与 chip 之间的间隔由业务自己在 text part 里写，
+ *   避免 value / segments 里出现用户没输入过的字符（与插入 skill 的既有约定一致）。
+ */
+import type { ChipData, SkillItem } from '../_genui-types';
+/**
+ * insertContent 支持的内容片段：
+ * - `text`：普通文本（支持 `\n`；`\r\n` 会归一成 `\n`）
+ * - `skill`：按技能目录的条目生成一个 invocation chip（含 hint / initialState）
+ * - `chip`：逃生舱，业务自带完整 chip 数据（mention / 自定义 kind / 已存草稿）
+ */
+export type ComposerInsertPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'skill';
+    skill: SkillItem;
+} | {
+    type: 'chip';
+    chip: ChipData;
+};
+export interface ComposerInsertOptions {
+    /**
+     * 插入位置。
+     *
+     * 当前仅支持 `'end'`（已有内容末尾）；`'caret'` 预留在同一入口，
+     * 未来扩展时**不会改变现有调用**，`'end'` 的语义也保持不变。
+     */
+    position: 'end';
+    /**
+     * 插入后是否聚焦编辑器，并把 caret 落到新内容末尾（同时滚到可见区）。
+     * 传 `false` 时只改内容，不动焦点、不滚动（如后台预填草稿）。
+     * @default true
+     */
+    focus?: boolean;
+}
+export interface ComposerInsertResult {
+    /** 实际插入的 chip id，顺序与 parts 中 chip 出现顺序一致；id 冲突时已换新 */
+    chipIds: string[];
+    /** 插入后的 raw value（含 marker），等价于本次 onChange 第一参 */
+    value: string;
+}
+/** buildInsertPayload 的产物：可直接交给 editor 插入。 */
+export interface ComposerInsertPayload {
+    /** 待插入的 raw value（唯一数据源：marker 与 text 交替） */
+    value: string;
+    /** 待插入 chip 的完整数据（只含本次新增，不含编辑器里已有的） */
+    chips: ChipData[];
+    /** 本次实际使用的 chip id（与 chips 一一对应） */
+    chipIds: string[];
+}
+/**
+ * 按 SkillItem 生成 chip 实例数据。
+ *
+ * hint 随 chip 快照下来（而不是渲染时回查技能目录）：草稿用
+ * `defaultValue + defaultChips` 还原时，目录可能已经变了。
+ */
+export declare function createSkillChipData(skill: SkillItem): ChipData;
+/**
+ * 把 parts 编成一次插入所需的 raw value + chips。
+ *
+ * 返回 `null` 表示没有可插入内容（空数组 / 全空文本），调用方应直接 no-op，
+ * 不要触发 onChange。
+ */
+export declare function buildInsertPayload(parts: ComposerInsertPart | ComposerInsertPart[] | string, existingChips?: readonly ChipData[]): ComposerInsertPayload | null;

package/dist/composer/insert.js

@@ -0,0 +1,130 @@
+import _objectSpread from "@babel/runtime/helpers/esm/objectSpread2";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+/**
+ * Composer · 命令式插入内容（insertContent）
+ *
+ * 业务场景：Welcome Card / 建议项 / 外部面板希望在「已有输入内容的末尾」一次性
+ * 塞入文本、skill chip 等，而不是依赖当前 caret（用户可能停在任意位置）。
+ *
+ * 职责边界：
+ * - 本模块只把 parts 编成 `{ value, chips }`（含 marker 的 raw value + 新 chip
+ *   快照），真正的 DOM 插入由 editor 的 `insertSerializedAtEnd` →
+ *   `insertSerializedAtRange` 完成——与粘贴 / 草稿还原共用同一条链路，
+ *   因此 onChange / 派生 hint / 高度 / trigger 只会重算一次。
+ * - **不自动补空格**：文本与 chip 之间的间隔由业务自己在 text part 里写，
+ *   避免 value / segments 里出现用户没输入过的字符（与插入 skill 的既有约定一致）。
+ */
+
+import { createMarker, stripInvisibleChars } from "./utils";
+
+/**
+ * insertContent 支持的内容片段：
+ * - `text`：普通文本（支持 `\n`；`\r\n` 会归一成 `\n`）
+ * - `skill`：按技能目录的条目生成一个 invocation chip（含 hint / initialState）
+ * - `chip`：逃生舱，业务自带完整 chip 数据（mention / 自定义 kind / 已存草稿）
+ */
+
+/** buildInsertPayload 的产物：可直接交给 editor 插入。 */
+
+var randomSuffix = function randomSuffix() {
+  return "".concat(Date.now().toString(36), "-").concat(Math.random().toString(36).slice(2, 6));
+};
+
+/**
+ * 按 SkillItem 生成 chip 实例数据。
+ *
+ * hint 随 chip 快照下来（而不是渲染时回查技能目录）：草稿用
+ * `defaultValue + defaultChips` 还原时，目录可能已经变了。
+ */
+export function createSkillChipData(skill) {
+  return {
+    id: "skill-".concat(skill.id, "-").concat(randomSuffix()),
+    label: skill.label,
+    icon: skill.icon,
+    kind: 'invocation',
+    state: skill.initialState,
+    refId: skill.id,
+    payload: {},
+    hint: skill.hint
+  };
+}
+
+/**
+ * 文本预处理：
+ * - `\r\n` / `\r` → `\n`，交给行模型拆行
+ * - 剔除零宽 marker 字符，避免业务文案里混入 `\u200b\u2063` 后被解析成 chip
+ * - 不 trim：首尾空格是业务显式传入的内容，库不替它做决定
+ */
+function normalizeText(text) {
+  return stripInvisibleChars(text.replace(/\r\n?/g, '\n'));
+}
+
+/**
+ * chip id 必须唯一：marker、Portal key、removeChip / updateChipData 都靠它定位。
+ * 冲突时换一个新 id，并在开发期提示——返回值里的 `chipIds` 才是最终生效的 id。
+ */
+function resolveUniqueChipId(chip, usedIds) {
+  if (chip.id && !usedIds.has(chip.id)) return chip.id;
+  var nextId = "".concat(chip.id || 'chip', "-").concat(randomSuffix());
+  while (usedIds.has(nextId)) nextId = "chip-".concat(randomSuffix());
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line no-console
+    console.warn("[Composer] insertContent \u6536\u5230\u91CD\u590D\u6216\u4E3A\u7A7A\u7684 chip id\u300C".concat(chip.id, "\u300D\uFF0C") + "\u5DF2\u6539\u7528\u300C".concat(nextId, "\u300D\u3002\u8BF7\u4EE5\u8FD4\u56DE\u7684 chipIds \u4E3A\u51C6\u3002"));
+  }
+  return nextId;
+}
+
+/**
+ * 把 parts 编成一次插入所需的 raw value + chips。
+ *
+ * 返回 `null` 表示没有可插入内容（空数组 / 全空文本），调用方应直接 no-op，
+ * 不要触发 onChange。
+ */
+export function buildInsertPayload(parts) {
+  var existingChips = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : [];
+  var list = typeof parts === 'string' ? [{
+    type: 'text',
+    text: parts
+  }] : Array.isArray(parts) ? parts : [parts];
+  var usedIds = new Set(existingChips.map(function (chip) {
+    return chip.id;
+  }));
+  var chips = [];
+  var chipIds = [];
+  var value = '';
+  var _iterator = _createForOfIteratorHelper(list),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var part = _step.value;
+      if (!part || _typeof(part) !== 'object') continue;
+      if (part.type === 'text') {
+        if (typeof part.text === 'string') value += normalizeText(part.text);
+        continue;
+      }
+      var chip = null;
+      if (part.type === 'skill') {
+        chip = part.skill ? createSkillChipData(part.skill) : null;
+      } else if (part.chip) {
+        chip = _objectSpread({}, part.chip);
+      }
+      if (!chip) continue;
+      chip.id = resolveUniqueChipId(chip, usedIds);
+      usedIds.add(chip.id);
+      chips.push(chip);
+      chipIds.push(chip.id);
+      value += createMarker(chip.id);
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  if (!value) return null;
+  return {
+    value: value,
+    chips: chips,
+    chipIds: chipIds
+  };
+}

package/dist/composer/utils.d.ts

@@ -113,6 +113,15 @@ export declare function getPlainText(editor: HTMLElement, chipIdAttr?: string):
  * 空格 / 全角空格也算"已输入"，只要文本非空就该收起 placeholder。
  */
 export declare function isEditorEmpty(editor: HTMLElement, chipIdAttr?: string): boolean;
+/**
+ * 在 host 后面垫一个「不进 value」的 ZWSP 文本锚点并返回它。
+ *
+ * chip 后面没有正文时（行尾 / 后面只剩派生 hint / 后面紧跟着另一个 chip），
+ * caret 若只靠「元素偏移」落位，部分浏览器会把它带到结构块之后；垫一个只含
+ * ZWSP 的文本节点，caret 始终有真实文本落点，而 `getPlainText` 会把整段剔掉，
+ * 因此不进 value / segments / 剪贴板。已有锚点直接复用，避免越积越多。
+ */
+export declare function ensureCaretAnchorAfter(host: Node): Text;
 /**
  * 清理 contenteditable 删字后的幽灵节点：空 text、仅 chip 时的占位 <br>。
  * 避免「文字 + invocation」删光文字后出现多余换行，以及 caret 卡在 chip 后误删 invocation。

package/dist/composer/utils.js

@@ -368,6 +368,24 @@ export function isEditorEmpty(editor) {
  * chip 前的 leading <br> / 空 text node。
  * ──────────────────────────────────────────────────────────────────── */
 
+/**
+ * 在 host 后面垫一个「不进 value」的 ZWSP 文本锚点并返回它。
+ *
+ * chip 后面没有正文时（行尾 / 后面只剩派生 hint / 后面紧跟着另一个 chip），
+ * caret 若只靠「元素偏移」落位，部分浏览器会把它带到结构块之后；垫一个只含
+ * ZWSP 的文本节点，caret 始终有真实文本落点，而 `getPlainText` 会把整段剔掉，
+ * 因此不进 value / segments / 剪贴板。已有锚点直接复用，避免越积越多。
+ */
+export function ensureCaretAnchorAfter(host) {
+  var _tail$textContent, _tail$textContent2;
+  var parent = host.parentNode;
+  var tail = host.nextSibling;
+  var reusable = (tail === null || tail === void 0 ? void 0 : tail.nodeType) === Node.TEXT_NODE && ((_tail$textContent = tail.textContent) !== null && _tail$textContent !== void 0 ? _tail$textContent : '') !== '' && stripInvisibleChars((_tail$textContent2 = tail.textContent) !== null && _tail$textContent2 !== void 0 ? _tail$textContent2 : '') === '' ? tail : null;
+  var anchor = reusable !== null && reusable !== void 0 ? reusable : document.createTextNode(ZWSP);
+  if (!reusable) parent.insertBefore(anchor, tail);
+  return anchor;
+}
+
 /**
  * 清理 contenteditable 删字后的幽灵节点：空 text、仅 chip 时的占位 <br>。
  * 避免「文字 + invocation」删光文字后出现多余换行，以及 caret 卡在 chip 后误删 invocation。

package/dist/index.d.ts

@@ -63,6 +63,7 @@ export { CHAT_LIST_PINNED_ID, CHAT_LIST_UNGROUPED_ID, default as ChatList, match
 export { CLARIFY_DOCK_MAX_OPTIONS, CLARIFY_DOCK_SKIPPED_LABEL, CLARIFY_DOCK_SKIPPED_VALUE, ClarifyDockPanel, ClarifyDockTrigger, clarifyDockLayoutId, parseClarifyBoundDate, toISODate, useClarifyDockState, type ClarifyDockAnswerItem, type ClarifyDockHostMessage, type ClarifyDockMessageState, type ClarifyDockPanelProps, type ClarifyDockQuestion, type ClarifyDockResolvePayload, type ClarifyDockSpec, type ClarifyDockState, type ClarifyDockTriggerProps, type ClarifyInput, type ClarifyOption, } from './clarify-dock';
 export { default as CodeBlock, type CodeBlockProps } from './code-block';
 export { default as Composer, type ComposerProps, type ComposerRef, type ComposerSkillSlotProps, type ComposerTool, type ComposerToolConfig, } from './composer';
+export type { ComposerInsertOptions, ComposerInsertPart, ComposerInsertResult, } from './composer/insert';
 export { type ComposerParamPanelContext } from './composer/param-panel';
 export { default as ErrorBlock, type ErrorBlockProps } from './error-block';
 export { default as Fab, type FabProps } from './fab';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "one-design-next",
-  "version": "0.0.114",
+  "version": "0.0.115",
   "description": "One Design Next from TAD@tencent.com",
   "license": "MIT",
   "type": "module",