@dsh-plus/lifeboat 0.1.6 → 0.2.0

package/lib/index.js

@@ -61,6 +61,16 @@ const NS_AGENT_DEFAULT = settingsNamespace("agent-default-model");
 const RAW_NS_LLM_PI = "dsh-plus-llm-pi";
 /** 官方配置路径物化的 compat 子集（其余字段降级期丢弃）。 */
 const COMPAT_WHITELIST = ["thinkingFormat", "supportsReasoningEffort"];
+/**
+* master 官方 llm-pi-ai 的 COMPAT_GATES（llm-pi-ai/src/catalog.ts）：每个 compat
+* 字段按协议门控，写时经 assertOfferedCompatFields 拒绝不适配字段——thinkingFormat /
+* supportsReasoningEffort 仅 openai-completions 提供。翻译按推断 api 过滤，避免
+* 整段 compat 写入被官方校验拒绝。
+*/
+const COMPAT_OFFER_APIS = {
+	thinkingFormat: /* @__PURE__ */ new Set(["openai-completions"]),
+	supportsReasoningEffort: /* @__PURE__ */ new Set(["openai-completions"])
+};
 /** 官方 reasoning 词表（ModelThinkingLevel 的保守子集），不在其中的值丢弃。 */
 const REASONING_LEVELS = /* @__PURE__ */ new Set([
 	"off",
@@ -112,8 +122,14 @@ function translateProvider(routeKey, raw) {
 	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 api = inferApi(routeKey, raw);
 		const compat = {};
-		for (const key of COMPAT_WHITELIST) if (raw.compat[key] !== void 0) compat[key] = raw.compat[key];
+		for (const key of COMPAT_WHITELIST) {
+			const value = raw.compat[key];
+			if (value === void 0 || value === null) continue;
+			if (!COMPAT_OFFER_APIS[key]?.has(api)) continue;
+			compat[key] = value;
+		}
 		if (Object.keys(compat).length > 0) out.compat = compat;
 	}
 	if (Array.isArray(raw.models) && raw.models.length > 0) out.models = raw.models.map((m) => {
@@ -139,14 +155,12 @@ async function readRawSection(settingsFile, ns) {
 	if (typeof section !== "object" || section === null) return void 0;
 	return section;
 }
-/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。
-*  冲突判定双条件：instanceof 覆盖同版本副本；error.code 覆盖跨版本副本
-*  （插件自带 rc.7 依赖与 host rc.8 抛错时 instanceof 为 false）。 */
+/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。 */
 async function writeWithRetry(write) {
 	try {
 		await write();
 	} catch (error) {
-		if (!(error instanceof SettingsConflictError || typeof error === "object" && error !== null && error.code === "SETTINGS_CONFLICT")) throw error;
+		if (!(error instanceof SettingsConflictError)) throw error;
 		await write();
 	}
 }
@@ -165,11 +179,16 @@ function installLlmFallback(ctx, deps) {
 		}
 		const translated = translateProviders(providers);
 		const fbProvider = `${provider}-fb`;
-		await writeWithRetry(() => writes.update(NS_PI_AI, { providers: translated }));
-		await writeWithRetry(() => writes.update(NS_AGENT_DEFAULT, {
-			provider: fbProvider,
-			model
-		}));
+		try {
+			await writes.update(NS_PI_AI, { providers: translated });
+			await writes.update(NS_AGENT_DEFAULT, {
+				provider: fbProvider,
+				model
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`翻译失败（官方 llm-pi-ai 拒绝写入翻译后的配置）: ${message}`);
+		}
 		await deps.writeState({
 			active: true,
 			originalProvider: provider,
@@ -237,6 +256,16 @@ function installLlmFallback(ctx, deps) {
 * 官方预留的逃生门：用户层支持 id 定向 disabled，覆盖 bundle 层 insert。
 * 写入纪律：先备份、幂等（已禁用跳过）、原子落盘（tmp + rename），失败抛错由调用方告警，
 * 绝不写半个文件、绝不改动既有条目内容。
+*
+* 2026-08-30 事故教训（保险丝必须先于负载可靠）：
+* 1. 并发写竞争：多个插件同一毫秒 FAILED → 多路 appendDisable 共享固定 tmp 名
+*    → rename ENOENT / 读改写丢更新。修复：进程内按文件串行化（promise 链锁）
+*    + tmp 名带 pid/随机后缀。
+* 2. YAML 带错仍强行 stringify：parseDocument 对语法错误不抛而收集进
+*    doc.errors，后续 toString 抛 "Document with errors cannot be stringified"
+*    → 隔离永远写不进去。修复：写前校验 doc.errors；文件已坏时走重建通道
+*    （备份坏文件 → 容错打捞既有 disabled 条目 → 重写干净文档），
+*    隔离落盘优先于保留坏文件。
 * @module lifeboat/patch-file
 */
 /** 条目（含 insert 子列表）中是否已有针对 targetId 的 disabled 覆盖。 */
@@ -247,66 +276,116 @@ function hasDisable(entries, targetId) {
 	}
 	return false;
 }
+/** 顶层条目中已禁用的 id 列表（不含 insert 子列表；用户层 disabled 语义只在顶层）。 */
+function listDisabled(entries) {
+	const out = [];
+	for (const entry of entries) if (typeof entry.id === "string" && entry.disabled === true) out.push(entry.id);
+	return out;
+}
+/** 进程内按文件串行化：并发隔离写同一 patch 文件时消除读改写竞争。 */
+const fileLocks = /* @__PURE__ */ new Map();
+function withFileLock(file, fn) {
+	const next = (fileLocks.get(file) ?? Promise.resolve()).then(fn, fn);
+	fileLocks.set(file, next.catch(() => {}));
+	return next;
+}
+/** 唯一 tmp 名（并发/重入不留共享路径），rename 原子落盘。 */
+async function atomicWrite(patchFile, content) {
+	const tmp = `${patchFile}.lifeboat.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+	await writeFile(tmp, content, "utf-8");
+	await rename(tmp, patchFile);
+}
+/**
+* 容错打捞坏 YAML 文本中既有的顶层 disabled 条目（best-effort）：
+* `- id: <name>` 与同条块内的 `disabled: true` 配对即认定。
+* 坏文件里可能躺着此前已隔离的插件——重建时漏掉它们等于重新放行故障插件。
+*/
+function salvageDisabled(text) {
+	const out = [];
+	for (const match of text.matchAll(/-\s+id:\s*(\S+)([^\0]*?)(?=\n\s*-\s+id:|$)/g)) {
+		const id = match[1];
+		const block = match[2] ?? "";
+		if (id !== void 0 && /\bdisabled:\s*true\b/.test(block)) out.push(id);
+	}
+	return out;
+}
+/**
+* 重建通道：原文件 YAML 已坏（doc.errors 非空）时的隔离写入。
+* 备份坏文件（保留现场）→ 打捞既有 disabled → 重写干净文档。
+* 即使目标已在打捞集中也照样重写——坏文件对 loader 等于不存在，
+* 修复文件本身与写入禁用同等重要；返回值仅报告目标集合是否变化。
+*/
+async function appendDisableRebuild(patchFile, text, targetId) {
+	const salvaged = salvageDisabled(text);
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "-");
+	await copyFile(patchFile, `${patchFile}.broken-${stamp}.bak`);
+	const entries = (salvaged.includes(targetId) ? salvaged : [...salvaged, targetId]).map((id) => `- id: ${id}\n  disabled: true`);
+	await atomicWrite(patchFile, [
+		"# 本文件由 lifeboat 重建：原文件存在 YAML 语法错误，无法安全改写。",
+		`# 原件已备份为同目录 .broken-${stamp}.bak，请人工合并残留自定义条目。`,
+		...entries,
+		""
+	].join("\n"));
+	return !salvaged.includes(targetId);
+}
 /**
 * 向 patch 文件追加一条禁用覆盖；返回是否实际写入（已存在禁用则跳过）。
+* 原文件 YAML 已坏时转重建通道（隔离落盘优先，原件备份待人工合并）。
 * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
 */
 async function appendDisable(patchFile, targetId) {
-	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;
-	await copyFile(patchFile, `${patchFile}.lifeboat.bak`);
-	doc.add({
-		id: targetId,
-		disabled: true
+	return withFileLock(patchFile, async () => {
+		const text = await readFile(patchFile, "utf-8");
+		const doc = parseDocument(text);
+		if (doc.errors.length > 0) return appendDisableRebuild(patchFile, text, targetId);
+		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
+		});
+		await atomicWrite(patchFile, doc.toString());
+		return true;
 	});
-	const tmp = `${patchFile}.lifeboat.tmp`;
-	await writeFile(tmp, doc.toString(), "utf-8");
-	await rename(tmp, patchFile);
-	return true;
-}
-/** 顶层条目中已禁用的 id 列表（不含 insert 子列表；用户层 disabled 语义只在顶层）。 */
-function listDisabled(entries) {
-	const out = [];
-	for (const entry of entries) if (typeof entry.id === "string" && entry.disabled === true) out.push(entry.id);
-	return out;
 }
 /**
 * 从 patch 文件移除针对 targetId 的禁用覆盖（恢复插件）；返回是否实际写入。
 * 只移除「id 定向且 disabled: true」的行，其余内容（注释经 yaml 文档保留、
 * 其他条目）原样不动；无该覆盖时幂等返回 false。
-* @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+* 原文件 YAML 已坏时不猜测改写，抛错指引人工处理（恢复操作有使用者在场）。
+* @throws 文件不可读/顶层不是数组/YAML 语法错误/落盘失败——调用方负责告警。
 */
 async function removeDisable(patchFile, targetId) {
-	const text = await readFile(patchFile, "utf-8");
-	const doc = parseDocument(text);
-	const root = doc.toJS();
-	if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`);
-	let removed = false;
-	const items = doc.contents;
-	if (items?.items !== void 0 && Array.isArray(items.items)) {
-		const headComment = items.items[0]?.commentBefore;
-		doc.contents.items = items.items.filter((item) => {
-			const value = item.toJS?.(doc);
-			if (value !== void 0 && typeof value === "object" && value.id === targetId && value.disabled === true) {
-				removed = true;
-				return false;
+	return withFileLock(patchFile, async () => {
+		const text = await readFile(patchFile, "utf-8");
+		const doc = parseDocument(text);
+		if (doc.errors.length > 0) throw new Error(`patch 文件存在 YAML 语法错误，请人工修复后重试: ${patchFile}`);
+		const root = doc.toJS();
+		if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`);
+		let removed = false;
+		const items = doc.contents;
+		if (items?.items !== void 0 && Array.isArray(items.items)) {
+			const headComment = items.items[0]?.commentBefore;
+			doc.contents.items = items.items.filter((item) => {
+				const value = item.toJS?.(doc);
+				if (value !== void 0 && typeof value === "object" && value.id === targetId && value.disabled === true) {
+					removed = true;
+					return false;
+				}
+				return true;
+			});
+			if (removed && headComment !== void 0 && doc.contents.items.length > 0) {
+				const next = doc.contents.items[0];
+				if (next.commentBefore === void 0) next.commentBefore = headComment;
 			}
-			return true;
-		});
-		if (removed && headComment !== void 0 && doc.contents.items.length > 0) {
-			const next = doc.contents.items[0];
-			if (next.commentBefore === void 0) next.commentBefore = headComment;
 		}
-	}
-	if (!removed) return false;
-	await copyFile(patchFile, `${patchFile}.lifeboat.bak`);
-	const tmp = `${patchFile}.lifeboat.tmp`;
-	await writeFile(tmp, doc.toString(), "utf-8");
-	await rename(tmp, patchFile);
-	return true;
+		if (!removed) return false;
+		await copyFile(patchFile, `${patchFile}.lifeboat.bak`);
+		await atomicWrite(patchFile, doc.toString());
+		return true;
+	});
 }
 //#endregion
 //#region src/quarantine.ts
@@ -375,6 +454,7 @@ function installHostWatch(ctx, q) {
 * - GET  /dsh-plus/lifeboat/status  → journal + 翻译状态 + 当前用户 patch 层已禁用的 dsh-plus 插件
 * - POST /dsh-plus/lifeboat/restore {name} → removeDisable + journal + 告警
 * rc8 用户 patch 层热应用：恢复无需重启，watchUserPatches 即时重载。
+* （0.1.2-alpha.1 基线：用户 patch 层热应用机制保留，行为不变。）
 * @module lifeboat/health-api
 */
 const ROUTE_STATUS = "/dsh-plus/lifeboat/status";
@@ -439,7 +519,7 @@ function registerHealthApi(ctx, deps) {
 				}
 				const written = await removeDisable(deps.patchFile, body.name);
 				deps.journal("quarantine-restore", written ? `${body.name}：已移除用户 patch 层的禁用覆盖（热应用即时恢复）` : `${body.name}：无需恢复（patch 层无禁用覆盖）`);
-				deps.alert("[DSH] 插件恢复", `插件 ${body.name} 的隔离已解除（移除 patch 层禁用覆盖）。${written ? "rc8 热应用即时生效，无需重启。" : "patch 层本无覆盖，可能已被手动恢复。"}`);
+				deps.alert("[DSH] 插件恢复", `插件 ${body.name} 的隔离已解除（移除 patch 层禁用覆盖）。${written ? "patch 层热应用即时生效，无需重启。" : "patch 层本无覆盖，可能已被手动恢复。"}`);
 				sendJson$1(res, 200, {
 					ok: true,
 					written

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/lifeboat",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "dsh-plus service plugin: 故障救生艇——兄弟插件崩溃时自动隔离（写用户 patch 层禁用），llm-pi 缺席时把其配置临时翻译为官方 llm-pi-ai 路由，恢复后自动还原",
   "type": "module",
   "main": "lib/index.js",
@@ -23,29 +23,29 @@
   "dsh": {
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-locale"
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-renderer"
       ],
       "platform": "web"
     }
   },
   "dependencies": {
     "yaml": "^2.6.0",
-    "@dsh-plus/shared": "0.1.5"
+    "@dsh-plus/shared": "0.1.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-home-paths": "^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.2-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.1",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
-    "@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/dsh-home-paths": "0.1.2-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.1",
     "@deepseek-ai/schemastery": "3.18.1",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",

package/src/fallback-llm.ts

@@ -35,6 +35,17 @@ export const FALLBACK_SUFFIX = '-fb'
 /** 官方配置路径物化的 compat 子集（其余字段降级期丢弃）。 */
 const COMPAT_WHITELIST = ['thinkingFormat', 'supportsReasoningEffort'] as const
 
+/**
+ * master 官方 llm-pi-ai 的 COMPAT_GATES（llm-pi-ai/src/catalog.ts）：每个 compat
+ * 字段按协议门控，写时经 assertOfferedCompatFields 拒绝不适配字段——thinkingFormat /
+ * supportsReasoningEffort 仅 openai-completions 提供。翻译按推断 api 过滤，避免
+ * 整段 compat 写入被官方校验拒绝。
+ */
+const COMPAT_OFFER_APIS: Readonly<Record<string, ReadonlySet<string>>> = {
+  thinkingFormat: new Set(['openai-completions']),
+  supportsReasoningEffort: new Set(['openai-completions']),
+}
+
 /** 官方 reasoning 词表（ModelThinkingLevel 的保守子集），不在其中的值丢弃。 */
 const REASONING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
 
@@ -124,9 +135,15 @@ export function translateProvider(routeKey: string, raw: RawProvider): Translate
   if (Array.isArray(raw.defaultInput) && raw.defaultInput.length > 0)
     out.defaultInput = raw.defaultInput
   if (raw.compat !== undefined) {
+    const api = inferApi(routeKey, raw)
     const compat: Record<string, unknown> = {}
     for (const key of COMPAT_WHITELIST) {
-      if (raw.compat[key] !== undefined) compat[key] = raw.compat[key]
+      const value = raw.compat[key]
+      // 空值同样丢弃：官方写时拒绝 valueless 键（catalog.ts assertOfferedCompatFields）
+      if (value === undefined || value === null) continue
+      // 按推断 api 门控：仅写入该协议 offer 的字段，其余丢弃（官方写时拒绝不适配字段）
+      if (!COMPAT_OFFER_APIS[key]?.has(api)) continue
+      compat[key] = value
     }
     if (Object.keys(compat).length > 0) out.compat = compat
   }
@@ -178,19 +195,12 @@ interface SettingsWrite {
   ): Promise<void>
 }
 
-/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。
- *  冲突判定双条件：instanceof 覆盖同版本副本；error.code 覆盖跨版本副本
- *  （插件自带 rc.7 依赖与 host rc.8 抛错时 instanceof 为 false）。 */
+/** 写 settings 带一次冲突重试（用户同时改配置时不抢，放弃并告警）。 */
 async function writeWithRetry(write: () => Promise<void>): Promise<void> {
   try {
     await write()
   } catch (error) {
-    const conflict =
-      error instanceof SettingsConflictError ||
-      (typeof error === 'object' &&
-        error !== null &&
-        (error as { code?: unknown }).code === 'SETTINGS_CONFLICT')
-    if (!conflict) throw error
+    if (!(error instanceof SettingsConflictError)) throw error
     await write()
   }
 }
@@ -225,8 +235,16 @@ export function installLlmFallback(ctx: Context, deps: FallbackDeps): void {
     }
     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 }))
+    try {
+      // 官方 llm-pi-ai 的 installSettingsSection 注册了 validate（assertServiceable），
+      // 写时拒绝不适配的翻译结果；update 无 expectedRevision 本就无条件写，不做冲突
+      // 重试——失败一律分类为「翻译失败」。
+      await writes.update(NS_PI_AI, { providers: translated })
+      await writes.update(NS_AGENT_DEFAULT, { provider: fbProvider, model })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`翻译失败（官方 llm-pi-ai 拒绝写入翻译后的配置）: ${message}`)
+    }
     await deps.writeState({
       active: true,
       originalProvider: provider,
@@ -306,5 +324,9 @@ export function installLlmFallback(ctx: Context, deps: FallbackDeps): void {
   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)
+  // 事件名已核对：master 0.1.2-alpha.1 的 dsh-llm 保留 'llm/adapters-updated'
+  // （packages/llm/llm/src/types.ts:23 module augmentation，index.ts:344 于每次
+  // adapter 注册/注销提交点 dispatch）；@deepseek-ai/dsh-llm 的类型导入已携带该
+  // 声明，无需 as never。
+  ctx.root.on('llm/adapters-updated', run)
 }

package/src/health-api.ts

@@ -3,6 +3,7 @@
  * - GET  /dsh-plus/lifeboat/status  → journal + 翻译状态 + 当前用户 patch 层已禁用的 dsh-plus 插件
  * - POST /dsh-plus/lifeboat/restore {name} → removeDisable + journal + 告警
  * rc8 用户 patch 层热应用：恢复无需重启，watchUserPatches 即时重载。
+ * （0.1.2-alpha.1 基线：用户 patch 层热应用机制保留，行为不变。）
  * @module lifeboat/health-api
  */
 import { readFile } from 'node:fs/promises'
@@ -106,7 +107,7 @@ export function registerHealthApi(ctx: Context, deps: HealthDeps): void {
         deps.alert(
           '[DSH] 插件恢复',
           `插件 ${body.name} 的隔离已解除（移除 patch 层禁用覆盖）。${
-            written ? 'rc8 热应用即时生效，无需重启。' : 'patch 层本无覆盖，可能已被手动恢复。'
+            written ? 'patch 层热应用即时生效，无需重启。' : 'patch 层本无覆盖，可能已被手动恢复。'
           }`,
         )
         sendJson(res, 200, { ok: true, written })

package/src/patch-file.ts

@@ -3,6 +3,16 @@
  * 官方预留的逃生门：用户层支持 id 定向 disabled，覆盖 bundle 层 insert。
  * 写入纪律：先备份、幂等（已禁用跳过）、原子落盘（tmp + rename），失败抛错由调用方告警，
  * 绝不写半个文件、绝不改动既有条目内容。
+ *
+ * 2026-08-30 事故教训（保险丝必须先于负载可靠）：
+ * 1. 并发写竞争：多个插件同一毫秒 FAILED → 多路 appendDisable 共享固定 tmp 名
+ *    → rename ENOENT / 读改写丢更新。修复：进程内按文件串行化（promise 链锁）
+ *    + tmp 名带 pid/随机后缀。
+ * 2. YAML 带错仍强行 stringify：parseDocument 对语法错误不抛而收集进
+ *    doc.errors，后续 toString 抛 "Document with errors cannot be stringified"
+ *    → 隔离永远写不进去。修复：写前校验 doc.errors；文件已坏时走重建通道
+ *    （备份坏文件 → 容错打捞既有 disabled 条目 → 重写干净文档），
+ *    隔离落盘优先于保留坏文件。
  * @module lifeboat/patch-file
  */
 import { copyFile, readFile, rename, writeFile } from 'node:fs/promises'
@@ -26,24 +36,6 @@ export function hasDisable(entries: PatchEntry[], targetId: string): boolean {
   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
-}
-
 /** 顶层条目中已禁用的 id 列表（不含 insert 子列表；用户层 disabled 语义只在顶层）。 */
 export function listDisabled(entries: PatchEntry[]): string[] {
   const out: string[] = []
@@ -53,47 +45,133 @@ export function listDisabled(entries: PatchEntry[]): string[] {
   return out
 }
 
+/** 进程内按文件串行化：并发隔离写同一 patch 文件时消除读改写竞争。 */
+const fileLocks = new Map<string, Promise<unknown>>()
+
+function withFileLock<T>(file: string, fn: () => Promise<T>): Promise<T> {
+  const prev = fileLocks.get(file) ?? Promise.resolve()
+  const next = prev.then(fn, fn)
+  fileLocks.set(
+    file,
+    next.catch(() => {}),
+  )
+  return next
+}
+
+/** 唯一 tmp 名（并发/重入不留共享路径），rename 原子落盘。 */
+async function atomicWrite(patchFile: string, content: string): Promise<void> {
+  const tmp = `${patchFile}.lifeboat.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`
+  await writeFile(tmp, content, 'utf-8')
+  await rename(tmp, patchFile)
+}
+
+/**
+ * 容错打捞坏 YAML 文本中既有的顶层 disabled 条目（best-effort）：
+ * `- id: <name>` 与同条块内的 `disabled: true` 配对即认定。
+ * 坏文件里可能躺着此前已隔离的插件——重建时漏掉它们等于重新放行故障插件。
+ */
+export function salvageDisabled(text: string): string[] {
+  const out: string[] = []
+  const blockRe = /-\s+id:\s*(\S+)([^\0]*?)(?=\n\s*-\s+id:|$)/g
+  for (const match of text.matchAll(blockRe)) {
+    const id = match[1]
+    const block = match[2] ?? ''
+    if (id !== undefined && /\bdisabled:\s*true\b/.test(block)) out.push(id)
+  }
+  return out
+}
+
+/**
+ * 重建通道：原文件 YAML 已坏（doc.errors 非空）时的隔离写入。
+ * 备份坏文件（保留现场）→ 打捞既有 disabled → 重写干净文档。
+ * 即使目标已在打捞集中也照样重写——坏文件对 loader 等于不存在，
+ * 修复文件本身与写入禁用同等重要；返回值仅报告目标集合是否变化。
+ */
+async function appendDisableRebuild(
+  patchFile: string,
+  text: string,
+  targetId: string,
+): Promise<boolean> {
+  const salvaged = salvageDisabled(text)
+  const stamp = new Date().toISOString().replaceAll(/[:.]/g, '-')
+  await copyFile(patchFile, `${patchFile}.broken-${stamp}.bak`)
+  const ids = salvaged.includes(targetId) ? salvaged : [...salvaged, targetId]
+  const entries = ids.map((id) => `- id: ${id}\n  disabled: true`)
+  const content = [
+    '# 本文件由 lifeboat 重建：原文件存在 YAML 语法错误，无法安全改写。',
+    `# 原件已备份为同目录 .broken-${stamp}.bak，请人工合并残留自定义条目。`,
+    ...entries,
+    '',
+  ].join('\n')
+  await atomicWrite(patchFile, content)
+  return !salvaged.includes(targetId)
+}
+
+/**
+ * 向 patch 文件追加一条禁用覆盖；返回是否实际写入（已存在禁用则跳过）。
+ * 原文件 YAML 已坏时转重建通道（隔离落盘优先，原件备份待人工合并）。
+ * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+ */
+export async function appendDisable(patchFile: string, targetId: string): Promise<boolean> {
+  return withFileLock(patchFile, async () => {
+    const text = await readFile(patchFile, 'utf-8')
+    const doc = parseDocument(text)
+    if (doc.errors.length > 0) return appendDisableRebuild(patchFile, text, targetId)
+    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 })
+    await atomicWrite(patchFile, doc.toString())
+    return true
+  })
+}
+
 /**
  * 从 patch 文件移除针对 targetId 的禁用覆盖（恢复插件）；返回是否实际写入。
  * 只移除「id 定向且 disabled: true」的行，其余内容（注释经 yaml 文档保留、
  * 其他条目）原样不动；无该覆盖时幂等返回 false。
- * @throws 文件不可读/顶层不是数组/落盘失败——调用方负责告警。
+ * 原文件 YAML 已坏时不猜测改写，抛错指引人工处理（恢复操作有使用者在场）。
+ * @throws 文件不可读/顶层不是数组/YAML 语法错误/落盘失败——调用方负责告警。
  */
 export async function removeDisable(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}`)
-  let removed = false
-  const items = doc.contents
-  if (items?.items !== undefined && Array.isArray(items.items)) {
-    // 头注释挂在首个条目的 commentBefore 上：被移除项若为首项，注释迁移给
-    // 新的首项，避免整文件头注释丢失。
-    const headComment = (items.items[0] as unknown as { commentBefore?: string })?.commentBefore
-    doc.contents.items = items.items.filter((item) => {
-      const value = (item as unknown as { toJS?(doc: unknown): unknown }).toJS?.(doc) as
-        | PatchEntry
-        | undefined
-      if (
-        value !== undefined &&
-        typeof value === 'object' &&
-        value.id === targetId &&
-        value.disabled === true
-      ) {
-        removed = true
-        return false
+  return withFileLock(patchFile, async () => {
+    const text = await readFile(patchFile, 'utf-8')
+    const doc = parseDocument(text)
+    if (doc.errors.length > 0) {
+      throw new Error(`patch 文件存在 YAML 语法错误，请人工修复后重试: ${patchFile}`)
+    }
+    const root = doc.toJS() as unknown
+    if (!Array.isArray(root)) throw new Error(`patch 文件顶层不是数组: ${patchFile}`)
+    let removed = false
+    const items = doc.contents
+    if (items?.items !== undefined && Array.isArray(items.items)) {
+      // 头注释挂在首个条目的 commentBefore 上：被移除项若为首项，注释迁移给
+      // 新的首项，避免整文件头注释丢失。
+      const headComment = (items.items[0] as unknown as { commentBefore?: string })?.commentBefore
+      doc.contents.items = items.items.filter((item) => {
+        const value = (item as unknown as { toJS?(doc: unknown): unknown }).toJS?.(doc) as
+          | PatchEntry
+          | undefined
+        if (
+          value !== undefined &&
+          typeof value === 'object' &&
+          value.id === targetId &&
+          value.disabled === true
+        ) {
+          removed = true
+          return false
+        }
+        return true
+      })
+      if (removed && headComment !== undefined && doc.contents.items.length > 0) {
+        const next = doc.contents.items[0] as unknown as { commentBefore?: string }
+        if (next.commentBefore === undefined) next.commentBefore = headComment
       }
-      return true
-    })
-    if (removed && headComment !== undefined && doc.contents.items.length > 0) {
-      const next = doc.contents.items[0] as unknown as { commentBefore?: string }
-      if (next.commentBefore === undefined) next.commentBefore = headComment
     }
-  }
-  if (!removed) return false
-  await copyFile(patchFile, `${patchFile}.lifeboat.bak`)
-  const tmp = `${patchFile}.lifeboat.tmp`
-  await writeFile(tmp, doc.toString(), 'utf-8')
-  await rename(tmp, patchFile)
-  return true
+    if (!removed) return false
+    await copyFile(patchFile, `${patchFile}.lifeboat.bak`)
+    await atomicWrite(patchFile, doc.toString())
+    return true
+  })
 }