# 安装与切换指南

## 1. 三种安装方式

| 来源 | 命令 | 依赖形态（`~/.dsh/profiles/web/package.json`） |
|---|---|---|
| npm（正式） | `dsh plugin --profile web add dsh-token-monitor@latest` | `"dsh-token-monitor": "1.0.6"`（也可能是 `^1.0.6`） |
| GitHub | `dsh plugin --profile web add github:licyer/dsh-token-monitor` | `github:licyer/dsh-token-monitor` |
| **本地（开发）** | `dsh plugin --profile web add E:\VsCodeProjects\dsh-token-monitor` | `link:E:/VsCodeProjects/dsh-token-monitor` |

> 三种来源**都会自动挂载**（项目 `package.json` 声明了 `dsh.bundle.patch`，reconcile 会把它写进 `dsh.profile.bundles`）。**装完必须重启 `dsh web`**。

## 2. 先确认现在装的是哪种

- 看 `~/.dsh/profiles/web/package.json` 的 `dependencies["dsh-token-monitor"]`：`link:` = 本地挂载，`github:` = GitHub，纯版本号 = npm。
- 或在 DSH 设置页看「版本更新」行：本地挂载渠道显示"本地挂载"+ 依赖原文；npm / GitHub 显示当前版本与是否有新版。

## 3. 切换步骤（四个方向通用）

任意两种来源之间切换 = **卸载旧来源 → 安装新来源 → 重启**：

```sh
# ① 卸载旧来源（npm/GitHub 是干净的；link 来源常常删不干净，见 §5）
dsh plugin --profile web remove dsh-token-monitor

# ② 装新来源（参数见下表）
dsh plugin --profile web add <新来源>

# ③ 重启 dsh web
```

| 切换到 | `add` 的参数 |
|---|---|
| npm | `dsh-token-monitor@latest`（锁版本写 `dsh-token-monitor@1.0.6`） |
| GitHub | `github:licyer/dsh-token-monitor` |
| 本地 | 项目绝对路径，如 `E:\VsCodeProjects\dsh-token-monitor` |

**唯一要特别处理的组合**：从**本地（link）**切走时，`remove` 往往删不干净 → 按 §5 手动清理，再执行 ② ③。

## 4. 同一来源内换版本：升级 / 锁版 / 回滚

```sh
# 升级到范围内最新（用 update，别用 add —— 已装时 add 可能复用旧状态）
dsh plugin --profile web update dsh-token-monitor

# 锁版 / 回滚到指定版本（例如新版有问题，退回上一版）
dsh plugin --profile web add dsh-token-monitor@1.0.5
```

- `@latest` 依赖镜像的 `dist-tags.latest`；镜像滞后时**直接用精确版本**绕过。
- `update`（以及设置页「版本更新」行的应用内升级）会把依赖 spec **钉到具体版本**（如 `"dsh-token-monitor": "1.0.7"`），不再保留 `^x.y.z` / `latest` 形态——这是预期行为，不影响后续 `update`。
- 设置页「版本更新」行只是替你跑 `update`（npm / GitHub 渠道可用，本地挂载渠道禁用），**同样需要重启 `dsh web`** 才加载新代码。

## 5. ⚠️ link 版 remove 删不干净：彻底清理

**现象**：`dsh plugin --profile web remove dsh-token-monitor` 输出 `Already up to date`，但：

- `dependencies` 里的 `link:` 条目**可能还在**
- `node_modules` 里的 **junction 还在**
- `dsh.profile.bundles` 里的 `dsh-token-monitor` **不移出**（reconcile 认为依赖仍在、仍是 bundle）

### 清理办法一：让 reconcile 自愈（推荐）

```sh
# ① 删掉 node_modules 里的 junction（rmdir 只删链接、不删本地项目）
cmd /c "rmdir %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-token-monitor"

# ② 若 package.json 的 dependencies 里还有 link 条目，手动删掉（编辑 JSON）
#    目标状态："dependencies": {}（或只剩其他依赖）

# ③ 跑一次 dsh plugin 命令触发 reconcile —— 依赖已不在、包不可解析，
#    reconcile 会把 dsh-token-monitor 从 bundles 自动移出
dsh plugin --profile web install

# ④ 按 §7 验证三处干净
```

### 清理办法二：完全手动（reconcile 不跑时的兜底）

```sh
# ① 删 junction（同上）
cmd /c "rmdir %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-token-monitor"

# ② 编辑 %USERPROFILE%\.dsh\profiles\web\package.json：
#    - dependencies 里删掉 "dsh-token-monitor" 条目
#    - dsh.profile.bundles 里删掉 "dsh-token-monitor" 条目
#      （最终 bundles 只剩 @deepseek-ai/dsh-base、@deepseek-ai/dsh-web-app）

# ③ 可选：删掉 pnpm-lock.yaml（可能残留 link 引用）
del %USERPROFILE%\.dsh\profiles\web\pnpm-lock.yaml
```

## 6. 卸载

```sh
dsh plugin --profile web remove dsh-token-monitor
```

- npm / GitHub 渠道：命令即可删干净，按 §7 验证三处无残留，重启 `dsh web`。
- 本地（link）渠道：**必须**再走一遍 §5 的清理，否则 `dependencies` / `node_modules` / `bundles` 会留残迹。

## 7. 验证清单（切换 / 卸载 / 清理后都做）

1. **三处无残留**：
   - `%USERPROFILE%\.dsh\profiles\web\package.json`：`dependencies` 无 `dsh-token-monitor`、`dsh.profile.bundles` 无 `dsh-token-monitor`
   - `%USERPROFILE%\.dsh\profiles\web\node_modules\dsh-token-monitor`：不存在
2. **重启 `dsh web` 无报错**：不应出现 `cannot resolve profile bundle "dsh-token-monitor"` 之类的 fail-loud 错误
3. **页面无插件痕迹**：会话头部无余量徽标、主区无"用量"页签

## 8. 常见问题

**Q：装完看不到插件？**
A：确认 `dsh.profile.bundles` 里有 `dsh-token-monitor`（自动挂载成功的标志）；重启 `dsh web`。

**Q：`@latest` 装到旧版本？**
A：镜像的 `dist-tags.latest` 滞后，改用精确版本（`dsh-token-monitor@1.0.6`）或指定官方源。

**Q：切了来源但页面还是旧的？**
A：没重启。运行中的进程仍加载着上次启动时的插件代码，`dsh web` 重启后才生效。

**Q：本地挂载模式改了代码怎么生效？**
A：前端 `lib/client.js` 由 DSH 的 client-hmr 热替换（刷新页面亦可）；服务端 `lib/index.js` / `lib/util/` 需要重启 `dsh web`。确认当前是本地挂载（`dependencies` 是 `link:`）。