@dsh-plus/lifeboat 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,39 @@
+window.__ModuleLoader__.load({
+	id: "@dsh-plus/lifeboat",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+
+
+//#region src/client/client.ts
+const name = "dsh-plus-lifeboat";
+/** Runtime mirror: FiberState 是 cordis 跨包 const enum（FAILED = 3，cordis 4.0.1）。 */
+const FIBER_FAILED = 3;
+/** 永不回报的条目：救生艇自身与聚合 bundle。 */
+const EXCLUDED = new Set(["dsh-plus-lifeboat", "dsh-plus-bundle-main"]);
+const GUARD_RE = /^dsh-plus-[a-z0-9-]+$/;
+function apply(ctx) {
+	try {
+		const reported = /* @__PURE__ */ new Set();
+		ctx.root.on("internal/status", (fiber) => {
+			try {
+				if (fiber.state !== FIBER_FAILED) return;
+				const plugin = fiber.name;
+				if (!GUARD_RE.test(plugin) || EXCLUDED.has(plugin) || reported.has(plugin)) return;
+				reported.add(plugin);
+				fetch("/dsh-plus/lifeboat/quarantine", {
+					method: "POST",
+					headers: { "content-type": "application/json" },
+					body: JSON.stringify({ name: plugin })
+				}).catch(() => {});
+			} catch {}
+		});
+	} catch {}
+}
+
+//#endregion
+exports.apply = apply;
+exports.name = name;
+		return module.exports;
+	}
+});

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+import z from "@deepseek-ai/schemastery";
+import "@deepseek-ai/dsh-settings";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/config.d.ts
+
+/** 行级配置：全部有默认值，正常部署零配置。 */
+declare const Config: z<Schemastery.ObjectS<{
+  enabled: z<boolean, boolean>;
+  patchFile: z<string, string>;
+  llmFallback: z<boolean, boolean>;
+  alertCooldownMs: z<number, number>;
+}>, Schemastery.ObjectT<{
+  enabled: z<boolean, boolean>;
+  patchFile: z<string, string>;
+  llmFallback: z<boolean, boolean>;
+  alertCooldownMs: z<number, number>;
+}>>;
+type LifeboatConfig = Schemastery.TypeT<typeof Config>;
+//#endregion
+//#region src/index.d.ts
+declare const name = "dsh-plus-lifeboat";
+declare const inject: readonly ["settings", "llm"];
+declare function apply(ctx: Context, config: LifeboatConfig): void;
+//#endregion
+export { Config, apply, inject, name };

package/lib/index.js

@@ -0,0 +1,440 @@
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import z from "@deepseek-ai/schemastery";
+import { SettingsConflictError, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { copyFile, readFile, rename, writeFile } from "node:fs/promises";
+import { parseDocument } from "yaml";
+
+//#region src/ns.ts
+/**
+* settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+* @module lifeboat/ns
+*/
+const SETTINGS_NS$1 = "dsh-plus-lifeboat";
+
+//#endregion
+//#region src/config.ts
+/** settings 命名空间（品牌化后供 settings 服务注册/读写）。 */
+const SETTINGS_NS = settingsNamespace(SETTINGS_NS$1);
+/** 行级配置：全部有默认值，正常部署零配置。 */
+const Config = z.object({
+	enabled: z.boolean().description("故障隔离总开关").default(true),
+	patchFile: z.string().description("隔离写入的 profile 用户 patch 文件绝对路径；留空自动取 $DSH_HOME/profiles/web/cordis.patch.yml").default(""),
+	llmFallback: z.boolean().description("llm-pi 缺席时自动翻译其配置到官方 llm-pi-ai 并切换默认模型").default(true),
+	alertCooldownMs: z.natural().description("同一插件重复告警的最小间隔毫秒数").default(3e5)
+});
+/** journal 单条记录。 */
+const JournalEntry = z.object({
+	at: z.string(),
+	kind: z.string(),
+	detail: z.string()
+});
+/** LLM 应急翻译的持久状态（还原依据）。 */
+const FallbackState = z.object({
+	active: z.boolean(),
+	originalProvider: z.string(),
+	originalModel: z.string(),
+	fallbackProvider: z.string(),
+	providers: z.array(z.string()),
+	at: z.string()
+});
+/** 命名空间 schema：宽松承载 journal 与翻译状态，上限截断防膨胀。 */
+const JournalSchema = z.object({
+	journal: z.array(JournalEntry).description("救生艇操作日志（最新在尾，封顶 50 条）").default([]),
+	llmFallback: z.union([FallbackState, z.const(null)]).description("LLM 应急翻译状态；null 表示未处于降级").default(null)
+});
+
+//#endregion
+//#region src/notify.ts
+/**
+* 装配告警出口。返回同步派单函数：内部异步发送，失败只记日志。
+* notify-email 出现时升级为邮件；全程 journal 兜底可溯。
+*/
+function installAlerter(ctx, journal) {
+	const logger = ctx.logger("lifeboat");
+	let mailer;
+	ctx.inject(["notifyEmail"], (mailCtx) => {
+		mailer = mailCtx.notifyEmail;
+		return () => {
+			mailer = void 0;
+		};
+	});
+	return (subject, text) => {
+		journal("alert", `${subject} | ${text}`);
+		const active = mailer;
+		if (!active?.sendNotice) {
+			logger.warn(`${subject} —— ${text}`);
+			return;
+		}
+		active.sendNotice({
+			subject,
+			text
+		}).then((result) => {
+			if (!result.ok) logger.warn(`邮件告警投递失败: ${result.detail}`);
+		}, (error) => {
+			logger.warn(`邮件告警异常: ${error instanceof Error ? error.message : String(error)}`);
+		});
+	};
+}
+
+//#endregion
+//#region src/patch-file.ts
+/** 条目（含 insert 子列表）中是否已有针对 targetId 的 disabled 覆盖。 */
+function hasDisable(entries, targetId) {
+	for (const entry of entries) {
+		if (entry.id === targetId && entry.disabled === true) return true;
+		if (Array.isArray(entry.insert) && hasDisable(entry.insert, targetId)) return true;
+	}
+	return false;
+}
+/**
+* 向 patch 文件追加一条禁用覆盖；返回是否实际写入（已存在禁用则跳过）。
+* @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+*/
+async function appendDisable(patchFile, targetId) {
+	const doc = parseDocument(await readFile(patchFile, "utf-8"));
+	const root = doc.toJS();
+	if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`);
+	if (hasDisable(root, targetId)) return false;
+	await copyFile(patchFile, `${patchFile}.lifeboat.bak`);
+	doc.add({
+		id: targetId,
+		disabled: true
+	});
+	const tmp = `${patchFile}.lifeboat.tmp`;
+	await writeFile(tmp, doc.toString(), "utf-8");
+	await rename(tmp, patchFile);
+	return true;
+}
+
+//#endregion
+//#region src/quarantine.ts
+/** Runtime mirror: FiberState 是 cordis 跨包 const enum（官方 dsh-host-plugin-inventory 同款做法）。 */
+const FIBER_FAILED = 3;
+/** 永不隔离的条目：救生艇自身与聚合 bundle（禁了它们等于关掉整个防线/全家）。 */
+const EXCLUDED = new Set(["dsh-plus-lifeboat", "dsh-plus-bundle-main"]);
+const GUARD_RE = /^dsh-plus-[a-z0-9-]+$/;
+/** 名字是否属于可隔离的 dsh-plus 兄弟插件（entry id 与插件 name 同字面量是本仓库约定）。 */
+function isGuardedPlugin(name$1) {
+	return typeof name$1 === "string" && GUARD_RE.test(name$1) && !EXCLUDED.has(name$1);
+}
+/** 装配隔离执行器（纯逻辑，可测）。 */
+function createQuarantine(ctx, deps) {
+	const logger = ctx.logger("lifeboat");
+	const lastAlertAt = /* @__PURE__ */ new Map();
+	const inFlight = /* @__PURE__ */ new Set();
+	async function quarantine(name$1, origin) {
+		if (!isGuardedPlugin(name$1)) return;
+		if (inFlight.has(name$1)) return;
+		inFlight.add(name$1);
+		try {
+			const written = await appendDisable(deps.patchFile, name$1);
+			deps.journal("quarantine", `${name$1}（来源 ${origin}，${written ? "已写入禁用" : "已存在禁用"}）`);
+			const now = Date.now();
+			if (now - (lastAlertAt.get(name$1) ?? 0) >= deps.alertCooldownMs) {
+				lastAlertAt.set(name$1, now);
+				deps.alert(`[DSH] 插件 ${name$1} 加载失败，已自动隔离`, `检测到插件 ${name$1} 的 fiber 进入 FAILED（来源：${origin}）。\n已向 ${deps.patchFile} 写入 disabled 覆盖，重启/刷新后该插件不再加载，其余插件不受影响。\n修复后删除该条覆盖即可恢复。`);
+			}
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.warn(`隔离 ${name$1} 失败: ${message}`);
+			deps.journal("quarantine-error", `${name$1}: ${message}`);
+			deps.alert(`[DSH] 插件 ${name$1} 加载失败，自动隔离未果`, `隔离写入失败：${message}\n请手动在 patch 层禁用该插件。`);
+		} finally {
+			inFlight.delete(name$1);
+		}
+	}
+	return { quarantine };
+}
+/**
+* host 侧监听：root context 上兄弟 fiber 的 internal/status 转移。
+* fiber.name 对 loader 条目即插件 display name（模块导出的 name 字段）。
+*/
+function installHostWatch(ctx, q) {
+	ctx.root.on("internal/status", (fiber) => {
+		if (fiber.state !== FIBER_FAILED) return;
+		if (!isGuardedPlugin(fiber.name)) return;
+		q.quarantine(fiber.name, "host");
+	});
+}
+
+//#endregion
+//#region src/quarantine-api.ts
+const ROUTE = "/dsh-plus/lifeboat/quarantine";
+function sendJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+		req.on("error", reject);
+	});
+}
+/** 注册哨兵回报路由（webServer 缺失时由调用方保证不调用）。 */
+function registerQuarantineApi(ctx, q) {
+	const logger = ctx.logger("lifeboat");
+	ctx.webServer.register({
+		kind: "prefix",
+		path: ROUTE,
+		handler: async (req, res) => {
+			try {
+				if (req.method !== "POST") {
+					sendJson(res, 405, { error: "POST only" });
+					return;
+				}
+				const body = JSON.parse(await readBody(req));
+				if (typeof body.name !== "string") {
+					sendJson(res, 400, { error: "missing name" });
+					return;
+				}
+				q.quarantine(body.name, "client");
+				sendJson(res, 200, { ok: true });
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				logger.warn(`quarantine api failed: ${message}`);
+				if (!res.headersSent) sendJson(res, 400, { error: message });
+				else res.end();
+			}
+		}
+	});
+}
+
+//#endregion
+//#region src/fallback-llm.ts
+const NS_PI_AI = settingsNamespace("llm-pi-ai");
+const NS_AGENT_DEFAULT = settingsNamespace("agent-default-model");
+const RAW_NS_LLM_PI = "dsh-plus-llm-pi";
+/** 翻译路由键后缀：与源路由错开，避免 llm-pi 恢复瞬间撞 DUPLICATE_ADAPTER。 */
+const FALLBACK_SUFFIX = "-fb";
+/** 官方配置路径物化的 compat 子集（其余字段降级期丢弃）。 */
+const COMPAT_WHITELIST = ["thinkingFormat", "supportsReasoningEffort"];
+/** 官方 reasoning 词表（ModelThinkingLevel 的保守子集），不在其中的值丢弃。 */
+const REASONING_LEVELS = new Set([
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+]);
+/** 模型继承源（extends 的 provider 前缀）→ 协议的已知映射。 */
+const EXTENDS_PROTOCOL = {
+	anthropic: "anthropic-messages",
+	"kimi-coding": "anthropic-messages",
+	deepseek: "openai-completions",
+	openai: "openai-completions"
+};
+/** 路由名里的协议线索。 */
+const ROUTE_PROTOCOL = {
+	chat: "openai-completions",
+	completions: "openai-completions",
+	response: "openai-responses",
+	responses: "openai-responses",
+	anthropic: "anthropic-messages",
+	claude: "anthropic-messages"
+};
+/**
+* 推断路由协议：显式 api > 路由名线索 > 首个模型的继承源 > openai-completions。
+* 兜底选 openai-completions 因为多数网关提供 OpenAI 兼容面；推错时告警里注明。
+*/
+function inferApi(routeKey, provider) {
+	if (typeof provider.api === "string" && provider.api.length > 0) return provider.api;
+	const routeHint = ROUTE_PROTOCOL[routeKey.toLowerCase()];
+	if (routeHint !== void 0) return routeHint;
+	const source = (provider.models?.find((m) => typeof m.extends === "string")?.extends)?.split("/")[0];
+	if (source !== void 0 && EXTENDS_PROTOCOL[source] !== void 0) return EXTENDS_PROTOCOL[source];
+	return "openai-completions";
+}
+/** 单个 provider 翻译（纯函数）。 */
+function translateProvider(routeKey, raw) {
+	const out = {
+		displayName: `${raw.displayName ?? routeKey} [fallback]`,
+		api: inferApi(routeKey, raw)
+	};
+	if (raw.apiKeyEnv !== void 0) out.apiKeyEnv = raw.apiKeyEnv;
+	if (raw.baseURL !== void 0) out.baseURL = raw.baseURL;
+	if (raw.headers !== void 0) out.headers = raw.headers;
+	if (raw.reasoning !== void 0 && REASONING_LEVELS.has(raw.reasoning)) out.reasoning = raw.reasoning;
+	if (raw.thinkingBudgets !== void 0) out.thinkingBudgets = raw.thinkingBudgets;
+	if (Array.isArray(raw.defaultInput) && raw.defaultInput.length > 0) out.defaultInput = raw.defaultInput;
+	if (raw.compat !== void 0) {
+		const compat = {};
+		for (const key of COMPAT_WHITELIST) if (raw.compat[key] !== void 0) compat[key] = raw.compat[key];
+		if (Object.keys(compat).length > 0) out.compat = compat;
+	}
+	if (Array.isArray(raw.models) && raw.models.length > 0) out.models = raw.models.map((m) => {
+		const model = { id: m.id };
+		if (m.name !== void 0) model.name = m.name;
+		if (m.contextWindow !== void 0) model.contextWindow = m.contextWindow;
+		if (m.maxTokens !== void 0) model.maxTokens = m.maxTokens;
+		if (Array.isArray(m.input) && m.input.length > 0) model.input = m.input;
+		return model;
+	});
+	return out;
+}
+/** 整表翻译：键加 -fb 后缀（纯函数）。 */
+function translateProviders(providers) {
+	const out = {};
+	for (const [key, raw] of Object.entries(providers)) out[`${key}${FALLBACK_SUFFIX}`] = translateProvider(key, raw);
+	return out;
+}
+/** 读 settings.yaml 原始文档的指定段落（只读；文件/段落缺失返回 undefined）。 */
+async function readRawSection(settingsFile, ns) {
+	const section = parseDocument(await readFile(settingsFile, "utf-8")).toJS()[ns];
+	if (typeof section !== "object" || section === null) return void 0;
+	return section;
+}
+/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。 */
+async function writeWithRetry(write) {
+	try {
+		await write();
+	} catch (error) {
+		if (!(error instanceof SettingsConflictError)) throw error;
+		await write();
+	}
+}
+/** 装配 LLM 应急翻译：启动后及 settings/llm 变化时评估一次（并发合并）。 */
+function installLlmFallback(ctx, deps) {
+	const logger = ctx.logger("lifeboat");
+	const writes = ctx.settings;
+	const settingsFile = dshHomePath("settings.yaml");
+	let inFlight;
+	const listProviderIds = () => new Set(ctx.llm.listProviders().map((p) => p.id));
+	async function activate(provider, model) {
+		const providers = (await readRawSection(settingsFile, RAW_NS_LLM_PI).catch(() => void 0))?.providers;
+		if (providers === void 0 || providers[provider] === void 0) {
+			deps.alert("[DSH] 默认模型不可用且无配置可翻译", `默认模型的 provider "${provider}" 没有已注册 adapter，且 ${RAW_NS_LLM_PI} 配置中找不到对应条目，无法应急翻译。请手动修复。`);
+			return;
+		}
+		const translated = translateProviders(providers);
+		const fbProvider = `${provider}${FALLBACK_SUFFIX}`;
+		await writeWithRetry(() => writes.update(NS_PI_AI, { providers: translated }));
+		await writeWithRetry(() => writes.update(NS_AGENT_DEFAULT, {
+			provider: fbProvider,
+			model
+		}));
+		await deps.writeState({
+			active: true,
+			originalProvider: provider,
+			originalModel: model,
+			fallbackProvider: fbProvider,
+			providers: Object.keys(translated),
+			at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		deps.journal("llm-fallback", `默认模型切换到 ${fbProvider}/${model}（翻译 ${Object.keys(translated).length} 个 provider）`);
+		deps.alert("[DSH] LLM 配置已应急翻译", `默认模型的 provider "${provider}" 不可用（llm-pi 缺席？），已把 ${RAW_NS_LLM_PI} 配置翻译为官方 llm-pi-ai 路由（-fb 后缀）并切换默认模型为 ${fbProvider}/${model}。源插件恢复后将自动还原。`);
+	}
+	async function revert(state) {
+		const ops = state.providers.map((key) => ({
+			op: "unset",
+			path: ["providers", key]
+		}));
+		await writeWithRetry(() => writes.mutate(NS_PI_AI, ops));
+		await writeWithRetry(() => writes.update(NS_AGENT_DEFAULT, {
+			provider: state.originalProvider,
+			model: state.originalModel
+		}));
+		await deps.writeState(null);
+		deps.journal("llm-fallback-revert", `默认模型还原为 ${state.originalProvider}/${state.originalModel}`);
+		deps.alert("[DSH] LLM 应急翻译已还原", `provider "${state.originalProvider}" 恢复健康，默认模型已还原，临时翻译路由已清除。`);
+	}
+	async function evaluate() {
+		const state = deps.readState();
+		const ids = listProviderIds();
+		if (state?.active) {
+			if (ids.has(state.originalProvider)) await revert(state);
+			return;
+		}
+		const def = ctx.settings.get(NS_AGENT_DEFAULT);
+		if (def?.provider === void 0 || def.model === void 0) return;
+		if (ids.has(def.provider)) return;
+		await activate(def.provider, def.model);
+	}
+	const run = () => {
+		inFlight ??= evaluate().catch((error) => {
+			const message = error instanceof Error ? error.message : String(error);
+			logger.warn(`llm fallback 评估失败: ${message}`);
+			deps.journal("llm-fallback-error", message);
+		}).finally(() => {
+			inFlight = void 0;
+		});
+	};
+	const bootTimer = setTimeout(run, 1e4);
+	ctx.effect(() => () => clearTimeout(bootTimer), "lifeboat: fallback boot timer");
+	ctx.on("ready", run);
+	const WATCHED_NS = new Set([
+		"agent-default-model",
+		"llm-pi-ai",
+		RAW_NS_LLM_PI
+	]);
+	ctx.root.on("settings/updated", (ns) => {
+		if (typeof ns === "string" && WATCHED_NS.has(ns)) run();
+	});
+	ctx.root.on("llm/adapters-updated", run);
+}
+
+//#endregion
+//#region src/index.ts
+const name = "dsh-plus-lifeboat";
+const inject = ["settings", "llm"];
+/** journal 上限：只留最近 50 条，防长期运行膨胀。 */
+const JOURNAL_CAP = 50;
+function apply(ctx, config) {
+	const logger = ctx.logger("lifeboat");
+	let doc = {
+		journal: [],
+		llmFallback: null
+	};
+	let persist;
+	try {
+		const scope = ctx.settings.register(SETTINGS_NS, JournalSchema);
+		doc = scope.get();
+		persist = (patch) => scope.update(patch);
+	} catch (error) {
+		logger.warn(`journal 命名空间注册失败，降级为内存态: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const journal = (kind, detail) => {
+		doc = {
+			...doc,
+			journal: [...doc.journal, {
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				kind,
+				detail
+			}].slice(-JOURNAL_CAP)
+		};
+		persist?.({ journal: doc.journal }).catch((error) => {
+			logger.warn(`journal 持久化失败: ${error instanceof Error ? error.message : String(error)}`);
+		});
+	};
+	const alert = installAlerter(ctx, journal);
+	if (config.enabled) {
+		const quarantine = createQuarantine(ctx, {
+			patchFile: config.patchFile.length > 0 ? config.patchFile : dshHomePath("profiles", "web", "cordis.patch.yml"),
+			alertCooldownMs: config.alertCooldownMs,
+			journal,
+			alert
+		});
+		installHostWatch(ctx, quarantine);
+		ctx.inject(["webServer"], (webCtx) => {
+			registerQuarantineApi(webCtx, quarantine);
+		});
+	}
+	if (config.llmFallback) installLlmFallback(ctx, {
+		journal,
+		alert,
+		readState: () => doc.llmFallback,
+		writeState: async (state) => {
+			doc = {
+				...doc,
+				llmFallback: state
+			};
+			await persist?.({ llmFallback: state });
+		}
+	});
+}
+
+//#endregion
+export { Config, apply, inject, name };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dsh-plus/lifeboat",
+  "version": "0.1.0",
+  "description": "dsh-plus service plugin: 故障救生艇——兄弟插件崩溃时自动隔离（写用户 patch 层禁用），llm-pi 缺席时把其配置临时翻译为官方 llm-pi-ai 路由，恢复后自动还原",
+  "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": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.7",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A-G-guy/dsh-plus.git",
+    "directory": "packages/lifeboat"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}

package/src/client/client.ts

@@ -0,0 +1,45 @@
+/**
+ * 浏览器半哨兵：bundle 首位加载，在 root context 监听兄弟 fiber 的 FAILED 转移，
+ * 经同源 HTTP 回报 host 半隔离。boot 失败页是内核所有（fail-loud），本次启动
+ * 无法挽回——哨兵保证的是「刷新一次即恢复」。
+ *
+ * 零依赖铁律：不 import 任何包（含 cordis/shared），FiberState.FAILED 以字面量
+ * 3 镜像一个道理（官方 dsh-host-plugin-inventory 同款做法）；任何异常止步自身。
+ * @module @dsh-plus/lifeboat/client
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+export const name = 'dsh-plus-lifeboat'
+
+/** Runtime mirror: FiberState 是 cordis 跨包 const enum（FAILED = 3，cordis 4.0.1）。 */
+const FIBER_FAILED = 3
+
+/** 永不回报的条目：救生艇自身与聚合 bundle。 */
+const EXCLUDED = new Set(['dsh-plus-lifeboat', 'dsh-plus-bundle-main'])
+
+const GUARD_RE = /^dsh-plus-[a-z0-9-]+$/
+
+export function apply(ctx: Context): void {
+  try {
+    const reported = new Set<string>()
+    ctx.root.on('internal/status', (fiber: { state: number; name: string }) => {
+      try {
+        if (fiber.state !== FIBER_FAILED) return
+        const plugin = fiber.name
+        if (!GUARD_RE.test(plugin) || EXCLUDED.has(plugin) || reported.has(plugin)) return
+        reported.add(plugin)
+        void fetch('/dsh-plus/lifeboat/quarantine', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ name: plugin }),
+        }).catch(() => {
+          // boot 失败期连接未必就绪；host 半的监听仍是主通道，这里失败静默。
+        })
+      } catch {
+        // 哨兵监听器绝不向外抛异常（fail-loud 启动门下，自身异常会卡死整页）。
+      }
+    })
+  } catch {
+    // apply 自身同理。
+  }
+}

package/src/config.ts

@@ -0,0 +1,54 @@
+/**
+ * 配置与 journal 单一事实源。
+ * - 行级 Config（cordis 组合层）：救生艇自身行为开关，dev/prod patch 层可覆盖。
+ * - settings 命名空间 dsh-plus-lifeboat：运行期 journal 与 LLM 应急翻译状态，
+ *   经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml，重启后可据此还原。
+ * schema 刻意宽松：lifeboat 是最后防线，自身命名空间的数据问题绝不能让它起不来。
+ * @module lifeboat/config
+ */
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
+
+/** settings 命名空间（品牌化后供 settings 服务注册/读写）。 */
+export const SETTINGS_NS = settingsNamespace(NS_LITERAL)
+
+/** 行级配置：全部有默认值，正常部署零配置。 */
+export const Config = z.object({
+  enabled: z.boolean().description('故障隔离总开关').default(true),
+  patchFile: z.string()
+    .description('隔离写入的 profile 用户 patch 文件绝对路径；留空自动取 $DSH_HOME/profiles/web/cordis.patch.yml')
+    .default(''),
+  llmFallback: z.boolean()
+    .description('llm-pi 缺席时自动翻译其配置到官方 llm-pi-ai 并切换默认模型').default(true),
+  alertCooldownMs: z.natural().description('同一插件重复告警的最小间隔毫秒数').default(300000),
+})
+
+export type LifeboatConfig = Schemastery.TypeT<typeof Config>
+
+/** journal 单条记录。 */
+const JournalEntry = z.object({
+  at: z.string(),
+  kind: z.string(),
+  detail: z.string(),
+})
+
+/** LLM 应急翻译的持久状态（还原依据）。 */
+const FallbackState = z.object({
+  active: z.boolean(),
+  originalProvider: z.string(),
+  originalModel: z.string(),
+  fallbackProvider: z.string(),
+  providers: z.array(z.string()),
+  at: z.string(),
+})
+
+/** 命名空间 schema：宽松承载 journal 与翻译状态，上限截断防膨胀。 */
+export const JournalSchema = z.object({
+  journal: z.array(JournalEntry).description('救生艇操作日志（最新在尾，封顶 50 条）').default([]),
+  llmFallback: z.union([FallbackState, z.const(null)]).description('LLM 应急翻译状态；null 表示未处于降级').default(null),
+})
+
+export type JournalDoc = Schemastery.TypeT<typeof JournalSchema>
+export type FallbackStateT = Schemastery.TypeT<typeof FallbackState>

package/src/fallback-llm.ts

@@ -0,0 +1,273 @@
+/**
+ * LLM 应急翻译：默认模型路由的 provider 无已注册 adapter 时（典型场景：llm-pi
+ * 被隔离/加载失败），把 settings.yaml 里 dsh-plus-llm-pi 的 provider 配置翻译为
+ * 官方 llm-pi-ai 命名空间的原生格式（键加 -fb 后缀避开 DUPLICATE_ADAPTER 冲突），
+ * 默认模型指到翻译路由；源 provider 恢复健康后按 journal 自动还原。
+ *
+ * 为什么读原始 settings.yaml 而不是 settings 服务：插件被禁用后其命名空间随之
+ * 注销，服务层读不到——但数据仍在文件里（只读，不修改）。
+ * 降级语义：翻译只覆盖官方物化的字段子集，dsh-plus 扩展的全量 compat 丢弃；
+ * 协议推断是启发式（显式 api > 路由名 > 模型继承源 > openai-completions 兜底）。
+ * @module lifeboat/fallback-llm
+ */
+import { readFile } from 'node:fs/promises'
+
+import type { Context } from '@deepseek-ai/cordis'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+import type {} from '@deepseek-ai/dsh-llm'
+import { SettingsConflictError, settingsNamespace, type SettingsProvider } from '@deepseek-ai/dsh-settings'
+import { parseDocument } from 'yaml'
+
+import type { FallbackStateT } from './config.ts'
+import type { Alerter } from './notify.ts'
+
+const NS_PI_AI = settingsNamespace('llm-pi-ai')
+const NS_AGENT_DEFAULT = settingsNamespace('agent-default-model')
+const RAW_NS_LLM_PI = 'dsh-plus-llm-pi'
+
+/** 翻译路由键后缀：与源路由错开，避免 llm-pi 恢复瞬间撞 DUPLICATE_ADAPTER。 */
+export const FALLBACK_SUFFIX = '-fb'
+
+/** 官方配置路径物化的 compat 子集（其余字段降级期丢弃）。 */
+const COMPAT_WHITELIST = ['thinkingFormat', 'supportsReasoningEffort'] as const
+
+/** 官方 reasoning 词表（ModelThinkingLevel 的保守子集），不在其中的值丢弃。 */
+const REASONING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
+
+/** dsh-plus-llm-pi provider 配置的松散视图（原始文件读取，未经 schema 解析）。 */
+export interface RawProvider {
+  displayName?: string
+  apiKeyEnv?: string
+  baseURL?: string
+  api?: string
+  headers?: Record<string, string>
+  reasoning?: string
+  thinkingBudgets?: Record<string, unknown>
+  defaultInput?: string[]
+  compat?: Record<string, unknown>
+  models?: RawModel[]
+}
+
+export interface RawModel {
+  id: string
+  name?: string
+  extends?: string
+  contextWindow?: number
+  maxTokens?: number
+  input?: string[]
+  reasoningEfforts?: Record<string, string>
+}
+
+/** 官方 llm-pi-ai provider 档案的翻译目标形状（字段子集）。 */
+export interface TranslatedProvider {
+  displayName?: string
+  apiKeyEnv?: string
+  baseURL?: string
+  api: string
+  headers?: Record<string, string>
+  reasoning?: string
+  thinkingBudgets?: Record<string, unknown>
+  defaultInput?: string[]
+  compat?: Record<string, unknown>
+  models?: Record<string, unknown>[]
+}
+
+/** 模型继承源（extends 的 provider 前缀）→ 协议的已知映射。 */
+const EXTENDS_PROTOCOL: Record<string, string> = {
+  anthropic: 'anthropic-messages',
+  'kimi-coding': 'anthropic-messages',
+  deepseek: 'openai-completions',
+  openai: 'openai-completions',
+}
+
+/** 路由名里的协议线索。 */
+const ROUTE_PROTOCOL: Record<string, string> = {
+  chat: 'openai-completions',
+  completions: 'openai-completions',
+  response: 'openai-responses',
+  responses: 'openai-responses',
+  anthropic: 'anthropic-messages',
+  claude: 'anthropic-messages',
+}
+
+/**
+ * 推断路由协议：显式 api > 路由名线索 > 首个模型的继承源 > openai-completions。
+ * 兜底选 openai-completions 因为多数网关提供 OpenAI 兼容面；推错时告警里注明。
+ */
+export function inferApi(routeKey: string, provider: RawProvider): string {
+  if (typeof provider.api === 'string' && provider.api.length > 0) return provider.api
+  const routeHint = ROUTE_PROTOCOL[routeKey.toLowerCase()]
+  if (routeHint !== undefined) return routeHint
+  const firstExtends = provider.models?.find((m) => typeof m.extends === 'string')?.extends
+  const source = firstExtends?.split('/')[0]
+  if (source !== undefined && EXTENDS_PROTOCOL[source] !== undefined) return EXTENDS_PROTOCOL[source]
+  return 'openai-completions'
+}
+
+/** 单个 provider 翻译（纯函数）。 */
+export function translateProvider(routeKey: string, raw: RawProvider): TranslatedProvider {
+  const out: TranslatedProvider = {
+    displayName: `${raw.displayName ?? routeKey} [fallback]`,
+    api: inferApi(routeKey, raw),
+  }
+  if (raw.apiKeyEnv !== undefined) out.apiKeyEnv = raw.apiKeyEnv
+  if (raw.baseURL !== undefined) out.baseURL = raw.baseURL
+  if (raw.headers !== undefined) out.headers = raw.headers
+  if (raw.reasoning !== undefined && REASONING_LEVELS.has(raw.reasoning)) out.reasoning = raw.reasoning
+  if (raw.thinkingBudgets !== undefined) out.thinkingBudgets = raw.thinkingBudgets
+  if (Array.isArray(raw.defaultInput) && raw.defaultInput.length > 0) out.defaultInput = raw.defaultInput
+  if (raw.compat !== undefined) {
+    const compat: Record<string, unknown> = {}
+    for (const key of COMPAT_WHITELIST) {
+      if (raw.compat[key] !== undefined) compat[key] = raw.compat[key]
+    }
+    if (Object.keys(compat).length > 0) out.compat = compat
+  }
+  if (Array.isArray(raw.models) && raw.models.length > 0) {
+    out.models = raw.models.map((m) => {
+      const model: Record<string, unknown> = { id: m.id }
+      if (m.name !== undefined) model.name = m.name
+      if (m.contextWindow !== undefined) model.contextWindow = m.contextWindow
+      if (m.maxTokens !== undefined) model.maxTokens = m.maxTokens
+      if (Array.isArray(m.input) && m.input.length > 0) model.input = m.input
+      return model
+    })
+  }
+  return out
+}
+
+/** 整表翻译：键加 -fb 后缀（纯函数）。 */
+export function translateProviders(providers: Record<string, RawProvider>): Record<string, TranslatedProvider> {
+  const out: Record<string, TranslatedProvider> = {}
+  for (const [key, raw] of Object.entries(providers)) {
+    out[`${key}${FALLBACK_SUFFIX}`] = translateProvider(key, raw)
+  }
+  return out
+}
+
+/** 读 settings.yaml 原始文档的指定段落（只读；文件/段落缺失返回 undefined）。 */
+export async function readRawSection(settingsFile: string, ns: string): Promise<Record<string, unknown> | undefined> {
+  const text = await readFile(settingsFile, 'utf-8')
+  const doc = parseDocument(text).toJS() as Record<string, unknown>
+  const section = doc[ns]
+  if (typeof section !== 'object' || section === null) return undefined
+  return section as Record<string, unknown>
+}
+
+interface SettingsWrite {
+  update(ns: ReturnType<typeof settingsNamespace>, patch: object): Promise<void>
+  mutate(ns: ReturnType<typeof settingsNamespace>, ops: readonly { op: 'set' | 'unset'; path: readonly string[]; value?: unknown }[]): Promise<void>
+}
+
+/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。 */
+async function writeWithRetry(write: () => Promise<void>): Promise<void> {
+  try {
+    await write()
+  } catch (error) {
+    if (!(error instanceof SettingsConflictError)) throw error
+    await write()
+  }
+}
+
+export interface FallbackDeps {
+  journal: (kind: string, detail: string) => void
+  alert: Alerter
+  /** 持久化翻译状态（journal 命名空间内）。 */
+  readState(): FallbackStateT | null
+  writeState(state: FallbackStateT | null): Promise<void>
+}
+
+/** 装配 LLM 应急翻译：启动后及 settings/llm 变化时评估一次（并发合并）。 */
+export function installLlmFallback(ctx: Context, deps: FallbackDeps): void {
+  const logger = ctx.logger('lifeboat')
+  const settings = ctx.settings as SettingsProvider
+  const writes = settings as unknown as SettingsWrite
+  const settingsFile = dshHomePath('settings.yaml')
+  let inFlight: Promise<void> | undefined
+
+  const listProviderIds = (): Set<string> =>
+    new Set(ctx.llm.listProviders().map((p) => p.id))
+
+  async function activate(provider: string, model: string): Promise<void> {
+    const section = await readRawSection(settingsFile, RAW_NS_LLM_PI).catch(() => undefined)
+    const providers = section?.providers as Record<string, RawProvider> | undefined
+    if (providers === undefined || providers[provider] === undefined) {
+      deps.alert(
+        '[DSH] 默认模型不可用且无配置可翻译',
+        `默认模型的 provider "${provider}" 没有已注册 adapter，且 ${RAW_NS_LLM_PI} 配置中找不到对应条目，无法应急翻译。请手动修复。`,
+      )
+      return
+    }
+    const translated = translateProviders(providers)
+    const fbProvider = `${provider}${FALLBACK_SUFFIX}`
+    await writeWithRetry(() => writes.update(NS_PI_AI, { providers: translated }))
+    await writeWithRetry(() => writes.update(NS_AGENT_DEFAULT, { provider: fbProvider, model }))
+    await deps.writeState({
+      active: true,
+      originalProvider: provider,
+      originalModel: model,
+      fallbackProvider: fbProvider,
+      providers: Object.keys(translated),
+      at: new Date().toISOString(),
+    })
+    deps.journal('llm-fallback', `默认模型切换到 ${fbProvider}/${model}（翻译 ${Object.keys(translated).length} 个 provider）`)
+    deps.alert(
+      '[DSH] LLM 配置已应急翻译',
+      `默认模型的 provider "${provider}" 不可用（llm-pi 缺席？），已把 ${RAW_NS_LLM_PI} 配置翻译为官方 llm-pi-ai 路由（-fb 后缀）并切换默认模型为 ${fbProvider}/${model}。源插件恢复后将自动还原。`,
+    )
+  }
+
+  async function revert(state: FallbackStateT): Promise<void> {
+    const ops = state.providers.map((key) => ({ op: 'unset' as const, path: ['providers', key] }))
+    await writeWithRetry(() => writes.mutate(NS_PI_AI, ops))
+    await writeWithRetry(() =>
+      writes.update(NS_AGENT_DEFAULT, { provider: state.originalProvider, model: state.originalModel }),
+    )
+    await deps.writeState(null)
+    deps.journal('llm-fallback-revert', `默认模型还原为 ${state.originalProvider}/${state.originalModel}`)
+    deps.alert(
+      '[DSH] LLM 应急翻译已还原',
+      `provider "${state.originalProvider}" 恢复健康，默认模型已还原，临时翻译路由已清除。`,
+    )
+  }
+
+  async function evaluate(): Promise<void> {
+    const state = deps.readState()
+    const ids = listProviderIds()
+    if (state?.active) {
+      if (ids.has(state.originalProvider)) await revert(state)
+      return
+    }
+    const def = ctx.settings.get(NS_AGENT_DEFAULT) as { provider?: string; model?: string } | undefined
+    if (def?.provider === undefined || def.model === undefined) return
+    if (ids.has(def.provider)) return
+    await activate(def.provider, def.model)
+  }
+
+  const run = (): void => {
+    inFlight ??= evaluate()
+      .catch((error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`llm fallback 评估失败: ${message}`)
+        deps.journal('llm-fallback-error', message)
+      })
+      .finally(() => {
+        inFlight = undefined
+      })
+  }
+
+  // 首次评估延迟到启动收尾：lifeboat 首位加载时兄弟插件的 adapter 尚未注册，
+  // 立刻评估会把"还没加载"误判为"缺席"。事件订阅覆盖后续变化。
+  const bootTimer = setTimeout(run, 10_000)
+  ctx.effect(
+    () => () => clearTimeout(bootTimer),
+    'lifeboat: fallback boot timer',
+  )
+  ctx.on('ready' as never, run)
+  // 只响应与本判定相关的命名空间变化：journal 写自身命名空间，不过滤会自触发循环。
+  const WATCHED_NS = new Set(['agent-default-model', 'llm-pi-ai', RAW_NS_LLM_PI])
+  ctx.root.on('settings/updated' as never, (ns: unknown) => {
+    if (typeof ns === 'string' && WATCHED_NS.has(ns)) run()
+  })
+  ctx.root.on('llm/adapters-updated' as never, run)
+}

package/src/index.ts

@@ -0,0 +1,84 @@
+/**
+ * dsh 插件：故障救生艇。
+ * 职责（全部事件触发，平时零开销）：
+ * 1. 故障隔离——兄弟 dsh-plus 插件 fiber FAILED 时（host 侧直接监听，浏览器侧
+ *    经哨兵回报），向 profile 用户 patch 层写入 disabled 覆盖；重启/刷新后
+ *    失败插件缺席、其余正常，修复后删覆盖即恢复。
+ * 2. LLM 应急翻译——默认模型 provider 无 adapter 时，把 dsh-plus-llm-pi 配置
+ *    临时翻译为官方 llm-pi-ai 路由并切换默认模型，恢复后自动还原。
+ * 3. 告警与 journal——一切动作记录进自身 settings 命名空间，并经 notify-email
+ *    发邮件（缺席降级为日志）。
+ *
+ * 零 dsh-plus 内部依赖铁律：不 import 本仓库任何其他包，防止共享代码故障团灭。
+ * @module @dsh-plus/lifeboat
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+
+import { Config, JournalSchema, SETTINGS_NS, type FallbackStateT, type JournalDoc, type LifeboatConfig } from './config.ts'
+import { installAlerter } from './notify.ts'
+import { createQuarantine, installHostWatch } from './quarantine.ts'
+import { registerQuarantineApi } from './quarantine-api.ts'
+import { installLlmFallback } from './fallback-llm.ts'
+
+export const name = 'dsh-plus-lifeboat'
+
+export const inject = ['settings', 'llm'] as const
+
+export { Config }
+
+/** journal 上限：只留最近 50 条，防长期运行膨胀。 */
+const JOURNAL_CAP = 50
+
+export function apply(ctx: Context, config: LifeboatConfig): void {
+  const logger = ctx.logger('lifeboat')
+
+  // 自身命名空间：journal 与翻译状态的持久化。schema 宽松，注册失败也不能
+  // 拖垮救生艇——降级为内存态（重启丢失 journal，但隔离/翻译功能仍在）。
+  let doc: JournalDoc = { journal: [], llmFallback: null }
+  let persist: ((patch: object) => Promise<void>) | undefined
+  try {
+    const scope = ctx.settings.register(SETTINGS_NS, JournalSchema)
+    doc = scope.get()
+    persist = (patch) => scope.update(patch)
+  } catch (error) {
+    logger.warn(`journal 命名空间注册失败，降级为内存态: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  const journal = (kind: string, detail: string): void => {
+    doc = { ...doc, journal: [...doc.journal, { at: new Date().toISOString(), kind, detail }].slice(-JOURNAL_CAP) }
+    void persist?.({ journal: doc.journal }).catch((error: unknown) => {
+      logger.warn(`journal 持久化失败: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+
+  const alert = installAlerter(ctx, journal)
+
+  if (config.enabled) {
+    const patchFile = config.patchFile.length > 0
+      ? config.patchFile
+      : dshHomePath('profiles', 'web', 'cordis.patch.yml')
+    const quarantine = createQuarantine(ctx, {
+      patchFile,
+      alertCooldownMs: config.alertCooldownMs,
+      journal,
+      alert,
+    })
+    installHostWatch(ctx, quarantine)
+    ctx.inject(['webServer'], (webCtx) => {
+      registerQuarantineApi(webCtx, quarantine)
+    })
+  }
+
+  if (config.llmFallback) {
+    installLlmFallback(ctx, {
+      journal,
+      alert,
+      readState: () => doc.llmFallback,
+      writeState: async (state: FallbackStateT | null) => {
+        doc = { ...doc, llmFallback: state }
+        await persist?.({ llmFallback: state })
+      },
+    })
+  }
+}

package/src/notify.ts

@@ -0,0 +1,41 @@
+/**
+ * 告警出口：优先复用 notify-email 服务（懒取，不 inject 不 import——notify-email
+ * 自身被隔离时救生艇仍需工作），缺席降级为 logger.warn。所有告警同时进 journal。
+ * @module lifeboat/notify
+ */
+import type { Context, Logger } from '@deepseek-ai/cordis'
+
+/** notify-email 服务的最小 duck 接口（避免 import 依赖）。 */
+interface NotifyEmailLike {
+  sendNotice?(notice: { subject: string; text: string }): Promise<{ ok: boolean; detail: string }>
+}
+
+export type Alerter = (subject: string, text: string) => void
+
+/**
+ * 装配告警出口。返回同步派单函数：内部异步发送，失败只记日志。
+ * notify-email 出现时升级为邮件；全程 journal 兜底可溯。
+ */
+export function installAlerter(ctx: Context, journal: (kind: string, detail: string) => void): Alerter {
+  const logger: Logger = ctx.logger('lifeboat')
+  let mailer: NotifyEmailLike | undefined
+  ctx.inject(['notifyEmail' as never], (mailCtx) => {
+    mailer = (mailCtx as unknown as { notifyEmail: NotifyEmailLike }).notifyEmail
+    return () => {
+      mailer = undefined
+    }
+  })
+  return (subject, text) => {
+    journal('alert', `${subject} | ${text}`)
+    const active = mailer
+    if (!active?.sendNotice) {
+      logger.warn(`${subject} —— ${text}`)
+      return
+    }
+    void active.sendNotice({ subject, text }).then((result) => {
+      if (!result.ok) logger.warn(`邮件告警投递失败: ${result.detail}`)
+    }, (error: unknown) => {
+      logger.warn(`邮件告警异常: ${error instanceof Error ? error.message : String(error)}`)
+    })
+  }
+}

package/src/ns.ts

@@ -0,0 +1,5 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+ * @module lifeboat/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-lifeboat'

package/src/patch-file.ts

@@ -0,0 +1,45 @@
+/**
+ * profile 用户 patch 文件（cordis.patch.yml）的安全写入。
+ * 官方预留的逃生门：用户层支持 id 定向 disabled，覆盖 bundle 层 insert。
+ * 写入纪律：先备份、幂等（已禁用跳过）、原子落盘（tmp + rename），失败抛错由调用方告警，
+ * 绝不写半个文件、绝不改动既有条目内容。
+ * @module lifeboat/patch-file
+ */
+import { copyFile, readFile, rename, writeFile } from 'node:fs/promises'
+
+import { parseDocument } from 'yaml'
+
+/** patch 文件顶层条目（松散视图：只关心 id/disabled/insert 三个键）。 */
+export interface PatchEntry {
+  id?: string
+  disabled?: boolean
+  insert?: PatchEntry[]
+  [key: string]: unknown
+}
+
+/** 条目（含 insert 子列表）中是否已有针对 targetId 的 disabled 覆盖。 */
+export function hasDisable(entries: PatchEntry[], targetId: string): boolean {
+  for (const entry of entries) {
+    if (entry.id === targetId && entry.disabled === true) return true
+    if (Array.isArray(entry.insert) && hasDisable(entry.insert, targetId)) return true
+  }
+  return false
+}
+
+/**
+ * 向 patch 文件追加一条禁用覆盖；返回是否实际写入（已存在禁用则跳过）。
+ * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+ */
+export async function appendDisable(patchFile: string, targetId: string): Promise<boolean> {
+  const text = await readFile(patchFile, 'utf-8')
+  const doc = parseDocument(text)
+  const root = doc.toJS() as unknown
+  if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`)
+  if (hasDisable(root as PatchEntry[], targetId)) return false
+  await copyFile(patchFile, `${patchFile}.lifeboat.bak`)
+  doc.add({ id: targetId, disabled: true })
+  const tmp = `${patchFile}.lifeboat.tmp`
+  await writeFile(tmp, doc.toString(), 'utf-8')
+  await rename(tmp, patchFile)
+  return true
+}

package/src/quarantine-api.ts

@@ -0,0 +1,56 @@
+/**
+ * 哨兵回报的 host 接收面：POST /dsh-plus/lifeboat/quarantine {name}
+ * 仅监听 dsh web 同源（webserver 默认 127.0.0.1），与 GUI 其余面同等暴露面。
+ * @module lifeboat/quarantine-api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+
+import type { Quarantine } from './quarantine.ts'
+
+const ROUTE = '/dsh-plus/lifeboat/quarantine'
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')))
+    req.on('error', reject)
+  })
+}
+
+/** 注册哨兵回报路由（webServer 缺失时由调用方保证不调用）。 */
+export function registerQuarantineApi(ctx: Context, q: Quarantine): void {
+  const logger = ctx.logger('lifeboat')
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE,
+    handler: async (req, res) => {
+      try {
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { error: 'POST only' })
+          return
+        }
+        const body = JSON.parse(await readBody(req)) as { name?: unknown }
+        if (typeof body.name !== 'string') {
+          sendJson(res, 400, { error: 'missing name' })
+          return
+        }
+        void q.quarantine(body.name, 'client')
+        sendJson(res, 200, { ok: true })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn(`quarantine api failed: ${message}`)
+        if (!res.headersSent) sendJson(res, 400, { error: message })
+        else res.end()
+      }
+    },
+  })
+}

package/src/quarantine.ts

@@ -0,0 +1,84 @@
+/**
+ * 故障隔离：监听兄弟 dsh-plus 插件的 fiber FAILED 转移（host 侧直接监听；
+ * 浏览器侧经哨兵 HTTP 回报），把对应 loader 条目禁用写进 profile 用户 patch 层。
+ * 只处理 dsh-plus- 前缀且排除自身/bundle——官方条目与救生艇自身一概不碰。
+ * @module lifeboat/quarantine
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import type { Alerter } from './notify.ts'
+import { appendDisable } from './patch-file.ts'
+
+/** Runtime mirror: FiberState 是 cordis 跨包 const enum（官方 dsh-host-plugin-inventory 同款做法）。 */
+const FIBER_FAILED = 3
+
+/** 永不隔离的条目：救生艇自身与聚合 bundle（禁了它们等于关掉整个防线/全家）。 */
+const EXCLUDED = new Set(['dsh-plus-lifeboat', 'dsh-plus-bundle-main'])
+
+const GUARD_RE = /^dsh-plus-[a-z0-9-]+$/
+
+/** 名字是否属于可隔离的 dsh-plus 兄弟插件（entry id 与插件 name 同字面量是本仓库约定）。 */
+export function isGuardedPlugin(name: unknown): name is string {
+  return typeof name === 'string' && GUARD_RE.test(name) && !EXCLUDED.has(name)
+}
+
+export interface QuarantineDeps {
+  patchFile: string
+  alertCooldownMs: number
+  journal: (kind: string, detail: string) => void
+  alert: Alerter
+}
+
+export interface Quarantine {
+  /** 隔离指定插件（幂等；冷却期内重复触发只计 journal 不写文件）。 */
+  quarantine(name: string, origin: 'host' | 'client'): Promise<void>
+}
+
+/** 装配隔离执行器（纯逻辑，可测）。 */
+export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine {
+  const logger = ctx.logger('lifeboat')
+  const lastAlertAt = new Map<string, number>()
+  const inFlight = new Set<string>()
+
+  async function quarantine(name: string, origin: 'host' | 'client'): Promise<void> {
+    if (!isGuardedPlugin(name)) return
+    if (inFlight.has(name)) return
+    inFlight.add(name)
+    try {
+      const written = await appendDisable(deps.patchFile, name)
+      deps.journal('quarantine', `${name}（来源 ${origin}，${written ? '已写入禁用' : '已存在禁用'}）`)
+      const now = Date.now()
+      const last = lastAlertAt.get(name) ?? 0
+      if (now - last >= deps.alertCooldownMs) {
+        lastAlertAt.set(name, now)
+        deps.alert(
+          `[DSH] 插件 ${name} 加载失败，已自动隔离`,
+          `检测到插件 ${name} 的 fiber 进入 FAILED（来源：${origin}）。\n` +
+            `已向 ${deps.patchFile} 写入 disabled 覆盖，重启/刷新后该插件不再加载，其余插件不受影响。\n` +
+            `修复后删除该条覆盖即可恢复。`,
+        )
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      logger.warn(`隔离 ${name} 失败: ${message}`)
+      deps.journal('quarantine-error', `${name}: ${message}`)
+      deps.alert(`[DSH] 插件 ${name} 加载失败，自动隔离未果`, `隔离写入失败：${message}\n请手动在 patch 层禁用该插件。`)
+    } finally {
+      inFlight.delete(name)
+    }
+  }
+
+  return { quarantine }
+}
+
+/**
+ * host 侧监听：root context 上兄弟 fiber 的 internal/status 转移。
+ * fiber.name 对 loader 条目即插件 display name（模块导出的 name 字段）。
+ */
+export function installHostWatch(ctx: Context, q: Quarantine): void {
+  ctx.root.on('internal/status', (fiber: { state: number; name: string }) => {
+    if (fiber.state !== FIBER_FAILED) return
+    if (!isGuardedPlugin(fiber.name)) return
+    void q.quarantine(fiber.name, 'host')
+  })
+}