dsh-mcp-connector 0.2.32 → 0.2.33

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 ## [Unreleased]
 
+## [0.2.33] - 2026-09-04
+
+### Added
+
+- 新增 Workspace project / profile global 连接作用域：新连接明确选择目标，已有连接可先预览 Server/工具影响，再复制、移动或按 revision 回滚。
+- project-only 连接通过 DSH Workspace Registry 解析 Agent 归属，并由逐 Agent `tools.restrict()` 和全局 `tools.guard()` 同时强制可见性与执行隔离。
+- 连接健康摘要新增可解释诊断：失败阶段、稳定错误码、说明、建议动作、检查时间和插件进程内最近成功时间，并同步到目录、状态、健康检查、工具发现与图形界面。
+- 新增可携带脱敏配置导出，以及连接变更前自动保存、最多保留 20 个的本机配置快照；页面和对话工具均可创建、列出、预览并原子恢复。
+- 新增 Connection / Server / Tool 三层治理策略，支持影响预览、revision 并发校验、最近 20 版回滚，以及工具增删和重命名后的安全失效处理。
+- deny 规则通过 DSH 官方逐 Agent `tools.restrict()` 收窄 schema/lookup/dispatch，并由全局 `tools.guard()` 在正式执行边界兜底；不提供只能隐藏 UI 的伪禁用。
+
+### Changed
+
+- 作用域文档与连接/凭据分离存储，只包含 connection key、Workspace id 和历史 revision；旧连接按 profile global 兼容，重新授权不会静默改变原范围。同名 Server 由不同连接管理时拒绝覆盖。
+- 已保存但尚未观察到检查结果的连接，以及 Host 暂时无法确认的 stdio 注册状态，现在明确显示“状态未知”；不再以“已配置”暗示连接可用。
+- JSON 脱敏导出会移除 Token、API Key、OAuth Grant、本地路径、Header/env 值与 stdio 参数；占位符未重填时整批拒绝导入。连接配置、导入、启停或断开失败时不保留无效快照。
+
+### Fixed
+
+- 客户端入口移除对 Host 版本特有的 Store、Runtime 和 UI Primitives 模块依赖；弹窗状态改用内置标准 Slot Store contract，避免 Windows Desktop 模块表差异导致插件树加载失败并进入 Safe Mode。
+
+### Documentation
+
+- 新增 project/global 作用域文档，说明继承、Host 强制执行、凭据单份存储、同名 Server 冲突、Workspace 删除和失败回滚边界。
+- 补充兼容矩阵、插件/Host/MCP Server 责任边界、当前限制与按诊断代码排障入口；工具试运行明确等待 DSH 官方执行、权限与审批 API。
+- 补充脱敏矩阵、快照存储边界、原子恢复流程，以及服务端 OAuth 撤销不可由本机快照逆转的责任边界。
+- 补充三层策略优先级、Host 强制执行、未知工具状态、失效规则和回滚边界。
+- 补充 DSH `rc.2` / `alpha.1` / `alpha.5` 工具执行与审批 API 证据矩阵；确认详情页直接试运行仍受 open-turn 审批编排和 MCP annotations 两项缺口阻断。
+
+### Verification
+
+- 190 项自动测试、lint、版本/营销元数据/商店截图门禁和 npm 发布包白名单/敏感内容扫描全部通过。
+
 ## [0.2.32] - 2026-08-31
 
 ### Fixed

package/README.en.md

@@ -1,6 +1,6 @@
 # MCP Connector and MCP Server Marketplace for DeepSeek Harness
 
-> A universal MCP connector and marketplace for connecting, authorizing, discovering, and managing MCP servers, initiated and maintained by the Qichacha (QCC) team
+> DeepSeek Harness MCP Connector and MCP Server marketplace with over one hundred MCP connectors, continuously updated; discover, authorize, and manage connections in one place with OAuth 2.0 PKCE, API keys, stdio/HTTP, mcpServers JSON import, and tool and prompt discovery; maintained by Qichacha/QCC
 
 Manage MCP connections from different providers in one place inside DeepSeek Harness Desktop/Web. Use OAuth 2.0 PKCE, API keys, stdio/HTTP, `mcpServers` JSON import, tool and prompt discovery, and an independently updated Registry of curated connectors.
 
@@ -43,6 +43,7 @@ If the plugin helps you connect an MCP server faster, consider [starring the rep
 | Tool and prompt discovery | Implementation-specific | ✅ |
 | Authorization recovery and connection lifecycle management | Usually not included | ✅ |
 | Connection health checks and Registry refresh | Usually not included | ✅ |
+| Explainable diagnostics and honest unknown state | Usually not included | ✅ |
 | Plugin version discovery and safe updates | Usually not included | ✅ |
 
 ## Features
@@ -55,13 +56,17 @@ If the plugin helps you connect an MCP server faster, consider [starring the rep
 - Dynamic tool discovery grouped by MCP server, including descriptions, search, batched rendering, and an independent scroll region.
 - Curated prompt templates that can open a DSH conversation and prefill its draft; missing variables are requested before the prompt is sent.
 - Persistent connection lifecycle management: restore on restart, enable/disable, disconnect, retry transient OAuth refresh failures with bounded backoff, and revoke authorization. Cards declaring issuer-level sharing reuse one grant; a cross-process lock and per-grant atomic journal prevent Desktop and Web hosts from consuming or overwriting the same rotating refresh token.
+- Portable redacted configuration export plus up to 20 local pre-change snapshots, with preview and atomic restore. Credentials, local paths, and OAuth grants never enter the export.
+- Project/global connection scopes: choose the current DSH Workspace or profile-global visibility when connecting, preview affected servers/tools, then copy, move, or roll back by revision. Credentials remain single-copy and project-only tools are enforced by the DSH Host.
+- Three-layer Connection, Server, and Tool governance with Tool > Server > Connection > default-allow precedence, preview, revision-checked commits, and rollback. DSH Host restrictions narrow schemas/lookups/dispatch while a final execution guard prevents UI-only enforcement.
+- Explainable diagnostics report only observed evidence. Unchecked or Host-unobservable connections remain `unknown`, with a failure stage, stable code, suggested action, check time, and process-local last-success time.
 - Built-in, remote, and local catalogs with `published` and `featured` controls.
 - A standalone remote Registry, allowing new marketplace cards to appear after refresh without publishing a new npm version.
 - Plugin version and one-click updates: version discovery is independent of the installation source, while an Update Provider adapter layer negotiates safe mutation capabilities. DSH Market API v1 is the first adapter and supports progress, normalized failures, rollback, and capability-gated restart/refresh actions. Without a compatible provider the UI offers update instructions; if Desktop has no plugin-market section, it opens the npm package page instead of leaving the user on generic Settings.
 - Explicit, non-destructive migration from the two earlier Qichacha OAuth plugins, plus active-plugin conflict detection that blocks duplicate server management and credential overwrites.
 
 <!-- catalog-stats:start -->
-As of 2026-08-30, the public Registry publishes 82 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 86 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
+As of 2026-09-02, the public Registry publishes 101 connector descriptors. After merging and deduplicating them with the 4 bundled Qichacha cards, the Marketplace exposes 105 cards across 9 business categories. Recommendations remain limited to the four Qichacha cards, PKULaw, and Wind, for 6 featured cards in total. The Registry evolves independently; the badge shown after a client refresh and the live badges above are the authoritative current counts.
 <!-- catalog-stats:end -->
 
 ## Interface and demo
@@ -93,17 +98,20 @@ Run the same command again to upgrade. Fully quit and restart DeepSeek Harness D
 ## Usage
 
 1. Select **MCP Connector** in the primary sidebar.
-2. Choose a connector in Marketplace and complete authorization or configuration.
+2. Choose a connector, confirm **Current project** or **All projects (global)**, and complete authorization or configuration.
 3. Open its details to inspect tools or send an example prompt to a new conversation draft.
 4. Use Installed or the conversation tools to enable, disable, inspect, or disconnect a connection.
 
 Connected tools are exposed to the model with the `mcp__<serverName>__*` prefix.
 
-The detailed [Chinese user guide](docs/USER-GUIDE.md) covers category browsing, the four authentication modes, HTTP/stdio configuration, JSON import, connection management, and troubleshooting.
+The detailed [Chinese user guide](docs/USER-GUIDE.md) covers category browsing, authentication and connection states, HTTP/stdio configuration, JSON import, explainable diagnostics, compatibility, responsibility boundaries, and troubleshooting.
 
 ## Guides and ecosystem
 
-- [User guide: installation, authorization, JSON import, and troubleshooting](docs/USER-GUIDE.md)
+- [User guide: installation, authorization, diagnostics, compatibility, and troubleshooting](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)
+- [Tool trial: official API evidence and safety design](docs/TOOL-TRIAL-DESIGN.md)
 - [Plugin updates: version discovery, providers, and rollback](docs/PLUGIN-UPDATE.md)
 - [Marketplace registration: local cards, the public Registry, and OAuth requirements](docs/MARKET-REGISTRATION.md)
 - [Third-party connector onboarding](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)
@@ -135,6 +143,19 @@ The default bundle configuration is in `cordis.patch.yml`:
 
 Set `catalogUrl` to an empty string for an explicitly offline/private setup. A custom non-default URL is used as-is and does not fall back to the public registry.
 
+## Compatibility and responsibility boundary
+
+| Area | Current boundary |
+|---|---|
+| Host and runtime | DSH Desktop / `web` profile; Node.js 20+ |
+| MCP client | Official `@deepseek-ai/dsh-mcp-client` `^0.1.1-rc.2` |
+| Transports | Streamable HTTP and stdio; legacy `sse` normalizes to Streamable HTTP |
+| Configuration scope | Workspace project / profile global, with Host enforcement, impact preview, copy/move, and revision rollback |
+| Configuration exchange | JSON import, redacted export, up to 20 local snapshots, preview, and atomic restore |
+| Governance and execution | Connection / Server / Tool allow/deny with preview, revision commits, and rollback; no tool trial yet |
+
+The plugin owns the catalog, authorization, connection records, governance rules, official-client provisioning, read-only health checks, tool discovery, and diagnostics. DSH Host and the official MCP client own transport, stdio subprocesses, tool registration, real tool execution, and permission/approval flows. Governance uses the Host's official restriction/guard boundary; the plugin never invokes MCP tools from the browser. See the [user guide](docs/USER-GUIDE.md#74-如何理解连接诊断) for status semantics, limitations, and troubleshooting.
+
 ## Development and release checks
 
 ```bash
@@ -150,7 +171,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.32`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.32](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.32).
+The current public version is [`dsh-mcp-connector@0.2.33`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.33](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.33).
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md) for the Desktop release checklist.
 
@@ -158,12 +179,16 @@ See [CHANGELOG.md](CHANGELOG.md) for version history and [docs/DESKTOP-E2E.md](d
 
 - Credentials stay inside the local DSH storage boundary: connection records use the storage domain, while rotating OAuth credentials are also saved in `$DSH_HOME/storages/mcp_connector_grants_v1` so stale host snapshots cannot overwrite them. The directory is mode 0700 and records are mode 0600; credentials are never written to the catalog, Git repository, page, logs, or conversation history.
 - Failed API key/token validation is not persisted; authentication, timeout, DNS, and TLS/network errors are reported separately.
+- Unchecked or Host-unobservable connections are reported as `unknown`, never as healthy. Health history and last-success timestamps are currently process-local.
 - External URLs must use HTTPS; HTTP is allowed only for loopback development.
 - Remote descriptors and catalogs are limited to 2 MiB, Web API requests to 1 MiB, and imported JSON is scanned for credential fields before normalization.
 - Streamable HTTP and stdio are supported end to end. Legacy `sse` entries are normalized to Streamable HTTP. The connector passes stdio `command/args/env/cwd` to `@deepseek-ai/dsh-mcp-client` instead of reimplementing process transport.
 - stdio starts a local process. Import or connect only trusted commands and packages. Catalog descriptors may declare `credentialFields` and `credentialBindings`, but may never contain actual token/secret values; user input is injected only into the local Host process environment.
 - OAuth DCR client secrets share the same local-only boundary as access and refresh tokens and are omitted from catalog/status responses and logs.
+- Redacted exports replace tokens, API keys, static header/env values, stdio arguments, local directories, and URLs containing query/user information with explicit placeholders. OAuth entries contain only a reconnect reference; full snapshots remain inside the current profile's storage domain.
 - The primary sidebar placement uses the stable DSH `data-slot` marker and falls back to the footer if that marker is removed.
+- Project/global scopes apply only inside the current DSH profile and do not synchronize across profiles. If a Workspace is deleted, its project-only bindings remain fail-closed until moved to another project or global.
+- Tool trials are not implemented. Governance and scopes are enforced in the DSH Host execution path. The tool-trial design records the official API evidence, but remains blocked until DSH exposes safe out-of-turn approval orchestration and the MCP bridge preserves side-effect metadata. A local snapshot cannot recreate a server-side OAuth grant after revocation.
 
 ## License
 

package/README.md

@@ -1,6 +1,6 @@
 # MCP连接器：DeepSeek Harness MCP Server 连接与管理市场
 
-> 连接、授权、发现和管理 MCP Server 的通用 MCP Connector 与 Marketplace，由企查查（Qichacha/QCC）团队发起并维护
+> DeepSeek Harness 的 MCP连接器与 MCP Server 市场，收录超百个 MCP连接器并持续更新；统一发现、授权和连接管理，支持 OAuth 2.0 PKCE、API Key、stdio/HTTP、mcpServers JSON 导入，以及工具与 Prompt 发现；由企查查/QCC 团队维护
 
 在 DeepSeek Harness Desktop/Web 中一站式管理不同厂商的 MCP 连接：支持 OAuth 2.0 PKCE、API Key、stdio/HTTP、`mcpServers` JSON 导入、工具与 Prompt 发现，并通过独立 Registry 持续更新精选连接器目录。
 
@@ -43,6 +43,7 @@ dsh plugin --profile web add dsh-mcp-connector
 | 工具与 Prompt 发现 | 视实现而定 | ✅ |
 | 授权恢复与连接生命周期管理 | 通常无 | ✅ |
 | 连接健康检查与 Registry 刷新 | 通常无 | ✅ |
+| 可解释诊断与诚实的未知状态 | 通常无 | ✅ |
 | 插件版本检测与安全更新 | 通常无 | ✅ |
 
 ## 功能
@@ -55,15 +56,19 @@ dsh plugin --profile web add dsh-mcp-connector
 - 三种接入：OAuth 2.0 PKCE、自定义 HTTP/stdio、导入 `mcpServers` JSON；也支持从连接器描述 URL 安装。OAuth 动态注册兼容公共客户端以及 `client_secret_post` / `client_secret_basic` 机密客户端。
 - 市场 Bearer/API Key 连接器先执行 MCP initialize 连通性与凭据校验，全部 HTTP Server 通过后才持久化凭据并进入“已安装”；stdio 卡片可声明多个本机凭据字段及其环境变量映射。
 - 生命周期管理：连接持久化、重启恢复、启停、断开、OAuth 自动刷新/退避恢复与撤销；同 issuer 卡片共享一次授权，跨进程锁与独立原子 Grant journal 防止 Desktop/Web 并行时重复消耗 Refresh Token。
+- 配置备份：一键复制/下载可再次导入的脱敏 JSON；连接变更前自动保存最多 20 个本机快照，支持预览与原子恢复。凭据、本地路径和 OAuth Grant 不进入导出结果。
+- 连接作用域：新连接可选当前 Workspace 项目或 profile 全局；支持先预览 Server/工具影响，再复制、移动或按 revision 回滚。凭据只存一份，project-only 工具由 DSH Host 强制隔离。
+- 三层治理：Connection、Server、Tool 规则按 Tool > Server > Connection > 默认允许解析；变更先预览、按 revision 提交并可回滚，由 DSH Host 的 schema/lookup/dispatch restriction 与最终执行 Guard 真实生效。
+- 可解释诊断：只报告实际观察结果；未检查或 Host 状态不可见时显示“状态未知”，并提供失败阶段、稳定错误码、建议动作、检查时间和进程内最近成功时间。
 - 目录运营：内置目录、远程 registry、本地覆盖，支持 `published` 上下架与 `featured` 精选。
 - 独立远程 Registry：新市场卡片合并后客户端刷新即可见，无需重新发布 npm；远程不可用时自动回退内置目录。
 - 插件版本与一键更新：版本发现独立于安装来源；页面通过 Update Provider 适配层探测安全更新能力。DSH Market API v1 是首个适配器，支持进度、稳定失败码、回滚及按宿主能力提供的重启/刷新操作；无可用 Provider 时回退到当前插件市场或 npm。
 - Registry 工具链：Schema/唯一性/密钥审计、MCP/OAuth 无凭据探针、每周健康巡检。
 - 平滑迁移：显式扫描并复制两个旧企查查 OAuth 插件授权；检测到旧插件仍启用并管理同名 Server 时阻断重复连接，避免凭据相互覆盖。
-- 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`install_from_url`、`status`、`health_check`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。
+- 对话工具：`mcp_connector_catalog`、`connect`、`configure`、`import_json`、`export_config`、`snapshot`、`install_from_url`、`status`、`scope`、`health_check`、`policy`、`set_enabled`、`disconnect`、`refresh_catalog`、`publish`、`tools_list`。
 
 <!-- catalog-stats:start -->
-截至 2026-08-30，公共 Registry 已发布 82 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 86 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标和上方实时统计徽标为准。
+截至 2026-09-02，公共 Registry 已发布 101 条连接器描述；与随包的 4 张企查查卡片合并去重后，市场页可浏览 105 张卡片，覆盖企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他 9 类。推荐位严格保留 4 张企查查卡片、北大法宝和 Wind，共 6 张；其他连接器按业务分类展示。Registry 可独立持续更新，实际数量以客户端刷新后的市场页签徽标和上方实时统计徽标为准。
 <!-- catalog-stats:end -->
 
 ## 界面与演示
@@ -95,17 +100,21 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/m
 ## 使用
 
 1. 点击左侧“🧩 MCP连接器”。
-2. 在市场中选择连接器并完成授权或配置。
+2. 在市场中选择连接器，确认“当前项目”或“所有项目（全局）”，再完成授权或配置。
 3. 打开卡片详情，可点击示例 Prompt 的发送按钮，在当前工作区创建/复用空白会话并写入草稿。
 4. 在“已安装”或对话工具中查看、停用、恢复或断开连接。
 
 连接成功后，工具按 `mcp__<serverName>__*` 前缀提供给模型。
 
-分类浏览、四种鉴权状态、自定义 HTTP/stdio、JSON 导入、连接管理与故障排查见完整的[用户手册](docs/USER-GUIDE.md)。
+分类浏览、鉴权与连接状态、自定义 HTTP/stdio、JSON 导入、脱敏备份、可解释诊断、兼容矩阵、责任边界与故障排查见完整的[用户手册](docs/USER-GUIDE.md)。
 
 ## 中文教程与生态入口
 
-- [用户手册：安装、授权、JSON 导入与故障排查](docs/USER-GUIDE.md)
+- [用户手册：安装、授权、诊断、兼容性与故障排查](docs/USER-GUIDE.md)
+- [配置备份：脱敏导出、快照与恢复边界](docs/CONFIG-BACKUP.md)
+- [连接作用域：project/global 继承、复制、移动与回滚](docs/CONNECTION-SCOPES.md)
+- [连接、Server 与 Tool 治理](docs/TOOL-GOVERNANCE.md)
+- [工具试运行：官方 API 证据与安全设计](docs/TOOL-TRIAL-DESIGN.md)
 - [插件更新：版本检测、Provider 与回滚](docs/PLUGIN-UPDATE.md)
 - [市场注册：本地卡片、公共 Registry 与 OAuth 要求](docs/MARKET-REGISTRATION.md)
 - [第三方连接器上架指南](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)
@@ -130,6 +139,19 @@ Bundle 默认配置位于 `cordis.patch.yml`：
 
 `catalogUrl` 默认通过 jsDelivr CDN 读取公共 [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry)，支持 ETag/TTL 缓存；主源失败时自动尝试 GitHub raw 备用源，再回退到上次缓存或随包内置目录。jsDelivr 的分支 URL 可能存在缓存延迟，因此 Registry 合并后的新卡片不保证秒级出现。需要离线/私有模式时可将 `catalogUrl` 显式设为空字符串；显式配置其他目录 URL 时不会自动切换到公共备用源。
 
+## 兼容性与责任边界
+
+| 项目 | 当前边界 |
+|---|---|
+| 宿主与运行时 | DSH Desktop / `web` profile，Node.js 20+ |
+| MCP 客户端 | 官方 `@deepseek-ai/dsh-mcp-client` `^0.1.1-rc.2` |
+| 传输 | Streamable HTTP、stdio；旧 `sse` 归一为 Streamable HTTP |
+| 配置作用域 | Workspace project / profile global；全局由项目继承，Host 强制隔离，支持预览、复制/移动和 revision 回滚 |
+| 配置交换 | JSON 导入、脱敏导出、最多 20 个本机快照、预览与原子恢复 |
+| 治理与执行 | Connection / Server / Tool allow/deny，预览、revision 提交与回滚；暂无工具试运行 |
+
+插件负责目录、授权、连接记录、官方客户端条目、治理规则、只读健康检查、工具发现和诊断；DSH Host 与官方 MCP 客户端负责 transport、stdio 子进程、工具注册、正式工具执行及权限/审批链。治理通过 Host 官方 restriction/guard 生效，插件不会从浏览器旁路调用 MCP 工具。详细状态语义、限制与排障见[用户手册第 7–10 节](docs/USER-GUIDE.md#74-如何理解连接诊断)。
+
 ## 开发与发布门禁
 
 ```bash
@@ -145,7 +167,7 @@ npm run dev:ui
 
 公共 Registry 每次合并后会生成 `catalog-stats.json`；本仓库的定时工作流每小时同步中英文介绍和统计快照。npm 页面中的静态正文随版本发布更新，上方动态统计徽标则直接读取 Registry，可在不发布新 npm 版本时保持实时数量一致。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.32`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.32](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.32)。
+当前公开版本为 [`dsh-mcp-connector@0.2.33`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.33](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.33)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。
@@ -157,13 +179,17 @@ stdio 传输的架构、透传边界与安全约束见 [docs/STDIO-SUPPORT.md](d
 
 - 凭证只持久化在本机 DSH storage 边界：连接记录使用 storage domain，OAuth 轮换凭据同步保存到 `$DSH_HOME/storages/mcp_connector_grants_v1`。该目录为 0700、文件为 0600；凭证不进入市场目录、Git 仓库、页面、日志或对话历史。
 - 市场 Key/Token 校验失败时不写入 storage domain；鉴权、超时、DNS、TLS/网络错误会分类提示。
+- 未检查或 Host 状态不可见时显示“状态未知”，不会冒充健康；健康摘要与最近成功时间当前只保留在插件进程内。
 - 外部 URL 仅允许 HTTPS，HTTP 仅允许回环地址；导入配置会校验 URL 与 Header。
 - 远程目录/描述响应限制 2 MiB，Web API 请求限制 1 MiB；原始 JSON 在归一化前扫描凭据字段。
 - 完整覆盖 Streamable HTTP 与 stdio；旧 `sse` 配置在导入/恢复时归一为 Streamable HTTP。stdio 的 `command/args/env/cwd` 原样交给 `@deepseek-ai/dsh-mcp-client`，插件本身不重复实现进程传输。
 - stdio 会启动本机进程：仅导入或连接可信命令/软件包。市场目录只能用 `credentialFields` + `credentialBindings` 声明输入与 env 映射，不得携带真实 token/secret；用户填写值只写入本机连接记录并交给 Host。
 - OAuth DCR 的 `client_secret` 与 Access/Refresh Token 采用相同的本机存储边界，不会进入市场 API、状态输出或日志。
+- 脱敏导出把 Token/API Key、静态 Header/env 值、stdio 参数、本地目录及带查询参数的 URL 替换为占位符；OAuth 只保留重新授权引用。快照中的完整配置仍只在当前 profile 的 storage domain 内。
 - 顶部入口通过 DSH 稳定 `data-slot` 定位并使用 React Portal；DSH 若移除该标记，入口会回退到底部，不影响连接器功能。
 - 旧授权迁移必须显式确认，只复制不删除；确认新连接可用后再手动停用旧插件。
+- project/global 作用域仅在当前 DSH profile 内生效；不会跨 profile 同步。删除 Workspace 后，原 project-only 绑定保持 fail closed，需手动移动到其他项目或全局。
+- 当前没有工具试运行；治理与作用域都由 DSH Host 正式工具执行链强制应用。试运行已完成官方 API 复核，但在 out-of-turn 审批编排和 MCP 副作用元数据缺口补齐前保持 design blocked。快照不能恢复服务端已撤销的 OAuth Grant。
 
 ## License
 

package/docs/CONFIG-BACKUP.md

@@ -0,0 +1,39 @@
+# 配置备份：脱敏导出、快照与恢复
+
+MCP连接器提供“可携带脱敏导出”和“当前 profile 本机快照”两套能力。前者用于迁移或排障共享，后者用于撤销本机连接变更；两者的安全边界不同。
+
+## 脱敏导出
+
+在“已安装”页点击“配置备份”，可复制或下载 JSON；对话中可调用 `mcp_connector_export_config`。
+
+| 配置内容 | 导出行为 |
+|---|---|
+| Bearer Token / API Key | 替换为 `<REDACTED:REENTER>` |
+| 静态 Header 与 env 值 | 保留字段名，值替换为占位符 |
+| stdio 参数 | 每个参数替换为占位符 |
+| 绝对命令、本地 `cwd` | 替换为 `<REDACTED:LOCAL_VALUE>` |
+| 带用户信息、查询参数或 fragment 的 URL | 整个 URL 替换为占位符 |
+| OAuth Grant、Access/Refresh Token、动态客户端密钥 | 永不导出；仅记录需要从市场重新授权的连接引用 |
+
+导出的 `connections` 仍兼容 JSON 导入。只要存在未替换的占位符，导入会在启动任何 Server 前整体拒绝；全部重填后才进入既有的批量预校验和原子连接流程。`oauthConnections` 不会被当作本机凭据导入，并会显示“需从市场重新授权”。
+
+## 本机配置快照
+
+连接、配置、JSON 导入、启停和断开前会先保存受影响 key 的状态；也可在页面手动创建全量当前快照，或调用 `mcp_connector_snapshot`：
+
+- `list`：列出公开摘要；
+- `create`：手动创建；
+- `preview`：查看恢复与移除范围；
+- `restore`：执行原子恢复。
+
+每个 profile 最多保留 20 个快照，超过后删除最旧项。完整记录可能含本机凭据，只保存在 `mcp_connector` storage domain 的 `snapshots` 表；公开 API 只返回 id、时间、原因、key 与数量，不返回记录正文或 Grant key。
+
+## 原子恢复
+
+恢复只影响快照声明的目标 key：先为目标记录准备 Host 条目，再移除变更后新增的目标条目，最后写入连接存储。如果任一 Server 启动、Host 更新、删除或持久化失败，插件会恢复调用前的 Host 条目和连接记录。重复恢复同一快照保持相同结果。若恢复会移除后来新增的 OAuth 连接，预览会明确提示；连接移除成功后，只在没有其他连接共享时撤销该授权。
+
+## OAuth 边界
+
+快照不复制 OAuth Access/Refresh Token 或动态客户端密钥，只引用当前本机 Grant。共享 Grant 仍存在且有效时，连接记录可以恢复；如果断开最后一个引用后 Grant 已在服务端撤销、在本机删除或被标记为需重新授权，预览和恢复都会拒绝伪恢复，并要求从市场重新授权。
+
+服务端撤销是外部状态，无法由本机快照逆转。这是明确的非目标，不属于原子恢复承诺。

package/docs/CONNECTION-SCOPES.md

@@ -0,0 +1,66 @@
+# MCP 连接的 project/global 作用域
+
+本说明定义 MCP连接器的 Workspace 项目范围、profile 全局范围、Host 强制执行边界，以及复制、移动和回滚的安全语义。
+
+## 1. 两级范围与继承
+
+- **项目（project/workspace）**：绑定 DSH 的稳定 `workspaceId`，只向该 Workspace 内的 Agent 展示并允许执行。
+- **全局（profile/global）**：在当前 DSH profile 的所有 Workspace 中可见。这不是操作系统级全局，也不会跨 profile 共享。
+
+全局连接由所有 Workspace 继承。项目连接可绑定一个或多个 Workspace；同一连接也可保留项目绑定同时提升为全局。
+
+## 2. 新建连接
+
+Desktop 和 Web 使用同一个 Host API：
+
+1. 市场从父级 DSH 客户端读取当前 Workspace；
+2. OAuth、免密、Bearer/API Key、JSON 导入和 URL 安装都会在提交前显示目标范围；
+3. 已选择 Workspace 时页面默认为“当前项目”，也可显式选择“所有项目（全局）”；
+4. 项目范围只在 Host 支持最终执行 Guard，且目标 Workspace 仍存在时才能保存。
+
+对话工具的 `scope` 可传 `project` 或 `global`；`project` 同时要求 `workspaceId`。旧版客户端未传作用域时，新连接按兼容规则归为当前 profile 全局。
+
+## 3. Host 强制执行
+
+项目隔离不是页面过滤：
+
+- 插件使用 Workspace Registry 将 Agent 的 session/cwd 解析为稳定 `workspaceId`；
+- 通过每 Agent `tools.restrict()` 从 schema、lookup 和 dispatch 中隐藏其他项目的工具；
+- 通过全局 `tools.guard()` 在正式执行边界再次检查；
+- 没有 Agent 上下文的 project-only 工具调用会 fail closed；
+- 工具注册变化或作用域提交后，存活 Agent 的 restriction 会重新同步。
+
+连接、Server、Tool 三层 allow/deny 治理与作用域同时生效：只有当前 Workspace 可见且治理规则允许的工具才能执行。
+
+## 4. 复制、移动、预览与回滚
+
+“已安装”页的“范围”操作提供两种变更：
+
+- `copy`：增加目标绑定，保留现有范围；
+- `move`：用一个目标替换现有范围。
+
+每次变更都先返回受影响的连接、Server 和已观察/快照工具，只读预览不写入存储。用户确认后使用预览返回的 `baseRevision` 提交；并发变更会被拒绝并要求重新预览。
+
+作用域文档保留最近 20 个历史 revision。回滚恢复整份作用域文档，并产生新 revision；不修改连接配置或服务端授权。
+
+## 5. 凭据、冲突与失败边界
+
+- 作用域文档只保存 connection key、全局布尔值、Workspace id 和 revision 历史；不保存 URL、Header、Token、API Key、OAuth Grant、stdio 参数或本地路径。
+- `copy`/`move` 只改变绑定，连接和凭据仍只存储一份；重新授权或重新配置在没有显式新范围时保留原绑定。
+- 不同连接试图管理同一 `serverName` 时直接拒绝，不会用新凭据或新范围静默覆盖旧连接。
+- 新连接提交时先持久化作用域，再使连接对 Host 可见；后续持久化或 Host 启动失败时作用域自动回滚。
+- 断开后可保留不含凭据的孤立绑定，用于本机快照恢复；同 key 新建连接会按新选择重置范围。
+- Workspace 被删除后，指向它的 project-only 连接不会泄漏到其他项目；可在已安装页把它移动到当前项目或全局。
+- 仅“从未存在作用域文档/绑定”按旧版全局连接兼容；已存在文档读取失败或绑定损坏时插件 fail closed，不会把项目连接降级为全局。
+
+## 6. 对话工具
+
+`mcp_connector_scope` 支持：
+
+- `action=context`：读取 Workspace、Host 能力和 revision；
+- `action=preview`：预览 `copy`/`move` 及 Server/工具影响；
+- `action=apply`：带 `expectedRevision` 提交；
+- `action=preview-rollback`：预览恢复历史 revision 将影响的 Server/工具；
+- `action=rollback`：使用预览时的 `expectedRevision` 恢复指定 `rollbackRevision`。
+
+页面和对话工具调用同一 API 门面与 Host 控制器，Desktop 与 `dsh web` 没有另外的前端作用域实现。

package/docs/TOOL-GOVERNANCE.md

@@ -0,0 +1,67 @@
+# MCP 连接、Server 与 Tool 治理
+
+本说明描述 MCP连接器的三层治理模型、DSH Host 强制执行边界、预览/回滚流程，以及工具增删时的安全语义。
+
+## 1. 策略层级与优先级
+
+策略作用于当前 DSH profile，默认允许。存在多层显式规则时，越具体的规则优先：
+
+1. Tool：一个 MCP Server 下的单个工具；
+2. Server：一个连接器下的单个 `serverName`；
+3. Connection：同一 `connectorId` 的全部 Server；
+4. 默认允许。
+
+例如，Connection 设置为拒绝、某个 Server 设置为允许、该 Server 下一个写入 Tool 再设置为拒绝，最终只有这个 Tool 被拒绝，Server 的其他 Tool 仍允许。
+
+“已安装”页的启停是连接生命周期控制，会让对应 Server 的官方 MCP Client 条目下线。生命周期停用高于所有治理 allow，不能用 Tool/Server allow 重新启用一个已停用连接。
+
+## 2. Host 强制执行
+
+治理不是前端隐藏：
+
+- 插件通过 DSH 官方 `ToolRuntime.restrict()`，为每个 Agent 收窄模型可见 schema、工具查找与 dispatch；
+- 插件同时通过官方 `ToolRuntime.guard()` 安装全局、单调拒绝的最终执行 Guard；
+- `agent/created` 保证新 Agent 在首轮 Prompt 组装前得到 restriction；
+- `tools/change` 在 MCP Server 新增、删除或重新注册工具时同步更新所有存活 Agent；
+- Guard 动态读取当前规则，因此即使可见性同步发生竞争，拒绝规则仍不能被调用绕过。
+
+如果 Host 没有 `tools.guard`，插件会拒绝保存新的 deny 规则，不会把只能隐藏页面、无法阻止执行的状态报告为“已禁用”。
+
+## 3. 预览、提交与回滚
+
+页面每次修改 Connection、Server 或 Tool 策略时，先调用只读预览：
+
+- 返回当前 `baseRevision`；
+- 统计 Host 已观察工具中将新增拒绝、恢复允许和总变化数量；
+- 用户确认后才用同一 revision 提交；
+- 如果期间策略已经变化，提交失败并要求重新预览。
+
+每次有效提交都会保存上一 revision 的规则快照，最多保留 20 份。页面“撤销最近变更”或 `mcp_connector_policy` 的 `rollback` 操作可以恢复历史内容；回滚本身生成一个新的 revision，不改写历史。
+
+## 4. 工具增删、重命名与未知状态
+
+Tool 规则同时保存 MCP 原始工具名和 Host 实际注册的 public name。复杂名称按官方 MCP Client 的公开命名契约规范化并加 SHA-256 短哈希，避免从截断后的名称反推原名。
+
+- 新增工具：自动继承其 Server/Connection 规则，并在注册事件内同步到 Agent restriction；
+- 删除或重命名：旧规则只会匹配旧 public name，不会误伤新工具；成功观察到最新清单后标记为 `stale`；
+- Server 暂时离线或 Host 未提供工具清单：规则标记为 `unobserved`，而不是误报“已禁用”或“健康”；
+- 目标连接已经删除：规则标记为 `orphaned`，不会匹配后来由其他连接器创建的同名 Server。
+
+## 5. 页面与对话工具
+
+连接器详情的“工具详情”区域提供：
+
+- Connection 策略：一次覆盖该连接器的全部 Server；
+- Server 策略：覆盖单个 Server；
+- Tool 策略：覆盖单个 Tool；
+- 每个已观察 Tool 的最终状态、策略来源和继承关系；
+- revision 与最近一次策略回滚入口。
+
+对话中使用 `mcp_connector_policy`：
+
+- `action=list`：列出规则、状态、Host 能力和历史 revision；
+- `action=preview`：只读预览；
+- `action=apply`：带 `expectedRevision` 提交；
+- `action=rollback`：恢复指定 `rollbackRevision`。
+
+正式 MCP 工具执行仍由 DSH Host 与官方 MCP Client 负责；本插件不从浏览器直接调用 MCP 工具，也不绕过 Host 的权限或审批链。

package/docs/USER-GUIDE.md

@@ -57,6 +57,8 @@ dsh web
 
 ## 4. 连接市场卡片
 
+新连接提交前会显示目标范围。已在 DSH 中选择 Workspace 时默认为“当前项目”；选择“所有项目（全局）”后，当前 profile 的每个 Workspace 都会继承该连接。OAuth、免密、Bearer/API Key、JSON 导入和 URL 安装使用相同规则。
+
 卡片右侧按钮会根据鉴权方式和当前状态变化：
 
 | 按钮/状态 | 含义 | 操作 |
@@ -65,7 +67,7 @@ dsh web
 | `配置` | 需要 Bearer Token 或 API Key | 录入服务商签发的凭据并验证 |
 | `需重新授权` | OAuth 授权过期、被撤销或不可用 | 点击后重新完成 OAuth 授权 |
 | `自动重试中` | OAuth Token 刷新遇到网络或服务端暂时故障 | 无需重新授权；保持 DSH 运行，插件会按退避策略自动恢复 |
-| `已配置` | 本机已有配置，尚未完成本轮健康确认 | 点击“刷新连接器目录”或进入详情检查 |
+| `状态未知` | 本机已有配置，但本进程尚未观察到可用性检查结果；不代表健康或异常 | 点击“刷新连接器目录”或进入详情检查 |
 | `已连接` | 最近一次健康检查通过 | 可直接在会话中使用对应 MCP 工具 |
 | `部分异常` / `连接异常` | 一个或多个 Server 未通过检查 | 打开详情查看提示，核对网络、权限和服务状态 |
 
@@ -83,10 +85,10 @@ OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据
 
 1. 阅读服务说明、鉴权方式、数据范围与可能产生的费用或副作用。
 2. 在“试试这样用”中选择示例 Prompt；带变量的模板会先要求补齐查询主体等信息。
-3. 展开“工具详情”查看 Server 数量、工具名称与描述，并可搜索工具。
+3. 展开“工具详情”查看 Server 数量、工具名称与描述，并可搜索工具；连接后还可按 Connection、Server、Tool 设置治理规则。
 4. 点击“去试试”或 Prompt 的发送按钮，在当前工作区创建或复用空白会话并写入草稿。
 
-连接成功后，工具按 `mcp__<serverName>__*` 前缀提供给模型。工具清单来自服务端，实际数量会随服务商权限和版本变化。
+连接成功后，工具按 `mcp__<serverName>__*` 前缀提供给模型。工具清单来自服务端，实际数量会随服务商权限和版本变化。详情与“已安装”列表会展示最近一次诊断的阶段、稳定错误码、说明、建议动作和最近成功时间。
 
 ## 6. 添加自定义连接
 
@@ -143,7 +145,77 @@ stdio 进程由 `@deepseek-ai/dsh-mcp-client` 管理，插件透传 `command`、
 
 OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端点时仍会删除 DSH 本机授权记录。连接状态发生变化后，可点击“刷新连接器目录”重新检查。
 
-## 8. 安全边界
+### 7.1 配置备份与恢复
+
+“已安装”页的“配置备份”提供两种互补能力：
+
+- **脱敏导出**：复制或下载可携带 JSON。Token/API Key、静态 Header/env 值、stdio 参数、本地目录以及可能含凭据的 URL 会变成明确占位符；目标设备导入前必须重填。OAuth 只导出连接引用，必须从市场重新授权。
+- **本机快照**：连接、配置、导入、启停或断开前自动保存变更范围，也可手动创建；最多保留 20 个。恢复前可查看将恢复和移除的 key，恢复过程中任一 Server 或持久化步骤失败会整体回到恢复前状态。
+
+快照可能包含用于原样恢复的本机凭据，因此只保存在当前 profile 的 storage domain，不会通过 Web API、对话工具或日志原样返回。断开并撤销 OAuth 后，快照不能重建服务端 Grant，会明确要求重新授权。完整边界见[配置备份说明](CONFIG-BACKUP.md)。
+
+### 7.2 Connection、Server 与 Tool 治理
+
+连接器详情的“工具详情”支持三层 allow/deny：Tool 规则优先于 Server，Server 优先于 Connection，没有显式规则时默认允许。“已安装”页的连接停用是物理下线状态，不能被下级 allow 覆盖。
+
+每次修改先显示 Host 已观察工具的影响预览，确认后按 revision 提交；策略并发变化时会要求重新预览。最近 20 个 revision 可回滚。拒绝规则同时通过 DSH Host 的逐 Agent restriction 和最终执行 Guard 生效，不是只隐藏页面。
+
+工具尚未被 Host 观察时显示“未观察”，不会报告为“已禁用”或“健康”。工具删除或重命名后，旧规则标记为失效但不会误伤新工具；新注册工具自动继承 Server/Connection 规则。完整语义见[治理说明](TOOL-GOVERNANCE.md)。
+
+### 7.3 project/global 连接范围
+
+“已安装”会在每条连接上显示范围。点击“范围”可选择：
+
+- “复制”增加当前项目或全局绑定，保留原范围；
+- “移动”用所选范围替换原绑定。
+
+提交前页面会列出受影响的 Server 和已知工具。确认后才按 revision 写入，可使用“回滚上次范围变更”恢复。范围变更不复制 Token、API Key 或 OAuth Grant；不同连接管理同一 `serverName` 时会拒绝静默覆盖。完整执行和失败边界见 [project/global 作用域](CONNECTION-SCOPES.md)。
+
+### 7.4 如何理解连接诊断
+
+诊断结果只陈述插件实际观察到的事实，不把“配置已保存”当作“连接健康”：
+
+- `unknown` / `状态未知`：没有本进程内的主动检查结果，或 Host 暂时无法提供 stdio 工具注册状态。它既不是成功，也不是失败。
+- `stage` / `stageLabel`：失败或未知发生在哪一层，例如鉴权、网络与传输、MCP 初始化、Host 启动、Host 状态观测或工具发现。
+- `code`：便于 Issue、自动化和排障引用的稳定代码，例如 `auth`、`dns`、`protocol`、`host-tools-pending`。
+- `message` / `action`：当前观察结果与下一步建议；不会包含 Token、API Key 或 OAuth 客户端密钥。
+- `checkedAt`：最近一次观察时间；`lastSuccessfulAt`：当前插件进程内最近一次确认可用的时间。插件重启后，如果还没有重新检查，时间为空并回到“状态未知”，不会沿用未经本进程验证的健康状态。
+
+多 Server 连接器只要部分 Server 可用、部分异常，就显示“部分异常”；每条已安装连接仍保留自己的诊断。OAuth Access Token 暂时刷新失败显示“自动重试中”，只有明确的永久授权失败才显示“需重新授权”。
+
+## 8. 兼容性、架构与责任边界
+
+### 8.1 兼容矩阵
+
+| 能力 | 当前支持 | 说明 |
+|---|---|---|
+| DSH 宿主 | Desktop / `web` profile | Node.js 20+；连接保存于当前 profile |
+| 官方 MCP 客户端 | `@deepseek-ai/dsh-mcp-client` `^0.1.1-rc.2` | 负责连接生命周期、stdio 进程和工具注册 |
+| 传输 | Streamable HTTP、stdio | 历史 `sse` 配置归一为 Streamable HTTP |
+| 鉴权 | 无鉴权、Bearer、API Key、OAuth 2.0 PKCE | OAuth 支持动态客户端注册和 Grant 共享 |
+| 配置交换 | JSON 导入、脱敏导出、本机快照 | 占位符需重填；恢复原子执行；OAuth 撤销后需重新授权 |
+| 作用域 | Workspace project / profile global | 全局由所有 Workspace 继承；project-only 工具由 Host restriction + guard 强制隔离 |
+| 治理 | 连接生命周期启停；Connection / Server / Tool allow/deny | 规则作用于当前 profile，支持预览、revision 提交与回滚 |
+| 工具能力 | 工具清单与描述发现 | 暂无工具试运行按钮；不会绕过 Host 权限/审批链调用工具 |
+
+### 8.2 谁负责什么
+
+- **MCP连接器插件**：市场目录、配置录入、OAuth/Key 生命周期、连接记录、治理规则、向官方 MCP 客户端创建条目、只读健康检查、工具发现和诊断展示。
+- **DSH Host 与 `@deepseek-ai/dsh-mcp-client`**：HTTP/stdio 传输、stdio 子进程环境清理和启动、MCP 生命周期、工具注册、正式工具执行，以及宿主提供的权限与审批流程。
+- **MCP Server / 服务商**：工具定义、账户权限、配额、费用、数据新鲜度和实际副作用。
+- **用户与模型**：确认调用目的、参数与影响；涉及写入、付费、发布、删除等副作用时，遵循 Host 的确认/审批流程。
+
+插件不会自行重写官方 MCP transport，也不会从浏览器直接调用 MCP 工具。DSH 已提供正式 ToolRuntime 执行、取消、超时和一次性审批契约；但详情页直接试运行仍缺少 out-of-turn 用户编排入口，官方 MCP bridge 也未传递工具副作用 annotations。安全门槛与版本证据见[工具试运行设计](TOOL-TRIAL-DESIGN.md)。
+
+### 8.3 当前限制
+
+- 健康摘要和最近成功时间目前只保留在插件进程内；重启后先显示“状态未知”，直至重新检查。
+- HTTP 工具清单使用只读 MCP `tools/list` 发现；stdio 工具清单读取 Host 已注册工具。Host 不提供可观测状态时只能报告未知。
+- 连接凭据、快照、治理规则和作用域历史都存储在当前 profile；project/global 不跨 profile 同步。
+- Workspace 被删除后，原 project-only 绑定保持 fail closed，需手动移动到当前项目或全局。
+- 连接级停用可逆；断开会删除本机连接，并在授权不再共享时尽力撤销 OAuth。非 OAuth 配置可用断开前快照恢复；已撤销的 OAuth 必须重新授权。
+
+## 9. 安全边界
 
 - 凭据仅保存在 DSH storage domain，不进入市场目录、Git 仓库或对话历史。
 - stdio 目录只能声明凭据字段与 env 映射，不能给出真实值；Registry 探针不会执行目录中的本地命令。
@@ -153,7 +225,7 @@ OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端
 - 连接器能看到的数据和能执行的操作取决于你授予的账户权限；优先使用最小权限 Token/API Key。
 - 生成、付费、写入、发布、删除、停止任务等有副作用的工具，应在执行前再次确认参数和影响。
 
-## 9. 常见问题
+## 10. 常见问题
 
 ### 安装后没有入口，或界面仍是旧版
 
@@ -171,6 +243,21 @@ OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端
 
 页面会在有限时间内结束等待，并区分命令不存在、进程退出、初始化失败或启动超时。先在终端确认命令本身可执行、软件包可信、Node/运行时版本满足要求，并检查 `cwd`、参数和环境变量；随后查看 Host 日志并点击“重新检查”。不要把本机凭据写入公开 Registry descriptor。
 
+### 为什么显示“状态未知”
+
+这表示插件没有足够证据确认健康或失败，常见于 DSH 刚重启、尚未执行健康检查，或当前 Host 无法读取 stdio 工具注册状态。点击“刷新连接器目录”或进入详情重新检查；若仍为未知，根据诊断的 `code` 和建议查看 Host 日志或升级 Host。不要把“状态未知”理解为“已连接”。
+
+### 如何按诊断代码排查
+
+| 代码示例 | 先检查什么 |
+|---|---|
+| `auth` | Token/API Key 是否过期、账号是否有目标 Server 权限；OAuth 是否需要重新授权 |
+| `refresh` | 网络、OAuth 服务状态和自动重试时间；不要立即重复授权 |
+| `dns` / `tls` / `timeout` / `http` | DNS、代理、VPN/专线、证书、IP 白名单、URL 和服务状态 |
+| `protocol` | URL 是否为兼容的 MCP Streamable HTTP 端点 |
+| `process-not-found` / `process-exit` / `startup` | 本地运行时、command/args/env/cwd、退出码和 Host 日志 |
+| `host-tools-pending` / `host-status-unavailable` | Host 是否完成工具注册、Host 版本是否支持状态读取 |
+
 ### 如何反馈问题
 
 提交 [GitHub Issue](https://github.com/duhu2000/dsh-mcp-connector/issues) 时，请提供 DSH 版本、插件版本、连接器名称、复现步骤和已脱敏的错误信息。不要附带 Token、API Key、Cookie、授权码或包含真实凭据的配置文件。