openclaw-openagent 1.0.0

package/src/plugin-ui/modules/agent-book/panel/inject-ui.js

@@ -0,0 +1,456 @@
+
+// ── 注入逻辑（v3 — OC handleKeyDown/handleInput 钩子驱动）──
+//
+// 事件处理策略：
+//   keydown / input → 由 OC 注入钩子（mention-hooks UIExtension）调用 window.__clMention
+//   selectionchange → document 级事件委托（不绑 textarea，不怕 Lit 重建）
+//   beforeinput → document 级事件委托（同上）
+//   compositionstart/end → document 级事件委托（同上）
+//
+// tryInject() 只做 DOM 注入（@ 按钮 + CSS class），不绑定任何事件。
+
+// ── textarea 选择器（全局复用）──
+const _CL_TEXTAREA_SELECTOR = 'textarea[placeholder*="Message"], textarea[placeholder*="Enter to send"]';
+
+function _getTextarea() {
+  return document.querySelector(_CL_TEXTAREA_SELECTOR);
+}
+
+function _setTextareaValue(textarea, value) {
+  const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')?.set;
+  if (setter) setter.call(textarea, value);
+  else textarea.value = value;
+  textarea.dispatchEvent(new Event('input', { bubbles: true }));
+}
+
+function _buildRemoteAgentMarker(mention, userText) {
+  const hasChinese = /[\u4e00-\u9fff]/.test(userText || '');
+  const instruction = hasChinese
+    ? '请调用 openagent_call_remote_agent 工具将此请求转发给远端 Agent 处理'
+    : 'Please invoke the openagent_call_remote_agent tool to forward this request to the remote agent';
+  return `{openagent_call_remote_agent:agent_id="${mention.agent_id}",agent_name="${mention.name}",instruction="${instruction}"}`;
+}
+
+function _composeRemoteAgentMessage(textarea, mention) {
+  const currentVal = textarea.value || '';
+  const marker = _buildRemoteAgentMarker(mention, currentVal);
+  const escapedName = mention.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const atPattern = new RegExp('@' + escapedName + '\\s*');
+  return {
+    currentVal,
+    marker,
+    message: currentVal.replace(atPattern, marker + ' ')
+  };
+}
+
+function _isLikelyNativeSendButton(target, textarea) {
+  const button = target && target.closest ? target.closest('button, [role="button"]') : null;
+  if (!button || !textarea) return false;
+  if (button.classList && button.classList.contains('openagent-at-btn')) return false;
+
+  const inputContainer = textarea.closest('.chat-input')
+                      || textarea.closest('[class*="chat-composer"]')
+                      || textarea.closest('[class*="chat"]')
+                      || textarea.parentElement;
+  if (!inputContainer || !inputContainer.contains(button)) return false;
+
+  const label = [
+    button.getAttribute('aria-label'),
+    button.getAttribute('title'),
+    button.textContent
+  ].filter(Boolean).join(' ').toLowerCase();
+  if (/send|发送/.test(label)) return true;
+
+  const buttons = Array.from(inputContainer.querySelectorAll('button, [role="button"]'))
+    .filter(function(btn) {
+      if (btn.classList && btn.classList.contains('openagent-at-btn')) return false;
+      if (btn.disabled || btn.getAttribute('aria-disabled') === 'true') return false;
+      return btn.offsetParent !== null;
+    });
+  return buttons.length > 0 && buttons[buttons.length - 1] === button;
+}
+
+function _sendPendingMention(textarea) {
+  if (!textarea || !CL.pendingMention) return false;
+  if (CL.remoteSendInFlight) return true;
+
+  const mention = CL.pendingMention;
+  const payload = _composeRemoteAgentMessage(textarea, mention);
+  CL.remoteSendInFlight = true;
+
+  console.log('[cl-diag][send-marker]', {
+    agentId: mention.agent_id,
+    agentName: mention.name,
+    userTextPreview: payload.currentVal.slice(0, 200),
+    markerPreview: payload.marker.slice(0, 240),
+    sendValuePreview: payload.message.slice(0, 260),
+  });
+
+  // 不把内部 marker 写入 textarea。可见输入框按原生发送行为立即清空；
+  // 真正发给 OpenClaw 的带 marker 文本只作为 handleSendChat 参数传入。
+  _setTextareaValue(textarea, '');
+
+  (async () => {
+    try {
+      CL.lastMentionAgentId = mention.agent_id;
+      CL.pendingMention = null;
+      await CL.sendRemoteAgentMessage(payload.message);
+      console.log('[openagent] remote call sent');
+    } catch (err) {
+      CL.pendingMention = mention;
+      _setTextareaValue(textarea, payload.currentVal);
+      console.error('[openagent] remote call send failed', err);
+      window.alert?.('OpenAgent remote call 未发送：请检查 gateway 连接后重试。');
+    } finally {
+      CL.remoteSendInFlight = false;
+    }
+  })();
+
+  return true;
+}
+
+function _installSendClickInterceptor() {
+  if (window.__openagentSendClickInterceptorInstalled) return;
+  window.__openagentSendClickInterceptorInstalled = true;
+  document.addEventListener('click', function(e) {
+    if (!CL.pendingMention || CL.remoteSendInFlight) return;
+    const textarea = _getTextarea();
+    if (!_isLikelyNativeSendButton(e.target, textarea)) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    if (typeof e.stopImmediatePropagation === 'function') e.stopImmediatePropagation();
+    _sendPendingMention(textarea);
+  }, true);
+}
+
+function tryInject() {
+  const textarea = _getTextarea();
+
+  if (!textarea) return false;
+  _installSendClickInterceptor();
+  if (document.querySelector('.openagent-at-btn')) return true; // 已注入
+
+  // ── 定位插入点：麦克风图标所在的 toolbar 行 ──
+  const textareaParent = textarea.parentElement;
+  let toolbarRow = null;
+
+  if (textareaParent) {
+    for (const child of textareaParent.children) {
+      if (child !== textarea && child.querySelector('svg')) {
+        toolbarRow = child;
+        break;
+      }
+    }
+  }
+  if (!toolbarRow && textareaParent) {
+    const grandparent = textareaParent.parentElement;
+    if (grandparent) {
+      for (const child of grandparent.children) {
+        if (child !== textareaParent && child.querySelector('svg')) {
+          toolbarRow = child;
+          break;
+        }
+      }
+    }
+  }
+
+  // ── 创建 Agent Book 按钮 ──
+  const atBtn = document.createElement('button');
+  atBtn.className = 'openagent-at-btn';
+  atBtn.innerHTML = '<span class="at-sym">@</span> Agent Book';
+  atBtn.addEventListener('click', () => {
+    // 在 textarea 中插入 @ 字符，让状态机自然检测 → openPanel
+    const ta = _getTextarea();
+    if (!ta) return;
+    ta.focus();
+    const val = ta.value;
+    const pos = ta.selectionStart;
+    // 如果光标前已经是 @，不重复插入
+    if (pos > 0 && val[pos - 1] === '@') {
+      _handleStateChange(ta);
+      return;
+    }
+    // 插入 @ 字符（前面加空格分隔，除非行首/空白后）
+    const needSpace = pos > 0 && !/[\s\n]/.test(val[pos - 1]);
+    const insert = needSpace ? ' @' : '@';
+    const newVal = val.slice(0, pos) + insert + val.slice(pos);
+    const setter = Object.getOwnPropertyDescriptor(
+      HTMLTextAreaElement.prototype, 'value'
+    )?.set;
+    if (setter) setter.call(ta, newVal);
+    else ta.value = newVal;
+    ta.selectionStart = ta.selectionEnd = pos + insert.length;
+    ta.dispatchEvent(new Event('input', { bubbles: true }));
+    // input 事件 → OC handleInput → __clMention.onInput → 状态机打开面板
+  });
+
+  if (toolbarRow) {
+    const toolbarLeft = toolbarRow.querySelector('[class*="toolbar-left"]') || toolbarRow;
+    const iconButtons = toolbarLeft.querySelectorAll('button, [role="button"]');
+    let micBtn = null;
+    if (iconButtons.length >= 2) {
+      micBtn = iconButtons[1];
+    } else if (iconButtons.length === 1) {
+      micBtn = iconButtons[0];
+    }
+
+    if (micBtn) {
+      micBtn.after(atBtn);
+    } else {
+      toolbarLeft.appendChild(atBtn);
+    }
+  } else {
+    (textareaParent || textarea.parentElement).appendChild(atBtn);
+  }
+
+  // ── 给输入区域加 position: relative 包裹层 ──
+  const inputContainer = textarea.closest('.chat-input')
+                      || textarea.closest('[class*="chat-composer"]')
+                      || textarea.closest('[class*="chat"]')
+                      || textareaParent?.parentElement
+                      || textareaParent;
+  if (inputContainer) {
+    inputContainer.classList.add('openagent-input-wrapper');
+    inputWrapperRef = inputContainer;
+  }
+
+  console.log('[openagent] ✅ Agent Book UI injected (v3 hook-driven)');
+
+  return true;
+}
+
+// ════════════════════════════════════════════════════════════════
+// ── window.__clMention — OC 注入钩子的桥接对象 ──
+// ════════════════════════════════════════════════════════════════
+//
+// OC 的 handleKeyDown 中注入了：
+//   if (window.__clMention?.onKeyDown(e)) return;
+//
+// OC 的 handleInput 中注入了：
+//   window.__clMention?.onInput?.(target);
+//
+// 所有业务逻辑在此处理，注入端只做调用转发。
+
+window.__clMention = {
+
+  /**
+   * OC handleKeyDown 钩子。
+   * 返回 true → OC 跳过后续处理（包括 Enter 发送）。
+   * 返回 false → OC 继续正常处理。
+   */
+  onKeyDown(e) {
+    const textarea = e.target;
+
+    // ── 1. 面板打开时：键盘导航 ──
+    if (isActive()) {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault();
+          moveSelectionDown();
+          return true;
+
+        case 'ArrowUp':
+          e.preventDefault();
+          moveSelectionUp();
+          return true;
+
+        case 'Enter':
+          if (e.shiftKey) return false; // Shift+Enter = 换行，交给 OC
+          e.preventDefault();
+          selectHighlightedAgent(textarea);
+          return true; // 阻止 OC 发送
+
+        case 'Escape':
+          e.preventDefault();
+          setDismissed();
+          closePanel();
+          return true;
+      }
+      // 其他键（字符输入）：不拦截，让 OC 继续 → handleInput → onInput
+      return false;
+    }
+
+    // ── 2. Backspace 原子删除 @mention ──
+    // 对标 TIM mention.ts:321-356
+    // 整体删除 @AgentName（含 @ 符号），不保留 @，不重新弹出面板
+    if (e.key === 'Backspace' && CL.pendingMention) {
+      const val = textarea.value;
+      const pos = textarea.selectionStart;
+      const name = CL.pendingMention.name;
+      const mention = '@' + name;
+
+      const searchStart = Math.max(0, pos - mention.length - 1);
+      const nearText = val.substring(searchStart, pos);
+      const idx = nearText.lastIndexOf(mention);
+
+      if (idx !== -1) {
+        const mentionStart = searchStart + idx;
+        let mentionEnd = mentionStart + mention.length;
+        if (val[mentionEnd] === ' ') mentionEnd++; // 包含尾部空格
+
+        if (pos > mentionStart && pos <= mentionEnd) {
+          e.preventDefault();
+          // 整体删除 @AgentName（含 @ 符号）
+          const newVal = val.slice(0, mentionStart) + val.slice(mentionEnd);
+
+          const setter = Object.getOwnPropertyDescriptor(
+            HTMLTextAreaElement.prototype, 'value'
+          )?.set;
+          if (setter) setter.call(textarea, newVal);
+          else textarea.value = newVal;
+
+          // 光标放在删除位置
+          textarea.selectionStart = textarea.selectionEnd = mentionStart;
+          textarea.dispatchEvent(new Event('input', { bubbles: true }));
+          CL.pendingMention = null;
+          // @ 已被删除，状态机不会检测到 @ → 面板不会弹出
+          return true;
+        }
+      }
+    }
+
+    // ── 3. Enter 发送时：标记替换（面板关闭 + 有 pendingMention）──
+    // 这里接管原生发送，只是为了把可见 @mention 替换成 OpenAgent 内部 marker。
+    if (e.key === 'Enter' && !e.shiftKey && CL.pendingMention) {
+      e.preventDefault();
+      _sendPendingMention(textarea);
+
+      // 返回 true：OC 注入钩子会停止原生 Enter 发送，避免重复发送。
+      return true;
+    }
+
+    return false;
+  },
+
+  /**
+   * OC handleInput 钩子。
+   * 在 OC 的 props.onDraftChange(target.value) 之后调用。
+   */
+  onInput(textarea) {
+    _handleStateChange(textarea);
+  },
+
+  // ── 暴露给外部查询的辅助方法 ──
+  active() { return isActive(); },
+};
+
+// ════════════════════════════════════════════════════════════════
+// ── 事件委托（document 级，不怕 Lit 重建）──
+// ════════════════════════════════════════════════════════════════
+
+// ── 输入法组合状态跟踪 ──
+// 对标 suggestion.ts:508 "editor.view.composing"
+// 输入法组合中的 @ 不应触发面板（§1.1 ⑥）
+document.addEventListener('compositionstart', (e) => {
+  if (e.target?.matches?.(_CL_TEXTAREA_SELECTOR)) {
+    setComposing(true);
+  }
+});
+document.addEventListener('compositionend', (e) => {
+  if (e.target?.matches?.(_CL_TEXTAREA_SELECTOR)) {
+    setComposing(false);
+    // 输入法确认后可能产生 @，OC 的 handleInput 会触发 onInput
+    // 但 compositionend 在 input 之前触发，需要主动评估一次
+    _handleStateChange(e.target);
+  }
+});
+
+// ── 光标变化检测 ──
+// 对标 suggestion.ts:473 "选区变化也产生 transaction"
+// 实现 §1.3 ⑤ "点击输入框内其他位置 → 面板关闭"
+let _guardSelection = false;
+let _lastCursorPos = -1; // 追踪上次光标位置，用于判断进入 mention 的方向
+document.addEventListener('selectionchange', () => {
+  const textarea = _getTextarea();
+  if (!textarea || document.activeElement !== textarea) return;
+  if (_guardSelection) return;
+
+  // mention 光标保护（§1.6 原子标签）
+  // 对标 TIM：左键从右侧进入 → 跳到 @ 之前；右键从左侧进入 → 跳到末尾
+  const mentionRange = _findMentionRange(textarea.value);
+  if (mentionRange) {
+    const pos = textarea.selectionStart;
+    if (pos > mentionRange.start && pos < mentionRange.end &&
+        textarea.selectionStart === textarea.selectionEnd) {
+      _guardSelection = true;
+      if (_lastCursorPos >= 0 && _lastCursorPos >= mentionRange.end) {
+        // 箭头左键从右侧进入 → 跳到 @ 之前
+        textarea.selectionStart = textarea.selectionEnd = mentionRange.start;
+      } else if (_lastCursorPos >= 0 && _lastCursorPos <= mentionRange.start) {
+        // 箭头右键从左侧进入 → 跳到末尾
+        textarea.selectionStart = textarea.selectionEnd = mentionRange.end;
+      } else {
+        // 鼠标点击跳入 或 _lastCursorPos 未知(-1) → 跳到最近边界
+        const distToStart = pos - mentionRange.start;
+        const distToEnd = mentionRange.end - pos;
+        textarea.selectionStart = textarea.selectionEnd =
+          distToStart <= distToEnd ? mentionRange.start : mentionRange.end;
+      }
+      _lastCursorPos = textarea.selectionStart;
+      _guardSelection = false;
+      return;
+    }
+  }
+
+  _lastCursorPos = textarea.selectionStart;
+  // 状态机评估（光标移走 → 可能关闭面板）
+  _handleStateChange(textarea);
+});
+
+// ── mention 原子保护：阻止在 @mention 内部输入字符（§1.6）──
+// 事件委托：OC 不监听 beforeinput，不会冲突
+document.addEventListener('beforeinput', (e) => {
+  if (!e.target?.matches?.(_CL_TEXTAREA_SELECTOR)) return;
+  const textarea = e.target;
+  const mentionRange = _findMentionRange(textarea.value);
+  if (!mentionRange) return;
+  const selStart = textarea.selectionStart;
+  const selEnd = textarea.selectionEnd;
+  // 编辑范围与 mention 重叠 → 阻止
+  if (selStart > mentionRange.start && selStart < mentionRange.end) {
+    e.preventDefault();
+  } else if (selEnd > mentionRange.start && selEnd < mentionRange.end) {
+    e.preventDefault();
+  }
+});
+
+// ── 辅助函数 ──
+
+/**
+ * 统一的状态变化处理：调用状态机 → 根据结果操作面板。
+ */
+function _handleStateChange(textarea) {
+  const val = textarea.value;
+  const result = evaluateState(val, textarea.selectionStart, textarea.selectionEnd);
+
+  switch (result.action) {
+    case 'open':
+      openPanel(textarea);
+      break;
+    case 'update':
+      updatePanelSearch(textarea);
+      break;
+    case 'close':
+      closePanel();
+      break;
+    // 'none': 不做任何操作
+  }
+}
+
+/**
+ * 找到 textarea.value 中当前 mention 的范围。
+ * 用于原子保护（beforeinput / selectionchange）。
+ *
+ * @returns {{ start: number, end: number }|null}
+ */
+function _findMentionRange(value) {
+  if (!CL.pendingMention) return null;
+  const name = CL.pendingMention.name;
+  const mention = '@' + name;
+  const idx = value.lastIndexOf(mention);
+  if (idx === -1) return null;
+  let end = idx + mention.length;
+  if (value[end] === ' ') end++; // 包含尾部空格
+  return { start: idx, end };
+}

package/src/plugin-ui/modules/agent-book/panel/mention-state.js

@@ -0,0 +1,206 @@
+/**
+ * mention-state.js — @Mention 状态机
+ * 
+ * 模拟 Tiptap suggestion.ts 的核心逻辑，适配原生 textarea。
+ * 纯逻辑模块，不依赖 DOM、不操作面板 UI。
+ * 
+ * 参考：
+ *   - TIM suggestion.ts apply() L508-568（状态计算）
+ *   - TIM findSuggestionMatch.ts L37-77（@ 匹配）
+ *   - TIM suggestion.ts L491, L543-563（dismissed 机制）
+ * 
+ * 需求文档：024-B-at-mention-trigger-logic-v1.md
+ *   §1.1 弹出条件（⑤光标范围 ⑥选区/输入法 ⑦dismissed）
+ *   §1.3 关闭条件（③删@ ④空格 ⑤光标移走）
+ *   §1.4 dismissed 机制
+ */
+
+// ── 状态变量 ──
+// 对标 TIM suggestion.ts 的 Plugin state
+
+let _active = false;          // 面板是否激活（suggestion.ts:474 prev.active / next.active）
+let _anchorPos = -1;          // @ 字符在 value 中的位置（suggestion.ts:558 next.range.from）
+let _dismissedPos = null;     // ESC 关闭时记录的 @ 位置（suggestion.ts:491 dismissedRange）
+let _isComposing = false;     // 输入法组合中（suggestion.ts:508 editor.view.composing）
+
+// ── 前缀正则 ──
+// CL 的前缀规则：空白、换行、CJK、全角标点
+// 对标 inject-ui.js:110 现有逻辑，保持兼容
+const PREFIX_RE = /[\s\n\u4e00-\u9fff\u3000-\u303f\uff00-\uffef]/;
+
+/**
+ * 在 value 中找光标前最近的有效 @ 位置。
+ * 
+ * "有效" = @ 前面是允许的前缀（行首、空白、CJK、全角标点）。
+ * 从光标往前逐字符扫描，遇到空格则停止（不跨空格找 @）。
+ * 
+ * 对标 findSuggestionMatch.ts:37-71
+ * 
+ * @param {string} value - textarea.value
+ * @param {number} cursorPos - textarea.selectionStart
+ * @returns {number} @ 的位置索引，找不到返回 -1
+ */
+function findAtAnchor(value, cursorPos) {
+  for (let i = cursorPos - 1; i >= 0; i--) {
+    const ch = value[i];
+    if (ch === '@') {
+      // 行首 或 前一字符满足前缀条件
+      if (i === 0 || PREFIX_RE.test(value[i - 1])) {
+        return i;
+      }
+      // 前缀不合法（如 "hello@"），继续往前找？不，直接返回 -1
+      // 因为更前面的 @ 已经跟当前光标不连续了
+      return -1;
+    }
+    // @ 到光标之间只允许非空白字符（query 部分）
+    // 遇到空白就停止——说明光标已经离开 @xxx 范围
+    if (/\s/.test(ch)) return -1;
+  }
+  return -1;
+}
+
+/**
+ * 核心函数：评估当前 textarea 状态，决定面板动作。
+ * 
+ * 每次 textarea 内容变化 或 光标移动 时调用。
+ * 对标 suggestion.ts apply() L508-568。
+ * 
+ * @param {string} value - textarea.value
+ * @param {number} cursorPos - textarea.selectionStart
+ * @param {number} selectionEnd - textarea.selectionEnd
+ * @returns {{ action: 'open'|'update'|'close'|'none', query: string, anchorPos: number }}
+ */
+function evaluateState(value, cursorPos, selectionEnd) {
+  const result = { action: 'none', query: '', anchorPos: -1 };
+
+  // ── 条件 ⑥ 前半：输入法组合中 → 不处理 ──
+  // 对标 suggestion.ts:508 "empty || editor.view.composing"
+  if (_isComposing) {
+    return result;
+  }
+
+  // ── 条件 ⑥ 后半：有文字选区 → 关闭 ──
+  if (cursorPos !== selectionEnd) {
+    if (_active) {
+      _active = false;
+      _anchorPos = -1;
+      return { action: 'close', query: '', anchorPos: -1 };
+    }
+    return result;
+  }
+
+  // ── 全空检测：输入框清空 → 关闭 + 清 dismissed ──
+  if (value.trim() === '') {
+    _dismissedPos = null;
+    if (_active) {
+      _active = false;
+      _anchorPos = -1;
+      return { action: 'close', query: '', anchorPos: -1 };
+    }
+    return result;
+  }
+
+  // ── 条件 ⑤：找光标前的有效 @ ──
+  const anchorPos = findAtAnchor(value, cursorPos);
+
+  if (anchorPos === -1) {
+    // 没有有效的 @ → 关闭 + 清 dismissed
+    // 对标 suggestion.ts:565 "if (!match) { next.dismissedRange = null }"
+    _dismissedPos = null;
+    if (_active) {
+      _active = false;
+      _anchorPos = -1;
+      return { action: 'close', query: '', anchorPos: -1 };
+    }
+    return result;
+  }
+
+  // ── 提取 query（@ 后面到光标的文字）──
+  const query = value.slice(anchorPos + 1, cursorPos);
+
+  // ── 条件：@ 后有空格 → 关闭 ──
+  // 对标 findSuggestionMatch.ts:33 正则不匹配含空格
+  // 注意：query 中出现空格说明用户已经结束 @mention 输入
+  if (/\s/.test(query)) {
+    _dismissedPos = null;
+    if (_active) {
+      _active = false;
+      _anchorPos = -1;
+      return { action: 'close', query: '', anchorPos: -1 };
+    }
+    return result;
+  }
+
+  // ── 条件 ⑦：dismissed 检查 ──
+  // 对标 suggestion.ts:543-563 "match.range.from === dismissedRange.from"
+  if (_dismissedPos !== null && _dismissedPos === anchorPos) {
+    // 同一个 @ 位置被 ESC 关闭过 → 不弹出
+    if (_active) {
+      _active = false;
+      _anchorPos = -1;
+      return { action: 'close', query: '', anchorPos: -1 };
+    }
+    return result;
+  }
+
+  // ── 所有条件满足 → 打开或更新 ──
+  if (!_active) {
+    _active = true;
+    _anchorPos = anchorPos;
+    return { action: 'open', query, anchorPos };
+  } else {
+    _anchorPos = anchorPos;
+    return { action: 'update', query, anchorPos };
+  }
+}
+
+// ── 状态管理函数 ──
+
+/**
+ * ESC 关闭时调用：记录 dismissed 位置。
+ * 对标 suggestion.ts:491 设置 dismissedRange。
+ * 
+ * dismissed 恢复条件（§1.4）：
+ *   ① 输入空格 → evaluateState 检测到 query 含空格 → _dismissedPos 被清空
+ *   ② 新位置输入 @ → anchorPos !== _dismissedPos → 不受 dismissed 影响
+ *   ③ 删掉原 @ → anchorPos === -1 → _dismissedPos 被清空
+ */
+function setDismissed() {
+  _dismissedPos = _anchorPos;
+  _active = false;
+  _anchorPos = -1;
+}
+
+/**
+ * 面板正常关闭（选中 Agent / 点击 backdrop / 点击 ✕）。
+ * 不设置 dismissed——下次输入 @ 应该能正常弹出。
+ */
+function closeMention() {
+  _active = false;
+  _anchorPos = -1;
+  // 不动 _dismissedPos
+}
+
+/**
+ * 完全重置（选中 Agent 后、@ 被删除后）。
+ * 清空所有状态包括 dismissed。
+ */
+function resetMention() {
+  _active = false;
+  _anchorPos = -1;
+  _dismissedPos = null;
+}
+
+/**
+ * 设置输入法组合状态。
+ * 由 compositionstart / compositionend 事件驱动。
+ * @param {boolean} composing
+ */
+function setComposing(composing) {
+  _isComposing = composing;
+}
+
+// ── 状态读取 ──
+
+function isActive() { return _active; }
+function getAnchorPos() { return _anchorPos; }