dsh-mcp-connector 0.2.54 → 0.2.56

package/CHANGELOG.md

@@ -4,6 +4,19 @@
 
 ## [Unreleased]
 
+## [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
+
+- Windows 钉钉 CLI 桥接解析官方 npm 包内原生 `dws.exe`，覆盖全局与 npx 布局，不执行 cmd shim，保持 shell:false；允许带空格的显式绝对路径并提供安装/原生文件缺失诊断（#91）。
+- 精确迁移标准受管钉钉 0.2.48/0.2.49 桥接到 0.2.55，保留自定义命令、参数、环境和授权配置。
+
 ## [0.2.54] - 2026-09-21
 
 ### 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.54`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.54](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.54).
+The current public version is [`dsh-mcp-connector@0.2.56`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.56](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.56).
 
 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.54`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.54](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.54)。
+当前公开版本为 [`dsh-mcp-connector@0.2.56`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.56](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.56)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/CLI-PROVIDERS.md

@@ -34,7 +34,7 @@ MCP 连接器原生支持 Streamable HTTP 和 stdio MCP。对于钉钉 `dws` 这
         "-y",
         "--legacy-peer-deps",
         "--package",
-        "dsh-mcp-connector@0.2.48",
+        "dsh-mcp-connector@0.2.55",
         "--package",
         "dingtalk-workspace-cli@1.0.61",
         "dsh-mcp-cli-bridge",
@@ -48,6 +48,10 @@ MCP 连接器原生支持 Streamable HTTP 和 stdio MCP。对于钉钉 `dws` 这
 
 ## 首批只读能力
 
+Windows 从 DSH 进程 PATH 中的全局 npm 或 npx `.bin` 位置查找官方包，直接运行包内 `vendor/dws.exe`；不执行 `.cmd`/`.bat`/`.ps1`，不启用 shell。也可在启动 DSH 的环境中设置 `DSH_MCP_DINGTALK_DWS_BIN` 为原生 exe 的绝对路径（允许空格），随后重启 DSH。无需复制 exe 到 npm 前缀；复制品可能在 CLI 升级后过期。缺失程序不等于 OAuth 未登录。
+
+升级主插件并重启后，标准受管钉钉 0.2.48/0.2.49 桥接参数会在加载时迁移到 0.2.55；自定义命令和参数不自动修改，需自行更新固定桥接版本。授权信息和环境配置保持不变。
+
 - 当前用户、通讯录搜索与用户详情
 - 日程列表与日程详情
 - 待办列表与待办详情

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/cli-providers.js

@@ -1,4 +1,6 @@
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
 
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -198,8 +200,8 @@ export function listCliProviderTools(providerId) {
 
 function assertSafeExecutable(executable) {
   const value = String(executable ?? '').trim();
-  if (!value || /[\0\r\n]/.test(value) || /\s/.test(value)) {
-    throw new Error('CLI executable must be one command name or an absolute path without whitespace');
+  if (!value || /[\0\r\n]/.test(value) || (/\s/.test(value) && !path.isAbsolute(value) && !path.win32.isAbsolute(value))) {
+    throw new Error('CLI executable must be one command name or an absolute path');
   }
   return value;
 }
@@ -290,11 +292,48 @@ export function redactCliError(value) {
     .trim();
 }
 
+// Resolve only the known provider package; never interpret or execute a shell shim.
+export function resolveCliExecutable(command, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  if (platform !== 'win32') return command;
+  if (/\.(cmd|bat|ps1)$/i.test(command)) throw new Error('[CLI_SHIM_UNSUPPORTED] 请指定原生 exe，而非 shell 启动脚本');
+  if (command !== 'dws') return command; // Explicit override stays authoritative.
+  const pathValue = Object.entries(env).find(([key]) => key.toLowerCase() === 'path')?.[1] ?? '';
+  let sawShim = false;
+  for (const raw of pathValue.split(';')) {
+    const dir = raw.replace(/^"(.*)"$/, '$1');
+    if (!path.isAbsolute(dir)) continue; // Never search cwd or relative PATH entries.
+    const native = path.join(dir, 'dws.exe');
+    if (existsSync(native) && statSync(native).isFile()) return native;
+    if (existsSync(path.join(dir, 'dws.cmd'))) sawShim = true;
+    const roots = path.basename(dir).toLowerCase() === '.bin'
+      ? [path.join(dir, '..', 'dingtalk-workspace-cli')]
+      : [path.join(dir, 'node_modules', 'dingtalk-workspace-cli')];
+    for (const root of roots) {
+      if (!existsSync(path.join(root, 'package.json'))) continue;
+      try {
+        const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+        if (pkg.name !== 'dingtalk-workspace-cli' || pkg.bin?.dws !== 'bin/dws.js') continue;
+        const realRoot = realpathSync(root);
+        const binary = realpathSync(path.join(root, 'vendor', 'dws.exe'));
+        const relative = path.relative(realRoot, binary);
+        if (relative.startsWith('..') || path.isAbsolute(relative) || !statSync(binary).isFile()) continue;
+        return binary;
+      } catch { /* Missing/corrupt packages must fail closed, not launch a shim. */ }
+    }
+  }
+  throw new Error(sawShim
+    ? '[CLI_NATIVE_MISSING] 已发现 dws npm 启动脚本，但未找到有效的官方原生程序；请检查 CLI 安装，或通过 DSH_MCP_DINGTALK_DWS_BIN 指定 dws.exe'
+    : '[CLI_NOT_FOUND] DSH 进程 PATH 中未找到 dws 原生程序或官方 npm 包；请检查安装与 DSH 环境后重启，不代表 OAuth 未登录');
+}
+
 export function runCliProcess(command, args, options = {}) {
   const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
   const maxOutputBytes = Number.isInteger(options.maxOutputBytes) ? options.maxOutputBytes : MAX_OUTPUT_BYTES;
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    const executable = resolveCliExecutable(command, options);
+    const child = spawn(executable, args, {
       shell: false,
       windowsHide: true,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -399,12 +438,17 @@ export async function ensureCliProviderReady(providerId, options = {}) {
 // Upgrade only the exact managed legacy invocation; preserve custom commands,
 // environment, cwd and credentials. Applied on every provision, including restore.
 export function cliBridgeArgs(record) {
-  const legacy = ['--yes', '--legacy-peer-deps', '--package', 'dsh-mcp-connector@0.2.48',
+  const legacy = ['--yes', '--legacy-peer-deps', '--package', argsVersion(record),
     '--package', 'dingtalk-workspace-cli@1.0.61', 'dsh-mcp-cli-bridge', '--provider', 'dingtalk-dws'];
   const args = record.args ?? [];
-  if (record.connectorId !== 'dingtalk' || record.command !== 'npx'
+  if (!legacy[3] || record.connectorId !== 'dingtalk' || record.command !== 'npx'
     || JSON.stringify(args) !== JSON.stringify(legacy)) return args;
-  return args.map((arg) => arg === 'dsh-mcp-connector@0.2.48' ? 'dsh-mcp-connector@0.2.49' : arg);
+  return args.map((arg) => arg === legacy[3] ? 'dsh-mcp-connector@0.2.55' : arg);
+}
+
+function argsVersion(record) {
+  const value = record.args?.[3];
+  return ['dsh-mcp-connector@0.2.48', 'dsh-mcp-connector@0.2.49'].includes(value) ? value : null;
 }
 
 export async function handleCliBridgeRequest(message, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.54",
+  "version": "0.2.56",
   "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",