dsh-mcp-connector 0.2.16 → 0.2.17

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ## [Unreleased]
 
+## [0.2.17] - 2026-08-24
+
+### Documentation
+
+- 新增面向下载用户的完整使用手册，覆盖安装/升级与重启、市场分类、鉴权状态、自定义 HTTP/stdio、JSON 导入、连接管理、安全边界和常见故障。
+- 使用当前 14 张市场卡片与 6 张推荐位的实机界面重采 4 张公开截图，并重建 16 秒演示 GIF；同步链接 Registry 的第三方连接器上架指南。
+
 ## [0.2.16] - 2026-08-24
 
 ### Changed

package/README.en.md

@@ -8,6 +8,8 @@ Browse and install MCP connectors from different providers in DeepSeek Harness D
 
 [简体中文](README.md)
 
+[Chinese user guide](docs/USER-GUIDE.md) · [Connector onboarding](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md) · [Issues](https://github.com/duhu2000/dsh-mcp-connector/issues)
+
 [![CI](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-mcp-connector.svg)](https://www.npmjs.com/package/dsh-mcp-connector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -38,7 +40,7 @@ The first four bundled cards are Qichacha connectors, followed by PKULaw and Win
 | Tool discovery, descriptions, and scrolling | JSON import |
 | ![Tool discovery](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/screenshots/03-tool-discovery.jpg) | ![JSON import](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/screenshots/04-json-import.jpg) |
 
-The assets are captured from the credential-free local UI harness. See [`docs/screenshots/README.md`](docs/screenshots/README.md) for provenance.
+The assets are captured from a local DSH `web` acceptance environment and show only public marketplace metadata, example prompts, and tool descriptions. They contain no credentials, local paths, or query results. See [`docs/screenshots/README.md`](docs/screenshots/README.md) for provenance.
 
 ## Installation
 
@@ -54,7 +56,7 @@ Or use the installer:
 bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/install.sh)
 ```
 
-Fully quit and restart DeepSeek Harness Desktop after installation or upgrade.
+Run the same command again to upgrade. Fully quit and restart DeepSeek Harness Desktop after installation or upgrade. For `dsh web`, stop the original process before starting it again; `EADDRINUSE 127.0.0.1:3080` means another instance is already listening.
 
 ## Usage
 
@@ -65,6 +67,8 @@ Fully quit and restart DeepSeek Harness Desktop after installation or upgrade.
 
 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.
+
 ## Connector catalog
 
 The package contains a bundled fallback catalog. By default, it refreshes from the public [dsh-mcp-connector-registry](https://github.com/duhu2000/dsh-mcp-connector-registry); cached or bundled data remains available if the remote registry cannot be reached.
@@ -101,7 +105,7 @@ npm run dev:ui
 
 `npm run check` performs syntax checks, automated tests, and an npm package allowlist/sensitive-content audit. `npm run market:check` tracks the external DSH marketplace PR and live directory. Tags matching `v*` trigger GitHub Actions; the tag must match `package.json`. npm releases use Trusted Publishing through GitHub OIDC and do not require a long-lived `NPM_TOKEN`.
 
-The current public version is [`dsh-mcp-connector@0.2.16`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.16](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.16).
+The current public version is [`dsh-mcp-connector@0.2.17`](https://www.npmjs.com/package/dsh-mcp-connector), with [GitHub Release v0.2.17](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.17).
 
 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

@@ -8,6 +8,8 @@
 
 [English](README.en.md)
 
+[用户手册](docs/USER-GUIDE.md) · [第三方连接器上架指南](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md) · [问题反馈](https://github.com/duhu2000/dsh-mcp-connector/issues)
+
 [![CI](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-mcp-connector/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-mcp-connector.svg)](https://www.npmjs.com/package/dsh-mcp-connector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -40,7 +42,7 @@
 | 工具发现、描述与独立滚动 | JSON 导入 |
 | ![工具发现](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/screenshots/03-tool-discovery.jpg) | ![JSON 导入](https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/docs/screenshots/04-json-import.jpg) |
 
-素材由无真实凭据的本地 UI harness 生成，详见 [`docs/screenshots/README.md`](docs/screenshots/README.md)。
+素材从本机 DSH `web` 验收环境采集，只展示公开市场元数据、示例 Prompt 和工具说明，不包含凭据、本机路径或查询结果。详见 [`docs/screenshots/README.md`](docs/screenshots/README.md)。
 
 ## 安装
 
@@ -56,7 +58,7 @@ dsh plugin --profile web add dsh-mcp-connector
 bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/install.sh)
 ```
 
-安装或升级后需完全退出并重启 DeepSeek Harness Desktop。
+重复执行安装命令即可升级。安装或升级后需完全退出并重启 DeepSeek Harness Desktop；使用 `dsh web` 时需先停止原进程再启动，`EADDRINUSE 127.0.0.1:3080` 表示已有实例正在运行。
 
 ## 使用
 
@@ -67,6 +69,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/m
 
 连接成功后，工具按 `mcp__<serverName>__*` 前缀提供给模型。
 
+分类浏览、四种鉴权状态、自定义 HTTP/stdio、JSON 导入、连接管理与故障排查见完整的[用户手册](docs/USER-GUIDE.md)。
+
 ## 配置
 
 Bundle 默认配置位于 `cordis.patch.yml`：
@@ -96,12 +100,13 @@ npm run dev:ui
 
 `check` 执行语法检查、自动测试和 npm 发布包白名单校验；`market:check` 检查外部 DSH 市场 PR 与线上目录；`dev:ui` 启动不含真实凭据的本地 mock 市场。CI 使用 `--legacy-peer-deps` 安装显式测试依赖，DSH 运行期 peer 仍由 Host 提供。`v*` Tag 会触发 GitHub Actions；Tag 必须与 `package.json` 版本一致。Release 通过 npm Trusted Publishing (GitHub OIDC) 发布，不依赖长期 `NPM_TOKEN`。
 
-当前公开版本为 [`dsh-mcp-connector@0.2.16`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.16](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.16)。
+当前公开版本为 [`dsh-mcp-connector@0.2.17`](https://www.npmjs.com/package/dsh-mcp-connector)，对应 [GitHub Release v0.2.17](https://github.com/duhu2000/dsh-mcp-connector/releases/tag/v0.2.17)。
 
 版本能力与变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 Desktop 发版回归见 [docs/DESKTOP-E2E.md](docs/DESKTOP-E2E.md)。
 市场卡片、公共 registry 与 OAuth 一键授权要求见 [docs/MARKET-REGISTRATION.md](docs/MARKET-REGISTRATION.md)。
 stdio 传输的架构、透传边界与安全约束见 [docs/STDIO-SUPPORT.md](docs/STDIO-SUPPORT.md)。
+第三方服务商提交市场卡片请阅读 Registry 的[第三方连接器上架指南](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)，无需修改插件代码或等待插件重新发布 npm。
 
 ## 安全与限制
 

package/docs/USER-GUIDE.md

@@ -0,0 +1,168 @@
+# MCP连接器用户手册
+
+本手册面向安装和使用 `dsh-mcp-connector` 的 DeepSeek Harness（DSH）用户。服务商或 MCP 原作者如需提交市场卡片，请改看独立 Registry 的[第三方连接器上架指南](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)。
+
+## 1. 安装、升级与重启
+
+要求：DSH Desktop 或 `web` profile，Node.js 20 或更高版本。
+
+```bash
+dsh plugin --profile web add dsh-mcp-connector
+```
+
+也可以运行一键安装脚本：
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-mcp-connector/main/install.sh)
+```
+
+重复执行同一安装命令即可升级。安装或升级后必须让 DSH **完全退出并重新启动**，仅刷新浏览器页面不足以替换已经加载的插件代码。
+
+- DSH Desktop：退出应用后重新打开。
+- `dsh web`：停止原进程，再运行 `dsh web`。
+- 浏览器访问：默认打开 `http://127.0.0.1:3080`。
+
+如果重新运行 `dsh web` 出现 `EADDRINUSE 127.0.0.1:3080`，说明已有 DSH 进程正在监听 3080 端口，并不表示插件安装失败。可以直接打开现有页面；若确实要重启，先在原终端停止进程，或用下面的只读命令确认监听者，再正常结束对应 PID：
+
+```bash
+lsof -nP -iTCP:3080 -sTCP:LISTEN
+kill <PID>
+dsh web
+```
+
+不要同时启动两个 `dsh web` 实例。
+
+## 2. 打开 MCP连接器
+
+重启后，在 DSH 左侧主导航点击“🧩 MCP连接器”。入口通常位于“新会话”下方、工作区/会话列表上方；如果当前 DSH 版本没有对应的公开插槽，入口会回退到左侧底部。
+
+页面顶部提供：
+
+- **市场**：浏览内置目录与远程 Registry 合并后的公开连接器，页签徽标显示当前卡片数。
+- **已安装**：查看已经保存到本机的连接，页签徽标显示连接数。
+- **搜索**：按名称、服务商、简介和标签查找。
+- **添加连接**：导入 JSON、手动配置 HTTP/stdio，或从市场描述 URL 安装。
+- **刷新**：重新拉取目录，并更新连接健康状态。
+
+## 3. 浏览市场与分类
+
+默认选择“全部”，页面按以下顺序分章节展示：推荐、企业数据、金融投资、法律合规、开发工具、办公协作、调研分析、设计创意、效率工具、其他。
+
+- 推荐位固定为 6 张精选卡片；其他卡片仍会出现在各自业务分类中。
+- 每个章节先展示最多 4 张卡片；数量更多时可点击“查看全部”，再点击“收起”。
+- 点击某个分类标签后，只展示该分类的全部卡片。
+- 分类栏固定在页面 Header 内，滚动卡片时不会遮挡内容；切换到“已安装”后自动隐藏。
+- 远程目录不可用时，插件会继续使用上次缓存或随包内置目录，不影响已有连接。
+
+## 4. 连接市场卡片
+
+卡片右侧按钮会根据鉴权方式和当前状态变化：
+
+| 按钮/状态 | 含义 | 操作 |
+|---|---|---|
+| `连接` | OAuth 或免密连接器尚未连接 | 点击后按页面提示完成授权或连通性检查 |
+| `配置` | 需要 Bearer Token 或 API Key | 录入服务商签发的凭据并验证 |
+| `需重新授权` | OAuth 授权过期、被撤销或不可用 | 点击后重新完成 OAuth 授权 |
+| `已配置` | 本机已有配置，尚未完成本轮健康确认 | 点击“刷新”或进入详情检查 |
+| `已连接` | 最近一次健康检查通过 | 可直接在会话中使用对应 MCP 工具 |
+| `部分异常` / `连接异常` | 一个或多个 Server 未通过检查 | 打开详情查看提示，核对网络、权限和服务状态 |
+
+Bearer/API Key 连接器会先执行 MCP `initialize` 验证。所有 Server 通过后，凭据才会保存并出现在“已安装”中；验证失败不会写入新凭据。
+
+OAuth 一键连接要求服务商支持标准 OAuth 2.1/PKCE 和公开元数据发现。插件不会要求用户把 OAuth Token 复制到聊天中。
+
+## 5. 查看详情、Prompt 与工具
+
+点击卡片或“详情”可打开连接器详情：
+
+1. 阅读服务说明、鉴权方式、数据范围与可能产生的费用或副作用。
+2. 在“试试这样用”中选择示例 Prompt；带变量的模板会先要求补齐查询主体等信息。
+3. 展开“工具详情”查看 Server 数量、工具名称与描述，并可搜索工具。
+4. 点击“去试试”或 Prompt 的发送按钮，在当前工作区创建或复用空白会话并写入草稿。
+
+连接成功后，工具按 `mcp__<serverName>__*` 前缀提供给模型。工具清单来自服务端，实际数量会随服务商权限和版本变化。
+
+## 6. 添加自定义连接
+
+点击“＋ 添加连接”后有三种方式。
+
+### 6.1 导入 `mcpServers` JSON
+
+支持 Streamable HTTP、历史 `sse` 配置和 stdio。历史 `sse` 会自动归一为 Streamable HTTP。
+
+```json
+{
+  "mcpServers": {
+    "my-http-server": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
+      }
+    },
+    "my-local-server": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@vendor/example-mcp-server"],
+      "env": {
+        "EXAMPLE_MODE": "readonly"
+      }
+    }
+  }
+}
+```
+
+导入前请把示例占位符替换为自己的值。凭据只应在本机导入，不要把含真实 Token、API Key、密码或 Cookie 的 JSON 提交到 Git、Issue 或聊天。
+
+### 6.2 手动配置
+
+- **HTTP**：填写名称、HTTPS MCP URL、可选 Header 和传输方式。
+- **stdio**：填写本机命令、参数、环境变量和可选工作目录。
+
+stdio 进程由 `@deepseek-ai/dsh-mcp-client` 管理，插件只透传 `command`、`args`、`env`、`cwd`。stdio 会以当前用户权限启动本机进程，只运行你信任的软件包和命令。
+
+### 6.3 市场卡片 URL
+
+填写一个公开的 HTTPS Connector Descriptor URL。描述文件只能携带公开元数据，不应包含任何凭据；安装后仍由用户在本机完成 OAuth 或录入 Key。
+
+## 7. 管理已安装连接
+
+在“已安装”中可以：
+
+- 查看连接状态和 Server 数量；
+- 启用或停用连接；
+- 重新授权 OAuth，或重新录入 Token/API Key；
+- 执行健康检查；
+- 断开连接并删除该连接的本机配置。
+
+OAuth 断开时，插件会尽力调用服务商的撤销端点；无撤销端点时仍会删除 DSH 本机授权记录。连接状态发生变化后，可点击“刷新”重新检查。
+
+## 8. 安全边界
+
+- 凭据仅保存在 DSH storage domain，不进入市场目录、Git 仓库或对话历史。
+- 外部 HTTP 地址必须使用 HTTPS；仅本机回环开发地址允许 HTTP。
+- Registry 健康探针不持有用户凭据，也绝不会执行目录里的 stdio 命令。
+- 连接器能看到的数据和能执行的操作取决于你授予的账户权限；优先使用最小权限 Token/API Key。
+- 生成、付费、写入、发布、删除、停止任务等有副作用的工具，应在执行前再次确认参数和影响。
+
+## 9. 常见问题
+
+### 安装后没有入口，或界面仍是旧版
+
+确认安装目标是 `web` profile，然后完全退出并重启 DSH。浏览器强制刷新只能刷新静态页面，不能替换仍在运行的旧插件进程。
+
+### 市场里没有最新卡片
+
+点击“刷新”。如果远程 Registry 暂时不可用，页面会继续显示缓存或内置目录；稍后恢复网络再刷新即可。
+
+### Token/API Key 一直验证失败
+
+核对凭据是否过期、是否具备目标 MCP Server 权限、Header 类型是否正确，以及服务商是否要求单独开通或付费。失败的候选凭据不会覆盖本机原有可用配置。
+
+### stdio 启动失败
+
+先在终端确认命令本身可执行、软件包可信、Node/运行时版本满足要求，并检查 `cwd` 和环境变量。不要把本机凭据写入公开 Registry descriptor。
+
+### 如何反馈问题
+
+提交 [GitHub Issue](https://github.com/duhu2000/dsh-mcp-connector/issues) 时，请提供 DSH 版本、插件版本、连接器名称、复现步骤和已脱敏的错误信息。不要附带 Token、API Key、Cookie、授权码或包含真实凭据的配置文件。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mcp-connector",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "General-purpose MCP connector, connection manager, plugin extension, and integration marketplace for DeepSeek Harness, initiated and maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -20,6 +20,7 @@
     "docs/DESKTOP-E2E.md",
     "docs/MARKET-REGISTRATION.md",
     "docs/STDIO-SUPPORT.md",
+    "docs/USER-GUIDE.md",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",