dsh-quote-annotate-pro 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 本项目的所有重要变更都记在这里。版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## 0.2.7 — 引用渲染定版：输入框与对话区都不再"先露原文"
+
+- **输入框侧（本次）**：插入引用后**同一帧内**完成装饰 —— 不再走 `setTimeout`，改为在 `MutationObserver` 回调里同步执行（回调先于绘制），消除此前约 40ms 的"先露出完整引用块"窗口
+- **对话区侧（本次）**：位置行不再"先露一百多毫秒再被隐藏"（依据录屏 + diag-sink 日志定位）
+  - 用户消息行有两副面孔：宿主的正式行带 `data-chat-anchor-key`，但消息刚发出去的那一下先渲染成 `div.*_userRow`（**还没有锚点属性**）→ 插件此前够不到，实测空窗约 122ms
+  - 现在两类行都按用户行处理（`USER_ROW_SEL`）：行出现的**同一帧**就完成装饰（MutationObserver 回调先于绘制），不再等防抖
+  - 宿主在渲染后还会重排气泡内容（实测再约 120ms 一次），会把已隐藏的位置行换回原文；判定改为**看内容**（`rowHasRawHeader()`）而不是看 `data-dshq-sent` 标记，重排的同一帧即补装饰
+  - 观察器增加 `attributeFilter: ['data-chat-anchor-key','data-chat-flow-kind']`，覆盖"先插文本、后挂锚点"的渲染顺序
+- **文本零改动**：装饰只加样式类/包一层隐藏元素，**消息文本仍是 `【引用 · 第N轮 · 角色】` + 原文** → 模型侧定位能力不变
+- 新增静默诊断探针（`cmp:probe` 等），仅在运行 `npm run diag` 时上报；发布版无任何网络请求
+
+## 0.2.6 — 输入框与消息统一为紧凑引用（消除插入瞬间的闪烁）
+
+- **输入框里的引用**：插入后渲染成**紧凑原文块**（位置行隐藏）
+  - 实现：装饰函数暴露为模块级钩子，插入成功即调用一次
+- **引用文本去掉 `> ` 前缀**（`【引用 · 第N轮 · 角色】` + 原文），编辑器里不再多露一个符号
+- **文本保持完整**：界面只是隐藏位置行（加样式类，不动编辑器文本），因此**发送出去的内容仍带轮次/角色** → 模型侧定位能力不变
+- 消息侧（0.2.3）的紧凑渲染保持不变，输入与输出观感一致
+
 ## 0.2.5 — 引用块样式：贴在输入框上沿
 
 - 0.2.4 曾把引用块挪进 `conversation.input.overlay`，实测该槽位是**浮动弹层**（放的是 slash-menu / command-popup 这类弹窗），静态内容放进去不可见 → **改回 `conversation.input.dock`**

package/README.en.md

@@ -17,8 +17,8 @@
 | --- | --- |
 | Select & annotate | Select text in the transcript → a bubble appears above the selection → write a comment (optional) → `Enter` |
 | Quote chip | An atomic `引用1` chip (short label) lands in the composer; it expands to the full quote block on send |
-| **Quote block** | While a quote is in the composer, a compact block above it shows the **quoted text snippet** (single line, ellipsised). Click it to jump back to the source and highlight it — no visible "jump" affordance, so the composer stays clean |
-| **Compact quotes in the transcript** | A sent message shows only a **compact quote block** (up to 3 lines) — the `【引用 · 第N轮 · 角色】` label is hidden. Clicking the block jumps back to the source and highlights it, while the message payload still carries the turn/role, so the model keeps the position context |
+| **Quote block (in the composer)** | After inserting a quote the composer shows only the **quoted text** (the turn/role line is hidden); click it to jump back to the source and highlight it — no visible "jump" affordance |
+| **Compact quotes in the transcript** | A sent message shows only a **compact quote block** (up to 3 lines). The message text still starts with `【引用 · 第N轮 · 角色】` — hidden in the UI, so the model keeps the position context |
 | **Turn-accurate context** | The quote block starts with `【引用 · 第3轮 · 你的消息】` followed by `> quoted text`, so the model knows exactly which turn and whose message |
 | Turn-level quoting | Every finished turn gets `引用提问` / `引用回答` buttons that quote the whole question or answer |
 | Anchors survive reload | The `ref → anchor` map is persisted in `localStorage` (per session, 60 entries max), so quotes still jump after a page refresh |

package/README.md

@@ -17,8 +17,8 @@
 |---|---|
 | 划词批注 | 会话里选中任意文字 → 选区上方浮出气泡（预览 + 「批注」）→ 编辑框里写评语（可留空）→ `Enter` 插入 |
 | 引用 chip | 输入框里出现 `引用1` 的原子 chip（短标签）；发送时展开为完整引用块 |
-| **引用块（输入框上方）** | 有引用时在输入框上方显示**原文片段**（单行、超出省略）；**点一下即跳回原文并高亮** —— 不做任何可见的"跳转"提示，保持输入区干净 |
-| **对话页里的紧凑引用** | 已发送消息里的引用也只显示**紧凑原文块**（最多 3 行），**不显示"第N轮/谁说的"标签**；点该块可跳回原文。而**消息本体仍带位置信息**，模型照旧知道出处 |
+| **引用块（输入框内）** | 插入引用后输入框里只显示**原文片段**（位置行隐藏）；**点一下即跳回原文并高亮** —— 不做任何可见的"跳转"提示 |
+| **对话页里的紧凑引用** | 已发送消息里的引用同样只显示**紧凑原文块**（最多 3 行）。**消息文本仍以 `【引用 · 第N轮 · 角色】` 开头** —— 界面隐藏、模型照旧知道出处 |
 | **模型侧精确定位** | 引用块首行是 `【引用 · 第5轮 · 你的消息】`，后接 `> 原文`，让模型明确知道**哪一轮、谁说的** |
 | 回合级引用 | 每条已完成回合尾部有「引用提问 / 引用回答」，整段引用该轮 |
 | 锚点持久化 | `ref → 锚点` 映射写入 `localStorage`（按会话，最多 60 条），**刷新页面后引用块仍能跳回原文** |

package/lib/client.js

@@ -147,6 +147,10 @@ window.__ModuleLoader__.load({
     const refTargets = new Map()
     // ref -> { body, clipboardText } 提交时经 codec 序列化
     const refCodecs = new Map()
+    // 输入框引用装饰的"立即执行"钩子：插入后马上贴样式，避免先露出旧样子再变（用户反馈的瞬间闪烁）
+    let composerDecorateNow = null
+    // 诊断用：最近一次插入引用的时刻（毫秒），用于测"装饰相对插入晚了多久"
+    let lastInsertAt = 0
 
     // 页面内反馈 toast（点击 chip 时显示结果）
     const toastStore = {
@@ -735,8 +739,8 @@ window.__ModuleLoader__.load({
         try {
           const c = (comment || '').trim()
           const header = buildQuoteHeader(item)
-          const quoted = item.text.split('\n').map((line) => '> ' + line).join('\n')
-          const quoteBody = header === '' ? quoted : header + '\n' + quoted
+          // 引用正文不再加 "> " 前缀：输入框与消息里都由插件渲染成紧凑块（前缀会在编辑器里露出一截符号）
+          const quoteBody = header === '' ? item.text : header + '\n' + item.text
           const conversation = rootCtx ? rootCtx.get('conversation') : undefined
           const sessions = rootCtx ? rootCtx.get('sessions') : undefined
           if (!conversation || !conversation.input || !sessions) {
@@ -762,6 +766,8 @@ window.__ModuleLoader__.load({
           const ref = 'q' + REF_RUN + (++refSeq)
           // 输入框里的 chip 文案只要短、可区分即可（轮次/角色写在发送后的引用块里，不在输入框展示）
           const chipLabel = '引用' + refSeq
+          // 输入框与消息里显示的就是这段文本（实测：宿主消息 = 草稿文本，WYSIWYG）；
+          // 因此位置行（【引用 · 第N轮 · 角色】）保留在文本里给模型用，界面上由插件渲染时隐藏。
           refTargets.set(ref, { sessionId, anchorKey: item.anchorKey || null, body: quoteBody, label: chipLabel })
           refCodecs.set(ref, { body: quoteBody, clipboardText: quoteBody })
           saveRef(sessionId, ref, { anchorKey: item.anchorKey || null, body: quoteBody, label: chipLabel })
@@ -791,7 +797,19 @@ window.__ModuleLoader__.load({
               const st3 = input.state.getSnapshot()
               input.setDraft(st3.draft.replace(/[ \t]+$/, '') + commentTail)
             }
+            try {
+              const snap2 = input.state.getSnapshot()
+              const occ2 = (snap2 && snap2.occurrences) || []
+              report('insert:draft', {
+                draft: String((snap2 && snap2.draft) || '').replace(/\s+/g, ' ').slice(0, 120),
+                occ: occ2.length,
+                occLabels: occ2.map((o) => (o && o.label) || '').join('|').slice(0, 80),
+              })
+            } catch (e) { /* ignore */ }
             report('insert:chip', { ref, anchorKey: item.anchorKey || null, header, chars: item.text.length })
+            // 立刻给刚插入的内容贴样式，避免"先露出旧样子、稍后才变紧凑"的闪烁
+            lastInsertAt = (typeof performance !== 'undefined' ? performance.now() : Date.now())
+            try { if (typeof composerDecorateNow === 'function') composerDecorateNow() } catch (e) { /* ignore */ }
             setStatus({
               ok: true,
               text: '已插入引用 ✓' + (item.anchorKey ? '（输入框上方的引用块可点回原文）' : '（未定位到消息行，可能无法跳回）'),
@@ -997,6 +1015,11 @@ window.__ModuleLoader__.load({
 .dshq-sent-quote{display:block;margin:3px 0;padding:6px 10px;border-radius:8px;background:rgba(127,127,127,.10);color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1.5;cursor:pointer;overflow:hidden;transition:background .12s ease,color .12s ease}
 .dshq-sent-quote:hover{color:var(--dsw-alias-label-primary)}
 .dshq-sent-quote-text{display:-webkit-box;-webkit-line-clamp:3;-webkit-box-orient:vertical;overflow:hidden;white-space:pre-wrap;word-break:break-word}
+/* 输入框里的引用：隐藏位置行，正文显示为紧凑块（输入框与消息观感一致） */
+.dshq-cmp-header{display:none !important}
+.dshq-cmp-quote{background:rgba(127,127,127,.10);border-radius:8px;padding:2px 10px;margin:2px 0}
+.dshq-cmp-quote-first{margin-top:4px}
+.dshq-cmp-quote-last{margin-bottom:4px}
 `
 
     // ============ 插件主体 ============
@@ -1270,18 +1293,22 @@ window.__ModuleLoader__.load({
             })
             return wrap
           }
-          /** 把承载「【引用…】\n> 原文…」的文本节点拆成：隐藏头部 + 紧凑引用块 + 其余文本 */
+          /** 把承载「【引用…】\n原文…」的文本节点拆成：隐藏头部 + 紧凑引用块 + 其余文本 */
           const transformTextNode = (node) => {
             const raw = node.nodeValue || ''
             const m = HEADER_RE.exec(raw)
             if (!m) return false
-            const quoteStart = m.index + m[0].length
-            const nl = raw.indexOf('\n', quoteStart)
+            const after = raw.slice(m.index + m[0].length)
+            const nl = after.indexOf('\n')
             if (nl < 0) return false
-            const lines = raw.slice(nl + 1).split('\n')
+            const lines = after.slice(nl + 1).split('\n')
+            // 引用正文 = 头部之后、直到空行之前的连续非空行（兼容旧格式的 "> " 前缀）
             const quote = []
             let i = 0
-            while (i < lines.length && /^>\s?/.test(lines[i])) { quote.push(lines[i].replace(/^>\s?/, '')); i++ }
+            for (; i < lines.length; i++) {
+              if (lines[i].trim() === '') break
+              quote.push(lines[i].replace(/^>\s?/, ''))
+            }
             if (quote.length === 0) return false
             const rest = lines.slice(i).join('\n')
             const frag = document.createDocumentFragment()
@@ -1300,17 +1327,22 @@ window.__ModuleLoader__.load({
           const scan = () => {
             timer = null
             try {
-              for (const row of document.querySelectorAll('[data-chat-anchor-key]')) {
-                if (row.getAttribute('data-chat-flow-kind') !== 'user') continue
-                if (row.dataset && row.dataset.dshqSent === '1') continue
+              for (const row of document.querySelectorAll(USER_ROW_SEL)) {
+                const kind = row.getAttribute('data-chat-flow-kind')
+                if (kind && kind !== 'user') continue
                 let walker
                 try { walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT, null) } catch (e) { continue }
                 const targets = []
                 let n = walker.nextNode()
                 while (n) {
-                  if (HEADER_RE.test(n.nodeValue || '')) targets.push(n)
+                  const parent = n.parentElement
+                  // 已经装饰过的部分（隐藏的位置行 / 紧凑引用块）不再重复处理
+                  const managed = parent && typeof parent.closest === 'function'
+                    ? parent.closest('.dshq-sent-header, .dshq-sent-quote') : null
+                  if (!managed && HEADER_RE.test(n.nodeValue || '')) targets.push(n)
                   n = walker.nextNode()
                 }
+                if (targets.length === 0) continue
                 let done = false
                 for (const t of targets) { try { if (transformTextNode(t)) done = true } catch (e) { /* ignore */ } }
                 if (done && row.dataset) row.dataset.dshqSent = '1'
@@ -1318,10 +1350,80 @@ window.__ModuleLoader__.load({
             } catch (e) { report('sent:scan-throw', String((e && e.message) || e)) }
           }
           const schedule = () => { if (timer === null) timer = setTimeout(scan, 300) }
+          // 消息从输入框进入对话区时，首帧先画出的是原始文本（含"【引用 · …】"位置行），
+          // 300ms 防抖会让它闪一下。MutationObserver 回调在下一次绘制前执行，
+          // 因此只要这次变动牵扯到"还没装饰过的用户消息行"就同步扫一次，首帧即完成隐藏；
+          // 其余情况（例如助手流式输出）仍走防抖，不增加扫描开销。
+          // 用户消息行有两副面孔：正式行带 anchor 属性；但实测"刚发出去"的那一下，
+          // 宿主先渲染出 <div class="cJsG2q_userRow">（还没有 data-chat-anchor-key），
+          // 等属性挂上才轮得到插件 —— 那段空窗就是用户看到的闪。两类都按用户行处理。
+          const USER_ROW_SEL = '[data-chat-anchor-key][data-chat-flow-kind="user"], [class*="userRow" i]'
+          const asElement = (node) => (node && node.nodeType === 1 ? node : (node && node.parentElement) || null)
+          // 行里是否还存在"没被插件接管过的"位置行文本。
+          // 宿主会在渲染后重排/替换气泡内容（实测发送后约 120ms 会有一次），
+          // 那时我们贴好的隐藏 span 会被换回原始文本 —— 用内容判断而不是用标记判断，
+          // 才能在重渲染的同一帧里立刻补装饰。
+          const rowHasRawHeader = (row) => {
+            try {
+              const walker = document.createTreeWalker(row, NodeFilter.SHOW_TEXT, null)
+              let n = walker.nextNode()
+              while (n) {
+                const parent = n.parentElement
+                const managed = parent && typeof parent.closest === 'function'
+                  ? parent.closest('.dshq-sent-header, .dshq-sent-quote') : null
+                if (!managed && HEADER_RE.test(n.nodeValue || '')) return true
+                n = walker.nextNode()
+              }
+              return false
+            } catch (e) { return false }
+          }
+          const touchesPendingUserRow = (node) => {
+            const el = asElement(node)
+            if (!el || typeof el.closest !== 'function') return false
+            const row = el.closest(USER_ROW_SEL)
+            // ① 变动落在用户消息行内部（含行自身）：只要还能找到未接管的位置行就立刻扫
+            if (row) {
+              const kind = row.getAttribute('data-chat-flow-kind')
+              if (kind && kind !== 'user') return false
+              return rowHasRawHeader(row)
+            }
+            // ② 新增的子树里带着这样的用户消息行（宿主可能整块替换容器）
+            if (typeof el.querySelector === 'function') {
+              try {
+                for (const r of el.querySelectorAll(USER_ROW_SEL)) {
+                  const kind = r.getAttribute('data-chat-flow-kind')
+                  if (kind && kind !== 'user') continue
+                  if (rowHasRawHeader(r)) return true
+                }
+              } catch (e) { /* ignore */ }
+            }
+            return false
+          }
+          const onMutations = (records) => {
+            let urgent = false
+            try {
+              for (const r of records) {
+                const cands = [r.target]
+                const added = r.addedNodes
+                if (added) { for (const n of added) cands.push(n) }
+                for (const c of cands) {
+                  if (!urgent && touchesPendingUserRow(c)) urgent = true
+                }
+              }
+              if (urgent) scan()
+            } catch (e) { /* ignore */ }
+            schedule()
+          }
           scan()
           try {
-            observer = new MutationObserver(schedule)
-            observer.observe(document.body, { childList: true, subtree: true })
+            observer = new MutationObserver(onMutations)
+            observer.observe(document.body, {
+              childList: true,
+              subtree: true,
+              characterData: true,
+              attributes: true,
+              attributeFilter: ['data-chat-anchor-key', 'data-chat-flow-kind'],
+            })
           } catch (e) { report('sent:observer-throw', String((e && e.message) || e)) }
           return () => {
             if (timer !== null) clearTimeout(timer)
@@ -1331,6 +1433,79 @@ window.__ModuleLoader__.load({
       } catch (e) {
         report('apply:sent-decor-throw', String((e && e.message) || e))
       }
+
+      // ============ 输入框里的引用：隐藏位置行 + 紧凑块（与消息里的渲染保持一致） ============
+      // 只给编辑器的行元素加 class，**不改动编辑器文本** → 发送出去的内容不变（模型仍拿到位置信息）。
+      // 编辑器重渲染会丢掉 class，因此用 MutationObserver 重新贴上。
+      try {
+        ctx.effect(() => {
+          let timer = null
+          let observer = null
+          const isSingleLine = (t) => t !== '' && t.indexOf('\n') === -1
+          let lastSig = ''
+          const decorate = () => {
+            timer = null
+            try {
+              for (const ed of document.querySelectorAll('[contenteditable="true"]')) {
+                const kids = Array.from(ed.children || [])
+                let headerEl = null
+                const quoteEls = []
+                for (const el of kids) {
+                  const t = String(el.textContent || '').trim()
+                  if (!headerEl) {
+                    // 位置行必须"整行且只有一行"，避免误把整个编辑器当成头部
+                    if (isSingleLine(t) && /^【引用\s*·[^\n]*】$/.test(t)) headerEl = el
+                    continue
+                  }
+                  if (t === '') break
+                  if (!isSingleLine(t)) break
+                  quoteEls.push(el)
+                }
+                if (!headerEl) {
+                  // 诊断：编辑器里出现了"【引用"但没能匹配成"位置行 + 正文行"时，把结构打出来
+                  const raw = String(ed.textContent || '')
+                  if (raw.indexOf('【引用') >= 0) {
+                    const sig = raw.slice(0, 40) + '|' + kids.length
+                    if (sig !== lastSig) {
+                      lastSig = sig
+                      report('cmp:probe', {
+                        ms: lastInsertAt ? Math.round((typeof performance !== 'undefined' ? performance.now() : Date.now()) - lastInsertAt) : null,
+                        kids: kids.length,
+                        singles: kids.map((el) => (isSingleLine(String(el.textContent || '').trim()) ? 1 : 0)).join(''),
+                        first: String((kids[0] && kids[0].textContent) || '').slice(0, 24),
+                      })
+                    }
+                  }
+                  continue
+                }
+                headerEl.classList.add('dshq-cmp-header')
+                quoteEls.forEach((el, idx) => {
+                  el.classList.add('dshq-cmp-quote')
+                  el.classList.toggle('dshq-cmp-quote-first', idx === 0)
+                  el.classList.toggle('dshq-cmp-quote-last', idx === quoteEls.length - 1)
+                })
+                report('cmp:decorated', { lines: quoteEls.length })
+              }
+            } catch (e) { report('cmp:scan-throw', String((e && e.message) || e)) }
+          }
+          // 关键：MutationObserver 回调在**下一次绘制之前**执行 —— 因此在这里同步装饰即可消除
+          // "先露出完整引用块、稍后才变紧凑"的闪烁（之前用 setTimeout(40ms) 期间已经画了一帧）。
+          // decorate() 只在缺少 class 时改动 DOM，不会形成观察循环。
+          decorate()
+          composerDecorateNow = decorate
+          try {
+            observer = new MutationObserver(() => { decorate() })
+            observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+          } catch (e) { report('cmp:observer-throw', String((e && e.message) || e)) }
+          return () => {
+            if (composerDecorateNow === decorate) composerDecorateNow = null
+            if (timer !== null) clearTimeout(timer)
+            if (observer) { try { observer.disconnect() } catch (e) { /* ignore */ } }
+          }
+        }, 'dsh-quote-annotate-pro: composer quote decoration')
+      } catch (e) {
+        report('apply:cmp-decor-throw', String((e && e.message) || e))
+      }
       const tryRegister = (tag, fn) => {
         try { fn(); report('register:ok', tag); return true } catch (e) {
           report('register:throw', tag + ' :: ' + String((e && e.stack) || (e && e.message) || e))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-quote-annotate-pro",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "选区引用与锚点批注（增强 fork）：划词 → 批注 → 带精确锚点的引用；输入框上方只显示原文片段，点一下跳回原文；发送时把轮次/角色写入引用块，让模型精确知道你指的是哪一处。",
   "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "quote", "annotate", "selection", "reference", "anchor"],
   "license": "MIT",