dsh-browser-view 0.8.2 → 0.8.3

package/README.md

@@ -291,23 +291,30 @@ browser_confirm({
 v0.8.0 起本包附带独立 MCP 入口 `dsh-browser-mcp`(stdio),DSH 之外的 MCP 客户端(Claude Desktop / ZCode / Cursor 等)可直接调用全部 39 个工具——走与 DSH 宿主**同一条** registerTools 装配链,审批闸/录制打点/时光机行为一致:
 
 ```jsonc
-// 客户端 mcpServers 配置示例
+// 客户端 mcpServers 配置(推荐:先全局安装一次,再用绝对路径启动)
+// 第一步:npm i -g dsh-browser-view
+// 第二步:command 填 bin 绝对路径(`which dsh-browser-mcp` 查,如 /usr/local/bin/dsh-browser-mcp)
 {
   "mcpServers": {
     "dsh-browser": {
-      "command": "npx",
-      "args": ["-y", "dsh-browser-view"],
+      "command": "/usr/local/bin/dsh-browser-mcp",
       "env": {
         "DSH_BROWSER_HEADLESS": "true",
-        "DSH_BROWSER_USER_DATA_DIR": "~/.dsh-browser/mcp-profile",
+        "DSH_BROWSER_USER_DATA_DIR": "/home/you/.dsh-browser/mcp-profile",
         "DSH_BROWSER_TOOLSET": "core"
-      }
+      },
+      "timeoutMs": 60000
     }
   }
 }
 ```
 
-- 已安装本包时可直接用 `"command": "dsh-browser-mcp"` 或 `"dsh-browser-view"`(双 bin 别名);
+快速体验也可用 `"command": "npx", "args": ["-y", "dsh-browser-view"]`,但注意:
+
+- **npx 冷安装可能超过客户端的 MCP 默认超时**(常见 30s):本包依赖 `playwright-core`,慢网络下首次下载数分钟,期间无响应会被判启动失败——务必加 `"timeoutMs": 120000`,或改用上面的全局安装方案(一次性下载不受超时约束,日常启动 1~2s);
+- **env 里的路径必须写绝对路径**:`~` 不会被展开(环境变量注入不经过 shell),写 `~/.dsh-browser/...` 会在进程工作目录下建名为 `~` 的目录。
+
+- 全局安装后两个 bin 别名等价(`dsh-browser-mcp` / `dsh-browser-view`);GUI 客户端(Claude Desktop 等)建议写绝对路径,避免 PATH 差异;
 - 配置走环境变量 `DSH_BROWSER_<大写蛇形>` → 同名配置键(`TIMEOUT_MS`→`timeoutMs`),`true/false` 转 boolean、纯数字转 number、列表键逗号分隔;校验与默认值复用同一套(见上方配置表,不新增配置键);
 - 工具使用指引由 server `instructions` 下发(与 DSH systemPrompt 同源),`what:"登录"` 语义定位等用法完全一致;
 - 工具元数据支持 MCP 2025 标准 `annotations`(`readOnlyHint` / `destructiveHint` 等属性);

package/lib/mcp.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -10469,6 +10469,12 @@ async function main() {
 	await server.connect(transport);
 	console.error(`dsh-browser-mcp: stdio server ready (toolset=${config.toolset}, headless=${config.headless}, profile=${config.userDataDir || "ephemeral"})`);
 }
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
+if (process.argv[1] && import.meta.url === (() => {
+	try {
+		return pathToFileURL(realpathSync(process.argv[1])).href;
+	} catch {
+		return "";
+	}
+})()) main();
 //#endregion
 export { collectToolDefinitions, configFromEnv, createBrowserMcpServer, main, resolveToolAnnotations };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-browser-view",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "DSH 插件:共享 Playwright 浏览器自动化(38 个 browser_* 工具,含 what 意图语义定位(一次调用替代快照→查找→点击)、SoM 标徽看图点击与零命中截图兜底、SPA ref 软失效重锚定、open Shadow DOM 组合树穿透、跨 Frame/IFrame 定位、视口感知动态快照、批量表单智能填充、点击效果验证与定位失败遥测、Playwright 规范代码导出、批处理、视觉回归、选择器自愈、增量快照)+ 人机协作(面板点选教学 browser_pick_element、人工接管等待、敏感操作审批硬拦截、人机混合录制、面板一键重跑)+ CDP 流式推流、拟人化轨迹与高斯击键、全景时光机、企业富控件矩阵。另附独立 MCP server 入口(bin dsh-browser-mcp,stdio),任意 MCP 客户端可直接调用全部工具。运行时依赖 playwright-core 与 @modelcontextprotocol/sdk(仅 MCP 入口,不进 DSH 插件加载链)。",
   "type": "module",
   "main": "./lib/index.js",