dsh-music-panel 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.2.0
+
+### 功能
+
+- 记忆播放：启动 / 刷新后恢复上次的队列、当前曲目与播放位置（默认暂停，点 ▶ 继续）；设置里可开「恢复后自动播放」与「每首歌记住播放位置」
+- 播放次数按 Last.fm / MusicBee 规则记录：曲目 > 30 秒，且播放到一半或 4 分钟（先到为准）才计一次，不再每次切歌就 +1
+- 有效播放时长：只累计播放中自然前进的时间，拖动进度条不计，单次不足 30 秒的片段不计
+- 统计页：主面板新增「统计」tab，支持最近一周 / 最近一月 / 全部时间，按时长 / 次数 / 最近排序，显示累计时长、播放次数、最近播放与汇总
+- 新增接口：`GET/POST /music/state`、`POST /music/playback`、`GET/POST /music/position`、`GET /music/stats`
+- 设置面板新增「播放」标签页
+
+### 数据
+
+- `stats.json` 扩展 `playSeconds`、`lastPlayedAt`、`lastPositionSec` 与最近 31 天的每日分桶；旧文件自动兼容
+- 新增 `<DSH_HOME>/music/playback.json` 保存上次播放状态
+
 ## 0.1.0
 
 首个公开版本。

package/README.md

@@ -23,8 +23,10 @@ DeepSeek Harness 的本地音乐插件：左侧栏一个音符入口，点开是
 - **歌曲列表**：封面缩略图、标题、歌手（带 CD 徽标）、专辑、时长、采样率；当前曲高亮。
 - **播放控制**：列表循环 / 单曲循环 / 不循环，随机播放，上一首、下一首、进度拖动、音量与静音。
 - **播放队列**：底部「队列」按钮展开当前队列，点击任意条目跳转；「更多」里显示格式 / 码率 / 采样率，可复制文件路径。
+- **记忆播放**：启动 / 刷新后恢复上次的队列、当前曲目与播放位置（默认停在暂停，点 ▶ 继续）；设置里可选「恢复后自动播放」和「每首歌记住播放位置」。
+- **统计**：主面板「统计」页按最近一周 / 最近一月 / 全部时间查看每首歌的累计播放时长、播放次数与最近播放，可按时长 / 次数 / 最近排序。播放次数按 Last.fm 规则（曲目 > 30 秒且播放到一半或 4 分钟）记录，播放时长只累计真正在播放的时间。
 - **列表操作**：搜索、排序（标题 / 文件名 / 专辑 / 艺术家 / 大小 / 年份 / 文件夹 / 播放次数 / 时长 / 修改时间 / 添加时间，点击同项切换升降序）、多选后「播放选中」或加入播放列表、清空列表。
-- **设置面板**：主面板右上角齿轮打开，含「外观 / 歌词 / 音乐库」三个标签页：外观调整迷你浮窗与圆形封面显示，歌词调整来源顺序、对齐、字号、翻译与状态栏歌词，音乐库管理音乐文件夹与子文件夹深度（保存后主面板自动重新扫描）。
+- **设置面板**：主面板右上角齿轮打开，含「外观 / 歌词 / 音乐库 / 播放」四个标签页：外观调整迷你浮窗与圆形封面显示，歌词调整来源顺序、对齐、字号、翻译与状态栏歌词，音乐库管理音乐文件夹与子文件夹深度（保存后主面板自动重新扫描），播放控制启动恢复、自动播放与每首歌断点。
 - **外观设置**：迷你浮窗（右下角可拖动、记忆位置）、播放页圆形封面 / 黑胶底盘 / 封面旋转。
 - **歌词设置**：歌词来源顺序（内嵌 / LRC，可调）、对齐方式、字体大小与粗细、模糊非当前歌词、翻译开关与翻译字号缩放、状态栏歌词（输入框内或输入框上方显示当前唱词）。
 - **播放列表**：顶栏「全部歌曲」与每个歌单各占一个 tab，**页面结构完全一致**（搜索、排序、多选、播放全部、循环/随机、队列）；「全部歌曲」是不可编辑集合，歌单可点标题改名、删除、逐首移除。右侧 `+` 新建歌单（自动命名，重名递增）并立即选中。歌单存于 `<DSH_HOME>/music/playlists.json`。
@@ -67,6 +69,12 @@ plugin_manager install_bundle D:/SystemFiles/Documents/Project/DSH/plugins/dsh-m
 | PATCH | `/music/playlists/:id` | 重命名 / 加曲 / 删曲：`{ name?, add?: string[], remove?: string[] }` |
 | DELETE | `/music/playlists/:id` | 删除播放列表 |
 | POST | `/music/play` | 记一次播放，body `{ path }` |
+| GET | `/music/state` | 上次播放状态（队列 / 索引 / 位置 / 循环 / 顺序） |
+| POST | `/music/state` | 保存上次播放状态，body `{ queue, index, positionSec, durationSec, loop, order }` |
+| POST | `/music/playback` | 累加有效播放时长，body `{ path, seconds }` |
+| GET | `/music/position?path=…` | 该曲上次停止位置（每首歌断点） |
+| POST | `/music/position` | 保存某曲停止位置，body `{ path, seconds }` |
+| GET | `/music/stats?range=week\|month\|all` | 按范围聚合的播放次数 / 时长 / 最近播放 |
 | GET | `/music/cover?path=…` | 内嵌封面；无封面返回 404 |
 
 `stream` / `cover` 的 `path` 会 `realpath` 后重新校验是否位于已配置的根目录内，越界一律 404。
@@ -87,6 +95,17 @@ patch 的 `config` 是首次启动的种子：
 
 用户在设置面板的音乐库标签页保存后，以 `<DSH_HOME>/music/settings.json` 为准（`extensions: []` 表示使用全部支持的格式）。播放次数与首次入库时间存在 `<DSH_HOME>/music/stats.json`。
 
+## 播放状态与统计
+
+两个文件都在 `<DSH_HOME>/music/`：
+
+- `playback.json`：上次播放的队列（最多 500 条）、当前索引、位置、循环 / 顺序，用于启动恢复。
+- `stats.json`：每首歌的 `addedAt`、`plays`（Last.fm 规则计数）、`playSeconds`（有效播放秒数）、`lastPlayedAt`、`lastPositionSec`（每首歌断点，仅在设置里开启时写入），以及最近 31 天的每日分桶 `days`（供统计页的「最近一周 / 最近一月」使用）。
+
+写入时机：播放中每 5 秒保存一次状态；切歌、暂停、页面隐藏 / 关闭时立即 flush。播放时长只累计播放中自然前进的时间（拖动进度条不计），单次不足 30 秒的片段不进入统计（对齐网易云「有效播放」）。
+
+多标签页同时播放同一首歌时会各自计时，统计可能重复；这一期不做标签页互斥。
+
 ## 播放宿主与后台播放
 
 - `<audio>` 元素挂在宿主的 `shell.overlay`（常驻浮层）里，主面板切走、会话切换都不会卸载它，所以播放不中断；播放状态由 `client.js` 里的引擎单例（`window.__dshMusicPlayer`）持有，模块被 HMR 重新执行也复用同一实例。
@@ -96,7 +115,7 @@ patch 的 `config` 是首次启动的种子：
 
 ## 已知限制
 
-- 收藏、播放历史尚未实现（播放列表已支持）。
+- 收藏尚未实现（播放列表与统计已支持）。
 - m4a 的文本标签可读，内嵌封面暂不解析（封面支持 mp3 / flac）。
 - 扫描缓存 30 秒；文件变化后点「重新扫描」强制刷新。
 - 播放依赖浏览器的 `<audio>`：DSH 的 Web GUI 在 `http://127.0.0.1` 下可用；远程访问（非回环）会返回 403。

package/client.js

@@ -45,6 +45,11 @@ window.__ModuleLoader__.load({
       translationScale: 80,
       composerLyrics: false,
       composerLyricPlace: 'input-left',
+      // Resume behaviour follows mainstream desktop players: restore the queue
+      // and position on start, but stay paused until the user asks to play.
+      resumeOnStart: true,
+      autoResume: false,
+      rememberPerTrack: false,
     }
 
     // ── locale ────────────────────────────────────────────────────────────
@@ -122,7 +127,23 @@ window.__ModuleLoader__.load({
         'page.lyricWeight': '字体粗细',
         'page.lyricBlur': '模糊非当前歌词',
         'page.translationScale': '翻译字体缩放',
+        'stats.rangeWeek': '最近一周',
+        'stats.rangeMonth': '最近一月',
+        'stats.rangeAll': '全部时间',
+        'stats.sortTime': '按时长',
+        'stats.sortPlays': '按次数',
+        'stats.sortRecent': '按最近',
+        'stats.totalTime': '累计播放时长',
+        'stats.totalPlays': '总播放次数',
+        'stats.trackCount': '有记录曲目',
+        'stats.plays': '{n} 次',
+        'stats.empty': '还没有播放记录',
+        'stats.loading': '加载中…',
+        'stats.loadFailed': '统计加载失败',
+        'stats.retry': '重试',
+        'stats.unavailable': '文件已不可用',
         'page.tabSongs': '全部歌曲',
+        'page.tabStats': '统计',
         'page.tabPlaylists': '播放列表',
         'page.newPlaylist': '新建播放列表',
         'page.playlistName': '播放列表名称',
@@ -160,6 +181,11 @@ window.__ModuleLoader__.load({
         'settings.tabAppearance': '外观',
         'settings.tabLyrics': '歌词',
         'settings.tabLibrary': '音乐库',
+        'settings.tabPlayback': '播放',
+        'settings.resumeOnStart': '启动时恢复上次播放',
+        'settings.autoResume': '恢复后自动播放',
+        'settings.rememberPerTrack': '每首歌记住播放位置',
+        'settings.playbackHint': '播放次数按 Last.fm 规则记录：曲目超过 30 秒，且播放到一半或 4 分钟（先到为准）才算一次；播放时长只累计真正在播放的时间。',
         'settings.libraryHint': '音乐文件夹（自动保存）',
         'settings.removeConfirm': '确定移除这个音乐文件夹？不会删除文件。',
         'settings.up': '↑ 上级',
@@ -259,7 +285,23 @@ window.__ModuleLoader__.load({
         'page.lyricWeight': 'Font weight',
         'page.lyricBlur': 'Blur inactive lines',
         'page.translationScale': 'Translation scale',
+        'stats.rangeWeek': 'Last week',
+        'stats.rangeMonth': 'Last month',
+        'stats.rangeAll': 'All time',
+        'stats.sortTime': 'By time',
+        'stats.sortPlays': 'By plays',
+        'stats.sortRecent': 'By recent',
+        'stats.totalTime': 'Listening time',
+        'stats.totalPlays': 'Total plays',
+        'stats.trackCount': 'Tracks',
+        'stats.plays': '{n} plays',
+        'stats.empty': 'No listening history yet',
+        'stats.loading': 'Loading…',
+        'stats.loadFailed': 'Failed to load statistics',
+        'stats.retry': 'Retry',
+        'stats.unavailable': 'File unavailable',
         'page.tabSongs': 'All songs',
+        'page.tabStats': 'Stats',
         'page.tabPlaylists': 'Playlists',
         'page.newPlaylist': 'New playlist',
         'page.playlistName': 'Playlist name',
@@ -297,6 +339,11 @@ window.__ModuleLoader__.load({
         'settings.tabAppearance': 'Appearance',
         'settings.tabLyrics': 'Lyrics',
         'settings.tabLibrary': 'Library',
+        'settings.tabPlayback': 'Playback',
+        'settings.resumeOnStart': 'Resume last playback on start',
+        'settings.autoResume': 'Start playing after restore',
+        'settings.rememberPerTrack': 'Remember each track position',
+        'settings.playbackHint': 'Play counts follow the Last.fm rule: a track longer than 30 seconds counts once after half its duration or 4 minutes, whichever comes first. Listening time only counts time actually played.',
         'settings.libraryHint': 'Music folders (auto-saved)',
         'settings.removeConfirm': 'Remove this music folder? Files are not deleted.',
         'settings.up': '↑ Up',
@@ -388,6 +435,17 @@ window.__ModuleLoader__.load({
       return String(khz).replace(/\.0$/, '') + ' kHz'
     }
 
+    /**
+     * Last.fm / MusicBee play threshold: half the track or four minutes,
+     * whichever comes first. Tracks of 30 seconds or less never count.
+     */
+    function playThresholdOf(durationSec) {
+      var duration = Number(durationSec)
+      if (!isFinite(duration) || duration <= 0) return 240
+      if (duration <= 30) return duration + 0.5
+      return Math.min(duration / 2, 240)
+    }
+
     /** Clamp a stored preference to a sane numeric range. */
     function clampPref(value, min, max, fallback) {
       var number = Number(value)
@@ -980,6 +1038,184 @@ window.__ModuleLoader__.load({
         buffered: 0,
       }
 
+      // ── resume + listening statistics ───────────────────────────────────
+      // Counting follows the Last.fm / MusicBee rule (half the track or four
+      // minutes, whichever comes first); resume follows the NetEase / Spotify
+      // pattern (restore the queue and position, then stay paused). The clock
+      // only counts time that naturally advanced while playing, so dragging
+      // the seek bar never inflates the statistics.
+      var session = { path: '', seconds: 0, pending: 0, lastTime: 0, counted: false }
+      var lastStateSave = 0
+      var restoreAttempted = false
+      var pendingResumeSeconds = null
+
+      function resetSession(item) {
+        session = {
+          path: item ? item.path : '',
+          seconds: 0,
+          pending: 0,
+          lastTime: 0,
+          counted: false,
+        }
+      }
+
+      function durationOf(item) {
+        if (audio !== null && isFinite(audio.duration) && audio.duration > 0) return audio.duration
+        return item && item.durationSec > 0 ? item.durationSec : 0
+      }
+
+      function recordStatsPlay(item) {
+        try {
+          postJson(API + 'play', { path: item.path }).catch(function () {})
+        } catch (error) {
+          // Statistics never block playback.
+        }
+      }
+
+      /** Flush the seconds that have not been reported yet (>= 30s only). */
+      function flushListening(force) {
+        if (session.path === '' || session.pending <= 0) return
+        if (session.seconds < 30) {
+          if (force) session.pending = 0
+          return
+        }
+        var seconds = session.pending
+        session.pending = 0
+        try {
+          postJson(API + 'playback', { path: session.path, seconds: seconds }).catch(function () {})
+        } catch (error) {
+          // Best effort.
+        }
+      }
+
+      function flushSessionPosition() {
+        if (session.path === '' || readPrefs().rememberPerTrack !== true) return
+        var item = currentItem()
+        if (item === null || item.path !== session.path) return
+        var seconds = state.currentTime
+        if (!(seconds > 0)) return
+        try {
+          postJson(API + 'position', { path: session.path, seconds: seconds }).catch(function () {})
+        } catch (error) {
+          // Best effort.
+        }
+      }
+
+      function savePlaybackState() {
+        var item = currentItem()
+        if (item === null) return
+        var duration = state.duration > 0 ? state.duration : item.durationSec || 0
+        try {
+          postJson(API + 'state', {
+            queue: state.queue.map(function (track) {
+              return track.path
+            }),
+            index: state.index,
+            positionSec: state.currentTime,
+            durationSec: duration,
+            loop: state.loop,
+            order: state.order,
+          }).catch(function () {})
+        } catch (error) {
+          // Best effort.
+        }
+      }
+
+      function trackListening() {
+        if (audio === null) return
+        var item = currentItem()
+        if (item === null) return
+        if (session.path !== item.path) resetSession(item)
+
+        var current = audio.currentTime
+        if (state.playing && !audio.paused) {
+          var delta = current - session.lastTime
+          // A seek produces a large or negative jump; only natural playback
+          // advances count toward listening time.
+          if (delta > 0 && delta <= 3) {
+            session.seconds += delta
+            session.pending += delta
+          }
+        }
+        session.lastTime = current
+
+        var duration = durationOf(item)
+        var threshold = playThresholdOf(duration)
+        if (!session.counted && duration > 30 && session.seconds >= threshold) {
+          session.counted = true
+          recordStatsPlay(item)
+        }
+
+        if (session.seconds >= 30 && session.pending >= 10) flushListening(false)
+
+        var now = Date.now()
+        if (now - lastStateSave >= 5000) {
+          lastStateSave = now
+          savePlaybackState()
+        }
+      }
+
+      function restorePlayback(saved, tracks) {
+        if (!saved || !Array.isArray(saved.queue) || saved.queue.length === 0) return false
+        if (!Array.isArray(tracks) || tracks.length === 0) return false
+        var byPath = {}
+        tracks.forEach(function (track) {
+          byPath[track.path] = track
+        })
+        var queue = []
+        saved.queue.forEach(function (path) {
+          if (byPath[path] !== undefined) queue.push(byPath[path])
+        })
+        if (queue.length === 0) return false
+        var wantedPath = saved.queue[saved.index]
+        var index = 0
+        for (var i = 0; i < queue.length; i += 1) {
+          if (typeof wantedPath === 'string' && queue[i].path === wantedPath) {
+            index = i
+            break
+          }
+        }
+        state = Object.assign({}, state, {
+          queue: queue,
+          index: index,
+          loop: saved.loop === 'one' || saved.loop === 'none' ? saved.loop : 'all',
+          order: saved.order === 'random' ? 'random' : 'list',
+          currentTime: saved.positionSec > 0 ? saved.positionSec : 0,
+          duration: saved.durationSec > 0 ? saved.durationSec : 0,
+          playing: false,
+        })
+        randomOrder = randomOrderOf(queue.length)
+        emit()
+        syncMediaSession()
+        resetSession(queue[index])
+        pendingResumeSeconds = saved.positionSec > 0 ? saved.positionSec : null
+        // Paused by default (NetEase/Spotify behaviour); the setting can ask
+        // for playback to start right after restore.
+        load(index, readPrefs().autoResume === true)
+        return true
+      }
+
+      function tryRestore() {
+        if (restoreAttempted) return
+        restoreAttempted = true
+        if (readPrefs().resumeOnStart !== true) return
+        Promise.all([getJson(API + 'state'), getJson(API + 'library')])
+          .then(function (results) {
+            var saved = results[0] !== null && results[0].state !== undefined ? results[0].state : null
+            var tracks = results[1] !== null && Array.isArray(results[1].tracks) ? results[1].tracks : []
+            restorePlayback(saved, tracks)
+          })
+          .catch(function () {
+            // Resume is best effort.
+          })
+      }
+
+      function flushOnHide() {
+        flushListening(true)
+        flushSessionPosition()
+        savePlaybackState()
+      }
+
       function emit() {
         listeners.forEach(function (fn) {
           fn()
@@ -1059,6 +1295,7 @@ window.__ModuleLoader__.load({
         if (audio === null) return
         state = Object.assign({}, state, { currentTime: audio.currentTime })
         emitTime()
+        trackListening()
       }
 
       function onDuration() {
@@ -1089,6 +1326,9 @@ window.__ModuleLoader__.load({
       }
 
       function onPause() {
+        flushListening(true)
+        flushSessionPosition()
+        savePlaybackState()
         if (state.playing) {
           patch({ playing: false })
           syncMediaSession()
@@ -1096,8 +1336,11 @@ window.__ModuleLoader__.load({
       }
 
       function onEnded() {
+        flushListening(true)
+        flushSessionPosition()
         if (state.queue.length === 0) return
         if (state.loop === 'one') {
+          resetSession(currentItem())
           if (audio) {
             audio.currentTime = 0
             audio.play().catch(function () {})
@@ -1186,23 +1429,17 @@ window.__ModuleLoader__.load({
       function load(at, autoplay) {
         var item = state.queue[at]
         if (!item) return
+        // Close the previous listening session before switching tracks.
+        flushListening(true)
+        flushSessionPosition()
         var token = (loadToken += 1)
         state = Object.assign({}, state, { index: at, currentTime: 0, duration: 0, buffered: 0 })
         emit()
         syncMediaSession()
         pendingAutoplay = autoplay === true
-        // One load == one play; recorded so "play count" can be a sort key.
-        try {
-          window
-            .fetch(API + 'play', {
-              method: 'POST',
-              headers: { 'content-type': 'application/json' },
-              body: JSON.stringify({ path: item.path }),
-            })
-            .catch(function () {})
-        } catch (error) {
-          // Statistics never block playback.
-        }
+        // A new session starts here. The play count is recorded later, and
+        // only when the Last.fm / MusicBee threshold is reached.
+        resetSession(item)
         if (audio === null) return
 
         cancelPendingFetch()
@@ -1228,6 +1465,19 @@ window.__ModuleLoader__.load({
             objectUrl = URL.createObjectURL(blob)
             audio.src = objectUrl
             audio.load()
+            if (pendingResumeSeconds !== null) {
+              var resumeAt = pendingResumeSeconds
+              pendingResumeSeconds = null
+              api.seek(resumeAt)
+            } else if (readPrefs().rememberPerTrack === true) {
+              getJson(API + 'position?path=' + encodeURIComponent(item.path))
+                .then(function (body) {
+                  if (token !== loadToken) return
+                  var seconds = Number(body.lastPositionSec)
+                  if (isFinite(seconds) && seconds > 1) api.seek(seconds)
+                })
+                .catch(function () {})
+            }
             if (pendingAutoplay) {
               pendingAutoplay = false
               audio.play().catch(function () {
@@ -1266,6 +1516,10 @@ window.__ModuleLoader__.load({
         getTime: function () {
           return { currentTime: state.currentTime, duration: state.duration, buffered: state.buffered }
         },
+        /** Restore the last queue/position once (called by the resident host). */
+        tryRestore: tryRestore,
+        /** Flush statistics + resume state when the page is hidden/closed. */
+        flushOnHide: flushOnHide,
         /** Hand the resident <audio> element to the engine (null detaches). */
         attachAudio: function (el) {
           if (audio === el) return
@@ -1455,6 +1709,7 @@ window.__ModuleLoader__.load({
       var ref = useRef(null)
       useEffect(function () {
         player.attachAudio(ref.current)
+        player.tryRestore()
         return function () {
           player.attachAudio(null)
         }
@@ -2220,6 +2475,238 @@ window.__ModuleLoader__.load({
 
     // ── main panel ───────────────────────────────────────────────────────
 
+    // ── listening statistics (NetEase-style listening ranking) ────────────
+
+    function basenameOf(path) {
+      var parts = String(path || '').split(/[\\/]/)
+      return parts.length > 0 ? parts[parts.length - 1] : String(path || '')
+    }
+
+    function fmtListenTime(seconds) {
+      var total = Math.round(Number(seconds) || 0)
+      if (total <= 0) return '—'
+      var hours = Math.floor(total / 3600)
+      var minutes = Math.floor((total % 3600) / 60)
+      if (hours > 0) return hours + ' 小时 ' + minutes + ' 分'
+      if (minutes > 0) return minutes + ' 分'
+      return total + ' 秒'
+    }
+
+    function fmtRecent(ts) {
+      var value = Number(ts)
+      if (!isFinite(value) || value <= 0) return '—'
+      var date = new Date(value)
+      var now = new Date()
+      var startOfDay = function (day) {
+        return new Date(day.getFullYear(), day.getMonth(), day.getDate()).getTime()
+      }
+      var days = Math.round((startOfDay(now) - startOfDay(date)) / 86_400_000)
+      if (days <= 0) return '今天'
+      if (days === 1) return '昨天'
+      if (days < 7) return days + ' 天前'
+      return date.getFullYear() + '-' + pad2(date.getMonth() + 1) + '-' + pad2(date.getDate())
+    }
+
+    /**
+     * Listening ranking: last week / month / all time, sorted by time, plays or
+     * recency. Mirrors the NetEase "listening ranking" page, limited to what
+     * the local library can know without a server.
+     */
+    function StatsView(props) {
+      var t = props.t
+      var [range, setRange] = useState('week')
+      var [sortBy, setSortBy] = useState('seconds')
+      var [loading, setLoading] = useState(true)
+      var [error, setError] = useState(null)
+      var [rows, setRows] = useState([])
+      var [reload, setReload] = useState(0)
+
+      useEffect(
+        function () {
+          var alive = true
+          setLoading(true)
+          setError(null)
+          getJson(API + 'stats?range=' + encodeURIComponent(range))
+            .then(function (body) {
+              if (!alive) return
+              var map = body.tracks !== null && typeof body.tracks === 'object' ? body.tracks : {}
+              var list = []
+              Object.keys(map).forEach(function (path) {
+                var stat = map[path]
+                var track = props.trackByPath[path] || null
+                var seconds = Number(stat.playSeconds) || 0
+                var plays = Number(stat.plays) || 0
+                if (seconds <= 0 && plays <= 0) return
+                list.push({
+                  path: path,
+                  track: track,
+                  title: track ? track.title : basenameOf(path),
+                  artist: track ? track.artist || '' : '',
+                  seconds: seconds,
+                  plays: plays,
+                  lastPlayedAt: Number(stat.lastPlayedAt) || 0,
+                  missing: track === null,
+                })
+              })
+              setRows(list)
+              setLoading(false)
+            })
+            .catch(function (cause) {
+              if (!alive) return
+              setError(cause && cause.message ? cause.message : String(cause))
+              setLoading(false)
+            })
+          return function () {
+            alive = false
+          }
+        },
+        [range, reload],
+      )
+
+      var sorted = useMemo(
+        function () {
+          var list = rows.slice()
+          list.sort(function (left, right) {
+            if (sortBy === 'recent') return right.lastPlayedAt - left.lastPlayedAt
+            if (sortBy === 'plays') return right.plays - left.plays || right.seconds - left.seconds
+            return right.seconds - left.seconds || right.plays - left.plays
+          })
+          return list
+        },
+        [rows, sortBy],
+      )
+
+      var totals = useMemo(
+        function () {
+          var seconds = 0
+          var plays = 0
+          rows.forEach(function (row) {
+            seconds += row.seconds
+            plays += row.plays
+          })
+          return { seconds: seconds, plays: plays, tracks: rows.length }
+        },
+        [rows],
+      )
+
+      var ranges = [
+        ['week', t('stats.rangeWeek')],
+        ['month', t('stats.rangeMonth')],
+        ['all', t('stats.rangeAll')],
+      ]
+      var sorts = [
+        ['seconds', t('stats.sortTime')],
+        ['plays', t('stats.sortPlays')],
+        ['recent', t('stats.sortRecent')],
+      ]
+
+      return h(
+        'div',
+        { className: 'mu-stats' },
+        h(
+          'div',
+          { className: 'mu-stats-toolbar' },
+          ranges.map(function (entry) {
+            return h(
+              'button',
+              {
+                key: entry[0],
+                type: 'button',
+                className: 'mu-chip mu-stats-chip' + (range === entry[0] ? ' is-on' : ''),
+                onClick: function () {
+                  setRange(entry[0])
+                },
+              },
+              entry[1],
+            )
+          }),
+          h('span', { className: 'mu-stats-divider' }),
+          sorts.map(function (entry) {
+            return h(
+              'button',
+              {
+                key: entry[0],
+                type: 'button',
+                className: 'mu-chip mu-stats-chip' + (sortBy === entry[0] ? ' is-on' : ''),
+                onClick: function () {
+                  setSortBy(entry[0])
+                },
+              },
+              entry[1],
+            )
+          }),
+        ),
+        h(
+          'div',
+          { className: 'mu-stats-summary' },
+          h(
+            'div',
+            { className: 'mu-stats-card' },
+            h('div', { className: 'mu-stats-card-label' }, t('stats.totalTime')),
+            h('div', { className: 'mu-stats-card-value' }, fmtListenTime(totals.seconds)),
+          ),
+          h(
+            'div',
+            { className: 'mu-stats-card' },
+            h('div', { className: 'mu-stats-card-label' }, t('stats.totalPlays')),
+            h('div', { className: 'mu-stats-card-value' }, String(totals.plays)),
+          ),
+          h(
+            'div',
+            { className: 'mu-stats-card' },
+            h('div', { className: 'mu-stats-card-label' }, t('stats.trackCount')),
+            h('div', { className: 'mu-stats-card-value' }, String(totals.tracks)),
+          ),
+        ),
+        loading
+          ? h('div', { className: 'mu-state' }, h('div', { className: 'mu-spinner' }), t('stats.loading'))
+          : error !== null
+            ? h(
+                'div',
+                { className: 'mu-state' },
+                h('div', { className: 'mu-state-title' }, t('stats.loadFailed')),
+                h('div', { className: 'mu-state-sub' }, error),
+                h(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'mu-btn',
+                    onClick: function () {
+                      setReload(reload + 1)
+                    },
+                  },
+                  t('stats.retry'),
+                ),
+              )
+            : sorted.length === 0
+              ? h('div', { className: 'mu-state' }, h('div', { className: 'mu-state-sub' }, t('stats.empty')))
+              : h(
+                  'div',
+                  { className: 'mu-stats-list' },
+                  sorted.map(function (row) {
+                    return h(
+                      'div',
+                      { className: 'mu-stats-row', key: row.path, title: row.path },
+                      h(Cover, { track: row.track, size: 36, radius: 6 }),
+                      h(
+                        'div',
+                        { className: 'mu-stats-main' },
+                        h('div', { className: 'mu-stats-title' }, row.title),
+                        h(
+                          'div',
+                          { className: 'mu-stats-artist' },
+                          row.artist || (row.missing ? t('stats.unavailable') : ''),
+                        ),
+                      ),
+                      h('div', { className: 'mu-stats-seconds' }, fmtListenTime(row.seconds)),
+                      h('div', { className: 'mu-stats-plays' }, t('stats.plays', { n: row.plays })),
+                      h('div', { className: 'mu-stats-last' }, fmtRecent(row.lastPlayedAt)),
+                    )
+                  }),
+                ),
+      )
+    }
+
     function MusicPanel() {
       var prefs = useRef(readPrefs()).current
       var [snap, setSnap] = useState(player.getSnapshot())
@@ -3073,6 +3560,17 @@ window.__ModuleLoader__.load({
             },
             t('page.tabSongs'),
           ),
+          h(
+            'button',
+            {
+              type: 'button',
+              className: 'mu-tab' + (view === 'stats' ? ' is-on' : ''),
+              onClick: function () {
+                setView('stats')
+              },
+            },
+            t('page.tabStats'),
+          ),
           playlists.map(function (playlist) {
             var isOn = view === 'playlists' && playlistId === playlist.id
             return h(
@@ -3168,6 +3666,17 @@ window.__ModuleLoader__.load({
                   },
                   t('settings.tabLibrary'),
                 ),
+                h(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'mu-prefs-tab' + (prefsTab === 'playback' ? ' is-on' : ''),
+                    onClick: function () {
+                      setPrefsTab('playback')
+                    },
+                  },
+                  t('settings.tabPlayback'),
+                ),
               ),
               prefsTab === 'appearance'
                 ? h(
@@ -3245,7 +3754,8 @@ window.__ModuleLoader__.load({
                       },
                     ),
                   )
-                  : h(
+                  : prefsTab === 'library'
+                    ? h(
                       'div',
                       { className: 'mu-prefs-body' },
                       h('p', { className: 'mu-prefs-hint' }, t('settings.libraryHint')),
@@ -3413,6 +3923,20 @@ window.__ModuleLoader__.load({
                             ),
                           )
                         : null,
+                    )
+                  : h(
+                      'div',
+                      { className: 'mu-prefs-body' },
+                      settingToggle(t('settings.resumeOnStart'), prefsUi.resumeOnStart, function (value) {
+                        updatePref('resumeOnStart', value)
+                      }),
+                      settingToggle(t('settings.autoResume'), prefsUi.autoResume, function (value) {
+                        updatePref('autoResume', value)
+                      }),
+                      settingToggle(t('settings.rememberPerTrack'), prefsUi.rememberPerTrack, function (value) {
+                        updatePref('rememberPerTrack', value)
+                      }),
+                      h('p', { className: 'mu-prefs-hint' }, t('settings.playbackHint')),
                     ),
             )
           : null,
@@ -3464,7 +3988,7 @@ window.__ModuleLoader__.load({
 
         h(
           'div',
-          { className: 'mu-chips' },
+          { className: 'mu-chips', style: view === 'stats' ? { display: 'none' } : undefined },
           h(
             'button',
             { type: 'button', className: 'mu-chip', title: loopLabel(), onClick: cycleLoop },
@@ -3562,7 +4086,10 @@ window.__ModuleLoader__.load({
 
         h(
           'div',
-          { className: 'mu-list' },
+          { className: 'mu-list' + (view === 'stats' ? ' is-stats' : '') },
+          view === 'stats'
+            ? h(StatsView, { tracks: tracks, trackByPath: trackByPath, t: t })
+            : [
           loading && tracks.length === 0
             ? h('div', { className: 'mu-state' }, h('div', { className: 'mu-spinner' }), t('page.scanning'))
             : null,
@@ -3601,6 +4128,7 @@ window.__ModuleLoader__.load({
             ? h('div', { className: 'mu-warn' }, t('page.warnings') + '：' + warnings.slice(0, 3).join(' · '))
             : null,
           visible.map(renderRow),
+              ],
         ),
 
         h(
@@ -3993,6 +4521,24 @@ window.__ModuleLoader__.load({
       '.mu-tab.is-on{background:var(--dsw-alias-interactive-bg-active,rgba(255,255,255,.1));color:var(--dsw-alias-label-primary,#f4f4f5);font-weight:600}',
       '.mu-tab-add{width:30px;padding:0;display:inline-flex;align-items:center;justify-content:center;border:.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12))}',
       '.mu-tab-add:hover{border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.2))}',
+      '.mu-list.is-stats{padding-top:4px}',
+      '.mu-stats{display:flex;flex-direction:column;gap:12px;padding:2px 0 10px}',
+      '.mu-stats-toolbar{display:flex;align-items:center;gap:6px;flex-wrap:wrap}',
+      '.mu-stats-chip{height:26px;padding:0 10px;font-size:12px}',
+      '.mu-stats-divider{width:1px;height:16px;background:var(--dsw-alias-border-l2,rgba(255,255,255,.12));margin:0 2px}',
+      '.mu-stats-summary{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}',
+      '.mu-stats-card{border:.5px solid var(--dsw-alias-border-l1,rgba(255,255,255,.08));border-radius:var(--dsw-radius-md,8px);background:var(--dsw-alias-bg-layer-2,var(--dsw-alias-bg-layer-1,#1b1b1e));padding:10px 12px;min-width:0}',
+      '.mu-stats-card-label{font-size:11px;color:var(--dsw-alias-label-tertiary,#8a8a93);white-space:nowrap}',
+      '.mu-stats-card-value{font-size:17px;font-weight:600;margin-top:2px;color:var(--dsw-alias-label-primary,#f4f4f5);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;font-variant-numeric:tabular-nums}',
+      '.mu-stats-list{display:flex;flex-direction:column;gap:2px}',
+      '.mu-stats-row{display:flex;align-items:center;gap:10px;padding:6px 8px;border-radius:var(--dsw-radius-sm,6px);min-width:0}',
+      '.mu-stats-row:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.05))}',
+      '.mu-stats-main{flex:1;min-width:0}',
+      '.mu-stats-title{font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+      '.mu-stats-artist{font-size:11px;color:var(--dsw-alias-label-tertiary,#8a8a93);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;margin-top:1px}',
+      '.mu-stats-seconds{flex:none;width:104px;text-align:right;font-size:12px;color:var(--dsw-alias-label-secondary,#a1a1aa);font-variant-numeric:tabular-nums}',
+      '.mu-stats-plays{flex:none;width:64px;text-align:right;font-size:11px;color:var(--dsw-alias-label-tertiary,#8a8a93);font-variant-numeric:tabular-nums}',
+      '.mu-stats-last{flex:none;width:78px;text-align:right;font-size:11px;color:var(--dsw-alias-label-tertiary,#8a8a93)}',
       '.mu-view{flex:1;min-height:0;display:flex;flex-direction:column}',
       '.mu-pl-new{display:flex;gap:8px;padding:4px 24px 12px}',
       '.mu-pl-new .mu-input{flex:1}',
@@ -4384,6 +4930,22 @@ window.__ModuleLoader__.load({
           }
         })
 
+        // Flush resume state / listening seconds when the page goes away.
+        ctx.effect(function () {
+          function onVisibility() {
+            if (document.visibilityState === 'hidden') player.flushOnHide()
+          }
+          function onUnload() {
+            player.flushOnHide()
+          }
+          document.addEventListener('visibilitychange', onVisibility)
+          window.addEventListener('beforeunload', onUnload)
+          return function () {
+            document.removeEventListener('visibilitychange', onVisibility)
+            window.removeEventListener('beforeunload', onUnload)
+          }
+        })
+
         function mount(name, registration, component) {
           ctx.effect(function () {
             var dispose = ctx.slots.inject(name, function () {

package/index.js

@@ -9,6 +9,7 @@
  */
 
 import { createLibrary } from './lib/library.js'
+import { createPlayback } from './lib/playback.js'
 import { createPlaylists } from './lib/playlists.js'
 import { createRoutes } from './lib/routes.js'
 import { createSettings } from './lib/settings.js'
@@ -28,9 +29,10 @@ export function apply(ctx, rawConfig) {
   const config = rawConfig !== null && typeof rawConfig === 'object' ? rawConfig : {}
   const settings = createSettings({ dshHome: config.dshHome, seed: config })
   const stats = createStats({ dir: settings.dir })
+  const playback = createPlayback({ dir: settings.dir })
   const library = createLibrary({ getSettings: settings.read, stats })
   const playlists = createPlaylists({ dir: settings.dir })
-  const handle = createRoutes({ settings, library, playlists, stats })
+  const handle = createRoutes({ settings, library, playlists, stats, playback })
 
   ctx.effect(() => {
     const dispose = ctx.webServer.register({

package/lib/playback.js

@@ -0,0 +1,97 @@
+/**
+ * Last playback state for dsh-music-panel.
+ *
+ * Mirrors the resume behaviour of mainstream players (NetEase "remember the
+ * last playback position on start", Spotify/YouTube Music restoring the queue):
+ * the queue, the current index, the position and loop/order are written while
+ * playing and read once when the plugin starts again.
+ *
+ * Stored as `<DSH_HOME>/music/playback.json`. Pure Node.
+ *
+ * @module dsh-music-panel/playback
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const MAX_QUEUE = 500
+const LOOPS = new Set(['all', 'one', 'none'])
+const ORDERS = new Set(['list', 'random'])
+
+function finiteOr(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : fallback
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Coerce an arbitrary payload into a state the client can trust, or null.
+ *
+ * @param {unknown} raw
+ * @returns {{queue: string[], index: number, positionSec: number, durationSec: number, loop: string, order: string, updatedAt: number} | null}
+ */
+export function sanitizePlayback(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const queue = Array.isArray(raw.queue)
+    ? raw.queue.filter((path) => typeof path === 'string' && path !== '').slice(0, MAX_QUEUE)
+    : []
+  const durationSec = Math.max(0, finiteOr(raw.durationSec, 0))
+  const positionSec = clamp(Math.max(0, finiteOr(raw.positionSec, 0)), 0, durationSec > 0 ? durationSec : Number.MAX_SAFE_INTEGER)
+  const index = queue.length === 0
+    ? -1
+    : clamp(Math.floor(finiteOr(raw.index, 0)), 0, queue.length - 1)
+  const loop = LOOPS.has(raw.loop) ? raw.loop : 'all'
+  const order = ORDERS.has(raw.order) ? raw.order : 'list'
+  return {
+    queue,
+    index,
+    positionSec: Math.round(positionSec * 10) / 10,
+    durationSec,
+    loop,
+    order,
+    updatedAt: Math.max(0, Math.round(finiteOr(raw.updatedAt, 0))),
+  }
+}
+
+/**
+ * @param {{ dir: string }} options `dir` is `<DSH_HOME>/music`
+ */
+export function createPlayback({ dir }) {
+  const file = join(dir, 'playback.json')
+  /** `undefined` = not read yet, `null` = no usable file. */
+  let cache
+
+  async function read() {
+    if (cache !== undefined) return cache
+    let parsed = null
+    try {
+      parsed = JSON.parse(await readFile(file, 'utf8'))
+    } catch {
+      parsed = null
+    }
+    cache = sanitizePlayback(parsed)
+    return cache
+  }
+
+  async function write(raw) {
+    const next = sanitizePlayback(raw)
+    if (next === null) return null
+    next.updatedAt = Date.now()
+    await mkdir(dir, { recursive: true })
+    await writeFile(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+    cache = next
+    return next
+  }
+
+  return {
+    file,
+    read,
+    write,
+    invalidate() {
+      cache = undefined
+    },
+  }
+}

package/lib/routes.js

@@ -9,6 +9,11 @@
  *   GET  /music/lyrics?path=...    sidecar .lrc as timed lines
  *   GET  /music/playlists          user playlists
  *   POST /music/play               record one playback for a track
+ *   GET  /music/state              last playback state (resume)
+ *   POST /music/state              persist last playback state
+ *   POST /music/playback           add actually-listened seconds
+ *   POST /music/position           remember one track's resume point
+ *   GET  /music/stats?range=...    aggregated play time / plays (all|week|month)
  *
  * Every path parameter is re-resolved against the configured roots, so a
  * crafted `?path=` can never read outside the folders the user granted.
@@ -200,9 +205,10 @@ async function validateRoots(list) {
  *     remove: (id: string) => Promise<boolean>,
  *   },
  *   stats: { recordPlay: (path: string) => Promise<{ plays: number }> },
+ *   playback: { read: () => Promise<object | null>, write: (state: unknown) => Promise<object | null> },
  * }} deps
  */
-export function createRoutes({ settings, library, playlists, stats }) {
+export function createRoutes({ settings, library, playlists, stats, playback }) {
   return async function handle(req, res) {
     try {
       if (!isLoopback(req)) return fail(res, 403, 'NOT_LOOPBACK', '仅允许本机访问（远程访问已禁用音乐面板）')
@@ -359,6 +365,86 @@ export function createRoutes({ settings, library, playlists, stats }) {
         }
       }
 
+      if (pathname === '/state' && method === 'GET') {
+        const state = playback === undefined ? null : await playback.read()
+        return sendJson(res, 200, { ok: true, state })
+      }
+
+      if (pathname === '/state' && method === 'POST') {
+        if (playback === undefined) return fail(res, 503, 'UNAVAILABLE', '播放状态持久化未启用')
+        let body
+        try {
+          body = await readJson(req)
+        } catch {
+          return fail(res, 400, 'BAD_JSON', '请求体不是合法 JSON')
+        }
+        const state = await playback.write(body)
+        if (state === null) return fail(res, 400, 'BAD_STATE', '播放状态格式不正确')
+        return sendJson(res, 200, { ok: true, state })
+      }
+
+      if (pathname === '/playback' && method === 'POST') {
+        if (stats === undefined) return fail(res, 503, 'UNAVAILABLE', '统计未启用')
+        let body
+        try {
+          body = await readJson(req)
+        } catch {
+          return fail(res, 400, 'BAD_JSON', '请求体不是合法 JSON')
+        }
+        const config = await settings.read()
+        const file = await resolveTrack(body?.path, config.roots)
+        if (file === null) return fail(res, 404, 'NOT_FOUND', '文件不在已配置的音乐目录内')
+        const seconds = Number(body?.seconds)
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+          return fail(res, 400, 'BAD_SECONDS', 'seconds 必须是正数')
+        }
+        const entry = await stats.addPlayTime(file, seconds)
+        if (entry === null) return fail(res, 400, 'BAD_SECONDS', 'seconds 必须是正数')
+        if (body?.positionSec !== undefined) {
+          await stats.setPosition(file, body.positionSec)
+        }
+        return sendJson(res, 200, {
+          ok: true,
+          path: file,
+          playSeconds: entry.playSeconds,
+          plays: entry.plays,
+        })
+      }
+
+      if (pathname === '/position' && method === 'GET') {
+        if (stats === undefined) return sendJson(res, 200, { ok: true, lastPositionSec: null })
+        const config = await settings.read()
+        const file = await resolveTrack(params.get('path'), config.roots)
+        if (file === null) return fail(res, 404, 'NOT_FOUND', '文件不在已配置的音乐目录内')
+        const entry = await stats.get(file)
+        return sendJson(res, 200, { ok: true, path: file, lastPositionSec: entry === null ? null : entry.lastPositionSec })
+      }
+
+      if (pathname === '/position' && method === 'POST') {
+        if (stats === undefined) return fail(res, 503, 'UNAVAILABLE', '统计未启用')
+        let body
+        try {
+          body = await readJson(req)
+        } catch {
+          return fail(res, 400, 'BAD_JSON', '请求体不是合法 JSON')
+        }
+        const config = await settings.read()
+        const file = await resolveTrack(body?.path, config.roots)
+        if (file === null) return fail(res, 404, 'NOT_FOUND', '文件不在已配置的音乐目录内')
+        const entry = await stats.setPosition(file, body?.seconds)
+        if (entry === null) return fail(res, 400, 'BAD_POSITION', 'seconds 必须是非负数')
+        return sendJson(res, 200, { ok: true, path: file, lastPositionSec: entry.lastPositionSec })
+      }
+
+      if (pathname === '/stats' && method === 'GET') {
+        if (stats === undefined || typeof stats.summarize !== 'function') {
+          return sendJson(res, 200, { ok: true, range: 'all', tracks: {} })
+        }
+        const requested = String(params.get('range') || 'all')
+        const range = requested === 'week' || requested === 'month' ? requested : 'all'
+        return sendJson(res, 200, { ok: true, range, tracks: await stats.summarize(range) })
+      }
+
       if (pathname === '/play' && method === 'POST') {
         let body
         try {

package/lib/stats.js

@@ -1,6 +1,12 @@
 /**
- * Per-track statistics for dsh-music-panel: when a file first entered the library
- * and how many times it was played.
+ * Per-track statistics for dsh-music-panel: when a file first entered the
+ * library, how many times it was played, how many seconds it was actually
+ * played, and (optionally) the last position inside the track.
+ *
+ * Counting follows the Last.fm / MusicBee convention: a play only counts when
+ * the track is longer than 30 seconds and has been played for at least half
+ * its duration or 4 minutes (whichever comes first). The caller decides when
+ * that threshold is reached; this module only records.
  *
  * Stored next to the settings in `<DSH_HOME>/music/stats.json`. Pure Node.
  *
@@ -12,17 +18,85 @@ import { join } from 'node:path'
 
 /** Bound the file so a long-lived library cannot grow without limit. */
 const MAX_ENTRIES = 20_000
+/** Daily buckets older than this many days are dropped. */
+const KEEP_DAYS = 31
+
+const MIN_PLAY_SECONDS = 30
+const FOUR_MINUTES = 240
+
+function pad2(value) {
+  return value < 10 ? `0${value}` : String(value)
+}
+
+/** Local calendar day, so "last week" matches what the user sees. */
+export function dayKey(ts = Date.now()) {
+  const date = new Date(ts)
+  return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`
+}
+
+function finiteOr(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : fallback
+}
+
+function sanitizeBucket(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const plays = Math.max(0, Math.floor(finiteOr(raw.plays, 0)))
+  const seconds = Math.max(0, Math.round(finiteOr(raw.seconds, 0) * 10) / 10)
+  const lastAt = Math.max(0, Math.round(finiteOr(raw.lastAt, 0)))
+  return { plays, seconds, lastAt }
+}
 
 function sanitizeEntry(raw) {
-  if (raw === null || typeof raw !== 'object') return null
-  const addedAt = Number(raw.addedAt)
-  const plays = Number(raw.plays)
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const addedAt = finiteOr(raw.addedAt, 0)
+  const plays = Math.max(0, Math.floor(finiteOr(raw.plays, 0)))
+  const playSeconds = Math.max(0, Math.round(finiteOr(raw.playSeconds, 0) * 10) / 10)
+  const lastPlayedAt = raw.lastPlayedAt === null || raw.lastPlayedAt === undefined
+    ? null
+    : Math.max(0, Math.round(finiteOr(raw.lastPlayedAt, 0))) || null
+  const lastPositionSec = raw.lastPositionSec === null || raw.lastPositionSec === undefined
+    ? null
+    : Math.max(0, Math.round(finiteOr(raw.lastPositionSec, 0) * 10) / 10)
+  const days = {}
+  if (raw.days !== null && typeof raw.days === 'object' && !Array.isArray(raw.days)) {
+    for (const [key, value] of Object.entries(raw.days)) {
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(key)) continue
+      const bucket = sanitizeBucket(value)
+      if (bucket !== null) days[key] = bucket
+    }
+  }
   return {
-    addedAt: Number.isFinite(addedAt) && addedAt > 0 ? addedAt : Date.now(),
-    plays: Number.isFinite(plays) && plays >= 0 ? Math.floor(plays) : 0,
+    addedAt: addedAt > 0 ? addedAt : Date.now(),
+    plays,
+    playSeconds,
+    lastPlayedAt,
+    lastPositionSec,
+    days,
+  }
+}
+
+function pruneDays(entry, now = Date.now()) {
+  const cutoff = dayKey(now - (KEEP_DAYS - 1) * 86_400_000)
+  for (const key of Object.keys(entry.days)) {
+    if (key < cutoff) delete entry.days[key]
   }
 }
 
+/**
+ * Threshold after which one play is counted (Last.fm / MusicBee default).
+ * `durationSec <= 0` means "unknown": the caller should wait for 4 minutes.
+ *
+ * @param {number} durationSec
+ * @returns {number}
+ */
+export function playThreshold(durationSec) {
+  const duration = finiteOr(durationSec, 0)
+  if (duration <= 0) return FOUR_MINUTES
+  if (duration <= MIN_PLAY_SECONDS) return duration + 0.5
+  return Math.min(duration / 2, FOUR_MINUTES)
+}
+
 /**
  * @param {{ dir: string }} options `dir` is `<DSH_HOME>/music`
  */
@@ -51,7 +125,13 @@ export function createStats({ dir }) {
 
   async function save() {
     await mkdir(dir, { recursive: true })
-    await writeFile(file, `${JSON.stringify({ tracks: cache }, null, 2)}\n`, 'utf8')
+    await writeFile(file, `${JSON.stringify({ version: 2, tracks: cache }, null, 2)}\n`, 'utf8')
+  }
+
+  function bucketOf(entry, now) {
+    const key = dayKey(now)
+    if (entry.days[key] === undefined) entry.days[key] = { plays: 0, seconds: 0, lastAt: 0 }
+    return entry.days[key]
   }
 
   return {
@@ -62,7 +142,14 @@ export function createStats({ dir }) {
       let dirty = false
       for (const path of paths) {
         if (tracks[path] === undefined) {
-          tracks[path] = { addedAt: now, plays: 0 }
+          tracks[path] = {
+            addedAt: now,
+            plays: 0,
+            playSeconds: 0,
+            lastPlayedAt: null,
+            lastPositionSec: null,
+            days: {},
+          }
           dirty = true
         }
       }
@@ -75,15 +162,115 @@ export function createStats({ dir }) {
       return tracks[path] ?? null
     },
 
+    /** Count one qualifying play (the caller applies the Last.fm threshold). */
     async recordPlay(path) {
       const tracks = await load()
-      const entry = tracks[path] ?? { addedAt: Date.now(), plays: 0 }
+      const entry = tracks[path] ?? {
+        addedAt: Date.now(),
+        plays: 0,
+        playSeconds: 0,
+        lastPlayedAt: null,
+        lastPositionSec: null,
+        days: {},
+      }
+      const now = Date.now()
       entry.plays = (Number(entry.plays) || 0) + 1
+      entry.lastPlayedAt = now
+      const bucket = bucketOf(entry, now)
+      bucket.plays += 1
+      bucket.lastAt = now
+      pruneDays(entry, now)
+      tracks[path] = entry
+      await save()
+      return { ...entry }
+    },
+
+    /** Add actually-listened seconds (never seeks or paused time). */
+    async addPlayTime(path, seconds) {
+      const value = finiteOr(seconds, 0)
+      if (value <= 0) return null
+      const tracks = await load()
+      const entry = tracks[path] ?? {
+        addedAt: Date.now(),
+        plays: 0,
+        playSeconds: 0,
+        lastPlayedAt: null,
+        lastPositionSec: null,
+        days: {},
+      }
+      const now = Date.now()
+      entry.playSeconds = Math.round((entry.playSeconds + value) * 10) / 10
+      entry.lastPlayedAt = now
+      const bucket = bucketOf(entry, now)
+      bucket.seconds = Math.round((bucket.seconds + value) * 10) / 10
+      bucket.lastAt = now
+      pruneDays(entry, now)
       tracks[path] = entry
       await save()
       return { ...entry }
     },
 
+    /** Per-track resume point, used when "remember per track" is enabled. */
+    async setPosition(path, seconds) {
+      const value = finiteOr(seconds, -1)
+      if (value < 0) return null
+      const tracks = await load()
+      const entry = tracks[path] ?? {
+        addedAt: Date.now(),
+        plays: 0,
+        playSeconds: 0,
+        lastPlayedAt: null,
+        lastPositionSec: null,
+        days: {},
+      }
+      entry.lastPositionSec = Math.round(value * 10) / 10
+      tracks[path] = entry
+      await save()
+      return { ...entry }
+    },
+
+    /**
+     * Aggregate per track over `all`, `week` (last 7 days) or `month`
+     * (last 30 days). Only tracks with activity inside the range are kept.
+     *
+     * @param {'all'|'week'|'month'} [range]
+     */
+    async summarize(range = 'all') {
+      const tracks = await load()
+      const days = range === 'week' ? 7 : range === 'month' ? 30 : 0
+      const since = days > 0 ? dayKey(Date.now() - (days - 1) * 86_400_000) : null
+      const out = {}
+      for (const [path, entry] of Object.entries(tracks)) {
+        if (since === null) {
+          if (entry.plays > 0 || entry.playSeconds > 0) {
+            out[path] = {
+              plays: entry.plays,
+              playSeconds: entry.playSeconds,
+              lastPlayedAt: entry.lastPlayedAt,
+            }
+          }
+          continue
+        }
+        let plays = 0
+        let seconds = 0
+        let lastAt = 0
+        for (const [day, bucket] of Object.entries(entry.days)) {
+          if (day < since) continue
+          plays += bucket.plays
+          seconds += bucket.seconds
+          if (bucket.lastAt > lastAt) lastAt = bucket.lastAt
+        }
+        if (plays > 0 || seconds > 0) {
+          out[path] = {
+            plays,
+            playSeconds: Math.round(seconds * 10) / 10,
+            lastPlayedAt: lastAt || entry.lastPlayedAt,
+          }
+        }
+      }
+      return out
+    },
+
     /** In-memory view; the file is read once per process. */
     async snapshot() {
       return { ...(await load()) }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-music-panel",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Local music library for DeepSeek Harness: scan a folder, browse tracks with cover art and tags, and play through a sidebar-panel player with loop, shuffle and volume. · DSH 本地音乐插件：扫描音乐目录、读取封面与标签、侧栏入口 + 全屏播放器。",
   "license": "MIT",
@@ -25,8 +25,8 @@
     "audio"
   ],
   "scripts": {
-    "test": "node test/config.test.mjs && node test/meta.test.mjs && node test/library.test.mjs && node test/routes.test.mjs && node test/lyrics.test.mjs && node test/playlists.test.mjs && node test/stats.test.mjs && node test/client.smoke.test.mjs",
-    "check": "node --check index.js && node --check client.js && node --check lib/config.js && node --check lib/settings.js && node --check lib/meta.js && node --check lib/library.js && node --check lib/http.js && node --check lib/lyrics.js && node --check lib/playlists.js && node --check lib/stats.js && node --check lib/routes.js",
+    "test": "node test/config.test.mjs && node test/meta.test.mjs && node test/library.test.mjs && node test/routes.test.mjs && node test/lyrics.test.mjs && node test/playlists.test.mjs && node test/stats.test.mjs && node test/playback.test.mjs && node test/client.smoke.test.mjs",
+    "check": "node --check index.js && node --check client.js && node --check lib/config.js && node --check lib/settings.js && node --check lib/meta.js && node --check lib/library.js && node --check lib/http.js && node --check lib/lyrics.js && node --check lib/playlists.js && node --check lib/stats.js && node --check lib/playback.js && node --check lib/routes.js",
     "pack:check": "npm pack --dry-run"
   },
   "exports": {