@free-lzj/dsh-browser-use 0.1.1 → 0.1.2

package/README.md

@@ -41,6 +41,8 @@ bsk status      # 要能看到 browsers connected 1
 
 插件不装扩展、不配浏览器；`bsk` 是它的运行时（见文末声明）。缺了 `bsk` 时插件照常加载，只是没有浏览器工具——`@` 提及和技能仍在。
 
+**没装或连不上时，`@` 菜单不会空着**：它会显示一行「浏览器不可用」，后面跟 `bsk` 的原因和一句该做什么（`bsk --version` 确认装没装、`bsk status` 看 daemon 和浏览器连接）。插件不做任何下载或安装——`bsk` 不是独立分发的可执行文件，它是 BrowserSkill 那套东西的一部分，装法跟着它走。
+
 ## 安装
 
 ```sh

package/lib/client.js

@@ -21,7 +21,8 @@ window.__ModuleLoader__.load({
 		/**
 		* The `@` menu's copy for this plugin.
 		*
-		* Only the section heading needs translating: every row's text is the user's own
+		* Only two things need translating: the section heading, and the row that
+		* explains why the section is missing. Every other row's text is the user's own
 		* page title, which no dictionary can hold.
 		*
 		* @module @free-lzj/dsh-browser-use/client/locales
@@ -29,9 +30,15 @@ window.__ModuleLoader__.load({
 		/** Dictionary namespace owned by this plugin. */
 		const NS = "browserUse";
 		/** Simplified Chinese dictionary (the key-set source of truth). */
-		const zh = { sectionBrowser: "浏览器" };
+		const zh = {
+			sectionBrowser: "浏览器",
+			unavailable: "浏览器不可用"
+		};
 		/** English dictionary, key-identical to the Chinese source of truth. */
-		const en = { sectionBrowser: "Browser" };
+		const en = {
+			sectionBrowser: "Browser",
+			unavailable: "Browser unavailable"
+		};
 		//#endregion
 		//#region lib/types/client/index.js
 		/**
@@ -82,7 +89,7 @@ window.__ModuleLoader__.load({
 		* Ask the Host what can be mentioned.
 		* @param query - text after `@`.
 		* @param signal - the menu's cancellation.
-		* @returns every reachable group; an unreachable Host yields no rows rather than an error.
+		* @returns every reachable group, plus the providers that could not answer.
 		*/
 		async function fetchGroups(query, signal) {
 			try {
@@ -90,14 +97,39 @@ window.__ModuleLoader__.load({
 					signal,
 					headers: { accept: "application/json" }
 				});
-				if (!response.ok) return [];
+				if (!response.ok) return {
+					groups: [],
+					failures: []
+				};
 				const body = await response.json();
-				return Array.isArray(body.groups) ? body.groups : [];
+				return {
+					groups: Array.isArray(body.groups) ? body.groups : [],
+					failures: Array.isArray(body.failures) ? body.failures : []
+				};
 			} catch {
-				return [];
+				return {
+					groups: [],
+					failures: []
+				};
 			}
 		}
 		/**
+		* One non-selectable row explaining why the browser group is missing.
+		* @param failure - the Host's sentence, ready to read.
+		* @param t - the namespace's translator.
+		* @returns a single row for the menu.
+		*/
+		function noticeRow(failure, t) {
+			return [{
+				name: "browser-use:unavailable",
+				label: t("unavailable"),
+				description: failure,
+				icon: "file",
+				section: t("sectionBrowser"),
+				value: JSON.stringify({ notice: true })
+			}];
+		}
+		/**
 		* One candidate row per mentionable thing.
 		* @param group - the provider's answer.
 		* @param section - rendered heading.
@@ -141,13 +173,19 @@ window.__ModuleLoader__.load({
 				showGroupTitle: false,
 				async candidates(_session, req) {
 					if (req.quoted === true) return [];
-					const groups = await fetchGroups(req.query, req.signal);
+					const { groups, failures } = await fetchGroups(req.query, req.signal);
 					if (req.signal.aborted) return [];
+					if (groups.length === 0) {
+						const first = failures[0];
+						return first === void 0 ? [] : noticeRow(first, t);
+					}
 					return groups.flatMap((group) => rowsOf(group, sectionLabel(group, t)));
 				},
 				onPick({ candidate }) {
 					const value = parseValue(candidate.value);
 					if (value === void 0) return void 0;
+					if (value.notice === true) return void 0;
+					if (value.ref === void 0 || value.label === void 0) return void 0;
 					const mention = `@[${value.label}](${mentionAddress(value.ref)})`;
 					return { insert: {
 						source: SOURCE_NAME,
@@ -167,12 +205,13 @@ window.__ModuleLoader__.load({
 		/**
 		* Read a row's pick payload.
 		* @param value - the row's opaque `value`.
-		* @returns the ref and label, or undefined when the row was not ours.
+		* @returns the payload, or undefined when the row was not ours.
 		*/
 		function parseValue(value) {
 			if (value === void 0) return void 0;
 			try {
 				const parsed = JSON.parse(value);
+				if (parsed.notice === true) return { notice: true };
 				if (typeof parsed.ref !== "string" || typeof parsed.label !== "string") return void 0;
 				return {
 					ref: parsed.ref,

package/lib/index.js

@@ -292,6 +292,45 @@ var BskMcpChannel = class {
 	}
 };
 //#endregion
+//#region lib/types/diagnose.js
+/**
+* Turning `bsk`'s own failure text into something a person can act on.
+*
+* The menu is the only place this appears, and it appears exactly when the
+* browser group is missing — so the sentence has to answer "why is this empty"
+* rather than describe an internal transport. `bsk` already writes a precise
+* diagnosis; what it does not do is say what to do about it in this context.
+*
+* @module @free-lzj/dsh-browser-use/diagnose
+*/
+/** Probes worth trying for any of these failures, cheapest first. */
+const CHECK_COMMAND = "bsk --version";
+const STATUS_COMMAND = "bsk status";
+/**
+* Explain one provider failure.
+* @param message - the failure text, already prefixed with the provider id.
+* @returns the cause and one next step.
+*/
+function explainBsk(message) {
+	const text = message.toLowerCase();
+	if (text.includes("enoent") || text.includes("could not start") || text.includes("not found")) return {
+		reason: "找不到 BrowserSkill 的 bsk 命令（没装，或不在这个进程的 PATH 里）",
+		action: `在终端跑 ${CHECK_COMMAND} 确认；有多个 bsk 时用 DSH_BSK_PATH 指到对的那个`
+	};
+	if (text.includes("daemon") || text.includes("job object") || text.includes("breakaway")) return {
+		reason: "bsk 装好了，但它起不来或连不上后台 daemon",
+		action: `在终端跑 ${STATUS_COMMAND}：能连上说明是本进程受限，重启 dsh 桌面端；连不上就按 bsk 的提示处理`
+	};
+	if (text.includes("browser") && (text.includes("connect") || text.includes("session"))) return {
+		reason: "bsk 在跑，但没有浏览器连上来",
+		action: `打开浏览器并确认 BrowserSkill 扩展已启用，再用 ${STATUS_COMMAND} 看 browsers connected`
+	};
+	return {
+		reason: "BrowserSkill 没能列出标签页",
+		action: `在终端跑 ${STATUS_COMMAND} 看它的原话`
+	};
+}
+//#endregion
 //#region lib/types/browser-mention.js
 /**
 * The browser tab provider: the first, and for now the only, mentionable thing.
@@ -350,7 +389,13 @@ function browserMentionProvider(cli) {
 		label: PROVIDER_LABEL,
 		async candidates(query, signal) {
 			const needle = query.trim().toLowerCase();
-			const tabs = await cli.listUserTabs(signal);
+			let tabs;
+			try {
+				tabs = await cli.listUserTabs(signal);
+			} catch (error) {
+				const diagnosis = explainBsk(error instanceof Error ? error.message : String(error));
+				throw new Error(`${diagnosis.reason}。${diagnosis.action}`);
+			}
 			if (signal.aborted) return [];
 			return tabs.filter((tab) => matches(tab, needle)).map((tab) => ({
 				ref: `${PROVIDER_ID}:${tab.tabId}`,

package/lib/types/client/locales.d.ts

@@ -1,7 +1,8 @@
 /**
  * The `@` menu's copy for this plugin.
  *
- * Only the section heading needs translating: every row's text is the user's own
+ * Only two things need translating: the section heading, and the row that
+ * explains why the section is missing. Every other row's text is the user's own
  * page title, which no dictionary can hold.
  *
  * @module @free-lzj/dsh-browser-use/client/locales
@@ -11,6 +12,7 @@ export declare const NS = "browserUse";
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export declare const zh: {
     readonly sectionBrowser: "浏览器";
+    readonly unavailable: "浏览器不可用";
 };
 /** English dictionary, key-identical to the Chinese source of truth. */
 export declare const en: Record<BrowserUseKey, string>;

package/lib/types/diagnose.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Turning `bsk`'s own failure text into something a person can act on.
+ *
+ * The menu is the only place this appears, and it appears exactly when the
+ * browser group is missing — so the sentence has to answer "why is this empty"
+ * rather than describe an internal transport. `bsk` already writes a precise
+ * diagnosis; what it does not do is say what to do about it in this context.
+ *
+ * @module @free-lzj/dsh-browser-use/diagnose
+ */
+/** One explanation: what went wrong, and the shortest thing that would fix it. */
+export interface Diagnosis {
+    /** The cause, in the user's terms. */
+    readonly reason: string;
+    /** One concrete check or repair step. */
+    readonly action: string;
+}
+/**
+ * Explain one provider failure.
+ * @param message - the failure text, already prefixed with the provider id.
+ * @returns the cause and one next step.
+ */
+export declare function explainBsk(message: string): Diagnosis;
+//# sourceMappingURL=diagnose.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@free-lzj/dsh-browser-use",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drive the browser you are already signed into: mention an open tab with @, then read and operate it through BrowserSkill's own tools",
   "repository": {
     "type": "git",