@kidli1412/dsh-token-heatmap 0.1.0 → 0.1.2

package/README.md

@@ -17,7 +17,7 @@ A DeepSeek Harness web plugin: a GitHub-style daily token-usage heatmap of the *
 - ⚙️ **插件配置卡**（设置 → 插件 → 插件配置，随官方"插件配置"页签渲染）：
   - **显示热力图** 开关：关闭后新会话页面不再显示热力图卡片。
   - **配色方案**：绿色 / 蓝色 / 橙色 / 红色 / 紫色 / 青色，六个色板按钮即时预览。
-  - 修改后需点"保存"（显示"未保存"徽标提示），"放弃修改"可丢弃草稿；配置经回环端点持久化到 `<DSH_HOME>/storages/token-heatmap-config.json`。
+  - 修改后需点"保存"（显示"未保存"徽标提示），"放弃修改"可丢弃草稿；配置经 `token-heatmap` settings namespace 持久化到 `<DSH_HOME>/settings.yaml`（0.1.1 及更早版本存在 `<DSH_HOME>/storages/token-heatmap-config.json` 的旧配置会在启动时自动迁移）。
 
 ## 安装 / Install
 
@@ -49,8 +49,8 @@ dsh plugin --profile web remove @kidli1412/dsh-token-heatmap
 
 ## 工作原理 / How it works
 
-- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，增量折叠全部会话事件日志中的 token 用量样本（`assistant/chunk` 的 `usage` 与 `assistant/message` 的 `usage`；同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天），按天、按模型聚合，缓存到 `<DSH_HOME>/storages/token-heatmap-cache.json`，并通过回环受限端点 `GET /api/token-heatmap/usage` 提供；显示配置（开关 + 配色）经 `GET/POST /api/token-heatmap/config` 读写，持久化到 `<DSH_HOME>/storages/token-heatmap-config.json`。
-- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅当 `session.composerPhase === "blank"`（新会话 hero 屏）且配置开关开启时渲染。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。配置卡注册进官方 `settings.plugin.item` 插槽（设置 → 插件 → 插件配置页签）；官方 Host 只向 Web 客户端暴露白名单内的设置命名空间，因此本插件不依赖 `settingsScope`，而是直接读写自己的回环配置端点。
+- **服务端**（`lib/index.js` + `lib/usage.js` + `lib/config.js`）：作为 profile bundle 挂载，增量折叠全部会话事件日志中的 token 用量样本（`assistant/chunk` 的 `usage` 与 `assistant/message` 的 `usage`；同 `(turn, step)` 的重复样本按"替换"语义处理，归属后一天），按天、按模型聚合，缓存到 `<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.1 及更早的 `token-heatmap-config.json` 文档在启动时一次性迁移。
+- **客户端**（`lib/client.js`）：手写 `__ModuleLoader__` bundle，注册进会话 `conversation.input.dock` 列表插槽，仅当 `session.composerPhase === "blank"`（新会话 hero 屏）且配置开关开启时渲染。框架真正的"卡片下方"插槽 `conversation.composer.dock` 在 hero 屏被 `!hero` 门控禁用，因此本插件利用 `input.dock` 容器（flex 列）的 CSS `order` 把自己排到输入卡片**之后**。配置卡注册进官方 `settings.plugin.item` 插槽（设置 → 插件 → 插件配置页签），经 settings scope 读写 `token-heatmap` namespace（该 namespace 由本插件在服务端注册，官方页签只渲染"Host 实际 serve 的 namespace ∩ 已注册 key"的卡片）。
 - 语义与 `dsh-token-meter` 的 `tokenUsage` 投影一致（参考插件 [dsh-usage-stats](https://github.com/Ychris12138/dsh-usage-stats)，MIT）。
 
 ## 说明 / Notes

package/lib/client.js

@@ -8,7 +8,8 @@
  * totals and a ‹year› year selector next to the stats. It also registers a
  * settings card into the official `settings.plugin.item` seat
  * (设置 → 插件 → 插件配置) with a display switch and a green/blue palette
- * choice, persisted through the server half's loopback config endpoint.
+ * choice, persisted through the `token-heatmap` settings namespace (settings
+ * scope).
  *
  * The card is shown ONLY on the new-session (hero) screen — gated on
  * `session.composerPhase === "blank"` — and is positioned visually BELOW the
@@ -327,25 +328,88 @@ window.__ModuleLoader__.load({
 			if (payload === null || typeof payload !== "object") throw new Error("unexpected response");
 			return payload;
 		}
+		//#endregion
 
-		async function postJson(path, body) {
-			const response = await fetch(path, {
-				method: "POST",
-				headers: { "content-type": "application/json" },
-				body: JSON.stringify(body)
-			});
-			if (!response.ok) throw new Error(`HTTP ${response.status}`);
-			const payload = await response.json();
-			if (payload === null || typeof payload !== "object") throw new Error("unexpected response");
-			return payload;
+		//#region config store (settings-scope backed)
+		/**
+		 * Display preferences (enabled + colorScheme), persisted through the
+		 * Host `token-heatmap` settings namespace (settings.yaml) via the bound
+		 * settings scope — NOT the legacy loopback config endpoint. The
+		 * heatmap and the settings card read the store through
+		 * useSyncExternalStore; while the scope is loading or unavailable the
+		 * store falls back to the defaults (enabled / green), so the UI never
+		 * blocks on the settings transport.
+		 */
+		const CONFIG_DEFAULTS = { enabled: true, colorScheme: "green" };
+		/** Coerce a scheme to a non-blank string, else the default. */
+		function sanitizeScheme(value) {
+			if (typeof value !== "string") return CONFIG_DEFAULTS.colorScheme;
+			const scheme = value.trim();
+			return scheme.length > 0 && scheme.length <= 32 ? scheme : CONFIG_DEFAULTS.colorScheme;
 		}
+		/**
+		 * Reactive adapter over one bound settings scope: a
+		 * useSyncExternalStore-compatible store whose snapshot is
+		 * `{ status, enabled, colorScheme }` 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.
+		 */
+		function createConfigStore(scope) {
+			const listeners = [];
+			let snapshot = { status: "loading", ...CONFIG_DEFAULTS };
+			const compute = () => {
+				const s = scope.getSnapshot();
+				if (s === void 0 || s === null || s.status !== "ready" || s.value === void 0 || s.value === null) {
+					return { status: s === void 0 || s === null ? "unavailable" : s.status, ...CONFIG_DEFAULTS };
+				}
+				const v = s.value;
+				return {
+					status: s.status,
+					enabled: v.enabled !== false,
+					colorScheme: sanitizeScheme(v.colorScheme)
+				};
+			};
+			const notify = () => {
+				snapshot = compute();
+				for (const listener of listeners.slice()) {
+					try { listener(); } catch { /* contained: never break the fan-out */ }
+				}
+			};
+			const unsubscribe = scope.subscribe(notify);
+			snapshot = compute();
+			return {
+				getSnapshot: () => snapshot,
+				subscribe: (listener) => {
+					listeners.push(listener);
+					return () => {
+						const index = listeners.indexOf(listener);
+						if (index !== -1) listeners.splice(index, 1);
+					};
+				},
+				set: async (patch) => {
+					if (Object.hasOwn(patch, "enabled")) {
+						await scope.set("enabled", patch.enabled === true);
+					}
+					if (Object.hasOwn(patch, "colorScheme")) {
+						await scope.set("colorScheme", sanitizeScheme(patch.colorScheme));
+					}
+				},
+				reload: () => scope.load(),
+				dispose: () => unsubscribe()
+			};
+		}
+		/** Module-level store, created in apply() once the settings scope is bound. */
+		let configStore = null;
+		//#endregion
 
 		/**
 		 * Cell palettes by scheme, level 0 (empty) → 4 (peak). Green is the
 		 * classic GitHub scale; the others are ColorBrewer single-hue ramps
 		 * (blue/orange/red/purple) plus a custom teal. The active scheme comes
-		 * from the settings card (配置 → 配色方案), persisted by the server
-		 * half's config endpoint.
+		 * from the settings card (配置 → 配色方案), persisted through the
+		 * `token-heatmap` settings namespace.
 		 */
 		const COLOR_SCHEMES = {
 			green: ["rgba(128,128,128,0.15)", "#9be9a8", "#40c463", "#30a14e", "#216e39"],
@@ -440,7 +504,6 @@ window.__ModuleLoader__.load({
 			const dict = t !== void 0 ? t : (key) => zh[key] ?? key;
 			const translate = (key, params) => interpolate(dict(key), params);
 			const [data, setData] = react.useState(null);
-			const [config, setConfig] = react.useState(null);
 			const [error, setError] = react.useState(null);
 			const [loading, setLoading] = react.useState(false);
 			const [year, setYear] = react.useState(() => new Date().getFullYear());
@@ -450,13 +513,9 @@ window.__ModuleLoader__.load({
 				const id = loaderRef.current.start();
 				setLoading(true);
 				try {
-					const [payload, cfg] = await Promise.all([
-						fetchJson("/api/token-heatmap/usage"),
-						fetchJson("/api/token-heatmap/config")
-					]);
+					const payload = await fetchJson("/api/token-heatmap/usage");
 					if (loaderRef.current.isCurrent(id)) {
 						setData(payload);
-						setConfig(cfg);
 						setError(null);
 					}
 				} catch (err) {
@@ -478,12 +537,17 @@ window.__ModuleLoader__.load({
 				};
 			}, [load]);
 
+			// Display preferences come from the settings scope (auto-refreshed
+			// on settings/document-updated and connection/reset), not from a
+			// config fetch — the loopback endpoint remains as a back-compat API.
+			const config = react.useSyncExternalStore(configStore.subscribe, configStore.getSnapshot);
+
 			// New-session hero only: a blank session whose composer is still in
 			// the guidance phase. Conversed sessions hide the card.
 			if (session === void 0 || session === null || input === void 0 || input === null) return null;
 			if (session.composerPhase !== "blank") return null;
 			// Master switch from the settings card (设置 → 插件 → 插件配置).
-			if (config !== null && config.enabled === false) return null;
+			if (config.enabled === false) return null;
 
 			const now = Date.now();
 			// Year-selector bounds: the current year at most (no future usage),
@@ -509,7 +573,7 @@ window.__ModuleLoader__.load({
 			const grid = buildGrid(dayMap, now, year);
 			const levelLegend = uiDict().levelLegend;
 			// Palette from the settings card; unknown schemes fall back to green.
-			const palette = COLOR_SCHEMES[config?.colorScheme] ?? COLOR_SCHEMES.green;
+			const palette = COLOR_SCHEMES[config.colorScheme] ?? COLOR_SCHEMES.green;
 
 			const stats = [
 				{ label: dict("today"), value: todayTokens },
@@ -663,11 +727,12 @@ window.__ModuleLoader__.load({
 		 * The plugin settings card, rendered inside the official
 		 * 设置 → 插件 → 插件配置 tab (the `settings.plugin.item` seat).
 		 *
-		 * The Host only exposes its own allowlisted settings namespaces to the
-		 * Web client, so this card does NOT bind a settingsScope; instead it
-		 * reads/writes the plugin's own loopback config endpoint and stages a
-		 * draft until the user saves, mirroring the official card chrome
-		 * (disclosure header, unsaved badge, discard/save footer).
+		 * The card edits the `token-heatmap` settings namespace through the
+		 * bound settings scope (the tab only dispatches it while the Host
+		 * serves that namespace) and stages a draft until the user saves,
+		 * mirroring the official card chrome (disclosure header, unsaved
+		 * badge, discard/save footer). The legacy loopback config endpoint
+		 * remains as a back-compat API, but the card no longer uses it.
 		 * @param props - `t` bound by the slot runtime locale seat.
 		 */
 		function TokenHeatmapSettingsCard({ t }) {
@@ -677,21 +742,15 @@ window.__ModuleLoader__.load({
 			const [draft, setDraft] = react.useState(null);
 			const [saving, setSaving] = react.useState(false);
 			const [saveFailed, setSaveFailed] = react.useState(false);
-			const [loadFailed, setLoadFailed] = react.useState(false);
-			const load = react.useCallback(async () => {
-				try {
-					const payload = await fetchJson("/api/token-heatmap/config");
-					setLoaded(payload);
-					setDraft(payload);
-					setLoadFailed(false);
-					setSaveFailed(false);
-				} catch {
-					setLoadFailed(true);
-				}
-			}, []);
+			const config = react.useSyncExternalStore(configStore.subscribe, configStore.getSnapshot);
+			// Seed the staged form from the confirmed scope snapshot once (a
+			// later scope change is the card's own save confirmation; external
+			// edits land in loaded via the explicit sync in save()).
 			react.useEffect(() => {
-				load();
-			}, [load]);
+				if (config.status !== "ready" || loaded !== null) return;
+				setLoaded({ enabled: config.enabled, colorScheme: config.colorScheme });
+				setDraft({ enabled: config.enabled, colorScheme: config.colorScheme });
+			}, [config, loaded]);
 
 			const dirty = loaded !== null && draft !== null && (draft.enabled !== loaded.enabled || draft.colorScheme !== loaded.colorScheme);
 			const save = react.useCallback(async () => {
@@ -699,9 +758,14 @@ window.__ModuleLoader__.load({
 				setSaving(true);
 				setSaveFailed(false);
 				try {
-					const payload = await postJson("/api/token-heatmap/config", draft);
-					setLoaded(payload);
-					setDraft(payload);
+					await configStore.set({ enabled: draft.enabled, colorScheme: draft.colorScheme });
+					// The scope confirms the write and refreshes its snapshot
+					// synchronously before settling; sync the staged form.
+					const confirmed = configStore.getSnapshot();
+					if (confirmed.status === "ready") {
+						setLoaded({ enabled: confirmed.enabled, colorScheme: confirmed.colorScheme });
+						setDraft({ enabled: confirmed.enabled, colorScheme: confirmed.colorScheme });
+					}
 				} catch {
 					setSaveFailed(true);
 				} finally {
@@ -721,7 +785,7 @@ window.__ModuleLoader__.load({
 			const title = dict("settingsTitle");
 
 			let bodyContent;
-			if (loadFailed) {
+			if (config.status === "unavailable") {
 				bodyContent = react_jsx_runtime.jsxs("p", {
 					className: S.settingsError,
 					children: [
@@ -730,7 +794,7 @@ window.__ModuleLoader__.load({
 						react_jsx_runtime.jsx("button", {
 							type: "button",
 							className: S.settingsRetry,
-							onClick: load,
+							onClick: () => configStore.reload(),
 							children: dict("settingsRetry")
 						})
 					]
@@ -871,14 +935,38 @@ window.__ModuleLoader__.load({
 		//#endregion
 
 		//#region plugin body
+		/**
+		 * Settings namespace this plugin's card edits — 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.
+		 */
+		const SETTINGS_NS = "token-heatmap";
 		/** Services required by the client plugin body. */
-		const inject = ["slots", "locale"];
+		const inject = ["slots", "locale", "connection", "remote", "settingsScope"];
 
 		/**
-		 * Client plugin body: register the dictionaries and the dock entry.
+		 * Client plugin body: register the dictionaries, the input-dock entry
+		 * (heatmap below the composer card on the new-session screen) and the
+		 * plugin settings card (设置 → 插件 → 插件配置), all backed by the
+		 * `token-heatmap` settings namespace through a bound settings scope.
+		 *
+		 * Slot-kind contract: `conversation.input.dock` is a LIST slot, so its
+		 * registration is keyed by `id`; `settings.plugin.item` is a KEYED slot,
+		 * so its registration must carry `key` (the settings namespace the card
+		 * edits) — registering with `id` instead throws
+		 * `keyed slot "settings.plugin.item" requires options.key` and fails
+		 * the whole plugin load. The card is only dispatched by the official
+		 * 插件配置 tab when the Host actually SERVES that namespace, which is
+		 * why this plugin registers it on the Host side too.
 		 * @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 });
+			configStore = createConfigStore(scope);
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "token-heatmap: dictionaries");
 			ctx.slots.inject("conversation.input.dock", () => ctx.slots.register({
 				name: "conversation.input.dock",
@@ -888,7 +976,7 @@ window.__ModuleLoader__.load({
 			}, TokenHeatmap));
 			ctx.slots.inject("settings.plugin.item", () => ctx.slots.register({
 				name: "settings.plugin.item",
-				id: "token-heatmap",
+				key: SETTINGS_NS,
 				order: 30,
 				locale: NS
 			}, TokenHeatmapSettingsCard));
@@ -903,6 +991,7 @@ window.__ModuleLoader__.load({
 		exports.levelOf = levelOf;
 		exports.CELL_COLORS = CELL_COLORS;
 		exports.COLOR_SCHEMES = COLOR_SCHEMES;
+		exports.createConfigStore = createConfigStore;
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -11,6 +11,12 @@
  * 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.
+ *
  * Usage aggregation is INCREMENTAL: per-session fold state (day/model
  * buckets plus the last usage sample) is cached in memory and persisted to
  * `<DSH_HOME>/storages/token-heatmap-cache.json`. On each request only the
@@ -28,15 +34,43 @@
 
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { applyUsageDelta, createUsageState, mergeInto, renderUsage, zeroBuckets } from "./usage.js";
 import { DEFAULT_CONFIG, parseConfig } from "./config.js";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
 
 /** Stable Cordis plugin name. */
 const name = "token-heatmap";
 
 /** Services required before this plugin activates. */
-const inject = ["webServer", "sessions", "sessionPersistence"];
+const inject = ["webServer", "sessions", "sessionPersistence", "settings"];
+
+//#region settings namespace
+/**
+ * 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).
+ */
+const SETTINGS_NAMESPACE = settingsNamespace("token-heatmap");
+
+/**
+ * Durable display preferences; also the wire envelope the browser scope
+ * 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
+ * string.
+ */
+const TokenHeatmapSettingsSchema = z.object({
+	enabled: z.boolean().default(true),
+	colorScheme: z.string().min(1).max(32).default("green")
+});
+//#endregion
 
 const USAGE_PATH = "/api/token-heatmap/usage";
 const CONFIG_PATH = "/api/token-heatmap/config";
@@ -273,51 +307,64 @@ function withLock(run) {
 }
 //#endregion
 
-//#region config store
-/** Config file location under the dsh home. */
+//#region config route + legacy migration
+/** Legacy config file location under the dsh home (pre-0.1.2 storage). */
 function configPath() {
 	const home = process.env.DSH_HOME ?? join(homedir(), ".dsh");
 	return join(home, "storages", "token-heatmap-config.json");
 }
 
-let loadedConfig = null;
-let configLoadPromise = null;
-
-/** Read the config document once per process; absence or corruption degrades to defaults. */
-async function readConfigFile() {
-	if (loadedConfig !== null) return loadedConfig;
-	configLoadPromise ??= (async () => {
+/**
+ * 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.
+ * @param ctx - plugin context carrying the settings service.
+ */
+async function migrateLegacyConfig(ctx) {
+	try {
+		const path = configPath();
+		let rawText;
 		try {
-			const raw = await readFile(configPath(), "utf8");
-			return parseConfig(JSON.parse(raw));
+			rawText = await readFile(path, "utf8");
 		} catch {
-			return { ...DEFAULT_CONFIG };
+			return; // no legacy document
 		}
-	})();
-	loadedConfig = await configLoadPromise;
-	return loadedConfig;
-}
-
-/** Persist the config atomically (temp + rename); failures are logged, never fatal. */
-async function writeConfigFile(ctx, config) {
-	try {
-		const path = configPath();
-		await mkdir(dirname(path), { recursive: true });
-		const tmp = `${path}.tmp`;
-		await writeFile(tmp, JSON.stringify({ version: 1, ...config }, null, 2), "utf8");
-		await rename(tmp, path);
-		loadedConfig = config;
+		let legacy;
+		try {
+			legacy = parseConfig(JSON.parse(rawText));
+		} catch {
+			await rm(path, { force: true });
+			return;
+		}
+		const descriptor = ctx.settings.describe().find((entry) => entry.ns === SETTINGS_NAMESPACE);
+		const userExists = descriptor !== void 0 && descriptor.user !== void 0;
+		if (!userExists) {
+			const patch = {};
+			if (legacy.enabled !== DEFAULT_CONFIG.enabled) patch.enabled = legacy.enabled;
+			if (legacy.colorScheme !== DEFAULT_CONFIG.colorScheme) patch.colorScheme = legacy.colorScheme;
+			if (Object.keys(patch).length > 0) await ctx.settings.update(SETTINGS_NAMESPACE, patch);
+		}
+		await rm(path, { force: true });
 	} catch (error) {
-		ctx.logger.warn(`token-heatmap: saving config failed: ${String(error)}`);
-		throw error;
+		ctx.logger.warn(`token-heatmap: migrating legacy config failed: ${String(error)}`);
 	}
 }
 
+/** Serve the resolved settings section (schema defaults + user layer). */
+function serveConfig(ctx) {
+	const section = ctx.settings.get(SETTINGS_NAMESPACE);
+	return { enabled: section?.enabled !== false, colorScheme: typeof section?.colorScheme === "string" && section.colorScheme.length > 0 ? section.colorScheme : DEFAULT_CONFIG.colorScheme };
+}
+
 async function handleConfig(ctx, req, res) {
 	if (rejectForeignConfigCaller(req, res)) return;
 	try {
 		if (req.method === "GET") {
-			json(res, 200, { ok: true, ...(await readConfigFile()) });
+			json(res, 200, { ok: true, ...serveConfig(ctx) });
 			return;
 		}
 		let raw;
@@ -327,9 +374,12 @@ async function handleConfig(ctx, req, res) {
 			json(res, 400, { ok: false, error: "bad-json", message: "request body must be a JSON object" });
 			return;
 		}
+		// parseConfig coerces the write the same way the legacy file path did
+		// (boolean check, scheme trimmed and shape-bounded, unknown schemes kept
+		// verbatim); the settings schema then validates the canonical shape.
 		const config = parseConfig(raw);
-		await writeConfigFile(ctx, config);
-		json(res, 200, { ok: true, ...config });
+		await ctx.settings.update(SETTINGS_NAMESPACE, config);
+		json(res, 200, { ok: true, ...serveConfig(ctx) });
 	} catch (error) {
 		ctx.logger.warn(`token-heatmap: config ${req.method} failed: ${String(error)}`);
 		json(res, 500, { ok: false, error: "internal", message: error instanceof Error ? error.message : String(error) });
@@ -455,10 +505,19 @@ async function handleUsage(ctx, req, res) {
 }
 
 /**
- * Plugin body: register the usage and config routes.
- * @param ctx - plugin context carrying webServer, sessions, and sessionPersistence.
+ * Plugin body: register the usage and config routes, the settings namespace
+ * that backs the plugin configuration card (设置 → 插件 → 插件配置), and the
+ * one-time legacy-config migration.
+ * @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).
+	migrateLegacyConfig(ctx);
 	ctx.effect(() => ctx.webServer.register({
 		kind: "exact",
 		path: USAGE_PATH,
@@ -471,4 +530,4 @@ function apply(ctx) {
 	}), "token-heatmap: config route");
 }
 
-export { apply, inject, name, CONFIG_PATH, USAGE_PATH };
+export { apply, inject, name, CONFIG_PATH, USAGE_PATH, SETTINGS_NAMESPACE, TokenHeatmapSettingsSchema, migrateLegacyConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kidli1412/dsh-token-heatmap",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "DSH web plugin: GitHub-style daily token-usage heatmap on the new-session screen with a selectable calendar-year view, green/blue color schemes and a display switch (设置 → 插件 → 插件配置), plus today / this-month / all-time totals.",
   "type": "module",
   "main": "lib/index.js",
@@ -16,6 +16,10 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -31,7 +35,7 @@
   },
   "scripts": {
     "check": "node --check lib/usage.js && node --check lib/config.js && node --check lib/index.js && node --check lib/client.js",
-    "test": "node scripts/smoke.mjs",
+    "test": "node scripts/smoke.mjs && node scripts/settings-smoke.mjs",
     "prepublishOnly": "npm run check && npm test"
   },
   "license": "MIT",