# 安装 / 卸载 / 故障恢复

## 前置条件

- 已安装 DeepSeek Harness —— **桌面端客户端**，或命令行启动的 CLI profile（`dsh web`）
- 已安装 [pnpm](https://pnpm.io/)（`dsh plugin` 与插件页的安装框都依赖它）
- 拥有 ChatGPT Plus / Pro 订阅（或包含 Codex 额度的套餐）

## 安装

### 方式一：在 DSH 插件页添加（推荐；桌面端唯一方式）

打开 DSH 的 **插件 → 添加插件**，在「包名或地址」里填：

```
https://github.com/SONGOAO25/dsh-chatgpt-subscription
```

包就在仓库根目录，`lib/` 已入库，所以填地址安装**不跑构建、不会弹「待批准的构建脚本」**，装完即用。同一个框也接受：

- 本仓库工作副本的绝对路径 —— 用于开发（会产生 `link:` 安装）。

**本插件不发布 npm 包**：那一栏填包名 `dsh-chatgpt-subscription` 只会报「未找到相关插件」，请始终填上面的仓库地址。

**桌面端客户端只能用这条**：DSH 的 `desktop` profile 由客户端自己管理，命令行 `dsh plugin --profile desktop ...` 会被直接拒绝（`profile "desktop" is managed exclusively by the Electron application`）。

### 方式二：命令行 `dsh plugin`

用你实际启动的 profile（`dsh web` 启动的是 `web`）：

```bash
# 跟随仓库默认分支（不跑构建，lib/ 已入库）
dsh plugin --profile web add https://github.com/SONGOAO25/dsh-chatgpt-subscription
```

命令行同样没有包名可填——本插件不发布 npm 包，填包名只会报「未找到相关插件」。

`desktop` 被保留给桌面端客户端——CLI 会直接拒绝这个 profile，不会替你安装。

### 方式三：一键脚本（产生 `link:` 安装）

```bash
git clone https://github.com/SONGOAO25/dsh-chatgpt-subscription.git
cd dsh-chatgpt-subscription
./install.sh
# 默认安装到 web profile；其他 profile：
./install.sh --profile <profile名>
```

脚本会先重建一次 `lib/`（`lib/` 已入库，这一步只是保证跑起来的代码与 `src/` 一致），再执行 `dsh plugin --profile <name> add <仓库根>`。`link:` 安装跟随你的工作副本而不是 npm。

### 安装原理

`dsh plugin add`（以及插件页的安装框）会：

1. 用 pnpm 把插件包安装到 profile 目录（`~/.dsh/profiles/<name>/`）；
2. 检测到包声明了 `dsh.bundle`（仓库根的 `cordis.patch.yml`），自动把包名加入 profile 的 bundle 层列表（`dsh.profile.bundles`）；
3. 下次启动 `dsh` 时，插件随 profile 自动加载——host 注册 OAuth 流程与 RPC、client 在插件详情页提供「ChatGPT 订阅」配置。

**注意：安装后需要重启 DSH 才会生效**——宿主进程在启动时组合插件。刷新页面不足以加载 host 端。

**为什么 git 地址安装不需要构建**：`lib/` 是入库的构建产物，仓库根就是一个开箱即用的插件包。

pnpm 对 git 依赖会执行包里的 `prepare` 脚本，且默认拦下要求批准（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`）。本包不声明 `prepare` / `prepack`（`package.json` 里只有 `prepublishOnly`，仅在本仓库自己执行发布时才跑），所以填 GitHub 地址是**零构建、零授权**的。

### 验证安装成功

```bash
dsh --profile web --dump-config | grep dsh-chatgpt-subscription
# 应看到 dsh-chatgpt-subscription 行（bundle 层已生效）
```

重启后，在 DSH **插件** 页能看到 **ChatGPT 订阅** 即安装成功。（桌面端客户端没有可用的 `dsh --profile` 命令，直接在插件页确认即可。）

## 绑定 ChatGPT 订阅

1. 打开 DSH **插件** 页 → 进入 **ChatGPT 订阅**。
2. 点「**绑定 ChatGPT 账号**」→ 浏览器打开 OpenAI 官方授权页。
3. 用 ChatGPT 账号登录并同意；插件页显示「已连接」即完成。
4. 新建对话，在模型切换器选择提供商 **ChatGPT** 的模型（如 `gpt-5.6-terra`）对话。

> 若浏览器未自动打开，请允许 DSH 弹窗（页面会以 `window.open` 兜底）。
> 绑定后模型切换器出现 ChatGPT 提供商；对话消耗订阅额度。

## 更新

| 你的安装方式 | 更新命令 |
|---|---|
| 仓库地址（插件页或命令行） | 再执行一次同样的地址安装（插件页重填同一个地址），然后重启 DSH |
| `link:`（一键脚本或本地代码） | 见下方三步 |

`link:` 安装更新时要**三步一起做**：拉代码 → 切到默认分支 → 重新构建：

```bash
cd dsh-chatgpt-subscription
git fetch origin && git checkout main && git merge --ff-only origin/main
node scripts/build.mjs
# 重启 DSH
```

- **别只用 `git pull`**：本地开发分支从没推到远端时它会直接失败（`no such ref was fetched`）；而且 `link:` 安装加载的是构建产物 `lib/`，只拉代码不重建，重启后跑的还是旧代码。
- 三条命令都是 `--ff-only` / 非破坏性的：工作区不干净或分支上有本地提交时，git 会拒绝执行，而不是覆盖你的改动。
- **更新不会自动发生**：本插件不提供自动更新；磁盘上的一切改动都要等你执行命令之后才发生。
- 本插件不发布 npm 包，所以更新也只能走仓库地址或本地副本这两条路。

## 卸载

桌面端客户端：在 **插件** 页里卸载。命令行：

```bash
cd dsh-chatgpt-subscription
./uninstall.sh
# 或手动：
dsh plugin --profile web remove dsh-chatgpt-subscription
```

卸载会清理：profile 插件条目、`llm-pi-ai.providers.openai-codex` 路由配置、`OPENAI_CODEX_API_KEY` 凭据、绑定标记目录。**保留** `~/.codex/auth.json`（codex CLI 自己的登录态）。重启后模型切换器的 ChatGPT 提供商自动消失。

## 与联网搜索的关系

插件**不管理联网搜索**：不会把 ChatGPT 订阅令牌当作搜索服务凭据，也不会读取、删除、记录或改写任何搜索配置（如 `DEEPSEEK_API_KEY`、`EXA_API_KEY`）。

搜索商（`searchProvider`，如 `deepseek-official` / `exa`）完全由用户在 DSH 的 profile 配置层自行指定；本插件无论绑定与否、处于哪个模型模式，都不触碰搜索设置。若未配置任何可用搜索商，`web_search` 会按 DSH 自身的规则明确失败，这与本插件无关。

## 故障排查

| 现象 | 原因与处理 |
|---|---|
| 插件详情里没有配置页 | ① 没重启：需重启 DSH；② 装错 profile：确认启动用的 profile 与安装目标一致；③ `dsh --profile web --dump-config` 里没有 dsh-chatgpt-subscription：重新执行安装 |
| 插件页或命令行报「未找到相关插件」 | 输入的是包名。本插件不发布 npm 包，请改填仓库地址 `https://github.com/SONGOAO25/dsh-chatgpt-subscription` |
| 插件页报「这个包没有声明组合包」 | 装到的是一个「仓库根不是包」的仓库。本仓库根目录一直是包；请确认填的是本仓库，并用包含最新提交的地址 |
| 插件页提示「有依赖的安装脚本需要你允许」/「待批准的构建脚本」 | 装到的清单里声明了 `prepare` / `prepack`（本仓库当前清单没有，只有 `prepublishOnly`）。用最新提交的仓库地址重装；确实需要放行时，按提示把 pnpm 打印的那一行加进 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 再重试 |
| 命令行报 `profile "desktop" is managed exclusively by the Electron application` | 桌面端客户端的 profile 不能用 CLI 改：请在客户端 **插件 → 添加插件** 里安装/卸载 |
| 点绑定没反应/浏览器没打开 | ① 检查是否允许 DSH 弹窗；② 重启 DSH 后再试 |
| 提示「回调端口被占用」 | 端口 1455 被其他程序占用（如正在运行的 codex 登录流程），关闭占用程序后重试 |
| 授权超时（5 分钟） | 重新点「绑定 ChatGPT 账号」再试；确认浏览器完成了授权 |
| 绑定后模型切换器无 ChatGPT | 确认绑定成功（插件页显示「已连接」）；重启 DSH 让路由注册生效 |
| 对话报错/模型不可用 | 可用模型以套餐为准（如 `gpt-5.3-codex-spark` 需更高计划）；检查订阅额度 |
| 安装报 `pnpm not found` / 「没有找到 pnpm」 | 安装 pnpm：`npm i -g pnpm` 或 `corepack enable` |
| 想彻底移除插件影响 | 卸载 + 重启 DSH |

## 与其他插件的关系

- **[Bottom Info Bar](https://github.com/SONGOAO25/dsh-bottom-info-bar)**：信息栏插件只读本插件维护的令牌，在底部信息栏显示 ChatGPT 额度（5 小时/周/月窗口与重置时间）。两者可独立安装；信息栏的 ChatGPT 额度显示需要本插件先绑定。