dsh-armory 2.4.3 → 2.4.4

package/lib/session-persona.js

@@ -16,16 +16,112 @@
 // 重绑为**调用方 ctx** —— 所以用 `agent.ctx.systemPrompt.section(...)` 注册，段就落在
 // 该会话自己的 scope 层：只影响这个会话，且 ctx.effect 返回的 disposer 可随时撤销。
 //
-// 与「召唤预设」的分工：召唤写 profile patch，管**新会话的预设选择器**（长期身份）；
+// ── 为什么专家会「掉」（2026-10 抖音反馈）────────────────────────────────
+// 上面那个 section 的生命周期是**这个 live agent 的 scope**，不是会话文件：
+//   - 会话切走/落盘后 agent 被卸载（dsh-session 明说「persisted-but-unloaded sources」），
+//     再打开走 agents.resume() 重建 agent —— 旧 scope 连同 section 一起销毁；
+//   - 宿主重启同理，且本模块原来只有内存 Map，重启后连「挂过谁」都不知道；
+//   - 原先 reconcilePersonas 还把「不在 agents.list() 里」当成用户取消，把仅有的记录删掉。
+// 于是 chip 消失、人设失效，只能重新勾选——这正是「每个会话中专家容易掉」的来源。
+//
+// WorkBuddy 的逻辑是「专家属于这个会话」：选择是持久的，会话回来时专家就回来。这里照做：
+//   1. 选择（plugin/name/personaText）落盘到 ~/.dsh/wb-market/experts/session-persona.json；
+//   2. 每个 agent/created（含 resume / clear / compaction）都把该会话的选择重新注入；
+//      宿主在创建事务里 await 串行监听器，所以恢复后的**第一个模型请求**就带着人设；
+//   3. reconcile 只清理失效的运行时 section，**绝不**因为会话暂时不在运行就删选择；
+//   4. 只有用户点 ×（detach）才删除选择。
+// 人设正文随选择一起存：重启/离线时不必再请求专家市场，恢复出来的行为与当时一致。
+//
+// 与「召唤预设」的分工不变：召唤写 profile patch，管**新会话的预设选择器**（长期身份）；
 // 本模块管**当前会话的即时人设**（会话内挂/换/摘）。两者互不干扰：预设仍在，随时可用；
-// 会话内挂的专家只是这段提示词 section 的替换，不动工具目录与任何持久化配置。
+// 会话内挂的专家只是这段提示词 section 的替换，不动工具目录与 profile 配置。新增的落盘
+// 文件只记录「哪个会话挂了哪位专家」，是纯增值数据，损坏时静默重置。
+
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 
 /** 与 dsh-persona / dsh-subagent 共用的 section 名（同名即遮蔽，最近 scope 胜出）。 */
 const PERSONA_PREFIX_SECTION = "deployment:persona-prefix";
-/** 单个会话最多保留的撤销记录（防泄漏；正常使用远小于此）。 */
+/** 最多记住多少个会话的选择（防泄漏；正常使用远小于此）。 */
 const MAX_SESSIONS = 64;
-/** sessionId -> { plugin, name, disposer } */
+/** 运行中的注入记录：sessionId -> { plugin, name, disposer, agentCtx }。 */
 const activePersonas = new Map();
+/** 持久化的用户选择：sessionId -> { plugin, name, personaText, savedAt }。 */
+const stickyPersonas = new Map();
+let stickyLoaded = false;
+
+// ── 落盘 ────────────────────────────────────────────────────────────────
+// 与 expert-market.js 的 cacheDir 同一根（同一套 DSH_ARMORY_MARKET_HOME 测试隔离口）。
+// 不 import 那个模块：它带 yaml 等依赖，而本模块会被 test/session-persona.mjs 直接 import。
+function storeFile() {
+	const root = process.env.DSH_ARMORY_MARKET_HOME || join(homedir(), ".dsh", "wb-market");
+	return join(root, "experts", "session-persona.json");
+}
+function ensureSticky() {
+	if (stickyLoaded) return;
+	stickyLoaded = true;
+	let raw = null;
+	try {
+		raw = JSON.parse(readFileSync(storeFile(), "utf8"));
+	} catch {
+		return; // 没有文件 / 损坏：纯增值数据，静默重置
+	}
+	const rows = Array.isArray(raw?.sessions) ? raw.sessions : [];
+	for (const row of rows) {
+		const sessionId = typeof row?.sessionId === "string" ? row.sessionId.trim() : "";
+		const personaText = typeof row?.personaText === "string" ? row.personaText.trim() : "";
+		if (!sessionId || !personaText) continue;
+		stickyPersonas.set(sessionId, {
+			plugin: String(row.plugin || ""),
+			name: String(row.name || row.plugin || "专家"),
+			personaText,
+			savedAt: Number(row.savedAt) || 0,
+		});
+	}
+	pruneSticky();
+}
+function persistSticky(ctx) {
+	try {
+		const target = storeFile();
+		mkdirSync(dirname(target), { recursive: true });
+		const payload = {
+			version: 1,
+			sessions: [...stickyPersonas.entries()].map(([sessionId, row]) => ({ sessionId, ...row })),
+		};
+		const tmp = `${target}.${process.pid}.${Date.now().toString(36)}.tmp`;
+		try {
+			writeFileSync(tmp, JSON.stringify(payload, null, 1), "utf8");
+			renameSync(tmp, target);
+		} catch (error) {
+			rmSync(tmp, { force: true });
+			throw error;
+		}
+	} catch (error) {
+		// 落盘失败不影响本次挂载：section 已经生效，只是重启后不会自动恢复。
+		ctx?.logger?.warn?.(`armory: 会话专家选择落盘失败（本次仍生效）：${error?.message || error}`);
+	}
+}
+/** 超出上限时丢掉最久没用的选择（连同其运行时注入）。 */
+function pruneSticky() {
+	if (stickyPersonas.size <= MAX_SESSIONS) return;
+	const oldest = [...stickyPersonas.entries()].sort((a, b) => a[1].savedAt - b[1].savedAt);
+	for (const [sessionId] of oldest.slice(0, stickyPersonas.size - MAX_SESSIONS)) {
+		stickyPersonas.delete(sessionId);
+		clearPersona(sessionId);
+	}
+}
+
+// ── 运行时注入 ───────────────────────────────────────────────────────────
+// 插件 HMR 后模块级 Map 会重置，但 agent scope 里的 section 仍在——此时再注册同名 section
+// 会被宿主拒绝（NamedEntries 同名即抛）。用一个跨模块实例共享的 WeakMap 记住「这个 agent
+// 作用域注册过什么」，重装时先撤旧的再装新的，HMR 前后都能做到幂等。
+const REGISTRATION_KEY = Symbol.for("dsh-armory.sessionPersona.registrations");
+function registrationStore() {
+	const host = globalThis;
+	if (!(host[REGISTRATION_KEY] instanceof WeakMap)) host[REGISTRATION_KEY] = new WeakMap();
+	return host[REGISTRATION_KEY];
+}
 
 function agentCtxOf(ctx, sessionId) {
 	const agents = typeof ctx?.get === "function" ? ctx.get("agents") : undefined;
@@ -38,38 +134,82 @@ function agentCtxOf(ctx, sessionId) {
 }
 
 /**
- * 摘掉某会话当前注入的人设（若有）。
- * @returns {boolean} 是否真的摘掉了一段。
+ * 摘掉某会话当前注入的人设（若有）。只动运行时 section，不动持久化选择。
+ * @returns {{existed: boolean, disposed: boolean}} existed=有过运行时记录；
+ *          disposed=真正执行了撤销句柄（adopted 记录没有句柄，只能等会话重建）。
  */
 function clearPersona(sessionId) {
 	const current = activePersonas.get(sessionId);
-	if (!current) return false;
+	if (!current) return { existed: false, disposed: false };
 	activePersonas.delete(sessionId);
+	let disposed = false;
+	if (typeof current.disposer === "function") {
+		try {
+			current.disposer();
+			disposed = true;
+		} catch { /* 撤销失败不回滚状态：section 已随 scope 失效，重复撤销无害 */ }
+	}
+	if (current.agentCtx) registrationStore().delete(current.agentCtx);
+	return { existed: true, disposed };
+}
+
+function isDuplicateSection(error) {
+	return /already registered/i.test(String(error?.message || error));
+}
+
+/**
+ * 把一段人设注册进某个 agent scope。同名 section 已存在时视为「已在生效」（HMR 前一代
+ * 留下的注册无法撤销），返回 adopted 而不是把异常抛给用户。
+ */
+function registerSection(agentCtx, text) {
+	const prompt = agentCtx.systemPrompt;
+	if (!prompt || typeof prompt.section !== "function") {
+		throw new Error("该会话没有 systemPrompt 服务，无法注入人设");
+	}
+	// 同一作用域里本模块先前留下的注册：先撤掉，保证「换专家」是替换而不是叠加。
+	try {
+		registrationStore().get(agentCtx)?.();
+	} catch { /* 已失效的 disposer 重复调用无害 */ }
+	registrationStore().delete(agentCtx);
 	try {
-		current.disposer?.();
-	} catch { /* 撤销失败不回滚状态：section 已随 scope 失效，重复撤销无害 */ }
-	return true;
+		// 与 dsh-persona 同款：同名 section + 同一处 order = 遮蔽该会话的部署人设前缀。
+		const disposer = prompt.section({
+			name: PERSONA_PREFIX_SECTION,
+			order: typeof prompt.getSectionOrder === "function"
+				? prompt.getSectionOrder("DEPLOYMENT_PERSONA_PREFIX")
+				: 0,
+			text,
+		});
+		registrationStore().set(agentCtx, disposer);
+		return { disposer, adopted: false };
+	} catch (error) {
+		if (!isDuplicateSection(error)) throw error;
+		return { disposer: null, adopted: true };
+	}
 }
 
-/** 当前挂在某会话上的专家（供客户端 chip 显示真实状态）。 */
+/** 当前挂在某会话上的专家（读的是用户选择；会话暂时不在运行也有值）。 */
 export function personaOf(sessionId) {
-	const row = activePersonas.get(sessionId);
+	ensureSticky();
+	const row = stickyPersonas.get(String(sessionId || "").trim());
 	return row ? { plugin: row.plugin, name: row.name } : null;
 }
 
-/** 所有会话的挂载快照（会话被销毁后由 reconcile 清理）。 */
+/**
+ * 所有「挂了专家」的会话快照。
+ * 刻意以持久化选择为准而不是运行时 Map：会话被宿主卸载时 agent scope 已销毁，但用户
+ * 的选择还在，chip 不应闪没；恢复完成后 expertActive 仍是同一答案。
+ */
 export function listPersonas() {
-	return [...activePersonas.entries()].map(([sessionId, row]) => ({ sessionId, plugin: row.plugin, name: row.name }));
-}
-
-/** 会话已不在运行 → 清掉它的撤销记录（disposer 早已随 scope 失效）。 */
-export function reconcilePersonas(ctx) {
-	const agents = typeof ctx?.get === "function" ? ctx.get("agents") : undefined;
-	if (!agents || typeof agents.get !== "function") return;
-	const live = new Set(agents.list().map((agent) => agent.id));
-	for (const sessionId of [...activePersonas.keys()]) {
-		if (!live.has(sessionId)) activePersonas.delete(sessionId);
+	ensureSticky();
+	const rows = new Map([...stickyPersonas.entries()].map(([sessionId, row]) => [sessionId, { plugin: row.plugin, name: row.name }]));
+	// 运行时记录覆盖持久化选择：persist=false 的替身人设不进粘性表，但它才是会话里
+	// 真正生效的那一位；同会话后来挂了替身时，看板 / chip 不能还显示上一位专家。
+	// 会话卸载后 reconcile 会清掉运行时记录，这时才回落到持久化选择。
+	for (const [sessionId, row] of activePersonas) {
+		rows.set(sessionId, { plugin: row.plugin, name: row.name });
 	}
+	return [...rows.entries()].map(([sessionId, row]) => ({ sessionId, ...row }));
 }
 
 /**
@@ -77,44 +217,158 @@ export function reconcilePersonas(ctx) {
  * @param {object} ctx - 插件宿主上下文。
  * @param {string} sessionId - 目标会话。
  * @param {object} spec - { plugin, name, personaText }。
+ * @param {{persist?: boolean}} [options] - persist=false 用于「按已存选择恢复」，不再写盘。
  * @returns {{ok: true, plugin: string, name: string, replaced: boolean}}
  */
-export function attachPersona(ctx, sessionId, spec) {
+export function attachPersona(ctx, sessionId, spec, options = {}) {
 	const id = String(sessionId || "").trim();
 	if (!id) throw new Error("缺少会话 id");
 	const text = String(spec?.personaText || "").trim();
 	if (!text) throw new Error("人设内容为空，无法挂载");
+	ensureSticky();
 	const { agentCtx, error } = agentCtxOf(ctx, id);
 	if (error) throw new Error(error);
-	const prompt = agentCtx.systemPrompt;
-	if (!prompt || typeof prompt.section !== "function") {
-		throw new Error("该会话没有 systemPrompt 服务，无法注入人设");
+	const replaced = clearPersona(id).existed;
+	const { disposer, adopted } = registerSection(agentCtx, text);
+	if (adopted) {
+		// 只可能来自上一版插件在同一 agent scope 留下的同名 section（那一代的 disposer 已丢）：
+		// 人设仍然生效，但本次拿不到撤销句柄，点 × 要等会话重建后才彻底生效。
+		ctx?.logger?.warn?.("armory: 该会话已有同名专家人设 section，本次沿用（重启 DSH 后可正常取消）");
 	}
-	const replaced = clearPersona(id);
-	// 与 dsh-persona 同款：同名 section + 同一处 order = 遮蔽该会话的部署人设前缀。
-	const disposer = prompt.section({
-		name: PERSONA_PREFIX_SECTION,
-		order: typeof prompt.getSectionOrder === "function"
-			? prompt.getSectionOrder("DEPLOYMENT_PERSONA_PREFIX")
-			: 0,
-		text,
-	});
-	activePersonas.set(id, {
-		plugin: String(spec?.plugin || ""),
-		name: String(spec?.name || spec?.plugin || "专家"),
-		disposer,
-	});
-	// 防泄漏：超出上限时丢掉最早的记录（其 disposer 一并撤销）。
-	while (activePersonas.size > MAX_SESSIONS) {
-		const oldest = activePersonas.keys().next().value;
-		clearPersona(oldest);
+	const plugin = String(spec?.plugin || "");
+	const name = String(spec?.name || spec?.plugin || "专家");
+	activePersonas.set(id, { plugin, name, disposer, agentCtx });
+	if (options.persist !== false) {
+		stickyPersonas.set(id, { plugin, name, personaText: text, savedAt: Date.now() });
+		pruneSticky();
+		persistSticky(ctx);
 	}
-	return { ok: true, plugin: String(spec?.plugin || ""), name: String(spec?.name || spec?.plugin || "专家"), replaced };
+	// adopted：人设已在生效，但本次拿不到撤销句柄。不能把它当成一次完整成功——
+	// 客户端据此提示「取消需重启」，否则用户点 × 看到 removed=false 却不知道原因。
+	return { ok: true, applied: !adopted, needsRestart: adopted, plugin, name, replaced };
 }
 
-/** 摘掉某会话的专家人设。@returns {{ok: true, removed: boolean}} */
+/**
+ * 摘掉某会话的专家人设与持久化选择（用户点 ×）。
+ * @returns {{ok: true, removed: boolean, needsRestart: boolean}}
+ *          removed 只代表「运行时 section 真的撤销了或持久化选择被删了」；
+ *          adopted 记录没有撤销句柄，此时 needsRestart=true，不能谎报已彻底取消。
+ */
 export function detachPersona(ctx, sessionId) {
 	const id = String(sessionId || "").trim();
 	if (!id) throw new Error("缺少会话 id");
-	return { ok: true, removed: clearPersona(id) };
+	ensureSticky();
+	const runtime = clearPersona(id);
+	const removedSticky = stickyPersonas.delete(id);
+	if (removedSticky) persistSticky(ctx);
+	return {
+		ok: true,
+		removed: runtime.disposed || removedSticky,
+		needsRestart: runtime.existed && !runtime.disposed,
+	};
+}
+
+/**
+ * 会话（重新）创建时按已存选择恢复人设。任何失败都只返回原因、不抛出——本函数挂在
+ * 宿主的串行 agent/created 监听器上，抛错会**否决会话创建**。
+ * @returns {{restored: boolean, plugin?: string, name?: string, reason?: string}}
+ */
+export function restorePersonaForAgent(ctx, agent) {
+	const id = String(agent?.id || "").trim();
+	if (!id) return { restored: false, reason: "缺少会话 id" };
+	ensureSticky();
+	const record = stickyPersonas.get(id);
+	if (!record) return { restored: false, reason: "该会话没有专家选择" };
+	const agentCtx = agent.ctx;
+	if (!agentCtx) return { restored: false, reason: "该会话没有可用的作用域上下文" };
+	const current = activePersonas.get(id);
+	if (current && current.agentCtx === agentCtx) return { restored: false, reason: "人设已生效" };
+	try {
+		const result = attachPersona(ctx, id, {
+			plugin: record.plugin,
+			name: record.name,
+			personaText: record.personaText,
+		}, { persist: false });
+		return { restored: true, applied: result.applied, needsRestart: result.needsRestart, plugin: result.plugin, name: result.name };
+	} catch (error) {
+		// 记录保留：下一次 agent/created 或 reconcile 再试，绝不因为一次失败丢掉选择。
+		return { restored: false, reason: String(error?.message || error) };
+	}
+}
+
+/**
+ * 对齐运行时注入与宿主存活会话：
+ *   - 失效（agent 已卸载/已被新 agent 取代）的运行时记录撤销，但**保留用户选择**；
+ *   - 活着的 agent 若有选择却没有注入（切换会话恢复、插件热重载、上次恢复失败），立刻补上。
+ * 不抛错：它由只读 RPC expertActive 轮询调用，不能影响状态查询。
+ */
+export function reconcilePersonas(ctx) {
+	const agents = typeof ctx?.get === "function" ? ctx.get("agents") : undefined;
+	if (!agents || typeof agents.get !== "function" || typeof agents.list !== "function") return;
+	ensureSticky();
+	let live = [];
+	try {
+		live = agents.list() || [];
+	} catch {
+		return;
+	}
+	for (const [sessionId, row] of [...activePersonas]) {
+		const agent = live.find((candidate) => candidate.id === sessionId);
+		if (agent && agent.ctx === row.agentCtx) continue;
+		clearPersona(sessionId);
+	}
+	for (const agent of live) {
+		if (!stickyPersonas.has(agent.id)) continue;
+		const current = activePersonas.get(agent.id);
+		if (current && current.agentCtx === agent.ctx) continue;
+		restorePersonaForAgent(ctx, agent);
+	}
+}
+
+/**
+ * 安装会话专家运行时：订阅 agent/created（宿主串行 await，恢复后首轮即带人设），并对
+ * 安装时已经活着的会话做一次补装（插件热重载 / 运行中安装的场景）。
+ * @returns {() => void} 幂等清理函数。
+ */
+export function installPersonaRuntime(ctx) {
+	if (typeof ctx?.on !== "function") return () => {};
+	ensureSticky();
+	let disposed = false;
+	let off;
+	const cleanup = () => {
+		if (disposed) return;
+		disposed = true;
+		try { off?.(); } catch { /* noop */ }
+	};
+	try {
+		off = ctx.on("agent/created", (payload) => {
+			// 边界：agent/created 是串行且抛错会否决创建的。人设恢复失败只能记账，不能挡会话。
+			try {
+				const agent = payload?.agent;
+				if (agent?.id) {
+					const result = restorePersonaForAgent(ctx, agent);
+					if (!result.restored && result.reason && result.reason !== "该会话没有专家选择" && result.reason !== "人设已生效") {
+						ctx.logger?.warn?.(`armory: 恢复会话专家失败（不影响会话创建）：${result.reason}`);
+					}
+				}
+			} catch (error) {
+				ctx.logger?.warn?.(`armory: 恢复会话专家异常（已吞掉，不阻断会话创建）：${error?.message || error}`);
+			}
+		});
+		if (typeof ctx.effect === "function") ctx.effect(() => cleanup, "armory.sessionPersona");
+	} catch (error) {
+		cleanup();
+		ctx.logger?.warn?.(`armory: 订阅 agent/created 失败，会话专家不会自动恢复：${error?.message || error}`);
+		return () => {};
+	}
+	// 安装前就活着的会话（热重载）：逐个补装。
+	try {
+		const agents = typeof ctx.get === "function" ? ctx.get("agents") : undefined;
+		if (agents && typeof agents.list === "function") {
+			for (const agent of agents.list() || []) {
+				if (agent?.id && stickyPersonas.has(agent.id)) restorePersonaForAgent(ctx, agent);
+			}
+		}
+	} catch { /* 补装失败留给下一次 reconcile */ }
+	return cleanup;
 }

package/lib/skill-disable.js

@@ -0,0 +1,178 @@
+// 技能禁用数据层（工具裁缝技能账本「禁用 / 释放」的唯一落盘点）。
+//
+// 机制：写 SKILL.md frontmatter 的 `disable-model-invocation` 标志。这是宿主
+// （@deepseek-ai/dsh-skill-filesystem）官方支持的「模型侧禁用」键：置 true 后该技能
+// 不再进模型目录与加载器，Schema 与描述不再随每轮请求下发（上下文税归零）；输入框
+// 手动 /引用 不受影响。skills 根目录有监听器，改动会被自动拾取，无需重启宿主。
+// 「释放」= 移除该标志，恢复模型可调用。禁用是可逆编辑，不是卸载——目录与正文分毫不动。
+//
+// 为什么不让客户端传路径直接改：与 lib/skill-remove.js 同一理由——RPC 入参是浏览器
+// 可写的。这里只认「宿主注册表给这条 skill 的真实 source + path」，并把写入面钉死在
+// 四类 skills 根目录里（用户级 ~/.agents/skills、~/.dsh/skills，项目级 <cwd>/.agents/
+// skills、<cwd>/.dsh/skills）。bundled（随应用分发，升级会被覆盖回去）、runtime
+// （不落盘）、custom（没有可信根目录做包含性校验）一律拒绝——白名单与 skill-remove 同集。
+//
+// 安全闸门（与 skill-remove 同序，任一不过即抛错，绝不「尽力而为」地写）：
+//   1. source 在白名单内，且能推导出绝对根目录（项目级必须有 cwd）；
+//   2. path 是绝对路径，resolve 后严格位于根目录内（≠ 根自身，`..` 穿越不过）；
+//      注册表的 path 通常指向 <skill>/SKILL.md，也可能指向目录或扁平 <name>.md，
+//      归一到「要编辑的那个 .md 清单文件」再校验；
+//   3. 清单文件的 realpath 必须仍在根目录 realpath 内（防符号链接把写入面带出根；
+//      链接指回根内是允许的——写 realpath 而不是链接路径，用户的链接结构分毫不动）。
+//
+// frontmatter 手术只动一处（editInvocationFlag 纯函数，磁盘外可测）：按与宿主解析器
+// 相同的规则定位开/闭 `---` 行之间的块——
+//   禁用：删掉块内全部 `disable-model-invocation` 行（重复键是脏数据，统一收敛），
+//         在闭行前插入一行 `disable-model-invocation: true`；
+//   释放：删掉块内全部该行（值为 false 的也删——恢复作者未写该键时的原貌）。
+// 其余字节（键序、缩进、注释、正文）原样保留；行尾风格按文件现状保留（\n / \r\n）。
+// 开/闭行缺失（没有合法 frontmatter）一律拒绝——那不是本层该修的文件。
+//
+// 纯数据层：零网络、零宿主服务依赖；home / cwd 可注入，测试用 mkdtemp 隔离。
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { writeFileAtomic } from '@deepseek-ai/dsh-atomic-write';
+import { skillRootFor } from './skill-remove.js';
+
+/** frontmatter 里的模型侧禁用键：宿主 dsh-skill-filesystem 的 canonical 拼写。 */
+export const DISABLED_INVOCATION_KEY = 'disable-model-invocation';
+
+const FLAG_LINE_RE = /^disable-model-invocation[ \t]*:/;
+
+function describeSource(source) {
+  return source ? `「${source}」` : '未知来源';
+}
+
+/** 严格包含：child 在 parent 之内且不等于 parent。 */
+function isInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/** 包含或相等：符号链接项只做包含校验，允许恰好落在根上。 */
+function isInsideOrEqual(parent, child) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/**
+ * 在 SKILL.md 原文里写入 / 移除 disable-model-invocation 标志（纯字符串手术）。
+ *
+ * 开/闭行判定与宿主 parseFrontmatter 同规则：首行去掉 \r 后必须恰为 `---`，闭行
+ * 同为一整行 `---`；找不到任一者视为「没有合法 frontmatter」返回 null（调用方拒绝）。
+ *
+ * @param {string} text SKILL.md 原文
+ * @param {boolean} disabled true = 置标志，false = 移除标志
+ * @returns {string | null} 改写后的全文；无合法 frontmatter 时 null
+ */
+export function editInvocationFlag(text, disabled) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  const firstBreak = text.indexOf('\n');
+  if (firstBreak < 0) return null;
+  if (text.slice(0, firstBreak).replace(/\r$/, '') !== '---') return null;
+  // 闭行检索与宿主 findClosingFrontmatter 同步：逐行找去掉 \r 后恰为 `---` 的一行。
+  let lineStart = firstBreak + 1;
+  let closeStart = -1;
+  while (lineStart <= text.length) {
+    const nextBreak = text.indexOf('\n', lineStart);
+    const lineEnd = nextBreak < 0 ? text.length : nextBreak;
+    if (text.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+      closeStart = lineStart;
+      break;
+    }
+    if (nextBreak < 0) return null;
+    lineStart = nextBreak + 1;
+  }
+  if (closeStart < 0) return null;
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const block = text.slice(firstBreak + 1, closeStart);
+  // 块恒以换行收口（closeStart 是闭行行首），split 的尾随空串是切片伪影，弹掉；
+  // 中间的空行是真实内容，必须保留。
+  const lines = block.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  const kept = lines.map((line) => line.replace(/\r$/, '')).filter((line) => !FLAG_LINE_RE.test(line));
+  if (disabled) kept.push(DISABLED_INVOCATION_KEY + ': true');
+  // 闭行行首之前是上一行的换行符，所以块内每行（含新插入行）都要以行尾收口；
+  // 空块释放后保持空串——开闭行紧邻的空 frontmatter 依然合法。
+  const nextBlock = kept.length ? kept.join(eol) + eol : '';
+  return text.slice(0, firstBreak + 1) + nextBlock + text.slice(closeStart);
+}
+
+/**
+ * 把一条宿主注册表 skill 的「模型可调用」开关落到磁盘。
+ *
+ * @param {{ name?: string, source?: string, path?: string }} skill 宿主注册表返回的条目
+ * @param {{ disabled: boolean, cwd?: string, home?: string }} options
+ * @returns {Promise<{ path: string, disabled: boolean, changed: boolean }>}
+ *   path 是实际写入的清单文件绝对路径；changed=false 表示文件本就处于目标状态
+ *   （幂等重放），未写盘。
+ */
+export async function setSkillModelInvocationOnDisk(skill, options = {}) {
+  const disabled = options.disabled === true;
+  const source = typeof skill?.source === 'string' ? skill.source : '';
+  const root = skillRootFor(source, options);
+  if (!root) {
+    if (source === 'project-agents' || source === 'project-dsh') {
+      throw new Error(`禁用项目级 skill 需要当前项目路径（来源：${describeSource(source)}）`);
+    }
+    throw new Error(
+      `这个 skill 来自${describeSource(source)}，不在可禁用范围内（只支持用户级/项目级的 .dsh/skills 与 .agents/skills）`,
+    );
+  }
+  if (!isAbsolute(root)) throw new Error('拒绝修改：无法确定 skills 根目录的绝对路径');
+  const raw = typeof skill?.path === 'string' ? skill.path.trim() : '';
+  if (!raw) throw new Error('这个 skill 没有可修改的磁盘路径（运行时注册的 skill 不落盘）');
+  if (!isAbsolute(raw)) throw new Error('拒绝修改：skill 路径不是绝对路径');
+
+  const rootAbs = resolve(root);
+  const rawAbs = resolve(raw);
+  if (!isInside(rootAbs, rawAbs)) {
+    throw new Error(`拒绝修改：skill 路径不在预期的 skills 根目录内（${rootAbs}）`);
+  }
+
+  // stat 跟随符号链接：整个 skill 目录是链接（常见于把仓库目录链进 skills 根）时
+  // 也能正确识别成目录，最终由 realpath 闸门判定链接落点是否可信。
+  let rawInfo;
+  try {
+    rawInfo = await stat(rawAbs);
+  } catch (error) {
+    if (error?.code === 'ENOENT') throw new Error('这个 skill 已经不在磁盘上了（可能刚被移动或删除）');
+    throw error;
+  }
+  let manifestPath;
+  if (rawInfo.isDirectory()) {
+    manifestPath = join(rawAbs, 'SKILL.md');
+  } else if (rawInfo.isFile() && rawAbs.toLowerCase().endsWith('.md')) {
+    manifestPath = rawAbs; // 扁平 <name>.md 形态的 skill，清单就是文件本身
+  } else {
+    throw new Error('拒绝修改：skill 路径不是 skill 目录，也不是 .md 清单文件');
+  }
+  const manifest = await stat(manifestPath).catch(() => null);
+  if (!manifest || !manifest.isFile()) {
+    throw new Error('拒绝修改：目录里没有 SKILL.md，看起来不是 skill 目录');
+  }
+
+  // realpath 校验：防「根内路径 → 符号链接实际指向根外」。根目录本身是符号链接
+  // （例如 ~/.agents → 别处）是允许的，所以比的是 realpath 后的根。
+  const rootReal = await realpath(rootAbs);
+  const fileReal = await realpath(manifestPath);
+  if (!isInsideOrEqual(rootReal, fileReal)) {
+    throw new Error('拒绝修改：skill 路径经符号链接指向了 skills 根目录之外');
+  }
+
+  // BOM 会同时挡住宿主解析器（首行不再是 ---）与本层手术，明确拒绝而不是绕过。
+  const original = await readFile(fileReal, 'utf8');
+  if (original.charCodeAt(0) === 0xfeff) {
+    throw new Error('拒绝修改：SKILL.md 带 BOM 头，宿主解析器也无法读取它');
+  }
+  const next = editInvocationFlag(original, disabled);
+  if (next === null) {
+    throw new Error('拒绝修改：SKILL.md 没有合法的 YAML frontmatter（开/闭 --- 行缺失），本层不做修补');
+  }
+  if (next === original) {
+    return { path: fileReal, disabled, changed: false };
+  }
+  // 写 realpath：rename 永远落在真实文件上，绝不把用户的符号链接替换成普通文件。
+  await writeFileAtomic(fileReal, next, { mode: manifest.mode });
+  return { path: fileReal, disabled, changed: true };
+}