dsh-mcp-connector 0.2.32 → 0.2.34

package/CHANGELOG.md

@@ -4,6 +4,50 @@
 
 ## [Unreleased]
 
+## [0.2.34] - 2026-09-04
+
+### Added
+
+- 用户自建连接可对 RFC1918 IPv4 / RFC4193 IPv6 ULA 字面量显式授权明文 HTTP；默认仍拒绝，公网 HTTP、域名、链路本地与元数据地址不受该开关影响。
+
+### Fixed
+
+- OAuth 一键连接现在标记资源发现、服务发现、回调监听、客户端注册、授权回调和 Token 换取阶段；DCR HTTP 403 会明确说明服务商客户端准入限制，不再误导为用户授权或凭据问题。
+- OAuth 在动态客户端注册等浏览器打开前的阶段失败时，会立即关闭本机回调监听，避免遗留端口与超时任务。
+
+## [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
@@ -494,7 +538,10 @@
 - 外部 URL 与导入 Header 执行安全校验。
 - iframe 消息校验同源和消息来源。
 
-[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.31...HEAD
+[Unreleased]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.34...HEAD
+[0.2.34]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.33...v0.2.34
+[0.2.33]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.32...v0.2.33
+[0.2.32]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.31...v0.2.32
 [0.2.31]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.30...v0.2.31
 [0.2.30]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.29...v0.2.30
 [0.2.29]: https://github.com/duhu2000/dsh-mcp-connector/compare/v0.2.28...v0.2.29

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.34`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.34](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.34).
 
 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,17 @@ 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.
-- External URLs must use HTTPS; HTTP is allowed only for loopback development.
+- Unchecked or Host-unobservable connections are reported as `unknown`, never as healthy. Health history and last-success timestamps are currently process-local.
+- External URLs use HTTPS by default, and HTTP is allowed for loopback development. A user-created connection may explicitly opt in to plaintext HTTP for literal RFC1918 IPv4 or RFC4193 IPv6 ULA addresses; hostnames, public HTTP, link-local addresses, and cloud metadata addresses remain blocked.
 - 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.
+- OAuth failures identify resource discovery, server discovery, client registration, browser callback, or token exchange. A DCR HTTP 403 is reported as provider-side client admission rejection rather than a missing user authorization.
+- 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.34`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.34](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.34)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。
@@ -157,13 +179,18 @@ 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/网络错误会分类提示。
-- 外部 URL 仅允许 HTTPS，HTTP 仅允许回环地址；导入配置会校验 URL 与 Header。
+- 未检查或 Host 状态不可见时显示“状态未知”，不会冒充健康；健康摘要与最近成功时间当前只保留在插件进程内。
+- 外部 URL 默认仅允许 HTTPS，HTTP 默认仅允许回环地址。用户自建连接可在明确风险确认后放行 RFC1918 IPv4 / RFC4193 IPv6 ULA 字面量；域名、公网 HTTP、链路本地与云元数据地址仍拒绝。
 - 远程目录/描述响应限制 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、状态输出或日志。
+- OAuth 连接失败会标明资源发现、服务发现、客户端注册、授权回调或 Token 换取阶段；DCR HTTP 403 表示服务商拒绝未准入客户端，不是用户未点击授权。
+- 脱敏导出把 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 的权限或审批链。