dsh-workbuddy-files 0.1.0

package/src/client/components/overlay.tsx

@@ -0,0 +1,36 @@
+import type { DropBus } from '../lib/bus'
+
+/** 组件只需 React 的这三个能力；由 app.ts 的 factory 通过 require('react') 注入 */
+export interface ReactLike {
+  createElement(type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]): unknown
+  useState<T>(initial: T | (() => T)): [T, (next: T | ((prev: T) => T)) => void]
+  useEffect(effect: () => void | (() => void), deps?: readonly unknown[]): void
+}
+
+/**
+ * 全屏拖拽遮罩 + toast（挂在 shell.overlay 列表槽）。
+ * 遮罩只在拖拽含非图片文件/文件夹时出现（纯图片拖放交给原生图片轨道）；
+ * 层本身点击穿透，遮罩激活时开启 pointer-events 承接 drop。
+ */
+export function createOverlayComponent(React: ReactLike, bus: DropBus) {
+  return function WorkbuddyOverlay() {
+    const [state, setState] = React.useState(bus.get())
+    React.useEffect(() => bus.subscribe(setState), [])
+
+    return React.createElement('div', { className: 'wbd-overlay' },
+      state.active
+        ? React.createElement('div', { className: 'wbd-shield' },
+          React.createElement('div', { className: 'wbd-shield-inner' },
+            React.createElement('div', { className: 'wbd-shield-icon' }, '📥'),
+            React.createElement('div', { className: 'wbd-shield-title' }, '松开以接收文件'),
+            React.createElement('div', { className: 'wbd-shield-sub' }, state.count + ' 项 · 将作为引用气泡插入输入框光标处'),
+            React.createElement('div', { className: 'wbd-shield-hint' }, '文件（含图片）将缓存至 ~/.dsh-drops 并引用绝对路径'),
+          ),
+        )
+        : null,
+      state.toast
+        ? React.createElement('div', { className: 'wbd-toast' + (state.toast.level === 'error' ? ' wbd-error' : '') }, state.toast.text)
+        : null,
+    )
+  }
+}

package/src/client/components/pick-button.tsx

@@ -0,0 +1,55 @@
+import type { DropBus } from '../lib/bus'
+import type { DropHandlers } from '../lib/drop'
+import type { TreeFile } from '../types'
+import type { ReactLike } from './overlay'
+
+/**
+ * 📎 引用按钮（挂在 conversation.input.left 列表槽）：
+ * 统一走 <input type=file>（多选 / webkitdirectory）→ 立即插入气泡 →
+ * 后台缓存（所有浏览器行为一致）。
+ */
+export function createPickButtonComponent(React: ReactLike, bus: DropBus, handlers: Pick<DropHandlers, 'acceptTree'>) {
+  return function PickButton() {
+    const [open, setOpen] = React.useState(false)
+    const newBatch = () => 'drop-' + Date.now().toString(36)
+
+    const pickFolder = async () => {
+      setOpen(false)
+      const input = document.createElement('input')
+      input.type = 'file'
+      input.setAttribute('webkitdirectory', '')
+      input.onchange = () => {
+        const files: TreeFile[] = []
+        const tops: string[] = []
+        for (const f of Array.from(input.files ?? [])) {
+          files.push({ rel: f.webkitRelativePath || f.name, name: f.name, size: f.size, file: f })
+          const top = (f.webkitRelativePath || '').split('/')[0]
+          if (top !== '' && !tops.includes(top)) tops.push(top)
+        }
+        if (files.length > 0) void handlers.acceptTree(files, tops, newBatch())
+      }
+      input.click()
+    }
+
+    const pickFiles = async () => {
+      setOpen(false)
+      const input = document.createElement('input')
+      input.type = 'file'
+      input.multiple = true
+      input.onchange = () => {
+        const files: TreeFile[] = []
+        for (const f of Array.from(input.files ?? [])) files.push({ rel: f.name, name: f.name, size: f.size, file: f })
+        if (files.length > 0) void handlers.acceptTree(files, [], newBatch())
+      }
+      input.click()
+    }
+
+    return React.createElement('div', { className: 'wbd-pick' },
+      React.createElement('button', { type: 'button', className: 'wbd-pick-btn', title: '引用文件/文件夹（也可直接拖拽或粘贴）', onClick: () => setOpen(!open) }, '📎'),
+      open ? React.createElement('div', { className: 'wbd-pick-menu' },
+        React.createElement('button', { type: 'button', onClick: pickFiles }, '选择文件…'),
+        React.createElement('button', { type: 'button', onClick: pickFolder }, '选择文件夹…（保留目录树）'),
+      ) : null,
+    )
+  }
+}

package/src/client/css.ts

@@ -0,0 +1,32 @@
+/** 包内样式（styles.insert 注入，随插件 Run 生命周期清理） */
+export const CSS = [
+  '.wbd-overlay{position:fixed;inset:0;pointer-events:none;z-index:2147483000}',
+  '.wbd-shield{position:fixed;inset:0;pointer-events:auto;display:flex;align-items:center;justify-content:center;background:color-mix(in srgb,var(--dsw-color-bg,#0e1116) 72%,transparent);backdrop-filter:blur(2px)}',
+  '.wbd-shield-inner{min-width:340px;max-width:520px;padding:28px 36px;text-align:center;border:2px dashed var(--dsw-alias-border-l3,#4c9aff);border-radius:14px;background:var(--dsw-color-bg-elevated,#161b24);box-shadow:0 12px 48px rgba(0,0,0,.45)}',
+  '.wbd-shield-icon{font-size:34px;line-height:1}',
+  '.wbd-shield-title{margin-top:10px;font-size:17px;font-weight:600;color:var(--dsw-alias-label-primary,#f2f4f8)}',
+  '.wbd-shield-sub{margin-top:6px;font-size:13px;color:var(--dsw-alias-label-secondary,#aab2c0)}',
+  '.wbd-shield-hint{margin-top:10px;font-size:12px;color:var(--dsw-alias-label-tertiary,#6b7280)}',
+  '.wbd-toast{position:fixed;right:24px;bottom:132px;max-width:360px;padding:9px 14px;border-radius:10px;background:var(--dsw-color-bg-elevated,#1c222e);border:1px solid var(--dsw-alias-border-l3,#3a4252);color:var(--dsw-alias-label-primary,#f2f4f8);font-size:13px;box-shadow:0 8px 28px rgba(0,0,0,.35);pointer-events:auto}',
+  '.wbd-toast.wbd-error{border-color:#b3453f}',
+  '.wbd-cards{display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin:14px 0 4px;font-size:13px}',
+  '.wbd-cards-label{color:var(--dsw-alias-label-tertiary,#6b7280);margin-right:4px}',
+  '.wbd-card{display:inline-flex;align-items:center;gap:7px;max-width:340px;padding:4px 10px 4px 8px;border:1px solid var(--dsw-alias-border-l2,#2c3342);border-radius:8px;background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.04));color:var(--dsw-alias-label-primary,#f2f4f8);font:inherit;font-size:13px;cursor:pointer;text-align:left}',
+  '.wbd-card:hover{border-color:var(--dsw-alias-border-l3,#4c9aff)}',
+  '.wbd-card-icon{flex:none;font-size:15px}',
+  '.wbd-card-name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+  '.wbd-card-sub{flex:none;color:var(--dsw-alias-label-tertiary,#6b7280);font-size:12px}',
+  '.wbd-pick{position:relative;display:inline-flex}',
+  '.wbd-pick-btn{display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;border:none;border-radius:8px;background:transparent;color:var(--dsw-alias-label-secondary,#aab2c0);font-size:15px;cursor:pointer}',
+  '.wbd-pick-btn:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.06));color:var(--dsw-alias-label-primary,#f2f4f8)}',
+  '.wbd-pick-menu{position:absolute;left:0;bottom:calc(100% + 8px);display:flex;flex-direction:column;min-width:220px;padding:6px;border-radius:10px;border:1px solid var(--dsw-alias-border-l2,#2c3342);background:var(--dsw-color-bg-elevated,#1c222e);box-shadow:0 10px 32px rgba(0,0,0,.4);z-index:10}',
+  '.wbd-pick-menu button{display:block;width:100%;padding:8px 10px;border:none;border-radius:6px;background:transparent;color:var(--dsw-alias-label-primary,#f2f4f8);font:inherit;font-size:13px;text-align:left;cursor:pointer}',
+  '.wbd-pick-menu button:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.06))}',
+  '/* ---- 引用气泡换肤：主题色圆角矩形（原子删除由输入机原生保证） ---- */',
+  '/* 关键：padding 用等量负 margin 抵消、描边用 box-shadow（不占布局）—— */',
+  '/* 气泡外部宽度与 textarea 字符宽度完全一致，backdrop 与光标严格对齐 */',
+  '[data-decoration="chip"]{padding:0 8px !important;margin:0 -8px !important;border-radius:8px;background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4c9aff) 14%,transparent) !important;box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--dsw-alias-brand-primary,#4c9aff) 45%,transparent);color:var(--dsw-alias-brand-primary,#4c9aff) !important;font-weight:500}',
+  '[data-decoration="chip"]:hover{background:color-mix(in srgb,var(--dsw-alias-brand-primary,#4c9aff) 22%,transparent) !important}',
+  '[data-decoration="chip"][data-invalid="true"]{color:var(--dsw-alias-state-error-primary,#e56a64) !important;background:color-mix(in srgb,var(--dsw-alias-state-error-primary,#e56a64) 14%,transparent) !important;box-shadow:inset 0 0 0 1px color-mix(in srgb,var(--dsw-alias-state-error-primary,#e56a64) 45%,transparent) !important}',
+  '[data-decoration="chip"] [class*="chipTriggerGlyph"]{font-size:12px;opacity:.8}',
+].join('\n')

package/src/client/definitions.ts

@@ -0,0 +1,83 @@
+import { extractRefs } from './lib/transfer'
+
+/**
+ * 会话事件定义（conversationEvents 注册表）—— 按轮次聚合用户消息中的
+ * 文件引用，发布为 Turn 级位置数据，供 turnTail 文件卡片的 selector
+ * 无快照、纯数据地判断「这一轮是否渲染卡片」。
+ *
+ * 关联规则：turn/start 时通过 reader.previous 取最近的前置用户消息上下文；
+ * 结合 turn 边界定义（workbuddy-turn-boundary）排除「无用户消息的轮次
+ * （如 goal 轮）」错误继承上一轮引用的情况。
+ */
+export interface UserMessageEvent {
+  type: 'user/message'
+  seq: number
+  data: {
+    id: string
+    source: { kind: string }
+    content: ReadonlyArray<{ type: string; text?: string }>
+  }
+}
+
+export interface TurnBoundaryEvent {
+  type: 'turn/start' | 'turn/end'
+  seq: number
+  data: { turn: number }
+}
+
+export const boundaryDef = {
+  kind: 'workbuddy-turn-boundary',
+  match: (event: { type: string; data: { turn: number } }) =>
+    event.type === 'turn/start' ? { id: String(event.data.turn), role: 'start' as const }
+      : event.type === 'turn/end' ? { id: String(event.data.turn), role: 'update' as const }
+        : null,
+  start: (_context: unknown, match: { event: TurnBoundaryEvent }) => {
+    if (match.event.type !== 'turn/start') throw new Error('workbuddy-turn-boundary start requires turn/start')
+    return { turn: match.event.data.turn, startSeq: match.event.seq }
+  },
+  update: (context: { state: unknown }) => context.state,
+}
+
+export const fileRefsDef = {
+  kind: 'workbuddy-file-refs',
+  match: (event: { type: string; seq: number; data: { id?: string; turn?: number; source?: { kind: string }; content?: ReadonlyArray<{ type: string; text?: string }> } }) => {
+    if (event.type === 'user/message' && event.data?.source?.kind === 'user' && event.data.id !== undefined) {
+      return { id: String(event.data.id), role: 'start' as const }
+    }
+    if (event.type === 'turn/start' && event.data.turn !== undefined) {
+      return { id: 'turn-' + String(event.data.turn), role: 'start' as const }
+    }
+    return null
+  },
+  start: (context: { state: unknown }, match: { event: UserMessageEvent | TurnBoundaryEvent }, reader: { previous(kind: string): { startSeq: number; state: unknown } | undefined }) => {
+    if (match.event.type === 'turn/start') {
+      let refs: string[] = []
+      const prev = reader.previous('workbuddy-file-refs')
+      const prevBoundary = reader.previous('workbuddy-turn-boundary')
+      if (prev !== undefined && prev.state !== undefined && Array.isArray((prev.state as { refs?: unknown }).refs)) {
+        const afterBoundary = prevBoundary === undefined || prevBoundary.state === undefined || prev.startSeq > prevBoundary.startSeq
+        if (afterBoundary) refs = (prev.state as { refs: string[] }).refs
+      }
+      return { turn: match.event.data.turn, refs }
+    }
+    void context
+    const ev = match.event as UserMessageEvent
+    return { seq: ev.seq, refs: extractRefs(ev.data?.content ?? []) }
+  },
+  update: (context: { state: unknown }) => context.state,
+  buildLocationData: (context: { state: unknown }, scope: string) => {
+    if (scope !== 'turn') return null
+    const s = context.state as { turn?: number; refs?: string[] } | undefined
+    if (s === undefined || s.turn === undefined || !Array.isArray(s.refs) || s.refs.length === 0) return null
+    return { kind: 'turn', turn: s.turn, key: 'workbuddy-file-refs', value: { refs: s.refs } }
+  },
+}
+
+/** turnTail chain selector：仅当该轮次存在文件引用时返回 matched，避免抢占其他链条目 */
+export function selectTurnFileRefs(owner: { turn?: { data: { get(key: string): { refs?: string[] } | undefined } } } | null | undefined): { refs: string[] } | null {
+  const t = owner !== null && owner !== undefined ? owner.turn : undefined
+  if (t === undefined || t.data === undefined || typeof t.data.get !== 'function') return null
+  const data = t.data.get('workbuddy-file-refs')
+  if (data === undefined || data === null || !Array.isArray(data.refs) || data.refs.length === 0) return null
+  return { refs: data.refs }
+}

package/src/client/index.ts

@@ -0,0 +1,15 @@
+// Client 半侧 bundle 外壳：由 tsdown 构建为 lib/client.js。
+// 必须是一个「普通副作用脚本」——加载时调用 window.__ModuleLoader__.load，
+// 不能包含顶层 ESM export / import（react 由 factory 的 require 取得）。
+import { makeFactory } from './app'
+
+declare const window: {
+  __ModuleLoader__: {
+    load(info: { id: string; factory: (require: (m: string) => unknown) => unknown }): void
+  }
+}
+
+window.__ModuleLoader__.load({
+  id: 'dsh-workbuddy-files',
+  factory: makeFactory() as never,
+})

package/src/client/lib/bus.ts

@@ -0,0 +1,34 @@
+import type { BusState } from '../types'
+
+/**
+ * 拖拽遮罩 / toast 的轻量发布订阅总线。
+ * 动态（dynamic）插件里同一逻辑内联在 apply 中；这里抽成模块便于测试。
+ */
+export interface DropBus {
+  get(): BusState
+  set(next: BusState): void
+  subscribe(fn: (s: BusState) => void): () => void
+  toast(text: string, level?: 'info' | 'error'): void
+}
+
+export function createDropBus(): DropBus {
+  let state: BusState = { active: false, count: 0, toast: null }
+  const subs = new Set<(s: BusState) => void>()
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const get = () => state
+  const set = (next: BusState) => {
+    state = next
+    for (const fn of subs) fn(state)
+  }
+  const subscribe = (fn: (s: BusState) => void) => {
+    subs.add(fn)
+    return () => { subs.delete(fn) }
+  }
+  const toast = (text: string, level: 'info' | 'error' = 'info') => {
+    if (timer !== null) clearTimeout(timer)
+    set({ ...state, toast: { text: String(text), level } })
+    timer = setTimeout(() => { timer = null; set({ ...state, toast: null }) }, 4600)
+  }
+  return { get, set, subscribe, toast }
+}

package/src/client/lib/drop.ts

@@ -0,0 +1,235 @@
+import type { InsertItem, TreeFile, UploadJob } from '../types'
+import type { DropBus } from './bus'
+import type { InsertPipeline } from './insert'
+import { mentionFor, walkEntry } from './transfer'
+
+/**
+ * 拖拽 / 粘贴处理（统一接管 + 拖入即插气泡）：
+ *
+ *  1. 任何文件拖入/粘贴（含图片）都走本插件：全屏遮罩 → 解析引用项；
+ *  2. 最终缓存路径在拖入时即可确定（<dropsRoot>/<批次>/<相对路径>），
+ *     因此**立即**在输入框光标处插入气泡 —— 不等上传；
+ *  3. 文件落盘由 enqueueUpload 在后台异步进行（本地写盘，用户无感），
+ *     完成/失败以 toast 告知；
+ *  4. 接管时从 dragenter 起 stopPropagation（window capture 首站），
+ *     DSH 原生图片拖放遮罩不会激活，也不会因收不到收尾事件而卡住页面。
+ */
+
+export interface DropDeps {
+  bus: DropBus
+  insert: InsertPipeline
+  /** 缓存根目录（应用启动时预取，拖入时兜底拉取） */
+  ensureRoot(): Promise<string | null>
+  /** 后台上传入口（不阻塞输入；完成后自行 toast） */
+  enqueueUpload(jobs: UploadJob[], batch: string): void
+}
+
+/** 任何文件拖拽都接管；items 不可用（Firefox dragenter/dragover）时按 types 兜底 */
+export function interceptable(dt: { items: DataTransferItemList | DataTransferItem[]; types?: readonly string[] } | null | undefined): boolean {
+  if (dt === null || dt === undefined) return false
+  const types = Array.from(dt.types ?? [])
+  if (types.includes('Files')) return true
+  if (dt.items) {
+    for (const it of Array.from(dt.items)) if (it.kind === 'file') return true
+  }
+  return false
+}
+
+export function countFiles(dt: { items: DataTransferItemList | DataTransferItem[] }): number {
+  let n = 0
+  for (const it of Array.from(dt.items)) if (it.kind === 'file') n += 1
+  return n
+}
+
+export interface DropHandlers {
+  /** 已同步收集的拖拽/粘贴条目 → 立即插气泡 + 后台缓存 */
+  acceptAndInsert(synced: SyncedItem[], batch: string): Promise<void>
+  /** 文件选择框（input.files）→ 立即插气泡 + 后台缓存 */
+  acceptTree(files: TreeFile[], dirTops: string[], batch: string): Promise<void>
+  installListeners(): () => void
+}
+
+/** drop/paste 事件内同步收集的结果（事件结束后 DataTransfer 即失效，不可再读） */
+export interface SyncedItem {
+  entry: FileSystemEntry | null
+  file: File | null
+}
+
+/**
+ * 关键：DataTransfer 只在事件同步阶段有效 —— getAsFile / webkitGetAsEntry
+ * 必须在事件处理器内、任何 await 之前完成调用，否则浏览器清空 DataTransfer
+ * 后全部返回 null。本函数专门在同步阶段收集 File / Entry。
+ */
+export function syncCollect(dt: { items: DataTransferItemList | DataTransferItem[] }): SyncedItem[] {
+  const synced: SyncedItem[] = []
+  for (const it of Array.from(dt.items)) {
+    if (it.kind !== 'file') continue
+    let entry: FileSystemEntry | null = null
+    try {
+      const getter = (it as unknown as { webkitGetAsEntry?: () => FileSystemEntry | null }).webkitGetAsEntry
+        ?? (it as unknown as { getAsEntry?: () => FileSystemEntry | null }).getAsEntry
+      entry = typeof getter === 'function' ? getter() : null
+    } catch { entry = null }
+    let file: File | null = null
+    try { file = typeof (it as DataTransferItem).getAsFile === 'function' ? (it as DataTransferItem).getAsFile() : null } catch { file = null }
+    if (entry === null && file === null) continue
+    synced.push({ entry, file })
+  }
+  return synced
+}
+
+export function createDropHandlers(deps: DropDeps): DropHandlers {
+  const { bus, insert } = deps
+
+  const submitRefs = async (refs: InsertItem[], jobs: UploadJob[], batch: string): Promise<void> => {
+    if (refs.length === 0) { bus.toast('无法读取拖入的内容', 'error'); return }
+    // 1) 立即插入气泡（不等上传）
+    const inserted = await insert(refs)
+    if (inserted > 0) bus.toast('已引用 ' + inserted + ' 项，文件正在后台缓存')
+    else bus.toast('未能插入引用（见上方提示）', 'error')
+    // 2) 后台缓存
+    deps.enqueueUpload(jobs, batch)
+  }
+
+  /** 文件选择框路径（已有 TreeFile 列表） */
+  const acceptTree = async (files: TreeFile[], dirTops: string[], batch: string): Promise<void> => {
+    const root = await deps.ensureRoot()
+    if (root === null) { bus.toast('无法获取缓存目录，请重试', 'error'); return }
+    const refs: InsertItem[] = []
+    for (const top of dirTops) {
+      const dirPath = root + '/' + batch + '/' + top
+      refs.push({ label: top, reference: { source: 'workbuddy', ref: mentionFor(dirPath, true), label: top, appearance: 'folder', clipboardText: mentionFor(dirPath, true) } })
+    }
+    for (const f of files) {
+      const path = root + '/' + batch + '/' + f.rel
+      refs.push({ label: f.name, reference: { source: 'workbuddy', ref: mentionFor(path, false), label: f.name, appearance: 'file', clipboardText: mentionFor(path, false) } })
+    }
+    await submitRefs(refs, files.map((f) => ({ kind: 'file', file: f.file, rel: f.rel, name: f.name })), batch)
+  }
+
+  /**
+   * 核心：先按预分配路径立即插入气泡，再交给后台缓存。
+   * synced 必须在事件内同步收集完毕（见 syncCollect）。
+   */
+  const acceptAndInsert = async (synced: SyncedItem[], batch: string): Promise<void> => {
+    const root = await deps.ensureRoot()
+    if (root === null) { bus.toast('无法获取缓存目录，请重试', 'error'); return }
+
+    const refs: InsertItem[] = []
+    const jobs: UploadJob[] = []
+
+    for (const s of synced) {
+      const { entry, file } = s
+
+      if (entry !== null && entry !== undefined && entry.isDirectory) {
+        const top = entry.name
+        const dirPath = root + '/' + batch + '/' + top
+        refs.push({ label: top, reference: { source: 'workbuddy', ref: mentionFor(dirPath, true), label: top, appearance: 'folder', clipboardText: mentionFor(dirPath, true) } })
+        jobs.push({ kind: 'dir', entry })
+        continue
+      }
+
+      if (file !== null && file !== undefined) {
+        const rel = file.name
+        const path = root + '/' + batch + '/' + rel
+        refs.push({ label: file.name, reference: { source: 'workbuddy', ref: mentionFor(path, false), label: file.name, appearance: 'file', clipboardText: mentionFor(path, false) } })
+        jobs.push({ kind: 'file', file, rel, name: file.name })
+        continue
+      }
+
+      // entry 是文件但 getAsFile 失败：尽力从 entry.file 取（事件外可能失效，尽力而为）
+      if (entry !== null && entry !== undefined && entry.isFile) {
+        const fe = entry as FileSystemFileEntry
+        const f = await new Promise<File | null>((resolve2) => fe.file((ff) => resolve2(ff), () => resolve2(null)))
+        if (f !== null && f !== undefined) {
+          const rel = f.name
+          const path = root + '/' + batch + '/' + rel
+          refs.push({ label: f.name, reference: { source: 'workbuddy', ref: mentionFor(path, false), label: f.name, appearance: 'file', clipboardText: mentionFor(path, false) } })
+          jobs.push({ kind: 'file', file: f, rel, name: f.name })
+        }
+      }
+    }
+
+    await submitRefs(refs, jobs, batch)
+  }
+
+  const installListeners = (): (() => void) => {
+    let dragDepth = 0
+    const onDragEnter = (e: DragEvent) => {
+      if (!interceptable(e.dataTransfer)) return
+      e.preventDefault()
+      // 关键：capture 首站即阻断传播。DSH 原生图片拖放轨道在 document(bubble)
+      // 上监听 dragenter 并无条件显示全屏遮罩；若它先激活、而我们的 drop 又
+      // stopPropagation，它会收不到收尾事件而永久卡住页面。
+      e.stopPropagation()
+      dragDepth += 1
+      bus.set({ ...bus.get(), active: true, count: countFiles(e.dataTransfer) })
+    }
+    const onDragOver = (e: DragEvent) => {
+      if (!interceptable(e.dataTransfer)) return
+      e.preventDefault()
+      e.stopPropagation()
+      if (!bus.get().active) { dragDepth = 1; bus.set({ ...bus.get(), active: true, count: countFiles(e.dataTransfer) }) }
+    }
+    const onDragLeave = (e: DragEvent) => {
+      if (!interceptable(e.dataTransfer)) return
+      e.preventDefault()
+      e.stopPropagation()
+      if (dragDepth > 0) dragDepth -= 1
+      if (dragDepth === 0) bus.set({ ...bus.get(), active: false, count: 0 })
+    }
+    const onDrop = (e: DragEvent) => {
+      const dt = e.dataTransfer
+      if (dt === null || dt === undefined) return
+      if (!interceptable(dt)) return
+      e.preventDefault()
+      e.stopPropagation()
+      dragDepth = 0
+      bus.set({ ...bus.get(), active: false, count: 0 })
+      // 事件内同步收集（await 之前），否则 DataTransfer 失效
+      const synced = syncCollect(dt)
+      if (synced.length === 0) return
+      acceptAndInsert(synced, 'drop-' + Date.now().toString(36)).catch((err) => {
+        console.error('[workbuddy] drop 处理失败:', err)
+        bus.toast('拖入处理失败：' + String((err as Error)?.message ?? err), 'error')
+      })
+    }
+    const onDragEnd = () => {
+      dragDepth = 0
+      bus.set({ ...bus.get(), active: false, count: 0 })
+    }
+    const onPaste = (e: ClipboardEvent) => {
+      const cd = e.clipboardData
+      if (cd === null || cd === undefined || !cd.items) return
+      let hasFile = false
+      for (const it of Array.from(cd.items)) if (it.kind === 'file') { hasFile = true; break }
+      if (!hasFile) return
+      e.preventDefault()
+      e.stopPropagation()
+      // 事件内同步收集（await 之前），否则 clipboardData 失效
+      const synced = syncCollect(cd)
+      if (synced.length === 0) return
+      acceptAndInsert(synced, 'drop-' + Date.now().toString(36)).catch((err) => {
+        console.error('[workbuddy] 粘贴处理失败:', err)
+        bus.toast('粘贴处理失败：' + String((err as Error)?.message ?? err), 'error')
+      })
+    }
+
+    window.addEventListener('dragenter', onDragEnter, true)
+    window.addEventListener('dragover', onDragOver, true)
+    window.addEventListener('dragleave', onDragLeave, true)
+    window.addEventListener('drop', onDrop, true)
+    window.addEventListener('dragend', onDragEnd, true)
+    window.addEventListener('paste', onPaste, true)
+    return () => {
+      window.removeEventListener('dragenter', onDragEnter, true)
+      window.removeEventListener('dragover', onDragOver, true)
+      window.removeEventListener('dragleave', onDragLeave, true)
+      window.removeEventListener('drop', onDrop, true)
+      window.removeEventListener('dragend', onDragEnd, true)
+      window.removeEventListener('paste', onPaste, true)
+    }
+  }
+
+  return { acceptAndInsert, acceptTree, installListeners }
+}

package/src/client/lib/icons.ts

@@ -0,0 +1,26 @@
+/** 文件类型 → 图标/颜色映射（WorkBuddy 风格的类型标识） */
+
+const ICONS: Record<string, string> = {
+  pdf: '📕', doc: '📘', docx: '📘', xls: '📊', xlsx: '📊', csv: '📊', ppt: '📙', pptx: '📙',
+  png: '🖼️', jpg: '🖼️', jpeg: '🖼️', gif: '🖼️', webp: '🖼️', svg: '🖼️', bmp: '🖼️',
+  zip: '🗜️', '7z': '🗜️', rar: '🗜️', tar: '🗜️', gz: '🗜️',
+  mp3: '🎵', wav: '🎵', flac: '🎵', mp4: '🎬', mov: '🎬', mkv: '🎬',
+  md: '📝', txt: '📄', log: '📄',
+  js: '💻', ts: '💻', jsx: '💻', tsx: '💻', py: '💻', go: '💻', rs: '💻', java: '💻',
+  c: '💻', h: '💻', cpp: '💻', cs: '💻', json: '💻', yaml: '💻', yml: '💻', toml: '💻',
+  sh: '💻', ps1: '💻', bat: '💻', css: '💻', html: '💻', vue: '💻', sql: '💻',
+}
+
+export function iconFor(name: string): string {
+  const dot = String(name).lastIndexOf('.')
+  const ext = dot >= 0 ? String(name).slice(dot + 1).toLowerCase() : ''
+  return ICONS[ext] ?? '📄'
+}
+
+export function formatSize(n: number | null | undefined): string {
+  if (n === null || n === undefined || !Number.isFinite(n)) return ''
+  if (n < 1024) return n + ' B'
+  if (n < 1048576) return (n / 1024).toFixed(1) + ' KB'
+  if (n < 1073741824) return (n / 1048576).toFixed(1) + ' MB'
+  return (n / 1073741824).toFixed(2) + ' GB'
+}

package/src/client/lib/insert.ts

@@ -0,0 +1,107 @@
+import type { InsertItem } from '../types'
+
+/**
+ * 气泡插入管线 —— 整个插件的核心：
+ *
+ * 通过对话包暴露的 `conversation.input`（InputHub，SessionInputResolver 面）
+ * 解析当前会话的输入 shell，读取实时 InputState（draft/draftRev），在
+ * 光标位置调用 `shell.insertReference(reference, span)` 铸造原生引用气泡
+ * （occurrence）。span 采用 draftRev CAS：若插入期间用户输入导致修订号
+ * 变化，重试读取新状态（最多 8 次）；非 plain 阶段（提交中）插入被拒。
+ *
+ * 兜底 1：insertReference 反复失败 → setDraft 直接写草稿文本（保证输入框有内容）；
+ * 兜底 2：无 facade → 聚焦 textarea 时 document.execCommand 纯文本插入。
+ */
+export interface InsertDeps {
+  sessions: {
+    list: { getSnapshot(): { current: string | undefined } }
+  }
+  conversation: {
+    input: {
+      /**
+       * id 寻址服务面（InputHub.shell）—— 直接返回会话输入 shell，
+       * 无需 sessions.scope()（后者返回 cordis Context，动态门面拒绝暴露）。
+       */
+      shell(id: string): {
+        state: { getSnapshot(): { draft: string; draftRev: number } }
+        insertReference(reference: InsertItem['reference'], span: { start: number; end: number; draftRev: number }): boolean
+        setDraft(text: string): void
+        notify(level: 'info' | 'error', text: string): void
+      }
+    }
+  }
+  toast(text: string, level?: 'info' | 'error'): void
+}
+
+export type InsertPipeline = (items: InsertItem[]) => Promise<number>
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+function readCaret(fallbackLen: number): number {
+  const el = document.activeElement
+  if (el !== null && el !== undefined && String(el.tagName).toUpperCase() === 'TEXTAREA' && typeof (el as HTMLTextAreaElement).selectionStart === 'number') {
+    return (el as HTMLTextAreaElement).selectionStart
+  }
+  return fallbackLen
+}
+
+export function createInsertPipeline(deps: InsertDeps): InsertPipeline {
+  return async function insertItems(items: InsertItem[]): Promise<number> {
+    const sessionId = deps.sessions.list.getSnapshot().current
+    if (sessionId === undefined) {
+      deps.toast('请先打开或新建一个会话，再拖入文件', 'error')
+      return 0
+    }
+    let shell: null | {
+      state: { getSnapshot(): { draft: string; draftRev: number } }
+      insertReference(reference: InsertItem['reference'], span: { start: number; end: number; draftRev: number }): boolean
+      setDraft(text: string): void
+      notify(level: 'info' | 'error', text: string): void
+    } = null
+    try { shell = deps.conversation.input.shell(sessionId) } catch { shell = null }
+
+    let inserted = 0
+    let firstCaret: number | null = null
+    for (const item of items) {
+      if (shell !== null && shell !== undefined) {
+        let ok = false
+        for (let attempt = 0; attempt < 8 && !ok; attempt += 1) {
+          try {
+            const st = shell.state.getSnapshot()
+            let caret = st.draft.length
+            if (firstCaret === null) {
+              firstCaret = readCaret(st.draft.length)
+              caret = firstCaret
+            }
+            const pos = Math.min(caret, st.draft.length)
+            ok = shell.insertReference(item.reference, { start: pos, end: pos, draftRev: st.draftRev })
+          } catch { ok = false }
+          if (!ok) await sleep(90)
+        }
+        if (ok) { inserted += 1; continue }
+        // 兜底 1：直接写草稿文本（无气泡，但输入框立刻有内容）
+        try {
+          const st = shell.state.getSnapshot()
+          const pos = Math.min(firstCaret !== null ? firstCaret : st.draft.length, st.draft.length)
+          const mention = typeof item.reference.ref === 'string' ? item.reference.ref : String(item.label)
+          const next = st.draft.slice(0, pos) + mention + ' ' + st.draft.slice(pos)
+          shell.setDraft(next)
+          inserted += 1
+          continue
+        } catch (err2) {
+          try { shell.notify('error', '未能插入引用「' + item.label + '」：' + String((err2 as Error)?.message ?? err2)) } catch { /* ignore */ }
+        }
+      } else {
+        // 兜底 2：无 facade —— 聚焦 textarea 时 execCommand 纯文本插入
+        const text = item.reference.ref
+        const el = document.activeElement
+        if (el !== null && el !== undefined && String(el.tagName).toUpperCase() === 'TEXTAREA') {
+          try { document.execCommand('insertText', false, text + ' '); inserted += 1 } catch { /* ignore */ }
+        } else {
+          deps.toast('输入区不可用，未能插入「' + item.label + '」', 'error')
+        }
+      }
+    }
+    return inserted
+  }
+}