one-design-next 0.0.113 → 0.0.114

package/dist/composer/index.js

@@ -29,7 +29,10 @@ function createInvocationChipData(skill) {
     kind: 'invocation',
     state: skill.initialState,
     refId: skill.id,
-    payload: {}
+    payload: {},
+    /* 提示文案随 chip 快照下来（而不是渲染时回查技能目录）：
+     * 草稿用 defaultValue + defaultChips 还原时，目录可能已经变了。 */
+    hint: skill.hint
   };
 }
 var TOOL_BTN_ACTIVE = 'color-mix(in srgb, var(--odn-color-brand-6) 10%, transparent)';
@@ -417,6 +420,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> 时视为发送失败，不清空；否则正常清空。
    *
@@ -681,7 +688,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 +707,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 +715,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 +762,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 +869,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 +912,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 +990,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 +1064,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 +1073,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 +1250,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/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;

package/dist/composer/segments.js

@@ -5,6 +5,8 @@
  *
  * - `rawValueToSegments`：库内部用，把含零宽 marker 的 raw value + chip 列表
  *   还原为 `ComposerSegment[]`。
+ * - `resolveHintTarget`：结构谓词——「最后一个 chip 之后一个字符都没有
+ *   （空格 / 换行都算内容）+ 该 chip 带 hint」，渲染与发送都靠它。
  * - `segmentsToReadableText`：业务可选工具，按指定占位符格式把 segments 拼成
  *   一句话（默认 `[Skill: label]` / `[@label]`，与 ComposerMention 兼容）。
  * - `segmentsHasContent`：是否含可见内容；库内 send 校验用，业务可复用。
@@ -12,9 +14,8 @@
 
 import { ComposerSegmentType } from "../_genui-types";
 import { chipToInvocationData, chipToMentionData } from "./send-meta";
-import { forEachMarkerSegment } from "./utils";
+import { forEachMarkerSegment, parseMarkers } from "./utils";
 export { ComposerSegmentType };
-
 /* ────────────────────────────────────────────────────────────────────
  * Type guards · 给业务方 filter / find 用，避免现场写 Extract<…>。
  *
@@ -30,8 +31,75 @@ export var isInvocationSegment = function isInvocationSegment(s) {
 export var isMentionSegment = function isMentionSegment(s) {
   return s.type === ComposerSegmentType.Mention;
 };
+export var isHintSegment = function isHintSegment(s) {
+  return s.type === ComposerSegmentType.Hint;
+};
+
+/* ────────────────────────────────────────────────────────────────────
+ * Hint 结构谓词 · 「最后一个 chip + 其后一个字符都没有」
+ *
+ * hint 不是内容，而是内容结构的投影：只要最后一个 chip 之后的 value 是
+ * **空串**，且该 chip 带 hint，就命中。
+ *
+ * 空格、换行、文字**都算内容**：用户在 chip 后面敲下第一个字符 / 按下
+ * Enter（含 Shift+Enter）都说明 skill 块之后已经有东西了，hint 必须让位。
+ * 反过来，把这些字符（包括换行）删干净、chip 后面重新变成空串，hint 才回来。
+ * 插入 chip 本身不会写空格（见 useChipManager.insertChip）：行尾插入后尾串
+ * 就是空串，hint 立刻命中，不需要为「自动补的空格」做特殊判断。
+ *
+ * 谓词与光标位置无关——用户在前面打字不影响。**渲染（Editor）与发送
+ * （Composer）都只依赖这一个谓词**，每次内容变化重算一次，两处永远一致。
+ * ──────────────────────────────────────────────────────────────────── */
+
+/** hint 命中结果。 */
+
+/**
+ * 最后一个 marker 的 chip id 与它之后的尾串；没有 chip 时返回 null。
+ *
+ * 「尾串」是 hint 判定的唯一输入：谓词要求它是**空串**。
+ */
+function getLastMarkerTail(raw) {
+  var markers = parseMarkers(raw);
+  var last = markers[markers.length - 1];
+  if (!last) return null;
+  return {
+    chipId: last.id,
+    tail: raw.slice(last.rawEnd)
+  };
+}
 
-/** 从含零宽 marker 的 raw value + chip 列表构建有序 segments。 */
+/**
+ * 判定当前内容是否命中 hint：
+ * 1. `value` 里存在 marker（即至少有一个 chip）
+ * 2. 最后一个 marker 之后**一个字符都没有**（空格 / 换行都算内容）
+ * 3. 该 marker 对应的 chip 带 hint 文本（`@` 触发的 mention chip 不参与）
+ */
+export function resolveHintTarget(raw, chips) {
+  var _chip$hint;
+  var info = getLastMarkerTail(raw);
+  if (!info || info.tail.length > 0) return null;
+  var chip = chips.find(function (c) {
+    return c.id === info.chipId;
+  });
+  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;
+  return {
+    chipId: chip.id,
+    text: text
+  };
+}
+
+/**
+ * 从含零宽 marker 的 raw value + chip 列表构建有序 segments。
+ *
+ * 这是「编辑器状态 → 发送内容」的**唯一映射**：
+ * 1. marker 依次还原为 invocation / mention，与文本段按出现顺序交替
+ * 2. 末尾按结构谓词补一段派生的 `hint`（skill 在最后且其后一个字符都没有时）
+ *
+ * 因此 `rawValueToSegments(value, chips)` 与 `onSend` 收到的 segments 一致，
+ * 业务可以放心用它做预览 / 调试。
+ */
 export function rawValueToSegments(raw, chips) {
   var chipById = new Map(chips.map(function (c) {
     return [c.id, c];
@@ -63,6 +131,15 @@ export function rawValueToSegments(raw, chips) {
       });
     }
   });
+  var hintTarget = resolveHintTarget(raw, chips);
+  if (hintTarget) {
+    segments.push({
+      type: 'hint',
+      data: {
+        text: hintTarget.text
+      }
+    });
+  }
   return segments;
 }
 var defaultFormatInvocation = function defaultFormatInvocation(label) {
@@ -75,6 +152,8 @@ var defaultFormatMention = function defaultFormatMention(label) {
 /**
  * 把 segments 拼成一条字符串，供需要单串 string 的 LLM / 旧后端使用。
  * 库**不内置调用**此函数；由业务在 onSend 内自行选择。
+ *
+ * `hint` 段直接输出原文（它本身就是给模型的模板文案，不加 `[Skill: …]` 包裹）。
  */
 export function segmentsToReadableText(segments, options) {
   var _options$formatInvoca, _options$formatMentio;
@@ -88,15 +167,17 @@ export function segmentsToReadableText(segments, options) {
         return fmtInv(seg.data.label);
       case 'mention':
         return fmtMen(seg.data.label);
+      case 'hint':
+        return seg.data.text;
       default:
         return '';
     }
   }).join('');
 }
 
-/** segments 是否含可见内容（文本非空或含内联引用）。 */
+/** segments 是否含可见内容（文本非空、含内联引用，或含派生 hint）。 */
 export function segmentsHasContent(segments) {
   return segments.some(function (s) {
-    return s.type === 'invocation' || s.type === 'mention' || s.type === 'text' && s.data.text.trim().length > 0;
+    return s.type === 'invocation' || s.type === 'mention' || s.type === 'hint' || s.type === 'text' && s.data.text.trim().length > 0;
   });
 }

package/dist/composer/style/index.css

@@ -169,7 +169,12 @@
   width: 100%;
 }
 
+/* 升格态：box 必须回到正常流。
+ * 单行态是 absolute + bottom: 0（贴 inner 底部，inner 只留 52px）。内容一旦
+ * 变高（多行文本 / 派生 hint），绝对定位的 box 会向上溢出 inner 的占位、盖住
+ * 上方所有内容（demo 里表现为输入框飘到外面的文案上）。 */
 [data-odn-composer][data-odn-composer-variant=lite][data-odn-composer-expanded] [data-odn-composer-box] {
+  position: relative;
   padding-bottom: 42px;
 }
 
@@ -287,6 +292,23 @@
   line-height: inherit;
 }
 
+/* ------------------------------------------------------------------
+ * 派生 hint（结构谓词：chip 是最后一个内容且其后无可见内容）
+ * 它是 chip host 的**兄弟节点**（不是 host 内部）：
+ *   - 只有兄弟关系才存在「chip 之后、hint 之前」这个 caret 落点；
+ *     host 是 contentEditable=false 原子块，塞进 host 就只能落在整块之后
+ *   - hint 之后不允许落 caret（caret.ts · normalizeCollapsedCaretBeforeHint）
+ *   - 非内容：getPlainText 整棵子树跳过，不进 value / 剪贴板 / segments
+ *   - pre-wrap：skills 的模板文案可含换行
+ * ----------------------------------------------------------------- */
+[data-odn-composer] [data-odn-composer-skill-hint] {
+  margin-left: 4px;
+  color: var(--odn-color-black-8);
+  pointer-events: none;
+  user-select: none;
+  white-space: pre-wrap;
+}
+
 /* ------------------------------------------------------------------
  * Block 行模型（caret-rewrite step 1/5）
  *   editor 直接子节点都是 [data-composer-line] div，每行渲染为独立 block。

package/dist/composer/utils.d.ts

@@ -13,6 +13,15 @@
 export declare const LINE_DATASET_KEY = "composerLine";
 /** 行容器 DOM 属性名。 */
 export declare const LINE_ATTR_NAME = "data-composer-line";
+/**
+ * 派生 hint 的 DOM 钩子（skill 在最后且其后无内容时，渲染在 chip 之后的只读文本）。
+ *
+ * **不是正文**：它是 chip host 的兄弟节点，`getPlainText` 整棵子树跳过，
+ * 因此不进 value / 剪贴板；caret 也不允许停在它之后（见 `caret.ts`）。
+ * 注意别和底部快捷键提示的 `data-odn-composer-hint` 混用。
+ */
+export declare const COMPOSER_HINT_ATTR = "data-odn-composer-skill-hint";
+export declare const COMPOSER_HINT_SELECTOR = "[data-odn-composer-skill-hint]";
 /** 是否是行容器。 */
 export declare function isLineRoot(node: Node | null | undefined): node is HTMLDivElement;
 /** 创建一个新的空行容器。 */
@@ -70,6 +79,16 @@ export declare function forEachMarkerSegment(raw: string, visit: (segment: {
     type: 'marker';
     id: string;
 }) => void): void;
+/**
+ * 行容器内的 `<br>` 是否只是浏览器给「空行」补的占位。
+ *
+ * 行模型下换行由 line div 表达，行内的 `<br>` 不承载用户换行；Chrome 在
+ * 用户删空一行后会把该行变成 `<div><br></div>`（占位，撑住行高）。若把它
+ * 当成 '\n'，`value` 就会凭空多出一行（`marker + '\n'` 变成 `marker + '\n\n'`）。
+ *
+ * 判定：该 `<br>` 之后只剩不可见文本（ZWSP 等）或更多 `<br>`。
+ */
+export declare const isPlaceholderBr: (node: Node | null | undefined) => boolean;
 /**
  * 从 contenteditable 里把所有 chip 替换成 marker，得到上层 onChange / onSend
  * 关心的 raw string。
@@ -77,7 +96,8 @@ export declare function forEachMarkerSegment(raw: string, visit: (segment: {
  * 原则：
  * - chip host 元素 → 替换为 `createMarker(id)`
  * - 编辑器自塞的 ZWSP 锚点 → 全部剔除（不进入 value）
- * - `<br>` → `\n`
+ * - 派生 hint 子树 → 整棵跳过（它不是正文）
+ * - `<br>` → `\n`；但行容器内的「占位 `<br>`」（空行撑高用）不算换行
  * - 行容器 `<div data-composer-line>` → 行间输出 `\n`（首行除外）
  *
  * @param editor      编辑区根节点（contentEditable=true）

package/dist/composer/utils.js

@@ -29,6 +29,16 @@ export var LINE_DATASET_KEY = 'composerLine';
 /** 行容器 DOM 属性名。 */
 export var LINE_ATTR_NAME = 'data-composer-line';
 
+/**
+ * 派生 hint 的 DOM 钩子（skill 在最后且其后无内容时，渲染在 chip 之后的只读文本）。
+ *
+ * **不是正文**：它是 chip host 的兄弟节点，`getPlainText` 整棵子树跳过，
+ * 因此不进 value / 剪贴板；caret 也不允许停在它之后（见 `caret.ts`）。
+ * 注意别和底部快捷键提示的 `data-odn-composer-hint` 混用。
+ */
+export var COMPOSER_HINT_ATTR = 'data-odn-composer-skill-hint';
+export var COMPOSER_HINT_SELECTOR = "[".concat(COMPOSER_HINT_ATTR, "]");
+
 /** 是否是行容器。 */
 export function isLineRoot(node) {
   var _hasAttribute, _ref;
@@ -233,6 +243,35 @@ export function forEachMarkerSegment(raw, visit) {
  * getPlainText · 从 DOM 提取 marker 化的字符串
  * ──────────────────────────────────────────────────────────────────── */
 
+/**
+ * 行容器内的 `<br>` 是否只是浏览器给「空行」补的占位。
+ *
+ * 行模型下换行由 line div 表达，行内的 `<br>` 不承载用户换行；Chrome 在
+ * 用户删空一行后会把该行变成 `<div><br></div>`（占位，撑住行高）。若把它
+ * 当成 '\n'，`value` 就会凭空多出一行（`marker + '\n'` 变成 `marker + '\n\n'`）。
+ *
+ * 判定：该 `<br>` 之后只剩不可见文本（ZWSP 等）或更多 `<br>`。
+ */
+export var isPlaceholderBr = function isPlaceholderBr(node) {
+  if (!node || node.nodeType !== Node.ELEMENT_NODE) return false;
+  if (node.tagName !== 'BR') return false;
+  var cur = node.nextSibling;
+  while (cur) {
+    if (cur.nodeType === Node.TEXT_NODE) {
+      var _cur$textContent;
+      if (stripInvisibleChars((_cur$textContent = cur.textContent) !== null && _cur$textContent !== void 0 ? _cur$textContent : '') !== '') return false;
+      cur = cur.nextSibling;
+      continue;
+    }
+    if (cur.nodeType === Node.ELEMENT_NODE && cur.tagName === 'BR') {
+      cur = cur.nextSibling;
+      continue;
+    }
+    return false;
+  }
+  return true;
+};
+
 /**
  * 从 contenteditable 里把所有 chip 替换成 marker，得到上层 onChange / onSend
  * 关心的 raw string。
@@ -240,7 +279,8 @@ export function forEachMarkerSegment(raw, visit) {
  * 原则：
  * - chip host 元素 → 替换为 `createMarker(id)`
  * - 编辑器自塞的 ZWSP 锚点 → 全部剔除（不进入 value）
- * - `<br>` → `\n`
+ * - 派生 hint 子树 → 整棵跳过（它不是正文）
+ * - `<br>` → `\n`；但行容器内的「占位 `<br>`」（空行撑高用）不算换行
  * - 行容器 `<div data-composer-line>` → 行间输出 `\n`（首行除外）
  *
  * @param editor      编辑区根节点（contentEditable=true）
@@ -252,6 +292,8 @@ export function getPlainText(editor) {
   var out = '';
   var visit = function visit(node) {
     if (node instanceof HTMLElement) {
+      // 派生 hint 整棵子树都不是正文，直接跳过（含其内部文本节点）
+      if (node.hasAttribute(COMPOSER_HINT_ATTR)) return;
       var id = node.dataset[chipIdAttr];
       if (id) {
         out += createMarker(id);
@@ -286,6 +328,8 @@ export function getPlainText(editor) {
       firstLineSeen = true;
       for (var _i3 = 0, _Array$from3 = Array.from(c.childNodes); _i3 < _Array$from3.length; _i3++) {
         var cc = _Array$from3[_i3];
+        /* 行容器内的占位 <br> 不算换行（换行已由行边界表达）。 */
+        if (isPlaceholderBr(cc)) continue;
         visit(cc);
       }
       continue;
@@ -412,8 +456,8 @@ var isInvisibleChar = function isInvisibleChar(ch) {
  *  影响触发判定。 */
 var prevSignificantSibling = function prevSignificantSibling(node) {
   var cur = node.previousSibling;
-  while (cur && cur.nodeType === Node.TEXT_NODE && ((_cur$textContent = cur.textContent) !== null && _cur$textContent !== void 0 ? _cur$textContent : '') === '') {
-    var _cur$textContent;
+  while (cur && cur.nodeType === Node.TEXT_NODE && ((_cur$textContent2 = cur.textContent) !== null && _cur$textContent2 !== void 0 ? _cur$textContent2 : '') === '') {
+    var _cur$textContent2;
     cur = cur.previousSibling;
   }
   return cur;