dsh-mcp-connector 0.2.55 → 0.2.57

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.2.57] - 2026-09-22
+
+### Fixed
+
+- 打开插件及手动检查更新时刷新版本检测，新增常驻检查入口、检查时间和 npm 检测失败提示；更新服务已发现新版时不再被旧版本缓存隐藏按钮。
+
+## [0.2.56] - 2026-09-22
+
+### Documentation
+
+- 补充 macOS/Linux 与 Windows PowerShell 的 stdio 启动排查示例，说明 PATH、command/args、cwd、退出码及无 shell 启动的安全边界（#29）。
+
 ## [0.2.55] - 2026-09-22
 
 ### Fixed

package/README.en.md

@@ -190,7 +190,7 @@ npm run dev:ui
 
 Every Registry merge regenerates `catalog-stats.json`; an hourly workflow in this repository synchronizes the Chinese and English product copy plus a local stats snapshot. The static npm README updates with package releases, while the live badges above read the Registry directly and therefore stay current without another npm release.
 
-The current public version is [`dsh-mcp-connector@0.2.55`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.55](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.55).
+The current public version is [`dsh-mcp-connector@0.2.57`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.57](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.57).
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md) for the Desktop release checklist.
 

package/README.md

@@ -185,7 +185,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.55`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.55](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.55)。
+当前公开版本为 [`dsh-mcp-connector@0.2.57`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.57](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.57)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/USER-GUIDE.md

@@ -297,6 +297,71 @@ OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端
 
 页面会在有限时间内结束等待，并区分命令不存在、进程退出、初始化失败或启动超时。先在终端确认命令本身可执行、软件包可信、Node/运行时版本满足要求，并检查 `cwd`、参数和环境变量；随后查看 Host 日志并点击“重新检查”。不要把本机凭据写入公开 Registry descriptor。
 
+#### 1. 确认命令与运行环境
+
+stdio 会以当前用户权限在 DSH 所在机器上启动进程，只运行你信任的软件包和命令。先从连接配置记录 `command`、每个 `args` 元素、`cwd` 和所需环境变量名称；不要复制或公开凭据值。以下使用 Node 演示，其他运行时请替换为实际命令。
+
+macOS / Linux（终端）：
+
+```sh
+command -v node
+node --version
+pwd
+```
+
+Windows（PowerShell）：
+
+```powershell
+Get-Command node -All | Select-Object CommandType, Source
+node --version
+Get-Location
+```
+
+若找不到命令，先按可信软件的官方安装说明配置运行时，再重新打开终端和 DSH。核对服务要求的运行时版本。终端能找到命令，不代表桌面启动的 DSH 具有相同的 `PATH`；版本管理器、别名或 shell 函数也不一定对 DSH 可见。此时可将 `command` 改为本机实际可执行文件的绝对路径，不要填终端别名。
+
+#### 2. 在相同目录复现同一 command + args
+
+以下路径是占位符，必须替换为本机已安装、可信服务的实际路径；示例不下载软件、不需要账号或凭据。假设配置的 `command` 是 Node 的绝对路径，`args` 仅包含服务入口文件的绝对路径：
+
+macOS / Linux：
+
+```sh
+(
+  cd '/absolute/path/to/trusted-server' || exit 1
+  '/absolute/path/to/node' '/absolute/path/to/trusted-server/server.js'
+  result=$?
+  printf 'exit code: %s\n' "$result"
+)
+```
+
+Windows PowerShell：
+
+```powershell
+Push-Location -LiteralPath 'C:\path\to\trusted-server' -ErrorAction Stop
+try {
+    & 'C:\path\to\node.exe' 'C:\path\to\trusted-server\server.js'
+    Write-Output "exit code: $LASTEXITCODE"
+} finally {
+    Pop-Location
+}
+```
+
+按自己的配置逐项替换参数，不要把整条终端命令塞进 `command`，也不要把所有参数合并成一个字符串。带空格的路径在终端中需要引用；在配置的 `command` 或 `args` 字符串值中保留路径本身，不额外添加 shell 引号。只有服务依赖相对路径时，才需特别核对配置中的 `cwd` 是否存在、可访问且符合服务要求。所需环境变量应在本机安全配置，不要在反馈中粘贴完整 `env` 或包含密钥的命令行。
+
+Windows 下 `.cmd` / `.bat` 是脚本包装器，不等同于可直接启动的 `.exe`；PowerShell 中能运行包装器，不代表无 shell 的进程启动也能运行它。若诊断指向包装器，按该服务文档选择原生可执行文件，或用 Node 运行其可信 JavaScript 入口。不要通过设置 `shell: true`、关闭安全检查或执行策略绕过来解决。
+
+#### 3. 根据结果定位，再回到页面复查
+
+| 观察结果 | 排查方法 |
+|---|---|
+| 命令不存在 / 路径不存在 | 核对运行时安装、绝对路径及 DSH 进程的 `PATH`；同时确认 `cwd` 存在 |
+| 进程立即非零退出 | 查看本地标准错误输出和退出码，核对参数、依赖、运行时版本、文件权限及所需环境变量 |
+| 进程退出码为 0，但没有工具 | 确认启动的是 MCP stdio 服务，不是版本查询、安装器或一次性命令；退出成功不代表 MCP 初始化成功 |
+| 进程一直等待、没有输出 | stdio 服务可能正在等待客户端输入，这是正常可能性；终端启动只能验证进程，不证明 MCP 握手成功。可按 Ctrl+C 结束，再由 DSH 发起检查 |
+| 终端能启动，页面初始化失败 / 超时 | 对比 DSH 的 command/args/env/cwd，查看 Host 日志；确认服务支持 MCP stdio，且普通日志未污染用于协议通信的 stdout（日志应写 stderr） |
+
+修正后重新启动 DSH（如变更了进程环境），在连接详情点击“重新检查”，确认工具发现结果。反馈时只提交版本、脱敏后的诊断代码、退出码和必要日志；不要上传 Token、API Key、完整环境变量或个人路径。
+
 ### 为什么显示“状态未知”
 
 这表示插件没有足够证据确认健康或失败，常见于 DSH 刚重启、尚未执行健康检查，或当前 Host 无法读取 stdio 工具注册状态。点击“刷新连接器目录”或进入详情重新检查；若仍为未知，根据诊断的 `code` 和建议查看 Host 日志或升级 Host。不要把“状态未知”理解为“已连接”。

package/lib/client.js

@@ -448,11 +448,11 @@ window.__ModuleLoader__.load({
 			return mount;
 		}
 
-		async function fetchVersionStatus() {
+		async function fetchVersionStatus(force = false) {
 			const response = await window.fetch("/mcp-connector/api", {
 				method: "POST",
 				headers: { "content-type": "application/json" },
-				body: JSON.stringify({ method: "versionStatus", params: {} })
+				body: JSON.stringify({ method: "versionStatus", params: { force } })
 			});
 			const result = await response.json();
 			if (!response.ok || result.ok !== true || result.detail === void 0) {
@@ -1069,6 +1069,9 @@ window.__ModuleLoader__.load({
 			const [rollbackRunning, setRollbackRunning] = (0, react.useState)(false);
 			const [restarting, setRestarting] = (0, react.useState)(false);
 			const [manualCommandCopied, setManualCommandCopied] = (0, react.useState)(false);
+			const [versionCheckRequest, setVersionCheckRequest] = (0, react.useState)(0);
+			const [versionCheckBusy, setVersionCheckBusy] = (0, react.useState)(false);
+			const [versionCheckFailed, setVersionCheckFailed] = (0, react.useState)(false);
 			const frameRef = (0, react.useRef)(null);
 			const closeRef = (0, react.useRef)(null);
 			(0, react.useEffect)(() => {
@@ -1125,10 +1128,13 @@ window.__ModuleLoader__.load({
 					window.clearTimeout(pollTimer);
 					pollTimer = window.setTimeout(check, Math.max(1e3, delayMs));
 				};
-				const check = () => {
-					fetchVersionStatus().then((status) => {
+				const check = (force = false) => {
+					setVersionCheckBusy(true);
+					fetchVersionStatus(force).then((status) => {
 						if (disposed) return;
 						setVersionStatus(status);
+						setVersionCheckBusy(status.checking === true);
+						setVersionCheckFailed(!status.checking && status.sources?.npm?.ok !== true);
 						if (status.checking) {
 							schedule(1e3);
 							return;
@@ -1140,15 +1146,19 @@ window.__ModuleLoader__.load({
 						schedule(delay);
 					}, (error) => {
 						console.warn("[mcp-connector] plugin update check failed:", error);
-						if (!disposed) schedule(VERSION_CHECK_RETRY_MS);
+						if (!disposed) {
+							setVersionCheckBusy(false);
+							setVersionCheckFailed(true);
+							schedule(VERSION_CHECK_RETRY_MS);
+						}
 					});
 				};
-				check();
+				check(true);
 				return () => {
 					disposed = true;
 					window.clearTimeout(pollTimer);
 				};
-			}, [open]);
+			}, [open, versionCheckRequest]);
 			(0, react.useEffect)(() => {
 				if (open) setManualCommandCopied(false);
 			}, [open, versionStatus?.latestVersion]);
@@ -1175,7 +1185,7 @@ window.__ModuleLoader__.load({
 					setUpdateProviderState("unavailable");
 				});
 				return () => { disposed = true; };
-			}, [open]);
+			}, [open, versionCheckRequest]);
 			(0, react.useEffect)(() => {
 				const operationId = updateOperation?.operationId;
 				const provider = updateProviderSelection?.provider;
@@ -1319,7 +1329,9 @@ window.__ModuleLoader__.load({
 				const activationPendingVersion = updateProviderState === "ready"
 					? pendingActivationVersion(versionStatus, providerUpdateCheck)
 					: null;
-				if (!versionStatus?.updateAvailable && activationPendingVersion === null
+				if (!versionStatus?.updateAvailable
+					&& !(updateProviderState === "ready" && providerUpdateCheck?.updateAvailable === true)
+					&& activationPendingVersion === null
 					&& updateOperation === null && updateError === null) return null;
 				if (updateRunning) {
 					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
@@ -1573,6 +1585,19 @@ window.__ModuleLoader__.load({
 												children: versionStatus === null ? "v…" : `v${versionStatus.installedVersion}`
 											}),
 											renderUpdateControls(),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+												type: "button",
+												className: "mcpConnectorUpdateButton",
+												disabled: versionCheckBusy || updateRunning,
+												title: versionStatus?.checkedAt ? `上次检查：${new Date(versionStatus.checkedAt).toLocaleString()}` : "尚未完成版本检查",
+												onClick: () => setVersionCheckRequest((value) => value + 1),
+												children: versionCheckBusy ? "正在检查更新…" : "检查更新"
+											}),
+											versionCheckFailed && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "mcpConnectorUpdateStatus",
+												"data-tone": "error",
+												children: "暂时无法确认 npm 最新版本，请重试"
+											}),
 											versionStatus?.releasePending && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 												className: "mcpConnectorVersion",
 												title: "GitHub Release 已发布，等待 npm 同步后即可更新",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.55",
+  "version": "0.2.57",
   "description": "DeepSeek Harness MCP Connector: connect servers, search tools across active connections, and troubleshoot discovery. Includes a continuously updated catalog; supports OAuth 2.0 PKCE, API keys, Streamable HTTP/stdio, and mcpServers JSON import.",
   "type": "module",
   "main": "lib/index.js",