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 保持兼容，移除旧条目时保留持久化设置。详见迁移步骤。
它能帮你找到什么
| 导航对象 | 显示与行为 |
|---|---|
| 用户输入 | 独立入口，保留对话起点 |
| AI 过程输出 | 文本按语义分段；同轮连续过程可折叠为一枚键 |
| 最终结果 | 与过程输出分开标识 |
| AI 提问 / 用户回答 | 展示 ask_user_question 的问题、回答和状态 |
| 更早的历史轮次 | 未加载时显示真实大纲，点击交由 DSH 原生导航加载 |
普通工具日志、编辑、读取和推理不生成独立琴键；结构化问答是明确的例外。未加载轮次不会被猜测成虚构的细粒度段落。
合入主分支后自动运行完整验证；稳定版本号提升且验证通过后，自动发布 npm、核验下载包并创建 GitHub Release。普通提交只验证。发布方式见 发布说明。
独立演进的核心能力
- 一条完整历史轨道：合并轮次大纲和已加载语义段；接管成功后只显示 Piano，条件不满足时恢复原生导航。
- 按需展开过程：首次点击折叠键展开成员并定位到第一条；自动展开可揭示的原生过程区或问答卡片。轨道滚轮、正文滚动和流式更新保留手动展开。
- 连续指针波形：同键内移动也连续跟随；动画帧只更新可见键与必要预览，鼠标停止后没有常驻循环。
- 固定显示窗口：默认 20 枚键，保持稳定间距；轨道滚轮和键盘可以前后浏览全部可用入口。
- 完整日常交互：纯文本预览、阅读高亮、稳定节点复用、明暗主题、键盘操作与减少动画。
- 三语持久化设置：简体中文、English、繁體中文；粗细、间距和窗口容量即时调整。
常用操作
| 操作 | 结果 |
|---|---|
| 沿轨道移动鼠标 | 连续波形跟随，最近的键显示预览 |
点击普通键 / Enter / Space |
定位或交由原生导航加载目标 |
| 首次激活过程折叠键 | 展开该组并定位第一条，其他已展开组先收起 |
| 点击同组过程成员 | 连续定位，保持该组展开；其他类型键收回 |
| 轨道滚轮 | 前后浏览窗口，不滚动正文，并保留手动展开 |
↑ / ↓、PageUp / PageDown |
移动选择，必要时调整窗口 |
Home / End |
选择会话导航列表首尾 |
Escape |
关闭预览、收回展开并取消当前导航意图 |
默认键高 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
| 入口 | 内容 |
|---|---|
| 贡献指南 | 环境、目录职责、测试与提交要求 |
| 架构 | 读模型、原生所有权、调度与生命周期 |
| 语义规则 | 分段、问答、最终结果与折叠 |
| 发布指南 | 打包、认证、tarball 上传与核验 |
| 变更记录 | 独立维护版本的变化 |
实现位于 src/，回归与夹具位于 scripts/，跟踪构建产物位于 lib/。当前文档从 docs/README.md 进入，过往阶段方案和旧截图归入 docs/archive/。
来源与许可
基于 hjj345/dsh-sm-context-piano 演进，保留原有 MIT 版权；当前功能、适配与发布由本仓库维护。详见 LICENSE 与 NOTICE。
