@dsh-plus/lifeboat 0.1.3 → 0.1.4

package/lib/client.js

@@ -3,37 +3,35 @@ window.__ModuleLoader__.load({
 	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) => {
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#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 = /* @__PURE__ */ new Set(["dsh-plus-lifeboat", "dsh-plus-bundle-main"]);
+		const GUARD_RE = /^dsh-plus-[a-z0-9-]+$/;
+		function apply(ctx) {
 			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(() => {});
+				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 {}
-		});
-	} catch {}
-}
-
-//#endregion
-exports.apply = apply;
-exports.name = name;
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.name = name;
 		return module.exports;
 	}
 });

package/lib/index.d.ts

@@ -1,9 +1,6 @@
-import "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
-
 //#region src/config.d.ts
-
 /** 行级配置：全部有默认值，正常部署零配置。 */
 declare const Config: z<Schemastery.ObjectS<{
   enabled: z<boolean, boolean>;

package/lib/index.js

@@ -3,18 +3,18 @@ import { SettingsConflictError, settingsNamespace } from "@deepseek-ai/dsh-setti
 import z from "@deepseek-ai/schemastery";
 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
+/**
+* 配置与 journal 单一事实源。
+* - 行级 Config（cordis 组合层）：救生艇自身行为开关，dev/prod patch 层可覆盖。
+* - settings 命名空间 dsh-plus-lifeboat：运行期 journal 与 LLM 应急翻译状态，
+*   经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml，重启后可据此还原。
+* schema 刻意宽松：lifeboat 是最后防线，自身命名空间的数据问题绝不能让它起不来。
+* @module lifeboat/config
+*/
 /** settings 命名空间（品牌化后供 settings 服务注册/读写）。 */
-const SETTINGS_NS = settingsNamespace(SETTINGS_NS$1);
+const SETTINGS_NS = settingsNamespace("dsh-plus-lifeboat");
 /** 行级配置：全部有默认值，正常部署零配置。 */
 const Config = z.object({
 	enabled: z.boolean().description("故障隔离总开关").default(true),
@@ -42,18 +42,27 @@ 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/fallback-llm.ts
+/**
+* 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
+*/
 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([
+const REASONING_LEVELS = /* @__PURE__ */ new Set([
 	"off",
 	"minimal",
 	"low",
@@ -120,12 +129,13 @@ function translateProvider(routeKey, raw) {
 /** 整表翻译：键加 -fb 后缀（纯函数）。 */
 function translateProviders(providers) {
 	const out = {};
-	for (const [key, raw] of Object.entries(providers)) out[`${key}${FALLBACK_SUFFIX}`] = translateProvider(key, raw);
+	for (const [key, raw] of Object.entries(providers)) out[`${key}-fb`] = translateProvider(key, raw);
 	return out;
 }
 /** 读 settings.yaml 原始文档的指定段落（只读；文件/段落缺失返回 undefined）。 */
 async function readRawSection(settingsFile, ns) {
-	const section = parseDocument(await readFile(settingsFile, "utf-8")).toJS()[ns];
+	const text = await readFile(settingsFile, "utf-8");
+	const section = parseDocument(text).toJS()[ns];
 	if (typeof section !== "object" || section === null) return void 0;
 	return section;
 }
@@ -154,7 +164,7 @@ function installLlmFallback(ctx, deps) {
 			return;
 		}
 		const translated = translateProviders(providers);
-		const fbProvider = `${provider}${FALLBACK_SUFFIX}`;
+		const fbProvider = `${provider}-fb`;
 		await writeWithRetry(() => writes.update(NS_PI_AI, { providers: translated }));
 		await writeWithRetry(() => writes.update(NS_AGENT_DEFAULT, {
 			provider: fbProvider,
@@ -210,7 +220,7 @@ function installLlmFallback(ctx, deps) {
 	const bootTimer = setTimeout(run, 1e4);
 	ctx.effect(() => () => clearTimeout(bootTimer), "lifeboat: fallback boot timer");
 	ctx.on("ready", run);
-	const WATCHED_NS = new Set([
+	const WATCHED_NS = /* @__PURE__ */ new Set([
 		"agent-default-model",
 		"llm-pi-ai",
 		RAW_NS_LLM_PI
@@ -220,7 +230,6 @@ function installLlmFallback(ctx, deps) {
 	});
 	ctx.root.on("llm/adapters-updated", run);
 }
-
 //#endregion
 //#region src/notify.ts
 /**
@@ -253,9 +262,15 @@ function installAlerter(ctx, journal) {
 		});
 	};
 }
-
 //#endregion
 //#region src/patch-file.ts
+/**
+* profile 用户 patch 文件（cordis.patch.yml）的安全写入。
+* 官方预留的逃生门：用户层支持 id 定向 disabled，覆盖 bundle 层 insert。
+* 写入纪律：先备份、幂等（已禁用跳过）、原子落盘（tmp + rename），失败抛错由调用方告警，
+* 绝不写半个文件、绝不改动既有条目内容。
+* @module lifeboat/patch-file
+*/
 /** 条目（含 insert 子列表）中是否已有针对 targetId 的 disabled 覆盖。 */
 function hasDisable(entries, targetId) {
 	for (const entry of entries) {
@@ -269,7 +284,8 @@ function hasDisable(entries, targetId) {
 * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
 */
 async function appendDisable(patchFile, targetId) {
-	const doc = parseDocument(await readFile(patchFile, "utf-8"));
+	const text = await readFile(patchFile, "utf-8");
+	const doc = parseDocument(text);
 	const root = doc.toJS();
 	if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`);
 	if (hasDisable(root, targetId)) return false;
@@ -283,42 +299,51 @@ async function appendDisable(patchFile, targetId) {
 	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 EXCLUDED = /* @__PURE__ */ 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 isGuardedPlugin(name) {
+	return typeof name === "string" && GUARD_RE.test(name) && !EXCLUDED.has(name);
+}
+/** 告警/journal 里的失败原因摘录上限，防长堆栈淹没通知渠道。 */
+const REASON_CAP = 500;
+/** 提取 fiber 失败原因的短文本（无则空串）；cordis 把错误挂在 fiber._error。 */
+function reasonText(reason) {
+	if (reason === void 0 || reason === null) return "";
+	const text = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
+	return text.length > REASON_CAP ? `${text.slice(0, REASON_CAP)}…` : text;
 }
 /** 装配隔离执行器（纯逻辑，可测）。 */
 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);
+	async function quarantine(name, origin, reason) {
+		if (!isGuardedPlugin(name)) return;
+		if (inFlight.has(name)) return;
+		inFlight.add(name);
+		const reasonBlock = reasonText(reason);
+		const reasonSuffix = reasonBlock === "" ? "" : `\n失败原因：\n${reasonBlock}`;
 		try {
-			const written = await appendDisable(deps.patchFile, name$1);
-			deps.journal("quarantine", `${name$1}（来源 ${origin}，${written ? "已写入禁用" : "已存在禁用"}）`);
+			const written = await appendDisable(deps.patchFile, name);
+			deps.journal("quarantine", `${name}（来源 ${origin}，${written ? "已写入禁用" : "已存在禁用"}）${reasonSuffix}`);
 			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修复后删除该条覆盖即可恢复。`);
+			if (now - (lastAlertAt.get(name) ?? 0) >= deps.alertCooldownMs) {
+				lastAlertAt.set(name, now);
+				deps.alert(`[DSH] 插件 ${name} 加载失败，已自动隔离`, `检测到插件 ${name} 的 fiber 进入 FAILED（来源：${origin}）。\n已向 ${deps.patchFile} 写入 disabled 覆盖，重启/刷新后该插件不再加载，其余插件不受影响。\n修复后删除该条覆盖即可恢复。${reasonSuffix}`);
 			}
 		} 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 层禁用该插件。`);
+			logger.warn(`隔离 ${name} 失败: ${message}`);
+			deps.journal("quarantine-error", `${name}: ${message}`);
+			deps.alert(`[DSH] 插件 ${name} 加载失败，自动隔离未果`, `隔离写入失败：${message}\n请手动在 patch 层禁用该插件。`);
 		} finally {
-			inFlight.delete(name$1);
+			inFlight.delete(name);
 		}
 	}
 	return { quarantine };
@@ -331,10 +356,9 @@ 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");
+		q.quarantine(fiber.name, "host", fiber._error);
 	});
 }
-
 //#endregion
 //#region src/quarantine-api.ts
 const ROUTE = "/dsh-plus/lifeboat/quarantine";
@@ -378,13 +402,10 @@ function registerQuarantineApi(ctx, q) {
 		}
 	});
 }
-
 //#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 = {
@@ -406,7 +427,7 @@ function apply(ctx, config) {
 				at: (/* @__PURE__ */ new Date()).toISOString(),
 				kind,
 				detail
-			}].slice(-JOURNAL_CAP)
+			}].slice(-50)
 		};
 		persist?.({ journal: doc.journal }).catch((error) => {
 			logger.warn(`journal 持久化失败: ${error instanceof Error ? error.message : String(error)}`);
@@ -438,6 +459,5 @@ function apply(ctx, config) {
 		}
 	});
 }
-
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, inject, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/lifeboat",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "dsh-plus service plugin: 故障救生艇——兄弟插件崩溃时自动隔离（写用户 patch 层禁用），llm-pi 缺席时把其配置临时翻译为官方 llm-pi-ai 路由，恢复后自动还原",
   "type": "module",
   "main": "lib/index.js",
@@ -38,10 +38,10 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-settings": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
     "@deepseek-ai/schemastery": "3.18.1"
   },
   "publishConfig": {

package/src/quarantine.ts

@@ -31,7 +31,17 @@ export interface QuarantineDeps {
 
 export interface Quarantine {
   /** 隔离指定插件（幂等；冷却期内重复触发只计 journal 不写文件）。 */
-  quarantine(name: string, origin: 'host' | 'client'): Promise<void>
+  quarantine(name: string, origin: 'host' | 'client', reason?: unknown): Promise<void>
+}
+
+/** 告警/journal 里的失败原因摘录上限，防长堆栈淹没通知渠道。 */
+const REASON_CAP = 500
+
+/** 提取 fiber 失败原因的短文本（无则空串）；cordis 把错误挂在 fiber._error。 */
+function reasonText(reason: unknown): string {
+  if (reason === undefined || reason === null) return ''
+  const text = reason instanceof Error ? (reason.stack ?? reason.message) : String(reason)
+  return text.length > REASON_CAP ? `${text.slice(0, REASON_CAP)}…` : text
 }
 
 /** 装配隔离执行器（纯逻辑，可测）。 */
@@ -40,15 +50,21 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
   const lastAlertAt = new Map<string, number>()
   const inFlight = new Set<string>()
 
-  async function quarantine(name: string, origin: 'host' | 'client'): Promise<void> {
+  async function quarantine(
+    name: string,
+    origin: 'host' | 'client',
+    reason?: unknown,
+  ): Promise<void> {
     if (!isGuardedPlugin(name)) return
     if (inFlight.has(name)) return
     inFlight.add(name)
+    const reasonBlock = reasonText(reason)
+    const reasonSuffix = reasonBlock === '' ? '' : `\n失败原因：\n${reasonBlock}`
     try {
       const written = await appendDisable(deps.patchFile, name)
       deps.journal(
         'quarantine',
-        `${name}（来源 ${origin}，${written ? '已写入禁用' : '已存在禁用'}）`,
+        `${name}（来源 ${origin}，${written ? '已写入禁用' : '已存在禁用'}）${reasonSuffix}`,
       )
       const now = Date.now()
       const last = lastAlertAt.get(name) ?? 0
@@ -58,7 +74,7 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
           `[DSH] 插件 ${name} 加载失败，已自动隔离`,
           `检测到插件 ${name} 的 fiber 进入 FAILED（来源：${origin}）。\n` +
             `已向 ${deps.patchFile} 写入 disabled 覆盖，重启/刷新后该插件不再加载，其余插件不受影响。\n` +
-            `修复后删除该条覆盖即可恢复。`,
+            `修复后删除该条覆盖即可恢复。${reasonSuffix}`,
         )
       }
     } catch (error) {
@@ -82,9 +98,9 @@ export function createQuarantine(ctx: Context, deps: QuarantineDeps): Quarantine
  * fiber.name 对 loader 条目即插件 display name（模块导出的 name 字段）。
  */
 export function installHostWatch(ctx: Context, q: Quarantine): void {
-  ctx.root.on('internal/status', (fiber: { state: number; name: string }) => {
+  ctx.root.on('internal/status', (fiber: { state: number; name: string; _error?: unknown }) => {
     if (fiber.state !== FIBER_FAILED) return
     if (!isGuardedPlugin(fiber.name)) return
-    void q.quarantine(fiber.name, 'host')
+    void q.quarantine(fiber.name, 'host', fiber._error)
   })
 }