one-design-next 0.0.121 → 0.0.123

package/dist/_genui-types.d.ts

@@ -142,11 +142,25 @@ export interface ChipData {
      *
      * **不是正文内容**：既不进 `value`（无 marker），也不进剪贴板；只在
      * 「结构谓词成立」时作为派生的只读视觉渲染在 chip 之后——即该 chip 是
-     * 最后一个内容、且其后**一个字符都没有**（空格 / 换行都算内容；详见
-     * `resolveHintTarget`）。
+     * 最后一个内容、其后**一个字符都没有**（空格 / 换行都算内容），且它的
+     * hint 还没关闭（见 `hintClosed`；详见 `resolveHintTarget`）。
      * 发送时由 `rawValueToSegments` 按同一谓词追加为 `ComposerHintSegment`。
      */
     hint?: string;
+    /**
+     * 该 chip 的 hint 是否已经关闭（一次性，只关不开）。
+     *
+     * hint 的机会只有一次：只要这颗 chip **后面出现过东西**——插入时后面就有
+     * 文字、用户后面敲了字符 / 空格 / 换行，或者又插了一块 skill——就置为
+     * `true`。此后即使把后面的内容删回空串，灰字也不会再出现，发送时也不再补
+     * `hint` 段。
+     *
+     * 由编辑器在内容变化时写入（`resolveHintClosedChipIds`），业务不需要读写；
+     * 它随 `chips` 快照透传，业务若把 chips 一起存进草稿，恢复后 hint 也保持
+     * 关闭。skill 本身没有 `hint` 时不写这个字段——那是「没有这个能力」，不是
+     * 状态。
+     */
+    hintClosed?: boolean;
 }
 export interface SkillItem {
     id: string;
@@ -159,6 +173,8 @@ export interface SkillItem {
      * 选中插入后，只要该 skill chip 是输入框里最后一个内容且其后没有其它内容
      * （空格 / 换行都算内容），就会以只读灰字形式渲染在 chip 后面；用户在其后
      * 输入任何字符或换行即自动隐藏。与光标位置无关。
+     * 灰字是一次性的：一旦收起（或者插入时后面本来就有内容），再把后面的内容
+     * 删掉也不会重新出现。
      */
     hint?: string;
     /**
@@ -224,7 +240,8 @@ export interface ComposerMentionSegment {
 }
 /**
  * 派生的 skill 提示段：**不是用户输入的内容**，而是「最后一个 skill chip + 其后
- * 无内容」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板文案。
+ * 无内容 + hint 未关闭」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板
+ * 文案。
  *
  * 只在 `onSend` 的 segments 里出现；不出现在 `value` / `chips` / 剪贴板里。
  * 需要忽略它的业务可以直接 filter，或用 `isHintSegment` 收窄。

package/dist/_genui-types.js

@@ -56,7 +56,8 @@ export var ComposerSegmentType = {
 
 /**
  * 派生的 skill 提示段：**不是用户输入的内容**，而是「最后一个 skill chip + 其后
- * 无内容」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板文案。
+ * 无内容 + hint 未关闭」这一结构谓词成立时，由 Composer 在发送瞬间追加的模板
+ * 文案。
  *
  * 只在 `onSend` 的 segments 里出现；不出现在 `value` / `chips` / 剪贴板里。
  * 需要忽略它的业务可以直接 filter，或用 `isHintSegment` 收窄。

package/dist/composer/editor.d.ts

@@ -18,6 +18,7 @@
  */
 import React from 'react';
 import type { ChipData } from '../_genui-types';
+import { type ComposerSkillHint } from './segments';
 /** Composer editor 触发态对外信号——告诉父组件该弹浮层选 skill 了。 */
 export interface ComposerEditorTriggerInfo {
     /** 触发字符（@ 或 /） */
@@ -72,6 +73,16 @@ export interface ComposerEditorProps {
     defaultValue?: string;
     /** 值变化回调；参数是 raw string，含 marker。 */
     onChange?: (value: string) => void;
+    /**
+     * 灰字（skill hint）命中状态变化回调：
+     *   - 灰字出现（最后一个 chip 命中结构谓词）→ 传入命中的 chip / 文案
+     *   - 灰字消失（后面有内容 / chip 被删 / hint 已关闭）→ 传入 null
+     *
+     * 只在状态**真的变化**时抛一次；与灰字渲染共用同一份判定（先落 DOM 再抛，
+     * 不会各自算一套）。判定成立但灰字被临时摘掉（IME 合成期）时不跟着抖。
+     * 挂载时会先同步一次当前状态（空内容即 null），业务侧不必自己猜初始值。
+     */
+    onSkillHintChange?: (hint: ComposerSkillHint | null) => void;
     /** 与 defaultValue / 首次受控 value 配套，把 marker 还原成 chip。 */
     defaultChips?: ChipData[];
     placeholder?: string;

package/dist/composer/editor.js

@@ -29,7 +29,7 @@ import { buildClipboardPayload, COMPOSER_CLIPBOARD_MIME, parseClipboardPayload,
 import { useChipManager } from "./hooks/useChipManager";
 import { useChipSelectionMarker } from "./hooks/useChipSelectionMarker";
 import { chipHasEditableParams, ComposerInlineRef } from "./inline-ref";
-import { resolveHintTarget } from "./segments";
+import { resolveHintClosedChipIds, resolveHintTarget } from "./segments";
 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 了。 */
@@ -326,6 +326,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     defaultValue = _ref$defaultValue === void 0 ? '' : _ref$defaultValue,
     defaultChips = _ref.defaultChips,
     onChange = _ref.onChange,
+    onSkillHintChange = _ref.onSkillHintChange,
     placeholder = _ref.placeholder,
     autoSize = _ref.autoSize,
     onPressEnter = _ref.onPressEnter,
@@ -353,6 +354,9 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
   var isComposingRef = useRef(false);
   var onTriggerChangeRef = useRef(onTriggerChange);
   onTriggerChangeRef.current = onTriggerChange;
+  /** 灰字状态回调走 ref：调用方常传内联函数，不能让 fireChange / 挂载同步因此反复重建 */
+  var onSkillHintChangeRef = useRef(onSkillHintChange);
+  onSkillHintChangeRef.current = onSkillHintChange;
   var isControlled = valueProp !== undefined;
   var minRows = (_autoSize$minRows = autoSize === null || autoSize === void 0 ? void 0 : autoSize.minRows) !== null && _autoSize$minRows !== void 0 ? _autoSize$minRows : 1;
   var maxRows = autoSize === null || autoSize === void 0 ? void 0 : autoSize.maxRows;
@@ -490,6 +494,9 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
   var getChipsRef = useRef(function () {
     return [];
   });
+  /* hint 关闭器：与 getChipsRef 同一套「ref 打破声明顺序」做法——fireChange 声明
+   * 在 useChipManager 之前，而关闭方法由后者提供。 */
+  var closeChipHintsRef = useRef(function () {});
 
   /* ---- 派生 hint：imperative DOM 同步 ----
    * hint 必须是 chip host 的**兄弟节点**，不能塞在 host 内部：host 是
@@ -584,6 +591,33 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     }
   }, [removeHintNode]);
 
+  /* 灰字状态的**上一帧快照**：回调只在真的变化时抛一次。
+   * fireChange 每次输入都会跑，不去重的话业务侧会被同一条状态反复冲刷。
+   * `undefined` = 还没抛过（与「抛过 null」区分），保证挂载时一定会同步一次。 */
+  var lastSkillHintRef = useRef(undefined);
+
+  /**
+   * 把「灰字当前状态」通知给业务方（与 syncHintNode 同一份 target，保证同源）。
+   *
+   * 只在 chipId / refId / 文案任一变化时抛：同一条状态在连续输入里会算很多次。
+   */
+  var notifySkillHint = useCallback(function (target, chips) {
+    var _chips$find, _onSkillHintChangeRef;
+    var next = target ? {
+      chipId: target.chipId,
+      text: target.text,
+      refId: (_chips$find = chips.find(function (chip) {
+        return chip.id === target.chipId;
+      })) === null || _chips$find === void 0 ? void 0 : _chips$find.refId
+    } : null;
+    var prev = lastSkillHintRef.current;
+    if (prev !== undefined && (prev === null || prev === void 0 ? void 0 : prev.chipId) === (next === null || next === void 0 ? void 0 : next.chipId) && (prev === null || prev === void 0 ? void 0 : prev.text) === (next === null || next === void 0 ? void 0 : next.text) && (prev === null || prev === void 0 ? void 0 : prev.refId) === (next === null || next === void 0 ? void 0 : next.refId)) {
+      return;
+    }
+    lastSkillHintRef.current = next;
+    (_onSkillHintChangeRef = onSkillHintChangeRef.current) === null || _onSkillHintChangeRef === void 0 || _onSkillHintChangeRef.call(onSkillHintChangeRef, next);
+  }, []);
+
   /** 把 caret 直接落到 hint 之前（= chip 右侧）；没有 hint 时不动。 */
   var placeCaretBeforeHint = useCallback(function () {
     var el = editorRef.current;
@@ -615,11 +649,21 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     normalizeEditorDom(el);
     var chips = getChipsRef.current();
     var raw = getPlainText(el);
-    /* 派生 hint 与 value 同源同刻重算：结构谓词只依赖 raw + chips（换行也算
+    /* hint 是一次性的：先把「后面出现过东西」的 chip 永久关闭，再算谓词。
+     * 顺序不能反——反了的话，删到空的那一帧会先渲染出灰字再被移除（闪一下）。
+     * 关闭会改写 chips 快照，所以谓词必须用关闭后的快照重新取。
+     *
+     * 派生 hint 与 value 同源同刻重算：结构谓词只依赖 raw + chips（换行也算
      * 内容，所以按 Enter 后 hint 自动消失）。必须先落 DOM 再算 empty / 高度——
      * 否则「chip 被删」时残留的 hint 文本会让 placeholder 判定与 lite 升格
      * 判定晚一拍。 */
-    syncHintNode(resolveHintTarget(raw, chips));
+    closeChipHintsRef.current(resolveHintClosedChipIds(raw, chips));
+    /* 关闭会改写 chips 快照，谓词必须用关闭后的快照重新取；
+     * 渲染（syncHintNode）与对外回调（notifySkillHint）共用这一份 target，
+     * 业务拿到的是「这一刻灰字该不该在」的同一份判定，不会各算一套。 */
+    var hintChips = getChipsRef.current();
+    var hintTarget = resolveHintTarget(raw, hintChips);
+    syncHintNode(hintTarget);
     var showPlaceholder = shouldShowPlaceholder(el);
     if (forceNonEmptyOnceRef.current && showPlaceholder) {
       setEmpty(false);
@@ -632,7 +676,23 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     scheduleControlledSync();
     // editor.height 锁定时 RO 不触发，主动同步一次，确保升格判定能拿到 scrollHeight
     syncHeight();
-  }, [onChange, pullCaretBeforeHint, scheduleControlledSync, shouldShowPlaceholder, syncHeight, syncHintNode]);
+    /* 对外回调放在所有内部状态更新之后：业务在里面同步 setState 甚至
+     * updateChipData 都不会插进「DOM 已落、caret / 高度还没收尾」的中间态。 */
+    notifySkillHint(hintTarget, hintChips);
+  }, [notifySkillHint, onChange, pullCaretBeforeHint, scheduleControlledSync, shouldShowPlaceholder, syncHeight, syncHintNode]);
+
+  /* 挂载时同步一次灰字状态。
+   *
+   * 带 chips 的草稿恢复已经在挂载的 layout effect 里走 fireChange 抛过一次，
+   * 这里兜的是「空内容 / 只有纯文本挂载」——否则业务侧上一轮留下的状态没人复位。
+   * 放在 passive effect：晚于 chips 还原，且 notifySkillHint 自带去重，
+   * 与 fireChange 那一次重复时不会再抛。 */
+  useEffect(function () {
+    var el = editorRef.current;
+    if (!el) return;
+    var hintChips = getChipsRef.current();
+    notifySkillHint(resolveHintTarget(getPlainText(el), hintChips), hintChips);
+  }, [notifySkillHint]);
 
   /* ─────────────────────────────────────
    * chip 管理
@@ -648,10 +708,12 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
     syncChipsAfterDomMutation = _useChipManager.syncChipsAfterDomMutation,
     removeChip = _useChipManager.removeChip,
     updateChipData = _useChipManager.updateChipData,
+    closeChipHints = _useChipManager.closeChipHints,
     getChipHost = _useChipManager.getChipHost,
     getChips = _useChipManager.getChips,
     resetChips = _useChipManager.resetChips;
   getChipsRef.current = getChips;
+  closeChipHintsRef.current = closeChipHints;
   useChipSelectionMarker(editorRef, chips);
   var insertSerializedAtRangeRef = useRef(insertSerializedAtRange);
   insertSerializedAtRangeRef.current = insertSerializedAtRange;
@@ -775,6 +837,10 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
           onTriggerChange === null || onTriggerChange === void 0 || onTriggerChange(null);
         }
         onChange === null || onChange === void 0 || onChange('');
+        /* 这条路不走 fireChange（清空不是「内容变化」链路的一环），
+         * 灰字状态要在这里手动同步，否则业务侧会一直以为灰字还显示着。
+         * 位置放在 onChange 之后，与 fireChange 的「先 onChange 再灰字」一致。 */
+        notifySkillHint(null, []);
       },
       insertChip: function insertChip(data) {
         var el = editorRef.current;
@@ -871,7 +937,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
         return editorRef.current;
       }
     };
-  }, [onChange, _insertChip, insertSerializedAtRange, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
+  }, [onChange, _insertChip, insertSerializedAtRange, notifySkillHint, requestScrollCaretIntoView, removeChip, resetChips, onTriggerChange, getChips, updateChipData, getChipHost]);
 
   /* ─────────────────────────────────────
    * 监听 selection 变化：方向键 / 鼠标点击移位都要重算 trigger
@@ -1027,6 +1093,8 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
       removeHintNode();
       resetChips();
+      /* 同 clear()：外部改写 value 不走 fireChange，灰字状态在这里手动同步 */
+      notifySkillHint(null, []);
       setEmpty(shouldShowPlaceholder(el));
       if (triggerRef.current) {
         var _onTriggerChangeRef$c;
@@ -1035,7 +1103,7 @@ export var ComposerEditor = /*#__PURE__*/forwardRef(function ComposerEditor(_ref
       }
       syncHeight();
     }
-  }, [controlledSyncTick, valueProp, isControlled, resetChips, shouldShowPlaceholder, syncHeight]);
+  }, [controlledSyncTick, valueProp, isControlled, notifySkillHint, resetChips, shouldShowPlaceholder, syncHeight]);
 
   /* ─────────────────────────────────────
    * 输入事件

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

@@ -49,6 +49,14 @@ export interface UseChipManagerReturn {
     removeChip: (id: string) => void;
     /** 更新 chip 数据（参数面板关闭保存等）。 */
     updateChipData: (id: string, patch: Partial<ChipData>) => void;
+    /**
+     * 把这些 chip 的 hint 标记为已关闭（`ChipData.hintClosed`）。
+     *
+     * 只改 chips 快照里的数据，**不抛 onChange / 不走 onAfterMutate**：调用点在
+     * fireChange 内部，走 onAfterMutate 会立刻再进一次 fireChange（递归）。
+     * 幂等：已经关闭的 / 不存在的 id 直接忽略。
+     */
+    closeChipHints: (ids: readonly string[]) => void;
     /** 按 id 取 chip host（参数面板 anchor）。 */
     getChipHost: (id: string) => HTMLSpanElement | null;
     /** 当前 chip 快照（读 ref，插入后同步 onChange 时可用）。 */

package/dist/composer/hooks/useChipManager.js

@@ -397,6 +397,27 @@ onAfterMutate) {
     setChips(next);
     onAfterMutate === null || onAfterMutate === void 0 || onAfterMutate();
   }, [onAfterMutate]);
+  var closeChipHints = useCallback(function (ids) {
+    if (ids.length === 0) return;
+    var targets = new Set(ids);
+    var mutated = false;
+    /* 不就地写 `data`：insertChip / insertSerializedAtRange 拿到的对象可能属于
+     * 调用方（defaultChips / insertContent 的 chips），原地改会把内部状态写到
+     * 业务数据上。 */
+    var next = chipsRef.current.map(function (chip) {
+      if (!targets.has(chip.data.id) || chip.data.hintClosed) return chip;
+      mutated = true;
+      return _objectSpread(_objectSpread({}, chip), {}, {
+        data: _objectSpread(_objectSpread({}, chip.data), {}, {
+          hintClosed: true
+        })
+      });
+    });
+    if (!mutated) return;
+    chipsRef.current = next;
+    // 不调 onAfterMutate：调用方就在 fireChange 里，否则会递归
+    setChips(next);
+  }, []);
   var getChipHost = useCallback(function (id) {
     var _chipsRef$current$fin, _chipsRef$current$fin2;
     return (_chipsRef$current$fin = (_chipsRef$current$fin2 = chipsRef.current.find(function (c) {
@@ -422,6 +443,7 @@ onAfterMutate) {
     syncChipsAfterDomMutation: syncChipsAfterDomMutation,
     removeChip: removeChip,
     updateChipData: updateChipData,
+    closeChipHints: closeChipHints,
     getChipHost: getChipHost,
     getChips: getChips,
     resetChips: resetChips

package/dist/composer/index.d.ts

@@ -4,9 +4,11 @@ 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 { type ComposerSkillHint } from './segments';
 import './style';
 export type { ComposerInsertOptions, ComposerInsertPart, ComposerInsertResult, } from './insert';
 export type { ComposerParamPanelContext } from './param-panel';
+export type { ComposerHintTarget, ComposerSkillHint } from './segments';
 export type ComposerTool = 'attachment' | 'webSearch' | 'skill';
 export type ComposerVariant = 'full' | 'lite';
 export type SubmitType = 'enter' | 'shiftEnter';
@@ -105,17 +107,33 @@ export interface ComposerProps {
     defaultChips?: ChipData[];
     /** 输入框值变化回调。第二参是当前 chip 快照，旧调用方忽略即可。 */
     onChange?: (value: string, chips?: ChipData[]) => void;
+    /**
+     * 技能灰字（`SkillItem.hint`）的出现 / 消失回调。
+     *
+     * 入参与输入框里那行灰字共用**同一份判定**（`resolveHintTarget`）：命中时给
+     * `{ chipId, text, refId }`，消失时给 `null`。因此业务不需要自己解析
+     * value / chips，也不会出现「库里觉得有、业务觉得没有」的分歧。
+     *
+     * 语义要点：
+     * - 只在状态真的变化时抛一次，同一条状态不会因为连续输入重复抛；
+     * - 判定成立但灰字被临时摘掉（IME 合成期避开候选串）时不跟着抖；
+     * - 挂载时先同步一次当前状态（首屏没有灰字即 `null`），便于业务复位上一轮状态；
+     * - 灰字一次性：收起后即使把内容删回空串也不会再抛命中；
+     * - 卸载不会再补一次 `null`：需要清理时由业务在自己的卸载路径处理；
+     * - 与 `hint`（底部快捷键提示开关）无关。
+     */
+    onSkillHintChange?: (hint: ComposerSkillHint | null) => void;
     /**
      * 发送回调。
      *
      * `segments`：有序内容 IR，业务按数组顺序自定义拼后端。
      * `meta`：附件 / 联网搜索等非正文数据；为空时不传。
      *
-     * **派生 `hint` 段**：当最后一个 chip 是带 `SkillItem.hint` 的 skill、且其后
-     * 一个字符都没有（空格 / 换行都算内容）时，该提示文案会作为
-     * `{ type: 'hint', data: { text } }` 出现在 segments 末尾——与输入框里那段
-     * 灰字同源同谓词，不会漂移。不需要它的业务直接 filter / `isHintSegment`
-     * 判一下即可。
+     * **派生 `hint` 段**：当最后一个 chip 是带 `SkillItem.hint` 的 skill、其后
+     * 一个字符都没有（空格 / 换行都算内容）、且这颗 chip 的 hint 还没关闭时，
+     * 该提示文案会作为 `{ type: 'hint', data: { text } }` 出现在 segments 末尾
+     * ——与输入框里那段灰字同源同谓词，不会漂移。不需要它的业务直接 filter /
+     * `isHintSegment` 判一下即可。
      *
      * 兼容旧链路（需要单串文本）：业务可调 `segmentsToReadableText(segments)`。
      *

package/dist/composer/index.js

@@ -94,6 +94,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     defaultValue = _ref$defaultValue === void 0 ? '' : _ref$defaultValue,
     defaultChips = _ref.defaultChips,
     onChangeProp = _ref.onChange,
+    onSkillHintChange = _ref.onSkillHintChange,
     onSend = _ref.onSend,
     onStop = _ref.onStop,
     _ref$isGenerating = _ref.isGenerating,
@@ -514,9 +515,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 的一部分。
+   * 派生 hint：最后一个 chip 是 skill、其后没有内容、且它的 hint 还没关闭时，
+   * `rawValueToSegments` 会在末尾追加一段 `hint`（与该 chip 后面渲染的灰字
+   * 同源、同谓词）。它不属于用户输入，也不是受控 value 的一部分；hint 一旦
+   * 关闭（`ChipData.hintClosed`）就不再追加——没显示给用户的模板不会被发出去。
    *
    * 需要单串文本的业务方在 onSend 内自行调 segmentsToReadableText。
    * onSend 返回 false 或 Promise<false> 时视为发送失败，不清空；否则正常清空。
@@ -1234,6 +1236,7 @@ export var Composer = /*#__PURE__*/forwardRef(function Composer(_ref, ref) {
     value: text,
     defaultChips: defaultChips,
     onChange: updateText,
+    onSkillHintChange: onSkillHintChange,
     disabled: disabled,
     paramEditChipId: (_paramEdit$chipId = paramEdit === null || paramEdit === void 0 ? void 0 : paramEdit.chipId) !== null && _paramEdit$chipId !== void 0 ? _paramEdit$chipId : null,
     onInlineRefClick: renderParamPanel ? handleInlineRefClick : undefined

package/dist/composer/segments.d.ts

@@ -6,7 +6,10 @@
  * - `rawValueToSegments`：库内部用，把含零宽 marker 的 raw value + chip 列表
  *   还原为 `ComposerSegment[]`。
  * - `resolveHintTarget`：结构谓词——「最后一个 chip 之后一个字符都没有
- *   （空格 / 换行都算内容）+ 该 chip 带 hint」，渲染与发送都靠它。
+ *   （空格 / 换行都算内容）+ 该 chip 带 hint + hint 未关闭」，渲染与发送
+ *   都靠它。
+ * - `resolveHintClosedChipIds`：找出「一次性机会已作废」的 chip（自己的尾串
+ *   出现过内容），由编辑器写回 `ChipData.hintClosed`。
  * - `segmentsToReadableText`：业务可选工具，按指定占位符格式把 segments 拼成
  *   一句话（默认 `[Skill: label]` / `[@label]`，与 ComposerMention 兼容）。
  * - `segmentsHasContent`：是否含可见内容；库内 send 校验用，业务可复用。
@@ -26,19 +29,46 @@ export interface ComposerHintTarget {
     /** 提示文本（skill 模板文案，发送时原样作为 hint 段的 data.text） */
     text: string;
 }
+/**
+ * 灰字当前状态的对外快照（`ComposerProps.onSkillHintChange` 的入参）。
+ *
+ * 在 `ComposerHintTarget` 基础上补 chip 的业务标识：业务拿到回调时通常只想
+ * 知道「哪一块技能正在展示灰字」，不必再去 onChange 的 chips 快照里反查——
+ * 尤其 chip 插入与注册是两条异步链路，反查可能还没就绪。
+ */
+export interface ComposerSkillHint extends ComposerHintTarget {
+    /** 命中 chip 的业务侧资源 id（`ChipData.refId`，skill chip 即 `SkillItem.id`）；自定义 chip 可能没有 */
+    refId?: string;
+}
 /**
  * 判定当前内容是否命中 hint：
  * 1. `value` 里存在 marker（即至少有一个 chip）
  * 2. 最后一个 marker 之后**一个字符都没有**（空格 / 换行都算内容）
  * 3. 该 marker 对应的 chip 带 hint 文本（`@` 触发的 mention chip 不参与）
+ * 4. 该 chip 的 hint 还没关闭（`hintClosed`，一次性）
  */
 export declare function resolveHintTarget(raw: string, chips: ChipData[]): ComposerHintTarget | null;
+/**
+ * 找出「hint 的一次性机会已经作废」的 chip id（编辑器据此写回 `hintClosed`）。
+ *
+ * 判据只看每颗 chip **后面出现过什么**：本 marker 与下个 marker 之间有字符
+ * （文字 / 空格 / 换行），或者后面还有别的 marker（又插了一块），hint 的
+ * 机会就作废。因此它同时覆盖两类情况：
+ * - 插入时就落在正文中间（或后面紧跟着另一块）：hint 从未出现，之后把后面
+ *   删空也不该再冒出来
+ * - 展示过又被内容顶掉：删回空串也不该回来
+ *
+ * 纯函数，幂等（已关闭的 chip 直接跳过，重复调用结果一致）；没有 hint 文本的
+ * chip 不参与——没能力 ≠ 状态。
+ */
+export declare function resolveHintClosedChipIds(raw: string, chips: ChipData[]): string[];
 /**
  * 从含零宽 marker 的 raw value + chip 列表构建有序 segments。
  *
  * 这是「编辑器状态 → 发送内容」的**唯一映射**：
  * 1. marker 依次还原为 invocation / mention，与文本段按出现顺序交替
- * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后且其后一个字符都没有时）
+ * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后、其后一个字符都没有、
+ *    且 hint 还没关闭时）
  *
  * 因此 `rawValueToSegments(value, chips)` 与 `onSend` 收到的 segments 一致，
  * 业务可以放心用它做预览 / 调试。

package/dist/composer/segments.js

@@ -6,7 +6,10 @@
  * - `rawValueToSegments`：库内部用，把含零宽 marker 的 raw value + chip 列表
  *   还原为 `ComposerSegment[]`。
  * - `resolveHintTarget`：结构谓词——「最后一个 chip 之后一个字符都没有
- *   （空格 / 换行都算内容）+ 该 chip 带 hint」，渲染与发送都靠它。
+ *   （空格 / 换行都算内容）+ 该 chip 带 hint + hint 未关闭」，渲染与发送
+ *   都靠它。
+ * - `resolveHintClosedChipIds`：找出「一次性机会已作废」的 chip（自己的尾串
+ *   出现过内容），由编辑器写回 `ChipData.hintClosed`。
  * - `segmentsToReadableText`：业务可选工具，按指定占位符格式把 segments 拼成
  *   一句话（默认 `[Skill: label]` / `[@label]`，与 ComposerMention 兼容）。
  * - `segmentsHasContent`：是否含可见内容；库内 send 校验用，业务可复用。
@@ -36,27 +39,40 @@ export var isHintSegment = function isHintSegment(s) {
 };
 
 /* ────────────────────────────────────────────────────────────────────
- * Hint 结构谓词 · 「最后一个 chip + 其后一个字符都没有」
+ * Hint 结构谓词 · 「最后一个 chip + 其后一个字符都没有 + 没关闭」
  *
  * hint 不是内容，而是内容结构的投影：只要最后一个 chip 之后的 value 是
- * **空串**，且该 chip 带 hint，就命中。
+ * **空串**，且该 chip 带 hint、且它的 hint 还没关闭，就命中。
  *
  * 空格、换行、文字**都算内容**：用户在 chip 后面敲下第一个字符 / 按下
  * Enter（含 Shift+Enter）都说明 skill 块之后已经有东西了，hint 必须让位。
- * 反过来，把这些字符（包括换行）删干净、chip 后面重新变成空串，hint 才回来。
  * 插入 chip 本身不会写空格（见 useChipManager.insertChip）：行尾插入后尾串
  * 就是空串，hint 立刻命中，不需要为「自动补的空格」做特殊判断。
  *
+ * hint 是**一次性**的：只要这颗 chip 后面出现过东西——文字 / 空格 / 换行，
+ * 或者又插了一块——hint 就永久关闭（`ChipData.hintClosed`），之后把内容删回
+ * 空串也不会再出现，发送时也不再补 `hint` 段。因此「插入时后面本来就有内容」
+ * 的 chip 从一开始就是关闭态，不会因为后面被删空而凭空冒出灰字。关闭由
+ * `resolveHintClosedChipIds` 判定、编辑器在同一次内容变化里写回。
+ *
  * 谓词与光标位置无关——用户在前面打字不影响。**渲染（Editor）与发送
  * （Composer）都只依赖这一个谓词**，每次内容变化重算一次，两处永远一致。
  * ──────────────────────────────────────────────────────────────────── */
 
 /** hint 命中结果。 */
 
+/**
+ * 灰字当前状态的对外快照（`ComposerProps.onSkillHintChange` 的入参）。
+ *
+ * 在 `ComposerHintTarget` 基础上补 chip 的业务标识：业务拿到回调时通常只想
+ * 知道「哪一块技能正在展示灰字」，不必再去 onChange 的 chips 快照里反查——
+ * 尤其 chip 插入与注册是两条异步链路，反查可能还没就绪。
+ */
+
 /**
  * 最后一个 marker 的 chip id 与它之后的尾串；没有 chip 时返回 null。
  *
- * 「尾串」是 hint 判定的唯一输入：谓词要求它是**空串**。
+ * 「尾串」是结构判定的一部分：谓词要求它是**空串**（另外还要求 hint 未关闭）。
  */
 function getLastMarkerTail(raw) {
   var markers = parseMarkers(raw);
@@ -73,6 +89,7 @@ function getLastMarkerTail(raw) {
  * 1. `value` 里存在 marker（即至少有一个 chip）
  * 2. 最后一个 marker 之后**一个字符都没有**（空格 / 换行都算内容）
  * 3. 该 marker 对应的 chip 带 hint 文本（`@` 触发的 mention chip 不参与）
+ * 4. 该 chip 的 hint 还没关闭（`hintClosed`，一次性）
  */
 export function resolveHintTarget(raw, chips) {
   var _chip$hint;
@@ -83,19 +100,64 @@ export function resolveHintTarget(raw, chips) {
   });
   if (!chip || chip.kind === 'mention') return null;
   var text = (_chip$hint = chip.hint) === null || _chip$hint === void 0 ? void 0 : _chip$hint.trim();
-  if (!text) return null;
+  if (!text || chip.hintClosed) return null;
   return {
     chipId: chip.id,
     text: text
   };
 }
 
+/**
+ * 找出「hint 的一次性机会已经作废」的 chip id（编辑器据此写回 `hintClosed`）。
+ *
+ * 判据只看每颗 chip **后面出现过什么**：本 marker 与下个 marker 之间有字符
+ * （文字 / 空格 / 换行），或者后面还有别的 marker（又插了一块），hint 的
+ * 机会就作废。因此它同时覆盖两类情况：
+ * - 插入时就落在正文中间（或后面紧跟着另一块）：hint 从未出现，之后把后面
+ *   删空也不该再冒出来
+ * - 展示过又被内容顶掉：删回空串也不该回来
+ *
+ * 纯函数，幂等（已关闭的 chip 直接跳过，重复调用结果一致）；没有 hint 文本的
+ * chip 不参与——没能力 ≠ 状态。
+ */
+export function resolveHintClosedChipIds(raw, chips) {
+  /* 先看有没有「还开着 hint 的 chip」：没有就不必解析 marker（无 hint 的
+   * composer 每次输入都会走到这里）。 */
+  var hasCandidate = chips.some(function (chip) {
+    var _chip$hint2;
+    return chip.kind !== 'mention' && !chip.hintClosed && !!((_chip$hint2 = chip.hint) !== null && _chip$hint2 !== void 0 && _chip$hint2.trim());
+  });
+  if (!hasCandidate || !raw) return [];
+  var markers = parseMarkers(raw);
+  if (markers.length === 0) return [];
+  var chipById = new Map(chips.map(function (chip) {
+    return [chip.id, chip];
+  }));
+  var closed = [];
+  var seen = new Set();
+  markers.forEach(function (marker, index) {
+    var _chip$hint3, _next$rawStart;
+    var chip = chipById.get(marker.id);
+    if (!chip || chip.kind === 'mention' || chip.hintClosed) return;
+    if (!((_chip$hint3 = chip.hint) !== null && _chip$hint3 !== void 0 && _chip$hint3.trim()) || seen.has(chip.id)) return;
+    var next = markers[index + 1];
+    /* 尾串 = 本 marker 结束 → 下个 marker 开始 */
+    var hasTextAfter = raw.slice(marker.rawEnd, (_next$rawStart = next === null || next === void 0 ? void 0 : next.rawStart) !== null && _next$rawStart !== void 0 ? _next$rawStart : raw.length).length > 0;
+    if (next || hasTextAfter) {
+      seen.add(chip.id);
+      closed.push(chip.id);
+    }
+  });
+  return closed;
+}
+
 /**
  * 从含零宽 marker 的 raw value + chip 列表构建有序 segments。
  *
  * 这是「编辑器状态 → 发送内容」的**唯一映射**：
  * 1. marker 依次还原为 invocation / mention，与文本段按出现顺序交替
- * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后且其后一个字符都没有时）
+ * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后、其后一个字符都没有、
+ *    且 hint 还没关闭时）
  *
  * 因此 `rawValueToSegments(value, chips)` 与 `onSend` 收到的 segments 一致，
  * 业务可以放心用它做预览 / 调试。

package/dist/index.d.ts

@@ -83,4 +83,4 @@ export { default as Welcome, type WelcomeProps } from './welcome';
 export { ComposerSegmentType } from './_genui-types';
 export type { AgentEvent, Attachment, ChatMessage, ChipData, ComposerHintSegment, ComposerInvocationSegment, ComposerMentionSegment, ComposerSegment, ComposerTextSegment, Conversation, HintData, InlineRefState, InvocationData, MentionData, MessageSnapshot, PreviewTab, PreviewTarget, SendMeta, SkillItem, Source, TextData, ToolCall, ToolStatus, } from './_genui-types';
 export type { InterruptBase, InterruptIntent, InterruptStatus, } from './_interrupt-types';
-export { isHintSegment, isInvocationSegment, isMentionSegment, isTextSegment, rawValueToSegments, resolveHintTarget, segmentsHasContent, segmentsToReadableText, type ComposerHintTarget, type SegmentsToReadableTextOptions, } from './composer/segments';
+export { isHintSegment, isInvocationSegment, isMentionSegment, isTextSegment, rawValueToSegments, resolveHintTarget, segmentsHasContent, segmentsToReadableText, type ComposerHintTarget, type ComposerSkillHint, type SegmentsToReadableTextOptions, } from './composer/segments';

package/package.json

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