one-design-next 0.0.114 → 0.0.116

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_ACCEPT_ATTR, COMPOSER_HINT_ACCEPT_SELECTOR, 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,137 @@ 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;
+};
+
+/**
+ * hint 末尾的「TAB 采纳」小块：点它 = 按 Tab 采纳这段模板文案。
+ *
+ * 与 hint 文本是同级节点（见 `COMPOSER_HINT_ACCEPT_ATTR` 的说明），由
+ * `syncHintNode` 一起插入 / 移除，不进 value / 剪贴板 / segments。
+ * 视觉在 `style/index.scss`（`[data-odn-composer-hint-accept]`）。
+ */
+var createHintAcceptNode = function createHintAcceptNode() {
+  var accept = document.createElement('span');
+  accept.setAttribute(COMPOSER_HINT_ACCEPT_ATTR, '');
+  accept.contentEditable = 'false';
+  /* 刻意不加 role="button" / aria-label / title：
+   * - 它不可聚焦、也没有 Enter/Space 激活逻辑，挂 button 语义等于给读屏用户
+   *   一个按不动的控件（无障碍反而变成障碍）。真正的键盘路径就是它写着的
+   *   Tab 键本身，可见文案已经说清动作。
+   * - aria-label 会盖掉可见文案，反而违反「可见标签即无障碍名」。
+   * - title 是浏览器原生 tooltip：延迟出现、样式不可控、会盖住灰字。 */
+
+  var key = document.createElement('span');
+  key.setAttribute('data-odn-composer-hint-accept-key', '');
+  key.textContent = 'TAB';
+  var label = document.createElement('span');
+  label.setAttribute('data-odn-composer-hint-accept-label', '');
+  label.textContent = '采纳';
+  accept.append(key, label);
+  return accept;
+};
+
+/**
+ * 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;
@@ -256,12 +387,18 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
    * 就不存在了，caret 只能落在整个 host 之后（= 提示文本末尾）。
    *
    * 它不归 React 管（editor 的 children 由 contenteditable 自治），由 fireChange
-   * 按结构谓词增删/挪位；`getPlainText` 会整棵子树跳过，所以不进 value / 剪贴板。 */
+   * 按结构谓词增删/挪位；`getPlainText` 会整棵子树跳过，所以不进 value / 剪贴板。
+   *
+   * 末尾的「TAB 采纳」小块是 hint 文本的**兄弟节点**（不是子节点）：hint 的
+   * textContent 必须保持纯提示文案（采纳时直接落成正文，调试面板也按它读）。 */
   var hintNodeRef = useRef(null);
+  var hintAcceptNodeRef = useRef(null);
   var removeHintNode = useCallback(function () {
-    var _hintNodeRef$current;
+    var _hintNodeRef$current, _hintAcceptNodeRef$cu;
     (_hintNodeRef$current = hintNodeRef.current) === null || _hintNodeRef$current === void 0 || _hintNodeRef$current.remove();
     hintNodeRef.current = null;
+    (_hintAcceptNodeRef$cu = hintAcceptNodeRef.current) === null || _hintAcceptNodeRef$cu === void 0 || _hintAcceptNodeRef$cu.remove();
+    hintAcceptNodeRef.current = null;
   }, []);
   var syncHintNode = useCallback(function (target) {
     var _Array$from$find, _blankTail;
@@ -281,6 +418,11 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       hintNodeRef.current = node;
     }
     if (node.textContent !== target.text) node.textContent = target.text;
+    var accept = hintAcceptNodeRef.current;
+    if (!accept || !accept.isConnected) {
+      accept = createHintAcceptNode();
+      hintAcceptNodeRef.current = accept;
+    }
 
     /* 落位：命中 chip 之后、**紧随其后的不可见锚点文本（ZWSP）之后**。
      *
@@ -295,8 +437,9 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     var cur = host.nextSibling;
     while (cur) {
       var _cur$textContent;
-      // 跳过 hint 自身：上一轮若把它排到了锚点前面，这里顺手挪回末尾
-      if (cur === node) {
+      // 跳过 hint 自身与它的「TAB 采纳」小块：上一轮若排到了锚点前面，
+      // 这里顺手挪回末尾
+      if (cur === node || cur === accept) {
         cur = cur.nextSibling;
         continue;
       }
@@ -323,6 +466,12 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     if (node.parentNode !== parent || node.previousSibling !== anchor) {
       parent.insertBefore(node, anchor.nextSibling);
     }
+    /* 「TAB 采纳」小块紧跟 hint 文案之后（同一套行内流），顺序必须是
+     * hint → 小块：caret 的合法落点只到 hint 之前，块本身
+     * contentEditable=false，不会成为落点。 */
+    if (accept.parentNode !== parent || accept.previousSibling !== node) {
+      parent.insertBefore(accept, node.nextSibling);
+    }
   }, [removeHintNode]);
 
   /** 把 caret 直接落到 hint 之前（= chip 右侧）；没有 hint 时不动。 */
@@ -427,26 +576,45 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
   recomputeTriggerRef.current = recomputeTrigger;
 
   /* ─────────────────────────────────────
-   * Tab 采纳 hint
+   * 采纳 hint（Tab / 点击「TAB 采纳」小块）
    *
    * hint 只是结构投影（不进 value）；caret 恰好停在 chip 与 hint 之间
    * （= 内容末尾）时按 Tab，表示用户接受这段模板，于是把提示文案落成正文：
    * chip 之后出现内容 → 结构谓词不再命中 → 灰字自动移除，onChange 抛出的
    * value 里带上这段文案，与用户自己敲进去的效果一致。
+   *
+   * 鼠标点末尾的「TAB 采纳」小块走**同一条链路**，只是带 `force`：
+   * 不要求点击前 caret 就停在 hint 之前，先把 caret 归位到 chip 右侧再落。
    * ───────────────────────────────────── */
-  var acceptHintAsText = useCallback(function () {
+  var acceptHintAsText = useCallback(function (options) {
     var _hint$textContent;
     var el = editorRef.current;
     var hint = hintNodeRef.current;
     var sel = window.getSelection();
-    if (!el || !hint || !hint.isConnected || !sel || sel.rangeCount === 0) {
-      return false;
+    if (!el || !hint || !hint.isConnected || !sel) return false;
+    var range;
+    if (options !== null && options !== void 0 && options.force) {
+      /* 点击路径：mousedown 已被 preventDefault，焦点 / caret 都还没进来，
+       * 先聚焦再把 caret 落到 hint 之前（= 内容末尾），避免原生落点乱跳。 */
+      el.focus({
+        preventScroll: true
+      });
+      var target = caretBeforeHintIn(el);
+      if (!target) return false;
+      range = document.createRange();
+      range.setStart(target.node, target.offset);
+      range.collapse(true);
+      sel.removeAllRanges();
+      sel.addRange(range);
+      lastEditorRangeRef.current = range.cloneRange();
+    } else {
+      if (sel.rangeCount === 0) return false;
+      range = sel.getRangeAt(0);
+      if (!range.collapsed || !el.contains(range.startContainer)) return false;
+      /* 只认「chip 之后、hint 之前」这一个落点；caret 在别处时 Tab 仍归浏览器，
+       * 避免在任意位置误吞焦点切换。 */
+      if (!isCaretBeforeHint(range, el)) return false;
     }
-    var range = sel.getRangeAt(0);
-    if (!range.collapsed || !el.contains(range.startContainer)) return false;
-    /* 只认「chip 之后、hint 之前」这一个落点；caret 在别处时 Tab 仍归浏览器，
-     * 避免在任意位置误吞焦点切换。 */
-    if (!isCaretBeforeHint(range, el)) return false;
     var text = (_hint$textContent = hint.textContent) !== null && _hint$textContent !== void 0 ? _hint$textContent : '';
     if (!text) return false;
 
@@ -463,6 +631,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       caret.collapse(true);
       sel.removeAllRanges();
       sel.addRange(caret);
+      lastEditorRangeRef.current = caret.cloneRange();
     }
     fireChange();
     recomputeTrigger();
@@ -536,6 +705,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 +754,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
@@ -931,6 +1127,17 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     if (e.button !== 0 || disabled) return;
     // shift+click 是扩选，不劫持
     if (e.shiftKey) return;
+
+    /* 「TAB 采纳」小块：点它等价于按 Tab（同一条采纳链路），且不要求点击前
+     * caret 就停在 hint 之前。在 mousedown 阶段接管 + preventDefault，
+     * 原生 caret 一帧都不会落到 hint 之后。 */
+    if (e.target instanceof Element && e.target.closest(COMPOSER_HINT_ACCEPT_SELECTOR)) {
+      e.preventDefault();
+      acceptHintAsText({
+        force: true
+      });
+      return;
+    }
     var el = editorRef.current;
     var hint = hintNodeRef.current;
     if (!el || !hint || !hint.isConnected) return;
@@ -961,7 +1168,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     });
     placeCaretBeforeHint();
     requestScrollCaretIntoView();
-  }, [disabled, handlePointerInput, placeCaretBeforeHint, requestScrollCaretIntoView]);
+  }, [acceptHintAsText, disabled, handlePointerInput, placeCaretBeforeHint, requestScrollCaretIntoView]);
   var writeClipboardPayload = useCallback(function (e, payload) {
     if (!payload) return false;
     e.clipboardData.setData(COMPOSER_CLIPBOARD_MIME, JSON.stringify(payload));

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/style/index.css

@@ -309,6 +309,74 @@
   white-space: pre-wrap;
 }
 
+/* ------------------------------------------------------------------
+ * hint 末尾的「TAB 采纳」小块（点击 = 按 Tab 采纳，见 editor.tsx）
+ *
+ * 与 hint 文本是同级节点，一起增删。它不是正文：contentEditable=false、
+ * getPlainText 整棵跳过，点它走 force 版 acceptHintAsText。
+ * 尺寸对齐 Figma 9857:75425（62 × 22 / 圆角 6 / 内层键帽 28 × 16）：
+ *   - 编辑器固定 font-size 14 / line-height 24，块高 22 + top 1 → 视觉居中
+ *     且不撑高行盒（改编辑器行高时要同步调这个 1px）
+ *   - 底色 black-2(5%)、键帽 bg-elevated + black-5(12%) 1px 描边
+ * ----------------------------------------------------------------- */
+[data-odn-composer] [data-odn-composer-hint-accept] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 3px;
+  box-sizing: border-box;
+  height: 22px;
+  margin: 1px 0 0 4px;
+  padding: 0 4px 0 3px;
+  border-radius: 6px;
+  background: var(--odn-color-black-2);
+  color: var(--odn-color-solid-black-9);
+  font-size: 12px;
+  line-height: 20px;
+  white-space: nowrap;
+  vertical-align: top;
+  cursor: pointer;
+  user-select: none;
+  pointer-events: auto;
+  transition: background 0.15s ease-out, color 0.15s ease-out;
+  /* 底部 5% 太淡，hover 抬到 12%（约 2.4 倍）并加深文字，让「可点」更明确；
+   * active 再深一档。 */
+}
+[data-odn-composer] [data-odn-composer-hint-accept]:hover {
+  background: var(--odn-color-black-5);
+  color: var(--odn-color-solid-black-10);
+}
+[data-odn-composer] [data-odn-composer-hint-accept]:active {
+  background: var(--odn-color-black-6);
+}
+
+[data-odn-composer] [data-odn-composer-hint-accept-key] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  height: 16px;
+  padding: 0 4px;
+  border: 1px solid var(--odn-color-black-5);
+  border-radius: 4px;
+  /* 与 composer box 同为「浮在底层之上的面」，跟随主题变量而不是写死白色 */
+  background: var(--odn-color-bg-elevated);
+  font-size: 10px;
+  line-height: 10px;
+  letter-spacing: 0;
+}
+
+[data-odn-composer] [data-odn-composer-hint-accept-label] {
+  font-size: 12px;
+  line-height: 20px;
+}
+
+/* 禁用态：hint 仍按内容结构展示，但小块不可点（与 editor 冻结一致） */
+[data-odn-composer] [data-odn-composer-editor][data-odn-composer-editor-disabled] [data-odn-composer-hint-accept] {
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
 /* ------------------------------------------------------------------
  * Block 行模型（caret-rewrite step 1/5）
  *   editor 直接子节点都是 [data-composer-line] div，每行渲染为独立 block。

package/dist/composer/utils.d.ts

@@ -22,6 +22,15 @@ export declare const LINE_ATTR_NAME = "data-composer-line";
  */
 export declare const COMPOSER_HINT_ATTR = "data-odn-composer-skill-hint";
 export declare const COMPOSER_HINT_SELECTOR = "[data-odn-composer-skill-hint]";
+/**
+ * 派生 hint 末尾的「TAB 采纳」小块（可点击采纳）。
+ *
+ * 与 hint 文本是**兄弟节点**（不是子节点）：hint 自身的 `textContent` 必须
+ * 保持纯提示文案——采纳时直接把这段文字落成正文，且 `getPlainText` /
+ * 调试面板都按 textContent 读它。小块同样不是正文，遍历时整棵跳过。
+ */
+export declare const COMPOSER_HINT_ACCEPT_ATTR = "data-odn-composer-hint-accept";
+export declare const COMPOSER_HINT_ACCEPT_SELECTOR = "[data-odn-composer-hint-accept]";
 /** 是否是行容器。 */
 export declare function isLineRoot(node: Node | null | undefined): node is HTMLDivElement;
 /** 创建一个新的空行容器。 */
@@ -113,6 +122,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

@@ -39,6 +39,16 @@ export var LINE_ATTR_NAME = 'data-composer-line';
 export var COMPOSER_HINT_ATTR = 'data-odn-composer-skill-hint';
 export var COMPOSER_HINT_SELECTOR = "[".concat(COMPOSER_HINT_ATTR, "]");
 
+/**
+ * 派生 hint 末尾的「TAB 采纳」小块（可点击采纳）。
+ *
+ * 与 hint 文本是**兄弟节点**（不是子节点）：hint 自身的 `textContent` 必须
+ * 保持纯提示文案——采纳时直接把这段文字落成正文，且 `getPlainText` /
+ * 调试面板都按 textContent 读它。小块同样不是正文，遍历时整棵跳过。
+ */
+export var COMPOSER_HINT_ACCEPT_ATTR = 'data-odn-composer-hint-accept';
+export var COMPOSER_HINT_ACCEPT_SELECTOR = "[".concat(COMPOSER_HINT_ACCEPT_ATTR, "]");
+
 /** 是否是行容器。 */
 export function isLineRoot(node) {
   var _hasAttribute, _ref;
@@ -292,8 +302,8 @@ export function getPlainText(editor) {
   var out = '';
   var visit = function visit(node) {
     if (node instanceof HTMLElement) {
-      // 派生 hint 整棵子树都不是正文，直接跳过（含其内部文本节点）
-      if (node.hasAttribute(COMPOSER_HINT_ATTR)) return;
+      // 派生 hint（含末尾的「TAB 采纳」小块）整棵子树都不是正文，直接跳过
+      if (node.hasAttribute(COMPOSER_HINT_ATTR) || node.hasAttribute(COMPOSER_HINT_ACCEPT_ATTR)) return;
       var id = node.dataset[chipIdAttr];
       if (id) {
         out += createMarker(id);
@@ -368,6 +378,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/dist/skill-slot/index.js

@@ -7,6 +7,7 @@ import Icon from "../icon";
 import Input from "../input";
 import Popover from "../popover";
 import { highlightQueryText } from "../stream-text/highlight-query-text";
+import Tooltip from "../tooltip";
 import "./style";
 function skillMatchesQuery(skill, query) {
   var _skill$description;
@@ -367,8 +368,15 @@ export var SkillSlot = /*#__PURE__*/forwardRef(function SkillSlot(_ref2, ref) {
   };
   var renderBarItem = function renderBarItem(skill) {
     var disabled = !!skill.disabled;
-    var barButton = /*#__PURE__*/React.createElement("button", {
+
+    /* bar 无行内描述：整条 bar 由外层 Tooltip.Group 共用一层浮层（暗色，见 style）。
+     * 这里只把「本项的描述」交给 Group，hover 绑定由 Group 自己挂到 button 上。 */
+    return /*#__PURE__*/React.createElement(Tooltip, {
       key: skill.id,
+      popup: skill.description ? /*#__PURE__*/React.createElement("span", {
+        "data-odn-skill-slot-desc-full": true
+      }, skill.description) : null
+    }, /*#__PURE__*/React.createElement("button", {
       type: "button",
       "data-odn-skill-slot-item": true,
       "data-odn-skill-slot-item-disabled": disabled || undefined,
@@ -379,21 +387,8 @@ export var SkillSlot = /*#__PURE__*/forwardRef(function SkillSlot(_ref2, ref) {
       }
     }, /*#__PURE__*/React.createElement(Icon, {
       name: skill.icon,
-      size: 14
-    }), skill.label);
-
-    /* bar 无行内描述：整颗 chip hover 0.5s 后向上 Popover 出全文 */
-    if (skill.description) {
-      return /*#__PURE__*/React.createElement(Popover, {
-        key: skill.id,
-        placement: "top",
-        mouseEnterDelay: 0.5,
-        popup: /*#__PURE__*/React.createElement("span", {
-          "data-odn-skill-slot-desc-full": true
-        }, skill.description)
-      }, barButton);
-    }
-    return barButton;
+      size: 16
+    }), skill.label));
   };
   var listBody = skills.map(function (skill, index) {
     if (variant === 'card') return renderCardItem(skill);
@@ -461,10 +456,27 @@ export var SkillSlot = /*#__PURE__*/forwardRef(function SkillSlot(_ref2, ref) {
   } : {}), variant !== 'menu' && itemWidth !== undefined && itemWidth !== null ? {
     '--odn-skill-slot-item-width': "".concat(itemWidth, "px")
   } : {}), style);
-  if (variant !== 'menu') {
+
+  /* bar：整条 bar 是一组 Tooltip（与 preview-panel 右上角按钮同款手感）——
+   * 共用一层浮层，已展开时在块之间横移是 0 延迟换文案 + 浮层跟着滑，
+   * 移出整组 200ms 后才收起，不会一块一块地闪断。
+   * 容器本身就是 Tooltip.Group 的 Tag，data-* / className / style 一并落上去。 */
+  if (variant === 'bar') {
+    return /*#__PURE__*/React.createElement(Tooltip.Group, {
+      as: "div",
+      "data-odn-skill-slot": true,
+      "data-odn-skill-slot-variant": "bar",
+      className: className,
+      style: rootStyle,
+      placement: "top",
+      mouseEnterDelay: 0.1,
+      popupClassName: "odn-skill-slot-bar-popup"
+    }, listBody);
+  }
+  if (variant === 'card') {
     return /*#__PURE__*/React.createElement("div", {
       "data-odn-skill-slot": true,
-      "data-odn-skill-slot-variant": variant,
+      "data-odn-skill-slot-variant": "card",
       className: className,
       style: rootStyle
     }, listBody);

package/dist/skill-slot/style/index.css

@@ -237,39 +237,71 @@
   margin: 0;
 }
 
-/* ---- variant: bar ---- */
+/* ---- variant: bar ----
+ * 白底胶囊 chip：999 圆角，14/22 文案 + 16 icon，块间距 12。
+ * 设计稿：默认态**无描边**（描边在稿里是隐藏的），hover 才浮出黑-3 细描边，
+ * 底色/文字不变——所以预置 1px 透明描边占位，避免 hover 时宽度跳 2px。 */
 [data-odn-skill-slot][data-odn-skill-slot-variant=bar] {
   display: flex;
   flex-wrap: wrap;
-  gap: 8px;
+  gap: 12px;
 }
 
 [data-odn-skill-slot][data-odn-skill-slot-variant=bar] [data-odn-skill-slot-item] {
   display: inline-flex;
   align-items: center;
-  gap: 6px;
-  height: 32px;
+  gap: 4px;
+  height: 36px;
   padding: 0 12px;
-  border-radius: var(--odn-border-radius);
-  border: 1px solid var(--odn-color-black-6);
-  background: var(--odn-color-bg-elevated);
-  font-size: 13px;
-  color: var(--odn-color-black-10);
+  border-radius: 999px;
+  border: 1px solid transparent;
+  background: var(--odn-color-white);
+  box-sizing: border-box;
+  /* 不参与压缩：容器放不下就整块换行。否则窄容器里 flex 会把块挤到
+   * 比文案还窄，14/22 的文案折成两行、溢出固定 36px 的胶囊。 */
+  flex: 0 0 auto;
+  white-space: nowrap;
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+  color: var(--odn-color-black-12);
   transition: border-color 0.15s, background 0.15s, color 0.15s;
 }
 [data-odn-skill-slot][data-odn-skill-slot-variant=bar] [data-odn-skill-slot-item]:not([data-odn-skill-slot-item-disabled]):hover {
-  border-color: var(--odn-color-black-7);
-  background: var(--odn-color-black-3);
-  color: var(--odn-color-black-12);
+  border-color: var(--odn-color-black-3);
 }
 [data-odn-skill-slot][data-odn-skill-slot-variant=bar] [data-odn-skill-slot-item]:not([data-odn-skill-slot-item-disabled]):active {
-  background: var(--odn-color-black-4);
+  border-color: var(--odn-color-black-4);
 }
 [data-odn-skill-slot][data-odn-skill-slot-variant=bar] [data-odn-skill-slot-item]:not([data-odn-skill-slot-item-disabled]):focus-visible {
   outline: none;
   border-color: var(--odn-color-brand-6);
-  background: var(--odn-color-black-3);
-  color: var(--odn-color-black-12);
+}
+
+/* bar chip hover 的全文提示：暗色浮层（设计稿「文字提示」：向上、多行）。
+ * 整条 bar 走 Tooltip.Group，浮层是 tooltip；popupClassName 落在
+ * [data-odn-popup-content] 上，用 [data-type] 兜住 pop-base 的
+ * popover 白底 / tooltip #404040 两套默认值。 */
+[data-odn-popup][data-type] [data-odn-popup-content].odn-skill-slot-bar-popup {
+  max-width: 400px;
+  padding: 4px 8px;
+  border-radius: 4px;
+  background-color: var(--odn-color-solid-black-11);
+  color: var(--odn-color-white);
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+}
+
+[data-odn-popup][data-type] [data-odn-popup-content].odn-skill-slot-bar-popup [data-odn-popup-arrow-fill] {
+  fill: var(--odn-color-solid-black-11);
+}
+
+/* 浮层纯视觉遮挡，不接收鼠标：pointer-events 可继承，给外层一次即可。
+ * 多行 bar 里浮层会压在上一行的块上，若吃掉事件，块↔块之间就换不过去，
+ * 也会挡住下层页面/输入框。 */
+[data-odn-popup]:has(> [data-odn-popup-content].odn-skill-slot-bar-popup) {
+  pointer-events: none;
 }
 
 /* ---- variant: card ---- */
@@ -366,4 +398,12 @@
   color: var(--odn-color-black-9);
   word-break: break-word;
   white-space: pre-wrap;
+}
+
+/* bar 的全文浮层里换成暗底白字 14/22（宽度由 .odn-skill-slot-bar-popup 的 400 兜住） */
+.odn-skill-slot-bar-popup [data-odn-skill-slot-desc-full] {
+  max-width: 100%;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--odn-color-white);
 }

package/package.json

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