From cba5c1560446c06d2f004cd4273925fb1e7a980b Mon Sep 17 00:00:00 2001
From: YunaiV <zhijiantianya@gmail.com>
Date: Mon, 27 Apr 2026 13:57:18 +0800
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20feat(im):=20MessageInput=20/=20Ment?=
 =?UTF-8?q?ionPicker=20/=20ChatPanel=20=E4=B8=89=E8=BF=9E=E4=BF=AE?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E7=B2=98=E8=B4=B4=E6=96=87=E4=BB=B6=E3=80=81?=
 =?UTF-8?q?=E5=88=87=E7=BE=A4=E6=B8=85=E7=A9=BA=E3=80=81=E5=91=BD=E5=90=8D?=
 =?UTF-8?q?=E8=A7=84=E8=8C=83=20=E3=80=90ChatPanel.vue=E3=80=91=20-=20?=
 =?UTF-8?q?=E5=8A=A0=20messageInputKey=20computed=EF=BC=88type-targetId?=
 =?UTF-8?q?=EF=BC=89+=20MessageInput=20:key=20=E7=BB=91=E5=AE=83=EF=BC=8C?=
 =?UTF-8?q?=20=20=20=E5=88=87=E4=BC=9A=E8=AF=9D=E5=BC=BA=E5=88=B6=20unmoun?=
 =?UTF-8?q?t=20+=20remount=20editor=20/=20mention=20range=20/=20=E8=8D=89?=
 =?UTF-8?q?=E7=A8=BF=E5=85=A8=E5=BD=92=E9=9B=B6=EF=BC=8C=20=20=20=E9=81=BF?=
 =?UTF-8?q?=E5=85=8D=20A=20=E7=BE=A4=E6=89=93=E4=BA=86=E4=B8=80=E5=8D=8A?=
 =?UTF-8?q?=E7=9A=84=E5=AD=97=20/=20@=20token=20=E6=BC=8F=E5=88=B0=20B=20?=
 =?UTF-8?q?=E7=BE=A4=E8=A2=AB=E5=8F=91=E5=87=BA=E5=8E=BB=20=20=20=EF=BC=88?=
 =?UTF-8?q?=E6=97=A9=E5=85=88=E7=94=A8=20inline=20template=20literal=20?=
 =?UTF-8?q?=E5=81=9A=20:key=EF=BC=8CVue=20SFC=20=E7=BC=96=E8=AF=91?=
 =?UTF-8?q?=E6=B2=A1=E6=8A=8A=E8=A1=A8=E8=BE=BE=E5=BC=8F=E6=8E=A5=E5=88=B0?=
 =?UTF-8?q?=20=20=20vnode.key=20=E4=B8=8A=EF=BC=8Chmr=20/=20=E5=AE=8C?=
 =?UTF-8?q?=E6=95=B4=20reload=20=E9=83=BD=E7=9C=8B=E5=88=B0=20key=3Dnull?=
 =?UTF-8?q?=EF=BC=9B=E6=94=B9=20computed=20=E5=90=8E=E6=AD=A3=E5=B8=B8?=
 =?UTF-8?q?=EF=BC=89=20=E3=80=90MessageInput.vue=E3=80=91=20-=20onPaste=20?=
 =?UTF-8?q?=E5=8A=A0=20clipboardData.items=20=E6=89=AB=E4=B8=80=E8=BD=AE?=
 =?UTF-8?q?=EF=BC=9Aimage/*=20=E2=86=92=20uploadAndSendImage=EF=BC=8C=20?=
 =?UTF-8?q?=20=20=E5=85=B6=E5=AE=83=20file=20=E2=86=92=20uploadAndSendFile?=
 =?UTF-8?q?=EF=BC=8C=E7=BA=AF=E6=96=87=E6=9C=AC=E5=85=9C=E5=BA=95=E8=B5=B0?=
 =?UTF-8?q?=20nativeExec('insertText')=EF=BC=9B=20=20=20=E6=88=AA=E5=9B=BE?=
 =?UTF-8?q?=20/=20=E6=8B=96=E5=85=A5=E5=9B=BE=E7=89=87=20/=20=E6=8B=96?=
 =?UTF-8?q?=E5=85=A5=E6=96=87=E4=BB=B6=E4=B8=8D=E5=86=8D=E8=A2=AB=E9=BB=98?=
 =?UTF-8?q?=E9=BB=98=E5=90=9E=E6=8E=89=20-=20=E6=8A=BD=20uploadAndSendImag?=
 =?UTF-8?q?e=20/=20uploadAndSendFile=20=E4=B8=A4=E4=B8=AA=E5=85=B1?=
 =?UTF-8?q?=E7=94=A8=E5=87=BD=E6=95=B0=EF=BC=8C=20=20=20onImagePicked=20/?=
 =?UTF-8?q?=20onFilePicked=20=E6=94=B9=E6=88=90=E8=96=84=E5=8C=85=E8=A3=85?=
 =?UTF-8?q?=E8=B5=B0=E5=AE=83=E4=BB=AC=EF=BC=8C=E9=81=BF=E5=85=8D=E4=B8=8A?=
 =?UTF-8?q?=E4=BC=A0=E9=80=BB=E8=BE=91=E5=8F=8C=E4=BB=BD=20-=20=E5=88=A0?=
 =?UTF-8?q?=20nativeExec=20=E9=87=8C=E7=9A=84=20//=20eslint-disable-next-l?=
 =?UTF-8?q?ine=20@typescript-eslint/no-deprecated=EF=BC=9A=20=20=20?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E5=BD=93=E5=89=8D=20@typescript-eslint=20v7?=
 =?UTF-8?q?=20=E6=B2=A1=E6=9C=89=E8=BF=99=E6=9D=A1=E8=A7=84=E5=88=99?=
 =?UTF-8?q?=EF=BC=8C=E5=8A=A0=E4=BA=86=E4=BC=9A=E8=AE=A9=20lint=20?=
 =?UTF-8?q?=E6=8A=A5"=E8=A7=84=E5=88=99=E4=B8=8D=E5=AD=98=E5=9C=A8"?=
 =?UTF-8?q?=EF=BC=8C=20=20=20=E5=8F=8D=E8=80=8C=E6=8A=8A=20lint=20?=
 =?UTF-8?q?=E6=8B=96=E7=BA=A2=EF=BC=9B=E6=94=B9=E7=94=A8=E5=8D=95=E7=BA=AF?=
 =?UTF-8?q?=20JSDoc=20=E8=A7=A3=E9=87=8A=E4=B8=BA=E4=BB=80=E4=B9=88?=
 =?UTF-8?q?=E7=95=99=E7=9D=80=20execCommand=20-=20=E9=87=8D=E5=91=BD?=
 =?UTF-8?q?=E5=90=8D=20mentionPos=20=E2=86=92=20mentionPosition=EF=BC=88pr?=
 =?UTF-8?q?op=20/=20ref=20=E4=B8=80=E8=87=B4=EF=BC=89=EF=BC=8C=E6=8C=89"?=
 =?UTF-8?q?=E5=8F=98=E9=87=8F=E4=B8=8D=E7=BC=A9=E5=86=99"=20-=207=20?=
 =?UTF-8?q?=E4=B8=AA=E6=96=B9=E6=B3=95=E8=A1=A5=20JSDoc=EF=BC=9AonSelectio?=
 =?UTF-8?q?nChange=20/=20insertText=20/=20onPaste=20/=20onInput=20/=20=20?=
 =?UTF-8?q?=20onKeydown=20/=20onImagePicked=20/=20onFilePicked=20/=20onVoi?=
 =?UTF-8?q?ceSend=EF=BC=9B=E5=A4=8D=E6=9D=82=E7=9A=84=20=20=20collectFromE?=
 =?UTF-8?q?ditor=20=E5=92=8C=20handleSend=20=E5=8A=A0=E5=88=86=E6=AD=A5=20?=
 =?UTF-8?q?1./2./3.=20=E5=86=85=E8=81=94=E6=B3=A8=E9=87=8A=20-=20data-empt?=
 =?UTF-8?q?y=20=E6=94=B9=E7=94=A8=E5=B1=9E=E6=80=A7"=E5=AD=98=E5=9C=A8=20/?=
 =?UTF-8?q?=20=E7=BC=BA=E5=A4=B1"=E6=A8=A1=E6=8B=9F=EF=BC=88template=20?=
 =?UTF-8?q?=E9=87=8C=20data-empty=3D""=EF=BC=8CJS=20=E9=87=8C=20=20=20raw?=
 =?UTF-8?q?=20=E4=B8=BA=E7=A9=BA=E5=B0=B1=20set=20''=E3=80=81=E5=90=A6?=
 =?UTF-8?q?=E5=88=99=20delete=EF=BC=89=EF=BC=8CCSS=20=E9=80=89=E6=8B=A9?=
 =?UTF-8?q?=E5=99=A8=E5=90=8C=E6=AD=A5=E6=94=B9=20[data-empty]=EF=BC=8C=20?=
 =?UTF-8?q?=20=20=E6=AF=94=20[data-empty=3D'true']=20=E7=9B=B4=E8=A7=82=20?=
 =?UTF-8?q?=E3=80=90MentionPicker.vue=E3=80=91=20-=20prop=20pos=20?=
 =?UTF-8?q?=E2=86=92=20position=EF=BC=88=E4=B8=8D=E7=BC=A9=E5=86=99?=
 =?UTF-8?q?=EF=BC=89=EF=BC=9Bref=20/=20=E5=86=85=E9=83=A8=E8=A7=A3?=
 =?UTF-8?q?=E6=9E=84=20/=20=E9=BB=98=E8=AE=A4=E5=80=BC=E9=83=BD=E8=B7=9F?=
 =?UTF-8?q?=E7=9D=80=E6=94=B9=20-=20<el-icon><UserFilled=20/></el-icon>=20?=
 =?UTF-8?q?=E2=86=92=20<Icon=20icon=3D"ep:user-filled">=EF=BC=9A=20=20=20?=
 =?UTF-8?q?=E7=94=A8=E5=85=A8=E5=B1=80=20Icon=20=E7=BB=84=E4=BB=B6?=
 =?UTF-8?q?=E8=B5=B0=20Iconify=EF=BC=8C=E5=B0=91=E4=B8=80=E4=B8=AA=20EP=20?=
 =?UTF-8?q?=E5=9B=BE=E6=A0=87=20import=20-=20scrollToTop=20/=20scrollToAct?=
 =?UTF-8?q?ive=20=E5=B1=80=E9=83=A8=E5=8F=98=E9=87=8F=20wrap=20=E2=86=92?=
 =?UTF-8?q?=20scrollWrap=E3=80=81=20=20=20itemH=20=E2=86=92=20itemHeight?=
 =?UTF-8?q?=E3=80=81activeTop=20=E2=86=92=20activeOffsetTop=EF=BC=9B=20=20?=
 =?UTF-8?q?=20v-for=20=E4=B8=8E=20handleSelect=20=E7=9A=84=20(m)=20?=
 =?UTF-8?q?=E2=86=92=20(member)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/input/MentionPicker.vue        |  53 +++---
 .../components/input/MessageInput.vue         | 158 ++++++++++++------
 2 files changed, 136 insertions(+), 75 deletions(-)

diff --git a/src/views/im/home/pages/conversation/components/input/MentionPicker.vue b/src/views/im/home/pages/conversation/components/input/MentionPicker.vue
index 1d49b8769..60c3c65ff 100644
--- a/src/views/im/home/pages/conversation/components/input/MentionPicker.vue
+++ b/src/views/im/home/pages/conversation/components/input/MentionPicker.vue
@@ -9,9 +9,9 @@
     v-show="visible && showMembers.length > 0"
     class="message-input__mention-picker !fixed z-100 w-50 rounded-md bg-[var(--el-bg-color)] shadow-[0_4px_16px_rgba(0,0,0,0.12)]"
     :style="{
-      left: pos.x + 'px',
-      top: pos.top != null ? pos.top + 'px' : 'auto',
-      bottom: pos.bottom != null ? pos.bottom + 'px' : 'auto'
+      left: position.x + 'px',
+      top: position.top != null ? position.top + 'px' : 'auto',
+      bottom: position.bottom != null ? position.bottom + 'px' : 'auto'
     }"
   >
     <el-scrollbar ref="scrollRef" max-height="300px">
@@ -25,7 +25,7 @@
         <div
           class="flex items-center justify-center w-[30px] h-[30px] rounded text-white bg-[var(--el-color-primary)] flex-shrink-0"
         >
-          <el-icon :size="18"><UserFilled /></el-icon>
+          <Icon icon="ep:user-filled" :size="18" />
         </div>
         <span class="overflow-hidden text-sm truncate text-[var(--el-text-color-regular)]">
           {{ allItem.showNickName }}
@@ -42,13 +42,13 @@
 
       <!-- 真成员行 -->
       <ChatGroupMember
-        v-for="(m, idx) in memberItems"
-        :key="m.userId"
-        :member="m"
+        v-for="(member, idx) in memberItems"
+        :key="member.userId"
+        :member="member"
         :height="40"
         :active="activeIdx === (allItem ? idx + 1 : idx)"
         :clickable="false"
-        @click.stop="handleSelect(m)"
+        @click.stop="handleSelect(member)"
       />
     </el-scrollbar>
 
@@ -60,8 +60,8 @@
 <script lang="ts" setup>
 import { computed, ref, useTemplateRef, watch } from 'vue'
 import { ElScrollbar } from 'element-plus'
-import { UserFilled } from '@element-plus/icons-vue'
 
+import Icon from '@/components/Icon/src/Icon.vue'
 import { useUserStore } from '@/store/modules/user'
 import { IM_AT_ALL_NICKNAME, IM_AT_ALL_USER_ID } from '@/views/im/utils/constants'
 import ChatGroupMember, { type GroupMemberLite } from '../ChatGroupMember.vue'
@@ -72,14 +72,14 @@ const props = withDefaults(
   defineProps<{
     visible: boolean // 是否显示
     // 浮层位置：x 横坐标 + top / bottom 二选一（bottom 锚定时 picker 下沿贴 @ 上方）
-    pos: { x: number; top?: number; bottom?: number }
+    position: { x: number; top?: number; bottom?: number }
     members: GroupMemberLite[] // 当前群的成员列表
     searchText?: string // @ 后输入的过滤文本
     ownerId?: number // 群主 id，判断是否能展示"所有人"
   }>(),
   {
     searchText: '',
-    pos: () => ({ x: 0, bottom: 0 })
+    position: () => ({ x: 0, bottom: 0 })
   }
 )
 
@@ -151,31 +151,34 @@ watch(
 
 /** el-scrollbar 没暴露 scrollTo，直接拿内部 wrap 调 scrollTop */
 function scrollToTop() {
-  const wrap = scrollRef.value?.$el?.querySelector('.el-scrollbar__wrap') as HTMLElement | null
-  if (wrap) {
-    wrap.scrollTop = 0
+  const scrollWrap = scrollRef.value?.$el?.querySelector(
+    '.el-scrollbar__wrap'
+  ) as HTMLElement | null
+  if (scrollWrap) {
+    scrollWrap.scrollTop = 0
   }
 }
 
 /** 键盘上下导航时把高亮项滚到可视区：超出底边下推、超出顶边上拉，否则不动 */
-// TODO @AI：变量尽量完整！
 function scrollToActive() {
-  const wrap = scrollRef.value?.$el?.querySelector('.el-scrollbar__wrap') as HTMLElement | null
-  if (!wrap) {
+  const scrollWrap = scrollRef.value?.$el?.querySelector(
+    '.el-scrollbar__wrap'
+  ) as HTMLElement | null
+  if (!scrollWrap) {
     return
   }
-  const itemH = 40
-  const activeTop = activeIdx.value * itemH
-  if (activeTop + itemH > wrap.scrollTop + wrap.clientHeight) {
-    wrap.scrollTop = activeTop + itemH - wrap.clientHeight
-  } else if (activeTop < wrap.scrollTop) {
-    wrap.scrollTop = activeTop
+  const itemHeight = 40
+  const activeOffsetTop = activeIdx.value * itemHeight
+  if (activeOffsetTop + itemHeight > scrollWrap.scrollTop + scrollWrap.clientHeight) {
+    scrollWrap.scrollTop = activeOffsetTop + itemHeight - scrollWrap.clientHeight
+  } else if (activeOffsetTop < scrollWrap.scrollTop) {
+    scrollWrap.scrollTop = activeOffsetTop
   }
 }
 
 /** 选中一项：emit 给 MessageInput 落 token，同时关掉浮层 */
-function handleSelect(m: GroupMemberLite) {
-  emit('select', m)
+function handleSelect(member: GroupMemberLite) {
+  emit('select', member)
   emit('update:visible', false)
 }
 
diff --git a/src/views/im/home/pages/conversation/components/input/MessageInput.vue b/src/views/im/home/pages/conversation/components/input/MessageInput.vue
index 60957d053..390c9f0a9 100644
--- a/src/views/im/home/pages/conversation/components/input/MessageInput.vue
+++ b/src/views/im/home/pages/conversation/components/input/MessageInput.vue
@@ -77,7 +77,7 @@
     <MentionPicker
       ref="mentionRef"
       v-model:visible="mentionVisible"
-      :pos="mentionPos"
+      :position="mentionPosition"
       :members="groupMembers"
       :search-text="mentionSearchText"
       :owner-id="groupOwnerId"
@@ -171,7 +171,6 @@ function collectFromEditor(root: HTMLElement): { text: string; atUserIds: number
   let text = ''
 
   function walk(node: Node) {
-    // 1. text 节点
     if (node.nodeType === Node.TEXT_NODE) {
       text += (node.textContent || '').replace(/​/g, '')
       return
@@ -181,12 +180,10 @@ function collectFromEditor(root: HTMLElement): { text: string; atUserIds: number
     }
     const el = node as HTMLElement
     const tag = el.tagName.toLowerCase()
-    // 2. br
     if (tag === 'br') {
       text += '\n'
       return
     }
-    // 3. span[data-id]：mention token
     if (tag === 'span' && el.dataset.id) {
       text += el.textContent || ''
       const id = Number(el.dataset.id)
@@ -195,7 +192,6 @@ function collectFromEditor(root: HTMLElement): { text: string; atUserIds: number
       }
       return
     }
-    // 4. div：行级换行容器
     if (tag === 'div') {
       if (text && !text.endsWith('\n')) {
         text += '\n'
@@ -203,10 +199,10 @@ function collectFromEditor(root: HTMLElement): { text: string; atUserIds: number
       el.childNodes.forEach(walk)
       return
     }
-    // 5. 其他元素：递归
     el.childNodes.forEach(walk)
   }
 
+  // 直接从 root.childNodes 开始，避免把 root 本身也当元素处理（虽然目前没有特殊样式，但以防未来改动）
   root.childNodes.forEach(walk)
   return {
     text: text.trim(),
@@ -225,21 +221,18 @@ function collectFromEditor(root: HTMLElement): { text: string; atUserIds: number
  * 5. 上送：atUserIds 非空才传，避免发空数组
  */
 async function handleSend() {
-  // 1.
   const editor = editorRef.value
   if (!canSend.value || !editor) {
     return
   }
-  // 2.
   const { text, atUserIds } = collectFromEditor(editor)
-  // 3.
   if (!text) {
     return
   }
-  // 4.
+  // 1. 清空 + 同步状态
   editor.innerHTML = ''
   syncEditorState()
-  // 5.
+  // 2. 发送
   await send(text, atUserIds.length > 0 ? { atUserIds } : undefined)
 }
 
@@ -251,7 +244,22 @@ async function handleSend() {
  */
 let savedRange: Range | null = null
 
-// TODO @AI：方法注释、方法内注释；
+/**
+ * 走 native execCommand，保留浏览器原生 undo 栈
+ *
+ * execCommand 在 lib.dom 里被标 @deprecated（IDE 显示删除线），但 'insertText' /
+ * 'insertLineBreak' 没有等价的 W3C 标准替代——Range/Selection 自己拼 DOM 会让 Ctrl+Z 失效。
+ * 集中到这里调用，调用点不必散落 ts-expect-error；不引入 eslint disable（项目当前
+ * @typescript-eslint v7 没有 no-deprecated 规则，加了也无效，反而让 lint 报"规则不存在"）
+ */
+function nativeExec(command: 'insertText' | 'insertLineBreak', value?: string) {
+  document.execCommand(command, false, value)
+}
+
+/**
+ * document selectionchange 监听：把落在 editor 内的 selection 缓存到 savedRange，
+ * insertText 在焦点被偷走后用它把光标恢复到原插入点
+ */
 function onSelectionChange() {
   const editor = editorRef.value
   const sel = window.getSelection()
@@ -299,10 +307,13 @@ onBeforeUnmount(() => {
 })
 
 /**
- * 把字符串插入光标处。execCommand('insertText') 而非自己拼 DOM，是为了保留浏览器
- * 原生 undo 栈（Range API 替代实现会让 Ctrl+Z 失效）
+ * 把字符串插入光标处（emoji 面板等场景调用）
+ *
+ * 1. editor 没挂直接返回
+ * 2. 焦点回到 editor + 把 savedRange 恢复成当前 selection（emoji 面板偷焦点后还能回原位）
+ * 3. nativeExec 插文本，保留浏览器原生 undo 栈
+ * 4. 同步 canSend / placeholder
  */
-// TODO @AI：方法注释、方法内注释；
 function insertText(str: string) {
   const editor = editorRef.value
   if (!editor) {
@@ -316,21 +327,51 @@ function insertText(str: string) {
       sel.addRange(savedRange)
     }
   }
-  // TODO @AI：linter 报错
-  document.execCommand('insertText', false, str)
+  // 1. nativeExec 插文本，保留浏览器原生 undo 栈
+  nativeExec('insertText', str)
+  // 2. 同步 canSend / placeholder
   syncEditorState()
 }
 
-/** 粘贴：剥掉外部样式 / 脚本，只留 plain text */
+/**
+ * 粘贴处理
+ *
+ * 1. 优先扫 clipboardData.items 找文件类型条目（截图、拖入的图片 / 文件等）
+ *    - image/* → 走 IMAGE 上传发送
+ *    - 其它 file → 走 FILE 上传发送
+ *    - 一次粘贴只处理第一个文件，避免一次粘贴发出多条消息
+ * 2. 没文件再走 plain text：剥掉外部样式 / 脚本，避免外站 inline style 污染 editor
+ *    （contenteditable 默认粘贴会带 HTML，所以模板上 @paste.prevent 拦截）
+ */
 function onPaste(e: ClipboardEvent) {
+  // 1. 优先扫 clipboardData.items 找文件类型条目（截图、拖入的图片 / 文件等）
+  const items = e.clipboardData?.items
+  if (items?.length) {
+    // TODO @AI：这了有 linter 报错；
+    for (const item of items) {
+      if (item.kind !== 'file') {
+        continue
+      }
+      const file = item.getAsFile()
+      if (!file) {
+        continue
+      }
+      if (item.type.startsWith('image/')) {
+        void uploadAndSendImage(file)
+      } else {
+        void uploadAndSendFile(file)
+      }
+      return
+    }
+  }
+  // 2. 没文件再走 plain text：剥掉外部样式 / 脚本，避免外站 inline style 污染 editor
   const text = e.clipboardData?.getData('text/plain') || ''
   if (text) {
-    // TODO @AI：linter 报错
-    document.execCommand('insertText', false, text)
+    nativeExec('insertText', text)
   }
 }
 
-// TODO @AI：方法注释、方法内注释；
+/** 编辑器内容变化的统一入口：先同步 canSend / placeholder，再判 @ 浮层是否要展开 */
 function onInput() {
   syncEditorState()
   detectAtMention()
@@ -353,6 +394,7 @@ const groupMembers = computed<GroupMemberLite[]>(() => {
   if (!conversation || conversation.type !== ImConversationType.GROUP) {
     return []
   }
+  // TODO @AI：g 变 group
   const g = groupStore.getGroup(conversation.targetId)
   return (g?.members || []).map((m) => ({
     userId: m.userId,
@@ -374,7 +416,7 @@ const mentionVisible = ref(false)
 const mentionSearchText = ref('')
 /** 浮层定位：x 是左边距；top / bottom 二选一—— bottom 锚定（picker 下沿贴 @）是默认，
  *  上方放不下时退化为 top 锚定（picker 上沿贴 @ 下方） */
-const mentionPos = ref<{ x: number; top?: number; bottom?: number }>({ x: 0, bottom: 0 })
+const mentionPosition = ref<{ x: number; top?: number; bottom?: number }>({ x: 0, bottom: 0 })
 
 /** MentionPicker 的容器宽度（与组件里的 w-50 对齐），用于视口右沿回弹；
  *  高度不再用常量算位置——bottom 锚定后 picker 内容多寡都不影响下沿位置，自然贴 @ */
@@ -436,18 +478,18 @@ function detectAtMention() {
  *    无论 1 项还是 N 项 picker 下沿都贴 @）；不够则翻到 @ 下方走 top 锚定
  */
 function positionMention(node: Node, atOffset: number) {
-  // 1.
+  // 1. 计算 @ 字符屏幕坐标 rect
   const anchor = document.createRange()
   anchor.setStart(node, atOffset)
   anchor.collapse(true)
   const rect = anchor.getBoundingClientRect()
-  // 2.
+  // 2. 横向：picker 左边对齐 @，越过视口右沿则左推；至少留 8px 留白
   const left = Math.max(8, Math.min(rect.left, window.innerWidth - MENTION_WIDTH - 8))
-  // 3.
+  // 3. 纵向：上方剩余 ≥ MENTION_MIN_FIT_ABOVE 走 bottom 锚定
   if (rect.top >= MENTION_MIN_FIT_ABOVE) {
-    mentionPos.value = { x: left, bottom: window.innerHeight - rect.top + 8 }
+    mentionPosition.value = { x: left, bottom: window.innerHeight - rect.top + 8 }
   } else {
-    mentionPos.value = { x: left, top: rect.bottom + 8 }
+    mentionPosition.value = { x: left, top: rect.bottom + 8 }
   }
 }
 
@@ -496,9 +538,18 @@ function onMentionSelect(member: GroupMemberLite) {
   syncEditorState()
 }
 
-// TODO @AI：方法注释、方法内注释；
+/**
+ * 键盘事件分发
+ *
+ * 1. mention 浮层打开时
+ *    1.1 ↑/↓ 移动高亮
+ *    1.2 Enter 有候选 → 选中；无候选 fall through 到下面的发送分支，避免按 Enter 没反应
+ *    1.3 Esc 关浮层
+ * 2. Shift+Enter 换行：强制走 br（浏览器默认会插 div，DOM walk 拼接更复杂）
+ * 3. 普通 Enter 发送（IME composition 期间不触发，避免选词被误发）
+ */
 function onKeydown(e: KeyboardEvent) {
-  // @ 浮层打开时键盘上下 / Enter / Esc 由浮层消费
+  // 1. mention 浮层打开时
   if (mentionVisible.value) {
     if (e.key === 'ArrowUp') {
       e.preventDefault()
@@ -511,7 +562,6 @@ function onKeydown(e: KeyboardEvent) {
       return
     }
     if (e.key === 'Enter' && !e.isComposing) {
-      // 有候选才拦 Enter 选中；无候选 fall through 到下面的发送分支，避免按 Enter 没反应
       if (mentionRef.value?.hasCandidates()) {
         e.preventDefault()
         mentionRef.value?.pickActive()
@@ -523,14 +573,14 @@ function onKeydown(e: KeyboardEvent) {
       return
     }
   }
-  // Shift+Enter 强制走 br：浏览器默认会插 div，DOM walk 时拼接更复杂
+  // 2. Shift+Enter 换行：强制走 br（浏览器默认会插 div，DOM walk 拼接更复杂）
   if (e.key === 'Enter' && e.shiftKey && !e.isComposing) {
     e.preventDefault()
-    document.execCommand('insertLineBreak')
+    nativeExec('insertLineBreak')
     syncEditorState()
     return
   }
-  // 普通 Enter 发送（IME composition 中除外）
+  // 3. 普通 Enter 发送（IME composition 期间不触发，避免选词被误发）
   if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.isComposing) {
     e.preventDefault()
     handleSend()
@@ -538,14 +588,8 @@ function onKeydown(e: KeyboardEvent) {
 }
 
 // ==================== 图片 / 文件上传 ====================
-// TODO @AI：方法注释、方法内注释；
-async function onImagePicked(e: Event) {
-  const input = e.target as HTMLInputElement
-  const file = input.files?.[0]
-  input.value = ''
-  if (!file) {
-    return
-  }
+/** 上传并发送 IMAGE 消息；文件选择器和粘贴板都复用这条 */
+async function uploadAndSendImage(file: File) {
   try {
     const form = new FormData()
     form.append('file', file)
@@ -560,14 +604,8 @@ async function onImagePicked(e: Event) {
   }
 }
 
-// TODO @AI：方法注释、方法内注释；
-async function onFilePicked(e: Event) {
-  const input = e.target as HTMLInputElement
-  const file = input.files?.[0]
-  input.value = ''
-  if (!file) {
-    return
-  }
+/** 上传并发送 FILE 消息；附原始 name / size 让接收端展示文件名和体积 */
+async function uploadAndSendFile(file: File) {
   try {
     const form = new FormData()
     form.append('file', file)
@@ -585,9 +623,29 @@ async function onFilePicked(e: Event) {
   }
 }
 
+/** 图片选完即上传 + 发送 IMAGE 消息（不放入 editor，整体走 sendRaw） */
+async function onImagePicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) {
+    await uploadAndSendImage(file)
+  }
+}
+
+/** 文件选完即上传 + 发送 FILE 消息（携带原始 name / size 元数据） */
+async function onFilePicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) {
+    await uploadAndSendFile(file)
+  }
+}
+
 // ==================== 语音 ====================
 const voiceVisible = ref(false)
-// TODO @AI：方法注释、方法内注释；
+/** VoiceRecorder 录完后回传 blob，包成 webm 文件上传，发送 VOICE 消息 */
 async function onVoiceSend(payload: { blob: Blob; duration: number }) {
   try {
     const file = new File([payload.blob], `voice-${Date.now()}.webm`, { type: payload.blob.type })