dsh-code-ui 1.4.0 → 1.5.0

package/lib/client.js

@@ -153,18 +153,23 @@ window.__ModuleLoader__.load({
       .cdex-ref-head{display:flex;align-items:center;gap:6px;margin-bottom:6px;font-size:12px;}
       .cdex-ref-path{flex:1;color:var(--dsw-alias-label-secondary,#9d9d9d);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
       .cdex-ref-code{background:var(--dsw-alias-bg-base,#1e1e1e);border-radius:4px;padding:6px;font-family:Consolas,monospace;font-size:12px;white-space:pre-wrap;word-break:break-all;color:var(--dsw-alias-label-primary,#d4d4d4);max-height:140px;overflow:auto;}
+      /* 已使用（随消息消耗）的引用记录：整体弱化 + 「已使用」徽章 */
+      .cdex-ref-used{opacity:.62;}
+      .cdex-ref-usedbadge{flex:none;font-size:10px;line-height:16px;padding:0 6px;border-radius:8px;background:var(--dsw-alias-bg-layer-3,#3a3a41);color:var(--dsw-alias-label-secondary,#9d9d9d);}
       .cdex-section{color:var(--dsw-alias-label-secondary,#8a8a8a);font-size:11px;text-transform:uppercase;letter-spacing:.05em;margin:12px 0 6px;}
       .cdex-hint{color:var(--dsw-alias-label-secondary,#8a8a8a);font-size:12px;margin-top:12px;line-height:1.6;}
       .cdex-toast{position:fixed;z-index:10003;top:36px;left:50%;transform:translateX(-50%);background:var(--cdex-accent-bg,#0f1115);color:var(--cdex-accent-fg,#ffffff);padding:9px 16px;border-radius:6px;box-shadow:0 4px 16px rgba(0,0,0,.4);max-width:80vw;cursor:grab;user-select:none;touch-action:none;}
       .cdex-toast.placed{transform:none;cursor:grabbing;}
       .cdex-toast-grip{margin-right:8px;opacity:.55;font-size:12px;letter-spacing:-1px;}
+      .cdex-toast-x{flex:none;border:none;background:transparent;color:inherit;cursor:pointer;font-size:12px;line-height:1;padding:2px 0 2px 10px;margin-left:10px;opacity:.7;}
+      .cdex-toast-x:hover{opacity:1;}
       .cdex-resize{position:absolute;right:0;bottom:0;width:18px;height:18px;cursor:nwse-resize;z-index:10;}
       .cdex-resize::after{content:'';position:absolute;right:4px;bottom:4px;width:8px;height:8px;border-right:2px solid var(--dsw-alias-label-secondary,#7f849c);border-bottom:2px solid var(--dsw-alias-label-secondary,#7f849c);}
       .cdex-aiinput-wrap{position:relative;padding:10px 14px 16px;background:transparent;border-top:1px solid var(--dsw-alias-border-l1,#3e3e42);}
       .cdex-aiinput-card{background:var(--dsw-alias-bg-overlay,#252526);border:1px solid var(--dsw-alias-border-l1,#3e3e42);border-radius:14px;box-shadow:0 2px 12px rgba(0,0,0,.18);overflow:hidden;}
       .cdex-aiinput-tags{display:flex;flex-wrap:wrap;gap:6px;padding:10px 12px 0;}
-      .cdex-aiinput-tag{display:inline-flex;align-items:center;gap:6px;background:var(--cdex-accent-bg,#0f1115);color:var(--cdex-accent-fg,#ffffff);border-radius:12px;padding:3px 10px 3px 12px;font-size:12px;}
-      .cdex-aiinput-tag-label{white-space:nowrap;}
+      .cdex-aiinput-tag{display:inline-flex;align-items:center;gap:6px;background:var(--cdex-accent-bg,#0f1115);color:var(--cdex-accent-fg,#ffffff);border-radius:12px;padding:3px 10px 3px 12px;font-size:12px;max-width:260px;min-width:0;}
+      .cdex-aiinput-tag-label{white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-width:0;}
       .cdex-aiinput-tag-tr{background:#b45309;color:#fff;}
       .cdex-aiinput-tag-x{border:none;background:transparent;color:var(--cdex-accent-fg,#ffffff);cursor:pointer;font-size:13px;padding:0;line-height:1;opacity:.85;}
       .cdex-aiinput-tag-x:hover{opacity:1;}
@@ -240,6 +245,26 @@ window.__ModuleLoader__.load({
       .cdex-workbench,.cdex-modebar{--cdex-accent-bg:var(--dsw-alias-brand-primary,#0f1115);--cdex-accent-fg:var(--dsw-alias-bg-base,#ffffff);}
       .cdex-tokens-light{--cdex-tk-kw:#af00db;--cdex-tk-str:#a31515;--cdex-tk-com:#008000;--cdex-tk-num:#098658;--cdex-tk-fn:#795e26;--cdex-tk-punc:#555555;}
       .cdex-tokens-dark{--cdex-tk-kw:#c586c0;--cdex-tk-str:#ce9178;--cdex-tk-com:#6a9955;--cdex-tk-num:#b5cea8;--cdex-tk-fn:#dcdcaa;--cdex-tk-punc:#808080;}
+      /* —— 引用 chip 升级：文件图标 + hover 全路径 + 点击跳转编辑器 —— */
+      .cdex-aiinput-tag{cursor:pointer;transition:filter .12s ease;}
+      .cdex-aiinput-tag:hover{filter:brightness(1.18);}
+      .cdex-tag-ic{display:inline-flex;align-items:center;flex:0 0 auto;}
+      .cdex-tag-ic svg{display:block;}
+      /* —— 引用 / 备注视图行可点击跳转 —— */
+      .cdex-ref-link{cursor:pointer;}
+      .cdex-ref-link:hover{color:var(--dsw-alias-label-primary,#d4d4d4);}
+      .cdex-ref-link .cdex-tag-ic{margin-right:2px;vertical-align:-1px;}
+      /* —— 消息区引用卡（Trae 式：左竖线 + 图标 + 文件名行号行，点击跳回编辑器） —— */
+      .cdex-refcard{margin-top:8px;border-left:2px solid var(--dsw-alias-button-info-fill,#4176e6);background:var(--dsw-alias-bg-layer-1,rgba(127,127,127,.08));border-radius:0 8px 8px 0;padding:6px 10px;display:flex;flex-direction:column;gap:2px;max-width:100%;box-sizing:border-box;}
+      .cdex-refcard-head{font-size:11px;color:var(--dsw-alias-label-tertiary,#8a8a8a);margin-bottom:2px;}
+      .cdex-refcard-row{display:flex;align-items:center;gap:6px;font-size:12px;line-height:20px;cursor:pointer;border-radius:4px;padding:0 4px;min-width:0;}
+      .cdex-refcard-row:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(127,127,127,.14));}
+      .cdex-refcard-ic{display:inline-flex;align-items:center;flex:0 0 auto;}
+      .cdex-refcard-ic svg{display:block;}
+      .cdex-refcard-num{flex:none;min-width:16px;height:16px;border-radius:8px;background:var(--dsw-alias-bg-layer-3,#3a3a3f);color:var(--dsw-alias-label-secondary,#a8a8ad);font-size:10px;line-height:16px;text-align:center;padding:0 4px;}
+      .cdex-refcard-name{color:var(--dsw-alias-label-primary,#d4d4d4);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+      .cdex-refcard-lines{color:var(--dsw-alias-button-info-fill,#4176e6);font-family:Consolas,'Cascadia Code',Menlo,monospace;font-size:11.5px;flex:0 0 auto;}
+      .cdex-refcard-kind{flex:0 0 auto;margin-left:auto;font-size:10px;line-height:16px;padding:0 6px;border-radius:8px;background:var(--dsw-alias-bg-layer-3,rgba(127,127,127,.18));color:var(--dsw-alias-label-secondary,#9d9d9d);}
     `; document.head.appendChild(tag); return () => tag.remove(); })
 
     /* ============ §3 状态层 ============ */
@@ -281,6 +306,7 @@ window.__ModuleLoader__.load({
       toastPos: null,
       sessionId: null,     // 当前会话 id（InputBridge 从 slot kit 捕获；blank 会话头隐藏时由 SessionWatch 兜底）：文件树根按会话解析/记忆
       rootSessionId: null, // 当前根归属哪个会话（落后于 sessionId 时触发重新解析；手动根由宿主按会话记忆）
+      sessionEditor: {},   // 会话 id -> { tabs, activePath, nodes, rootPath }：切换会话时快照/恢复编辑器标签与文件树展开状态（滚动位按文件路径记忆于 scrollPos）
       scrollPos: {},       // 文件路径 -> {top,left}：每个标签记住自己的滚动位置（切换后恢复）
       error: null,
     }
@@ -296,20 +322,33 @@ window.__ModuleLoader__.load({
       return store
     }
 
+    let toastSeq = 0
     function showToast(msg) {
-      store.toast = { msg }
+      store.toast = { msg, seq: ++toastSeq }
       store.toastKeep = false
       emit()
       scheduleToastHide(2800)
     }
-    // 提示自动消失；正在被拖拽（toastKeep）时顺延，松手后短暂展示再消失
+    // 提示自动消失；正在被拖拽（toastKeep）时顺延，松手后短暂展示再消失。
+    // seq 世代戳：手动 ✕ 关闭后残留的定时器不会误关下一条新提示。
+    // timer 是宿主服务（ctx.get('timer')），可能缺失——缺失时回退 setTimeout，
+    // 否则 scheduleToastHide 静默不挂定时器，提示条永远不关（历史上「有时不自动关闭」的根因）。
     function scheduleToastHide(ms) {
-      if (timer && typeof timer.timeout === 'function') {
-        timer.timeout(() => {
-          if (store.toastKeep) { scheduleToastHide(600); return }
-          store.toast = null; emit()
-        }, ms)
+      const seq = store.toast ? store.toast.seq : 0
+      const fire = () => {
+        if (!store.toast || store.toast.seq !== seq) return // 已被手动关闭或已换新提示
+        if (store.toastKeep) { scheduleToastHide(600); return }
+        store.toast = null
+        emit()
       }
+      if (timer && typeof timer.timeout === 'function') timer.timeout(fire, ms)
+      else if (typeof setTimeout === 'function') setTimeout(fire, ms)
+    }
+    // 手动关闭（✕ 兜底）：连带清 toastKeep，避免卡在拖拽态让后续提示无限顺延
+    function closeToastNow() {
+      store.toast = null
+      store.toastKeep = false
+      emit()
     }
     // 提示条拖拽：按住移动自定义位置（默认顶部居中，拖过之后记住位置，防止挡内容）
     function onToastPointerDown(e) {
@@ -346,6 +385,10 @@ window.__ModuleLoader__.load({
       return h('div', { className: 'cdex-toast' + (st.toastPos ? ' placed' : ''), style: style, title: '按住可拖动位置（不再挡内容）', onPointerDown: onToastPointerDown },
         h('span', { className: 'cdex-toast-grip' }, '⠿'),
         st.toast.msg,
+        // 手动关闭兜底：自动消失偶发失效时用户可一键关掉；✕ 上阻断 pointerdown，不触发拖拽
+        h('button', { className: 'cdex-toast-x', title: '关闭提示',
+          onPointerDown: (e) => { e.stopPropagation() },
+          onClick: (e) => { e.stopPropagation(); closeToastNow() } }, '✕'),
       )
     }
 
@@ -406,13 +449,36 @@ window.__ModuleLoader__.load({
       return parts.length ? parts[parts.length - 1] : String(p || '')
     }
     function tagLabel(r) {
+      // 短小原则：只显示 文件名:起-止 行号，让用户知道引了什么即可；完整路径放 hover title
       const name = baseName(r.path)
-      if (r.lineStart && r.lineEnd) {
-        return name + '(' + r.lineStart + '-' + r.lineEnd + ')'
-      }
-      if (!r.lineStart && r.kind === 'cite') return name + '(整文件)'
+      if (r.lineStart && r.lineEnd) return name + ':' + r.lineStart + '-' + r.lineEnd
       return name
     }
+    // —— 文件类型图标：按扩展名给色，chip / 引用视图 / 消息引用卡共用 ——
+    const FILE_ICON_COLOR = {
+      ts: '#4a9eff', tsx: '#4a9eff', js: '#e2c08d', jsx: '#e2c08d', mjs: '#e2c08d', cjs: '#e2c08d', json: '#d7ba7d',
+      md: '#9da5b4', mdx: '#9da5b4', txt: '#9da5b4',
+      css: '#b180d7', scss: '#b180d7', less: '#b180d7',
+      html: '#e37933', htm: '#e37933', xml: '#e37933', vue: '#41b883', svelte: '#e37933',
+      py: '#4ec9b0', rs: '#d19a66', go: '#4ec9b0', java: '#c78d5a', kt: '#c78d5a',
+      c: '#8a919f', h: '#8a919f', cpp: '#8a919f', cc: '#8a919f', hpp: '#8a919f', cs: '#4a9eff',
+      sh: '#89d185', ps1: '#4a9eff', bat: '#89d185', cmd: '#89d185',
+      yml: '#c7a252', yaml: '#c7a252', toml: '#c7a252', ini: '#c7a252', conf: '#c7a252', env: '#c7a252',
+      png: '#dd6eb4', jpg: '#dd6eb4', jpeg: '#dd6eb4', gif: '#dd6eb4', webp: '#dd6eb4', svg: '#dd6eb4', ico: '#dd6eb4',
+      zip: '#c7a252', gz: '#c7a252', tgz: '#c7a252', lock: '#8a919f',
+    }
+    function fileIconSvg(path) {
+      const name = baseName(path)
+      const dot = name.lastIndexOf('.')
+      const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : ''
+      const color = FILE_ICON_COLOR[ext] || '#8a919f'
+      return '<svg viewBox="0 0 16 16" width="12" height="12" fill="none" aria-hidden="true">'
+        + '<path d="M4 1.5h5L13 5.5v8a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1v-11a1 1 0 0 1 1-1z" stroke="' + color + '" stroke-width="1.2" stroke-linejoin="round"/>'
+        + '<path d="M9 1.5V5.5H13" stroke="' + color + '" stroke-width="1.2" stroke-linejoin="round"/></svg>'
+    }
+    const GLOBE_SVG = '<svg viewBox="0 0 16 16" width="12" height="12" fill="none" aria-hidden="true">'
+      + '<circle cx="8" cy="8" r="6.2" stroke="#7cc4ff" stroke-width="1.2"/>'
+      + '<path d="M1.8 8h12.4M8 1.8c2.4 1.9 2.4 10.5 0 12.4M8 1.8c-2.4 1.9-2.4 10.5 0 12.4" stroke="#7cc4ff" stroke-width="1.1"/></svg>'
     function parentPath(p) {
       const s = String(p).replace(/[\\/]+$/, '')
       const idx = Math.max(s.lastIndexOf('\\'), s.lastIndexOf('/'))
@@ -620,6 +686,7 @@ window.__ModuleLoader__.load({
     ]
     const HLJS_VENDOR_BASE = '/dsh-code-ui/vendor/'
     const HLJS_BIG_CHARS = 512 * 1024 // 超大文件不做 hljs（防卡顿），继续用轻量 tokenizer
+    const HLJS_SYNC_MAX = 32 * 1024 // 该阈值内同步走 hljs：单帧渲染，杜绝 tokenizer↔hljs 交换帧（交换帧会重写 innerHTML 丢滚动位 → 每敲一个字符文本抖动）
     // langOf 的输出大多是 hljs 语言 id/别名；少数需归一，其余交给 hljs.getLanguage 解析，失败回退 plaintext
     const HLJS_LANG_FIX = { text: 'plaintext', jsx: 'javascript', tsx: 'typescript', htm: 'xml' }
     function hljsLangOf(lang) {
@@ -714,8 +781,24 @@ window.__ModuleLoader__.load({
       if (hljsState !== 'ready' || content.length > HLJS_BIG_CHARS) return highlight(content, lang)
       const cached = hljsCache.get(p)
       if (cached && cached.content === content) return cached.html
+      // 小文件同步走 hljs：一次渲染直接出最终结果。原「tokenizer 顶上 + 60ms 后换 hljs」
+      // 的交换帧会让高亮层每击键重写两次 innerHTML（浏览器重写时 scrollTop/scrollLeft 被
+      // 重置为 0），表现为滚动过的文件每敲一个字符文本抖动一下。
+      if (content.length <= HLJS_SYNC_MAX) {
+        let html
+        try {
+          html = window.hljs.highlight(content, { language: hljsLangOf(lang) || 'plaintext', ignoreIllegals: true }).value
+        } catch (e) {
+          html = highlight(content, lang) // 单文件异常（不应发生）：退回 tokenizer 输出
+        }
+        // 与 tokenizer 输出保持行数一致：末尾换行补齐（textarea 会渲染最后的空行）
+        if (content.endsWith('\n') && !html.endsWith('\n')) html += '\n'
+        if (hljsCache.size > 24) { const first = hljsCache.keys().next().value; if (first !== undefined) hljsCache.delete(first) }
+        hljsCache.set(p, { content, html })
+        return html
+      }
       scheduleHljs(p, content, lang)
-      return highlight(content, lang) // 间歇帧：tokenizer 顶上，保证字符即时可见有色
+      return highlight(content, lang) // 大文件：tokenizer 顶上（同步、即时），60ms 防抖后换 hljs
     }
 
     /* ============ §4 RPC 操作层（文件树 / 标签页 / 引用备注） ============ */
@@ -755,22 +838,51 @@ window.__ModuleLoader__.load({
       await applyRoot((res && res.root) ? res.root : path)
       showToast('工作区根目录：' + store.rootPath)
     }
-    // 换根并整体重置文件树/标签页/缓冲（自动跟随与手动设置共用）
+    // 换根：标签页/缓冲/脏标记按会话记忆（handleSessionSwitch 快照恢复，均以绝对路径为键、
+    // 跨根安全）。树状态（目录展开/已加载子目录）同样按会话恢复——nodes 里已有该根节点时
+    // 跳过重置（同根换会话、或恢复了目标会话的树快照），只在新根没有树状态时重建。
+    // 注意不能用 toggleExpand 展开：它是切换语义，会把已展开的根折叠回去。
     async function applyRoot(newRoot) {
       store.rootPath = newRoot
-      store.nodes = {}
-      store.tabs = []
-      store.activePath = null
-      store.buffers = {}
-      store.savedContent = {}
-      store.dirty = {}
+      if (!store.nodes[newRoot]) {
+        store.nodes = {}
+        store.browsePath = null
+        store.browseEntries = []
+        store.nodes[newRoot] = { name: baseName(newRoot), path: newRoot, isDir: true, children: [], expanded: true, loaded: false }
+        store.filePickerOpen = false
+        emit()
+        await toggleExpand(newRoot)
+        return
+      }
+      emit()
+    }
+    // —— 会话切换：编辑器状态按会话记忆 ——
+    // 切换时快照当前会话的标签页/激活项/文件树（展开+已加载子目录）/根路径，恢复目标会话的；
+    // 滚动位按文件路径记忆于 store.scrollPos（标签恢复挂载时自动回滚），焦点不恢复、由用户
+    // 自己点击决定。缓冲/脏标记以绝对路径为键全局保留：切走再切回，未保存内容与 ● 状态
+    // 原样还在，因此不再需要「有脏文件暂不跟随」守卫——根始终跟随新会话。
+    function handleSessionSwitch(nextSid) {
+      if (!nextSid || nextSid === store.sessionId) return
+      const prevSid = store.sessionId
+      const keyOf = (s) => s || '__no-session__'
+      if (prevSid && store.rootPath) {
+        store.sessionEditor[keyOf(prevSid)] = {
+          tabs: store.tabs,
+          activePath: store.activePath,
+          nodes: store.nodes,
+          rootPath: store.rootPath,
+        }
+      }
+      const saved = store.sessionEditor[keyOf(nextSid)]
+      store.tabs = saved ? saved.tabs : []
+      store.activePath = saved ? saved.activePath : null
+      store.nodes = saved && saved.nodes ? saved.nodes : {}
+      store.rootPath = saved && saved.rootPath ? saved.rootPath : null
       store.activeNotes = []
-      store.browsePath = null
-      store.browseEntries = []
-      store.nodes[newRoot] = { name: baseName(newRoot), path: newRoot, isDir: true, children: [], expanded: true, loaded: false }
-      store.filePickerOpen = false
+      store.sessionId = nextSid
       emit()
-      await toggleExpand(newRoot)
+      if (store.activePath) loadNotes(store.activePath)
+      refresh()
     }
     // —— 文件树 ——
     async function refresh() {
@@ -831,6 +943,50 @@ window.__ModuleLoader__.load({
       }
       loadNotes(path)
     }
+    // —— 引用跳转：chip / 引用视图 / 消息引用卡共用。打开文件并选中行区间（选中即高亮），滚动到可视区 ——
+    function editorLineOffset(content, line) {
+      // line 为 1-based 行号；返回该行首字符在 buffer 中的偏移
+      const lines = String(content).split('\n')
+      let off = 0
+      for (let i = 0; i < line - 1 && i < lines.length; i++) off += lines[i].length + 1
+      return off
+    }
+    function waitForEditorBuffer(path, timeoutMs) {
+      // openFile 异步读盘后 React 才提交 textarea 重挂载；rAF 轮询直到编辑区内容与缓冲一致
+      const deadline = Date.now() + (timeoutMs || 2000)
+      return new Promise((resolve) => {
+        const tick = () => {
+          const ta = editorTaEl
+          const buf = store.buffers[path]
+          if (ta && buf != null && ta.value === buf) { resolve(true); return }
+          if (Date.now() > deadline) { resolve(false); return }
+          if (typeof window !== 'undefined' && window.requestAnimationFrame) window.requestAnimationFrame(tick)
+          else setTimeout(tick, 50)
+        }
+        tick()
+      })
+    }
+    async function jumpToRef(r) {
+      if (!r || !r.path) return
+      await openFile(r.path)
+      const content = store.buffers[r.path]
+      if (!r.lineStart || typeof content !== 'string') return
+      const ok = await waitForEditorBuffer(r.path)
+      const ta = editorTaEl
+      if (!ok || !ta) return
+      try {
+        const lines = content.split('\n')
+        const start = editorLineOffset(content, r.lineStart)
+        const endLine = Math.max(r.lineStart, r.lineEnd || r.lineStart)
+        let end = start
+        for (let i = r.lineStart - 1; i < Math.min(endLine, lines.length); i++) end += lines[i].length + 1
+        ta.focus({ preventScroll: true })
+        ta.setSelectionRange(Math.min(start, ta.value.length), Math.min(end, ta.value.length))
+        // 20px 行高与 .cdex-textarea/.cdex-code-ta 一致；目标行滚到视口上 1/3 处
+        ta.scrollTop = Math.max(0, (r.lineStart - 1) * 20 - ta.clientHeight / 3)
+        ta.dispatchEvent(new Event('scroll')) // 复用 onScroll：同步高亮层/行号槽并记忆滚动位
+      } catch (e) {}
+    }
     function closeTab(path) {
       const i = store.tabs.findIndex((t) => t.path === path)
       if (i < 0) return
@@ -969,14 +1125,29 @@ window.__ModuleLoader__.load({
       emit()
     }
     async function doCite(sel) {
-      const ref = await callHost('add-reference', { path: sel.path, language: sel.language, lineStart: sel.lineStart, lineEnd: sel.lineEnd, text: sel.text, kind: 'cite' })
-      if (ref && ref.reference) { store.references.push(ref.reference); emit() }
-      showToast('已引用：' + baseName(sel.path))
+      const res = await callHost('add-reference', { path: sel.path, language: sel.language, lineStart: sel.lineStart, lineEnd: sel.lineEnd, text: sel.text, kind: 'cite' })
+      if (res && res.reference) {
+        // 允许重复引用：chip 在输入框句中可视化，重复用户看得见、可删，host 端不再去重
+        if (!store.references.some((x) => x.id === res.reference.id)) store.references.push(res.reference)
+        emit()
+        // 路线A：优先把 chip 直接插进输入框末尾；失败（服务未就绪/草稿已变更等）仅提示
+        let chipped = false
+        try { chipped = insertRefChipDirect(res.reference) } catch (e) {}
+        showToast(chipped ? '已插入输入框：' + chipLabelFor(res.reference) : '已引用：' + baseName(sel.path))
+      }
     }
     async function doTranslate(sel) {
-      const ref = await callHost('add-reference', { path: sel.path, language: sel.language, lineStart: sel.lineStart, lineEnd: sel.lineEnd, text: sel.text, kind: 'translate' })
-      if (ref && ref.reference) { store.references.push(ref.reference); emit() }
-      showToast('已创建翻译引用（输入框上方已加 🌐 标签）。对 AI 说「翻译我引用的内容」即可。')
+      const res = await callHost('add-reference', { path: sel.path, language: sel.language, lineStart: sel.lineStart, lineEnd: sel.lineEnd, text: sel.text, kind: 'translate' })
+      if (res && res.reference) {
+        if (!store.references.some((x) => x.id === res.reference.id)) store.references.push(res.reference)
+        emit()
+        // 与引用同款：优先把 🌐 chip 直接插进输入框末尾；失败退回提示（可在【引用/备注】查看）
+        let chipped = false
+        try { chipped = insertRefChipDirect(res.reference) } catch (e) {}
+        showToast(chipped
+          ? '已插入输入框：' + chipLabelFor(res.reference)
+          : '已创建翻译引用（可在【引用/备注】查看）。对 AI 说「翻译我引用的内容」即可。')
+      }
     }
     function openNoteEditor(sel) {
       store.noteEditor = { path: sel.path, lineStart: sel.lineStart, lineEnd: sel.lineEnd, note: '' }
@@ -1002,11 +1173,14 @@ window.__ModuleLoader__.load({
       n.children = entries.map((e) => { store.nodes[e.path] = e; return e.path })
       emit()
     }
-    // 整文件引用：只给 AI 绝对路径，AI 用自己的读取工具打开
+    // 整文件引用：只给 AI 绝对路径，AI 用自己的读取工具打开（允许重复引用，不去重）
     async function citeWholeFile(path) {
-      const ref = await callHost('add-reference', { path: path, language: langOf(path), lineStart: null, lineEnd: null, text: '', kind: 'cite' })
-      if (ref && ref.reference) { store.references.push(ref.reference); emit() }
-      showToast('已引用整个文件：' + baseName(path) + '（AI 将自行读取）')
+      const res = await callHost('add-reference', { path: path, language: langOf(path), lineStart: null, lineEnd: null, text: '', kind: 'cite' })
+      if (res && res.reference) {
+        if (!store.references.some((x) => x.id === res.reference.id)) store.references.push(res.reference)
+        emit()
+        showToast('已引用整个文件：' + baseName(path) + '（AI 将自行读取）')
+      }
     }
     // 重命名后同步标签页/缓冲/激活路径/watcher
     function renameTabSync(fromPath, toPath) {
@@ -1111,33 +1285,153 @@ window.__ModuleLoader__.load({
       emit()
     }
     // —— 引用自动附带（AI 上下文） ——
+    // —— 引用一次性消耗：引用只能随一条消息使用，发送后标记 used（chip 即刻清空）；
+    // 已使用记录保留在【引用/备注】供用户查找（需要重复引用就重新选中代码再引用，不做重复引用按钮）。
+    // 标记 used 而非删除：AI 在消息发出后才调 get_referenced_snippets，删掉就读不到了。
+    function pendingRefs() {
+      return store.references.filter((r) => !r.used)
+    }
+    // 编号唯一出口：待用引用按创建序 1..N（删除后重排，发送后清零）。
+    // tag 显示 / 消息指针 / 引用卡 全部用它，保证用户说的「引用N」三处同号。
+    function numberedPendingRefs() {
+      return pendingRefs().map((r, i) => ({ r: r, n: i + 1 }))
+    }
+    function consumePendingRefs() {
+      const pend = pendingRefs()
+      if (pend.length === 0) return
+      const ids = pend.map((r) => r.id)
+      for (let i = 0; i < pend.length; i++) {
+        // 冻结发送时刻的编号到记录上：AI 经 get_referenced_snippets 读到的编号 = 用户在 tag 上看到的编号
+        pend[i].used = true
+        pend[i].usedAt = new Date().toISOString()
+        pend[i].seq = i + 1
+      }
+      emit()
+      callHost('use-references', { ids }).then(() => {})
+    }
     function buildSendPayload(draft) {
-      // 引用文本不再粘贴进消息（明面上不展示）：引用统一存 host 端，AI 通过 get_referenced_snippets
-      // 工具读取；消息里只附一行「标签级」指针，让 AI 知道有引用可读。
-      // 整文件引用（无行号）：直接给出绝对路径，AI 用自己的读取工具打开。
+      // 引用文本不粘贴进消息（明面上不展示代码正文）：引用统一存 host 端，AI 通过 get_referenced_snippets
+      // 工具读取；消息里附「结构化指针」——人可读、AI 可读，消息区引用卡也按它解析还原（单一事实源）。
+      // 只取未使用引用（used 的已随旧消息消耗，不再重复附带）。整文件引用：给出绝对路径。
       const text = draft || ''
       if (text.indexOf('[code UI] 已标记') >= 0) return text // 幂等：已带指针不重复附加
-      const citeRefs = store.references.filter((r) => r.kind === 'cite')
-      const trRefs = store.references.filter((r) => r.kind === 'translate')
-      const codeRefs = citeRefs.filter((r) => r.lineStart)
-      const fileRefs = citeRefs.filter((r) => !r.lineStart)
+      // 编号 = 待用引用创建序（1 起），与输入框 tag、AI 工具输出三处同号：用户说「引用N」AI 即知所指
+      // 已被行内 chip 携带的引用不再自动附带（发送时由 codec.serialize 在 chip 位置展开）。
+      // chip 集合以草稿 occurrences 实时为准（用户删 chip 后自动回到自动附带），chipRefs 为兜底
+      const chipIds = store.draftChipIds || store.chipRefs
+      const pend = numberedPendingRefs().filter((x) => !chipIds || !chipIds.has(x.r.id))
+      const codeRefs = pend.filter((x) => x.r.kind === 'cite' && x.r.lineStart)
+      const fileRefs = pend.filter((x) => x.r.kind === 'cite' && !x.r.lineStart)
+      const trRefs = pend.filter((x) => x.r.kind === 'translate')
+      const items = []
+      for (const x of codeRefs) items.push('- ' + x.n + ': 代码引用 ' + baseName(x.r.path) + ':' + x.r.lineStart + '-' + x.r.lineEnd + '（' + x.r.path + '）')
+      for (const x of fileRefs) items.push('- ' + x.n + ': 文件引用 ' + baseName(x.r.path) + '（整文件，绝对路径：' + x.r.path + '）')
+      for (const x of trRefs) items.push(x.r.lineStart
+        ? '- ' + x.n + ': 翻译引用 ' + baseName(x.r.path) + ':' + x.r.lineStart + '-' + x.r.lineEnd + '（' + x.r.path + '）'
+        : '- ' + x.n + ': 翻译引用 ' + baseName(x.r.path) + '（' + x.r.path + '）')
       const parts = []
       if (codeRefs.length > 0) parts.push(codeRefs.length + ' 段代码引用')
       if (fileRefs.length > 0) parts.push(fileRefs.length + ' 个文件引用')
       if (trRefs.length > 0) parts.push(trRefs.length + ' 条翻译请求')
       if (parts.length === 0) return text
-      let ptr = '[code UI] 已标记 ' + parts.join('、') + '。'
-      if (fileRefs.length > 0) {
-        ptr += '\n文件引用（整个文件，请用你的文件读取工具打开以下绝对路径）：\n'
-          + fileRefs.map((r) => '- ' + r.path).join('\n')
-      }
-      if (codeRefs.length > 0 || trRefs.length > 0) {
-        ptr += '\n（代码/翻译引用内容未粘贴在消息里，请调用 get_referenced_snippets 工具读取）。'
-      }
+      let ptr = '[code UI] 已标记 ' + parts.join('、') + '（代码正文不进消息，请调用 get_referenced_snippets 工具读取；条目编号与用户输入框上的引用 tag 序号一致，用户说「引用N」即指该条）：'
+      if (items.length > 0) ptr += '\n' + items.join('\n')
       const sep = text.trim() ? '\n\n' : ''
       return text + sep + ptr
     }
 
+    /* —— 消息区引用卡：解析消息里的结构化指针，在用户气泡内追加 Trae 式引用行 —— */
+    function parseRefsFromMessage(text) {
+      const out = []
+      if (!text || text.indexOf('[code UI] 已标记') < 0) return out
+      const reCode = /^- (?:(\d+): )?代码引用 (.+):(\d+)-(\d+)（(.+)）$/gm
+      const reTr = /^- (?:(\d+): )?翻译引用 (.+):(\d+)-(\d+)（(.+)）$/gm
+      const reTrFile = /^- (?:(\d+): )?翻译引用 ([^:\n]+)（(.+)）$/gm // 名字段禁冒号：避免吞掉上面带行号条目
+      const reFile = /^- (?:(\d+): )?文件引用 ([^:\n]+)（整文件，绝对路径：(.+)）$/gm
+      let m
+      while ((m = reCode.exec(text)) !== null) out.push({ num: m[1] ? +m[1] : null, name: m[2], lineStart: +m[3], lineEnd: +m[4], path: m[5], kind: 'cite' })
+      while ((m = reTr.exec(text)) !== null) out.push({ num: m[1] ? +m[1] : null, name: m[2], lineStart: +m[3], lineEnd: +m[4], path: m[5], kind: 'translate' })
+      while ((m = reFile.exec(text)) !== null) out.push({ num: m[1] ? +m[1] : null, name: m[2], path: m[3], kind: 'cite' })
+      while ((m = reTrFile.exec(text)) !== null) out.push({ num: m[1] ? +m[1] : null, name: m[2], path: m[3], kind: 'translate' })
+      return out
+    }
+    function buildRefCardEl(refs) {
+      if (!refs || refs.length === 0) return null
+      const card = document.createElement('div')
+      card.className = 'cdex-refcard'
+      const head = document.createElement('div')
+      head.className = 'cdex-refcard-head'
+      head.textContent = '引用上下文 ' + refs.length + ' 项 · 点击行跳转编辑器'
+      card.appendChild(head)
+      for (const r of refs) {
+        const row = document.createElement('div')
+        row.className = 'cdex-refcard-row'
+        row.title = r.path + (r.lineStart ? ' : 第 ' + r.lineStart + '-' + r.lineEnd + ' 行' : '')
+        const ic = document.createElement('span')
+        ic.className = 'cdex-refcard-ic'
+        ic.innerHTML = r.kind === 'translate' ? GLOBE_SVG : fileIconSvg(r.path)
+        row.appendChild(ic)
+        if (r.num) {
+          const nb = document.createElement('span')
+          nb.className = 'cdex-refcard-num'
+          nb.textContent = String(r.num)
+          row.appendChild(nb)
+        }
+        const nm = document.createElement('span')
+        nm.className = 'cdex-refcard-name'
+        nm.textContent = r.name || baseName(r.path)
+        row.appendChild(nm)
+        if (r.lineStart) {
+          const ln = document.createElement('span')
+          ln.className = 'cdex-refcard-lines'
+          ln.textContent = ':' + r.lineStart + '-' + r.lineEnd
+          row.appendChild(ln)
+        }
+        const kind = document.createElement('span')
+        kind.className = 'cdex-refcard-kind'
+        kind.textContent = r.kind === 'translate' ? '翻译' : (r.lineStart ? '代码' : '整文件')
+        row.appendChild(kind)
+        row.addEventListener('click', () => { jumpToRef({ path: r.path, lineStart: r.lineStart, lineEnd: r.lineEnd }) })
+        card.appendChild(row)
+      }
+      return card
+    }
+    // 用户气泡结构（与 dsh 宿主对话区一致）：row[data-time-hover-root] > stack > bubble；
+    // 只做「追加」不做搬移/改写——不碰 React 管理的节点，宿主重渲染丢卡后由观察器补挂。
+    function scanRefCards(root) {
+      const rows = root.querySelectorAll('[data-time-hover-root]:not([data-turn-tail])')
+      for (const row of rows) {
+        const text = row.textContent
+        if (!text || text.indexOf('[code UI] 已标记') < 0) continue
+        const stack = row.firstElementChild
+        const bubble = stack ? stack.lastElementChild : null
+        const target = (bubble instanceof HTMLElement) ? bubble : row
+        if (target.querySelector(':scope > .cdex-refcard')) continue
+        const refs = parseRefsFromMessage(text)
+        if (refs.length === 0) continue
+        const card = buildRefCardEl(refs)
+        if (card) target.appendChild(card)
+      }
+    }
+    function observeRefCards() {
+      if (typeof MutationObserver === 'undefined' || typeof document === 'undefined' || !document.body) return () => {}
+      let scheduled = false
+      const scan = () => { scheduled = false; try { scanRefCards(document) } catch (e) {} }
+      const schedule = () => {
+        if (scheduled) return
+        scheduled = true
+        if (typeof window !== 'undefined' && window.requestAnimationFrame) window.requestAnimationFrame(scan)
+        else setTimeout(scan, 60)
+      }
+      const mo = new MutationObserver(schedule)
+      mo.observe(document.body, { childList: true, subtree: true })
+      schedule()
+      return () => {
+        try { mo.disconnect() } catch (e) {}
+        try { document.querySelectorAll('.cdex-refcard').forEach((el) => el.remove()) } catch (e) {}
+      }
+    }
+
     /* ============ §6 Pointer 处理层（窗口拖拽 / 缩放 / 模式条移动） ============ */
     function onBarPointerDown(e) {
       if (e.target && typeof e.target.closest === 'function' && e.target.closest('button')) return
@@ -1207,6 +1501,40 @@ window.__ModuleLoader__.load({
 
     /* ============ §7 组件层（V.* 命名空间） ============ */
     let selfSending = false // AiInput 副本自己发送时置位，让挂钩的 submit 不重复附加指针
+    // shell.submit 补丁：宿主输入条的回车/发送按钮走 keyboard.submit = shell.submit（SessionInputShell），
+    // 不经过 inputActions.submit（那条只有发送按钮内部转发和插件输入卡用）——补丁必须挂在 shell.submit
+    // 这个必经点，否则原生输入条发送时引用既不附带指针也不消耗。
+    const patchedShells = new WeakSet()
+    function ensureShellSubmitPatch() {
+      try {
+        const sid = store.inputSessionId
+        if (!sid) return
+        const conversation = ctx.get('conversation')
+        const hub = conversation && conversation.input
+        if (!hub || typeof hub.shell !== 'function') return
+        const shell = hub.shell(sid)
+        if (!shell || typeof shell.submit !== 'function' || typeof shell.setDraft !== 'function') return
+        if (patchedShells.has(shell)) return
+        patchedShells.add(shell)
+        const origSubmit = shell.submit
+        shell.submit = function () {
+          let hadRefs = false
+          try {
+            const hasRefs = pendingRefs().length > 0
+            hadRefs = hasRefs
+            const draft = store.inputDraft || ''
+            if (hasRefs && !selfSending && String(draft).indexOf('[code UI]') < 0) {
+              shell.setDraft(buildSendPayload(draft))
+            }
+          } catch (e) {}
+          const result = origSubmit.apply(shell, arguments)
+          try { if (hadRefs && !selfSending) consumePendingRefs() } catch (e) {}
+          return result
+        }
+      } catch (e) {}
+    }
+    // （历史：曾在 conversation.input.dock 插槽挂"输入条上方引用 tag 条"（P1-15），
+    //   行内 chip（路线A）落地后冗余，已移除——引用的直接可视化由输入框内 chip 承担。）
     function InputBridge(props) {
       const useInput = props.useInput
       const inputState = typeof useInput === 'function' ? useInput((s) => s) : undefined
@@ -1216,15 +1544,21 @@ window.__ModuleLoader__.load({
         if (inputState) {
           store.inputDraft = inputState.draft
           store.inputPhase = inputState.phase
+          // 路线A直接插 chip 所需：compose() 快照的 draftRev（插入 CAS）+ 草稿中 code-ui chip 携带的引用 id
+          if (typeof inputState.draftRev === 'number') store.inputDraftRev = inputState.draftRev
+          try {
+            const ids = new Set()
+            const occs = Array.isArray(inputState.occurrences) ? inputState.occurrences : []
+            for (const o of occs) {
+              if (!o || o.source !== 'code-ui') continue
+              const cr = parseChipRef(o.ref)
+              if (cr && cr.id) ids.add(cr.id)
+            }
+            store.draftChipIds = ids
+          } catch (e) {}
         }
-        // 捕获当前会话 id：文件树根按会话隔离——切换即解析新会话的根
-        //（自动=该会话 cwd；手动=宿主 sessionRoots 里该会话记忆的根）
-        if (props.sessionId && props.sessionId !== store.sessionId) {
-          store.sessionId = props.sessionId
-          const hasDirty = Object.keys(store.dirty || {}).some((k) => store.dirty[k])
-          if (hasDirty) showToast('会话已切换：有未保存文件，工作区暂不跟随（保存后点 ⟳ 刷新即可）')
-          else refresh()
-        }
+        if (props.sessionId) { handleSessionSwitch(props.sessionId); store.inputSessionId = props.sessionId }
+        ensureShellSubmitPatch() // 每次渲染尝试挂 shell.submit 补丁（WeakSet 幂等，会话切换后补新 shell）
         emit()
       })
       // 挂钩 DSH 原生输入条的发送：存在引用时把指针附进草稿再发（整文件=绝对路径）。
@@ -1235,14 +1569,21 @@ window.__ModuleLoader__.load({
         const orig = inputActions.submit
         inputActions.__cdexPatched = true
         inputActions.submit = function () {
+          let attached = false
+          let hadRefs = false
           try {
-            const hasRefs = store.references.length > 0
+            const hasRefs = pendingRefs().length > 0
+            hadRefs = hasRefs
             const draft = store.inputDraft || ''
             if (hasRefs && !selfSending && draft.indexOf('[code UI]') < 0) {
               inputActions.setDraft(buildSendPayload(draft))
+              attached = true
             }
           } catch (e) {}
-          return orig.apply(inputActions, arguments)
+          const result = orig.apply(inputActions, arguments)
+          // 引用随本条消息消耗：chip 展开（attached=false）与自动附带（attached=true）两条路径都要消耗
+          try { if (hadRefs && !selfSending) consumePendingRefs() } catch (e) {}
+          return result
         }
         return () => {
           try { inputActions.submit = orig; delete inputActions.__cdexPatched } catch (e) {}
@@ -1259,11 +1600,7 @@ window.__ModuleLoader__.load({
       const useSessions = props.useSessions
       const sid = typeof useSessions === 'function' ? useSessions((s) => s.current) : undefined
       React.useEffect(() => {
-        if (!sid || sid === store.sessionId) return
-        store.sessionId = sid
-        const hasDirty = Object.keys(store.dirty || {}).some((k) => store.dirty[k])
-        if (hasDirty) showToast('会话已切换：有未保存文件，工作区暂不跟随（保存后点 ⟳ 刷新即可）')
-        else refresh()
+        if (sid) handleSessionSwitch(sid)
       }, [sid])
       return null
     }
@@ -1271,8 +1608,9 @@ window.__ModuleLoader__.load({
       const st = useStore()
       let taEl = null
       const disabled = !st.inputActions
-      // 引用与翻译请求都只显示「标签」：内容不进输入框/消息正文，AI 经 get_referenced_snippets 工具读取
-      const refs = st.references
+      // 引用与翻译请求都只显示「标签」：内容不进输入框/消息正文，AI 经 get_referenced_snippets 工具读取。
+      // 只显示未使用引用：used 的已随旧消息消耗（chip 清空），记录在【引用/备注】的已使用区。
+      const refs = st.references.filter((r) => !r.used)
       const citeCount = refs.filter((r) => r.kind === 'cite').length
       const trCount = refs.length - citeCount
       const submit = () => {
@@ -1289,15 +1627,20 @@ window.__ModuleLoader__.load({
           st.inputActions.setDraft(payload)
           st.inputActions.submit()
         } finally { selfSending = false }
+        // 引用随本条消息消耗（chip 清空；记录留在【引用/备注】已使用区）
+        consumePendingRefs()
         taEl.value = ''
       }
       return h('div', { className: 'cdex-aiinput-wrap' },
         h('div', { className: 'cdex-aiinput-card' },
           disabled ? h('div', { className: 'cdex-aiinput-warn' }, '⚠ 未打开会话：请先在主界面新建或选择一个会话，之后即可在此发送（引用标签会保留）') : null,
           refs.length > 0 ? h('div', { className: 'cdex-aiinput-tags' },
-            refs.map((r) => h('span', { className: 'cdex-aiinput-tag' + (r.kind === 'translate' ? ' cdex-aiinput-tag-tr' : ''), key: r.id },
-              h('span', { className: 'cdex-aiinput-tag-label' }, (r.kind === 'translate' ? '🌐 翻译 ' : '🔗 ') + tagLabel(r)),
-              h('button', { className: 'cdex-aiinput-tag-x', title: r.kind === 'translate' ? '删除翻译引用' : '删除引用', onClick: () => delReference(r.id) }, '✕'),
+            refs.map((r, i) => h('span', { className: 'cdex-aiinput-tag' + (r.kind === 'translate' ? ' cdex-aiinput-tag-tr' : ''), key: r.id,
+              title: '#' + (i + 1) + ' ' + r.path + (r.lineStart ? ' : 第 ' + r.lineStart + '-' + r.lineEnd + ' 行' : '') + '（点击跳转编辑器，✕ 删除；对 AI 说「引用' + (i + 1) + '」即指此条）',
+              onClick: () => jumpToRef(r) },
+              h('span', { className: 'cdex-tag-ic', dangerouslySetInnerHTML: { __html: r.kind === 'translate' ? GLOBE_SVG : fileIconSvg(r.path) } }),
+              h('span', { className: 'cdex-aiinput-tag-label' }, (r.kind === 'translate' ? '🌐' : '') + (i + 1) + ':' + tagLabel(r)),
+              h('button', { className: 'cdex-aiinput-tag-x', title: r.kind === 'translate' ? '删除翻译引用' : '删除引用', onClick: (e) => { e.stopPropagation(); delReference(r.id) } }, '✕'),
             )),
           ) : null,
           h('div', { className: 'cdex-aiinput' },
@@ -1441,18 +1784,61 @@ window.__ModuleLoader__.load({
       )
     }
     function RefItem(r) {
-      return h('div', { className: 'cdex-ref', key: r.id },
+      return h('div', { className: 'cdex-ref' + (r.used ? ' cdex-ref-used' : ''), key: r.id,
+        title: '右键：复制 / 翻译 / 引用（给AI）', onContextMenu: (e) => onRefContext(e, r) },
         h('div', { className: 'cdex-ref-head' },
-          h('span', { className: 'cdex-ref-path' }, r.path, r.lineStart ? (' :' + r.lineStart + '-' + r.lineEnd) : (r.kind === 'cite' ? ' （整个文件）' : '')),
-          h('button', { className: 'cdex-btn-ghost', onClick: () => delReference(r.id) }, '✕'),
+          h('span', { className: 'cdex-ref-path cdex-ref-link',
+            title: r.path + (r.lineStart ? ' : 第 ' + r.lineStart + '-' + r.lineEnd + ' 行' : '') + '（点击跳转编辑器）',
+            onClick: () => jumpToRef(r) },
+            h('span', { className: 'cdex-tag-ic', dangerouslySetInnerHTML: { __html: r.kind === 'translate' ? GLOBE_SVG : fileIconSvg(r.path) } }),
+            r.path, r.lineStart ? (' :' + r.lineStart + '-' + r.lineEnd) : (r.kind === 'cite' ? ' （整个文件）' : ''),
+          ),
+          r.used ? h('span', { className: 'cdex-ref-usedbadge', title: r.usedAt ? ('随消息消耗于 ' + r.usedAt) : '已随消息消耗' }, '已使用') : null,
+          h('button', { className: 'cdex-btn-ghost', title: r.used ? '删除已使用记录' : '删除引用', onClick: () => delReference(r.id) }, '✕'),
         ),
         h('div', { className: 'cdex-ref-code' }, r.text ? r.text.slice(0, 500) : '（AI 将按绝对路径自行读取整个文件）'),
       )
     }
+    /* —— 【引用/备注】条目右键菜单：复制 / 翻译 / 引用（给AI）——
+       引用记录自带 path/行区间/正文，直接复用；备注只存批注不存代码，
+       翻译/引用前先经 read-file 从磁盘取回对应行内容。 */
+    function refMenuItems(e, items) {
+      e.preventDefault()
+      store.ctxMenu = { x: e.clientX, y: e.clientY, items }
+      emit()
+    }
+    async function noteToSel(n) {
+      if (!n.lineStart) return { path: n.path, language: langOf(n.path), lineStart: null, lineEnd: null, text: '' } // 整文件备注：按整文件引用处理
+      const res = await callHost('read-file', { path: n.path })
+      if (!res || res.error) { showToast('读取原文件失败：' + ((res && res.error) || '未知错误')); return null }
+      const lines = String(res.content || '').split('\n')
+      const s = Math.max(1, n.lineStart)
+      const t = Math.min(lines.length, Math.max(s, n.lineEnd || s))
+      return { path: n.path, language: langOf(n.path), lineStart: s, lineEnd: t, text: lines.slice(s - 1, t).join('\n') }
+    }
+    function onRefContext(e, r) {
+      const isWhole = !r.lineStart
+      const sel = { path: r.path, language: r.language || langOf(r.path), lineStart: r.lineStart, lineEnd: r.lineEnd, text: r.text || '' }
+      refMenuItems(e, [
+        { icon: '📋', label: isWhole ? '复制路径' : '复制', act: () => { copyText(isWhole ? r.path : sel.text); showToast(isWhole ? '路径已复制' : '代码已复制') } },
+        { icon: '🌐', label: '翻译', act: () => { doTranslate(sel) } },
+        { icon: '🔗', label: '引用（给AI）', act: () => { doCite(sel) } },
+      ])
+    }
+    function onNoteContext(e, n) {
+      refMenuItems(e, [
+        { icon: '📋', label: '复制', act: () => { copyText(n.note || ''); showToast('备注已复制') } },
+        { icon: '🌐', label: '翻译', act: () => { noteToSel(n).then((sel) => { if (sel) doTranslate(sel) }) } },
+        { icon: '🔗', label: '引用（给AI）', act: () => { noteToSel(n).then((sel) => { if (sel) doCite(sel) }) } },
+      ])
+    }
     function ReferencesView() {
       const st = useStore()
-      const citeList = st.references.filter((r) => r.kind === 'cite')
-      const trList = st.references.filter((r) => r.kind === 'translate')
+      // 待用（chip 里挂着、随下一条消息发送）与已使用（已随消息消耗的历史记录）分区展示
+      const pending = st.references.filter((r) => !r.used)
+      const usedList = st.references.filter((r) => r.used)
+      const citeList = pending.filter((r) => r.kind === 'cite')
+      const trList = pending.filter((r) => r.kind === 'translate')
       return h('div', { className: 'cdex-sidebar', style: { width: st.sidebarW } },
         h('div', { className: 'cdex-sb-resize', title: '拖拽调整宽度（拖到最窄松手即收起）', onPointerDown: onSbResizeDown }),
         h('div', { className: 'cdex-sidebar-head' },
@@ -1464,15 +1850,20 @@ window.__ModuleLoader__.load({
           citeList.length === 0 ? h('div', { className: 'cdex-empty' }, '选中代码后右键「引用」。') : citeList.map((r) => RefItem(r)),
           h('div', { className: 'cdex-section' }, '🌐 翻译请求 (' + trList.length + ')'),
           trList.length === 0 ? h('div', { className: 'cdex-empty' }, '选中代码后右键「翻译」。') : trList.map((r) => RefItem(r)),
+          h('div', { className: 'cdex-section' }, '🕘 已使用 (' + usedList.length + ')'),
+          usedList.length === 0
+            ? h('div', { className: 'cdex-empty' }, '尚无已消耗的引用。引用随消息发送即标记已使用，记录保留在此供查找。')
+            : usedList.map((r) => RefItem(r)),
           h('div', { className: 'cdex-section' }, '📝 备注 (' + st.activeNotes.length + ')'),
-          st.activeNotes.length === 0 ? h('div', { className: 'cdex-empty' }, '当前文件暂无备注。') : st.activeNotes.map((n) => h('div', { className: 'cdex-ref', key: n.id },
+          st.activeNotes.length === 0 ? h('div', { className: 'cdex-empty' }, '当前文件暂无备注。') : st.activeNotes.map((n) => h('div', { className: 'cdex-ref', key: n.id,
+            title: '右键：复制 / 翻译 / 引用（给AI）', onContextMenu: (e) => onNoteContext(e, n) },
             h('div', { className: 'cdex-ref-head' },
               h('span', { className: 'cdex-ref-path' }, n.path, n.lineStart ? (' :' + n.lineStart + '-' + n.lineEnd) : ''),
               h('button', { className: 'cdex-btn-ghost', onClick: () => delNote(n.id) }, '✕'),
             ),
             h('div', { className: 'cdex-ref-code' }, n.note),
           )),
-          h('div', { className: 'cdex-hint' }, '在输入框对 AI 说「读取/翻译我引用的代码」，AI 会调用 get_referenced_snippets 工具获取内容。'),
+          h('div', { className: 'cdex-hint' }, '引用一次性使用：随消息发送即消耗（chip 清空，AI 仍可读取本次内容）。条目右键可快速复制 / 翻译 / 引用（给AI）。在输入框对 AI 说「读取/翻译我引用的代码」，AI 会调用 get_referenced_snippets 工具获取内容。'),
         ),
       )
     }
@@ -1496,6 +1887,19 @@ window.__ModuleLoader__.load({
     }
     function Editor() {
       const st = useStore()
+      // 高亮层 innerHTML 被替换时浏览器会把 scrollTop/scrollLeft 重置为 0；每次渲染提交后
+      // 从 textarea 回同步（也覆盖大文件 60ms 防抖换帧路径），杜绝输入时文本抖动。
+      // 必须放在 early return 之前（Hooks 顺序约束）。
+      React.useEffect(() => {
+        const ta = editorTaEl
+        if (!ta) return
+        const layer = ta.parentNode
+        if (!layer) return
+        const preEl = layer.querySelector('.cdex-code-pre')
+        if (preEl) { preEl.scrollTop = ta.scrollTop; preEl.scrollLeft = ta.scrollLeft }
+        const gutEl = layer.parentNode ? layer.parentNode.querySelector('.cdex-gutter') : null
+        if (gutEl) gutEl.scrollTop = ta.scrollTop
+      })
       if (!st.activePath) {
         // 空态时显式展示当前工作区根，避免「以此文件夹为根」后误认为未切换
         return h('div', { className: 'cdex-editor' },
@@ -1903,6 +2307,68 @@ window.__ModuleLoader__.load({
     let unmountEditorFns = null
     let layoutMode = 'dock'    // dock(右侧停靠,默认) / float(悬浮窗口)：编辑器以哪种布局呈现
     let toggleStyle = 'bar'    // bar(悬浮模式条,默认) / header(会话头 ⌨ 按钮)：用哪种按钮切换界面
+    // chip 显示标签：编号 + 短标签；翻译类加 🌐 前缀与代码引用区分
+    function chipLabelFor(r) {
+      const hit = numberedPendingRefs().find((x) => x.r.id === r.id)
+      const num = hit ? hit.n : '?'
+      return (r.kind === 'translate' ? '🌐' : '') + num + ':' + tagLabel(r)
+    }
+    // —— 直接插入行内 chip（不经 @ 菜单）——
+    // 数据全部取实时值：conversation.input (= inputHub).shell(sid).snapshot 的 draft/draftRev
+    // （compose 快照，宿主每次编辑同步发布），不再依赖本插件组件的渲染同步时机。
+    // 位置 = detect 文本末尾：draft 是 clipboard 投影，chip 在 detect 里占 1 个占位符，
+    // 需按 occurrences 把 clipboard 长度换算回 detect 长度（每颗 chip 减 clipboardText长-1）。
+    // 与官方 toggleCommandMenu 的合成 span 同构（span.draftRev CAS）。
+    // 返回 true = chip 已插入输入框末尾；false = 条件不满足（调用方退回 tag 条展示）。
+    function insertRefChipDirect(r) {
+      try {
+        const conversation = ctx.get('conversation')
+        const inputHub = conversation && conversation.input
+        if (!inputHub || typeof inputHub.shell !== 'function') return false
+        const sid = store.inputSessionId
+        if (!sid) return false
+        const shell = inputHub.shell(sid)
+        const snap = shell && shell.snapshot
+        if (!snap || typeof snap.draftRev !== 'number' || typeof snap.draft !== 'string') return false
+        if (snap.phase && snap.phase !== 'plain' && snap.phase !== 'claimed') return false
+        const inputTriggers = store.inputTriggers
+        if (!inputTriggers || !inputTriggers.live || !inputTriggers.live.controllers) return false
+        const controller = inputTriggers.live.controllers.get(sid)
+        if (!controller || typeof controller.execute !== 'function') return false
+        let detectLen = snap.draft.length
+        const occs = Array.isArray(snap.occurrences) ? snap.occurrences : []
+        for (const o of occs) {
+          if (o && typeof o.length === 'number') detectLen -= Math.max(0, o.length - 1)
+        }
+        if (detectLen < 0) detectLen = 0
+        const label = chipLabelFor(r)
+        const outcome = { insert: { source: 'code-ui', ref: JSON.stringify({ id: r.id, path: r.path, lineStart: r.lineStart, lineEnd: r.lineEnd, kind: r.kind }), label: label, appearance: 'file', clipboardText: label } }
+        return controller.execute(outcome, { start: detectLen, end: detectLen, draftRev: snap.draftRev }) === true
+      } catch (e) { return false }
+    }
+    // chip ref（JSON 串）→ 引用数据；解析失败返回 null
+    function parseChipRef(refJson) {
+      try {
+        const r = JSON.parse(refJson)
+        if (!r || !r.path) return null
+        return r
+      } catch (e) { return null }
+    }
+    function chipShortLabel(r) {
+      const name = baseName(r.path)
+      return r.lineStart && r.lineEnd ? name + ':' + r.lineStart + '-' + r.lineEnd : name
+    }
+    // chip → 模型侧文本：与消息指针条目同格式（AI 侧读取口径一致）
+    function formatRefModelLine(r) {
+      if (r.kind === 'translate') {
+        return r.lineStart
+          ? '- 翻译引用 ' + baseName(r.path) + ':' + r.lineStart + '-' + r.lineEnd + '（' + r.path + '）'
+          : '- 翻译引用 ' + baseName(r.path) + '（' + r.path + '）'
+      }
+      return r.lineStart
+        ? '- 代码引用 ' + baseName(r.path) + ':' + r.lineStart + '-' + r.lineEnd + '（' + r.path + '）'
+        : '- 文件引用 ' + baseName(r.path) + '（整文件，绝对路径：' + r.path + '）'
+    }
     function mountEditor() {
       if (unmountEditorFns) return
       const disposers = []
@@ -1916,6 +2382,65 @@ window.__ModuleLoader__.load({
         { name: 'shell.overlay', id: 'cdex-session-watch', order: 4, label: '' },
         (props) => h(SessionWatch, props),
       )))
+      // 消息区引用卡：观察宿主对话区，把带 [code UI] 指针的用户消息补挂引用卡（卸载时连卡移除）
+      disposers.push(observeRefCards())
+      // —— 路线A原型：@ 菜单行内引用 chip（宿主 ReferenceChipNode 装饰器）——
+      // 注册官方触发源：输入框打 @ 弹菜单出现「code UI 引用」分组（与 @file 同菜单），
+      // 选中即在光标处插入行内 chip；发送时宿主调 codec.serialize 把每颗 chip 在原位
+      // 展开成模型文本（这里 = 与指针条目同格式的引用行）。chip 携带的引用不走自动
+      // 附带（防重复），消耗仍随消息（consumePendingRefs 标记 used，记录保留）。
+      // 已知原型局限：chip 在草稿里被删掉后 chipRefs 未同步，该引用本次不自动附带。
+      // inputTriggers 服务由 dsh-client-ui-input-trigger 在 client 启动期注册，插件
+      // client 可能先于它启动——ctx.get 会拿到 undefined 静默跳过，改用 inject 等待。
+      if (!store.chipRefs) store.chipRefs = new Set()
+      ctx.inject(['inputTriggers'], (scope) => {
+        try {
+          const inputTriggers = scope.inputTriggers
+          if (!inputTriggers || typeof inputTriggers.registerSource !== 'function') return
+          store.inputTriggers = inputTriggers
+          disposers.push(ctx.effect(() => inputTriggers.registerSource({
+            trigger: '@',
+            name: 'code-ui',
+            showGroupTitle: true,
+            order: 100,
+            candidates: (session, req) => {
+              const pend = numberedPendingRefs()
+              if (pend.length === 0) return Promise.resolve([])
+              const query = String((req && req.query) || '').toLowerCase()
+              return Promise.resolve(pend
+                .filter((x) => !query || tagLabel(x.r).toLowerCase().indexOf(query) >= 0 || baseName(x.r.path).toLowerCase().indexOf(query) >= 0)
+                .map((x) => ({
+                  name: (x.r.kind === 'translate' ? '🌐' : '') + x.n + ':' + tagLabel(x.r),
+                  description: x.r.path,
+                  icon: 'file',
+                  section: 'code UI 引用',
+                  value: x.r.id,
+                })))
+            },
+            onPick: (arg) => {
+              const r = store.references.find((x) => x.id === arg.candidate.value)
+              if (!r) return undefined
+              store.chipRefs.add(r.id)
+              emit()
+              // ref 字段封入完整引用数据（JSON）：chip 自包含，serialize 不依赖 client store——
+              // 硬刷新/重启后草稿恢复的 chip 仍能正确展开（对齐 @file 的 ref=mention 自包含设计）
+              const label = chipLabelFor(r)
+              return { insert: { source: 'code-ui', ref: JSON.stringify({ id: r.id, path: r.path, lineStart: r.lineStart, lineEnd: r.lineEnd, kind: r.kind }), label: label, appearance: 'file', clipboardText: label } }
+            },
+            codec: {
+              clipboardText: (refJson) => {
+                const r = parseChipRef(refJson)
+                return r ? chipShortLabel(r) : String(refJson)
+              },
+              serialize: async (refJson) => {
+                const r = parseChipRef(refJson)
+                if (!r) return '（code UI 引用数据无效: ' + refJson + '）'
+                return formatRefModelLine(r)
+              },
+            },
+          }), 'code-ui: @ 引用源原型'))
+        } catch (e) {}
+      })
       // 切换按钮：按用户选择注册（与布局模式解耦，任意组合）
       if (toggleStyle === 'bar') {
         // 悬浮模式条：可拖动横条，两键切换 code UI / dsh UI