dsh-mcp-connector 0.2.58 → 0.2.60

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 ## [Unreleased]
 
+## [0.2.60] - 2026-09-29
+
+### Fixed
+
+- 放宽 `@deepseek-ai/dsh-mcp-client` peer 范围以支持 DSH `0.2.x`，避免插件在组合阶段被整体跳过、全部 MCP Server 消失（#101）。
+- 忽略工具 Schema 读取或 restriction 更新期间同步触发的嵌套 `tools/change`，阻断与工具重注册插件组合时的永久重扫和 100% CPU 死循环（#99）。
+- 连接范围选择器列出全部可用 Workspace；没有当前会话时仍可显式选择目标项目，不再只能保存为 profile 全局（#100）。
+
+### Verification
+
+- 新增治理与作用域控制器的同步重入回归、无当前会话的 Workspace 列表回归，以及 DSH `0.2.x` peer 范围门禁。
+
+## [0.2.59] - 2026-09-25
+
+### Fixed
+
+- 恢复市场中文描述中的连续“连接管理”短语，并增加核心检索文案门禁，修复真实 Market 查询无法命中该短语的回归。
+
+### Documentation
+
+- 新增统一首次成功路径，串联安装、连接、工具发现和 Host 审批下的首次只读调用。
+- 明确 DSH Desktop 与 `dsh web` 默认均使用本机 `web` profile；仅重启当前使用的 Host，避免安装位置与重启对象产生歧义。
+- 补充安全 Prompt 模板、权限/费用/副作用边界，以及 7/14 天无遥测复盘口径；没有证据时保持“无数据”，不从下载量推算转化率。
+
 ## [0.2.58] - 2026-09-22
 
 ### Documentation

package/README.en.md

@@ -40,7 +40,7 @@ Fully restart DeepSeek Harness Desktop or `dsh web` after installation or upgrad
 
 For a first successful use, confirm the connection and scope in Installed, find the expected tool and source in Tools, then complete one provider-permitted read-only call through the normal DSH Host approval flow. Cached visibility alone does not prove that a service is currently callable.
 
-Task guides (Chinese): [migrate `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [diagnose OAuth](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [find and recover tools](docs/tutorials/TOOL-SEARCH-RECOVERY.md).
+First-success guide (Chinese): [install → connect → find a tool → make the first read-only call](docs/tutorials/README.md). Task details: [migrate `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [diagnose OAuth](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [find and recover tools](docs/tutorials/TOOL-SEARCH-RECOVERY.md).
 
 ![43-second MCP Connector walkthrough](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/demo.gif)
 
@@ -131,6 +131,7 @@ The detailed [Chinese user guide](docs/USER-GUIDE.md) covers category browsing,
 ## Guides and ecosystem
 
 - [User guide: installation, authorization, diagnostics, compatibility, and troubleshooting](docs/USER-GUIDE.md)
+- [First-success guide: install, connect, find a tool, and make a read-only call (Chinese)](docs/tutorials/README.md)
 - [Task guides: JSON migration, OAuth diagnostics, and cross-connection tool recovery](docs/USER-GUIDE.md#按任务开始)
 - [Connection scopes: project/global inheritance, copy, move, and rollback](docs/CONNECTION-SCOPES.md)
 - [Connection, Server, and Tool governance](docs/TOOL-GOVERNANCE.md)
@@ -197,7 +198,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.58`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.58](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.58).
+The current public version is [`dsh-mcp-connector@0.2.60`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.60](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.60).
 
 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

@@ -40,7 +40,7 @@ dsh plugin --profile web add dsh-mcp-connector
 
 首次使用建议依次确认：连接已保存且范围正确 → “工具”页能找到预期工具与来源 → 在正常 DSH 会话中通过 Host 审批链完成一次服务商许可的只读调用。缓存可见不等于当前服务可调用。
 
-按任务阅读：[迁移现有 `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [OAuth 授权诊断](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [跨连接找工具与恢复](docs/tutorials/TOOL-SEARCH-RECOVERY.md)。
+[首次成功入口：安装 → 连接 → 找到工具 → 首次只读调用](docs/tutorials/README.md)。按任务深入：[迁移现有 `mcpServers` JSON](docs/tutorials/JSON-MIGRATION.md) · [OAuth 授权诊断](docs/tutorials/OAUTH-DIAGNOSTICS.md) · [跨连接找工具与恢复](docs/tutorials/TOOL-SEARCH-RECOVERY.md)。
 
 ![MCP 连接器 43 秒演示](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/demo.gif)
 
@@ -132,6 +132,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/m
 ## 中文教程与生态入口
 
 - [用户手册：安装、授权、诊断、兼容性与故障排查](docs/USER-GUIDE.md)
+- [首次成功入口：安装、连接、找工具和首次只读调用](docs/tutorials/README.md)
 - [任务教程：JSON 迁移、OAuth 诊断、跨连接找工具与恢复](docs/USER-GUIDE.md#按任务开始)
 - [配置备份：脱敏导出、快照与恢复边界](docs/CONFIG-BACKUP.md)
 - [连接作用域：project/global 继承、复制、移动与回滚](docs/CONNECTION-SCOPES.md)
@@ -192,7 +193,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.58`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.58](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.58)。
+当前公开版本为 [`dsh-mcp-connector@0.2.60`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.60](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.60)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。

package/docs/CONNECTION-SCOPES.md

@@ -13,9 +13,9 @@
 
 Desktop 和 Web 使用同一个 Host API：
 
-1. 市场从父级 DSH 客户端读取当前 Workspace；
+1. 市场从父级 DSH 客户端和 Host Workspace Registry 读取当前 Workspace 及可用 Workspace 列表；
 2. OAuth、免密、Bearer/API Key、JSON 导入和 URL 安装都会在提交前显示目标范围；
-3. 已选择 Workspace 时页面默认为“当前项目”，也可显式选择“所有项目（全局）”；
+3. 已选择 Workspace 时页面默认为“当前项目”；没有当前会话时仍可从列表显式选择任一 Workspace，或选择“所有项目（全局）”；
 4. 项目范围只在 Host 支持最终执行 Guard，且目标 Workspace 仍存在时才能保存。
 
 对话工具的 `scope` 可传 `project` 或 `global`；`project` 同时要求 `workspaceId`。旧版客户端未传作用域时，新连接按兼容规则归为当前 profile 全局。

package/docs/USER-GUIDE.md

@@ -4,6 +4,8 @@
 
 ## 按任务开始
 
+第一次使用请从[统一首次成功入口](tutorials/README.md)开始：安装并重启正确 profile，只选一种连接方式，确认工具来源，再回到正常 DSH 会话完成服务商许可的首次只读调用。
+
 - 已有其他客户端配置：从[迁移 `mcpServers` JSON](tutorials/JSON-MIGRATION.md)开始，逐项验证配置保存、工具发现/注册和只读调用。
 - OAuth 卡在注册、授权或刷新：看[OAuth 连接诊断](tutorials/OAUTH-DIAGNOSTICS.md)，先按阶段与稳定代码排查，不反复提交未获授权的账号。
 - 已连接多个服务却找不到工具：看[跨连接找工具与发现失败恢复](tutorials/TOOL-SEARCH-RECOVERY.md)。缓存可查不等于当前可调用。

package/docs/tutorials/JSON-MIGRATION.md

@@ -1,10 +1,12 @@
 # 把已有 `mcpServers` JSON 迁移到 MCP连接器
 
+返回[首次成功统一入口](README.md)。
+
 适用场景：你已经有其他客户端的 `mcpServers` 配置，希望在 DeepSeek Harness 中统一管理，而不是逐个重新录入。本文只演示受信任的 HTTP/stdio MCP Server；不会把普通 API 或 CLI 自动变成 MCP Server。
 
 ## 迁移前：先确认什么
 
-1. 安装 `dsh-mcp-connector`，完全退出并重启 DSH Desktop 或 `dsh web`；确认当前使用的 profile 与安装插件的 profile 一致（例如 Web 使用 `web`，Desktop 使用其对应 profile）。
+1. 按统一入口安装 `dsh-mcp-connector`：默认布局下 DSH Desktop 与 `dsh web` 都从本机 `web` profile 加载插件。安装后只需重启正在使用的宿主；自定义 profile 布局以宿主配置为准。
 2. 核对原配置的每个 Server：远端 URL 是否为 MCP Streamable HTTP 端点；本地 `command`、`args` 和运行时是否可信且可在 **DSH 所在机器** 启动。
 3. 对每个连接决定“当前项目”或“所有项目（全局）”。全局仅指当前 DSH profile，并非跨 profile 共享。
 4. 在本机保存原配置的安全备份。不要把含 Token、API Key、Cookie 或本机路径的原文发到 Issue、聊天或公开仓库。

package/docs/tutorials/OAUTH-DIAGNOSTICS.md

@@ -1,5 +1,7 @@
 # OAuth 连接没有成功时，先定位哪一层失败
 
+返回[首次成功统一入口](README.md)。
+
 适用场景：市场卡片要求 OAuth 2.0 PKCE，但按钮显示“自动重试中”“需重新授权”或连接异常。OAuth 接入能力依赖服务商公开元数据、客户端注册、账号权限与网络条件；插件支持 OAuth 流程，不等于每个市场连接器都已对任意账号开放。
 
 ## 先看状态，而不是反复点击授权

package/docs/tutorials/README.md

@@ -0,0 +1,51 @@
+# 从安装到首次成功调用
+
+这是一条统一的最短路径。它把已有教程串成“安装 → 连接 → 找到工具 → 首次只读调用”，不替代各服务商文档。首次调用只选你已获准使用、费用与权限边界明确的只读任务；截图、GIF、连接成功或工具缓存都不等于真实业务调用通过。
+
+## 1. 安装并重启正确的 profile
+
+当前默认安装布局中，DSH Desktop 和 `dsh web` 都从本机 `web` profile 加载插件，因此两种宿主都使用同一条安装命令；不要因为使用 Desktop 就把命令改成 `--profile desktop`。
+
+```bash
+dsh plugin --profile web add dsh-mcp-connector
+```
+
+安装或升级后，只重启你正在使用的宿主：DSH Desktop 需完全退出应用后重新打开；`dsh web` 需停止原进程后重新启动。打开左侧“🧩 MCP连接器”；若侧边栏入口已隐藏，从“设置 → 插件 → 插件配置 → MCP连接器”点击“打开 MCP连接器”。自定义过 profile 布局的部署应以其宿主配置为准。
+
+## 2. 只选一条连接路径
+
+- 已有其他客户端配置：按[迁移 `mcpServers` JSON](JSON-MIGRATION.md)导入，并在提交前确认当前项目或全局范围。
+- 使用市场中的 OAuth / API Key 连接器：按服务商要求授权或在本机录入凭据；卡住时转到[OAuth 连接诊断](OAUTH-DIAGNOSTICS.md)。OAuth 能否使用取决于服务商客户端注册政策、账号权限和授权范围。
+- 自建 HTTP / stdio Server：按[用户手册的自定义连接说明](../USER-GUIDE.md#6-添加自定义连接)填写可信端点或本机命令。普通 REST API 或 CLI 不能因此自动变成 MCP Server。
+
+连接后先在“已安装”确认名称、项目/全局范围和启停状态。这里只证明配置已保存，不证明工具已经注册或服务当前可调用。
+
+## 3. 找到要调用的工具
+
+在当前 Workspace 打开“工具”，搜索预期工具，核对连接、Server、工具来源和参数。若结果为空、陈旧或最近发现失败，按[跨连接找工具与恢复](TOOL-SEARCH-RECOVERY.md)处理。
+
+工具页只展示当前范围内已启用连接的安全缓存，不执行目标工具。继续之前，确认预期工具已被发现；必要时核对 DSH Host 中的 `mcp__<serverName>__*` 注册状态。
+
+## 4. 在正常 DSH 会话完成首次只读调用
+
+插件页面没有绕过审批的“试运行”按钮。回到正常 DSH 会话，替换尖括号后发送：
+
+```text
+请仅使用 MCP 工具 mcp__<serverName>__<toolName> 完成“<一个服务商允许的只读任务>”。
+调用前请列出工具来源、将发送的关键参数，以及是否可能产生费用或副作用。
+如果需要写入、付费、发布、删除，或超出当前账户权限，请停止并先请求我确认。
+```
+
+实际工具执行及权限/审批由 DSH Host 管理。服务商可能另有账号资格、配额和费用；不要为首次验收使用真实敏感数据，或选择写入、删除、发布等有副作用的操作。
+
+## 5. 记录三个独立结果
+
+| 层次 | 通过条件 |
+|---|---|
+| 配置 | “已安装”中存在目标连接，范围和启停状态正确 |
+| 发现/注册 | “工具”中出现预期工具和来源；必要时确认 Host 注册状态 |
+| 调用 | 正常会话经 Host 审批链完成服务商许可的只读调用，并得到可辨认结果 |
+
+只有第三项通过，才能把这个具体场景记为“首次成功调用”。若第三项没有条件验证，请明确写“无数据/待验收”，不要从下载量、页面浏览、连接成功或演示素材推算。
+
+如果这条路径确实帮你完成首次调用，欢迎克制地 [Star 项目](https://github.com/duhu2000/dsh-mcp-connector/stargazers)、[提交新连接器](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)或[参与贡献](../../CONTRIBUTING.md)。

package/docs/tutorials/TOOL-SEARCH-RECOVERY.md

@@ -1,5 +1,7 @@
 # 跨连接找工具，并在发现失败后恢复
 
+返回[首次成功统一入口](README.md)。
+
 适用场景：你已连接多个 MCP Server，想按任务找工具、看参数；或某条连接的最近发现失败，但仍需要判断工具曾经有哪些。本文不演示执行真实业务工具。
 
 ## 先定位正确的工具

package/lib/client.js

@@ -1013,6 +1013,20 @@ window.__ModuleLoader__.load({
 			};
 		}
 
+		function availableWorkspaceContexts(ctx) {
+			const items = ctx.workspaces.list.getSnapshot()?.items;
+			if (!Array.isArray(items)) return [];
+			const workspaces = new Map();
+			for (const item of items) {
+				if (typeof item?.workspaceId !== "string" || item.workspaceId === "") continue;
+				workspaces.set(item.workspaceId, {
+					workspaceId: item.workspaceId,
+					title: item.title ?? String(item.workspaceId)
+				});
+			}
+			return [...workspaces.values()];
+		}
+
 		async function startPromptSession(ctx, promptText) {
 			if (typeof promptText !== "string" || promptText.trim() === "") {
 				throw new Error("Prompt 不能为空");
@@ -1054,7 +1068,8 @@ window.__ModuleLoader__.load({
 				useStore,
 				actions,
 				startPromptSession: launchPromptSession,
-				workspaceContext = () => null
+				workspaceContext = () => null,
+				workspaceOptions = () => []
 			} = props;
 			const open = useStore((state) => state.open);
 			const detailOpen = useStore((state) => state.detailOpen);
@@ -1078,7 +1093,8 @@ window.__ModuleLoader__.load({
 				const sendWorkspaceContext = () => {
 					frameRef.current?.contentWindow?.postMessage({
 						type: WORKSPACE_CONTEXT_RESULT_TYPE,
-						workspace: workspaceContext()
+						workspace: workspaceContext(),
+						workspaces: workspaceOptions()
 					}, window.location.origin);
 				};
 				const onMessage = (event) => {
@@ -1726,7 +1742,8 @@ window.__ModuleLoader__.load({
 						store: marketView,
 						inject: () => ({
 							startPromptSession: (promptText) => startPromptSession(ctx, promptText),
-							workspaceContext: () => currentWorkspaceContext(ctx)
+							workspaceContext: () => currentWorkspaceContext(ctx),
+							workspaceOptions: () => availableWorkspaceContexts(ctx)
 						})
 					}, MarketOverlay);
 				});

package/lib/connection-scopes.js

@@ -313,13 +313,13 @@ export function createHostScopeController(ctx, {
   }
 
   let syncing = false;
-  let pending = false;
   function refresh() {
     if (disposed || !agentsMounted) return;
-    if (syncing) {
-      pending = true;
-      return;
-    }
+    // Reading lazy Host schemas or replacing a restriction may synchronously
+    // emit tools/change. Ignore that nested notification: replaying it scans
+    // the same single-threaded state and can otherwise keep the event loop in
+    // a permanent tools/change cycle with plugins that re-register tools.
+    if (syncing) return;
     syncing = true;
     try {
       const live = new Set(mountedAgentCtx?.agents?.list?.() ?? []);
@@ -327,10 +327,6 @@ export function createHostScopeController(ctx, {
       for (const agent of restrictions.keys()) if (!live.has(agent)) restrictions.delete(agent);
     } finally {
       syncing = false;
-      if (pending) {
-        pending = false;
-        refresh();
-      }
     }
   }
 

package/lib/governance.js

@@ -336,13 +336,14 @@ export function createHostGovernanceController(ctx, { getRules, getRecords, logg
   }
 
   let syncing = false;
-  let pendingSync = false;
   function syncRestrictions() {
     if (disposed || !agentsMounted) return;
-    if (syncing) {
-      pendingSync = true;
-      return;
-    }
+    // schemas()/restrict() may synchronously cause another tools/change while
+    // Host plugins materialize lazy schemas or re-register equivalent tools.
+    // JavaScript cannot interleave an unrelated external change in this stack,
+    // so replaying that nested event only scans the same state again and can
+    // form an endless tools/change -> schemas -> tools/change loop.
+    if (syncing) return;
     syncing = true;
     try {
       const denied = deniedObservedNames();
@@ -353,10 +354,6 @@ export function createHostGovernanceController(ctx, { getRules, getRecords, logg
       }
     } finally {
       syncing = false;
-      if (pendingSync) {
-        pendingSync = false;
-        syncRestrictions();
-      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.58",
+  "version": "0.2.60",
   "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",
@@ -45,7 +45,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check lib/discovery-policy.js && node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/settings.js && node --check lib/version-status.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/diagnostics.js && node --check lib/connection-backup.js && node --check lib/connection-editor.js && node --check lib/connection-scopes.js && node --check lib/governance.js && node --check lib/tool-catalog-cache.js && node --check lib/status-events.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/grant-journal.js && node --check lib/oauth.js && node --check lib/grant-lifecycle.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/cli-providers.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/cli-bridge.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs && node --check scripts/check-distribution-sync.mjs && node --check scripts/check-readme-version.mjs && node --check scripts/check-marketing-metadata.mjs && node --check scripts/check-storefront-screenshots.mjs && node --check scripts/sync-registry-stats.mjs && node --check scripts/verify-pack.mjs",
+    "lint": "node --check lib/discovery-policy.js && node --check lib/index.js && node --check lib/web.js && node --check lib/client.js && node --check lib/settings.js && node --check lib/version-status.js && node --check lib/schema.js && node --check lib/catalog.js && node --check lib/prompts.js && node --check lib/probe.js && node --check lib/diagnostics.js && node --check lib/connection-backup.js && node --check lib/connection-editor.js && node --check lib/connection-scopes.js && node --check lib/governance.js && node --check lib/tool-catalog-cache.js && node --check lib/status-events.js && node --check lib/mcp-validation.js && node --check lib/mcp-http.js && node --check lib/migration.js && node --check lib/stores.js && node --check lib/grant-journal.js && node --check lib/oauth.js && node --check lib/grant-lifecycle.js && node --check lib/callback-server.js && node --check lib/mcp-provision.js && node --check lib/cli-providers.js && node --check lib/util.js && node --check lib/constants.js && node --check lib/tools.js && node --check lib/connectors/oauth-connector.js && node --check lib/connectors/manual-connector.js && node --check lib/connectors/json-connector.js && node --check scripts/probe-connector.mjs && node --check scripts/cli-bridge.mjs && node --check scripts/build-registry.mjs && node --check scripts/ui-harness.mjs && node --check scripts/check-market-registration.mjs && node --check scripts/check-distribution-sync.mjs && node --check scripts/check-readme-version.mjs && node --check scripts/check-first-use-docs.mjs && node --check scripts/check-marketing-metadata.mjs && node --check scripts/check-storefront-screenshots.mjs && node --check scripts/sync-registry-stats.mjs && node --check scripts/verify-pack.mjs",
     "registry:build": "node scripts/build-registry.mjs",
     "registry:validate": "node scripts/probe-connector.mjs catalog/catalog.json --validate-only",
     "dev:ui": "node scripts/ui-harness.mjs",
@@ -53,13 +53,14 @@
     "distribution:check:live": "node scripts/check-distribution-sync.mjs --strict-sync",
     "registry:stats:sync": "node scripts/sync-registry-stats.mjs",
     "docs:check": "node scripts/check-readme-version.mjs",
+    "docs:first-use:check": "node scripts/check-first-use-docs.mjs",
     "marketing:check": "node scripts/check-marketing-metadata.mjs",
     "marketing:check:github": "node scripts/check-marketing-metadata.mjs --live-github",
     "marketing:check:npm": "node scripts/check-marketing-metadata.mjs --live-npm",
     "marketing:check:live": "node scripts/check-marketing-metadata.mjs --live",
     "storefront:check": "node scripts/check-storefront-screenshots.mjs",
     "verify-pack": "node scripts/verify-pack.mjs",
-    "check": "npm run lint && npm run docs:check && npm run marketing:check && npm run storefront:check && npm test && npm run verify-pack",
+    "check": "npm run lint && npm run docs:check && npm run docs:first-use:check && npm run marketing:check && npm run storefront:check && npm test && npm run verify-pack",
     "prepublishOnly": "npm run check"
   },
   "keywords": [
@@ -141,7 +142,7 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-client-ui-conversation": "*",
     "@deepseek-ai/dsh-client-ui-layout": "*",
-    "@deepseek-ai/dsh-mcp-client": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-mcp-client": "^0.1.1-rc.2 || >=0.2.0-rc.1 <0.3.0-0",
     "@deepseek-ai/dsh-storage-domain": "*",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@deepseek-ai/cordis": "^4.0.1",

package/ui/index.html

@@ -590,6 +590,7 @@
   let communityCtaEligible = false;
   let communityCtaDismissed = false;
   let currentWorkspace = null;
+  let availableWorkspaces = [];
   let scopeRevision = 0;
   let scopeRollbackRevision = null;
   let pendingScopeKey = null;
@@ -660,15 +661,34 @@
     showToast(message || (ok ? '已带入新会话' : '打开新会话失败，请重试'), ok);
   }
 
+  function normalizeWorkspaceOptions(input) {
+    const byId = new Map();
+    for (const item of Array.isArray(input) ? input : []) {
+      const workspaceId = typeof item?.workspaceId === 'string' ? item.workspaceId : typeof item?.id === 'string' ? item.id : '';
+      if (!workspaceId) continue;
+      byId.set(workspaceId, { workspaceId, title: String(item.title || workspaceId) });
+    }
+    if (currentWorkspace && !byId.has(currentWorkspace.workspaceId)) {
+      byId.set(currentWorkspace.workspaceId, currentWorkspace);
+    }
+    return [...byId.values()];
+  }
+
+  function updateAvailableWorkspaces(input) {
+    availableWorkspaces = normalizeWorkspaceOptions(input);
+  }
+
   window.addEventListener('message', (event) => {
     if (event.origin !== window.location.origin || event.source !== window.parent) return;
     if (event.data?.type === WORKSPACE_CONTEXT_RESULT_TYPE) {
       const workspace = event.data.workspace;
       const previousWorkspaceId = currentWorkspace?.workspaceId ?? null;
+      const previousWorkspaceOptions = JSON.stringify(availableWorkspaces);
       currentWorkspace = workspace && typeof workspace.workspaceId === 'string'
         ? { workspaceId: workspace.workspaceId, title: String(workspace.title || workspace.workspaceId) }
         : null;
-      if ((currentWorkspace?.workspaceId ?? null) !== previousWorkspaceId) {
+      updateAvailableWorkspaces(event.data.workspaces);
+      if ((currentWorkspace?.workspaceId ?? null) !== previousWorkspaceId || JSON.stringify(availableWorkspaces) !== previousWorkspaceOptions) {
         explorerSequence++; explorerDetailSequence++;
         explorerData = null; explorerOffset = 0;
         explorerFilter = { connectionKey: '', serverName: '', status: '' };
@@ -689,16 +709,25 @@
   }
 
   function scopeFieldHtml({ id = 'cfg-scope', selected } = {}) {
-    const projectAvailable = currentWorkspace !== null;
-    const value = selected || (projectAvailable ? 'project' : 'global');
-    return `<label for="${esc(id)}">连接范围</label><select id="${esc(id)}"><option value="project" ${value === 'project' ? 'selected' : ''} ${projectAvailable ? '' : 'disabled'}>${projectAvailable ? `当前项目：${esc(currentWorkspace.title)}` : '当前项目（请先选择 Workspace）'}</option><option value="global" ${value === 'global' ? 'selected' : ''}>所有项目（全局）</option></select><div class="field-help">项目范围只在当前 Workspace 的 Agent 中可见；全局范围由所有 Workspace 继承。范围绑定不保存或复制凭据。</div>`;
+    const defaultValue = currentWorkspace ? `project:${currentWorkspace.workspaceId}` : 'global';
+    const value = selected === 'project'
+      ? defaultValue
+      : selected || defaultValue;
+    const projectOptions = availableWorkspaces.map((workspace) => {
+      const optionValue = `project:${workspace.workspaceId}`;
+      const prefix = workspace.workspaceId === currentWorkspace?.workspaceId ? '当前项目' : '项目';
+      return `<option value="${esc(optionValue)}" ${value === optionValue ? 'selected' : ''}>${prefix}：${esc(workspace.title)}</option>`;
+    }).join('');
+    const unavailable = projectOptions ? '' : '<option value="" disabled>暂无可用 Workspace</option>';
+    return `<label for="${esc(id)}">连接范围</label><select id="${esc(id)}">${projectOptions}${unavailable}<option value="global" ${value === 'global' ? 'selected' : ''}>所有项目（全局）</option></select><div class="field-help">可选择任一 Workspace；项目范围只在该 Workspace 的 Agent 中可见。全局范围由所有 Workspace 继承，范围绑定不保存或复制凭据。</div>`;
   }
 
   function selectedScopeParams(id = 'cfg-scope') {
-    const scope = $(`#${id}`)?.value || 'global';
-    if (scope === 'project') {
-      if (!currentWorkspace) throw new Error('请先选择一个 Workspace，再使用项目范围');
-      return { scope, workspaceId: currentWorkspace.workspaceId };
+    const value = $(`#${id}`)?.value || 'global';
+    if (value.startsWith('project:')) {
+      const workspaceId = value.slice('project:'.length);
+      if (!workspaceId) throw new Error('请选择一个 Workspace，再使用项目范围');
+      return { scope: 'project', workspaceId };
     }
     return { scope: 'global' };
   }
@@ -1133,7 +1162,10 @@
     syncMarketNav();
     main.innerHTML = '<div class="empty">加载中…</div>';
     const [r, status] = await Promise.all([call('catalog', workspaceParams()), call('status', workspaceParams())]);
-    if (status.ok) setTabCount('installed', (status.detail?.items ?? []).length);
+    if (status.ok) {
+      updateAvailableWorkspaces(status.detail?.scope?.workspaces);
+      setTabCount('installed', (status.detail?.items ?? []).length);
+    }
     if (!r.ok) { main.innerHTML = `<div class="empty">${esc(r.message)}</div>`; return; }
     const items = r.detail?.items ?? [];
     setTabCount('market', items.length);
@@ -1284,6 +1316,7 @@
     main.innerHTML = '<div class="empty">加载中…</div>';
     const [r, migration] = await Promise.all([call('status', workspaceParams()), call('migrationPreview', { scanStored: false })]);
     if (!r.ok) { main.innerHTML = `<div class="empty">${esc(r.message)}</div>`; return; }
+    updateAvailableWorkspaces(r.detail?.scope?.workspaces);
     const items = r.detail?.items ?? [];
     installedItems = items;
     scopeRevision = Number.isInteger(r.detail?.scope?.revision) ? r.detail.scope.revision : 0;