dsh-code-ui 1.4.1 → 1.5.0

package/README.md

@@ -36,9 +36,9 @@
   - 📋 复制
   - 📥 粘贴到备注
   - 📝 添加备注
-  - 🌐 翻译（创建翻译引用，交给 AI 翻译）
+  - 🌐 翻译（🌐 chip 直插输入框，交给 AI 翻译）
   - 🔗 引用给 AI
-- **引用 chip**：引用后输入框上方显示 `文件名(起行-止行)` + ✕，删除引用
+- **行内引用 chip**：引用/翻译后 chip 直接嵌入输入框句中（`1:文件名:起行-止行`，翻译带 🌐 前缀），点击跳转编辑器；`@` 菜单可把引用插入句中任意位置；发送时 chip 原位展开为引用行，随消息一次性消耗（chip 清空、【引用/备注】留档可查）；允许重复引用（chip 可见、可删）
 - **内嵌 AI 输入框**（悬浮布局）：直接输入、`Ctrl+Enter` 发送；发送时不粘贴引用正文，只附一行引用指针，内容由 AI 调用 `get_referenced_snippets` 工具读取
 - **主题四态**：跟随 DSH（默认）/ 跟随系统 / 浅色 / 深色，插件卡片切换
 - **以此文件夹为根**：文件浏览器里可选任意目录作为工作区根
@@ -76,7 +76,7 @@ npm install dsh-code-ui
 1. 点顶部悬浮模式条的 `code UI` 打开编辑器（默认切换按钮；也可在插件卡片换成会话头 `⌨` 按钮），默认布局为右侧停靠
 2. 在文件树/浏览器里打开文件
 3. 选中代码右键 → 引用 / 翻译 / 备注 / 复制
-4. 悬浮布局底部输入框直接发消息（`Ctrl+Enter` 发送）；停靠布局用 DSH 原生输入条，引用只以标签显示，正文由 AI 工具读取
+4. 悬浮布局底部输入框直接发消息（`Ctrl+Enter` 发送）；停靠布局用 DSH 原生输入条，引用以行内 chip 嵌在输入框句中，正文由 AI 工具读取
 5. 也可对 AI 说「读取我引用的代码」，AI 会调用 `get_referenced_snippets` 工具
 
 ## 目录结构
@@ -114,6 +114,7 @@ dsh-code-ui/
 
 | 时间 | 版本 | 修复 / 新增 |
 | --- | --- | --- |
+| 2026-09-11 | v1.5.0 | 里程碑：**引用体系全面升级——行内引用 chip**。引用/翻译后标签不再挂在输入框上方，而是以 chip 直接嵌入输入框句中（`1:文件名:起行-止行`，翻译带 🌐 前缀），点击跳转编辑器、退格即删；`@` 菜单可把引用插入句中任意位置；发送时 chip 原位展开为 `- 代码引用 / - 翻译引用 文件名:行号（路径）` 引用行，正文由 AI 经 `get_referenced_snippets` 读取。实现：注册宿主 InputTrigger 触发源（candidates/onPick/codec）+ ReferenceChipNode 装饰器直插（shell.insertReference，实时取 `conversation.input.shell(sid).snapshot` 的 draft/draftRev）；chip ref 自包含 JSON（抗刷新/重启）。配套：**引用一次性消耗**——发送即标记已使用、chip 清空、【引用/备注】留档可查；**允许重复引用**（chip 可见可删，取消 host 去重）；**引用编号全链路贯通**——标签/消息指针/引用卡/AI 工具输出同号，对 AI 说「引用N」即指对应条目；【引用/备注】条目右键菜单（复制 / 翻译 / 引用给AI）；消息区引用卡 + chip 文件图标/点击跳转；提示条 ✕ 手动关闭兜底；移除「引用消耗模式」配置项（固定一次性）与输入条上方 tag 条（被行内 chip 取代）。工程：发送补丁改挂 shell.submit 必经点（原生输入条回车/按钮走 keyboard.submit，原 inputActions 补丁只覆盖插件输入卡）；纯 chip 携带的发送同样消耗 |
 | 2026-09-09 | v1.4.1 | 修复：编辑器**每敲一个字符文本抖动一下**。根因：hljs 就绪后，每次击键高亮层经历「tokenizer 顶上 → 60ms 防抖后换 hljs」**两次全量 innerHTML 重写**，浏览器重写 innerHTML 时 `scrollTop`/`scrollLeft` 被重置为 0——凡滚动过（垂直或水平）的文件，每次击键可见文本都会位移。修复：≤32KB 的文件改为**同步走 hljs**（单帧渲染直接出最终结果，无交换帧、工作量减半），>32KB 保留 60ms 防抖路径；并在每次渲染提交后从 textarea 回同步高亮层与行号滚动位（兜底所有 innerHTML 重写场景）。新增：**编辑器状态按会话记忆**——切换对话时快照当前会话的标签页/激活项并恢复目标会话的（此前 `applyRoot` 换根即清空标签与缓冲，切会话打开的文件全消失）；滚动位按文件路径记忆、标签恢复挂载即自动回滚；焦点不恢复，由用户自己点击决定；缓冲/脏标记以绝对路径为键全局保留，切走再切回未保存内容与 ● 状态原样还在，原「有脏文件暂不跟随根」守卫随之退役，根始终跟随新会话；**文件树展开状态同样按会话记忆**——目录展开与已加载子目录随会话快照/恢复（`applyRoot` 仅在 nodes 里没有该根节点时才重建树，同根换会话不再折叠），侧栏不再切一次对话就全部收起 |
 | 2026-09-08 | v1.4.0 | 里程碑：**语法高亮升级 highlight.js 11**（193 种语言，替换自研 tokenizer）。宿主 `webServer` exact 路由下发 `lib/vendor/` 全量包与主题 CSS，客户端首次高亮时懒加载、不拖累 SPA 启动；Electron（file://）/断网/路由缺失自动回退原 tokenizer 保底可用。插件卡片新增「语法配色」：自动（默认，随编辑器明暗 GitHub ↔ GitHub Dark）+ 10 款固定主题（GitHub / Dracula / Monokai / Nord / VS…），仅染 token 色、编辑器底色仍归「编辑器主题」管理，切换即时生效并持久化。性能：重高亮 ~60ms 防抖 + >512KB 大文件自动降级轻量高亮。`tools/vendor-hljs.mjs` 重建管线入库（支持 `--themes-only`、fetch 超时重试、Dracula 取官方源）。兼容性：适配 dsh 0.1.2+ 新版 settings 服务——不再 import 已删除的 `installSettingsSection`/`settingsNamespace` 具名导出（具名导出缺失会让宿主启动即退出），照 dshmarket 内联 `register`/`watch` 接线（服务 API 新旧一致），旧宿主 0.1.0-rc.7+ 同样可跑。交互优化：文件树选中态改为实心选中色 + 选中文字反白 + 左缘 2px 白色强调条——底色跟随宿主 `--dsw-alias-button-info-fill` 令牌（与 dshUI「对话/轨迹」页签同源，回退 #4176e6），宿主换肤自动同步；原层级灰在浅色主题下与侧栏底色仅差 5/255，选中几乎隐形。文件树根目录**按会话隔离**：宿主以 sessionId→root 映射记忆各会话的手动根（「以此文件夹为根」只影响当前会话，不再全局污染），切换会话即解析新会话的 cwd 或其记忆根——修复「新会话打开仍是旧会话地址」（原手动根为宿主级全局变量，且客户端跟随标志不持久化导致刷新后跟随失效且无提示）。未发消息的新会话也能解析根目录：会话创建时所选工作区路径已写入不可变 `SessionHeader.cwd`，经 `sessions` 服务可查（原仅查 `agents`，agent 要到首条消息后才存在）；重启后重开旧对话（agent 尚未恢复）时经 `sessionController.inspect` 读持久化 header 兜底。空新对话（blank 会话）根因：宿主对 blank 会话隐藏会话头 chrome（hideChrome），插件 InputBridge 所在 slot 不渲染、捕获不到新会话 id——新增常驻 SessionWatch（root 作用域 `shell.overlay` + 标准 props `useSessions`）监听当前选中会话，blank 会话（宿主侧 agent 在 session/create 时即建、cwd=所选工作区）也能即时换根。标签页**右键菜单**：关闭 / 关闭其他 / 关闭右侧标签页 / 关闭已保存 / 关闭全部 + 复制路径（无对象项自动置灰）；关闭波及未保存文件时弹确认框（保存并关闭 / 不保存 / 取消，多文件列清单、>5 折叠计数，保存失败者保留打开）——原标签 ✕ 按钮静默丢弃未保存改动，一并接入同一确认流程 |
 | 2026-09-02 | v1.3.2 | 调整：**切换按钮默认改为悬浮模式条**（原会话头 ⌨ 按钮，已保存选择的用户不受影响）；**文件树默认根跟随当前会话的工作区目录**——打开编辑器即定位到当前对话的项目根，会话切换自动换根（有未保存文件时暂不跟随并提示，保存后点 ⟳ 即切换）；手动「以此文件夹为根」后不再自动跟随 |

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 状态层 ============ */
@@ -297,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) {
@@ -347,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() } }, '✕'),
       )
     }
 
@@ -407,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('/'))
@@ -878,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
@@ -1016,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: '' }
@@ -1049,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) {
@@ -1158,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
@@ -1254,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
@@ -1263,9 +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：编辑器状态按会话记忆（标签快照/恢复 + 根解析），见 handleSessionSwitch
-        if (props.sessionId) handleSessionSwitch(props.sessionId)
+        if (props.sessionId) { handleSessionSwitch(props.sessionId); store.inputSessionId = props.sessionId }
+        ensureShellSubmitPatch() // 每次渲染尝试挂 shell.submit 补丁（WeakSet 幂等，会话切换后补新 shell）
         emit()
       })
       // 挂钩 DSH 原生输入条的发送：存在引用时把指针附进草稿再发（整文件=绝对路径）。
@@ -1276,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) {}
@@ -1308,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 = () => {
@@ -1326,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' },
@@ -1478,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' },
@@ -1501,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 工具获取内容。'),
         ),
       )
     }
@@ -1953,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 = []
@@ -1966,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

package/lib/index.js

@@ -664,15 +664,22 @@ function rpcHandler(ctx) {
       }
 
       if (endpoint === "add-reference") {
+        const path = args.path || "";
+        const kind = args.kind || "cite";
+        const lineStart = args.lineStart || null;
+        const lineEnd = args.lineEnd || null;
+        // 允许重复引用：chip 在输入框句中可视化，重复了用户看得见、可 ✕ 删除，无需 host 去重拦截。
+        // （原逻辑曾对同 path+行区间+kind 的未使用引用去重，行内 chip 落地后按用户要求取消）
         const id = "r" + (idSeq++);
         const ref = {
           id,
-          path: args.path || "",
+          path,
           language: args.language || "",
-          lineStart: args.lineStart || null,
-          lineEnd: args.lineEnd || null,
+          lineStart,
+          lineEnd,
           text: args.text || "",
-          kind: args.kind || "cite",
+          kind,
+          used: false, // 一次性消耗标记：随消息发送后由 use-references 置 true（chip 清空，记录保留）
           createdAt: now(),
         };
         references.push(ref);
@@ -683,6 +690,17 @@ function rpcHandler(ctx) {
         return ok({ references });
       }
 
+      if (endpoint === "use-references") {
+        // 引用一次性消耗：把本条消息附带的引用标记为 used（不删除——AI 在消息发出后才经
+        // get_referenced_snippets 读取，删除就读不到了；used 记录保留供用户在【引用/备注】查找）。
+        const ids = Array.isArray(args.ids) ? args.ids : [];
+        let n = 0;
+        for (const r of references) {
+          if (!r.used && ids.indexOf(r.id) >= 0) { r.used = true; r.usedAt = now(); n++; }
+        }
+        return ok({ ok: true, used: n });
+      }
+
       if (endpoint === "delete-reference") {
         const i = references.findIndex((r) => r.id === args.id);
         if (i >= 0) references.splice(i, 1);
@@ -911,7 +929,8 @@ function registerSnippetsTool(tools) {
             const whole = !r.lineStart;
             const label = r.kind === "translate" ? "翻译请求" : whole ? "文件引用" : "代码引用";
             const loc = (r.path || "") + (whole ? "（整个文件）" : ":" + r.lineStart + "-" + r.lineEnd);
-            const lang = r.language ? " [" + r.language + "]" : "";
+            const num = r.seq ? "，用户 tag 编号 " + r.seq : "";
+            const lang = (r.language ? " [" + r.language + "]" : "") + (r.used ? "（已使用" + (r.usedAt ? " " + r.usedAt : "") + num + "）" : "");
             const body = whole
               ? "整个文件的引用：请用你的文件读取工具打开上述绝对路径自行读取。"
               : (r.text || "");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-code-ui",
-  "version": "1.4.1",
-  "description": "Cursor 风格的 AI 代码编辑器工作台插件（DSH）：文件树、多标签页编辑、语法高亮、引用/翻译给 AI、右侧停靠/悬浮窗口双布局",
+  "version": "1.5.0",
+  "description": "Cursor 风格的 AI 代码编辑器工作台插件（DSH）：文件树、多标签页编辑、语法高亮、引用/翻译行内标签给 AI、右侧停靠/悬浮窗口双布局",
   "type": "module",
   "main": "lib/index.js",
   "repository": {