移动端历史预载 OranImp/dsh-fast-history

dsh-fast-history

English · 中文

DSH Web 历史会话渐进加载插件（面向手机/小屏）：首屏最近消息 → 后台预读少量历史 → 接近已加载头部提前补页；支持触摸屏/移动端。只影响显示，Host 为模型组装的上下文不变。

仓库：<https://github.com/OranImp/dsh-fast-history> · npm：dsh-fast-history（尚未发布）· MIT

面向 DSH Web 的移动优先客户端插件，渐进加载会话历史。最新消息先渲染（保留官方 tail-first 行为）；旧历史在后台预读，接近当前已加载头部时自动加载——针对手机和小屏调优。只改变显示内容；host 组装的模型上下文不受影响。

仓库：<https://github.com/OranImp/dsh-fast-history> · npm 包：dsh-fast-history（尚未发布）· MIT

官方 DSH 的行为

- 打开会话时加载尾部页（至少 50 条消息 / 2 个 Turn 起点，最多 500 条消息）。
- 顶部显示手动 Load earlier 按钮；每次点击前置一页。
- 没有滚动触发的自动加载，没有后台预读，也从不驱逐已加载窗口。
- 页大小和初始窗口在客户端硬编码，无配置。

本插件填补这些空白，不改动 host 或模型上下文。

功能

1. Tail-first 首屏 —— 与官方行为一致；不额外请求初始页。
2. 后台预读 —— 首屏稳定且会话空闲后，直接通过 SessionFace.loadOlder() 加载一页旧历史（0/1/2 可配置）。
3. 提前自动加载 —— 当你距离已加载头部 1.5 屏以内（可配置：1/1.5/2）时加载，不必等到「Load earlier」控件成为唯一继续方式。提前加载直接调用 loadOlder()，因为官方按钮在屏幕外，beginPaging() 会锚定到最旧行。
4. 链式补页 —— 如果一页短于提前量，每次接近最多连续加载 4 页（含首次）；头部离开提前量、历史结束、加载失败或会话切换时停止。
5. 触摸 / 移动端 —— 支持触摸输入；仅单指；忽略捏合和嵌套滚动容器（如代码块）。手指抬起且滚动安静约 140 ms 后才加载：手指按下或惯性滚动期间不加载，也不写 scrollTop。手机/粗指针环境使用更长的 160 ms 链式间隔。
6. 顶部锚定 —— 在真正顶部（≤4 px）且手指抬起时，手机直接加载，插件保持旧顶行固定；不点击官方分页器（其 beginPaging() 落点可能落到下一个分页器）。桌面保留官方分页器路径。顶部下拉只加载一页，从不链式。
7. 内存纪律 —— 只保留标量状态、官方对象引用和 DOM 引用；不复制历史条目；预读和链式有界；不预加载全量历史。

安装

从检出目录：
git clone https://github.com/OranImp/dsh-fast-history.git
dsh plugin --profile web add /absolute/path/to/dsh-fast-history

在 DSH 智能体会话里，等价的工具调用是 plugin_manager action=install_bundle target="/absolute/path/to/dsh-fast-history"。

npm 发布之后，可以直接用包名：

dsh plugin --profile web add dsh-fast-history

安装完成后刷新 Web GUI（没跑 pnpm run dev:web 时，客户端 bundle 不走 HMR）。

手动安装：把 "dsh-fast-history": "link:/absolute/path/to/dsh-fast-history" 加进配置档依赖，把 "dsh-fast-history" 追加到 dsh.profile.bundles，执行 pnpm install，然后刷新。

设置

Settings → General → History loading

- 开启/关闭自动加载与预取。关掉后，官方的手动按钮照常可用。
- Lead：1 / 1.5 / 2 屏（默认 1.5）。数值越大，不可见的预加载空间越多，但读取的内容也越多。
- 预取页数：0 / 1 / 2（默认 1）。

设置存在浏览器 localStorage（dsh-fast-history.settings.v1）里，按浏览器各存各的，不进主机配置。

调试：

localStorage.setItem('dsh-fast-history.debug', '1'); // refresh
window.__DSH_FAST_HISTORY__.stats();
window.__DSH_FAST_HISTORY__.diagnostics();
window.__DSH_FAST_HISTORY__.setSettings({ prefetchPages: 0, preloadScreens: 2 });

行为与限制

- 只影响显示：不写提示词，不追加会话事件，不新增主机工具或配置；模型上下文保持不变。
- 快速滚动：插入页面和修正 scrollTop 都推迟到手势/惯性停下之后；快速甩到顶部时，可能在加载开始前短暂显示「Load earlier」。这是有意为之，避免卡顿。
- 锚点：手机/粗指针环境从不写 scrollTop；桌面端用顶部可见行修正超过 2 px 的稳定偏移。
- 未实现硬淘汰：公开的 SessionFace 没有裁剪 API；插件不改私有字段，也不碰 eventSource.replace。增长量受用户浏览范围 + 最多 2 页预取（默认 1）+ 最多 4 页链式加载限制。
- 单轮 / 超大会话：官方分页可能在第一页就加载整个日志；插件不改官方分页，初始窗口过重时跳过预取。
- 分页器本地化：匹配 加载更早 / 加载更多 / Load earlier / Load more；匹配不上就用结构回退，再不行直接调 loadOlder()。
- 与移动端共存：在 dsh-mobile 专用布局（.dshm-main / [data-dsh-mobile-frame]）下，插件绑定移动端会话。手机上早期路径是直接调 loadOlder() 并修正旧顶部行，分页器点击也走同一条带锚点的直接路径——dsh-mobile 合成的 button.click() 和真实点击都一样。桌面端保持官方分页器行为。
- 其他配置档：如果你的手机应用连的是另一个 DSH 配置档，那边也要装这个 bundle。

测试

从代码检出运行（npm tarball 不含测试）：

node --test test/.test.mjs
optional Chromium fixture; requires Playwright + a Chromium build
python3 test/browser_test.py
if the browser is not in Playwright's default location:
CHROMIUM_PATH=/path/to/chrome python3 test/browser_test.py

卸载

在配置档里停用或移除 bundle，或者在 shell 里执行 dsh plugin --profile web remove dsh-fast-history，然后刷新。在 DSH 智能体会话里，对应的工具调用是 plugin_manager action=remove_bundle target="dsh-fast-history"。

面向手机/小屏的 DSH Web 历史会话渐进加载插件：首屏最近消息 → 后台预读少量历史 → 上滑自动加载更早。

只影响显示。插件不会发送提示词、不会追加会话事件、不会改变 Host 为模型组装的上下文。

它解决什么

当前安装并已核对的 DSH 0.2.1-rc.2 / rc.3 官方行为（更新版本请重新验证）：

- 打开会话只加载尾部一页（至少 50 条消息 / 2 个 Turn，最多 500 条或历史耗尽）。
- 顶部有「加载更早 / Load earlier」按钮，每次手动追加一页。
- 没有滚动自动加载，没有后台预取，已加载窗口也不会被回收。

本插件在官方分页接口之上补齐：

1. 首屏：不改变官方尾部优先策略，不增加首屏请求。
2. 预取：首屏稳定且会话空闲时，后台直接调用 SessionFace.loadOlder() 预读 1 页（可配置 0/1/2），让第一次上滑通常无需等待。
3. 提前自动加载：用 wheel / touch / 键盘输入方向门控；在距离已加载头部还有 1.5 屏（可设 1/1.5/2 屏）时就开始加载，而不是等只能靠点「加载更早」继续。提前加载使用 loadOlder() 直接请求；手机/粗指针上，加载后由插件把加载前的顶部可见消息行按原位置钉住（不在手指/惯性期间写 scrollTop）。真正到顶（≤4px）时：桌面点官方 pager，手机走直接加载 + 锚定校正，避免官方 beginPaging() 把视口落到下一个 pager。
4. 连续补页：如果一页内容不足以填满提前量，插件会在页与页之间自动续加载，一次接近最多 4 页（含第一次），直到头部离开提前区或历史耗尽，让上滑过程尽量不出现按钮/加载态。
5. 内存：只保留标量状态、官方对象引用和 DOM 引用；不复制历史事件，不预读整条历史，预取和续加载都有页数/条数预算。

安装

git clone https://github.com/OranImp/dsh-fast-history.git
dsh plugin --profile web add /absolute/path/to/dsh-fast-history

如果是在 DSH 智能体会话里，等价的工具调用是： plugin_manager action=install_bundle target="/absolute/path/to/dsh-fast-history"。

npm 发布后，也可以直接用包名：

dsh plugin --profile web add dsh-fast-history

安装后刷新 Web GUI（当前没有 pnpm run dev:web watcher，Client 变更不会 HMR）。

手动安装（如果插件管理器不可用）：

1. 在配置档的 package.json dependencies 中增加 "dsh-fast-history": "link:/absolute/path/to/dsh-fast-history"。
2. 在 dsh.profile.bundles 末尾增加 "dsh-fast-history"。
3. 在配置档目录执行 pnpm install，刷新页面。

设置

Settings → General → 历史消息加载：

- 开关：启用/停用自动加载与预取；关闭后官方手动按钮仍可用。
- 提前量：1 / 1.5 / 2 屏，默认 1.5 屏；越大越无感，但会更早多读内容。
- 预读页数：0 / 1 / 2，默认 1。

设置保存在浏览器 localStorage（dsh-fast-history.settings.v1），按浏览器生效；不是 Host 配置。

调试：

localStorage.setItem('dsh-fast-history.debug', '1'); // 刷新后生效
window.__DSH_FAST_HISTORY__.stats(); // 计数、页数、延迟、锚定漂移
window.__DSH_FAST_HISTORY__.diagnostics(); // 当前条件判定
window.__DSH_FAST_HISTORY__.setSettings({ prefetchPages: 0, preloadScreens: 2 });

行为细节

- 首屏：沿用官方 open()；插件不会在首屏前预读。
- 预取：openState=open、hasMore、非 running、在尾部、页面可见、当前窗口 entries ≤ 400 时，延迟约 1.2s 调一次 loadOlder()。每页新增 entries > 400 或累计 > 600 即停止。首屏过重的单 Turn 会话直接跳过预取。
- 提前量：有效触发距离 = max(96px, scroller.clientHeight × preloadScreens)；默认 1.5 屏。接近已加载头部时即触发，不必看到 pager。
- 手势：只响应 wheel / touch / ArrowUp|PageUp|Home 输入；wheel 进入提前区即触发；触摸手势只记下待加载意图，手指抬起且滚动停稳后再触发，不会在手指移动中插入内容。同页脚本也可以合成这些事件，或直接点官方 pager，因此这不是安全边界，只是交互门控。
- 触摸屏/手机：touchstart 后，手指向下滑（看更早内容）且进入提前区时，只记下待加载意图；手指抬起且滚动停稳（约 140ms）后才加载，避免和浏览器的滚动锚定/惯性抢位置。只处理单指，双指缩放和嵌套滚动区（代码块等）不触发。手机浏览器按窄视口/粗指针/触摸能力识别，不要求 dsh-mobile 专用布局；dsh-mobile 布局会优先绑定。
- 与 dsh-mobile 共存：提前区/续加载用 loadOlder() 直连；真正到顶（≤4px）时桌面点官方 pager，手机用直接加载 + 自锚定。手机上的 pager 点击（包括 dsh-mobile 的 64px gate 合成 click 和真实手指点击）都改走同一条锚定直连；桌面仍保留官方 pager 行为。
- 快速滑动/惯性：用 scrollTop 速度和单事件位移识别快速滑动；高速阶段不发起加载、不写 scrollTop，链式补页也暂停，等惯性停稳约 140ms 后再加载。快速滑到顶部时可能短暂看到“加载更早”，停稳后才补页，这是为了不打断滚动。
- 程序化滚动：不会把 host 的 prepend 补偿当成用户手势自触发；新的独立手势之间有 400ms cooldown。
- 连续补页：一页落下后，如果 scrollTop 仍在提前区内且 hasMore，桌面 80ms / 手机/粗指针 160ms 后自动再加载一页；一次接近最多 4 页（含第一次），头部离开提前区、历史耗尽、失败或切会话即停止。触摸进行中或高速滚动时链式补页暂停，停稳后继续。
- 锚定：提前/手机顶部加载走直接 loadOlder()，加载前记录顶部可见行（data-chat-anchor-key + rect），加载后若行仍在则把它的位置钉回原处；手机也做这个校正，但只在手指/惯性停止后写 scrollTop，并加 120ms × 最多 6 次的延迟重试。真正在顶部（≤4px）且桌面时点击官方 pager，交给 Chat 自己的 beginPaging。顶部 direct 加载后如果仍在 0px（锚定失败），只加载一页、不链式补页，避免循环。
- 会话切换：按 [data-conversation-session] 识别；切换/视图切换/滚动容器复用都会 teardown 旧监听与定时器；旧异步结果按 generation 丢弃。
- 清理：插件停用/卸载时移除所有监听、Observer、定时器、订阅；调试全局变量删除。

已知限制

- 硬回收不存在：公开的 SessionFace 没有裁剪已加载窗口的方法，插件也不会改私有字段或 eventSource.replace。内存增长仍由“用户浏览 + 最多 2 页预取（默认 1） + 一次接近最多 4 页提前加载”驱动；不预读整条历史。
- 单 Turn/超大会话：官方分页要求至少 2 个 Turn 且 50 条消息，某些会话首屏就会整条加载；插件不修改官方分页，只避免额外预取。
- 多语言按钮：pager 文本匹配 zh/en；其他语言走结构 fallback（_older 容器），再失败走 loadOlder()。
- 移动端：手机浏览器和 dsh-mobile 专用布局都可用；手机/小屏按窄视口、粗指针或触摸能力识别，不要求 .dshm-main。提前区和真正到顶都用 loadOlder() 直连，并做旧顶部行校正；桌面顶部才点官方 pager。若你的手机 App 连接的是另一个 DSH profile，需要把本插件也安装到那个 profile。
- 上下文不变：加载历史只影响客户端事件窗口；模型上下文由 Host 从持久日志组装。

测试

从源码 checkout 运行（npm tarball 不含 test/）：

node --test test/.test.mjs
可选：真实 Chromium fixture（需要 Playwright + Chromium）
python3 test/browser_test.py
如果 Playwright 浏览器不在默认缓存目录，设置 CHROMIUM_PATH：
CHROMIUM_PATH=/path/to/chrome python3 test/browser_test.py

浏览器 fixture 覆盖：预取 1 页、pager 仍在视口外时提前加载、提前区内自动续加载一页、官方 pager 手动仍可用、清理后不再自动加载、调试全局删除、dsh-mobile overlay 的手机上下文、无 overlay 的普通手机浏览器、快速滑动停稳前后不提前加载、body 焦点键盘 PageUp、resync 后重新预取、同会话 aria-hidden 重绑不重复预取、顶部无锚点时只点一次 pager 不续链、手机顶部无浏览器锚定时旧行仍保持、手机合成/真实 pager click 都改走锚定直连、无页面错误。

卸载

dsh plugin --profile web remove dsh-fast-history

或在 DSH Agent 会话里用 plugin_manager action=remove_bundle target="dsh-fast-history"。

刷新页面。浏览器中的设置键可手动清理：

localStorage.removeItem('dsh-fast-history.settings.v1');
localStorage.removeItem('dsh-fast-history.debug');