@doitian/dsh-music 0.1.2 → 0.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 NetEase Cloud Music ([music.163.com](https://music.163.com)) playback and an AI DJ, inside DeepSeek Harness.
 
-A **Music** entry appears in the DSH sidebar. It opens a player — your queue, synced lyrics, an `<audio>` element that streams through the host, QR sign-in, and a continuous AI DJ. The same player is also exposed to the agent through seven tools, so it can search, queue, and curate from a conversation.
+A **Music** entry appears in the DSH sidebar. It opens a player — your queue, synced lyrics, an `<audio>` element that streams through the host, QR sign-in, NetEase likes, and a continuous AI DJ. The same player is also exposed to the agent through seven tools, so it can search, queue, and curate from a conversation.
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -144,6 +144,59 @@ Two implementation details worth knowing:
 `/music/health` reports both: `audio.preferred` and `audio.last` (what the last
 stream actually served, including `downgraded`).
 
+## Likes and taste
+
+A track holds one of three taste levels — **liked**, **unrated**, or
+**disliked** — and the player draws whichever it is:
+
+| Control | Level it sets |
+|---|---|
+| the **♡ / ♥** in a queue row, or the heart in the transport row | **liked** — the track goes into the account's 我喜欢的音乐 playlist on NetEase. Clicking the filled heart takes the like back. |
+| the **✕** in the transport row | **disliked** — local, and fed to the DJ, which stops picking the track. Clicking the filled ✕ clears it. |
+| the **✕** on a queue row | **disliked** as well. Taking a track out of the queue is a judgement about the track, not just about the list — without recording it the DJ re-derives the same track from the same similarity and charts within a batch or two. |
+| neither | unrated. |
+
+A like is a **NetEase** like, not a plugin flag, and the two halves of what that
+needs are both plain endpoints:
+
+- `POST /api/song/like` — one of the few *write* endpoints the web API still
+  serves unencrypted, so no `weapi` client is needed. It takes the direction
+  rather than toggling: the page always says which level it wants, so a stale
+  poll cannot turn a click into the wrong one, and disliking a liked track is one
+  request instead of two racing ones.
+- `GET /api/song/like/check` — which of a batch of ids are liked. The answer is
+  cached per track (5 minutes), so a whole queue's hearts cost one request, and
+  only tracks with no fresh answer ever cost another.
+
+Four properties are worth knowing, because they are what makes a heart mean
+something:
+
+- **An unknown track is not an unliked one.** A track nobody has asked about has
+  no answer, and renders as unrated until NetEase gives one.
+- **A refusal is not an answer.** An anonymous session answers `code 301` for
+  every id, and a delisted track answers `400` with NetEase's own reason
+  (`下架歌曲无法收藏` for 晴天, for instance). Both leave the heart empty and say
+  why in the toast; a refused check is retried later instead of being cached as
+  "not liked", so signing in mid-session fills the hearts without a restart.
+- **The account is the record.** `feedback.likes` in `session.json` is a *copy*
+  of the account's likes, kept for the DJ's taste digest. It is reconciled with
+  the account at startup — one read of the liked playlist — so a like made on
+  the phone counts, and a like an earlier build recorded locally (because it had
+  nowhere to send it) does not linger as a phantom.
+- **A dislike is local.** The plain web API has no dislike endpoint, so this is
+  where the plugin's own taste memory is the only record. Liking and disliking
+  are the same three levels rather than two flags: one replaces the other, and
+  disliking a liked track removes it on NetEase as well.
+- **Removing a queued track is a dislike, once.** The row's ✕ goes through the
+  queue endpoint, whose removal *is* the judgement: the row leaves the list and
+  an unrated track is recorded as disliked in the same request, so the DJ does
+  not derive it again from the same similarity. The confirm names the removal —
+  the judgement is the host's side of it. A track that already carries a level
+  keeps it, because removing is often just queue housekeeping (clearing out what
+  has already been heard) and rewriting a like into a dislike would be worse
+  than missing the signal. Removing the track that is playing also advances
+  playback, which a removal otherwise would not.
+
 ## The AI DJ
 
 The DJ keeps the queue stocked. When the queue drops below
@@ -366,6 +419,7 @@ browser (DSH web GUI, http://127.0.0.1:<port>)
                           ├─ lib/session.js   cookie store + QR login state machine
                           ├─ lib/state.js     queue, cursor, transport revisions
                           ├─ lib/dj.js        candidate pool + model/heuristic tiers
+                          ├─ lib/likes.js     the account's like state, cached
                           └─ lib/router.js    JSON API, HTML, Range-capable audio proxy
 ```
 
@@ -398,8 +452,10 @@ Four design notes:
 
 - The `/music` route prefix is registered on the bare HTTP server, which owns no
   authentication of its own. Anyone who can reach the port can browse the
-  library and stream audio; the route is loopback-only in the shipped
-  composition. It exposes no credentials — only search results, the queue, and
+  library, stream audio, and **change the account's likes** — `POST
+  /music/api/taste` is the panel's own control, so it is a real write to the
+  NetEase account. The route is loopback-only in the shipped composition. It
+  exposes no credentials — only search results, the queue, the like state, and
   audio bytes.
 - The NetEase cookie lives in `$DSH_HOME/music/session.json` in plain text, the
   same posture as the rest of the profile's session data. `music_login` with
@@ -424,6 +480,7 @@ when something looks wrong:
             "music_dj", "music_now_playing", "music_login"],
   "dj": { "enabled": false, "model": null, "lastRoute": null,
           "modelError": null, "lastPlanAt": null, "error": null },
+  "likes": { "cached": 12, "pending": 0, "error": null },
   "dataDir": "C:\\Users\\…\\.dsh\\music",
   "session": { "authenticated": true, "nickname": "…", "vip": true },
   "uptimeMs": 123456
@@ -433,7 +490,10 @@ when something looks wrong:
 `tools` is the point: the HTTP route is registered before the tools, so a tool
 that failed to register would otherwise leave a route that answers normally.
 Seeing all seven names is what proves startup completed. `panelContract` is the
-page/engine boundary the browser half checks before it starts playback.
+page/engine boundary the browser half checks before it starts playback. `likes`
+is the cache behind the hearts: `cached` is how many answers it holds, and
+`error` names why a check produced none — an anonymous session never asks, so
+both stay empty.
 
 ### If the browser blocks autoplay
 
@@ -469,8 +529,8 @@ down first. A restart brings both halves back into agreement.
 
 ```powershell
 npm run check        # node --check on every module
-npm test             # 76 deterministic tests: pure, DJ, browser half
-npm run test:live    # 23 integration tests against the live NetEase API
+npm test             # 114 deterministic tests: pure, like state, DJ, browser half
+npm run test:live    # 33 integration tests against the live NetEase API
 npm run test:all     # both
 ```
 
@@ -486,10 +546,11 @@ network cases inside it.
 Or run one file directly:
 
 ```powershell
-node test/netease.test.mjs   # 18 pure: normalisation, quality ladder, cookies, player state
+node test/netease.test.mjs   # 32 pure: normalisation, quality ladder, likes, cookies, taste, player state
+node test/likes.test.mjs     # 12 like-state cache: what counts as an answer, refusals, batching, writes
 node test/dj.test.mjs        # 37 AI DJ: model call identity, route resolution, failure reporting, queue invariants
-node test/client.test.mjs    # 21 browser half: the engine against a fake DOM, and the page it pairs with
-node test/host.test.mjs      # 23 integration: routes, streaming, curation, quality
+node test/client.test.mjs    # 38 browser half: the engine against a fake DOM, and the page it pairs with
+node test/host.test.mjs      # 33 integration: routes, streaming, curation, quality, taste
 ```
 
 The DJ tests drive `ctx.llm.stream()` with a stub that emits the documented
@@ -522,7 +583,7 @@ poll, and a track change replaces the pane. Two more cover the pane's shape: it
 is capped to a few lines, collapses to its header on demand, and remembers that
 choice across loads — while still fetching the lines, so expanding is instant.
 
-`npm test` runs the three deterministic files in sequence (`npm run test:all`
+`npm test` runs the four deterministic files in sequence (`npm run test:all`
 adds the live one), deliberately **not** `node --test <dir>`: the directory form forks one child process per file, which
 is blocked in sandboxed environments.
 
@@ -581,9 +642,10 @@ workflow, tag, and commit — `npm view @doitian/dsh-music@<version> dist.attest
   a signed-in VIP account — 周杰伦's 晴天 (`id 186016`) is the canonical example,
   because it belongs to a digital album. The plugin surfaces NetEase's own
   refusal (`403` plus a reason) rather than retrying.
-- **No `weapi`/`eapi` encryption**, so like/scrobble/playlist-write endpoints
-  (which require it) are not implemented. Liking a track is recorded locally and
-  fed to the DJ instead.
+- **No `weapi`/`eapi` encryption**, so scrobbling and playlist writes are not
+  implemented. Liking a track needs none of it — see
+  [Likes and taste](#likes-and-taste) — but a *dislike* stays local, because
+  there is no plain endpoint for one.
 - **`apiPrefix` must stay `music`** unless `BASE` in `lib/client.js` is changed
   to match.
 - **The DJ's model tier is covered against stub contracts, not a live

package/lib/index.js

@@ -22,6 +22,7 @@ import { Netease } from './netease.js';
 import { QrLogin, SessionStore, ANONYMOUS_COOKIE } from './session.js';
 import { Player } from './state.js';
 import { AiDj } from './dj.js';
+import { LikeState } from './likes.js';
 import { MusicRouter } from './router.js';
 
 export const name = 'music';
@@ -129,6 +130,9 @@ export function apply(ctx, config = {}) {
 
   const qr = new QrLogin({ api, store, logger });
 
+  // The account owns its likes; this is the cache the panel's hearts read.
+  const likes = new LikeState({ api, logger });
+
   /**
    * The LLM service is optional: the DJ falls back to its heuristic tier when
    * absent, so the plugin still works in a composition without a model route.
@@ -190,10 +194,24 @@ export function apply(ctx, config = {}) {
   // ------------------------------------------------------------ session boot
   void api
     .fetchAccount()
-    .then((account) => {
+    .then(async (account) => {
       if (account) logger.info(`[music] signed in as ${account.nickname}`);
       else if (api.authenticated) logger.warn('[music] session cookie present but the account check failed');
       else logger.info('[music] anonymous session (search and non-VIP playback only)');
+
+      // The account holds the likes; the local list is a copy the DJ reads.
+      // Reconciling it here keeps that copy honest across a like made on the
+      // phone, and migrates a list an earlier build recorded locally because it
+      // had no endpoint to send it to.
+      try {
+        const likedIds = await api.likedPlaylistIds(account?.uid);
+        if (likedIds) {
+          store.setLikedIds(likedIds);
+          logger.debug(`[music] like mirror reconciled with the account (${likedIds.length} track(s))`);
+        }
+      } catch (error) {
+        logger.warn(`[music] could not read the account's likes: ${error.message}`);
+      }
     })
     .catch((error) => logger.warn(`[music] account check failed: ${error.message}`));
 
@@ -223,6 +241,7 @@ export function apply(ctx, config = {}) {
     store,
     qr,
     dj,
+    likes,
     panelHtml: PANEL_HTML,
     qrcodeJs: QRCODE_JS,
     config,
@@ -252,6 +271,8 @@ export function apply(ctx, config = {}) {
         lastPlanAt: player.dj.lastPlanAt,
         error: player.dj.error,
       },
+      /** How much of the account's like state is cached, and why it is not. */
+      likes: likes.status(),
       dataDir,
       session: { authenticated: api.authenticated, nickname: api.account?.nickname ?? null, vip: Boolean(api.account?.vip) },
       uptimeMs: Math.round(process.uptime() * 1000),

package/lib/likes.js

@@ -0,0 +1,169 @@
+/**
+ * NetEase's like state for the tracks the panel is showing.
+ *
+ * A like lives in the account, not in this plugin: `/api/song/like/check` is
+ * where the truth is, and this class is the cache in front of it. Four
+ * properties are deliberate:
+ *
+ *   - **Unknown is not "not liked".** A track nobody has asked about has no
+ *     answer; `isLiked` reads false for it, and `known` says which of the two
+ *     it is. The panel renders a hollow heart either way, so the difference
+ *     only matters to a caller that is about to write.
+ *   - **A refusal is not an answer.** An anonymous session answers `code: 301`
+ *     for every id. Caching that as "not liked" would leave every heart empty
+ *     for the rest of the session, so a refused check caches nothing and is
+ *     retried after a cool-off instead.
+ *   - **A write is authoritative.** `set()` writes through to NetEase and then
+ *     updates the cache, so the panel's next poll does not need a round trip to
+ *     see the change it just made. It never claims a like the account does not
+ *     have: a refused write leaves the cache untouched.
+ *   - **Nothing here is persisted.** The account is the storage; a restart
+ *     re-reads it, and a different account must not inherit the last one's
+ *     answers, which is what `clear()` is for.
+ *
+ * @module dsh-music/likes
+ */
+
+/** How long one answer is trusted before it is asked again. */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+
+/** Ids per `/api/song/like/check` request; it takes a list, but not a URL. */
+const CHECK_BATCH = 100;
+
+/** How long a refused or failed check waits before trying again. */
+const RETRY_AFTER_MS = 30_000;
+
+export class LikeState {
+  /**
+   * @param {object} options
+   * @param {import('./netease.js').Netease} options.api
+   * @param {{warn: Function, info: Function, debug: Function}} [options.logger]
+   * @param {number} [options.ttlMs] how long one answer stays fresh.
+   * @param {number} [options.batchSize] ids per check request.
+   */
+  constructor({ api, logger, ttlMs = DEFAULT_TTL_MS, batchSize = CHECK_BATCH } = {}) {
+    this.api = api;
+    this.logger = logger;
+    this.ttlMs = ttlMs;
+    this.batchSize = batchSize;
+    /** @type {Map<number, {liked: boolean, at: number}>} */
+    this.answers = new Map();
+    /** @type {Map<number, Promise<void>>} in-flight checks, so polls share one. */
+    this.pending = new Map();
+    /** Earliest time a refused check may be attempted again. */
+    this.retryAt = 0;
+    /** Why the last check did not produce answers, for `/music/health`. */
+    this.error = null;
+  }
+
+  /** The cached answer; false when there is none. See {@link known}. */
+  isLiked(id) {
+    return this.answers.get(Number(id))?.liked === true;
+  }
+
+  /** Whether a fresh answer for this track is cached — either way. */
+  known(id) {
+    const entry = this.answers.get(Number(id));
+    return Boolean(entry) && Date.now() - entry.at < this.ttlMs;
+  }
+
+  /** Forget every answer. A session change invalidates all of them. */
+  clear() {
+    this.answers.clear();
+    this.pending.clear();
+    this.retryAt = 0;
+    this.error = null;
+    return this;
+  }
+
+  /**
+   * Resolve the like state of `ids`, asking NetEase only about the tracks with
+   * no fresh answer. Never throws: a like check must not fail a poll, and an
+   * unresolved id simply stays unknown.
+   */
+  async ensure(ids) {
+    // Nothing can be liked on an anonymous session, so there is nothing to ask.
+    if (!this.api?.authenticated) return;
+    const list = [...new Set([...ids].map(Number).filter(Number.isFinite))];
+    const stale = list.filter((id) => !this.known(id) && !this.pending.has(id));
+    if (stale.length === 0) return;
+    if (Date.now() < this.retryAt) return;
+
+    const work = this.#load(stale).finally(() => {
+      for (const id of stale) this.pending.delete(id);
+    });
+    for (const id of stale) this.pending.set(id, work);
+    await work;
+  }
+
+  /** Ask for `ids` in batches and cache every answer in them. */
+  async #load(ids) {
+    for (let offset = 0; offset < ids.length; offset += this.batchSize) {
+      const chunk = ids.slice(offset, offset + this.batchSize);
+      let result;
+      try {
+        result = await this.api.likedIds(chunk);
+      } catch (error) {
+        this.#coolOff(`like check failed: ${error.message}`);
+        return;
+      }
+      if (!result.ok) {
+        // Not an answer: cache nothing, so signing in or a retry can still
+        // resolve these tracks rather than freezing them as unliked.
+        this.#coolOff(`like check refused (code ${result.code}): ${result.reason}`);
+        return;
+      }
+      const liked = new Set(result.ids);
+      const at = Date.now();
+      for (const id of chunk) this.answers.set(id, { liked: liked.has(id), at });
+      this.error = null;
+    }
+  }
+
+  #coolOff(reason) {
+    this.retryAt = Date.now() + RETRY_AFTER_MS;
+    this.error = reason;
+    this.logger?.debug?.(`[music] ${reason}`);
+  }
+
+  /**
+   * Like or un-like one track on NetEase.
+   *
+   * The account is written first and the cache only follows a confirmed change,
+   * so the panel can never show a heart the account would contradict.
+   *
+   * @param {number|string} trackId
+   * @param {boolean} liked
+   * @returns {Promise<{ok: boolean, id: number, liked?: boolean, code?: number|string, reason?: string}>}
+   */
+  async set(trackId, liked) {
+    const id = Number(trackId);
+    if (!Number.isFinite(id)) {
+      return { ok: false, id: trackId, code: 'BAD_ID', reason: `invalid track id "${trackId}"` };
+    }
+    if (!this.api?.authenticated) {
+      return { ok: false, id, code: 'ANONYMOUS', reason: 'the NetEase session is anonymous' };
+    }
+    let result;
+    try {
+      result = await this.api.likeSong(id, liked);
+    } catch (error) {
+      return { ok: false, id, code: 'NETWORK', reason: error.message };
+    }
+    if (!result.ok) return result;
+    this.answers.set(id, { liked: Boolean(liked), at: Date.now() });
+    this.error = null;
+    return result;
+  }
+
+  /** What the cache holds, for `/music/health`. */
+  status() {
+    return {
+      cached: this.answers.size,
+      pending: this.pending.size,
+      error: this.error,
+    };
+  }
+}
+
+export { CHECK_BATCH, DEFAULT_TTL_MS, RETRY_AFTER_MS };

package/lib/netease.js

@@ -14,6 +14,8 @@
  *   - `api/toplist`                   anonymous OK
  *   - `api/discovery/simiSong`        anonymous OK
  *   - `api/personalized/newsong`      anonymous OK
+ *   - `api/song/like`                 POST: like / un-like, needs a session
+ *   - `api/song/like/check`           which of these ids the account liked
  *   - `api/login/qrcode/*`            QR login handshake
  *
  * @module dsh-music/netease
@@ -544,6 +546,78 @@ export class Netease {
     return normalizeTracks(data?.data);
   }
 
+  // ------------------------------------------------------------------ likes
+
+  /**
+   * Like or un-like one track on the account.
+   *
+   * `/api/song/like` is one of the few *write* endpoints the plain web API
+   * still serves unencrypted — it answers `{playlistId, code: 200}` and puts the
+   * track in (or takes it out of) the account's 我喜欢的音乐 playlist. It takes
+   * the direction rather than toggling, so the caller must know which one it
+   * means; ask {@link likedIds} when it does not.
+   *
+   * A refusal is reported, not thrown: an anonymous session answers `code: 301`
+   * and a delisted track answers `code: 400` with NetEase's own reason
+   * ("歌曲已经下架了"), and both are ordinary outcomes of a click. Only a
+   * transport failure throws.
+   *
+   * @param {number|string} id track id.
+   * @param {boolean} like `true` to like, `false` to remove the like.
+   */
+  async likeSong(id, like = true) {
+    const trackId = Number(id);
+    if (!Number.isFinite(trackId)) {
+      return { ok: false, id, code: 'BAD_ID', reason: `invalid track id "${id}"` };
+    }
+    const data = await this.call('/api/song/like', {
+      method: 'POST',
+      query: { trackId, like: Boolean(like) },
+    });
+    if (Number(data?.code) !== 200) {
+      return {
+        ok: false,
+        id: trackId,
+        code: data?.code ?? 'UNKNOWN',
+        reason:
+          data?.message ||
+          data?.msg ||
+          (this.authenticated ? 'NetEase refused the change' : 'sign in to NetEase first'),
+      };
+    }
+    return { ok: true, id: trackId, liked: Boolean(like), playlistId: data?.playlistId ?? null };
+  }
+
+  /**
+   * Which of these tracks the account has liked.
+   *
+   * `/api/song/like/check` answers `{ids: [...the liked subset...]}`, so one
+   * request covers a whole queue. An anonymous session answers `code: 301` for
+   * every id — a refusal, not "nothing is liked" — and comes back as
+   * `ok: false` so a caller never caches it as an answer.
+   *
+   * @param {Iterable<number|string>} ids
+   * @returns {Promise<{ok: boolean, ids: number[], code?: number|string, reason?: string}>}
+   */
+  async likedIds(ids) {
+    const list = [...new Set([...ids].map(Number).filter(Number.isFinite))];
+    // NetEase answers an empty batch with `code: 400`, and an empty question has
+    // no answer to fetch anyway.
+    if (list.length === 0) return { ok: true, ids: [] };
+    const data = await this.call('/api/song/like/check', {
+      query: { trackIds: JSON.stringify(list) },
+    });
+    if (Number(data?.code) !== 200 || !Array.isArray(data?.ids)) {
+      return {
+        ok: false,
+        ids: [],
+        code: data?.code ?? 'UNKNOWN',
+        reason: data?.message || data?.msg || 'NetEase refused the like check',
+      };
+    }
+    return { ok: true, ids: data.ids.map(Number) };
+  }
+
   // -------------------------------------------------------------- account
 
   /** Account summary; `null` when the session is anonymous or expired. */
@@ -577,9 +651,32 @@ export class Netease {
       cover: resizeImage(item.coverImgUrl, 300),
       trackCount: item.trackCount ?? 0,
       subscribed: Boolean(item.subscribed),
+      /** `5` marks 我喜欢的音乐 — the account's likes, as a playlist. */
+      specialType: item.specialType ?? 0,
     }));
   }
 
+  /**
+   * Every track id in the account's 我喜欢的音乐 playlist, or `null` when there
+   * is no account or no such playlist.
+   *
+   * This is the whole like state in one read, which is what makes it useful for
+   * reconciling a local mirror; use {@link likedIds} to ask about specific
+   * tracks. The playlist's length is not capped by `n` — NetEase returns the
+   * complete `trackIds` list — so one request covers a library of any size.
+   *
+   * @param {number|string} [uid] owner; defaults to the fetched account.
+   */
+  async likedPlaylistIds(uid) {
+    const owner = Number(uid ?? this.account?.uid);
+    if (!Number.isFinite(owner)) return null;
+    const playlists = await this.userPlaylists(owner, { limit: 1000 });
+    const liked = playlists.find((playlist) => playlist.specialType === 5);
+    if (!liked) return null;
+    const detail = await this.call('/api/v6/playlist/detail', { query: { id: liked.id, n: 1 } });
+    return (detail?.playlist?.trackIds ?? []).map((entry) => entry.id).filter(Number.isFinite);
+  }
+
   // ------------------------------------------------------------ QR login
 
   /**