@dsh-plus/lifeboat 0.1.7 → 0.2.1

package/lib/index.js

@@ -1,7 +1,7 @@
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
-import { SettingsConflictError, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 import { copyFile, readFile, rename, writeFile } from "node:fs/promises";
+import { SettingsConflictError } from "@deepseek-ai/dsh-settings";
 import { parseDocument } from "yaml";
 //#endregion
 //#region src/config.ts
@@ -13,8 +13,8 @@ import { parseDocument } from "yaml";
 * schema 刻意宽松：lifeboat 是最后防线，自身命名空间的数据问题绝不能让它起不来。
 * @module lifeboat/config
 */
-/** settings 命名空间（品牌化后供 settings 服务注册/读写）。 */
-const SETTINGS_NS = settingsNamespace("dsh-plus-lifeboat");
+/** settings 命名空间（字面量直供 settings 服务注册/读写，0.1.2-alpha.2 起编译期校验语法）。 */
+const SETTINGS_NS = "dsh-plus-lifeboat";
 /** 行级配置：全部有默认值，正常部署零配置。 */
 const Config = z.object({
 	enabled: z.boolean().description("故障隔离总开关").default(true),
@@ -56,8 +56,8 @@ const JournalSchema = z.object({
 * 协议推断是启发式（显式 api > 路由名 > 模型继承源 > openai-completions 兜底）。
 * @module lifeboat/fallback-llm
 */
-const NS_PI_AI = settingsNamespace("llm-pi-ai");
-const NS_AGENT_DEFAULT = settingsNamespace("agent-default-model");
+const NS_PI_AI = "llm-pi-ai";
+const NS_AGENT_DEFAULT = "agent-default-model";
 const RAW_NS_LLM_PI = "dsh-plus-llm-pi";
 /** 官方配置路径物化的 compat 子集（其余字段降级期丢弃）。 */
 const COMPAT_WHITELIST = ["thinkingFormat", "supportsReasoningEffort"];
@@ -256,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 覆盖。 */
@@ -266,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
@@ -394,7 +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 层热应用机制保留，行为不变。）
+* （0.1.2-alpha.2 基线复核：用户 patch 层热应用机制保留，行为不变。）
 * @module lifeboat/health-api
 */
 const ROUTE_STATUS = "/dsh-plus/lifeboat/status";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/lifeboat",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "description": "dsh-plus service plugin: 故障救生艇——兄弟插件崩溃时自动隔离（写用户 patch 层禁用），llm-pi 缺席时把其配置临时翻译为官方 llm-pi-ai 路由，恢复后自动还原",
   "type": "module",
   "main": "lib/index.js",
@@ -30,26 +30,26 @@
     }
   },
   "dependencies": {
-    "yaml": "^2.6.0",
-    "@dsh-plus/shared": "0.1.6"
+    "yaml": "^2.9.0",
+    "@dsh-plus/shared": "0.1.7"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@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/dsh-home-paths": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@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",
-    "@types/node": "26.2.0"
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.2",
+    "@types/node": "26.4.0",
+    "@types/react": "~18.3.31",
+    "react": "^18.2.0"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -7,13 +7,12 @@
  * @module lifeboat/config
  */
 
-import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import z from '@deepseek-ai/schemastery'
 
 import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
 
-/** settings 命名空间（品牌化后供 settings 服务注册/读写）。 */
-export const SETTINGS_NS = settingsNamespace(NS_LITERAL)
+/** settings 命名空间（字面量直供 settings 服务注册/读写，0.1.2-alpha.2 起编译期校验语法）。 */
+export const SETTINGS_NS = NS_LITERAL
 
 /** 行级配置：全部有默认值，正常部署零配置。 */
 export const Config = z.object({

package/src/fallback-llm.ts

@@ -15,18 +15,16 @@ 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,
-  type SettingsProvider,
-  settingsNamespace,
-} from '@deepseek-ai/dsh-settings'
+import { SettingsConflictError, 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')
+// 0.1.2-alpha.2 起 settings 命名空间直接以字面量使用（编译期校验语法），
+// 不再需要 settingsNamespace() 品牌化。
+const NS_PI_AI = 'llm-pi-ai'
+const NS_AGENT_DEFAULT = 'agent-default-model'
 const RAW_NS_LLM_PI = 'dsh-plus-llm-pi'
 
 /** 翻译路由键后缀：与源路由错开，避免 llm-pi 恢复瞬间撞 DUPLICATE_ADAPTER。 */
@@ -184,9 +182,9 @@ export async function readRawSection(
 }
 
 interface SettingsWrite {
-  update(ns: ReturnType<typeof settingsNamespace>, patch: object): Promise<void>
+  update(ns: string, patch: object): Promise<void>
   mutate(
-    ns: ReturnType<typeof settingsNamespace>,
+    ns: string,
     ops: readonly {
       op: 'set' | 'unset'
       path: readonly string[]
@@ -236,7 +234,7 @@ export function installLlmFallback(ctx: Context, deps: FallbackDeps): void {
     const translated = translateProviders(providers)
     const fbProvider = `${provider}${FALLBACK_SUFFIX}`
     try {
-      // 官方 llm-pi-ai 的 installSettingsSection 注册了 validate（assertServiceable），
+      // 官方 llm-pi-ai 的 installSection 注册了 validate（assertServiceable），
       // 写时拒绝不适配的翻译结果；update 无 expectedRevision 本就无条件写，不做冲突
       // 重试——失败一律分类为「翻译失败」。
       await writes.update(NS_PI_AI, { providers: translated })
@@ -324,7 +322,7 @@ 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()
   })
-  // 事件名已核对：master 0.1.2-alpha.1 的 dsh-llm 保留 'llm/adapters-updated'
+  // 事件名已核对：0.1.2-alpha.2 的 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。

package/src/health-api.ts

@@ -3,7 +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 层热应用机制保留，行为不变。）
+ * （0.1.2-alpha.2 基线复核：用户 patch 层热应用机制保留，行为不变。）
  * @module lifeboat/health-api
  */
 import { readFile } from 'node:fs/promises'

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
+  })
 }