amazing-fish/dsh-piano-nav

DSH Piano Navigator

把长 Agent 会话变成一条可预览、可定位的语义导航轨道。

English · 使用指南 · 文档 · 反馈

面向 DeepSeek Harness Web GUI，由 amazing-fish 独立维护。项目已发展为包含完整历史导航、语义问答、过程折叠和连续指针交互的导航器。来源与版权记录见 NOTICE。

效果预览

循环展示 蓝色用户输入 → 灰色过程组 → 展开的过程 step → 琥珀色 AI 提问 → 绿色用户回答 → 紫色双线最终结果 → 定位后回折 → 深色过程键。预览来自实际插件与原生组件，使用合成会话；各状态停留片刻以便观察。深色主题的普通过程键为白色或近白。

连续鼠标跟随：查看上一轮修复前后对比

同一轨迹依次慢速、快速、立即反向；左侧为修复前，右侧为当前效果。实际插件浏览器回放使用合成会话，琴键放大 4 倍。图中的 5/120 和 120/120 是微移期间的宽度变化次数，不是 FPS。

安装

需要 DSH 的 web profile，以及 Node.js ^22.19.0 || >=24.0.0。

dsh plugin --profile web add dsh-piano-nav

刷新 Web GUI，在设置中找到 琴键导航 / Piano Navigator。包名为 dsh-piano-nav；npm 上已有的 dsh-piano 是另一款音乐插件。

从旧作用域包或本地链接迁移时，先移除旧插件的加载条目，再添加新包，避免重复装载。设置 entry id 保持兼容，移除旧条目时保留持久化设置。详见迁移步骤。

它能帮你找到什么

普通工具日志、编辑、读取和推理不生成独立琴键；结构化问答是明确的例外。未加载轮次不会被猜测成虚构的细粒度段落。

合入主分支后自动运行完整验证；稳定版本号提升且验证通过后，自动发布 npm、核验下载包并创建 GitHub Release。普通提交只验证。发布方式见 发布说明。

独立演进的核心能力

• 一条完整历史轨道：合并轮次大纲和已加载语义段；接管成功后只显示 Piano，条件不满足时恢复原生导航。
• 按需展开过程：首次点击折叠键展开成员并定位到第一条；自动展开可揭示的原生过程区或问答卡片。轨道滚轮、正文滚动和流式更新保留手动展开。
• 连续指针波形：同键内移动也连续跟随；动画帧只更新可见键与必要预览，鼠标停止后没有常驻循环。
• 固定显示窗口：默认 20 枚键，保持稳定间距；轨道滚轮和键盘可以前后浏览全部可用入口。
• 完整日常交互：纯文本预览、阅读高亮、稳定节点复用、明暗主题、键盘操作与减少动画。
• 三语持久化设置：简体中文、English、繁體中文；粗细、间距和窗口容量即时调整。

常用操作

默认键高 2px、中心间距 12px、最多 20 枚可见键。1.3.1 设置页支持六类语义配色、绑定图例和实时布局预览；修改后保存并同步实际琴键，可恢复主题默认色。设置范围、折叠规则和异常行为见使用指南。

查看当前版本设置页

实际 1.3.1 组件的简体中文截图，使用演示设置数据。图片来源与版本见素材说明。

兼容性与数据边界

当前开发依赖固定到 DSH 0.2.0-rc.2；类型与集成测试、固定官方源码的原生组件浏览器回归分别验证不同层面的兼容性。兼容说明列明适配方式和验证范围。

导航通过受校验的 DOM 桥接复用原生分页与滚动状态，尚不是官方稳定的导航替换 API。容器过窄、没有目标或契约变化时恢复原生界面。同一行的多个语义段可能落在同一行起点。

Piano 只读取导航信息、显示纯文本预览并保存自身设置；不改写消息、不注入系统提示、不提交问答答案。历史加载请求由 DSH 执行。

开发与文档

pnpm install --frozen-lockfile
pnpm verify
pnpm test:package

实现位于 src/，回归与夹具位于 scripts/，跟踪构建产物位于 lib/。当前文档从 docs/README.md 进入，过往阶段方案和旧截图归入 docs/archive/。

来源与许可

基于 hjj345/dsh-sm-context-piano 演进，保留原有 MIT 版权；当前功能、适配与发布由本仓库维护。详见 LICENSE 与 NOTICE。