@dsh-workbench/core 0.2.14 → 0.2.16

package/dist/host/index.js

@@ -13,11 +13,15 @@ var PREFS_PREFIX = `${API_PREFIX}/prefs`;
 var EVENTS_PATH = "/workbench/events";
 var ACTIONS_PREFIX = `${API_PREFIX}/actions`;
 var PROVISION_PREFIX = `${API_PREFIX}/provision`;
-var PANEL_STATE_PREFIX = `${API_PREFIX}/panel-state`;
+var PANEL_STATE_PATH = "panel-state";
+var DIY_DEBUG_PATH = "diy-debug";
+`${DIY_DEBUG_PATH}`;
+var PANEL_STATE_PREFIX = `${API_PREFIX}/${PANEL_STATE_PATH}`;
 var OPENCLI_PIN = "1.8.8";
 var PANELS_SERVICE = "workbenchPanels";
 var UNITS_SERVICE = "workbenchUnits";
 var PANEL_STATE_SERVICE = "workbenchPanelState";
+var DIY_DEBUG_SERVICE = "workbenchDiyDebug";
 var OPENCLI_TIMEOUT_MS = 12e4;
 var WARM_TIMEOUT_MS = 2e4;
 var INSTALL_TIMEOUT_MS = 3e5;
@@ -435,6 +439,125 @@ function createPanelStateStore() {
 	};
 }
 //#endregion
+//#region ../shared/dist/lib/board-fact.js
+function insideWorkshop$1(root, target) {
+	if (target === root) return true;
+	const base = root.endsWith("/") ? root : `${root}/`;
+	return target.startsWith(base);
+}
+function boardFactOf(probe, workshop) {
+	if (!probe.workbench) return "unknown";
+	if (!probe.bar || !probe.open || !probe.drawn) return "hidden";
+	if (probe.board === "" || workshop === null) return "unknown";
+	return insideWorkshop$1(workshop, probe.board) ? "workshop" : "other";
+}
+function boardSituation(probe, workshop) {
+	if (!probe.workbench || workshop === null) return "unknown";
+	if (probe.bar && probe.open && probe.drawn) {
+		if (probe.board === "") return "unknown";
+		return insideWorkshop$1(workshop, probe.board) ? "ok" : "other-board";
+	}
+	if (probe.where !== "" && !insideWorkshop$1(workshop, probe.where)) return "off-workspace";
+	return "panel-closed";
+}
+//#endregion
+//#region ../shared/dist/lib/diy-debug.js
+function parseDebugIntent(value) {
+	return value === "pause" || value === "resume" || value === "stop" ? value : null;
+}
+function alive(state, now) {
+	if (state === null) return null;
+	return now - state.at <= 144e5 ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+	const held = alive(state, now);
+	if (held === null) return "none";
+	return held.sessionId === sessionId ? held : "not-owner";
+}
+function createDebugStore() {
+	let held = null;
+	const live = (now) => alive(held, now);
+	return {
+		live,
+		begin(pact) {
+			const current = alive(held, pact.now);
+			if (current !== null) return {
+				ok: false,
+				code: current.sessionId === pact.sessionId ? "already-held" : "held-by-other"
+			};
+			const state = {
+				phase: "debugging",
+				sessionId: pact.sessionId,
+				workspace: pact.workspace,
+				board: pact.board,
+				unit: pact.unit,
+				name: pact.name,
+				startedAt: pact.now,
+				at: pact.now
+			};
+			held = state;
+			return {
+				ok: true,
+				state
+			};
+		},
+		pause(sessionId, now) {
+			const found = ownerOf(held, sessionId, now);
+			if (typeof found === "string") return {
+				ok: false,
+				code: found
+			};
+			if (found.phase === "paused") return {
+				ok: false,
+				code: "already-paused"
+			};
+			const state = {
+				...found,
+				phase: "paused",
+				at: now
+			};
+			held = state;
+			return {
+				ok: true,
+				state
+			};
+		},
+		resume(sessionId, now) {
+			const found = ownerOf(held, sessionId, now);
+			if (typeof found === "string") return {
+				ok: false,
+				code: found
+			};
+			if (found.phase === "debugging") return {
+				ok: false,
+				code: "already-debugging"
+			};
+			const state = {
+				...found,
+				phase: "debugging",
+				at: now
+			};
+			held = state;
+			return {
+				ok: true,
+				state
+			};
+		},
+		stop(sessionId, now) {
+			const found = ownerOf(held, sessionId, now);
+			if (typeof found === "string") return {
+				ok: false,
+				code: found
+			};
+			held = null;
+			return {
+				ok: true,
+				state: found
+			};
+		}
+	};
+}
+//#endregion
 //#region ../shared/dist/host/opencli-window.js
 var OPENCLI_WINDOW_ENV = "OPENCLI_WINDOW=background";
 function backgroundPrefix() {
@@ -1661,6 +1784,15 @@ function registerPanelState(ctx, store) {
 		}]
 	});
 }
+function registerDiyDebugAct(ctx, resource, log) {
+	return registerPost(ctx, {
+		prefix: `${API_PREFIX}/${DIY_DEBUG_PATH}`,
+		what: "工作台 DIY 调试动作",
+		refusedCode: "action-refused",
+		resources: [resource],
+		wrote: () => log?.bump(["diy-debug"])
+	});
+}
 //#endregion
 //#region ../shared/dist/host/long-task.js
 var LIVE = /* @__PURE__ */ new Set(["running", "needs-login"]);
@@ -2138,6 +2270,10 @@ function sessionWorkspace(exec) {
 	const cwd = exec?.agent?.session?.header?.cwd;
 	return typeof cwd === "string" && cwd.trim() !== "" ? cwd.trim() : null;
 }
+function sessionIdOf(exec) {
+	const id = exec?.agent?.session?.id;
+	return typeof id === "string" && id.trim() !== "" ? id.trim() : null;
+}
 function textOutput(text) {
 	return [{
 		type: "text",
@@ -2799,9 +2935,7 @@ function workshopPackagesDir(ctx) {
 	return root === null ? null : join(root, "packages");
 }
 function insideWorkshop(root, target) {
-	const base = existsSync(root) ? realpathSync(root) : resolve(root);
-	const real = existsSync(target) ? realpathSync(target) : resolve(target);
-	return real === base || real.startsWith(base + sep);
+	return insideWorkshop$1(existsSync(root) ? realpathSync(root) : resolve(root), existsSync(target) ? realpathSync(target) : resolve(target));
 }
 function workshopModules(packagesDir, installed = []) {
 	if (!existsSync(packagesDir)) return [];
@@ -2871,6 +3005,10 @@ var DIY_NET_STOP_TOOL = "workbench_diy_net_stop";
 var DIY_LOGS_WATCH_TOOL = "workbench_diy_logs_watch";
 var DIY_LOGS_READ_TOOL = "workbench_diy_logs_read";
 var DIY_LOGS_STOP_TOOL = "workbench_diy_logs_stop";
+var DIY_DEBUG_START_TOOL = "workbench_diy_debug_start";
+var DIY_DEBUG_PAUSE_TOOL = "workbench_diy_debug_pause";
+var DIY_DEBUG_RESUME_TOOL = "workbench_diy_debug_resume";
+var DIY_DEBUG_STOP_TOOL = "workbench_diy_debug_stop";
 var READ_TOOLS = [
 	PANELS_LIST_TOOL,
 	MODULES_LIST_TOOL,
@@ -2911,7 +3049,11 @@ var WRITE_TOOLS = [
 	MODULES_UNINSTALL_PLUGIN_TOOL,
 	MODULES_UPDATE_WORKBENCH_TOOL,
 	DIY_INSTALL_TOOL,
-	DIY_SHOW_TOOL
+	DIY_SHOW_TOOL,
+	DIY_DEBUG_START_TOOL,
+	DIY_DEBUG_PAUSE_TOOL,
+	DIY_DEBUG_RESUME_TOOL,
+	DIY_DEBUG_STOP_TOOL
 ];
 var DIY_TOOLS = [
 	DIY_LIST_TOOL,
@@ -2938,6 +3080,12 @@ var DIY_TOOLS = [
 	DIY_LOGS_READ_TOOL,
 	DIY_LOGS_STOP_TOOL
 ];
+var DIY_DEBUG_TOOLS = [
+	DIY_DEBUG_START_TOOL,
+	DIY_DEBUG_PAUSE_TOOL,
+	DIY_DEBUG_RESUME_TOOL,
+	DIY_DEBUG_STOP_TOOL
+];
 var panelsUnit = {
 	id: "panels",
 	card: null,
@@ -3031,6 +3179,13 @@ function askOf(reason, question, fallback) {
 	};
 }
 var panelsApproval = (call) => {
+	if (call.name === "workbench_diy_debug_start" || call.name === "workbench_diy_debug_resume") {
+		const starting = call.name === DIY_DEBUG_START_TOOL;
+		const unit = argsOf$1(call)["unit"];
+		const target = typeof unit === "string" && unit !== "" ? ` [${unit}]` : "";
+		return askOf(`${call.name}${target} takes over the user's screen to debug a workbench module`, pair(starting ? "要在「工作台DIY」那块板上开始调试 —— 调试中请留在那一屏，允许吗？" : "要接着调试 —— 请回到「工作台DIY」那一屏，允许吗？", starting ? "it takes over your screen to debug on the workshop board — please stay on that screen. Allow?" : "it needs your screen again to keep debugging — please go back to the workshop board. Allow?"), pair(starting ? "agent 要占用你的屏幕开始调试工作台模块，允许吗？" : "agent 要接着占用你的屏幕调试，允许吗？", starting ? "The agent wants to take over your screen to start debugging a workbench module. Allow?" : "The agent wants your screen again to keep debugging. Allow?"));
+	}
+	if (call.name === "workbench_diy_debug_pause" || call.name === "workbench_diy_debug_stop") return { kind: "allow" };
 	if (call.name !== void 0 && DIY_TOOLS.includes(call.name)) return { kind: "allow" };
 	const raw = argsOf$1(call);
 	const text = (key) => {
@@ -3591,11 +3746,28 @@ function numberIn$1(value, fallback) {
 }
 var PAGE_PROBE = `(async () => {
   const answer = await fetch('/workbench/api/health').then((one) => one.json()).catch(() => null);
+  const root = document.querySelector('.wb-root');
+  const where = root === null ? '' : (root.getAttribute('data-wb-where') ?? '');
+  const bar = document.querySelector('.wb-rightbar');
+  const board = bar === null ? '' : (bar.getAttribute('data-wb-board') ?? '');
+  const open = bar === null ? null : bar.hasAttribute('data-wb-open');
+  const style = bar === null ? null : getComputedStyle(bar);
+  const box = bar === null ? null : bar.getBoundingClientRect();
+  const drawn =
+    bar !== null &&
+    style.visibility !== 'hidden' &&
+    style.display !== 'none' &&
+    box.width > 0 &&
+    box.height > 0;
   return JSON.stringify({
     plugin: answer === null ? null : answer.plugin,
     pid: answer === null ? null : answer.pid,
     url: location.href,
     title: document.title,
+    where,
+    board,
+    open,
+    shown: drawn,
   });
 })()`;
 function cardSelectorOf(unit) {
@@ -3657,6 +3829,7 @@ var NO_PICK = {
 var EMPTY_CARD = {
 	ok: false,
 	anchored: false,
+	visible: false,
 	width: 0,
 	height: 0,
 	head: "",
@@ -3703,10 +3876,13 @@ function measureScriptOf(unit, pick) {
   };
   const anchor = document.querySelector(${JSON.stringify(cardSelectorOf(unit))});
   const all = [...document.querySelectorAll('.wb-card')];
-  if (anchor === null) return JSON.stringify({ ok: false, cards: all.length, anchored: false });
+  if (anchor === null) return JSON.stringify({ ok: false, cards: all.length, anchored: false, visible: false });
   const card = anchor.classList.contains('wb-card') ? anchor : anchor.querySelector('.wb-card');
-  if (card === null) return JSON.stringify({ ok: false, cards: all.length, anchored: true });
+  if (card === null) return JSON.stringify({ ok: false, cards: all.length, anchored: true, visible: false });
   const box = card.getBoundingClientRect();
+  const painted = getComputedStyle(card);
+  const visible =
+    painted.visibility !== 'hidden' && painted.display !== 'none' && box.width > 0 && box.height > 0;
   const head = card.querySelector('.wb-cardTitle');
   const text = scrub(card.textContent);
   const shown = scrub(card.innerText);
@@ -3749,6 +3925,7 @@ function measureScriptOf(unit, pick) {
   return JSON.stringify({
     ok: true,
     cards: all.length,
+    visible,
     width: Math.ceil(box.width),
     height: Math.ceil(box.height),
     x: Math.round(box.x),
@@ -3900,12 +4077,21 @@ async function workbenchPageOf(shell, command, session) {
 	if (parsed === void 0) return {
 		ok: false,
 		url: "",
-		title: ""
+		title: "",
+		where: "",
+		board: "",
+		open: null,
+		shown: false
 	};
+	const raw = parsed["open"];
 	return {
 		ok: textOf$4(parsed["plugin"]) === "@dsh-workbench/core",
 		url: textOf$4(parsed["url"]),
-		title: textOf$4(parsed["title"])
+		title: textOf$4(parsed["title"]),
+		where: textOf$4(parsed["where"]),
+		board: textOf$4(parsed["board"]),
+		open: typeof raw === "boolean" ? raw : null,
+		shown: parsed["shown"] === true
 	};
 }
 async function writeShotsDir(shell, dir) {
@@ -3951,13 +4137,15 @@ async function measureCard(shell, command, session, unit, pick) {
 	if (parsed === void 0 || parsed["ok"] !== true) return {
 		...EMPTY_CARD,
 		cards: numberIn(parsed?.["cards"], 0),
-		anchored: parsed?.["anchored"] === true
+		anchored: parsed?.["anchored"] === true,
+		visible: parsed?.["visible"] === true
 	};
 	const width = numberIn(parsed["width"], 0);
 	const height = numberIn(parsed["height"], 0);
 	return {
 		ok: true,
 		anchored: true,
+		visible: parsed["visible"] === true,
 		width,
 		height,
 		head: textOf$4(parsed["head"]),
@@ -4036,6 +4224,35 @@ async function shootCard(shell, command, session, unit, file, view) {
 }
 //#endregion
 //#region src/modules/panels/model/diy-page.ts
+function debugPausedText(held) {
+	return `调试已暂停（${held.unit}）—— 动作族关闸，不再拿屏当目标。要接着看先 workbench_diy_debug_resume（会再要用户点头一次）；这之前可以改源码 / build / 跑门禁。`;
+}
+function debugForeignPactText(held) {
+	return `另一场调试正占着那块屏（${held.sessionId} 在调试 ${held.unit}）—— 一台机器同时只允许一场：让它先 workbench_diy_debug_stop，或等它收工。`;
+}
+function debugOffBoardText(held, situation = "other-board") {
+	const what = situation === "off-workspace" ? "用户现在不在 DIY 工作区（外壳选中的是别的工作区）" : situation === "panel-closed" ? "工作台面板没画在屏上（右栏收着，或那一列让给了别的面板）" : "你现在这一页画的不是工坊那块板";
+	const next = situation === "off-workspace" ? "让用户在左栏切回「工作台DIY」那个工作区" : situation === "panel-closed" ? "让用户把「工作台面板」切回来（或把右栏展开）" : "让用户把那一页切回「工作台DIY」";
+	return `${what} —— 看 / 动 / 网络这一族现在发不出去，我不拿别的板当目标。${held.unit} 这场调试仍然**进行中**（我没有自动替你落 paused）：${next}；要停下来就自己 workbench_diy_debug_pause（不问审批），页面切回来了就接着看。`;
+}
+function boardProbeOf(page) {
+	return {
+		workbench: page.ok,
+		where: page.where,
+		bar: page.open !== null,
+		board: page.board,
+		open: page.open === true,
+		drawn: page.shown
+	};
+}
+function boardStateOf(page, workshop) {
+	return boardFactOf(boardProbeOf(page), workshop);
+}
+function boardGateText(situation, unit, page) {
+	if (situation === "off-workspace") return `用户现在不在 DIY 工作区 —— 外壳选中的是 ${page.where || "(问不出来是哪一块)"}。工坊那块板没在屏上，${unit} 的这张卡我看不到，也不拿别的板当目标。让用户在左栏切回「工作台DIY」；这之前我可以继续改源码 / build / 跑门禁。`;
+	if (situation === "panel-closed") return `工作台面板没画在屏上（右栏收着，或者这一页让给了别的面板：文件预览、模块市场等）。让用户把「工作台面板」切回来（或把右栏展开），我再接着看 ${unit}。`;
+	return `你现在这一页画的是 ${page.board || "(不知道哪一块)"} 的面板，工坊那块板没在这一屏 —— ${unit} 的这张卡不在屏上，我不拿别的板当目标。请用户在左栏切回「工作台DIY」；这之前我可以继续改源码 / build / 跑门禁。`;
+}
 async function pageAt(ctx, exec, raw, options = {}) {
 	const { packagesDir } = workshopOf(ctx, exec);
 	const args = asRecord$3(raw);
@@ -4053,6 +4270,17 @@ async function pageAt(ctx, exec, raw, options = {}) {
 		const { page } = handshake;
 		throw new Error(`你现在这一页不是工作台（${page.title || "(没有标题)"} ${page.url}）—— 把工作台那一页切到前台，再喊我一次。我只看用户正在看的那一页。`);
 	}
+	const workshop = workshopPathOf(ctx);
+	const board = boardStateOf(handshake.page, workshop);
+	const situation = boardSituation(boardProbeOf(handshake.page), workshop);
+	const held = ctx.get("workbenchDiyDebug")?.live(Date.now()) ?? null;
+	const sessionId = sessionIdOf(exec);
+	if (options.requirePact !== false && held !== null) {
+		if (held.sessionId !== sessionId) throw new Error(debugForeignPactText(held));
+		if (held.phase === "paused") throw new Error(debugPausedText(held));
+		if (board === "other" || board === "hidden") throw new Error(debugOffBoardText(held, situation));
+	}
+	if (options.requireBoard !== false && (board === "other" || board === "hidden")) throw new Error(boardGateText(situation, wanted, handshake.page));
 	return {
 		packagesDir,
 		unit: wanted,
@@ -4060,10 +4288,155 @@ async function pageAt(ctx, exec, raw, options = {}) {
 		shell,
 		command,
 		session,
-		bound: handshake.bound
+		bound: handshake.bound,
+		board,
+		boardPath: handshake.page.board
 	};
 }
 //#endregion
+//#region src/modules/panels/model/diy-debug-tools.ts
+var EMPTY = {
+	type: "object",
+	properties: {},
+	additionalProperties: false
+};
+function debugRefusalText(code, held) {
+	switch (code) {
+		case "held-by-other": return `另一场调试还占着那块屏（${held === void 0 ? "另一个会话" : held.sessionId}）—— 一台机器同时只允许一场：让它先 workbench_diy_debug_stop，或等它收工。`;
+		case "already-held": return `你这个会话已经持有一场调试（${held === void 0 ? "" : `${held.unit}，${held.phase}`}）—— 要换目标先 workbench_diy_debug_stop；暂停着要接着看用 workbench_diy_debug_resume。`;
+		case "not-owner": return "这个调试态不是你这个会话的 —— 谁开始的谁收工。";
+		case "none": return "现在没有调试态。";
+		case "already-paused": return "已经暂停了 —— 要接着看用 workbench_diy_debug_resume（会再要用户点头）。";
+		case "already-debugging": return "正在调试中，不用再开一次。";
+	}
+}
+function renderDebugStart(state) {
+	return [`开始调试 ${state.unit}（声明的目标：${state.board === "" ? "用户那一屏" : state.board}）。`, "现在看 / 动 / 网络那一族才把屏当目标 —— 收工前记得 workbench_diy_debug_stop。"].join("\n");
+}
+function renderDebugPause(state) {
+	return [`调试暂停了（${state.unit}）—— 动作族关闸，不再拿屏当目标。`, "改源码 / build / 跑门禁照常；要看屏再 workbench_diy_debug_resume（会再要用户点头一次）。"].join("\n");
+}
+function renderDebugResume(state) {
+	return [`继续调试 ${state.unit} —— 请用户回到「工作台DIY」那一屏。`, "卡不在屏上时我会当场拒（不拿别的板当目标）。"].join("\n");
+}
+function renderDebugStop(state) {
+	return `收工了：${state.unit} 的调试态清掉了（占用解除）。`;
+}
+function moveOrThrow(move, held) {
+	if (move.ok) return move.state;
+	throw new Error(debugRefusalText(move.code, held ?? void 0));
+}
+function registerDebugTools(ctx, tools, store) {
+	const startTool = {
+		name: DIY_DEBUG_START_TOOL,
+		description: "开始调试：占用用户那一屏（要点头一次）。声明 unit 之后，看 / 动那一族才把屏当目标。",
+		parameters: withApprovalNote({
+			type: "object",
+			properties: { unit: {
+				type: "string",
+				description: "工坊里的 unit（workbench_diy_list 会给）。"
+			} },
+			required: ["unit"],
+			additionalProperties: false
+		}, { required: true }),
+		output: OUTPUT$2,
+		async execute(raw, exec) {
+			const { packagesDir, workspace } = workshopOf(ctx, exec);
+			const unit = asText$1(asRecord$3(raw)["unit"]);
+			if (unit === "") {
+				const { modules } = modulesOf(ctx, packagesDir);
+				throw new Error(`要一个 unit（工坊里：${modules.map((one) => one.unit).join(", ") || "（空）"}）`);
+			}
+			const held = store.live(Date.now());
+			const page = await pageAt(ctx, exec, raw, {
+				requireBoard: false,
+				requirePact: false
+			});
+			const state = moveOrThrow(store.begin({
+				sessionId: sessionIdOf(exec) ?? "",
+				workspace: workspace ?? "",
+				board: page.boardPath,
+				unit,
+				name: modulesOf(ctx, packagesDir).modules.find((one) => one.unit === unit)?.name ?? unit,
+				now: Date.now()
+			}), held);
+			return plainJson({
+				workshop: packagesDir,
+				unit,
+				board: state.board,
+				phase: state.phase,
+				state,
+				text: renderDebugStart(state)
+			});
+		}
+	};
+	const pauseTool = {
+		name: DIY_DEBUG_PAUSE_TOOL,
+		description: "暂停调试（不审批）：动作族关闸，不再拿屏当目标。要看屏再 debug_resume。",
+		parameters: EMPTY,
+		output: OUTPUT$2,
+		async execute(_raw, exec) {
+			const { packagesDir } = workshopOf(ctx, exec);
+			const held = store.live(Date.now());
+			const state = moveOrThrow(store.pause(sessionIdOf(exec) ?? "", Date.now()), held);
+			return plainJson({
+				workshop: packagesDir,
+				unit: state.unit,
+				phase: state.phase,
+				state,
+				text: renderDebugPause(state)
+			});
+		}
+	};
+	const resumeTool = {
+		name: DIY_DEBUG_RESUME_TOOL,
+		description: "继续调试（要点头一次）：请用户回到「工作台DIY」那一屏。",
+		parameters: withApprovalNote(EMPTY, { required: true }),
+		output: OUTPUT$2,
+		async execute(_raw, exec) {
+			const { packagesDir } = workshopOf(ctx, exec);
+			const held = store.live(Date.now());
+			const page = await pageAt(ctx, exec, { unit: held?.unit ?? "" }, {
+				requireBoard: false,
+				requirePact: false,
+				requireUnit: false
+			});
+			const state = moveOrThrow(store.resume(sessionIdOf(exec) ?? "", Date.now()), held);
+			return plainJson({
+				workshop: packagesDir,
+				unit: state.unit,
+				board: page.boardPath,
+				phase: state.phase,
+				state,
+				text: renderDebugResume(state)
+			});
+		}
+	};
+	const stopTool = {
+		name: DIY_DEBUG_STOP_TOOL,
+		description: "结束调试（不审批）：清掉\"占用用户那一屏\"这件事。收工用它。",
+		parameters: EMPTY,
+		output: OUTPUT$2,
+		async execute(_raw, exec) {
+			const { packagesDir } = workshopOf(ctx, exec);
+			const held = store.live(Date.now());
+			const state = moveOrThrow(store.stop(sessionIdOf(exec) ?? "", Date.now()), held);
+			return plainJson({
+				workshop: packagesDir,
+				unit: state.unit,
+				phase: "idle",
+				text: renderDebugStop(state)
+			});
+		}
+	};
+	return [
+		tools.register(startTool),
+		tools.register(pauseTool),
+		tools.register(resumeTool),
+		tools.register(stopTool)
+	];
+}
+//#endregion
 //#region src/modules/panels/model/diy-browser-act.ts
 var ACT_TIMEOUT_MS = 15e3;
 function actTargetOf(raw) {
@@ -4180,12 +4553,11 @@ async function scrollIntoView(shell, command, session, unit, selector) {
 async function reloadPage(shell, command, session) {
 	return actBrowser(shell, command, session, ["eval", `(() => { setTimeout(() => location.reload(), 30); return JSON.stringify({ ok: true }); })()`]);
 }
-async function shootAtWidth(shell, command, session, file, width, height) {
+async function shootAtWidth(shell, command, session, file, width = 0, height = 0) {
 	const step = await actBrowser(shell, command, session, [
 		"screenshot",
 		file,
-		"--width",
-		String(width),
+		...width > 0 ? ["--width", String(width)] : [],
 		...height > 0 ? ["--height", String(height)] : []
 	], LOOK_TIMEOUT_MS);
 	return {
@@ -4321,16 +4693,20 @@ function registerLookTools(ctx, tools) {
 		},
 		output: OUTPUT$2,
 		async execute(raw, exec) {
-			const { packagesDir, unit, shell, command, session } = await pageAt(ctx, exec, raw);
+			const { packagesDir, unit, shell, command, session, board } = await pageAt(ctx, exec, raw);
 			const pick = pickOf(asRecord$3(raw));
 			let view = await measureCard(shell, command, session, unit, pick);
-			if (!view.ok) return plainJson({
-				workshop: packagesDir,
-				unit,
-				ok: false,
-				cards: view.cards,
-				text: renderMissingCard(unit, view.cards, view.anchored)
-			});
+			if (!view.ok || !view.visible) {
+				const state = view.ok ? "hidden" : board;
+				return plainJson({
+					workshop: packagesDir,
+					unit,
+					ok: false,
+					board: state,
+					cards: view.cards,
+					text: renderMissingCard(unit, view, state)
+				});
+			}
 			if (!insideViewportOf(view)) {
 				await scrollIntoView(shell, command, session, unit, "");
 				view = await measureCard(shell, command, session, unit, pick);
@@ -4431,9 +4807,12 @@ function renderLook(unit, view, shot, pick) {
 		...view.clipped ? ["有内容被裁掉了（某一格比它自己的宽度还宽）—— 这是要改的信号"] : []
 	].join("\n");
 }
-function renderMissingCard(unit, cards, anchored) {
-	if (anchored) return `面板里给 ${unit} 留了位置（锚点在），但里面没有卡片 —— 它的 View 没画出来：要么渲染时抛了（看 workbench_diy_panel 的运行态上报与 workbench_diy_status），要么它返回了空 / 没套卡壳。你现在这一页面板里一共 ${String(cards)} 张卡。`;
-	return `你现在这一页的面板里没有 ${unit} 这张卡（面板里现在有 ${String(cards)} 张卡）。三件事，按顺序试：① workbench_diy_show（unit=${unit}）把它上板；② 右栏可能没停在「工作台面板」那一列 —— 让用户切回来；③ 页面上跑的外壳可能还是旧的一份（锚点由外壳盖）—— 让用户刷新一次页面。`;
+function renderMissingCard(unit, view, board) {
+	if (board === "other") return `你现在这一页画的是别的工作区的面板，工坊那块板没在这一屏 —— ${unit} 的卡不在屏上，我不拿别的板当目标。请用户在左栏切回「工作台DIY」，或把这张卡上到他正看着的那块板上。`;
+	if (board === "hidden") return `右栏收着 —— 面板没画在屏上（锚点还在页面里，但看不见它），量不到也不该拍 ${unit}。让用户把面板展开、或切回「工作台DIY」，我再接着看。`;
+	if (view.anchored) return `面板里给 ${unit} 留了位置（锚点在），但里面没有卡片 —— 它的 View 没画出来：要么渲染时抛了（看 workbench_diy_panel 的运行态上报与 workbench_diy_status），要么它返回了空 / 没套卡壳。你现在这一页面板里一共 ${String(view.cards)} 张卡。`;
+	const stale = board === "unknown" ? "③ 页面上跑的外壳可能还是旧的一份（锚点由外壳盖）—— 让用户刷新一次页面。" : "";
+	return `你现在这一页的面板里没有 ${unit} 这张卡（面板里现在有 ${String(view.cards)} 张卡）。按顺序试：① workbench_diy_show（unit=${unit}）把它上板；② 右栏可能没停在「工作台面板」那一列 —— 让用户切回来。${stale}`;
 }
 //#endregion
 //#region src/modules/panels/model/diy-logs.ts
@@ -5089,24 +5468,26 @@ function registerActTools(ctx, tools) {
 	};
 	const viewportTool = {
 		name: DIY_VIEWPORT_TOOL,
-		description: "按某个宽度重拍一张整屏图（看窄屏/宽屏下这张卡挤不挤）—— 只在这一拍里换视口。",
+		description: "拍整屏图。不给宽高 = 按用户当前窗口拍；给了才换视口 —— 会回流一次。",
 		parameters: pageSchema({
 			width: {
 				type: "number",
-				description: "视口宽度（CSS px，例如 390）。"
+				description: "视口宽度（CSS px，如 390）；不填按当前窗口。"
 			},
 			height: {
 				type: "number",
 				description: "视口高度（可不要）。"
 			}
-		}, ["width"]),
+		}, []),
 		output: OUTPUT$2,
 		async execute(raw, exec) {
 			const page = await pageAt(ctx, exec, raw, { requireUnit: false });
-			const width = asNumber(page.args["width"]);
-			if (width === void 0 || width <= 0) throw new Error("多宽？给 width（CSS px）。");
+			const width = asNumber(page.args["width"]) ?? 0;
+			if (width < 0) throw new Error("width 得是正的 CSS px；不给就按用户当前窗口拍。");
 			const height = asNumber(page.args["height"]) ?? 0;
-			const file = join(dirname(page.packagesDir), "shots", `${page.unit || "page"}-${String(width)}-${String(Date.now())}.png`);
+			const overrode = width > 0 || height > 0;
+			const stamp = overrode ? `${String(width)}x${String(height)}` : "now";
+			const file = join(dirname(page.packagesDir), "shots", `${page.unit || "page"}-${stamp}-${String(Date.now())}.png`);
 			await writeShotsDir(page.shell, dirname(file));
 			const shot = await shootAtWidth(page.shell, page.command, page.session, file, width, height);
 			return plainJson({
@@ -5114,12 +5495,13 @@ function registerActTools(ctx, tools) {
 				unit: page.unit,
 				ok: shot.ok,
 				file: shot.file,
-				width,
-				viewport: {
+				overrode,
+				width: overrode ? width : null,
+				viewport: overrode ? {
 					width,
 					height
-				},
-				text: shot.ok ? `按 ${String(width)}px 宽重拍了一张：${shot.file}（页面按新视口回流，只在这一拍里生效）。` : `没拍成：${shot.reason}`
+				} : null,
+				text: shot.ok ? overrode ? `重拍了一张：${shot.file}（临时换了视口${width > 0 ? ` 宽 ${String(width)}px` : ""}${height > 0 ? ` 高 ${String(height)}px` : ""}，你那一屏会回流一次、拍完就恢复）。` : `按你当前窗口拍了一张：${shot.file}（没动你的视口）。` : `没拍成：${shot.reason}`
 			});
 		}
 	};
@@ -5483,7 +5865,7 @@ function renderList(packagesDir, modules) {
 }
 //#endregion
 //#region src/modules/panels/model/diy-tools.ts
-function registerDiyTools(ctx, market, panels) {
+function registerDiyTools(ctx, market, panels, debug) {
 	const tools = ctx.get("tools");
 	if (tools === void 0) {
 		ctx.logger?.info?.("[dsh-workbench] 没有 tools 服务，跳过 DIY 工坊工具注册");
@@ -5831,11 +6213,20 @@ function registerDiyTools(ctx, market, panels) {
 		...registerLogTools(ctx, tools),
 		...registerNetTools(ctx, tools),
 		...registerActTools(ctx, tools),
+		...registerDebugTools(ctx, tools, debug),
 		tools.register(showTool),
 		tools.register(installTool)
 	];
 }
 //#endregion
+//#region src/modules/panels/model/diy-debug-routes.ts
+function diyDebugRoutes(store) {
+	return { "panels/diy-debug": () => ({
+		ok: true,
+		state: store.live(Date.now())
+	}) };
+}
+//#endregion
 //#region src/shared/api/host/release.ts
 function parseLedgerVersion(stdout, name) {
 	const parsed = parseJsonLoose(stdout);
@@ -7869,7 +8260,14 @@ function applyPanelsPref(panels, payload) {
 //#endregion
 //#region src/modules/panels/model/handoff.ts
 var PANELS_FACT = "panels";
+var DIY_DEBUG_FACT = "diy-debug";
 var CAPABILITY_FACT = "capability";
+var DEBUG_TOOLS = [
+	DIY_DEBUG_START_TOOL,
+	DIY_DEBUG_PAUSE_TOOL,
+	DIY_DEBUG_RESUME_TOOL,
+	DIY_DEBUG_STOP_TOOL
+];
 var PROVISION_TOOLS = {
 	[MODULES_INSTALL_TOOL]: "install",
 	[MODULES_UPDATE_TOOL]: "update",
@@ -7905,6 +8303,7 @@ function panelsFactsOf(call, manifests) {
 	if (call.source === "workbench_modules_list") return [PANELS_FACT, CAPABILITY_FACT];
 	if (call.source === "workbench_modules_update_workbench") return [PANELS_FACT, CAPABILITY_FACT];
 	if (call.source === "workbench_diy_list") return [PANELS_FACT];
+	if (DEBUG_TOOLS.includes(call.source)) return [DIY_DEBUG_FACT];
 	const request = requestOf(call);
 	if (request === void 0) return void 0;
 	return [
@@ -8479,6 +8878,8 @@ var OWNED = [{
 			logger
 		});
 		ctx.provide(PANELS_SERVICE, panels);
+		const debug = createDebugStore();
+		ctx.provide(DIY_DEBUG_SERVICE, debug);
 		const profileDir = profileDirOf(ctx);
 		const shell = ctx.get("shell");
 		const moduleManifests = () => {
@@ -8526,12 +8927,13 @@ var OWNED = [{
 				...pluginRoutes({
 					ledger,
 					...shell === void 0 ? {} : { shell }
-				})
+				}),
+				...diyDebugRoutes(debug)
 			},
 			registerTools: () => [
 				...registerPanelTools(ctx, panels, values),
 				...registerMarketTools(ctx, market),
-				...registerDiyTools(ctx, market, panels)
+				...registerDiyTools(ctx, market, panels, debug)
 			],
 			factsOf: (call) => panelsFactsOf(call, manifests()),
 			needsApproval: panelsApproval,
@@ -8542,7 +8944,7 @@ var OWNED = [{
 					return [...manifests().flatMap((manifest) => owned.has(manifest.id) || resolveScope({
 						id: manifest.id,
 						boards
-					}) ? [] : manifest.tools.map((tool) => tool.name)), ...inWorkshopSession(ctx, workspace) ? [] : [...DIY_TOOLS]];
+					}) ? [] : manifest.tools.map((tool) => tool.name)), ...inWorkshopSession(ctx, workspace) ? [] : [...DIY_TOOLS, ...DIY_DEBUG_TOOLS]];
 				},
 				subscribe: (listener) => panels.subscribe(listener)
 			},
@@ -8875,6 +9277,122 @@ function createPostChannels(deps) {
 	};
 }
 //#endregion
+//#region src/shared/api/host/diy-debug-act.ts
+var DEBUG_NOTICE_KIND = "workbench-diy";
+var INTENT_WORD = {
+	pause: "暂停",
+	resume: "继续",
+	stop: "结束"
+};
+function debugNoticeText(intent, state) {
+	const head = `［工作台 DIY］用户按了「${INTENT_WORD[intent]}」：`;
+	if (intent === "pause") return `${head}${state.unit} 这场调试暂停了 —— 现在别再把那一屏当目标（看 / 动 / 网络那一族发不出去）。要接着看屏就等用户按「继续」；在那之前照常改源码 / build / 跑门禁。`;
+	if (intent === "resume") return `${head}${state.unit} 这场调试重新开始了 —— 那一屏又归你看。屏 / 板不对的话照旧会被拒，拒了就照实说清是哪种不对。`;
+	return `${head}${state.unit} 这场调试收工了（占用解除）。要再调试就重新 start 一场。`;
+}
+function debugNoticeSummary(intent, state) {
+	return `工作台 DIY：用户按了${INTENT_WORD[intent]}（${state.unit}）`;
+}
+function debugNotice(intent, state) {
+	const summary = debugNoticeSummary(intent, state);
+	return {
+		summary,
+		message: {
+			role: "user",
+			id: randomUUID(),
+			content: [{
+				type: "text",
+				text: debugNoticeText(intent, state)
+			}],
+			source: {
+				kind: DEBUG_NOTICE_KIND,
+				form: "notice",
+				summary
+			}
+		}
+	};
+}
+var NOTICE_MODE = {
+	resume: "wake",
+	pause: "hold",
+	stop: "drop"
+};
+var held = /* @__PURE__ */ new Map();
+function holdNotice(sessionId, message) {
+	const list = held.get(sessionId);
+	if (list === void 0) held.set(sessionId, [message]);
+	else list.push(message);
+}
+function takeHeldNotices(sessionId) {
+	const list = held.get(sessionId) ?? [];
+	held.delete(sessionId);
+	return list;
+}
+function deliverDebugNotice(agents, sessionId, message, mode = "wake") {
+	const agent = agents?.get(sessionId);
+	if (agent === void 0) {
+		if (mode === "drop") return "none";
+		holdNotice(sessionId, message);
+		return "held";
+	}
+	if (agent.status !== "idle") {
+		agent.inject(message);
+		return "inject";
+	}
+	if (mode === "wake") {
+		agent.followup(message);
+		return "followup";
+	}
+	if (mode === "hold") {
+		holdNotice(sessionId, message);
+		return "held";
+	}
+	return "skipped-idle";
+}
+var REFUSAL = {
+	"already-paused": "这一场已经是暂停态了",
+	"already-debugging": "这一场本来就在调试中",
+	none: "现在没有调试态",
+	"not-owner": "这场调试不是这个会话的"
+};
+function debugActResource(deps) {
+	const now = () => deps.now?.() ?? Date.now();
+	return {
+		resource: "act",
+		handle(payload) {
+			const intent = parseDebugIntent(payload?.intent);
+			if (intent === null) return {
+				ok: false,
+				text: "不认识的意图（只认 pause / resume / stop）"
+			};
+			const store = deps.store();
+			if (store === void 0) return {
+				ok: false,
+				text: "现在没有调试态 —— 没什么可暂停 / 继续 / 结束的"
+			};
+			const at = now();
+			const held = store.live(at);
+			if (held === null) return {
+				ok: false,
+				text: "现在没有调试态 —— 没什么可暂停 / 继续 / 结束的"
+			};
+			const move = intent === "pause" ? store.pause(held.sessionId, at) : intent === "resume" ? store.resume(held.sessionId, at) : store.stop(held.sessionId, at);
+			if (!move.ok) return {
+				ok: false,
+				text: REFUSAL[move.code] ?? `按不动：${move.code}`
+			};
+			const notice = deps.notice?.(intent, move.state) ?? debugNotice(intent, move.state);
+			return {
+				ok: true,
+				intent,
+				delivered: deliverDebugNotice(deps.agents(), held.sessionId, notice.message, NOTICE_MODE[intent]),
+				summary: notice.summary,
+				state: store.live(now())
+			};
+		}
+	};
+}
+//#endregion
 //#region src/shared/api/host/events.ts
 var HEARTBEAT_MS = 25e3;
 function frame(payload) {
@@ -11004,15 +11522,17 @@ function createToolScope(options) {
 	};
 }
 //#endregion
-//#region src/app/host.ts
-var name = "dsh-workbench";
-var inject = ["webServer"];
+//#region src/shared/api/host/host-args.ts
 function asArgs(value) {
 	return typeof value === "object" && value !== null ? value : {};
 }
 function warn(ctx, message) {
 	ctx.logger?.warn?.(`[dsh-workbench] ${message}`);
 }
+//#endregion
+//#region src/app/host.ts
+var name = "dsh-workbench";
+var inject = ["webServer"];
 function seedWorkbenchRuntime(ctx) {
 	const root = runtimeSeedRootOf(ctx);
 	if (root === null) return;
@@ -11384,9 +11904,10 @@ function apply(ctx) {
 			if (decision.kind === "reject") return decision;
 			try {
 				const message = await injector.inject(decision.messages ?? [], payload?.agent);
-				return message === void 0 ? decision : {
+				const extra = [...takeHeldNotices(String((payload?.agent)?.id ?? "")), ...message === void 0 ? [] : [message]];
+				return extra.length === 0 ? decision : {
 					...decision,
-					messages: [...decision.messages ?? [], message]
+					messages: [...decision.messages ?? [], ...extra]
 				};
 			} catch (error) {
 				ctx.logger?.warn?.(`[dsh-workbench] 对话引用注入失败：${String(error)}`);
@@ -11397,6 +11918,12 @@ function apply(ctx) {
 	}, `${PLUGIN_ID}: 对话引用注入`);
 	ctx.effect(() => registerFactStream(ctx, facts), `${PLUGIN_ID}: 变更流`);
 	ctx.effect(() => registerPanelState(ctx, panelState), `${PLUGIN_ID}: 面板运行态上报（浏览器半侧报自己的取数与渲染收尾）`);
+	ctx.effect(() => {
+		return registerDiyDebugAct(ctx, debugActResource({
+			store: () => ctx.get(DIY_DEBUG_SERVICE),
+			agents: () => ctx.get("agents")
+		}), { bump: (names) => facts.bump(names) });
+	}, `${PLUGIN_ID}: DIY 调试的三个键（用户按的）`);
 	ctx.effect(() => registerApi(ctx, routes), `${PLUGIN_ID}: HTTP 投影`);
 }
 //#endregion