# 使用指南

[项目首页](../README.md) · [English](usage.en.md)

## 运行要求

- 本机 dsh **0.2.0-rc.2**，Node.js **22+**。未来 dsh 版本以 CI/兼容验证为准。
- 本机 Web/CLI 的插件安装命令需要可用的 `pnpm`（10+）；Desktop 使用其自带的插件管理运行环境。
- Python **3.10+**，包含 `venv` / `pip`。准备环境需要连接 Python 包镜像。
- 已登录、具有目标模型使用权限的 **Trae CN / TRAE SOLO CN** 账号。
- Windows 10/11；Linux/macOS 提供同一安装流程与生命周期实现，实际支持范围以 CI 为准。
- 此版面向本机 Desktop / Web；不支持在远程浏览器打开 Host 回环地址的完整控制台。中国版协议，不承诺国际版兼容。

模型名称与额度由 TRAE 决定；账号没有 V4.1 Flash 权限时会返回上游错误，插件不会把请求悄悄改成其他模型。

## 首次配置

1. 首次打开 **TRAE 控制台** 会显示服务设置，点 **准备环境**。找不到 Python 时填写可执行文件完整路径；端口留空自动选择。首次下载可能需要几分钟。
2. 点 **启动服务**。
3. 选择实际登录的 **TRAE SOLO CN** 或 **Trae CN**，点 **导入当前桌面账号**。非标准安装可填写 `User` 数据目录（其下有 `globalStorage/storage.json`）。导入仅在点击时发生，源文件保持只读。
4. 点 **返回控制台**，原有控制台的概览、账号、消费、轮询与模型测试页面均保留。在其中的 **DSH 模型管理** 点 **接入 dsh 模型菜单**。
5. 在对话输入框原生模型菜单选择 TRAE CN 下任一显示的模型，并选择它支持的思考强度。管理显示/隐藏仍在控制台中完成。顶部 **刷新控制台** 重新加载内嵌页面，**新窗口打开** 可在浏览器使用同一完整控制台。

网页授权助手从已授权的控制台下载，自动指向本实例，仅携带 15 分钟有效的一次账号提交授权；过期后重新下载。Windows 的 `start_auth.bat` 需与下载的 `web_login.py` 放在同一目录。使用助手会在本机启动上游的 OAuth 回调监听器；桌面导入不需要助手。

导入新账号会将其选为当前账号；禁用旧账号可阻止其参与模型请求。已有账号额度轮询等高级策略由完整控制台的设置决定。

### 开启签到与账号轮询

1. **多账号**：在 **账号与签到** 添加账号，按需切换当前账号或保存各账号的模型开关。模型调用开关与签到管理分开，禁用模型调用不会删除账号。
2. **自动签到**：在同页的 **自动签到** 开启定时签到、设置北京时间并点 **保存**；可用 **立即执行** 手动签到，查看上次执行、下次执行和结果。
3. **账号轮询**：在 **轮询与设置 → 多账号轮询** 开启轮询，选择 **顺序轮询** 或 **积分优先**，再点 **保存轮询设置**。积分优先使用已缓存的剩余积分排序，可先在账号页刷新积分。

### 更多模型和显示设置

导入、切换账号或接入模型时会自动读取一次模型目录；成功登录不会因为目录读取失败而撤销，读取失败时会提示并保留旧列表。

登录后在原有控制台的 **DSH 模型管理** 点 **发现 / 刷新可用模型**。插件读取当前账号返回的真实模型配置，并逐个显示可选思考档位：`light → Low`、`high → High`、`extra_high → Xhigh`。例如上游只给 Low/High 的模型不会出现 Xhigh；没有公布思考档位的模型使用上游默认行为。目录读取不发送推理请求，不做逐模型扣费测试；实际调用仍受账号权限、额度和上游可用性限制。

勾选 **显示到 dsh** 可接入或隐藏单个模型；也可搜索、显示全部或隐藏全部。已接入时立即通过 dsh 官方 Settings API 同步。隐藏会从 dsh 提供的模型目录中移除模型，仍使用它的会话需要先切换模型。隐藏全部会暂时移除本插件的供应商目录，重新显示任一模型可恢复。其他供应商和已保存默认值保持原样。

显示偏好与最新成功读取的目录会持久保存，刷新失败不清空旧列表；上游暂时未返回的模型，其隐藏偏好仍保留。切换账号后请重新刷新目录。V4.1 Flash 在该账号目录存在时优先排列；混合非思考模型或档位不兼容时不强加统一 High 默认值，各模型使用其上游默认，用户可以在对话菜单选择实际支持的档位。

## 数据与权限

默认目录：`$DSH_HOME/plugins/dsh-trae-relay`；未设置 DSH_HOME 时在用户主目录 `.dsh/plugins/dsh-trae-relay`。
用 `DSH_TRAE_RELAY_HOME` 为不同 dsh 实例指定不同目录。不要让两个 Host 共享一个插件运行目录。

- `config.json`：端口、插件 API key、是否接入模型。
- `venv/`：独立 Python 环境。
- `engine/data/accounts.json`、`engine/.env`：代理自己的账号副本与设置。
- `relay.log`：本地错误日志。日志和账号文件不属于发布包，请勿上传。

Windows 初始化移除数据目录继承权限，仅授予当前用户与 SYSTEM；POSIX 私有目录/配置使用 0700/0600。
代理仅监听 `127.0.0.1`，模型请求需要 API key。控制台使用一次性入口交换 HttpOnly 会话，拒绝跨站写请求与非回环 Host；API key 不放在控制台地址中。

**接入模型**创建插件自己的 `DSH_TRAE_RELAY_API_KEY` credential 引用，并通过 dsh 官方 Settings API 只写入 `llm-pi-ai.providers.trae-relay`。使用配置 revision 防止覆盖并发编辑，保留其他供应商和全局默认模型。断开仅删除这个归属本插件的供应商字段，保留账号与 credential 便于再次接入。启动/退出不会重写模型配置；禁用或卸载前请先断开，避免留下指向已停止服务的供应商。

## 卸载与恢复

### 从旧包升级

项目及 GitHub 仓库现名为 **Trae2api-dsh**，安装包名为 `trae2api-dsh`，通过 GitHub Release 分发。如果已安装旧包 `dsh-trae-relay`：

1. 在旧插件控制台断开 dsh 模型接入、停止服务，然后移除旧插件；保留其数据目录。
2. 完整退出 dsh 后，通过插件管理器安装新的 `trae2api-dsh.tgz`，再启用插件。
3. 插件沿用原有账号、环境与显示偏好，重新接入模型菜单即可。

不要同时启用新旧两个包。数据目录仍为 `.dsh/plugins/dsh-trae-relay`，`DSH_TRAE_RELAY_HOME`、`DSH_TRAE_RELAY_API_KEY` 和 `trae-relay` provider 标识保持兼容，不需要手动重命名这些配置。GitHub 旧仓库地址保留重定向；新版 Release 同时提供旧文件名的兼容下载。

### 卸载与重新准备

先停止服务/断开模型，再在插件管理器卸载。本插件不自动删除账号文件，避免卸载造成数据丢失。
要彻底清理，完整退出 dsh 后手动删除上述插件数据目录，并在 dsh credential 管理中移除 `DSH_TRAE_RELAY_API_KEY`。
重新安装可沿用插件数据；插件更新会刷新自己的 Python runner 文件，保留虚拟环境、账号和显示偏好。上游依赖/环境版本变化需要点 **重新准备环境**，准备前先停止服务并断开模型。准备时保留账号和设置。

端口冲突会明确报错，不接管其他正在运行的反代；停止本插件后指定空闲端口并重新准备即可。
Python 下载失败可调整你自己的 pip 镜像或网络后重试。插件不更改系统代理、系统 Python 或全局 Git 设置。

## 相关说明

[使用边界与免责声明](../DISCLAIMER.md) · [第三方说明](../THIRD_PARTY_NOTICES.md)