@doitian/dsh-music 0.1.1 → 0.1.2

package/README.md

@@ -2,17 +2,19 @@
 
 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 full player — search, charts, 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, 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.
 
 ```
-┌ 音乐 music.163.com ───────────── [AI DJ] [mood input] [account] ┐
-│ 搜索 | 榜单 | 推荐        │  ♪ 海屿你 — 马也_Crabbit               │
-│                           │  ⏮  ▶  ⏭   列表   ♡ ✕ 🔊 ────────     │
-│  1. 海屿你                │                                        │
-│     马也_Crabbit           │  歌词 Lyrics                          │
-│  2. 明知故犯              │  [00:12.40] ...                        │
-│     Max李玄               │  播放队列 Queue (12)                   │
-└───────────────────────────┴────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│ 音乐 music.163.com              [AI DJ] [mood] [account]         │
+│                                                                  │
+│ ♪ 海屿你 — 马也_Crabbit                                          │
+│ 上一首 · 播放 · 下一首 · 列表 · 喜欢 · 静音 · 音量               │
+│                                                                  │
+│ 歌词 Lyrics                                                      │
+│ [00:12.40] ...                                                   │
+│ 播放队列 Queue (12)                                              │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
 ## Install
@@ -61,6 +63,15 @@ need no reinstall. Note that this is what makes a plugin *remount* re-read the
 served page while the module stays cached — see
 [Reloading a change](#reloading-a-change).
 
+**Language.** The UI follows the Harness language (Settings → Language): the
+sidebar label and error page register a zh/en dictionary with the host's
+`locale` service, and the player page follows the shell's `<html lang>` live.
+Switching language re-renders both in place — no restart.
+
+While a profile is linked, the Desktop app's **Add plugin** flow is the wrong
+tool for it: that flow installs the published tarball, which replaces the
+`link:` dependency. Re-add the link if it happens.
+
 ### Either way
 
 The bundle's own `cordis.patch.yml` inserts the plugin entry, so no
@@ -115,7 +126,7 @@ rich request could not be honoured. It never silently pretends, and it never
 leaves you with silence because you asked for more than the track has.
 
 The choice is saved in `session.json` and beats `config.audioLevel` in the
-profile patch, the same precedence the curator model uses. An unknown value in
+profile patch, the same precedence the DJ's model route uses. An unknown value in
 either place falls back to `exhigh` rather than failing a stream.
 
 Two implementation details worth knowing:
@@ -154,6 +165,28 @@ Then one of two tiers chooses:
   affinity, novelty against play history, and explicit like/dislike feedback,
   then interleaved so consecutive tracks do not share an artist.
 
+**Every model call carries a session identity.** A leaf call cannot set headers
+— `GenerateOptions` has no `headers` field — so `sessionId` is the only identity
+a plugin can give a provider, and each adapter maps it onto whatever that
+provider calls a per-conversation header: pi-ai emits `x-opencode-session` for
+the `opencode-go` route. Without it, a provider that keys on the conversation
+sees an anonymous client ignoring its conventions.
+
+The identity is minted once per install and persisted in `session.json`, so
+every plan and every restart stays inside one conversation; `dj.sessionId` pins
+it explicitly instead. A request with no identity is refused rather than sent
+bare, so the failure is a recorded `dj.modelError` rather than a silent one.
+
+Two other properties are worth knowing:
+
+- **The DJ is not an agent, and does not start one.** It is plugin code that
+  gathers candidates, makes one model call, and stocks the queue. Routing that
+  call through a DSH agent would buy conversation memory and an audit trail at
+  the cost of a session lifecycle (rotation, tool masking, disposal).
+- **The model tier is stateless.** Each plan sends its own pool and gets its
+  picks back; there is no accumulated transcript, no context growth and no drift
+  from a previous mood — which is the property, not a limitation, for this job.
+
 The model tier is optional and silent on failure; the DJ never blocks playback.
 It only ever **stocks the queue** — it never starts or stops playback, so a
 top-up while paused stays paused, and one that refills an empty queue after the
@@ -162,7 +195,7 @@ last track ended resumes on its own because the desired state was already
 
 ### Choosing the model
 
-**In the player.** The right column carries a **AI DJ 模型 / curator model**
+**In the player.** The right column carries a **AI DJ 模型 / DJ model**
 panel: a provider picker, a model picker, and three buttons.
 
 | Control | What it does |
@@ -201,21 +234,35 @@ control back to the patch.
 Both names must be ones the host actually serves. `provider` is a registered
 adapter route — read them from the `llm-pi-ai` entry's `config.providers` (or
 ask the agent for `ctx.llm.listProviders()`); `model` is any id that route
-accepts. The simplest safe choice is to **mirror the session's own model**:
-whatever `agent-default-model` uses is known to work.
+accepts.
+
+**Pin it, or follow the session.** With both fields unset the DJ inherits
+`agent-default-model` — the same selection the composer's model picker writes,
+so it is the model the agent loop itself runs on — which is why "use my session
+model" needs no configuration. Pinning `dj.provider`/`dj.model` curates on
+something else instead, and pinning is what makes the two choices independent:
+
+```yaml
+- id: agent-default-model        # the agent loop / session model
+  config: { provider: opencode-go, model: deepseek-v4.1-flash }
+- id: music
+  config:
+    dj:                          # the DJ's own model, when you want a different one
+      provider: opencode-go
+      model: minimax-m3
+```
 
 Three things worth knowing:
 
 - **`config` is replaced, not merged.** The loader assigns the whole object
   (`entry.ts`: `this.options.config = value`), so if you also want, say,
   `audioLevel`, keep every option in one block. Schema defaults fill the rest.
-- **Discovery runs when you pin nothing, and its choice is arbitrary.** With no
-  config the DJ asks the mounted LLM service for its routes
-  (`listProviders()`), takes the first, then takes that route's first catalogue
-  entry. On this machine `opencode-go`'s catalogue is
+- **Discovery is the last resort, and its choice is arbitrary.** Only when
+  neither a pin nor `agent-default-model` exists does the DJ ask the mounted LLM
+  service for its routes (`listProviders()`), take the first, then take that
+  route's first catalogue entry. On this machine `opencode-go`'s catalogue is
   `minimax-m3, deepseek-v4-flash, gpt-5.6-luna`, so discovery curates with
-  **MiniMax-M3** — not a recommendation, just the first row. Pinning both fields
-  is the only way to know which model is curating.
+  **MiniMax-M3** — not a recommendation, just the first row.
 - **Partial pins are honoured.** A `provider` alone keeps that route and picks
   its first catalogue model; a `model` alone keeps that model on the first
   route.
@@ -224,7 +271,7 @@ Confirm it took effect:
 
 | Where | What to look for |
 |---|---|
-| `/music/health` | `dj.model` is your pinned pair; `dj.modelSource` is `panel`, `config` or `discovered`; `dj.lastRoute` is the route that actually curated the last batch; `dj.modelError` is `null` once the tier works |
+| `/music/health` | `dj.model` is your pinned pair; `dj.modelSource` is `panel`, `config`, `agent-default` or `discovered`; `dj.resolvedFrom` is what the last plan actually used (`pin`, `agent-default`, `discovered`); `dj.sessionModel` is the deployment's own model; `dj.lastRoute` is the route that curated the last batch; `dj.sessionId` is the identity every call carries; `dj.modelError` is `null` once the tier works |
 | Player, DJ status line | **AI DJ** plus the route (heuristic runs read **AI DJ (heuristic)**, and a declined tier prints the reason) |
 | **测试 Test** in the player | Answers "does this route work?" in one click, without touching the queue |
 | `music_dj` tool result | `AI DJ is on (model via opencode-go/deepseek-v4.1-flash)` |
@@ -237,6 +284,29 @@ the provider's own failure (a `LlmError` code such as `NO_ADAPTER`,
 `MISSING_CREDENTIAL`, `AUTH`, `RATE_LIMIT`). The heuristic tier covers that batch
 either way.
 
+**If a provider says your usage does not follow its conventions**, the first
+thing to check is the route's identity, not the request: pi-ai adds
+`x-opencode-session` only for its own catalog routes `opencode-go` and
+`opencode`. A hand-declared route id that merely points at
+`https://opencode.ai/zen/go/v1` gets no wrapper and therefore no header, with
+nothing in the logs to say so — keep the catalog route name. For the same
+reason, do not set `x-opencode-session` in a profile's `headers`: the adapter
+lets a configured value win over the generated one, which would freeze a single
+id across every conversation. What remains after that is entitlement rather
+than convention — a plan that only permits its own client's traffic cannot be
+satisfied by a header, only by delegating transport to that client.
+
+To see the bytes rather than trust the reasoning, run the bundled probe, point a
+route's `baseURL` at it for one plan, and read what actually leaves the process:
+
+```powershell
+npm run probe:headers          # http://127.0.0.1:8787 -> https://opencode.ai
+```
+
+You should see `x-opencode-session` carrying the DJ's id, and
+`user-agent: deepseek-harness/<version> (+…)` — attribution that must never be
+replaced by a provider-shaped one. Take the `baseURL` back out afterwards.
+
 Editing `config` recomposes the running host, but **the plugin module itself is
 cached** — restart the harness for the new route to take effect. If the model
 tier fails for any reason (no adapter, bad credentials, unparseable reply,
@@ -263,6 +333,7 @@ add `config` to the inserted entry:
         dj:
           provider: opencode-go     # enables the model tier
           model: deepseek-v4.1-flash
+          sessionId: music-dj-mine  # optional: pin the provider-visible identity
 ```
 
 | Field | Default | Meaning |
@@ -271,7 +342,8 @@ add `config` to the inserted entry:
 | `dataDir` | `$DSH_HOME/music` | Where `session.json` (cookie, history, feedback, settings) lives. |
 | `audioLevel` | `exhigh` | Initial streaming quality, until the player's picker records a choice. One of the levels above; an unknown value falls back to `exhigh`. |
 | `requestTimeoutMs` | `15000` | Per-request deadline for NetEase calls. |
-| `dj.provider` / `dj.model` | unset | Model route for the DJ's model tier — see [Choosing the model](#choosing-the-model). Unset, the tier auto-discovers and falls back to heuristics on any failure. |
+| `dj.provider` / `dj.model` | unset | Model route for the DJ's model tier — see [Choosing the model](#choosing-the-model). Unset, the tier follows `agent-default-model` and only then falls back to discovery; any failure falls back to heuristics. |
+| `dj.sessionId` | minted, persisted | The identity every model call carries. Adapters map it onto the provider's per-conversation header. Pin it to control what a provider sees, or leave it unset and let the DJ mint one per install. |
 
 Player preferences (quality, DJ on/off, mood brief, batch size, extend
 threshold) are persisted in `session.json` and edited from the panel.
@@ -397,7 +469,7 @@ down first. A restart brings both halves back into agreement.
 
 ```powershell
 npm run check        # node --check on every module
-npm test             # 65 deterministic tests: pure, DJ, browser half
+npm test             # 76 deterministic tests: pure, DJ, browser half
 npm run test:live    # 23 integration tests against the live NetEase API
 npm run test:all     # both
 ```
@@ -414,16 +486,17 @@ network cases inside it.
 Or run one file directly:
 
 ```powershell
-node test/netease.test.mjs   # 16 pure: normalisation, quality ladder, cookies, player state
-node test/dj.test.mjs        # 31 AI DJ: model tier, failure reporting, picker listing, queue invariants
-node test/client.test.mjs    # 18 browser half, executed against a fake DOM
+node test/netease.test.mjs   # 18 pure: normalisation, quality ladder, cookies, player state
+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
 ```
 
-The DJ tests drive the model tier with a stub `ctx.llm.stream()` that emits the
-documented chunks, so the pinned-route happy path, both chunk spellings
-(`type`/`kind`), index filtering, prose-wrapped JSON, discovery, and every
-fallback are covered without a provider.
+The DJ tests drive `ctx.llm.stream()` with a stub that emits the documented
+chunks, and stub `ctx.agentDefaultModel` for route inheritance. So the
+pinned-route happy path, both chunk spellings (`type`/`kind`), index filtering,
+prose-wrapped JSON, the session identity every call must carry, inheritance from
+the session model, discovery, and every fallback are covered without a provider.
 
 The integration tests mount the plugin against stand-in `tools`/`webServer`
 services and drive the captured route over a real `node:http` server, so they
@@ -439,6 +512,16 @@ component ever rendered**, so playback cannot depend on the Music page being
 mounted. They also cover the seek handshake, failure reporting, disposal, and
 the contract handshake.
 
+The same fake DOM boots `lib/panel.html` itself, with an engine that reports
+`playback: true` — the shell document owns the audio element. That is the case
+where the page must fetch everything it renders on its own: lyrics used to be
+requested only from the local fallback transport's `applySource`, so with the
+engine playing the pane stayed empty for every track. Three tests hold the
+line: the rendered track is asked for, one fetch per track rather than one per
+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`
 adds the live one), deliberately **not** `node --test <dir>`: the directory form forks one child process per file, which
 is blocked in sandboxed environments.
@@ -462,6 +545,35 @@ is blocked in sandboxed environments.
 [qrcode-generator](https://github.com/kazuhikoarase/qrcode-generator) by
 Kazuhiko Arase, vendored so QR sign-in needs no network call or build step.
 
+### Releasing
+
+Releases are cut from GitHub and published by the `publish` workflow with **npm
+trusted publishing (OIDC)**. There is no `NPM_TOKEN` secret and no
+`NODE_AUTH_TOKEN` in the repository, and adding one would disable the OIDC
+exchange and break publishing.
+
+1. Bump `version` in `package.json`, commit, and push.
+2. Create a GitHub release whose tag is `v<version>` — `v0.1.2` for `0.1.2` —
+   pointing at that commit.
+
+The workflow runs `npm run check`, the deterministic suites, asserts the tag
+matches `package.json`, and publishes. A tag push alone publishes nothing: the
+trigger is `release: published`.
+
+Two timings look like failures and are not:
+
+- **A green job is not yet a live version.** The registry records a
+  `0.0.0-stage` placeholder first and reports the package as *being processed*;
+  the version becomes installable roughly a minute later. Inside that window the
+  packument still answers `404`, and publishing the same version from a second
+  place is refused with `409 Cannot publish over previously staged version`.
+- **Registry reads can lag the publish**, so an `npm view` run immediately
+  afterwards may still say `404`. Wait a minute, or read it from CI instead.
+
+Versions published this way carry a SLSA provenance attestation naming the
+workflow, tag, and commit — `npm view @doitian/dsh-music@<version> dist.attestations`.
+`0.1.0` predates the trusted publisher: it was published by hand and has none.
+
 ## Known limitations
 
 - **Anonymous sessions cannot play VIP tracks**; NetEase returns `url: null`.
@@ -474,10 +586,16 @@ Kazuhiko Arase, vendored so QR sign-in needs no network call or build step.
   fed to the DJ instead.
 - **`apiPrefix` must stay `music`** unless `BASE` in `lib/client.js` is changed
   to match.
-- **The DJ's model tier is covered against the stub stream contract, not a live
-  provider** — no adapter was configured where this was built, so request
-  building, the pinned route, both chunk spellings, index filtering and every
-  fallback are tested, but a real end-to-end model call has not been observed
-  here. The heuristic tier is what the live runs exercised.
+- **The DJ's model tier is covered against stub contracts, not a live
+  provider** — request building, the session identity, route resolution, both
+  chunk spellings, index filtering and every fallback are tested, but a real
+  end-to-end model call has not been observed here. The heuristic tier is what
+  the live runs exercised.
+- **The identity only becomes a header on the catalog routes that define one.**
+  pi-ai adds `x-opencode-session` for its own `opencode-go`/`opencode` routes. A
+  hand-declared route id pointing at the same endpoint gets no wrapper, so the
+  header is simply absent — keep the catalog route name, and never pin
+  `x-opencode-session` in a profile's `headers` (a configured value wins over
+  the generated one and freezes a single id for every conversation).
 - **Chromium autoplay policy** may block playback the agent starts before the
   user has interacted with the page; the panel then shows a *click to play* hint.

package/cordis.patch.yml

@@ -13,6 +13,20 @@
 #   requestTimeoutMs   NetEase request deadline (default 15000).
 #   dj.provider        model route for the AI DJ's model tier, e.g. opencode-go.
 #   dj.model           exact model id, e.g. deepseek-v4.1-flash.
+#   dj.sessionId       the identity every model call carries. A leaf call cannot
+#                      set headers, so this string is the only identity the DJ
+#                      can give a provider — and each adapter maps it onto that
+#                      provider's own per-conversation header (pi-ai emits
+#                      `x-opencode-session` for the `opencode-go` route). Left
+#                      unset, one is minted on first use and persisted in
+#                      session.json, so every plan and restart stays inside one
+#                      conversation.
+#
+# Route resolution, highest first: the player's picker -> `dj.provider`/`dj.model`
+# -> the deployment's own `agent-default-model` (the model the agent loop runs
+# on, which is why "use my session model" needs no configuration) -> discovery,
+# whose first row is arbitrary. The DJ is not an agent and starts none: each
+# plan is one stateless leaf call, so there is no session to rotate or dispose.
 #
 # Without `dj.provider`/`dj.model` the DJ still works: it falls back to scoring
 # similar songs, the daily recommendations and the charts by the listener's

package/lib/client.js

@@ -43,8 +43,34 @@ window.__ModuleLoader__.load({
     const API = `${BASE}/api`;
     /** Shared by the sidebar entry and the main panel it opens. */
     const PANEL_ID = 'music';
-    /** Visible label and collapsed-rail tooltip. */
-    const LABEL = '音乐 Music';
+
+    /**
+     * The locale namespace and its dictionary, registered with the host's
+     * `locale` service so the UI follows the Settings language. The service
+     * requires both shipped locales up front.
+     */
+    const NS = 'music';
+    const DICTIONARY = {
+      zh: {
+        panel: '音乐',
+        iframeTitle: '网易云音乐播放器',
+        unreachableTitle: '无法连接到音乐插件',
+        unreachableBody: '音乐插件路由没有响应。请确认插件已在当前 profile 中启用，然后',
+        unreachableLink: '直接打开播放器',
+        unreachableSuffix: '。',
+      },
+      en: {
+        panel: 'Music',
+        iframeTitle: 'NetEase Cloud Music player',
+        unreachableTitle: 'Music is not reachable',
+        unreachableBody:
+          'The music plugin route did not answer. Check that the plugin is enabled in this profile, then ',
+        unreachableLink: 'open the player directly',
+        unreachableSuffix: '.',
+      },
+    };
+    /** Bound in apply() once the dictionary is registered; English until then. */
+    let t = (key) => DICTIONARY.en[key] ?? key;
 
     /** How often the engine re-reads the host state; bounds control latency. */
     const POLL_MS = 500;
@@ -53,7 +79,7 @@ window.__ModuleLoader__.load({
     const IDLE_REPORT_MS = 5000;
 
     /** Services required before the slot registrations can be made. */
-    const inject = ['slots'];
+    const inject = ['slots', 'locale'];
 
     /** Absolute URL helper; the shell page and the panel share one origin. */
     function origin() {
@@ -357,13 +383,13 @@ window.__ModuleLoader__.load({
             opacity: 0.75,
           },
         },
-        h('div', { style: { fontWeight: 650, marginBottom: 6 } }, '音乐 Music is not reachable'),
+        h('div', { style: { fontWeight: 650, marginBottom: 6 } }, t('unreachableTitle')),
         h(
           'div',
           null,
-          'The music plugin route did not answer. Check that the plugin is enabled in this profile, then ',
-          h('a', { href: panelUrl(), target: '_blank', rel: 'noreferrer' }, 'open the player directly'),
-          '.',
+          t('unreachableBody'),
+          h('a', { href: panelUrl(), target: '_blank', rel: 'noreferrer' }, t('unreachableLink')),
+          t('unreachableSuffix'),
         ),
       );
     }
@@ -390,7 +416,7 @@ window.__ModuleLoader__.load({
 
       return h('iframe', {
         src: panelUrl(),
-        title: 'NetEase Cloud Music player',
+        title: t('iframeTitle'),
         allow: 'autoplay; clipboard-write; encrypted-media',
         style: {
           width: '100%',
@@ -425,13 +451,19 @@ window.__ModuleLoader__.load({
       );
     }
 
-    /** Register the sidebar entry and the page it opens. */
+    /**
+     * Register the sidebar entry and the page it opens.
+     *
+     * Both registrations carry `locale: NS` and resolve their text through
+     * `t` at render time, so the slot system re-renders them in place when
+     * the user switches the Harness language — no remount, no refresh.
+     */
     function registerUi(ctx) {
       ctx.slots.inject('main', () =>
-        ctx.slots.register({ name: 'main', key: PANEL_ID }, MusicPanel),
+        ctx.slots.register({ name: 'main', key: PANEL_ID, locale: NS }, MusicPanel),
       );
       ctx.slots.inject('sidebar.panellist', () =>
-        ctx.slots.register({ name: 'sidebar.panellist', id: PANEL_ID, order: 20, label: LABEL }, MusicIcon),
+        ctx.slots.register({ name: 'sidebar.panellist', id: PANEL_ID, order: 20, locale: NS, label: () => t('panel') }, MusicIcon),
       );
     }
 
@@ -447,6 +479,10 @@ window.__ModuleLoader__.load({
      * @returns disposer stopping playback and withdrawing both registrations.
      */
     async function apply(ctx) {
+      // The dictionary goes in before anything renders, and bound `t` reads
+      // the live snapshot, so a later language switch needs no rewiring.
+      const disposeLocale = ctx.locale.register(NS, DICTIONARY);
+      t = ctx.locale.bind(NS);
       const ui = ctx.inject(['slots'], () => registerUi(ctx));
       const engine = await createEngine();
       // The panel is same-origin, so it can nudge the engine after a command.
@@ -454,6 +490,7 @@ window.__ModuleLoader__.load({
       return () => {
         ui?.dispose?.();
         engine.dispose();
+        disposeLocale?.();
         if (window.__dshMusicEngine === engine) delete window.__dshMusicEngine;
       };
     }