@kidli1412/dsh-token-heatmap 0.4.2 → 0.5.0

package/README.md

@@ -36,11 +36,11 @@ GitHub 风格自然年热力图：覆盖所选自然年 1月–12月（`‹ 2026
 - ⚙️ **设置就在卡片上**：点标题行最右端的 **⚙**（`刷新 [⚙]`）弹出**悬浮设置面板** —— 位置在 ⚙ 正上方 8px、水平居中对齐、贴边留 12px，超出视口会自动钳制；点面板外的任意位置、按 **Esc**、或再点一次 ⚙ 都会收起。**插件不再往 DSH 设置（设置 → 插件 → 插件配置）里注册任何卡片**，所以那里看不到本插件。
 - **配色方案**：六个色板按钮，**点击即时生效**（不需要"保存"）；**默认视图**：年 / 月，决定新会话页面首次打开时显示哪个视图（当次会话手动切换只影响当前页面）。面板底部是阈值图例（悬停看各档范围）与一行说明。
 - 写入失败时面板底部会红字提示"保存失败，已回到服务端的值"（settings scope 复核后回滚乐观值）。
-- 配置经 `token-heatmap` settings namespace 持久化到 `<DSH_HOME>/settings.yaml`（0.1.1 及更早版本存在 `<DSH_HOME>/storages/token-heatmap-config.json` 的旧配置会在启动时自动迁移）。
+- 配置作为**本插件的 profile 配置**持久化：DSH 0.2.0 用插件导出的 `Config` schema 生成设置表单，表单以 **profile entry id**（`token-heatmap`）为键，值写进 profile patch（旧的 `<DSH_HOME>/settings.yaml` 段与 0.1.1 及更早的 `<DSH_HOME>/storages/token-heatmap-config.json` 都会在启动时**一次性迁移/抢救**回配置）。
 
 ## 安装 / Install
 
-需要 `web` profile 与 `pnpm`。DSH 兼容版本见下方「兼容性 / Compatibility」；运行于 `@deepseek-ai/dsh >= 0.1.2-alpha.4`（0.1.2 版本线）。
+需要 `web` profile 与 `pnpm`。DSH 兼容版本见下方「兼容性 / Compatibility」；运行于 `@deepseek-ai/dsh ^0.2.0-rc.2`（0.2.0 版本线；0.1.2 线请用 0.4.2）。
 
 从 npm 安装：
 
@@ -68,8 +68,8 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 工作原理 / How it works
 
-- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，**实时折叠会话事件**（监听官方 `session/event`，每个 `assistant/chunk`/`assistant/message` 的 `usage` 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 `collectUsage` 再做一次增量同步兜底，并枚举 **已归档（stored）会话**补齐历史——两种 `sessionPersistence` 接口都支持：0.1.2 线的 `listSnapshots()` + `readFrom()`，以及 0.1.3 起取代它们的 `list()` + `open()`/`handle.read()`。同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天；**fork（`isSeeded`）会话从它的继承切点开始折叠**——日志开头那批属于父会话的事件在父会话侧已折叠，跳过它们才不会把同一批 token 计两次；按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`。通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（配色 + 默认视图）由插件注册的 `token-heatmap` settings namespace 持有（settings.yaml），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一 namespace（0.1.x 的 `enabled` 开关已废弃，该字段只作为常量 `true` 回给旧客户端），0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
-- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅在 `session.blank`（新会话 hero 屏；旧宿主回退 `composerPhase === "blank"`）时渲染——卡片没有显示开关，hero 屏上始终显示。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。同一份数据由 `buildGrid()`（年，53 列 × 7 行）与 `buildMonthGrid()`（月，7 列 × 5–6 行，带日号）两个纯函数分别铺格，共用 `levelOf()` 的绝对阈值分档与 `palette` 配色；`‹ ›` 按钮按当前视图步进年或月，边界取"当前年/月"与"数据里最早的月"，年/月分段按钮紧跟在步进器后面，**⚙ 设置面板**在卡片底部展开（内嵌面板，动作：⚙ 切换 / × / Esc / 焦点移出）。**不注册 `settings.plugin.item`**（官方"插件配置"页签只渲染"Host 实际 serve 的 namespace ∩ 客户端已注册 key"的卡片，本插件不再占这个位置），只经 settings scope 读写 `token-heatmap` namespace（该 namespace 仍由服务端注册，是配置的校验与持久化管道）。
+- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，**实时折叠会话事件**（监听官方 `session/event`，每个 `assistant/chunk`/`assistant/message` 的 `usage` 事件即时写入缓存，不依赖 hero 屏挂载）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）；请求时 `collectUsage` 再做一次增量同步兜底，并枚举 **已归档（stored）会话**补齐历史——两种 `sessionPersistence` 接口都支持：0.1.2 线的 `listSnapshots()` + `readFrom()`，以及 0.1.3 起取代它们的 `list()` + `open()`/`handle.read()`。同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天；**fork（`isSeeded`）会话从它的继承切点开始折叠**——日志开头那批属于父会话的事件在父会话侧已折叠，跳过它们才不会把同一批 token 计两次；按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`。通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（配色 + 默认视图）由**导出的 `Config` schema** 持有（0.2.0 的设置模型：以 entry id `token-heatmap` 为键的表单，值写进 profile patch），`GET/POST /api/token-heatmap/config` 作为回环兼容 API 读写同一份配置（读经 `settings.describe()`，写经 `settings.update()`；0.1.x 的 `enabled` 开关已废弃，该字段只作为常量 `true` 回给旧客户端），0.1.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
+- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅在 `session.blank`（新会话 hero 屏；旧宿主回退 `composerPhase === "blank"`）时渲染——卡片没有显示开关，hero 屏上始终显示。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。同一份数据由 `buildGrid()`（年，53 列 × 7 行）与 `buildMonthGrid()`（月，7 列 × 5–6 行，带日号）两个纯函数分别铺格，共用 `levelOf()` 的绝对阈值分档与 `palette` 配色；`‹ ›` 按钮按当前视图步进年或月，边界取"当前年/月"与"数据里最早的月"，年/月分段按钮紧跟在步进器后面，**⚙ 设置面板**在卡片底部展开（内嵌面板，动作：⚙ 切换 / × / Esc / 焦点移出）。**不注册 `settings.plugin.item`**（官方"插件配置"页签只渲染"Host 实际 serve 的 namespace ∩ 客户端已注册 key"的卡片，本插件不再占这个位置），配置经 `ctx.configForms.get("token-heatmap")` 读写本插件配置（0.2.0 的设置模型，取代 0.1.x 的 settings scope）。
 - 语义与 `dsh-token-meter` 的 `tokenUsage` 投影一致（参考插件 [dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)，MIT）。
 
 ## 说明 / Notes
@@ -80,10 +80,17 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 兼容性 / Compatibility
 
-- **DSH**：manifest 通过 `dsh.compatibility.dshReleases` 将官方最新三个版本 `0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1` 逐项声明为 `compatible`（DSH STORE 的精确逐版本兼容证据；仅范围声明不会恢复上架）。插件使用的客户端注入（`dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`）与 Host 服务（`settings` namespace、`webServer` 精确路由）在这条版本线上保持稳定。
+- **DSH**：manifest 通过 `dsh.compatibility.dshReleases` 将当前版本线 `0.2.0-rc.2` 声明为 `compatible`（DSH STORE 的精确逐版本兼容证据；仅范围声明不会恢复上架）。插件使用的客户端注入（`dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`）、客户端服务（`slots` / `locale` / `configForms`）与 Host 服务（`webServer` 精确路由、`settings.describe` / `settings.update`、`sessions`、`sessionPersistence`）在 0.2.0 版本线上均已在真实安装中核对。
 - **Node**：`^22.19.0 || >=24.0.0`（与 DSH 一致）。
-- **宿主要求（dsh-market 显示）**：`engines.dsh: ^0.1.2-rc.1`，并将运行时依赖的 lockstep 宿主包声明为 `peerDependencies`（`dsh-host-webserver` / `dsh-session` / `dsh-session-persistence` / `dsh-settings` 与客户端模块 `dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`，均为 `^0.1.2-rc.1`）；插件市场会据此显示"宿主要求"并判断与当前 DSH 是否匹配。
-- **依赖**：`@deepseek-ai/dsh-settings` 自 0.1.3 起提升为 `^0.1.2-rc.1`、`@deepseek-ai/schemastery` 提升为 `^3.18.2`，与 DSH 0.1.2 版本线对齐。npm 的 prerelease 解析规则下 `^0.1.0-rc.7` 不会解析到 `0.1.2-rc.1`（只会装 `0.1.0-rc.8`），因此较低的范围会拉到与新版 DSH 不同 train 的 settings 副本。
+- **宿主要求（dsh-market 显示）**：`engines.dsh: ^0.2.0-rc.2`，并将运行时依赖的 lockstep 宿主包声明为 `peerDependencies`（`dsh-host-webserver` / `dsh-session` / `dsh-session-persistence` / `dsh-settings` 与客户端模块 `dsh-api-remotes` / `dsh-client-connection` / `dsh-client-locale` / `dsh-client-ui-conversation` / `dsh-client-ui-settings`，均为 `^0.2.0-rc.2`）；插件市场会据此显示"宿主要求"并判断与当前 DSH 是否匹配。这些包由 DSH 运行时提供、本插件**从不 import**，所以同时标为 `peerDependenciesMeta.optional`——npm/pnpm 不再把它们装进依赖树（0.2.0 起它们彼此还有 peer 关系，沿用旧的自动安装会直接解析冲突），而"宿主要求"的语义不受影响。
+- **依赖**：`@deepseek-ai/schemastery ^3.18.2`（唯一的真实依赖；`dsh-settings` 自 0.2.0 起不再需要作为 peer 之外的运行时依赖）。
+- **0.5.0（DSH 0.2.0 适配）**：DSH 0.2.0 换了三套契约，宿主兼容闸门会**直接拒绝挂载**声明不符的 bundle（现象：插件在市场里显示"不兼容"、`rows: []`、hero 屏上什么都没有）——
+  1. **宿主要求必须落在 0.2.0 线上**：闸门逐条比对 `peerDependencies` 里的 `@deepseek-ai/dsh*` 与运行时版本（`semver.satisfies(..., { includePrerelease: true })`），`^0.1.2-rc.1` 不满足 `0.2.0-rc.2`，因此本版把 `engines.dsh` 与 9 个宿主 peer 一起提到 `^0.2.0-rc.2`（并把宿主包标为 optional peer，见上）。
+  2. **设置模型重做**：0.1.x 的"插件自建 settings namespace + `settings.register(ns, schema)`"没了，`settings.get(ns)` 也没了。现在**插件导出的 `Config`（schemastery）就是设置表单**，以 **profile entry id**（bundle patch 里的 `id: token-heatmap`）为键；Host 侧读别人用 `settings.describe()`（`serveConfig()` 已改，否则配置端点会静默回默认值）、写自己用 `settings.update(ns, patch)`，浏览器端用 `ctx.configForms.get("token-heatmap")`（`getSnapshot` / `subscribe` / `set`），旧的 `ctx.settingsScope.bind({namespace})` 已从客户端消失。卡片 ⚙ 面板的 UI 与"点击即时生效"完全不变。
+  3. **弹层皮肤同步**：0.2.0 的原生 stat dialog 改用 `border-radius:var(--dsw-radius-lg)` 并加 `backdrop-filter:var(--dsw-menu-backdrop-filter)`，本插件的 ⚙ 悬浮面板跟着改（带 fallback，旧宿主仍渲染 12px 圆角）。
+  > 升级时会**自动抢救旧配置**：DSH 自己的 `settings.yaml` 导入按 entry id 进行，而当时本插件正因上面的 peer 不符被拒挂载，导入失败后值只留在 `~/.dsh/settings.yaml.imported` 里。本版 Host 在启动后（等 Loader settle）读一次该文档，若条目还没有用户值就把非默认的 `colorScheme` / `defaultView` 写进配置——一次性、只读、失败即跳过。（`enabled` 字段自 0.3.0 起已废弃，不参与抢救。）
+  > 另外提醒：0.2.0 给 `dsh web` 的每个请求加了**签名 cookie 鉴权**，插件的两个端点因此只有带 cookie 的同源页面能到达；用 node/curl 直接探端点拿到 401 是 DSH 的鉴权层，**不代表插件没挂载**。Host 侧的 loopback 精确路由 fence 保留为第二道防线。
+- **0.4.0（设置搬进卡片）**：不再注册官方 `settings.plugin.item` 插槽——设置页（设置 → 插件 → 插件配置）里不再有本插件的卡片，配色与默认视图改在卡片自己的 ⚙ 面板里改，**点击即时生效**（去掉了草稿/保存/放弃那套）。当时 Host 侧的 `settings.register("token-heatmap", schema)` 保留下来当 settings.yaml 的校验与持久化管道；**该注册在 0.5.0 已随 0.2.0 的设置模型一起移除**（导出的 `Config` 就是管道）。升级只影响设置入口位置，已有配置不动。
 - **0.1.4（DSH 0.1.2 适配）**：rc.1 起 live session 不再携带 `.events` 数组（改用 `session.seq` + `session.eventAt(seq)`，与官方 `dsh-token-meter` 相同），新会话判断从 `composerPhase === "blank"` 改为布尔 `session.blank`；`sessionPersistence` 的 stored 会话枚举在 0.1.3-alpha.2 被替换（`listSnapshots`/`readFrom` → `list()` + `open()`/`handle.read()`），两条接口见 0.1.6 条目。客户端注入模块列表同步为新架构模块（见上）。
 - **0.1.6（session/event 实时折叠 + stored 会话枚举修复）**：`apply()` 注册官方 `session/event` 监听器，每个 usage 事件即时折叠进缓存，解决 live 会话仅在 hero 屏挂载时才折叠而漏计同一日其他会话用量的问题（表现为当日总量偏小、历史天数丢失）；启动时一次性补折叠已存在的 live 会话（如 resumed 会话）。**stored 会话枚举修复**：0.1.3-alpha.2 起 `sessionPersistence` 移除了 `readFrom()` 与 `listSnapshots()`，只保留 `list()` + `open()`/`handle.read()`；旧实现只探测 `list`/`listSnapshots` 却无条件调用 `readFrom`，导致每个 stored 会话抛错并被吞成一条 warn —— 表现为热力图只剩进程内 live 的几天。现在两条接口都支持（`list()` 的 `revision` 同样用于跳过未变更的日志，增量仍按 `seq` 去重与连续性校验），stored 会话可完整补齐历史；两者都不可用时不再误判为"日志被截断"，而是保留已折叠天数并告警。token 口径与 `dsh-token-meter` 一致（input + output + cacheRead + cacheWrite，不含 reasoningTokens）。
 - **0.2.0（月视图 + 默认视图设置）**：新增 `buildMonthGrid()` 月视图（周一起、5–6 行、日号 + 当日 token 数）与 年/月 分段切换，`‹ ›` 按当前视图步进年或月；settings namespace 新增 `defaultView`（`"year" | "month"`）字段——与 `colorScheme` 的"只约束 shape"不同，**`defaultView` 是枚举校验**（未知视图没有可回退的渲染器），旧 Host 上该字段会被 schema 丢弃、旧客户端读到未知值时回退为"年"。0.1.x 的 `settings.yaml` 无需迁移（缺字段即取默认 `year`）。

package/lib/client.js

@@ -7,9 +7,10 @@
  * columns = weeks, rows = Mon..Sun, all seven weekday labels on the left) or a
  * single-month calendar, switchable from the header, plus today / this-month /
  * all-time totals and a ‹period› stepper. The card configures ITSELF through a
- * ⚙ panel (palette + default view) persisted in the `token-heatmap` settings
- * namespace (settings scope); it deliberately does not register into the
- * official `settings.plugin.item` seat (设置 → 插件 → 插件配置), so all of its
+ * ⚙ panel (palette + default view) persisted in this plugin's profile CONFIG —
+ * DSH 0.2.0 derives the form from the Host's exported `Config` and the card
+ * reads/writes it through `ctx.configForms.get("token-heatmap")`; there is no
+ * `settings.plugin.item` card and no settings scope any more, so all of its
  * settings live on the card.
  *
  * The card is shown ONLY on the new-session (hero) screen — gated on the
@@ -99,8 +100,10 @@ window.__ModuleLoader__.load({
 			// The settings panel mirrors DSH's own pill dialogs: portaled to
 			// document.body, position:fixed (so the card can never clip it),
 			// measure-then-place above the ⚙ and clamped to the viewport, with
-			// the shipped dialog surface + elevation tokens.
-			".thm_panel{position:fixed;z-index:1100;box-sizing:border-box;background:var(--dsw-specific-menu,#fff);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);width:400px;max-width:calc(100vw - 24px);box-shadow:var(--dsw-elevation-prominent,0 8px 32px rgba(0,0,0,.16));color:var(--dsw-alias-label-secondary);cursor:default;border:0;border-radius:12px;padding:16px;font-size:12px;line-height:18px;text-align:left;font-weight:400}",
+			// the shipped dialog surface + elevation tokens. DSH 0.2.0's stat
+			// dialog moved to `--dsw-radius-lg` and a backdrop filter, so the
+			// surface follows (the fallbacks keep it rendering on an older host).
+			".thm_panel{position:fixed;z-index:1100;box-sizing:border-box;background:var(--dsw-specific-menu,#fff);--dsw-elevation-stroke-color:var(--dsw-alias-border-l1);width:400px;max-width:calc(100vw - 24px);backdrop-filter:var(--dsw-menu-backdrop-filter);box-shadow:var(--dsw-elevation-prominent,0 8px 32px rgba(0,0,0,.16));color:var(--dsw-alias-label-secondary);cursor:default;border:0;border-radius:var(--dsw-radius-lg,12px);padding:16px;font-size:12px;line-height:18px;text-align:left;font-weight:400}",
 			".thm_panelHead{color:var(--dsw-alias-label-primary);justify-content:space-between;align-items:center;gap:16px;margin-bottom:8px;font-weight:500;display:flex}",
 			".thm_panelTitleLabel{align-items:center;gap:6px;display:inline-flex}",
 			".thm_panelTitleLabel svg{flex:none;width:14px;height:14px}",
@@ -406,13 +409,14 @@ window.__ModuleLoader__.load({
 			return VIEW_MODES.includes(view) ? view : CONFIG_DEFAULTS.defaultView;
 		}
 		/**
-		 * Reactive adapter over one bound settings scope: a
-		 * useSyncExternalStore-compatible store whose snapshot is
-		 * `{ status, colorScheme, defaultView }` derived from the scope.
-		 * `set(patch)` writes the touched fields through scope.set (async; the
-		 * scope fences revisions and reloads on failure), and the snapshot
-		 * only changes after the Host confirms. `reload()` re-reads from the
-		 * Host; `dispose()` removes the subscription.
+		 * Reactive adapter over one config form (`ctx.configForms.get(entryId)`):
+		 * a useSyncExternalStore-compatible store whose snapshot is
+		 * `{ status, colorScheme, defaultView }` derived from the form.
+		 * `set(patch)` writes the touched fields through `form.set(field, value)`
+		 * (async; the form fences revisions and reloads on failure), and the
+		 * snapshot only changes after the Host confirms. `dispose()` removes the
+		 * subscription. (The pre-0.2.0 `reload()` wrapper is gone: the shared
+		 * form re-reads on its own, and its API has no `load()`.)
 		 */
 		function createConfigStore(scope) {
 			const listeners = [];
@@ -454,7 +458,6 @@ window.__ModuleLoader__.load({
 						await scope.set("defaultView", sanitizeView(patch.defaultView));
 					}
 				},
-				reload: () => scope.load(),
 				dispose: () => unsubscribe()
 			};
 		}
@@ -1194,34 +1197,33 @@ window.__ModuleLoader__.load({
 
 		//#region plugin body
 		/**
-		 * Settings namespace the card reads/writes — must match the namespace
-		 * the Host registers (lib/index.js). Spelled here rather than imported:
-		 * a client package must not depend on a Host package.
+		 * Profile entry id this plugin's config form is keyed by. DSH 0.2.0
+		 * replaced the plugin-owned settings namespace with schema-derived plugin
+		 * CONFIG: the Host exports `Config`, the form is keyed by the profile
+		 * entry id — the `id` of the row our bundle patch inserts, which is what
+		 * the browser asks for here. Spelled as a literal rather than imported: a
+		 * client package must not depend on a Host package.
 		 */
 		const SETTINGS_NS = "token-heatmap";
 		/** Services required by the client plugin body. */
-		const inject = ["slots", "locale", "connection", "remote", "settingsScope"];
+		const inject = ["slots", "locale", "configForms"];
 
 		/**
 		 * Client plugin body: register the dictionaries and the input-dock entry
-		 * (the heatmap below the composer card on the new-session screen), backed
-		 * by the `token-heatmap` settings namespace through a bound settings
-		 * scope. The card configures itself through its own ⚙ panel, so this
-		 * plugin does NOT register into `settings.plugin.item` (the official
-		 * 设置 → 插件 → 插件配置 card seat) any more — the Host still serves the
-		 * namespace, it just has no configuration card to dispatch.
+		 * (the heatmap below the composer card on the new-session screen). The
+		 * card configures itself through its own ⚙ panel, which reads and writes
+		 * the plugin's config form (`ctx.configForms.get("token-heatmap")`) —
+		 * the shared form owns transport, revisions, and recovery.
 		 *
 		 * Slot-kind contract: `conversation.input.dock` is a LIST slot, so its
-		 * registration is keyed by `id` (a `settings.plugin.item` registration
-		 * would instead need `key`, the settings namespace the card edits).
+		 * registration is keyed by `id`.
 		 * @param ctx - client root context.
 		 */
 		function apply(ctx) {
-			// Bind the namespace scope on THIS plugin's fiber (settingsScope.bind
-			// registers the disposer itself); the scope auto-loads and refreshes
-			// on settings/document-updated and connection/reset. Requires the
-			// injected connection (transport) and remote (invalidation) services.
-			const scope = ctx.settingsScope.bind({ namespace: SETTINGS_NS });
+			// The shared form for our entry: `getSnapshot()`/`subscribe()` for
+			// reads, `set(field, value)` for writes. `createConfigStore` is
+			// duck-typed over exactly that surface, so the ⚙ panel is unchanged.
+			const scope = ctx.configForms.get(SETTINGS_NS);
 			configStore = createConfigStore(scope);
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "token-heatmap: dictionaries");
 			ctx.slots.inject("conversation.input.dock", () => ctx.slots.register({

package/lib/index.js

@@ -11,11 +11,13 @@
  * its own peer-socket loopback fence (the exact route bypasses the RPC trust
  * fence); Host is checked only as an additional defense.
  *
- * Display settings (enabled + colorScheme) are owned by the plugin's
- * `token-heatmap` settings namespace — the config card in
- * 设置 → 插件 → 插件配置 reads/writes it through the settings scope, and the
- * legacy `<DSH_HOME>/storages/token-heatmap-config.json` document is
- * migrated into the namespace once at startup.
+ * Display settings (colorScheme + defaultView) are owned by this plugin's
+ * profile CONFIG — DSH 0.2.0 derives the settings form from the exported
+ * `Config` schema, keys it by the profile entry id (`token-heatmap`, the id of
+ * the row our bundle patch inserts), and the browser edits it through
+ * `ctx.configForms.get("token-heatmap")`. The plugin's own ⚙ panel writes the
+ * same values; the legacy `<DSH_HOME>/storages/token-heatmap-config.json`
+ * document is migrated into it once at startup.
  *
  * Usage aggregation is INCREMENTAL: per-session fold state (day/model
  * buckets plus the last usage sample) is cached in memory and persisted to
@@ -33,6 +35,7 @@
  */
 
 import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { applyUsageDelta, createUsageState, mergeInto, renderUsage, zeroBuckets } from "./usage.js";
@@ -45,24 +48,17 @@ const name = "token-heatmap";
 /** Services required before this plugin activates. */
 const inject = ["webServer", "sessions", "sessionPersistence", "settings"];
 
-//#region settings namespace
+//#region plugin config
 /**
- * Settings namespace owned by this plugin. Registering it makes the Host
- * serve a `token-heatmap` section (resolved from schema defaults, then any
- * composition `base`, then the user settings.yaml layer), which is exactly
- * what the official 设置 → 插件 → 插件配置 tab dispatches on: it renders the
- * card registered into `settings.plugin.item` whose `key` matches a served
- * namespace. The card edits `enabled` + `colorScheme` through the settings
- * scope; the legacy `<DSH_HOME>/storages/token-heatmap-config.json` document
- * is migrated once at startup (see migrateLegacyConfig).
- * DSH 0.1.2 起 `@deepseek-ai/dsh-settings` 不再导出 settingsNamespace 帮助函数：
- * namespace 直接以字面量传入（register/get/update 内部仍按
- * /^[a-z][a-z0-9-]*$/ 校验）。
+ * Profile entry id this plugin's config form is keyed by: the `id` of the row
+ * the bundle patch inserts, which is also what the browser asks
+ * `ctx.configForms.get(...)` for. DSH 0.2.0 derives the form from the exported
+ * `Config` schema, so no registration call exists (nor does `settings.get`).
  */
 const SETTINGS_NAMESPACE = "token-heatmap";
 
 /**
- * Durable display preferences; also the wire envelope the browser scope
+ * Durable display preferences; also the wire envelope the browser form
  * validates against. Scheme membership is deliberately NOT enforced (a newer
  * client may know a palette the server does not — the client falls back to
  * green); only the same shape bounds parseConfig applies: a short, non-blank
@@ -72,10 +68,12 @@ const SETTINGS_NAMESPACE = "token-heatmap";
  * the hero screen, so the field is neither accepted nor served (an old
  * settings.yaml keeps its dead `enabled` key, and nothing reads it).
  */
-const TokenHeatmapSettingsSchema = z.object({
+const Config = z.object({
 	colorScheme: z.string().min(1).max(32).default("green"),
 	defaultView: z.union(VIEW_MODES.map((mode) => z.const(mode))).default("year")
 });
+/** @deprecated 0.1.x name; the schema IS the config now. Kept for old importers. */
+const TokenHeatmapSettingsSchema = Config;
 //#endregion
 
 const USAGE_PATH = "/api/token-heatmap/usage";
@@ -329,14 +327,127 @@ function configPath() {
 	return join(home, "storages", "token-heatmap-config.json");
 }
 
+/** DSH home resolution, mirroring `@deepseek-ai/dsh-home-paths` (no extra peer). */
+function dshHomeDirectory(env = process.env) {
+	const configured = env.DSH_HOME;
+	if (typeof configured === "string" && configured.trim() !== "") return configured.trim();
+	return join(homedir(), ".dsh");
+}
+
+/**
+ * One profile entry's descriptor from the settings service, or undefined when
+ * the service is absent or the entry is not live. DSH 0.2.0 dropped the old
+ * `settings.get(ns)` accessor — a plugin's settings ARE its profile entry
+ * config now — so reads go through the same `describe()` view the settings UI
+ * renders (its `value` is the resolved section, its `user` the raw user layer).
+ * @param ctx - plugin context.
+ * @param entryId - profile entry id (`token-heatmap`).
+ * @returns the descriptor, or undefined.
+ */
+function entryDescriptor(ctx, entryId) {
+	const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
+	if (settings === null || settings === void 0 || typeof settings.describe !== "function") return void 0;
+	try {
+		return settings.describe().find((row) => row.ns === entryId);
+	} catch {
+		return void 0;
+	}
+}
+
+/**
+ * One profile entry's resolved config section, read through the settings
+ * service.
+ * @param ctx - plugin context.
+ * @param entryId - profile entry id (`token-heatmap`).
+ * @returns the resolved section, or undefined when the entry is absent.
+ */
+function entryConfig(ctx, entryId) {
+	const value = entryDescriptor(ctx, entryId)?.value;
+	return value !== null && typeof value === "object" ? value : void 0;
+}
+
+/**
+ * Best-effort read of one scalar out of the pre-0.2.0 `settings.yaml` section
+ * for this entry. DSH's own importer moves those sections into the profile
+ * once, keyed by entry id — and skipped ours while the bundle was refused for
+ * incompatible peers, leaving the value only in the renamed document. This is
+ * a deliberately narrow scan (one top-level section, one scalar) rather than a
+ * YAML dependency: anything it cannot read is simply left for the user.
+ * @param text - contents of `settings.yaml` or `settings.yaml.imported`.
+ * @param section - top-level section name (`token-heatmap`).
+ * @param field - scalar key inside it.
+ * @returns the raw trimmed string value, or null.
+ */
+function legacySettingFromDocument(text, section, field) {
+	if (typeof text !== "string") return null;
+	const lines = text.split(/\r?\n/);
+	const inSection = /^[^\s#][^:]*:/;
+	let inside = false;
+	for (const line of lines) {
+		if (inSection.test(line)) {
+			inside = line.trim() === `${section}:` && !line.startsWith(" ");
+			continue;
+		}
+		if (!inside) continue;
+		const match = /^\s+([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line);
+		if (match === null || match[1] !== field) continue;
+		return match[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "");
+	}
+	return null;
+}
+
+/** Files the legacy value may still live in, newest name first. */
+const LEGACY_SETTINGS_FILES = ["settings.yaml.imported", "settings.yaml"];
+
+/**
+ * One-time rescue of display preferences from the removed settings document.
+ *
+ * DSH 0.2.0 imported the old `settings.yaml` sections per entry id, but this
+ * plugin was refused (incompatible peers) at that moment, so its section —
+ * `colorScheme` / `defaultView`, plus the dead `enabled` — only survives in
+ * the renamed document. Runs only when the entry has no user value yet, only
+ * for non-default fields, best effort, never blocking.
+ * @param ctx - plugin context carrying the settings service.
+ */
+async function rescueRemovedSettingsDocument(ctx) {
+	try {
+		const descriptor = entryDescriptor(ctx, SETTINGS_NAMESPACE);
+		if (descriptor === void 0) return;
+		const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
+		const user = descriptor.user;
+		if (user !== null && typeof user === "object" && (Object.hasOwn(user, "colorScheme") || Object.hasOwn(user, "defaultView"))) return;
+		const home = dshHomeDirectory();
+		let text = null;
+		for (const file of LEGACY_SETTINGS_FILES) {
+			try {
+				text = readFileSync(join(home, file), "utf8");
+			} catch {
+				continue;
+			}
+			if (text !== null) break;
+		}
+		if (text === null) return;
+		const patch = {};
+		const scheme = legacySettingFromDocument(text, SETTINGS_NAMESPACE, "colorScheme");
+		if (scheme !== null && scheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = scheme;
+		const view = legacySettingFromDocument(text, SETTINGS_NAMESPACE, "defaultView");
+		if (view !== null && VIEW_MODES.includes(view) && view !== DEFAULT_CONFIG.defaultView) patch.defaultView = view;
+		if (Object.keys(patch).length === 0) return;
+		await settings.update(SETTINGS_NAMESPACE, patch);
+		ctx.logger.info(`token-heatmap: carried ${JSON.stringify(patch)} over from the removed settings.yaml`);
+	} catch (error) {
+		ctx.logger.warn(`token-heatmap: legacy settings rescue skipped: ${String(error)}`);
+	}
+}
+
 /**
  * One-time migration from the legacy config document
- * (`<DSH_HOME>/storages/token-heatmap-config.json`) into the registered
- * settings namespace. Runs once per process, best-effort: when the user has
- * no settings.yaml section yet, non-default values are imported through the
- * settings write path; the legacy file is removed either way (the namespace
- * becomes the single source of truth). A corrupt legacy document is dropped,
- * never imported. Failures are logged and never fatal.
+ * (`<DSH_HOME>/storages/token-heatmap-config.json`) into the plugin config.
+ * Runs once per process, best-effort: when the user has no config value yet,
+ * non-default values are imported through the settings write path; the legacy
+ * file is removed either way (the config entry becomes the single source of
+ * truth). A corrupt legacy document is dropped, never imported. Failures are
+ * logged and never fatal.
  * @param ctx - plugin context carrying the settings service.
  */
 async function migrateLegacyConfig(ctx) {
@@ -355,15 +466,16 @@ async function migrateLegacyConfig(ctx) {
 			await rm(path, { force: true });
 			return;
 		}
-		const descriptor = ctx.settings.describe().find((entry) => entry.ns === SETTINGS_NAMESPACE);
+		const descriptor = entryDescriptor(ctx, SETTINGS_NAMESPACE);
+		const settings = typeof ctx.get === "function" ? ctx.get("settings") : ctx.settings;
 		const userExists = descriptor !== void 0 && descriptor.user !== void 0;
-		if (!userExists) {
+		if (!userExists && settings !== void 0 && typeof settings.update === "function") {
 			const patch = {};
 			// The legacy document's `enabled` switch died with 0.2.0: import only
 			// what the card still owns.
 			if (legacy.colorScheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = legacy.colorScheme;
 			if (legacy.defaultView !== DEFAULT_CONFIG.defaultView) patch.defaultView = legacy.defaultView;
-			if (Object.keys(patch).length > 0) await ctx.settings.update(SETTINGS_NAMESPACE, patch);
+			if (Object.keys(patch).length > 0) await settings.update(SETTINGS_NAMESPACE, patch);
 		}
 		await rm(path, { force: true });
 	} catch (error) {
@@ -372,13 +484,13 @@ async function migrateLegacyConfig(ctx) {
 }
 
 /**
- * Serve the resolved settings section (schema defaults + user layer).
+ * Serve the resolved config section (schema defaults + user layer).
  * `enabled` stays in the payload as a constant true: the legacy loopback
  * endpoint is a back-compat API, and a pre-0.2.0 client that reads it must not
  * lose the card over a switch this version no longer has.
  */
 function serveConfig(ctx) {
-	const section = ctx.settings.get(SETTINGS_NAMESPACE);
+	const section = entryConfig(ctx, SETTINGS_NAMESPACE);
 	const scheme = typeof section?.colorScheme === "string" && section.colorScheme.length > 0 ? section.colorScheme : DEFAULT_CONFIG.colorScheme;
 	const view = typeof section?.defaultView === "string" && VIEW_MODES.includes(section.defaultView) ? section.defaultView : DEFAULT_CONFIG.defaultView;
 	return { enabled: true, colorScheme: scheme, defaultView: view };
@@ -687,19 +799,22 @@ async function handleUsage(ctx, req, res) {
 }
 
 /**
- * Plugin body: register the usage and config routes, the settings namespace
- * that backs the plugin configuration card (设置 → 插件 → 插件配置), and the
- * one-time legacy-config migration.
+ * Plugin body: register the usage and config routes and run the two one-time
+ * legacy migrations. DSH 0.2.0 needs no namespace registration — the exported
+ * `Config` is the form — so nothing here touches the settings document beyond
+ * the rescues.
  * @param ctx - plugin context carrying webServer, sessions, sessionPersistence, and settings.
  */
 function apply(ctx) {
-	// The registration is fiber-bound: disposing this plugin removes the
-	// namespace and its observers. `settings` is a hard dependency (inject),
-	// so ctx.settings is available here unconditionally.
-	ctx.settings.register(SETTINGS_NAMESPACE, TokenHeatmapSettingsSchema);
 	// Best-effort, fire-and-forget: import the pre-0.1.2 config document into
-	// the namespace and drop the file (see migrateLegacyConfig).
+	// the config entry and drop the file (see migrateLegacyConfig), then rescue
+	// whatever the removed settings.yaml still holds. The rescue waits for the
+	// Loader to settle, exactly like DSH's own importer did, so the entry it
+	// inspects is the live one.
 	migrateLegacyConfig(ctx);
+	const loader = ctx.root?.loader;
+	const settled = typeof loader?.await === "function" ? Promise.resolve(loader.await()).catch(() => void 0) : Promise.resolve();
+	settled.then(() => rescueRemovedSettingsDocument(ctx)).catch(() => void 0);
 	// Real-time fold: listen to session/event and fold each usage event into
 	// the cache immediately, so live session usage is captured regardless of
 	// whether the hero screen is mounted (the client polls the usage endpoint
@@ -779,4 +894,18 @@ function apply(ctx) {
 	}), "token-heatmap: config route");
 }
 
-export { apply, inject, name, CONFIG_PATH, USAGE_PATH, SETTINGS_NAMESPACE, TokenHeatmapSettingsSchema, migrateLegacyConfig };
+export {
+	apply,
+	inject,
+	name,
+	Config,
+	CONFIG_PATH,
+	USAGE_PATH,
+	SETTINGS_NAMESPACE,
+	TokenHeatmapSettingsSchema,
+	migrateLegacyConfig,
+	entryConfig,
+	dshHomeDirectory,
+	legacySettingFromDocument,
+	rescueRemovedSettingsDocument
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kidli1412/dsh-token-heatmap",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with switchable year/month views and six color schemes. The card configures itself through a floating ⚙ panel (palette + default view) — no DSH settings card — and shows today / this-month / all-time totals.",
   "type": "module",
   "main": "lib/index.js",
@@ -20,15 +20,26 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1"
+    "@deepseek-ai/dsh-api-remotes": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": { "optional": true },
+    "@deepseek-ai/dsh-client-connection": { "optional": true },
+    "@deepseek-ai/dsh-client-locale": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-conversation": { "optional": true },
+    "@deepseek-ai/dsh-client-ui-settings": { "optional": true },
+    "@deepseek-ai/dsh-host-webserver": { "optional": true },
+    "@deepseek-ai/dsh-session": { "optional": true },
+    "@deepseek-ai/dsh-session-persistence": { "optional": true },
+    "@deepseek-ai/dsh-settings": { "optional": true }
   },
   "dsh": {
     "bundle": {
@@ -46,9 +57,7 @@
     },
     "compatibility": {
       "dshReleases": {
-        "0.1.2-alpha.4": "compatible",
-        "0.1.2-alpha.5": "compatible",
-        "0.1.2-rc.1": "compatible"
+        "0.2.0-rc.2": "compatible"
       }
     }
   },
@@ -60,7 +69,7 @@
   "license": "MIT",
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": "^0.1.2-rc.1"
+    "dsh": "^0.2.0-rc.2"
   },
   "repository": {
     "type": "git",