one-design-next 0.0.113 → 0.0.115

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 } from "../utils";
+import { createLineRoot, ensureCaretAnchorAfter, ensureLineRoots, forEachMarkerSegment, getCurrentLineRoot, LINE_ATTR_NAME, stripInvisibleChars } from "../utils";
 
 /** chip 在 React 状态中的形态：data + 对应的 DOM host。 */
 
@@ -120,17 +120,27 @@ onAfterMutate) {
     var newRange = document.createRange();
     var parent = host.parentNode;
     if (parent) {
-      var _nextText$textContent, _nextText$textContent2;
+      var _next$textContent, _nextText$textContent, _stripInvisibleChars$;
+      /* insertNode 在文本末尾切一刀会留下空文本节点，它等同于「后面没内容」，
+       * 不能当成「后面有正文」（否则行尾 chip 的 hint 永远不出现）。
+       * 纯 ZWSP 锚点文本（caret 落点）同理——它不是正文。 */
       var next = host.nextSibling;
-      var nextText = (next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE ? next : null;
-      var leading = (_nextText$textContent = nextText === null || nextText === void 0 || (_nextText$textContent2 = nextText.textContent) === null || _nextText$textContent2 === void 0 ? void 0 : _nextText$textContent2[0]) !== null && _nextText$textContent !== void 0 ? _nextText$textContent : '';
-      if (!nextText || !/\s/.test(leading)) {
-        var spacer = document.createTextNode(' ');
-        parent.insertBefore(spacer, next);
-        newRange.setStart(spacer, 1);
+      var nextText = (next === null || next === void 0 ? void 0 : next.nodeType) === Node.TEXT_NODE && ((_next$textContent = next.textContent) !== null && _next$textContent !== void 0 ? _next$textContent : '') !== '' ? next : null;
+      var nextRaw = (_nextText$textContent = nextText === null || nextText === void 0 ? void 0 : nextText.textContent) !== null && _nextText$textContent !== void 0 ? _nextText$textContent : '';
+      /* 跳过零宽锚点前缀后的第一个字符；空格也算用户已有的内容。 */
+      var firstContentChar = (_stripInvisibleChars$ = stripInvisibleChars(nextRaw)[0]) !== null && _stripInvisibleChars$ !== void 0 ? _stripInvisibleChars$ : '';
+
+      /* 插入 chip 从不往内容里写空格：补出来的空格会进 value / segments，
+       * 变成用户没输入过的字符。间隔由 chip 自身的 padding（0 4px）提供。
+       *   - 后面紧跟正文：caret 直接落到正文起点
+       *   - 后面是另一个 chip / 行尾 / 只剩派生 hint / 只有 ZWSP 锚点：垫一个
+       *     不进 value 的 ZWSP 锚点给 caret 落位 */
+      if (nextText && firstContentChar) {
+        newRange.setStart(nextText, nextRaw.indexOf(firstContentChar));
       } else {
-        var _nextText$textContent3;
-        newRange.setStart(nextText, Math.min(1, ((_nextText$textContent3 = nextText.textContent) !== null && _nextText$textContent3 !== void 0 ? _nextText$textContent3 : '').length));
+        var _anchor$textContent;
+        var anchor = ensureCaretAnchorAfter(host);
+        newRange.setStart(anchor, ((_anchor$textContent = anchor.textContent) !== null && _anchor$textContent !== void 0 ? _anchor$textContent : '').length);
       }
     } else {
       newRange.setStartAfter(host);
@@ -143,7 +153,7 @@ onAfterMutate) {
     });
     onAfterMutate === null || onAfterMutate === void 0 || onAfterMutate();
   }, [insertChipAtRange, onAfterMutate]);
-  var insertSerializedAtRange = useCallback(function (value, chipList, range, editor) {
+  var insertSerializedAtRange = useCallback(function (value, chipList, range, editor, options) {
     var chipById = new Map(chipList.map(function (c) {
       return [c.id, c];
     }));
@@ -227,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);
@@ -243,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();
@@ -260,9 +270,14 @@ onAfterMutate) {
       chipsRef.current = next;
       setChips(next);
     }
-    requestAnimationFrame(function () {
-      return editor.focus();
-    });
+
+    /* 默认保持原行为（粘贴 / Tab 采纳都发生在已聚焦的编辑器里，focus 是幂等的）。
+     * 首屏还原内容必须显式关掉：mount 期间 focus() 会连带触发页面滚动。 */
+    if ((options === null || options === void 0 ? void 0 : options.focus) !== false) {
+      requestAnimationFrame(function () {
+        return editor.focus();
+      });
+    }
     onAfterMutate === null || onAfterMutate === void 0 || onAfterMutate();
   }, [onAfterMutate]);
   var syncChipsAfterDomMutation = useCallback(function (editor) {

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 置为待补充态。
@@ -76,6 +110,12 @@ export interface ComposerProps {
      * `segments`：有序内容 IR，业务按数组顺序自定义拼后端。
      * `meta`：附件 / 联网搜索等非正文数据；为空时不传。
      *
+     * **派生 `hint` 段**：当最后一个 chip 是带 `SkillItem.hint` 的 skill、且其后
+     * 一个字符都没有（空格 / 换行都算内容）时，该提示文案会作为
+     * `{ type: 'hint', data: { text } }` 出现在 segments 末尾——与输入框里那段
+     * 灰字同源同谓词，不会漂移。不需要它的业务直接 filter / `isHintSegment`
+     * 判一下即可。
+     *
      * 兼容旧链路（需要单串文本）：业务可调 `segmentsToReadableText(segments)`。
      *
      * **返回值语义**：

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,20 +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: {}
-  };
-}
 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) {
@@ -319,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);
@@ -417,6 +444,10 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
    *   - segments：有序 IR（text / invocation / mention 交替）
    *   - meta：attachments / webSearch 等非正文数据；都为空时不传
    *
+   * 派生 hint：最后一个 chip 是 skill 且其后没有内容时，`rawValueToSegments`
+   * 会在末尾追加一段 `hint`（与该 chip 后面渲染的灰字同源、同谓词）。
+   * 它不属于用户输入，也不是受控 value 的一部分。
+   *
    * 需要单串文本的业务方在 onSend 内自行调 segmentsToReadableText。
    * onSend 返回 false 或 Promise<false> 时视为发送失败，不清空；否则正常清空。
    *
@@ -637,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);
@@ -681,7 +712,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
 
   /* editor 在 trigger 激活时把 ↑↓Enter Esc Tab 丢过来。返回 true = editor 别管了。
    * - ↑↓ 改高亮 index（夹在 [0, max] 内）
-   * - Enter / Tab 选中当前高亮项
+   * - Enter / Tab 选中当前高亮项（Tab 默认落在第一个可用技能上）
    * - Escape 关 menu，焦点保留在 editor */
   var handleTriggerKeyDown = useCallback(function (e) {
     if (!triggerMenuVisible) return false;
@@ -700,7 +731,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       (_triggerSkillSlotRef$2 = triggerSkillSlotRef.current) === null || _triggerSkillSlotRef$2 === void 0 || _triggerSkillSlotRef$2.moveActive('up');
       return true;
     }
-    if (e.key === 'Enter' && !e.shiftKey || e.key === 'Tab') {
+    if (e.key === 'Enter' && !e.shiftKey) {
       var _triggerSkillSlotRef$3, _triggerSkillSlotRef$4;
       e.preventDefault();
       var _skill = (_triggerSkillSlotRef$3 = (_triggerSkillSlotRef$4 = triggerSkillSlotRef.current) === null || _triggerSkillSlotRef$4 === void 0 ? void 0 : _triggerSkillSlotRef$4.getActiveSkill()) !== null && _triggerSkillSlotRef$3 !== void 0 ? _triggerSkillSlotRef$3 : filteredSkills === null || filteredSkills === void 0 ? void 0 : filteredSkills[triggerActiveIndex];
@@ -708,6 +739,20 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       handleSelectSkill(_skill, 'trigger');
       return true;
     }
+    /* Tab 与 Enter 同义：接受当前高亮项。query 变化时高亮已复位到第一个
+     * 可用项，所以「/ + 关键字有命中 → Tab」就是插入第一个匹配技能。
+     * 没有可选项时不 preventDefault，把 Tab 让回浏览器（editor 里还可能
+     * 落到 hint 采纳）。 */
+    if (e.key === 'Tab') {
+      var _ref4, _ref5, _triggerSkillSlotRef$5, _triggerSkillSlotRef$6;
+      var _skill2 = (_ref4 = (_ref5 = (_triggerSkillSlotRef$5 = (_triggerSkillSlotRef$6 = triggerSkillSlotRef.current) === null || _triggerSkillSlotRef$6 === void 0 ? void 0 : _triggerSkillSlotRef$6.getActiveSkill()) !== null && _triggerSkillSlotRef$5 !== void 0 ? _triggerSkillSlotRef$5 : filteredSkills === null || filteredSkills === void 0 ? void 0 : filteredSkills[triggerActiveIndex]) !== null && _ref5 !== void 0 ? _ref5 : filteredSkills === null || filteredSkills === void 0 ? void 0 : filteredSkills.find(function (s) {
+        return !s.disabled;
+      })) !== null && _ref4 !== void 0 ? _ref4 : null;
+      if (!_skill2) return false;
+      e.preventDefault();
+      handleSelectSkill(_skill2, 'trigger');
+      return true;
+    }
     if (e.key === 'Escape') {
       var _editorRef$current19;
       e.preventDefault();
@@ -741,8 +786,8 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
   useLayoutEffect(function () {
     if (!toolMenuOpen && !triggerMenuVisible) return undefined;
     var sync = function sync() {
-      var _skillTriggerRef$curr, _skillTriggerRef$curr2, _ref4, _triggerInfo$rect$top, _triggerAnchorRef$cur;
-      var triggerTop = toolMenuOpen ? (_skillTriggerRef$curr = (_skillTriggerRef$curr2 = skillTriggerRef.current) === null || _skillTriggerRef$curr2 === void 0 ? void 0 : _skillTriggerRef$curr2.getBoundingClientRect().top) !== null && _skillTriggerRef$curr !== void 0 ? _skillTriggerRef$curr : null : (_ref4 = (_triggerInfo$rect$top = triggerInfo === null || triggerInfo === void 0 ? void 0 : triggerInfo.rect.top) !== null && _triggerInfo$rect$top !== void 0 ? _triggerInfo$rect$top : (_triggerAnchorRef$cur = triggerAnchorRef.current) === null || _triggerAnchorRef$cur === void 0 ? void 0 : _triggerAnchorRef$cur.getBoundingClientRect().top) !== null && _ref4 !== void 0 ? _ref4 : null;
+      var _skillTriggerRef$curr, _skillTriggerRef$curr2, _ref6, _triggerInfo$rect$top, _triggerAnchorRef$cur;
+      var triggerTop = toolMenuOpen ? (_skillTriggerRef$curr = (_skillTriggerRef$curr2 = skillTriggerRef.current) === null || _skillTriggerRef$curr2 === void 0 ? void 0 : _skillTriggerRef$curr2.getBoundingClientRect().top) !== null && _skillTriggerRef$curr !== void 0 ? _skillTriggerRef$curr : null : (_ref6 = (_triggerInfo$rect$top = triggerInfo === null || triggerInfo === void 0 ? void 0 : triggerInfo.rect.top) !== null && _triggerInfo$rect$top !== void 0 ? _triggerInfo$rect$top : (_triggerAnchorRef$cur = triggerAnchorRef.current) === null || _triggerAnchorRef$cur === void 0 ? void 0 : _triggerAnchorRef$cur.getBoundingClientRect().top) !== null && _ref6 !== void 0 ? _ref6 : null;
       if (triggerTop === null) return;
       var next = resolveComposerSkillMenuMaxHeight({
         triggerTop: triggerTop,
@@ -848,7 +893,10 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       activeColor: TOOL_BTN_ACTIVE,
       disabled: btnDisabled
     }, /*#__PURE__*/React.createElement("button", {
-      type: "button",
+      type: "button"
+      /* 不进入 Tab 焦点序列：composer 内的 Tab 只用于 hint 采纳，
+       * 不允许它逐个跳到工具栏按钮上（鼠标点击仍可正常使用）。 */,
+      tabIndex: -1,
       onClick: function onClick() {
         var _fileInputRef$current;
         onToolClick === null || onToolClick === void 0 || onToolClick('attachment');
@@ -888,6 +936,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       disabled: disabled || webSearch
     }, /*#__PURE__*/React.createElement("button", {
       type: "button",
+      tabIndex: -1,
       onClick: function onClick() {
         onToolClick === null || onToolClick === void 0 || onToolClick('webSearch');
         setWebSearch(function (v) {
@@ -965,6 +1014,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
       disabled: disabled || toolMenuOpen
     }, /*#__PURE__*/React.createElement("button", {
       type: "button",
+      tabIndex: -1,
       disabled: disabled,
       onMouseDown: function onMouseDown(e) {
         return e.preventDefault();
@@ -1038,6 +1088,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
    * 因为整体禁用语义包含"现在什么都不能做"，包括中断。 */
   var sendOrStopButton = !disabled && isGenerating ? /*#__PURE__*/React.createElement("button", {
     type: "button",
+    tabIndex: -1,
     onClick: onStop,
     "data-odn-composer-stop-btn": true,
     title: "\u505C\u6B62\u751F\u6210"
@@ -1046,6 +1097,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     size: 18
   })) : /*#__PURE__*/React.createElement("button", {
     type: "button",
+    tabIndex: -1,
     onClick: handleSend,
     disabled: disabled || !canSend,
     "data-odn-composer-send-btn": true,
@@ -1222,6 +1274,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     placement: "top"
   }, /*#__PURE__*/React.createElement("button", {
     type: "button",
+    tabIndex: -1,
     "data-odn-composer-expand-btn": true,
     "aria-label": fullExpandLabel,
     "aria-expanded": fullExpanded,

package/dist/composer/inline-ref.d.ts

@@ -10,6 +10,11 @@ export interface ComposerInlineRefProps {
     /** 有参数面板时由 Composer 注入；点击打开面板 */
     onClick?: (anchor: HTMLElement) => void;
 }
-/** Composer 内联引用视觉：按 kind 派发 Invocation（/）或 Mention（@）。 */
+/**
+ * Composer 内联引用视觉：按 kind 派发 Invocation（/）或 Mention（@）。
+ *
+ * 注：派生 hint 不在 host 内渲染——它是 host 的兄弟节点（见 `editor.tsx` 的
+ * `syncHintNode`），否则「chip 之后、hint 之前」这个 caret 位置会不存在。
+ */
 export declare function ComposerInlineRef({ data, active, onClick, }: ComposerInlineRefProps): React.JSX.Element;
 export default ComposerInlineRef;

package/dist/composer/inline-ref.js

@@ -16,7 +16,12 @@ export function chipHasEditableParams(chip) {
     return v !== null && v !== undefined && v !== '';
   });
 }
-/** Composer 内联引用视觉：按 kind 派发 Invocation（/）或 Mention（@）。 */
+/**
+ * Composer 内联引用视觉：按 kind 派发 Invocation（/）或 Mention（@）。
+ *
+ * 注：派生 hint 不在 host 内渲染——它是 host 的兄弟节点（见 `editor.tsx` 的
+ * `syncHintNode`），否则「chip 之后、hint 之前」这个 caret 位置会不存在。
+ */
 export function ComposerInlineRef(_ref) {
   var data = _ref.data,
     _ref$active = _ref.active,

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/segments.d.ts

@@ -5,18 +5,44 @@
  *
  * - `rawValueToSegments`：库内部用，把含零宽 marker 的 raw value + chip 列表
  *   还原为 `ComposerSegment[]`。
+ * - `resolveHintTarget`：结构谓词——「最后一个 chip 之后一个字符都没有
+ *   （空格 / 换行都算内容）+ 该 chip 带 hint」，渲染与发送都靠它。
  * - `segmentsToReadableText`：业务可选工具，按指定占位符格式把 segments 拼成
  *   一句话（默认 `[Skill: label]` / `[@label]`，与 ComposerMention 兼容）。
  * - `segmentsHasContent`：是否含可见内容；库内 send 校验用，业务可复用。
  */
-import type { ChipData, ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, TextData } from '../_genui-types';
+import type { ChipData, ComposerHintSegment, ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, HintData, TextData } from '../_genui-types';
 import { ComposerSegmentType } from '../_genui-types';
-export type { ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, TextData, };
 export { ComposerSegmentType };
+export type { ComposerHintSegment, ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, HintData, TextData, };
 export declare const isTextSegment: (s: ComposerSegment) => s is ComposerTextSegment;
 export declare const isInvocationSegment: (s: ComposerSegment) => s is ComposerInvocationSegment;
 export declare const isMentionSegment: (s: ComposerSegment) => s is ComposerMentionSegment;
-/** 从含零宽 marker 的 raw value + chip 列表构建有序 segments。 */
+export declare const isHintSegment: (s: ComposerSegment) => s is ComposerHintSegment;
+/** hint 命中结果。 */
+export interface ComposerHintTarget {
+    /** 命中 hint 的 chip id（渲染时用它定位到具体 chip） */
+    chipId: string;
+    /** 提示文本（skill 模板文案，发送时原样作为 hint 段的 data.text） */
+    text: string;
+}
+/**
+ * 判定当前内容是否命中 hint：
+ * 1. `value` 里存在 marker（即至少有一个 chip）
+ * 2. 最后一个 marker 之后**一个字符都没有**（空格 / 换行都算内容）
+ * 3. 该 marker 对应的 chip 带 hint 文本（`@` 触发的 mention chip 不参与）
+ */
+export declare function resolveHintTarget(raw: string, chips: ChipData[]): ComposerHintTarget | null;
+/**
+ * 从含零宽 marker 的 raw value + chip 列表构建有序 segments。
+ *
+ * 这是「编辑器状态 → 发送内容」的**唯一映射**：
+ * 1. marker 依次还原为 invocation / mention，与文本段按出现顺序交替
+ * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后且其后一个字符都没有时）
+ *
+ * 因此 `rawValueToSegments(value, chips)` 与 `onSend` 收到的 segments 一致，
+ * 业务可以放心用它做预览 / 调试。
+ */
 export declare function rawValueToSegments(raw: string, chips: ChipData[]): ComposerSegment[];
 export interface SegmentsToReadableTextOptions {
     /** invocation 占位格式，默认 `[Skill: {label}]` */
@@ -27,7 +53,9 @@ export interface SegmentsToReadableTextOptions {
 /**
  * 把 segments 拼成一条字符串，供需要单串 string 的 LLM / 旧后端使用。
  * 库**不内置调用**此函数；由业务在 onSend 内自行选择。
+ *
+ * `hint` 段直接输出原文（它本身就是给模型的模板文案，不加 `[Skill: …]` 包裹）。
  */
 export declare function segmentsToReadableText(segments: ComposerSegment[], options?: SegmentsToReadableTextOptions): string;
-/** segments 是否含可见内容（文本非空或含内联引用）。 */
+/** segments 是否含可见内容（文本非空、含内联引用，或含派生 hint）。 */
 export declare function segmentsHasContent(segments: ComposerSegment[]): boolean;