# 安装与验证

> 面向「已经装好 DSH、想把这个面板跑起来」的人。**每一步都给了判据** —— 没有判据的步骤等于没写。
> 前置：DSH 能正常起（`dsh web` 能打开），Node.js 与插件 `engines.node` 相容（`>=22.19`）。

## 一、安装

### 方式 A · 本地目录（推荐）

1. 把本仓库放到一个**长期不变**的路径（插件按路径装载，挪位置后要重装）。
2. 侧栏 **插件** → **添加插件** → 粘贴该目录的**绝对路径** → **安装**。
3. **判据**：侧栏「插件」列表里出现本组合包；`profiles/<profile>/package.json` 的 `dsh.profile.bundles` 出现本包。

CLI 等价物（`<本仓库>` = 该目录绝对路径）：

```sh
dsh plugin --profile web add "<本仓库>"
```

### 方式 B · 从 GitHub 源安装

```sh
dsh plugin --profile web add github:yiyunet/dsh-mcp-client-manager
```

> 本包**没有 `prepare` / 构建脚本**，因此不会触发"批准构建脚本"那一关。
> ⚠️ 该路径**未经实测**（取决于你的包管理器与 `dsh plugin` 对 git 说明符的解析）；失败请回方式 A。

### 装完要不要重启

本 profile `patchReload: live`，bundles 变化在 HMR 监听范围内 → **通常不需要重启**。

- **判据**：打开 设置 → 侧栏，出现「MCP 客户端」。
- 没出现 → 重启一次宿主（`dsh web`）再看。仍没出现 → 看宿主日志里 `[mcp-client-manager]` 开头的行。

## 二、验证（10 步，逐条有判据）

| # | 动作 | 判据 |
|---|---|---|
| 1 | 打开 设置 → 侧栏 | 出现「MCP 客户端」 |
| 2 | 打开面板 | 列出你手写的 MCP 行（来源=手写，服务名下注「原手写行」）；状态为 **已启用** 或 `已启用 · 未发现工具` |
| 3 | 添加一条 `streamable-http` 行 → 保存 | `$DSH_HOME/cordis.patch.yml` 被创建/更新；列表出现 `mcpx-*`；该服务器工具挂载后可用 |
| 4 | 添加一条 `stdio` 行（command / args / env）→ 保存 | 同上；**env 的值落盘但不回显**（只显示键名与"已设置"） |
| 5 | 改一条手写行的 url → 保存 | 来源列变「手写 + 已覆盖」；`profiles/<profile>/cordis.patch.yml` **末尾**多出一条顶层 `- id: … / config: …` 覆盖行；新值立刻生效 |
| 6 | 再改同一行一次 | 覆盖行**原地更新**，不新增第二条 |
| 7 | 点该行「撤销覆盖」 | 覆盖行消失，值回到 `insert` 行原值；来源列恢复「手写」 |
| 8 | 禁用 / 启用手写行 | profile patch 里出现/更新 `disabled` 覆盖 |
| 9 | 删除一条受管行 | 自有层文件里该行消失、工具消失（手写行**没有**删除按钮） |
| 10 | 漂移演练：手工编辑 `$DSH_HOME/cordis.patch.yml` | 面板**转只读**，并给出两个逃生口（以清单为准重建 / 以文件为准清空清单） |

### 只读核对命令

```sh
# ⚠️ 输出包含密钥（url / env），别外传
dsh --profile web --dump-config
```

**判据**：输出里能看到 `@deepseek-ai/dsh-mcp-client` 的行，且受管行的 id 以 `mcpx-` 开头。

### 不需要 DSH 的机器自检

```sh
node --check plugin-src/host/index.mjs
node --check plugin-src/host/store.mjs
node --check plugin-src/host/validate.mjs
node --check plugin-src/host/adapter.mjs
node --check plugin-src/client/client.js
node --test test/validate.test.mjs test/store.test.mjs test/host-smoke.mjs
node scripts/verify-package.mjs
```

> ⚠️ **必须点明测试文件**：Node 24 下 `node --test test` 会把 `test` 当模块加载并报 `MODULE_NOT_FOUND`。
> `host-smoke.mjs` 会造一个**假宿主**（临时目录当 `DSH_HOME`），真跑一遍读写路径，
> 并断言**密钥绝不出现在回传给浏览器的载荷里**。

## 三、卸载

GUI：侧栏 **插件** → 找到本组合包 → **卸载**。

CLI：

```sh
dsh plugin --profile web remove "@yiyunet/dsh-mcp-client-manager"
Remove-Item "$env:USERPROFILE\.dsh\cordis.patch.yml"       # 受管层（手写行不受影响）
Remove-Item -Recurse "$env:USERPROFILE\.dsh\mcp-manager"   # 受管数据（可选）
```

> **卸载不会**动你在 profile patch 里手写的那两行，也**不会**撤销面板追加过的覆盖行；
> 想回到"面板从没来过"的状态，先逐行点「撤销覆盖」，再卸载。

## 四、装不上 / 用不了时的排查树

| 症状 | 先看这里 |
|---|---|
| 设置里没有「MCP 客户端」 | ① 本包是否真在 `dsh.profile.bundles`；② 重启宿主后再看；③ 宿主日志有 `[mcp-client-manager]` 行吗（`RPC 已注册 / 未注册`） |
| 面板在，但点任何按钮都报错 | 多半是 `connection` 服务没就绪（非 web 平面跑不起来）；看日志里的 `RPC 未注册` 原因 |
| 面板显示「工具探测返回 0」 | 服务器都没连上，**或**本面板取不到宿主工具表；两者现象相同 —— 先看宿主日志 |
| 保存后没反应 | 面板顶部是否为只读（漂移）？只读时保存会被明确拒绝并给处置按钮 |
| 改了 `insert` 行但值没变 | 该行已被面板覆盖 —— 先点「撤销覆盖」（见 [架构与写回模型.md](架构与写回模型.md) §4） |