linanatoly / dsh-chat-history-locator

Chat History Locator

一个为 DeepSeek Harness (DSH) Web 界面设计的动态 Cordis 插件：在聊天消息区左缘常驻一条竖向历史定位条，帮你快速回到聊天历史中的任意一条你发过的消息。

A dynamic Cordis plugin for the DeepSeek Harness (DSH) web UI: a persistent vertical marker rail on the left edge of the chat area, letting you jump back to any message you sent.

功能特性 / Features

• 竖向定位条：常驻在消息区左缘（不遮挡消息，利用消息列自带的内边距），每个你发过的消息（user / steering 类型）对应一个圆点。
• 最多 10 个可见标记：标记超过 10 个时以滑动窗口展示；在定位条上滚动滚轮即可浏览其余标记（每 60px 滚动距离换一格，触控板平滑累积）。
• 悬浮预览：鼠标悬浮圆点 → 弹出气泡显示该消息的内容（截断 140 字）和发送时间，同时在聊天里用虚线描出对应消息；悬浮的圆点变为固定大小的蓝色空心圆（scale(1.5)，任意位置大小一致）。
• 点击跳转：点击圆点 → 聊天滚到那条消息并闪光高亮，定位窗口自动把该标记移到中间。
• 中间大、两端小：可见圆点按余弦曲线缩放（中心 1.0 → 两端 0.35），滑动换格时尺寸同步平滑过渡。
• 端点提示：全部标记都在显示（无法滑动）时上下两端同时亮起蓝色端点条；窗口模式下到达顶部/底部时，对应端点（圆弧顶点处）亮蓝条。
• 回到最新：滚离底部时条顶出现「最新 ↓」，点击回到最新消息并显示末尾标记窗口。
• 健壮性：测量全部同步执行，不依赖 requestAnimationFrame（空闲/后台页面会冻结 rAF）；通过 ResizeObserver / MutationObserver / 原生 wheel（非 passive）跟踪变化；切换会话、加载更早、输入框变高都会自动重定位。

安装 / Install

这是一个动态 Cordis 插件（只有 Client 半身，无 Host 半身），只能在 DSH 会话内通过 cordis_define / cordis_run 工具加载（闭包符号 React / styles / host 仅在动态插件环境中存在）。

This is a dynamic Cordis plugin (client half only, no host half). It can only be loaded inside a DSH session through the cordis_define / cordis_run tools (the closure symbols React / styles / host exist only in the dynamic-plugin environment).

1. 在 DSH 会话中让 Agent 执行：
   cordis_define:
     plugin: { kind: "new", idPrefix: "chloc" }   （或任意 3–6 位小写字母前缀）
     name:   "Chat History Locator"
     purpose: "聊天历史定位条"
     code.client = plugin/client.js 的全部内容
2. cordis_run 激活返回的 pluginId / packageId，并在运行卡片上批准。

或者直接把本仓库 plugin/client.js 的内容贴给 Agent，告诉它「用 cordis_define 创建这个动态插件并运行」。

工作原理 / How it works

关注点	方案
数据来源	Session 标准 kit 的 useSession：snapshot.nodes（legacy 兼容层）+ chat.nodes（把消息 seq 映射到 DOM 行的 data-chat-anchor-key）
滚动容器	产品自带的 [data-conversation-scroll]，跳转公式与官方 chatScroll 记忆逻辑同源，不与自动跟随底部冲突
测量时机	useLayoutEffect 同步测量 + ResizeObserver（滚动区/输入区/消息流）+ MutationObserver（流元素挂载/卸载）+ scroll/resize 监听
滚轮浏览	原生 wheel 监听（passive: false + preventDefault），增量累积 60px/格
样式	styles.insert() 注入，CSS 变量驱动缩放（--dsh-loc-scale），生命周期随插件自动清理

文件 / Files

• plugin/client.js — 插件源码（code.client 函数体），含完整注释
• CHANGELOG.md — 从 v1 到定稿的演进记录
• LICENSE — MIT

许可 / License

MIT © 2025

---

Built and polished through 11 iterations inside a DeepSeek Harness session — from a plain marker strip to a windowed, wheel-browsable, animated locator rail.