@mzzsfy/dsh-think-expand 0.2.3 → 0.2.4

package/README.md

@@ -14,6 +14,7 @@ DeepSeek Harness 插件:流式输出思考时自动展开最新一条思考行,
 | 打开会话 / 刷新页面 / 切换会话 | 最后一条思考行自动展开,其余保持收起 |
 | 自动展开后用户手动收起 | 不再重展开,直到下次打开或切换会话 |
 | 用户手动展开较旧行 | 手动意图优先,插件不展开最后一条 |
+| 插件展开/收起动作改变内容高度 | 动作前置底的视口在高度落定后回补置底,官方自动滚动跟随不失联;用户主动滚开则不干预 |
 | 卸载插件 | 无持久副作用,重载页面即恢复官方默认行为 |
 
 无任何设置项,安装即自动生效;同一时刻至多一条思考行处于展开状态;不做行数裁剪,不改写思考正文与官方折叠组件结构。
@@ -23,7 +24,8 @@ DeepSeek Harness 插件:流式输出思考时自动展开最新一条思考行,
 - Think 行识别:官方 ReasoningRow 根节点字面量属性 `[data-variant="think"]` + `data-state`,折叠头 `[data-disclosure-row]`,滚动容器 `[data-conversation-scroll]`;正文容器按 `thinkBody` 类名子串匹配(CSS Modules 哈希带前缀);识别失败即不干预。
 - 展开/收起模拟点击折叠头(按 `aria-expanded` 判定),与官方组件状态机一致,不直改 DOM 内部状态,不写任何 DOM 属性。
 - 行标识 = 控制器侧元素稳定 uid(WeakMap 计数),标记命中 uid 优先、已见文本前缀兜底,标记载体为模块级 Map(键为登记时文本);client 端插件展开过的行另以元素 WeakSet 记闩锁(展开记入、收起解除,会话切换重置),供决策层区分手动展开,不写 DOM 属性;全部标记随页面生命周期存活,不持久化。body 哨兵观察器常驻 document.body 监视容器身份变化(会话切换,仅 childList 通道);容器重挂后首扫抑制手动识别,既存展开行视为中性;观察器句柄挂 window 代际槽,HMR 重评估先拆上一代,防多套决策机并行同扫。
-- 纯逻辑层(行分类、展开决策、标记存活性)在 `src/logic.mjs`,`src/client.js` 内嵌同源实现,`node --test` 以同一套 BDD 场景对两份实现做 parity 验证,并逐函数对比源码文本(含内部助手)防双写漂移。
+- 纯逻辑层(行分类、展开决策、标记存活性、置底判定)在 `src/logic.mjs`,`src/client.js` 内嵌同源实现,`node --test` 以同一套 BDD 场景对两份实现做 parity 验证,并逐函数对比源码文本(含内部助手)防双写漂移。
+- 置底保持:官方滚动跟随以"视口贴近底部"为前提(距离底部不超过阈值判定置底),插件展开/收起改变内容高度会把置底视口推离底部,官方跟随随即失联。动作前记录置底状态,高度落定(rAF 帧计数)后偏离量可被本次高度变化解释才回补置底,用户主动滚开不干预;判定函数进纯逻辑层。
 - Host 半区 `src/index.js` 为空壳,profile 行仅用于让 client 模块系统发现本包的 dsh.client 声明。
 
 ## 安装
@@ -51,7 +53,7 @@ pnpm --dir packages/dsh-think-expand test
 node --test packages/dsh-think-expand/test/*.test.mjs
 ```
 
-覆盖:上表全部行为场景、uid 行身份(同开头历史行不劫持定位、已读标记不拦同开头新行)、suppressManual 首扫、批量 running 降级、识别失败降级、空正文降级、双实现 parity(场景 + 导出键守卫 + 逐函数源码对比)、client.js 语法检查。
+覆盖:上表全部行为场景、置底判定与置底回补判定(阈值边界/高度变化可解释偏离/用户滚开不回补)、uid 行身份(同开头历史行不劫持定位、已读标记不拦同开头新行)、suppressManual 首扫、批量 running 降级、识别失败降级、空正文降级、双实现 parity(场景 + 导出键守卫 + 逐函数源码对比)、client.js 语法检查。
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-think-expand",
   "description": "流式回复时自动展开 AI 思考过程,始终显示最新一条;安装即生效,手动操作优先,装卸无残留",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -35,6 +35,22 @@ window.__ModuleLoader__.load({
     // 已见文本 Map 容量上限,超出按插入序裁剪最旧条目(手动/已读标记增长有界)。
     const SEEN_MAP_CAP = 10 * 20
 
+    // 置底判定阈值:与官方滚动跟随的贴近底部语义一致,距离底部不超过该值视为置底。
+    const PIN_THRESHOLD_PX = 25
+
+    // 置底判定:视口距底部不超过阈值;度量形态 { scrollHeight, scrollTop, clientHeight }。
+    function isPinned(metrics, threshold = PIN_THRESHOLD_PX) {
+      return metrics.scrollHeight - metrics.scrollTop - metrics.clientHeight <= threshold
+    }
+
+    // 置底回补判定:动作后偏离底部的量可被本次高度变化解释(官方跟随失效或浏览器
+    // 未补偿)才回补;用户在落定窗口内主动滚开的偏离超出该范围,不干预。
+    function shouldPinRestore(before, after, threshold = PIN_THRESHOLD_PX) {
+      const distance = after.scrollHeight - after.scrollTop - after.clientHeight
+      const heightDelta = after.scrollHeight - before.scrollHeight
+      return distance <= Math.abs(heightDelta) + threshold
+    }
+
     function capMap(map, cap = SEEN_MAP_CAP) {
       while (map.size > cap) {
         const oldest = map.keys().next()
@@ -249,28 +265,75 @@ window.__ModuleLoader__.load({
 
     const collectRows = (container) => Array.from(container.querySelectorAll(SELECTOR_ROW), describeRow)
 
-    // 执行动作并返回被点击的行元素(未触发点击返回 null)
-    function applyAction(described, action) {
+    // 执行动作并返回被点击的行元素(未触发点击返回 null)。
+    // 动作改变内容高度会把置底视口推离底部,官方滚动跟随随即失联:
+    // 动作前处于置底态时,高度落定后回补置底。
+    function applyAction(container, described, action) {
       const row = described[action.index]
       if (!row || !row.headable) return null
       const head = row.el.querySelector(SELECTOR_HEAD)
       if (head === null) return null
       if (head.getAttribute(ATTR_EXPANDED) !== String(action.kind === 'expand')) {
+        const before = containerMetrics(container)
         if (action.kind === 'expand') pluginExpandedEls.add(row.el)
         else pluginExpandedEls.delete(row.el)
         head.click()
+        if (isPinned(before)) schedulePinRestore(container, before)
         return row.el
       }
       return null
     }
 
+    // ---- 置底回补 ----
+
+    const containerMetrics = (container) => ({
+      scrollHeight: container.scrollHeight,
+      scrollTop: container.scrollTop,
+      clientHeight: container.clientHeight,
+    })
+
+    // 高度落定判定:高度变化后连续 SETTLE_FRAMES 帧不变即落定;
+    // 总帧数达上限按已落定兜底(渲染停滞环境不永久挂起)。
+    const PIN_SETTLE_FRAMES = 2
+    const PIN_SETTLE_MAX_FRAMES = 30
+
+    // 单一挂起回补任务(slot 代际槽):同批多动作时以最新前置度量重启,
+    // HMR 重评估经槽身份校验作废。
+    function schedulePinRestore(target, before) {
+      if (window[SLOT_KEY] !== slot) return
+      if (slot.pinFrame !== null) cancelAnimationFrame(slot.pinFrame)
+      let lastHeight = before.scrollHeight
+      let changed = false
+      let stableFrames = 0
+      let totalFrames = 0
+      const tick = () => {
+        slot.pinFrame = null
+        if (window[SLOT_KEY] !== slot || target !== observedContainer || !target.isConnected) return
+        const metrics = containerMetrics(target)
+        if (metrics.scrollHeight !== lastHeight) {
+          lastHeight = metrics.scrollHeight
+          changed = true
+          stableFrames = 0
+        } else {
+          stableFrames += 1
+        }
+        totalFrames += 1
+        if (totalFrames < PIN_SETTLE_MAX_FRAMES && (!changed || stableFrames < PIN_SETTLE_FRAMES)) {
+          slot.pinFrame = requestAnimationFrame(tick)
+          return
+        }
+        if (shouldPinRestore(before, metrics)) target.scrollTop = target.scrollHeight
+      }
+      slot.pinFrame = requestAnimationFrame(tick)
+    }
+
     function scan() {
       const container = document.querySelector(SELECTOR_SCROLL)
       // 容器身份守卫:容器替换至哨兵回调之间,旧观察器投递的扫描不对新容器用旧 registry 决策
       if (container === null || container !== observedContainer) return 0
       const described = collectRows(container)
       releaseLatchIfCollapsed(described)
-      for (const action of plan(registry, toLogicRows(described)).actions) applyAction(described, action)
+      for (const action of plan(registry, toLogicRows(described)).actions) applyAction(container, described, action)
       return described.length
     }
 
@@ -313,7 +376,7 @@ window.__ModuleLoader__.load({
       if (!described.some((row) => row.headable)) return
       finalState.pending = false
       for (const action of planFinal(toLogicRows(described)).actions) {
-        const clicked = applyAction(described, action)
+        const clicked = applyAction(container, described, action)
         if (clicked !== null) {
           finalState.el = clicked
           finalState.awaitRegister = true
@@ -366,7 +429,7 @@ window.__ModuleLoader__.load({
       if (container === null) return 0
       const described = collectRows(container)
       const actions = plan(registry, toLogicRows(described), { suppressManual: true }).actions
-      for (const action of actions) applyAction(described, action)
+      for (const action of actions) applyAction(container, described, action)
       return described.length
     }
 
@@ -381,8 +444,9 @@ window.__ModuleLoader__.load({
         if (previous.bodySentinel !== null) previous.bodySentinel.disconnect()
         if (previous.containerObserver !== null) previous.containerObserver.disconnect()
         if (previous.debounceTimer !== null) clearTimeout(previous.debounceTimer)
+        if (previous.pinFrame !== null) cancelAnimationFrame(previous.pinFrame)
       }
-      slot = { bodySentinel: null, containerObserver: null, debounceTimer: null }
+      slot = { bodySentinel: null, containerObserver: null, debounceTimer: null, pinFrame: null }
       window[SLOT_KEY] = slot
       bodySentinel = new MutationObserver(ensureAttached)
       slot.bodySentinel = bodySentinel

package/src/logic.mjs

@@ -7,6 +7,22 @@ export const STATE_OK = 'ok'
 // 已见文本 Map 容量上限,超出按插入序裁剪最旧条目(手动/已读标记增长有界)。
 export const SEEN_MAP_CAP = 10 * 20
 
+// 置底判定阈值:与官方滚动跟随的贴近底部语义一致,距离底部不超过该值视为置底。
+export const PIN_THRESHOLD_PX = 25
+
+// 置底判定:视口距底部不超过阈值;度量形态 { scrollHeight, scrollTop, clientHeight }。
+export function isPinned(metrics, threshold = PIN_THRESHOLD_PX) {
+  return metrics.scrollHeight - metrics.scrollTop - metrics.clientHeight <= threshold
+}
+
+// 置底回补判定:动作后偏离底部的量可被本次高度变化解释(官方跟随失效或浏览器
+// 未补偿)才回补;用户在落定窗口内主动滚开的偏离超出该范围,不干预。
+export function shouldPinRestore(before, after, threshold = PIN_THRESHOLD_PX) {
+  const distance = after.scrollHeight - after.scrollTop - after.clientHeight
+  const heightDelta = after.scrollHeight - before.scrollHeight
+  return distance <= Math.abs(heightDelta) + threshold
+}
+
 // 前缀匹配:空串 seen 会命中任意行,视为无匹配。
 function prefixOf(seen, text) {
   return seen.length > 0 && text.length >= seen.length && text.startsWith(seen)

package/test/logic.test.mjs

@@ -21,7 +21,7 @@ function clientLogic() {
   const factory = new Function(
     '"use strict";'
       + section
-      + '; return { STATE_RUNNING, STATE_OK, createRegistry, plan, planFinal, registerCurrent, capMap, needsReattach, SEEN_MAP_CAP, prefixOf, matchMark, findSeenKey, isCurrent, putSeen, findRow };',
+      + '; return { STATE_RUNNING, STATE_OK, createRegistry, plan, planFinal, registerCurrent, capMap, needsReattach, SEEN_MAP_CAP, prefixOf, matchMark, findSeenKey, isCurrent, putSeen, findRow, PIN_THRESHOLD_PX, isPinned, shouldPinRestore };',
   )
   return factory()
 }
@@ -37,7 +37,50 @@ const collapseOf = (result, index) =>
   result.actions.filter((a) => a.index === index && a.kind === 'collapse').length
 
 function defineScenarios(prefix, L) {
-  const { createRegistry, plan, planFinal, registerCurrent, STATE_RUNNING, STATE_OK, capMap, needsReattach, SEEN_MAP_CAP } = L
+  const { createRegistry, plan, planFinal, registerCurrent, STATE_RUNNING, STATE_OK, capMap, needsReattach, SEEN_MAP_CAP, PIN_THRESHOLD_PX, isPinned, shouldPinRestore } = L
+
+  // 滚动度量构造:{ scrollHeight, scrollTop, clientHeight }
+  const metrics = (scrollHeight, scrollTop, clientHeight) => ({ scrollHeight, scrollTop, clientHeight })
+
+  test(prefix + '置底判定:距离不超过阈值视为置底', () => {
+    // 距离 = 800 - 0 - 600 = 200,远超阈值,非置底
+    assert.equal(isPinned(metrics(800, 0, 600)), false)
+    // 恰好触底(scrollTop = scrollHeight - clientHeight)
+    assert.equal(isPinned(metrics(800, 550, 600)), true)
+    // 距离等于阈值,边界内置底
+    assert.equal(isPinned(metrics(800, 800 - 600 - PIN_THRESHOLD_PX, 600)), true)
+    // 距离超出阈值一个像素,非置底
+    assert.equal(isPinned(metrics(800, 800 - 600 - PIN_THRESHOLD_PX - 1, 600)), false)
+  })
+
+  test(prefix + '置底回补判定:偏离可被高度变化解释才回补', () => {
+    // 展开:高度 +500,原置底,官方未自愈(偏离 500)→ 回补
+    const before = metrics(1000, 300, 700)
+    const afterExpand = metrics(1500, 300, 700)
+    assert.equal(shouldPinRestore(before, afterExpand), true)
+    // 官方已自愈(已在底部)→ 回补判定为真,写入为幂等无操作
+    assert.equal(shouldPinRestore(before, metrics(1500, 800, 700)), true)
+    // 用户落定窗口内主动滚开:偏离超出变化量 + 阈值 → 不回补
+    const userScrolled = metrics(1500, 800 - PIN_THRESHOLD_PX - 1 - 500, 700)
+    assert.equal(shouldPinRestore(before, userScrolled), false)
+    // 收起:高度 -300,无钳制无锚定(偏离 300)→ 回补
+    const afterCollapse = metrics(700, 300, 700)
+    assert.equal(shouldPinRestore(before, afterCollapse), true)
+    // 收起后浏览器已钳制回底部 → 幂等
+    assert.equal(shouldPinRestore(before, metrics(700, 0, 700)), true)
+    // 高度未变化(原点击未改变高度)且已在底 → 幂等回补
+    assert.equal(shouldPinRestore(before, metrics(1000, 300, 700)), true)
+  })
+
+  test(prefix + '置底回补阈值可显式覆盖', () => {
+    const before = metrics(1000, 300, 700)
+    // 阈值 0:偏离恰等于高度变化量(500)→ 回补;再多一像素 → 不回补
+    assert.equal(shouldPinRestore(before, metrics(1500, 300, 700), 0), true)
+    assert.equal(shouldPinRestore(before, metrics(1500, 299, 700), 0), false)
+    // 默认阈值下偏离变化量 + 25 以内 → 回补
+    assert.equal(shouldPinRestore(before, metrics(1500, 275, 700)), true)
+    assert.equal(shouldPinRestore(before, metrics(1500, 274, 700)), false)
+  })
 
   test(prefix + '流式思考自动展开', () => {
     const reg = createRegistry()
@@ -329,7 +372,7 @@ test('LOGIC 段与 logic.mjs 逐函数源码一致(归一化注释与空白,含
     .replace(/\/\*[\s\S]*?\*\//g, '')
     .replace(/\/\/[^\n]*/g, '')
     .replace(/\s+/g, '')
-  for (const name of ['plan', 'planFinal', 'createRegistry', 'capMap', 'needsReattach', 'registerCurrent']) {
+  for (const name of ['plan', 'planFinal', 'createRegistry', 'capMap', 'needsReattach', 'registerCurrent', 'isPinned', 'shouldPinRestore']) {
     assert.equal(
       normalize(client[name].toString()),
       normalize(logic[name].toString()),
@@ -343,7 +386,7 @@ test('LOGIC 段与 logic.mjs 逐函数源码一致(归一化注释与空白,含
       'LOGIC 段内部助手与 logic.mjs 漂移: ' + name,
     )
   }
-  for (const name of ['STATE_RUNNING', 'STATE_OK', 'SEEN_MAP_CAP']) {
+  for (const name of ['STATE_RUNNING', 'STATE_OK', 'SEEN_MAP_CAP', 'PIN_THRESHOLD_PX']) {
     assert.equal(client[name], logic[name], '常量漂移: ' + name)
   }
 })