@tea-agent/loop-agent 0.40.0-next.4 → 0.40.0-next.6

package/dist/worker/observe/static/operator-chrome.js

@@ -12,18 +12,17 @@
  */
 
 export const OPERATE_TABS = Object.freeze([
-	{ id: "chat", label: "对话", href: "#/chat" },
-	{ id: "tasks", label: "任务", href: "#/tasks" },
-	{ id: "recovery", label: "恢复", href: "#/recovery" },
-	{ id: "night", label: "夜间", href: "#/night" },
-	{ id: "models", label: "模型与认证", href: "#/models" },
-	{ id: "settings", label: "设置", href: "#/settings" },
+	{ id: "tasks", label: "任务", href: "/#/operate/tasks" },
+	{ id: "recovery", label: "恢复", href: "/#/operate/recovery" },
+	{ id: "night", label: "夜间", href: "/#/operate/night" },
+	{ id: "models", label: "模型与认证", href: "/#/operate/models" },
+	{ id: "settings", label: "设置", href: "/#/operate/settings" },
 ]);
 
 export const INSPECT_TABS = Object.freeze([
-	{ id: "dashboard", label: "总览", href: "#/" },
-	{ id: "pool", label: "资源池", href: "#/pool" },
-	{ id: "failures", label: "异常 Task", href: "#/failures" },
+	{ id: "dashboard", label: "总览", href: "/#/inspect" },
+	{ id: "pool", label: "资源池", href: "/#/inspect/pool" },
+	{ id: "failures", label: "异常 Task", href: "/#/inspect/failures" },
 ]);
 
 export const READINESS_LABELS = Object.freeze({
@@ -45,14 +44,39 @@ const CONTEXT_KIND_LABELS = Object.freeze({
 /** 支持返回操作侧的对象视图 → 返回落地工作区。v1 仅接通 recovery 闭环。 */
 const RETURNABLE_VIEWS = new Set(["dag", "run"]);
 
+export function parseInspectWorkspaceId(hashValue) {
+	const { query } = splitHash(hashValue);
+	if (!query) return null;
+	const id = query.get("workspaceId")?.trim();
+	return id || null;
+}
+
+export function withWorkspaceQuery(href, workspaceId) {
+	const raw = String(href ?? "");
+	if (!workspaceId) return raw;
+	const qIndex = raw.indexOf("?");
+	if (qIndex < 0) return `${raw}?workspaceId=${encodeURIComponent(workspaceId)}`;
+	const params = new URLSearchParams(raw.slice(qIndex + 1));
+	if (params.get("workspaceId") === workspaceId) return raw;
+	params.set("workspaceId", workspaceId);
+	return `${raw.slice(0, qIndex)}?${params.toString()}`;
+}
+
 function splitHash(hashValue) {
 	const raw = String(hashValue ?? "").replace(/^#/, "");
 	const qIndex = raw.indexOf("?");
-	const path = (qIndex >= 0 ? raw.slice(0, qIndex) : raw) || "/";
+	const pathPart = (qIndex >= 0 ? raw.slice(0, qIndex) : raw) || "/";
+	const path = pathPart.startsWith("/") ? pathPart : `/${pathPart}`;
 	const query = qIndex >= 0 ? new URLSearchParams(raw.slice(qIndex + 1)) : null;
 	return { path, query };
 }
 
+function inspectInternalPath(path) {
+	if (path === "/inspect" || path === "/inspect/") return "/";
+	if (path.startsWith("/inspect/")) return path.slice("/inspect".length) || "/";
+	return path;
+}
+
 function decode(value) {
 	try {
 		return decodeURIComponent(value);
@@ -64,7 +88,8 @@ function decode(value) {
 /** 与 router.js 同形的最小对象视图解析（只读 chrome 用，不替代路由）。 */
 export function parseInspectObjectView(hashValue) {
 	const { path } = splitHash(hashValue);
-	const match = /^\/(dag|run|task|feature|batch|night)\/([^/]+)$/.exec(path);
+	const internal = inspectInternalPath(path);
+	const match = /^\/(dag|run|task|feature|batch|night)\/([^/]+)$/.exec(internal);
 	if (!match) return null;
 	const id = decode(match[2]);
 	if (!id) return null;
@@ -79,10 +104,15 @@ export function parseInspectObjectView(hashValue) {
  */
 export function activeInspectTabHref(hashValue) {
 	const { path } = splitHash(hashValue);
-	if (path === "/" || path === "") return "#/";
-	if (path === "/pool" || path.startsWith("/task/")) return "#/pool";
-	if (path === "/failures") return "#/failures";
-	if (path.startsWith("/feature/")) return "#/";
+	const internal = inspectInternalPath(path);
+	if (internal === "/" || internal === "" || internal === "/inspect") {
+		return "/#/inspect";
+	}
+	if (internal === "/pool" || internal.startsWith("/task/")) {
+		return "/#/inspect/pool";
+	}
+	if (internal === "/failures") return "/#/inspect/failures";
+	if (internal.startsWith("/feature/")) return "/#/inspect";
 	return null;
 }
 
@@ -104,7 +134,7 @@ export function parseInspectContext(hashValue) {
 		id: objectView.id,
 		from,
 		kindLabel: CONTEXT_KIND_LABELS[objectView.view] ?? objectView.view,
-		returnHref: `/#/recovery${suffix ? `?${suffix}` : ""}`,
+		returnHref: `/#/operate/recovery${suffix ? `?${suffix}` : ""}`,
 		returnLabel: "返回 恢复",
 	};
 }
@@ -113,20 +143,19 @@ export function parseInspectContext(hashValue) {
 export function resolveOperateHrefFromInspectHash(hashValue) {
 	const objectView = parseInspectObjectView(hashValue);
 	if (objectView?.view === "dag") {
-		return `/#/recovery?dagRunId=${encodeURIComponent(objectView.id)}`;
+		return `/#/operate/recovery?dagRunId=${encodeURIComponent(objectView.id)}`;
 	}
-	// 2026-08-16: 无持有对象时默认落到对话页（与 Console 默认 landing 一致）。
-	return "/#/chat";
+	return "/#/operate/tasks";
 }
 
 /** Inspect DAG 详情 → Operate Recovery 协作中止深链（只改导航，不发 mutation）。 */
 export function buildOperateInterruptHref(dagRunId) {
-	return `/#/recovery?dagRunId=${encodeURIComponent(dagRunId)}&intent=interrupt`;
+	return `/#/operate/recovery?dagRunId=${encodeURIComponent(dagRunId)}&intent=interrupt`;
 }
 
 /** 操作侧 → Inspect 的 canonical 深链（可携带 from 以激活上下文 chip）。 */
 export function buildInspectDagHref(dagRunId, options = {}) {
-	const base = `/inspect/#/dag/${encodeURIComponent(dagRunId)}`;
+	const base = `/#/inspect/dag/${encodeURIComponent(dagRunId)}`;
 	return options.from === "recovery" ? `${base}?from=recovery` : base;
 }
 
@@ -174,45 +203,76 @@ export function chromeStateFromHealth(body) {
  * 共用同一份模型结构，保证 DOM 契约一致。
  */
 export function buildOperatorChromeModel(config) {
-	const mode = config.mode === "inspect" ? "inspect" : "operate";
-	const tabs = (mode === "inspect" ? INSPECT_TABS : OPERATE_TABS).map(
-		(tab) => ({
-			...tab,
-			active: tab.href === (config.activeTabHref ?? null),
-		}),
-	);
+	const mode =
+		config.mode === "inspect"
+			? "inspect"
+			: config.mode === "chat"
+				? "chat"
+				: "operate";
+	const tabs = (
+		mode === "inspect"
+			? INSPECT_TABS
+			: mode === "operate"
+				? OPERATE_TABS
+				: []
+	).map((tab) => ({
+		...tab,
+		active:
+			tab.href ===
+			(String(config.activeTabHref ?? "").split("?")[0] || null),
+	}));
 	const state = config.readinessState ?? "unknown";
+	const operateHref = config.operateHref ?? "/#/operate/tasks";
+	const inspectHref = config.inspectHref ?? "/#/inspect";
+	const activeWorkspaceId = config.workspaceSwitcher?.activeId ?? null;
 	return {
 		mode,
-		homeHref: mode === "inspect" ? "/inspect/#/" : "/#/",
+		homeHref: withWorkspaceQuery(
+			mode === "inspect" ? "/#/inspect" : "/#/chat",
+			activeWorkspaceId,
+		),
 		brand: "Loop Agent",
 		repo: config.repo ?? null,
+		workspaceSwitcher: config.workspaceSwitcher ?? null,
 		modeButtons: [
+			{
+				id: "chat",
+				label: "对话",
+				href: config.chatHref ?? "/#/chat",
+				active: mode === "chat",
+			},
 			{
 				id: "operate",
 				label: "操作",
-				// 2026-08-16: 默认落到对话页，与 Console 默认 landing（chat）一致。
-				href: config.operateHref ?? "/#/chat",
+				href: operateHref,
 				active: mode === "operate",
 			},
 			{
 				id: "inspect",
 				label: "观测",
-				href: config.inspectHref ?? "/inspect/#/",
+				href: inspectHref,
 				active: mode === "inspect",
 			},
 		],
 		context: config.context ?? null,
 		freshness: mode === "inspect" && config.freshness !== false,
+		statusVisible: config.statusVisible !== false,
 		pi: {
 			state,
 			label: READINESS_LABELS[state] ?? state,
 			href:
-				config.readinessHref ?? (mode === "inspect" ? "/#/models" : "#/models"),
+				config.readinessHref ??
+				(mode === "inspect" ? "/#/operate/models" : "/#/operate/models"),
 			title: config.readinessTitle ?? "",
 		},
+		workspaceTabsVisible: tabs.length > 0,
 		tabs,
-		tabsAriaLabel: mode === "inspect" ? "观测看板" : "操作工作区",
+		tabsAriaLabel:
+			mode === "inspect"
+				? "观测看板"
+				: mode === "operate"
+					? "操作工作区"
+					: "对话工作区",
 	};
 }
 
@@ -254,6 +314,17 @@ const ICONS = Object.freeze({
 			["path", { d: "M6 8.4v7.2M8.2 6.9 15.8 8" }],
 		],
 	},
+	folder: {
+		size: 14,
+		parts: [
+			["path", { d: "M3 6.5h6l2-2h4.5c1.4 0 2.5 1.1 2.5 2.5v9.5c0 1.4-1.1 2.5-2.5 2.5h-11C3.1 19 2 17.9 2 16.5V8c0-.8.4-1.5 1-1.5z" }],
+		],
+	},
+	check: {
+		size: 12,
+		strokeWidth: 2.4,
+		parts: [["path", { d: "m5 12 4 4L19 6" }]],
+	},
 	chevron: {
 		size: 10,
 		strokeWidth: 2.4,
@@ -366,10 +437,21 @@ export function mountOperatorChrome(root, config = {}) {
 	function build(model) {
 		freshnessText =
 			root.querySelector("#header-refresh")?.textContent ?? freshnessText;
-		root.textContent = "";
+		/* Keep the product-mode control connected while the surrounding chrome is
+		 * rebuilt. In particular, the shared thumb must retain its DOM identity and
+		 * previous transform so the browser can interpolate to the next mode instead
+		 * of flashing a freshly-created indicator at the destination. */
+		const persistentModeNav = root.querySelector(".och-mode");
+		if (persistentModeNav) root.appendChild(persistentModeNav);
+		for (const child of [...root.children]) {
+			if (child !== persistentModeNav) child.remove();
+		}
 		const chrome = el("div", "och");
 		const inner = el("div", "och-inner");
 		chrome.appendChild(inner);
+		/* Attach the new shell before measuring the persistent mode buttons. Moving
+		 * the nav within the same connected root preserves its painted transform. */
+		root.appendChild(chrome);
 
 		/* Band 1 */
 		const global = el("div", "och-global");
@@ -386,7 +468,89 @@ export function mountOperatorChrome(root, config = {}) {
 		brand.appendChild(el("span", null, model.brand));
 		global.appendChild(brand);
 
-		if (model.repo) {
+		if (model.workspaceSwitcher) {
+			const picker = el("div", "och-workspace-picker");
+			const items = Array.isArray(model.workspaceSwitcher.items)
+				? model.workspaceSwitcher.items
+				: [];
+			const active = items.find(
+				(item) => item.workspaceId === model.workspaceSwitcher.activeId,
+			);
+			const repoBtn = el("button", "och-repo och-workspace-trigger");
+			repoBtn.type = "button";
+			repoBtn.setAttribute("aria-haspopup", "menu");
+			repoBtn.setAttribute("aria-controls", popoverId);
+			repoBtn.setAttribute("aria-expanded", String(popoverOpen));
+			repoBtn.setAttribute(
+				"aria-label",
+				active ? `切换工作区，当前 ${active.name}` : "切换工作区",
+			);
+			icon(repoBtn, "folder");
+			repoBtn.appendChild(
+				el(
+					"span",
+					"och-repo-name",
+					active?.name ?? (model.workspaceSwitcher.loading ? "加载中…" : "选择工作区"),
+				),
+			);
+			icon(repoBtn, "chevron");
+			picker.appendChild(repoBtn);
+
+			const pop = el("div", "och-pop och-workspace-menu");
+			pop.id = popoverId;
+			pop.hidden = !popoverOpen;
+			pop.setAttribute("role", "menu");
+			pop.setAttribute("aria-label", "切换工作区");
+			pop.append(el("p", "och-pop-title", "工作区"));
+			if (items.length === 0) {
+				pop.append(
+					el(
+						"p",
+						"och-workspace-empty",
+						model.workspaceSwitcher.loading ? "正在加载工作区…" : "暂无工作区",
+					),
+				);
+			}
+			for (const item of items) {
+				const option = el("button", "och-workspace-option");
+				option.type = "button";
+				option.setAttribute("role", "menuitemradio");
+				option.setAttribute(
+					"aria-checked",
+					String(item.workspaceId === model.workspaceSwitcher.activeId),
+				);
+				const copy = el("span", "och-workspace-option-copy");
+				copy.append(
+					el("strong", null, item.name),
+					el("small", null, item.displayPath || ""),
+				);
+				option.appendChild(copy);
+				if (item.workspaceId === model.workspaceSwitcher.activeId) {
+					icon(option, "check");
+				}
+				option.addEventListener("click", (event) => {
+					event.stopPropagation();
+					popoverOpen = false;
+					if (
+						item.workspaceId !== model.workspaceSwitcher.activeId &&
+						typeof currentConfig.onSelectWorkspace === "function"
+					) {
+						currentConfig.onSelectWorkspace(item.workspaceId);
+					} else {
+						render();
+					}
+				});
+				pop.appendChild(option);
+			}
+			picker.appendChild(pop);
+			global.appendChild(picker);
+			repoBtn.addEventListener("click", (event) => {
+				event.stopPropagation();
+				popoverOpen = !popoverOpen;
+				repoBtn.setAttribute("aria-expanded", String(popoverOpen));
+				pop.hidden = !popoverOpen;
+			});
+		} else if (model.repo) {
 			const repoBtn = el("button", "och-repo");
 			repoBtn.type = "button";
 			repoBtn.setAttribute("aria-haspopup", "dialog");
@@ -430,22 +594,61 @@ export function mountOperatorChrome(root, config = {}) {
 			});
 		}
 
-		const modeNav = el("nav", "och-mode");
+		const modeNav = persistentModeNav ?? el("nav", "och-mode");
 		modeNav.setAttribute("aria-label", "产品模式");
-		for (const btn of model.modeButtons) {
-			const a = el("a", `och-mode-btn${btn.active ? " och-on" : ""}`);
+		const modeIcons = { chat: "radar", operate: "zap", inspect: "eye" };
+		let buttons = [...modeNav.querySelectorAll(".och-mode-btn")];
+		if (buttons.length !== model.modeButtons.length) {
+			modeNav.replaceChildren();
+			buttons = model.modeButtons.map((btn) => {
+				const a = el("a", "och-mode-btn");
+				a.dataset.mode = btn.id;
+				// 2026-08-22: inline-flex 布局下裸文本节点不参与 name-from-content，
+				// a11y snapshot 序列化为无名 link；显式 aria-label 保证「操作/观测」
+				// 对 find/读屏稳定可断言（frontend-test passed 权威依赖可见 find）。
+				a.setAttribute("aria-label", btn.label);
+				a.appendChild(makeIcon(modeIcons[btn.id] ?? "eye"));
+				a.appendChild(document.createTextNode(btn.label));
+				modeNav.appendChild(a);
+				return a;
+			});
+		}
+		for (const [index, btn] of model.modeButtons.entries()) {
+			const a = buttons[index];
 			a.href = btn.href;
 			a.dataset.mode = btn.id;
-			// 2026-08-22: inline-flex 布局下裸文本节点不参与 name-from-content，
-			// a11y snapshot 序列化为无名 link；显式 aria-label 保证「操作/观测」
-			// 对 find/读屏稳定可断言（frontend-test passed 权威依赖可见 find）。
-			a.setAttribute("aria-label", btn.label);
+			a.classList.toggle("och-on", btn.active);
 			if (btn.active) a.setAttribute("aria-current", "page");
-			a.appendChild(makeIcon(btn.id === "operate" ? "zap" : "eye"));
-			a.appendChild(document.createTextNode(btn.label));
-			modeNav.appendChild(a);
+			else a.removeAttribute("aria-current");
 		}
+		/* DSH 2026-08-23：椭圆选中态 + 共享滑块（160-220ms），同一实现覆盖
+		 * React（Operate/Chat 壳）与 vanilla（Inspect）。reduced-motion 下无动画。 */
+		let thumb = modeNav.querySelector(".och-mode-thumb");
+		const firstMount = !thumb;
+		if (!thumb) {
+			thumb = el("span", "och-mode-thumb");
+			thumb.setAttribute("aria-hidden", "true");
+			modeNav.appendChild(thumb);
+		}
+		const positionThumb = (mode) => {
+			const target = buttons.find((button) => button.dataset.mode === mode);
+			if (!target) {
+				thumb.style.opacity = "0";
+				return;
+			}
+			thumb.style.opacity = "";
+			thumb.style.width = `${target.offsetWidth}px`;
+			thumb.style.height = `${target.offsetHeight}px`;
+			thumb.style.transform = `translate3d(${target.offsetLeft}px, ${target.offsetTop}px, 0)`;
+		};
 		global.appendChild(modeNav);
+		positionThumb(model.mode);
+		if (firstMount) {
+			/* The initial placement must not animate in from the origin. Every later
+			 * update reuses this ready thumb and therefore transitions immediately from
+			 * its last painted transform. */
+			requestAnimationFrame(() => thumb.classList.add("is-ready"));
+		}
 
 		if (model.context) {
 			const chip = el("div", "och-context");
@@ -477,7 +680,7 @@ export function mountOperatorChrome(root, config = {}) {
 
 		global.appendChild(el("span", "och-spacer"));
 
-		if (model.freshness) {
+		if (model.statusVisible && model.freshness) {
 			const fresh = el("span", "och-fresh");
 			fresh.setAttribute("aria-label", "数据新鲜度");
 			fresh.appendChild(el("span", "och-fresh-dot"));
@@ -489,6 +692,10 @@ export function mountOperatorChrome(root, config = {}) {
 			global.appendChild(fresh);
 		}
 
+		/* r4 AC-002：Chat 模式右侧保持干净 — 不渲染 repo 名与 Pi readiness 胶囊
+		 * （多 Workspace 下 repo 身份归左栏行，readiness 归侧栏与横幅）。 */
+		const piHidden = !model.statusVisible || model.mode === "chat";
+		if (!piHidden) {
 		const pi = el("a", "och-pi");
 		pi.dataset.state = model.pi.state;
 		pi.href = model.pi.href;
@@ -499,65 +706,69 @@ export function mountOperatorChrome(root, config = {}) {
 		piState.textContent = model.pi.label;
 		pi.appendChild(piState);
 		global.appendChild(pi);
+		}
 
-		/* 标签带折叠切换（收展两态同一按钮，位于全局带右端）。 */
-		const fold = el("button", "och-workspace-fold");
-		fold.type = "button";
-		fold.setAttribute("aria-expanded", String(!workspaceCollapsed));
-		fold.setAttribute("aria-controls", "och-workspace");
-		const foldLabel = workspaceCollapsed ? "展开标签栏" : "收起标签栏";
-		fold.title = foldLabel;
-		fold.setAttribute("aria-label", foldLabel);
-		if (workspaceCollapsed) fold.classList.add("is-folded");
-		fold.appendChild(makeIcon("chevronUp"));
-		fold.addEventListener("click", () => {
-			workspaceCollapsed = !workspaceCollapsed;
-			try {
-				window.localStorage.setItem(
-					OCH_WORKSPACE_COLLAPSED_KEY,
-					workspaceCollapsed ? "1" : "0",
-				);
-			} catch {
-				/* localStorage 不可用时仅保持内存态。 */
+		if (model.workspaceTabsVisible) {
+			/* 标签带折叠切换（收展两态同一按钮，位于全局带右端）。 */
+			const fold = el("button", "och-workspace-fold");
+			fold.type = "button";
+			fold.setAttribute("aria-expanded", String(!workspaceCollapsed));
+			fold.setAttribute("aria-controls", "och-workspace");
+			const foldLabel = workspaceCollapsed ? "展开标签栏" : "收起标签栏";
+			fold.title = foldLabel;
+			fold.setAttribute("aria-label", foldLabel);
+			if (workspaceCollapsed) fold.classList.add("is-folded");
+			fold.appendChild(makeIcon("chevronUp"));
+			fold.addEventListener("click", () => {
+				workspaceCollapsed = !workspaceCollapsed;
+				try {
+					window.localStorage.setItem(
+						OCH_WORKSPACE_COLLAPSED_KEY,
+						workspaceCollapsed ? "1" : "0",
+					);
+				} catch {
+					/* localStorage 不可用时仅保持内存态。 */
+				}
+				const ws = root.querySelector(".och-workspace");
+				const btn = root.querySelector(".och-workspace-fold");
+				if (ws) {
+					ws.classList.toggle(
+						"och-workspace-collapsed",
+						workspaceCollapsed,
+					);
+				}
+				if (btn) {
+					btn.classList.toggle("is-folded", workspaceCollapsed);
+					btn.setAttribute("aria-expanded", String(!workspaceCollapsed));
+					const label = workspaceCollapsed ? "展开标签栏" : "收起标签栏";
+					btn.title = label;
+					btn.setAttribute("aria-label", label);
+				}
+			});
+			global.appendChild(fold);
+
+			/* Band 2 */
+			const workspace = el("div", "och-workspace");
+			workspace.id = "och-workspace";
+			if (workspaceCollapsed) {
+				workspace.classList.add("och-workspace-collapsed");
 			}
-			const ws = root.querySelector(".och-workspace");
-			const btn = root.querySelector(".och-workspace-fold");
-			if (ws) {
-				ws.classList.toggle(
-					"och-workspace-collapsed",
-					workspaceCollapsed,
+			inner.appendChild(workspace);
+			const tabs = el("nav", "och-tabs");
+			tabs.setAttribute("aria-label", model.tabsAriaLabel);
+			for (const tab of model.tabs) {
+				const a = el(
+					"a",
+					`och-tab${tab.active ? " och-tab-active" : ""}`,
+					tab.label,
 				);
+				a.href = tab.href;
+				if (tab.active) a.setAttribute("aria-current", "page");
+				tabs.appendChild(a);
 			}
-			if (btn) {
-				btn.classList.toggle("is-folded", workspaceCollapsed);
-				btn.setAttribute("aria-expanded", String(!workspaceCollapsed));
-				const label = workspaceCollapsed ? "展开标签栏" : "收起标签栏";
-				btn.title = label;
-				btn.setAttribute("aria-label", label);
-			}
-		});
-		global.appendChild(fold);
-
-		/* Band 2 */
-		const workspace = el("div", "och-workspace");
-		workspace.id = "och-workspace";
-		if (workspaceCollapsed) workspace.classList.add("och-workspace-collapsed");
-		inner.appendChild(workspace);
-		const tabs = el("nav", "och-tabs");
-		tabs.setAttribute("aria-label", model.tabsAriaLabel);
-		for (const tab of model.tabs) {
-			const a = el(
-				"a",
-				`och-tab${tab.active ? " och-tab-active" : ""}`,
-				tab.label,
-			);
-			a.href = tab.href;
-			if (tab.active) a.setAttribute("aria-current", "page");
-			tabs.appendChild(a);
+			workspace.appendChild(tabs);
 		}
-		workspace.appendChild(tabs);
 
-		root.appendChild(chrome);
 	}
 
 	function render() {
@@ -581,6 +792,25 @@ export function mountOperatorChrome(root, config = {}) {
 	}
 
 	function onDocumentClick(event) {
+		if (event.target instanceof Element) {
+			const link = event.target.closest("a");
+			if (
+				link &&
+				root.contains(link) &&
+				typeof currentConfig.onNavigate === "function" &&
+				event.button === 0 &&
+				!event.metaKey &&
+				!event.ctrlKey &&
+				!event.shiftKey &&
+				!event.altKey
+			) {
+				const href = link.getAttribute("href") || "";
+				if (href.startsWith("#") || href.startsWith("/#") || href.startsWith("/inspect")) {
+					event.preventDefault();
+					currentConfig.onNavigate(href);
+				}
+			}
+		}
 		if (!popoverOpen || !(event.target instanceof Node)) return;
 		const repoBtn = root.querySelector(".och-repo");
 		const pop = root.querySelector(".och-pop");

package/dist/worker/observe/static/router.d.ts

@@ -0,0 +1,46 @@
+/** 与 router.js 对应的类型声明（供 vitest/TS 侧导入契约测试）。 */
+
+export type InspectHashRoute = {
+	view: string;
+	batchRunId?: string;
+	workerRunId?: string;
+	dagRunId?: string;
+	featureId?: string;
+	taskId?: string;
+	scheduleId?: string;
+	page?: number;
+	pageSize?: number;
+	filters?: { status?: string; q?: string };
+};
+
+export function parseHashRoute(hashValue: string): InspectHashRoute;
+export function parseRoute(): InspectHashRoute;
+export function setNavigateHandler(
+	handler: ((href: string) => void) | null,
+): void;
+export function inspectPathToCanonicalHref(path: string): string;
+export function navigate(path: string): void;
+
+export const DAG_HISTORY_DEFAULT_PAGE: number;
+export const DAG_HISTORY_DEFAULT_PAGE_SIZE: number;
+export const DAG_HISTORY_ALLOWED_PAGE_SIZES: readonly number[];
+
+export function clampDagHistoryPageSize(value: unknown): number;
+export function clampDagHistoryPage(
+	value: unknown,
+	totalPages?: number,
+): number;
+export function parseDagHistoryQuery(hashValue: string): {
+	page: number;
+	pageSize: number;
+};
+export function buildDagHistoryHash(page: unknown, pageSize: unknown): string;
+export function parseHashFilters(hashValue: string): {
+	status?: string;
+	q?: string;
+};
+export function parseHashRouteWithFilters(hashValue: string): InspectHashRoute;
+export function buildHashPath(
+	path: string,
+	filters?: Record<string, unknown>,
+): string;

package/dist/worker/observe/static/router.js

@@ -1,7 +1,10 @@
 /** Hash routing for Observe UI (R5). */
 
 export function parseHashRoute(hashValue) {
-	const hash = (hashValue.replace(/^#/, "") || "/").split("?")[0] || "/";
+	let hash = (hashValue.replace(/^#/, "") || "/").split("?")[0] || "/";
+	if (!hash.startsWith("/")) hash = `/${hash}`;
+	if (hash === "/inspect") hash = "/";
+	else if (hash.startsWith("/inspect/")) hash = hash.slice("/inspect".length) || "/";
 	const batchMatch = /^\/batch\/([^/]+)$/.exec(hash);
 	if (batchMatch) {
 		return { view: "batch", batchRunId: decodeURIComponent(batchMatch[1]) };
@@ -61,7 +64,28 @@ export function parseRoute() {
 	return parseHashRouteWithFilters(location.hash);
 }
 
+let navigateHandler = null;
+
+export function setNavigateHandler(handler) {
+	navigateHandler = typeof handler === "function" ? handler : null;
+}
+
+export function inspectPathToCanonicalHref(path) {
+	const raw = String(path ?? "");
+	if (raw.startsWith("/#/inspect")) return raw;
+	if (raw.startsWith("#/inspect")) return `/${raw}`;
+	const stripped = raw.replace(/^#/, "");
+	const withSlash = stripped.startsWith("/") ? stripped : `/${stripped}`;
+	if (withSlash === "/inspect" || withSlash === "/") return "/#/inspect";
+	if (withSlash.startsWith("/inspect/")) return `/#${withSlash}`;
+	return `/#/inspect${withSlash}`;
+}
+
 export function navigate(path) {
+	if (navigateHandler) {
+		navigateHandler(inspectPathToCanonicalHref(path));
+		return;
+	}
 	location.hash = path.startsWith("#") ? path.slice(1) : path;
 }