@dsh-plus/web-shell-sw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agguy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/client.js

@@ -0,0 +1,89 @@
+window.__ModuleLoader__.load({
+	id: "@dsh-plus/web-shell-sw",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region src/decision.ts
+		/**
+		* 决定浏览器半启动动作。
+		* @param config - 注入的配置行（缺席 = 插件未装配，零行为）。
+		* @param env - 运行环境（安全上下文且支持 serviceWorker 才可操作）。
+		*/
+		function decideClientAction(config, env) {
+			if (config === void 0) return "skip";
+			if (!env.isSecureContext || !env.hasServiceWorker) return "skip";
+			return config.enabled === true ? "register" : "cleanup";
+		}
+		//#endregion
+		//#region src/ns.ts
+		/** index-inject `kind:'global'` 注入的配置对象键。 */
+		const SW_GLOBAL_KEY = "__DSH_PLUS_WEB_SHELL_SW__";
+		/** sw.js 精确路由（注册与更新检查都打这里）。 */
+		const SW_SCRIPT_PATH = "/dsh-plus/shell-sw.js";
+		//#endregion
+		//#region src/client.ts
+		const name = "dsh-plus-web-shell-sw";
+		/** 收窄注入的 globalThis 值（形状不符一律视为缺席）。 */
+		function readConfig() {
+			const value = Reflect.get(globalThis, SW_GLOBAL_KEY);
+			if (typeof value !== "object" || value === null) return void 0;
+			return value;
+		}
+		/** 注册（幂等；失败仅告警——SW 缺席不影响页面任何功能）。 */
+		function registerSw() {
+			navigator.serviceWorker.register(SW_SCRIPT_PATH, { scope: "/" }).then(() => console.debug("[web-shell-sw] SW registered"), (error) => console.warn("[web-shell-sw] SW 注册失败（页面功能不受影响）", error));
+		}
+		/** 该注册是否属于本插件（三态 worker 任一匹配即可；scriptURL 在 worker 上）。 */
+		function isOurRegistration(registration) {
+			return [
+				registration.active,
+				registration.waiting,
+				registration.installing
+			].some((worker) => worker?.scriptURL.endsWith(SW_SCRIPT_PATH) === true);
+		}
+		/** 禁用清理：注销本插件的 SW 注册 + 删除本插件前缀的全部缓存。 */
+		function cleanupSw() {
+			const run = async () => {
+				try {
+					const registrations = await navigator.serviceWorker.getRegistrations();
+					for (const registration of registrations) if (isOurRegistration(registration)) await registration.unregister();
+					const keys = await caches.keys();
+					for (const key of keys) if (key.startsWith("dsh-shell-")) await caches.delete(key);
+					console.info("[web-shell-sw] 已注销 SW 并清理缓存（恢复原生网络行为）");
+				} catch (error) {
+					console.warn("[web-shell-sw] 禁用清理失败（下次加载会重试）", error);
+				}
+			};
+			run();
+		}
+		function apply(ctx) {
+			const action = decideClientAction(readConfig(), {
+				isSecureContext: window.isSecureContext,
+				hasServiceWorker: "serviceWorker" in navigator
+			});
+			if (action === "skip") return;
+			const run = () => {
+				if (action === "register") registerSw();
+				else cleanupSw();
+			};
+			let timer;
+			let disposed = false;
+			const start = () => {
+				if (disposed) return;
+				timer = window.setTimeout(run, 0);
+			};
+			if (document.readyState === "complete") start();
+			else window.addEventListener("load", start, { once: true });
+			ctx.effect(() => () => {
+				disposed = true;
+				if (timer !== void 0) window.clearTimeout(timer);
+				window.removeEventListener("load", start);
+			}, "web-shell-sw: cancel pending register/cleanup");
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/lib/index.d.ts

@@ -0,0 +1,37 @@
+import { UnwrapVolatile } from "@dsh-plus/shared";
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  enabled: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  enabled: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+type WebShellSwConfigFields = Schemastery.TypeT<typeof Config>;
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+type WebShellSwConfig = UnwrapVolatile<WebShellSwConfigFields>;
+//#endregion
+//#region src/ns.d.ts
+/**
+ * settings 命名空间 + 路由/缓存/全局键常量（纯常量，零依赖）。
+ * node 半（路由服务、注入行）与浏览器半（注册/注销、清理）共享同一来源，
+ * 避免两侧字面量漂移。
+ * @module @dsh-plus/web-shell-sw/ns
+ */
+declare const SETTINGS_NS = "dsh-plus-web-shell-sw";
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-plus-web-shell-sw";
+/**
+ * 装配路由与配置注入。配置行恒推（含 enabled=false——禁用需要浏览器半
+ * 执行注销，「行缺席」会使其无法区分禁用与未安装）；路由恒注册（禁用时
+ * 无人注册新 SW，已注册的由配置行驱动注销，无需路由参与）。
+ * @param ctx - 宿主上下文（webServer 可选）。
+ * @param config - 活动字段形态的行级 config（测试可传平面值）。
+ */
+declare function apply(ctx: Context, config: WebShellSwConfig | WebShellSwConfigFields): void;
+/** 供测试断言 inject 形态：本插件不声明硬依赖。 */
+declare const inject: readonly [];
+//#endregion
+export { Config, SETTINGS_NS, type WebShellSwConfig, apply, inject, name };

package/lib/index.js

@@ -0,0 +1,236 @@
+import { unwrapVolatile } from "@dsh-plus/shared";
+import z from "@deepseek-ai/schemastery";
+//#region src/ns.ts
+/**
+* settings 命名空间 + 路由/缓存/全局键常量（纯常量，零依赖）。
+* node 半（路由服务、注入行）与浏览器半（注册/注销、清理）共享同一来源，
+* 避免两侧字面量漂移。
+* @module @dsh-plus/web-shell-sw/ns
+*/
+const SETTINGS_NS = "dsh-plus-web-shell-sw";
+/** index-inject `kind:'global'` 注入的配置对象键。 */
+const SW_GLOBAL_KEY = "__DSH_PLUS_WEB_SHELL_SW__";
+/** sw.js 精确路由（注册与更新检查都打这里）。 */
+const SW_SCRIPT_PATH = "/dsh-plus/shell-sw.js";
+/**
+* Cache Storage 缓存名（同时是版本号）。
+* SW 脚本逻辑变更时手动 +1：activate 阶段删除前缀相同、名字不同的旧缓存。
+*/
+const SW_CACHE_NAME = "dsh-shell-v1";
+/** 缓存名前缀（禁用清理与版本升级都按它扫全量）。 */
+const SW_CACHE_PREFIX = "dsh-shell-";
+//#endregion
+//#region src/decision.ts
+/**
+* 决定一个 fetch 事件的处置（自包含纯函数，会被 toString 内嵌进 sw.js）。
+* @param method - HTTP 方法（大写）。
+* @param pathname - 已剥查询串的路径。
+* @param hasSearch - URL 是否带查询串（token 交换 `/?token=` 必须原生直通）。
+* @param hasRange - 请求是否带 Range 头（分段请求不走整包缓存）。
+*/
+function decideFetchAction(method, pathname, hasSearch, hasRange) {
+	if (method !== "GET") return "passthrough";
+	if (hasRange) return "passthrough";
+	if (pathname === "/" || pathname === "/index.html") return hasSearch ? "passthrough" : "network-first-shell";
+	if (pathname === "/plugins/events") return "passthrough";
+	if (pathname.startsWith("/assets/")) return "cache-first";
+	if (pathname.startsWith("/plugins/")) return "cache-first";
+	return "passthrough";
+}
+//#endregion
+//#region src/sw-script.ts
+/**
+* sw.js 脚本生成：把安全决策（decision.ts 自包含纯函数）与缓存策略
+* 渲染成一份独立的 Service Worker 脚本，由 node 半的精确路由对外服务。
+*
+* 设计要点（全部保守取向，宁可少缓存不可错缓存）：
+* - 不 skipWaiting、不 clients.claim：新版本等所有标签页关闭后才接管，
+*   绝不在会话中途换实现；首次注册只从下一次导航开始接管。
+* - passthrough 一大类（RPC、SSE、token 交换、跨源、Range、非 GET）
+*   不调 respondWith = 浏览器原生行为，零干预。
+* - 只有 status 200、type basic、且 cache-control 不含 no-store/no-cache
+*   的响应才入库——token 页（no-store）与代理侧 no-store 的 index 天然
+*   免疫，认证内容永不落 Cache Storage。
+* - 入库前剥离 content-encoding/content-length/transfer-encoding/vary：
+*   fetch() 暴露的 body 已解码，复制编码头会造成「解码头 + 原始体」错配
+*   （经典 SW 缓存坑）；存 identity 体，下次命中由 SW 直接原样返回。
+* - 缓存名带版本（ns.ts 的 SW_CACHE_NAME），activate 清理同前缀旧版本；
+*   源码逻辑变更时手动 +1 即可全量换血。
+*
+* 安全边界：`decideFetchAction` 无闭包依赖，toString() 内嵌后行为与
+* node 侧单测完全一致（tests/sw-script.test.ts 同时断言编译与内嵌等价）。
+* @module @dsh-plus/web-shell-sw/sw-script
+*/
+/**
+* 生成完整的 sw.js 脚本文本（纯函数，同配置恒等输出）。
+* @returns 可直接作为 application/javascript 响应体的脚本源码。
+*/
+function buildServiceWorkerScript() {
+	return `'use strict';
+const CACHE_NAME = ${JSON.stringify(SW_CACHE_NAME)};
+const CACHE_PREFIX = ${JSON.stringify(SW_CACHE_PREFIX)};
+const decideFetch = ${decideFetchAction.toString()};
+
+self.addEventListener('install', function () {
+  // 不 skipWaiting：新版本等待所有标签页关闭后接管，避免会话中途换实现。
+});
+
+self.addEventListener('activate', function (event) {
+  event.waitUntil(
+    caches.keys().then(function (keys) {
+      return Promise.all(
+        keys
+          .filter(function (key) { return key.indexOf(CACHE_PREFIX) === 0 && key !== CACHE_NAME; })
+          .map(function (key) { return caches.delete(key); })
+      );
+    })
+  );
+});
+
+self.addEventListener('fetch', function (event) {
+  const request = event.request;
+  let url;
+  try {
+    url = new URL(request.url);
+  } catch (error) {
+    return;
+  }
+  if (url.origin !== self.location.origin) return;
+  const action = decideFetch(
+    request.method,
+    url.pathname,
+    url.search !== '',
+    request.headers.has('range')
+  );
+  if (action === 'passthrough') return;
+  event.respondWith(
+    action === 'cache-first' ? cacheFirst(request) : shellNetworkFirst(request)
+  );
+});
+
+/** 剥离编码相关头后再入库：fetch 的 body 已解码，保留编码头会造成解码错配。 */
+function normalizeForCache(response) {
+  const headers = new Headers(response.headers);
+  ['content-encoding', 'content-length', 'transfer-encoding', 'vary'].forEach(function (name) {
+    headers.delete(name);
+  });
+  return response.arrayBuffer().then(function (body) {
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: headers });
+  });
+}
+
+/** 仅 200/basic/未标 no-store 且未标 no-cache 的响应可入库。 */
+function isStorable(response) {
+  if (response.status !== 200 || response.type !== 'basic') return false;
+  const cacheControl = (response.headers.get('cache-control') || '').toLowerCase();
+  return cacheControl.indexOf('no-store') === -1 && cacheControl.indexOf('no-cache') === -1;
+}
+
+function putNormalized(cache, request, response) {
+  return normalizeForCache(response).then(
+    function (stored) { return cache.put(request, stored); },
+    function (error) { console.warn('[web-shell-sw] cache.put failed', error); }
+  );
+}
+
+/** 内容寻址资源：命中即回；未命中回源，可存则存（存失败不影响本次响应）。 */
+function cacheFirst(request) {
+  return caches.open(CACHE_NAME).then(function (cache) {
+    return cache.match(request).then(function (hit) {
+      if (hit !== undefined) return hit;
+      return fetch(request).then(function (response) {
+        if (isStorable(response)) putNormalized(cache, request, response.clone());
+        return response;
+      });
+    });
+  });
+}
+
+/** index：网络优先（在线恒用最新外壳）；仅网络失败时才用缓存兜底，无缓存则原生失败。 */
+function shellNetworkFirst(request) {
+  return caches.open(CACHE_NAME).then(function (cache) {
+    return fetch(request).then(
+      function (response) {
+        if (isStorable(response)) putNormalized(cache, request, response.clone());
+        return response;
+      },
+      function (error) {
+        return cache.match(request).then(function (hit) {
+          if (hit !== undefined) return hit;
+          throw error;
+        });
+      }
+    );
+  });
+}
+`;
+}
+//#endregion
+//#region src/route.ts
+/**
+* 精确路由 handler（webserver.register kind:'exact'）。
+* @param req - 入站请求。
+* @param res - 出站响应（本 handler 拥有完整生命周期）。
+*/
+function serveServiceWorker(req, res) {
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		res.writeHead(405, {
+			"content-type": "text/plain; charset=utf-8",
+			allow: "GET, HEAD"
+		});
+		res.end("method not allowed");
+		return;
+	}
+	const body = buildServiceWorkerScript();
+	res.writeHead(200, {
+		"content-type": "text/javascript; charset=utf-8",
+		"cache-control": "no-cache",
+		"service-worker-allowed": "/",
+		"content-length": String(Buffer.byteLength(body))
+	});
+	res.end(body);
+}
+//#endregion
+//#region src/config.ts
+/**
+* 插件配置（schemastery）：可调参数一律外部化，不在逻辑里硬编码。
+*
+* 与仓库既有约定一致：Config 由 cordis 行级 config 解析，部署方可在
+* profile 的 cordis.patch.yml 覆盖；同时经 settings namespace 暴露到
+* $DSH_HOME/settings.yaml 用户层，修改热生效（无需 /reload）。
+* @module @dsh-plus/web-shell-sw/config
+*/
+const Config = z.object({ enabled: z.boolean().description("总开关（false = 浏览器半注销已注册的 Service Worker 并清空本插件缓存，恢复原生网络行为）").default(true).volatile() });
+//#endregion
+//#region src/index.ts
+const name = "dsh-plus-web-shell-sw";
+/**
+* 装配路由与配置注入。配置行恒推（含 enabled=false——禁用需要浏览器半
+* 执行注销，「行缺席」会使其无法区分禁用与未安装）；路由恒注册（禁用时
+* 无人注册新 SW，已注册的由配置行驱动注销，无需路由参与）。
+* @param ctx - 宿主上下文（webServer 可选）。
+* @param config - 活动字段形态的行级 config（测试可传平面值）。
+*/
+function apply(ctx, config) {
+	const logger = ctx.logger("web-shell-sw");
+	const current = () => unwrapVolatile(config);
+	ctx.inject(["webServer"], (webCtx) => {
+		webCtx.effect(() => webCtx.on("webserver/index-inject", (table) => {
+			table.push({
+				kind: "global",
+				name: SW_GLOBAL_KEY,
+				value: { enabled: current().enabled }
+			});
+		}), "web-shell-sw: index injection");
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "exact",
+			path: SW_SCRIPT_PATH,
+			handler: serveServiceWorker
+		}), "web-shell-sw: sw.js route");
+		logger.info(`installed (script route ${SW_SCRIPT_PATH})`);
+	});
+}
+/** 供测试断言 inject 形态：本插件不声明硬依赖。 */
+const inject = [];
+//#endregion
+export { Config, SETTINGS_NS, apply, inject, name };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dsh-plus/web-shell-sw",
+  "version": "0.1.0",
+  "description": "dsh-plus ui plugin: 外壳 Service Worker——内容寻址静态资源 cache-first、index network-first 离线兜底；绝不触碰 RPC/SSE/网关路由，token 页（no-store）永不入缓存，settings 一键注销",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dsh": {
+    "client": {
+      "inject": [],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@dsh-plus/shared": "0.1.24"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.1",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A-G-guy/dsh-plus.git",
+    "directory": "packages/web-shell-sw"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
+}

package/src/client.ts

@@ -0,0 +1,106 @@
+/**
+ * 浏览器半：Service Worker 的注册与注销（load 后执行，不与首屏抢带宽）。
+ *
+ * 启动链路：plugin apply → window load（已过则下一个宏任务）→
+ * decideClientAction 裁决：
+ * - register：幂等注册 `/dsh-plus/shell-sw.js`（scope `/`，由 node 半路由的
+ *   Service-Worker-Allowed 头授权）；新 SW 不 skipWaiting，本页不受影响，
+ *   从下一次导航开始接管。
+ * - cleanup（settings 禁用）：注销 scriptURL 匹配的注册 + 删除本插件
+ *   前缀的全部缓存——一键恢复原生网络行为。
+ * - skip：无配置行（插件缺席）或非安全上下文/无 SW 支持（裸 http 局域网
+ *   直连）——零行为，其余插件不受影响。
+ *
+ * 所有异步失败仅带上下文 warn/debug，绝不抛入 boot 链路。ctx.effect 兜底
+ * 移除 load 监听与未触发的定时器（已注册的 SW 不随 HMR 注销——它是部署级
+ * 状态，不是会话级状态）。
+ * 构建产物须为 window.__ModuleLoader__.load({id, factory}) 形式
+ * （包装见 tsdown.config.ts 的 banner/footer）。
+ * @module @dsh-plus/web-shell-sw/client
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { decideClientAction } from './decision.ts'
+import { SW_CACHE_PREFIX, SW_GLOBAL_KEY, SW_SCRIPT_PATH } from './ns.ts'
+
+export const name = 'dsh-plus-web-shell-sw'
+
+/** 注入的配置行形状（node 半保证 JSON 可序列化）。 */
+interface SwGlobal {
+  readonly enabled?: boolean
+}
+
+/** 收窄注入的 globalThis 值（形状不符一律视为缺席）。 */
+function readConfig(): SwGlobal | undefined {
+  const value: unknown = Reflect.get(globalThis, SW_GLOBAL_KEY)
+  if (typeof value !== 'object' || value === null) return undefined
+  return value as SwGlobal
+}
+
+/** 注册（幂等；失败仅告警——SW 缺席不影响页面任何功能）。 */
+function registerSw(): void {
+  navigator.serviceWorker.register(SW_SCRIPT_PATH, { scope: '/' }).then(
+    () => console.debug('[web-shell-sw] SW registered'),
+    (error: unknown) => console.warn('[web-shell-sw] SW 注册失败（页面功能不受影响）', error),
+  )
+}
+
+/** 该注册是否属于本插件（三态 worker 任一匹配即可；scriptURL 在 worker 上）。 */
+function isOurRegistration(registration: ServiceWorkerRegistration): boolean {
+  return [registration.active, registration.waiting, registration.installing].some(
+    (worker) => worker?.scriptURL.endsWith(SW_SCRIPT_PATH) === true,
+  )
+}
+
+/** 禁用清理：注销本插件的 SW 注册 + 删除本插件前缀的全部缓存。 */
+function cleanupSw(): void {
+  const run = async (): Promise<void> => {
+    try {
+      const registrations = await navigator.serviceWorker.getRegistrations()
+      for (const registration of registrations) {
+        if (isOurRegistration(registration)) await registration.unregister()
+      }
+      const keys = await caches.keys()
+      for (const key of keys) {
+        if (key.startsWith(SW_CACHE_PREFIX)) await caches.delete(key)
+      }
+      console.info('[web-shell-sw] 已注销 SW 并清理缓存（恢复原生网络行为）')
+    } catch (error) {
+      console.warn('[web-shell-sw] 禁用清理失败（下次加载会重试）', error)
+    }
+  }
+  void run()
+}
+
+export function apply(ctx: Context): void {
+  const config = readConfig()
+  const action = decideClientAction(config, {
+    isSecureContext: window.isSecureContext,
+    hasServiceWorker: 'serviceWorker' in navigator,
+  })
+  if (action === 'skip') return
+
+  const run = (): void => {
+    if (action === 'register') registerSw()
+    else cleanupSw()
+  }
+
+  // load 后下一个宏任务执行：此时首屏资源已全部就绪，注册/注销零竞争。
+  let timer: number | undefined
+  let disposed = false
+  const start = (): void => {
+    if (disposed) return
+    timer = window.setTimeout(run, 0)
+  }
+  if (document.readyState === 'complete') start()
+  else window.addEventListener('load', start, { once: true })
+
+  ctx.effect(
+    () => () => {
+      disposed = true
+      if (timer !== undefined) window.clearTimeout(timer)
+      window.removeEventListener('load', start)
+    },
+    'web-shell-sw: cancel pending register/cleanup',
+  )
+}

package/src/config.ts

@@ -0,0 +1,27 @@
+/**
+ * 插件配置（schemastery）：可调参数一律外部化，不在逻辑里硬编码。
+ *
+ * 与仓库既有约定一致：Config 由 cordis 行级 config 解析，部署方可在
+ * profile 的 cordis.patch.yml 覆盖；同时经 settings namespace 暴露到
+ * $DSH_HOME/settings.yaml 用户层，修改热生效（无需 /reload）。
+ * @module @dsh-plus/web-shell-sw/config
+ */
+import z from '@deepseek-ai/schemastery'
+import type { UnwrapVolatile } from '@dsh-plus/shared'
+
+// 0.1.7：`.volatile()` 使条目进入 settings describe 视图（卡片可读写）并让
+// loader 以活动引用原位提交热更新。
+export const Config = z.object({
+  enabled: z
+    .boolean()
+    .description(
+      '总开关（false = 浏览器半注销已注册的 Service Worker 并清空本插件缓存，恢复原生网络行为）',
+    )
+    .default(true)
+    .volatile(),
+})
+
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+export type WebShellSwConfigFields = Schemastery.TypeT<typeof Config>
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+export type WebShellSwConfig = UnwrapVolatile<WebShellSwConfigFields>

package/src/decision.ts

@@ -0,0 +1,64 @@
+/**
+ * Service Worker 路由决策纯函数（node 与浏览器两侧共用同一份实现）：
+ *
+ * - `decideFetchAction`：SW fetch 事件该不该 `respondWith`、用哪种策略。
+ *   安全底线——只有同源 GET、非 Range、内容寻址静态资源与无查询串的
+ *   index 才进缓存路径；SSE（/plugins/events）、RPC、网关路由、token 交换
+ *   （`/?token=` 带查询串）一律 passthrough（不调 respondWith = 浏览器
+ *   原生行为，零干预）。
+ * - `decideClientAction`：浏览器半启动时该注册、该注销还是跳过。
+ *
+ * 该模块无闭包依赖，函数体自包含——`decideFetchAction.toString()` 会被
+ * 内嵌进生成的 sw.js（见 sw-script.ts），测试同时验证内嵌前后行为一致。
+ * @module @dsh-plus/web-shell-sw/decision
+ */
+
+/** 单个 fetch 事件的处置。 */
+export type SwFetchAction =
+  | 'passthrough' /** 不 respondWith：浏览器原生处理（RPC/SSE/token/跨格式一律走此道） */
+  | 'cache-first' /** 内容寻址静态资源：缓存命中即回，未命中回源并按策略入库 */
+  | 'network-first-shell' /** 无查询串的 index：网络优先，仅网络失败时才用缓存兜底 */
+
+/**
+ * 决定一个 fetch 事件的处置（自包含纯函数，会被 toString 内嵌进 sw.js）。
+ * @param method - HTTP 方法（大写）。
+ * @param pathname - 已剥查询串的路径。
+ * @param hasSearch - URL 是否带查询串（token 交换 `/?token=` 必须原生直通）。
+ * @param hasRange - 请求是否带 Range 头（分段请求不走整包缓存）。
+ */
+export function decideFetchAction(
+  method: string,
+  pathname: string,
+  hasSearch: boolean,
+  hasRange: boolean,
+): SwFetchAction {
+  if (method !== 'GET') return 'passthrough'
+  if (hasRange) return 'passthrough'
+  if (pathname === '/' || pathname === '/index.html') {
+    return hasSearch ? 'passthrough' : 'network-first-shell'
+  }
+  if (pathname === '/plugins/events') return 'passthrough'
+  if (pathname.startsWith('/assets/')) return 'cache-first'
+  if (pathname.startsWith('/plugins/')) return 'cache-first'
+  return 'passthrough'
+}
+
+/** 浏览器半启动处置。 */
+export type ClientAction =
+  | 'register' /** 注册（幂等；无注册则新建，有则触发更新检查） */
+  | 'cleanup' /** 注销已注册 SW 并清空本插件缓存（禁用恢复原生行为） */
+  | 'skip' /** 无配置行（插件缺席）或环境不支持（非安全上下文/无 SW） */
+
+/**
+ * 决定浏览器半启动动作。
+ * @param config - 注入的配置行（缺席 = 插件未装配，零行为）。
+ * @param env - 运行环境（安全上下文且支持 serviceWorker 才可操作）。
+ */
+export function decideClientAction(
+  config: { readonly enabled?: boolean } | undefined,
+  env: { readonly isSecureContext: boolean; readonly hasServiceWorker: boolean },
+): ClientAction {
+  if (config === undefined) return 'skip'
+  if (!env.isSecureContext || !env.hasServiceWorker) return 'skip'
+  return config.enabled === true ? 'register' : 'cleanup'
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * dsh 插件：外壳 Service Worker（web-shell-sw）。
+ *
+ * 问题：弱网/远程访问下每次冷启动都要重新拉 ~1.4MB 外壳 + ~4MB 插件组合包
+ * （HTTP 缓存头已由 web-cache-headers 与官方 immutable 覆盖，但浏览器缓存
+ * 可被淘汰、且 index 本身不可缓存）；断网时完全打不开。Service Worker 提供
+ * 一层由本插件完全掌控的 Cache Storage：内容寻址资源 cache-first、index
+ * network-first 离线兜底。
+ *
+ * 三半协作，均为纯增量：
+ * - node 半：每次渲染 index 推 `kind:'global'` 配置行（含 enabled=false——
+ *   浏览器半据此注销，禁用即恢复原生行为）；精确路由 GET/HEAD
+ *   `/dsh-plus/shell-sw.js` 服务生成的 SW 脚本（Service-Worker-Allowed: /
+ *   使 scope 覆盖全站）。
+ * - 浏览器半（src/client.ts）：load 后经 requestIdleCallback 注册（不与
+ *   首屏抢带宽）；禁用时注销 SW 并清空本插件缓存。
+ * - SW 脚本（src/sw-script.ts 生成）：见该模块注释——不 skipWaiting、
+ *   不碰 RPC/SSE/token、no-store 永不入库。
+ *
+ * 安全边界与已知约束：
+ * - 仅安全上下文（https / localhost）可用 Service Worker；裸 http 的
+ *   局域网直连降级为「无 SW」，其余插件不受影响。
+ * - access-gate 未豁免 sw.js：注册发生在已认证页面（cookie 随请求携带），
+ *   未认证时浏览器更新检查得 403 → 保留现有 SW，不影响围栏语义。
+ * - 插件整体卸载会留下孤儿 SW：docs 给出一行手动清理命令。
+ * @module @dsh-plus/web-shell-sw
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-settings'
+import { unwrapVolatile } from '@dsh-plus/shared'
+
+import type { WebShellSwConfig, WebShellSwConfigFields } from './config.ts'
+import { SW_GLOBAL_KEY, SW_SCRIPT_PATH } from './ns.ts'
+import { serveServiceWorker } from './route.ts'
+
+export const name = 'dsh-plus-web-shell-sw'
+
+/** 无硬 inject：headless 等无 webServer 的 profile 里本插件空转（见 boot-retry 同款说明）。 */
+
+export { Config } from './config.ts'
+export { SETTINGS_NS } from './ns.ts'
+export type { WebShellSwConfig }
+
+/**
+ * 装配路由与配置注入。配置行恒推（含 enabled=false——禁用需要浏览器半
+ * 执行注销，「行缺席」会使其无法区分禁用与未安装）；路由恒注册（禁用时
+ * 无人注册新 SW，已注册的由配置行驱动注销，无需路由参与）。
+ * @param ctx - 宿主上下文（webServer 可选）。
+ * @param config - 活动字段形态的行级 config（测试可传平面值）。
+ */
+export function apply(ctx: Context, config: WebShellSwConfig | WebShellSwConfigFields): void {
+  const logger = ctx.logger('web-shell-sw')
+  // 活动引用原位提交：每次渲染现取快照，settings 翻转对下一次页面加载生效。
+  const current = (): WebShellSwConfig => unwrapVolatile(config)
+
+  ctx.inject(['webServer'], (webCtx) => {
+    webCtx.effect(
+      () =>
+        webCtx.on('webserver/index-inject', (table) => {
+          table.push({
+            kind: 'global',
+            name: SW_GLOBAL_KEY,
+            value: { enabled: current().enabled },
+          })
+        }),
+      'web-shell-sw: index injection',
+    )
+    webCtx.effect(
+      () =>
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: SW_SCRIPT_PATH,
+          handler: serveServiceWorker,
+        }),
+      'web-shell-sw: sw.js route',
+    )
+    logger.info(`installed (script route ${SW_SCRIPT_PATH})`)
+  })
+}
+
+/** 供测试断言 inject 形态：本插件不声明硬依赖。 */
+export const inject = [] as const

package/src/ns.ts

@@ -0,0 +1,22 @@
+/**
+ * settings 命名空间 + 路由/缓存/全局键常量（纯常量，零依赖）。
+ * node 半（路由服务、注入行）与浏览器半（注册/注销、清理）共享同一来源，
+ * 避免两侧字面量漂移。
+ * @module @dsh-plus/web-shell-sw/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-web-shell-sw'
+
+/** index-inject `kind:'global'` 注入的配置对象键。 */
+export const SW_GLOBAL_KEY = '__DSH_PLUS_WEB_SHELL_SW__'
+
+/** sw.js 精确路由（注册与更新检查都打这里）。 */
+export const SW_SCRIPT_PATH = '/dsh-plus/shell-sw.js'
+
+/**
+ * Cache Storage 缓存名（同时是版本号）。
+ * SW 脚本逻辑变更时手动 +1：activate 阶段删除前缀相同、名字不同的旧缓存。
+ */
+export const SW_CACHE_NAME = 'dsh-shell-v1'
+
+/** 缓存名前缀（禁用清理与版本升级都按它扫全量）。 */
+export const SW_CACHE_PREFIX = 'dsh-shell-'

package/src/route.ts

@@ -0,0 +1,38 @@
+/**
+ * sw.js 路由处理器：GET/HEAD 服务生成的 SW 脚本。
+ *
+ * 响应头三条缺一不可：
+ * - content-type 必须是 JavaScript MIME（否则注册被浏览器拒）；
+ * - service-worker-allowed: / 使 scope 覆盖全站（脚本挂在 /dsh-plus/ 下，
+ *   默认 scope 只到 /dsh-plus/，管不到 /assets 与 /plugins）；
+ * - cache-control: no-cache 让更新检查拿到最新脚本（现代浏览器主脚本本就
+ *   绕过 HTTP 缓存，此头是显式语义与旧实现的双保险）。
+ * @module @dsh-plus/web-shell-sw/route
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import { buildServiceWorkerScript } from './sw-script.ts'
+
+/**
+ * 精确路由 handler（webserver.register kind:'exact'）。
+ * @param req - 入站请求。
+ * @param res - 出站响应（本 handler 拥有完整生命周期）。
+ */
+export function serveServiceWorker(req: IncomingMessage, res: ServerResponse): void {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    res.writeHead(405, {
+      'content-type': 'text/plain; charset=utf-8',
+      allow: 'GET, HEAD',
+    })
+    res.end('method not allowed')
+    return
+  }
+  const body = buildServiceWorkerScript()
+  res.writeHead(200, {
+    'content-type': 'text/javascript; charset=utf-8',
+    'cache-control': 'no-cache',
+    'service-worker-allowed': '/',
+    'content-length': String(Buffer.byteLength(body)),
+  })
+  res.end(body)
+}

package/src/sw-script.ts

@@ -0,0 +1,129 @@
+/**
+ * sw.js 脚本生成：把安全决策（decision.ts 自包含纯函数）与缓存策略
+ * 渲染成一份独立的 Service Worker 脚本，由 node 半的精确路由对外服务。
+ *
+ * 设计要点（全部保守取向，宁可少缓存不可错缓存）：
+ * - 不 skipWaiting、不 clients.claim：新版本等所有标签页关闭后才接管，
+ *   绝不在会话中途换实现；首次注册只从下一次导航开始接管。
+ * - passthrough 一大类（RPC、SSE、token 交换、跨源、Range、非 GET）
+ *   不调 respondWith = 浏览器原生行为，零干预。
+ * - 只有 status 200、type basic、且 cache-control 不含 no-store/no-cache
+ *   的响应才入库——token 页（no-store）与代理侧 no-store 的 index 天然
+ *   免疫，认证内容永不落 Cache Storage。
+ * - 入库前剥离 content-encoding/content-length/transfer-encoding/vary：
+ *   fetch() 暴露的 body 已解码，复制编码头会造成「解码头 + 原始体」错配
+ *   （经典 SW 缓存坑）；存 identity 体，下次命中由 SW 直接原样返回。
+ * - 缓存名带版本（ns.ts 的 SW_CACHE_NAME），activate 清理同前缀旧版本；
+ *   源码逻辑变更时手动 +1 即可全量换血。
+ *
+ * 安全边界：`decideFetchAction` 无闭包依赖，toString() 内嵌后行为与
+ * node 侧单测完全一致（tests/sw-script.test.ts 同时断言编译与内嵌等价）。
+ * @module @dsh-plus/web-shell-sw/sw-script
+ */
+import { decideFetchAction } from './decision.ts'
+import { SW_CACHE_NAME, SW_CACHE_PREFIX } from './ns.ts'
+
+/**
+ * 生成完整的 sw.js 脚本文本（纯函数，同配置恒等输出）。
+ * @returns 可直接作为 application/javascript 响应体的脚本源码。
+ */
+export function buildServiceWorkerScript(): string {
+  return `'use strict';
+const CACHE_NAME = ${JSON.stringify(SW_CACHE_NAME)};
+const CACHE_PREFIX = ${JSON.stringify(SW_CACHE_PREFIX)};
+const decideFetch = ${decideFetchAction.toString()};
+
+self.addEventListener('install', function () {
+  // 不 skipWaiting：新版本等待所有标签页关闭后接管，避免会话中途换实现。
+});
+
+self.addEventListener('activate', function (event) {
+  event.waitUntil(
+    caches.keys().then(function (keys) {
+      return Promise.all(
+        keys
+          .filter(function (key) { return key.indexOf(CACHE_PREFIX) === 0 && key !== CACHE_NAME; })
+          .map(function (key) { return caches.delete(key); })
+      );
+    })
+  );
+});
+
+self.addEventListener('fetch', function (event) {
+  const request = event.request;
+  let url;
+  try {
+    url = new URL(request.url);
+  } catch (error) {
+    return;
+  }
+  if (url.origin !== self.location.origin) return;
+  const action = decideFetch(
+    request.method,
+    url.pathname,
+    url.search !== '',
+    request.headers.has('range')
+  );
+  if (action === 'passthrough') return;
+  event.respondWith(
+    action === 'cache-first' ? cacheFirst(request) : shellNetworkFirst(request)
+  );
+});
+
+/** 剥离编码相关头后再入库：fetch 的 body 已解码，保留编码头会造成解码错配。 */
+function normalizeForCache(response) {
+  const headers = new Headers(response.headers);
+  ['content-encoding', 'content-length', 'transfer-encoding', 'vary'].forEach(function (name) {
+    headers.delete(name);
+  });
+  return response.arrayBuffer().then(function (body) {
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: headers });
+  });
+}
+
+/** 仅 200/basic/未标 no-store 且未标 no-cache 的响应可入库。 */
+function isStorable(response) {
+  if (response.status !== 200 || response.type !== 'basic') return false;
+  const cacheControl = (response.headers.get('cache-control') || '').toLowerCase();
+  return cacheControl.indexOf('no-store') === -1 && cacheControl.indexOf('no-cache') === -1;
+}
+
+function putNormalized(cache, request, response) {
+  return normalizeForCache(response).then(
+    function (stored) { return cache.put(request, stored); },
+    function (error) { console.warn('[web-shell-sw] cache.put failed', error); }
+  );
+}
+
+/** 内容寻址资源：命中即回；未命中回源，可存则存（存失败不影响本次响应）。 */
+function cacheFirst(request) {
+  return caches.open(CACHE_NAME).then(function (cache) {
+    return cache.match(request).then(function (hit) {
+      if (hit !== undefined) return hit;
+      return fetch(request).then(function (response) {
+        if (isStorable(response)) putNormalized(cache, request, response.clone());
+        return response;
+      });
+    });
+  });
+}
+
+/** index：网络优先（在线恒用最新外壳）；仅网络失败时才用缓存兜底，无缓存则原生失败。 */
+function shellNetworkFirst(request) {
+  return caches.open(CACHE_NAME).then(function (cache) {
+    return fetch(request).then(
+      function (response) {
+        if (isStorable(response)) putNormalized(cache, request, response.clone());
+        return response;
+      },
+      function (error) {
+        return cache.match(request).then(function (hit) {
+          if (hit !== undefined) return hit;
+          throw error;
+        });
+      }
+    );
+  });
+}
+`
+}