# 飞阳网关（FeyaGate）DSH 插件 · 使用手册

> **这个文件解决什么问题**：给你（使用者）一份按界面导航写的操作手册 —— 每个页面能看到什么、能做什么、遇到红字怎么办。想了解"为什么这么设计"请看 [`design.md`](design.md) 与 [`adr/`](adr)。

**适用版本**：插件 `0.3.1` · 后台服务 `1.2.17` – `1.2.20`（`manifest/server-manifest.json` 的兼容区间）
**用词说明**：平台账号相关一律说「**登录**」；只有许可证才说「**授权**」。你在界面里看到的词与本文一致。

> ℹ️ **本文同时是界面说明书与验收契约**。Host 侧能力（安装/升级/回滚/守护/门面/管理 API）与界面源码（[`src/client/index.tsx`](../src/client/index.tsx)）都已落地，尚未做的是**真实设备上的端到端验收与界面截图**。本文的字段名、状态词、错误码、文案与源码（`constants.ts` / `types.ts` / `settings.ts` / `config-gen.ts` / `client/index.tsx`）保持一致；两者冲突时以源码为准。

---

## 1. 从哪里进去

```
DSH 侧栏底部「设置」→ 设置面板
└── 飞阳网关                          ← 本插件唯一的入口（导航列里 order 30）
    ├── 常驻服务状态条（所有 tab 顶部都有）
    ├── [服务] [账号] [设备] [智能] [授权]
```

**默认落在服务页。** 第一次进来，你看到的应该是一个大按钮「安装后台服务」—— 在你点它之前，插件不会下载任何东西。

### 六个 tab 各自解决什么问题

| Tab | 一句话职责 | MVP 做到哪 | 什么时候来 |
|---|---|---|---|
| **服务** | 后台服务在不在、什么版本、坏在哪、怎么修 | ✅ 概览 / 安装与重装 / 升级与版本 / 端口与网络 / 日志与诊断 / 危险区 | 装服务、升级、服务挂了、改端口、看日志、卸载 |
| **账号总览** | 一屏看清哪个平台是红的 | ✅ **只读总览** | 想知道"米家登录还在不在""涂鸦试用还剩几天" |
| **平台登录** | 直接在这里把账号登进去 / 退出来 | ✅ 米家 / 涂鸦 / 美的 / 易微联 / 华为（能用到哪些由后台服务自己报） | 新装了服务要登录、换了账号、要退出登录 |
| **设备** | 设备都被看见了吗、摄像头能看吗 | ❌ 二期 | 找不到某台设备、摄像头连不上 |
| **智能** | 小智 AI / Vision AI / 触发规则 / 记忆 / 技能 | ❌ 二期 | 想让摄像头画面自动触发动作、想配视觉模型 |
| **授权** | 免费能用什么、授权解锁什么、还剩几天 | ✅ 完整 | 想知道要不要买、试用到期、要写授权码 |

> 界面上没有"跳到另一个 tab"的按钮 —— 这是 DSH 设置框架的限制（一个 section 只能拿到"关闭"）。跨页的指引一律是**可复制的文字路径**，例如 `设置 › 飞阳网关 › 授权`。

### 常驻服务状态条

所有 tab 顶部都有一条，10 秒刷新一次（页面不在前台时暂停）：

```
● 运行中 · v1.2.20 · 端口 38080 · 3/7 平台已登录 · 试用剩 12 天   [检查更新]
○ 未安装 · 尚未下载后台服务                                       [安装]
▲ 降级运行 · 华为设备控制不可用（命令通道未建立）                  查看原因
```

点「查看原因」是**展开**而不是弹窗 —— 故障原因不该用一个会消失的东西告诉你。

---

## 2. 服务 tab

### 2.1 概览（S1）

**看到什么**：状态徽标 + 版本 + 端口 + 已运行时长 + 一组健康检查行（HTTP 接口 / MCP 端点 / WebSocket / 命令通道 / 摄像头子系统 / 磁盘）+ 快捷统计（设备数、摄像头数、已登录平台、试用剩余）。

**能做什么**：启动 / 停止 / 重启服务、查看日志、打开数据目录、跳到升级页。

**常见疑问**

| 疑问 | 答案 |
|---|---|
| "端口 38080 和我配置的不一样" | 说明 38080 被占用，插件在 20 个端口内**漂移**了。真实端口以状态条和概览显示为准；漂移值写在 `state.json` 里 |
| "命令通道显示降级，但我能用米家" | 降级只影响**华为设备的控制**（华为云没有 REST 写通道，控制必须走消息中心长连接）。看得到状态、控制会失败 |
| "为什么摄像头子系统显示不可用" | 三种可能：① Windows 平台不支持（依赖米家 P2P 协议库）；② 米家没登录；③ 上游产物里缺小米专有库。界面上会写明是哪一种 |
| "远程打开设置面板，按钮全是灰的" | 后台服务只能在**运行 DSH 的那台电脑**上管理。远程浏览器里所有写操作被禁用，并会说明原因 |

**空态**：没装服务时，除 Hero 外的卡片不渲染，只有一行灰字提示"安装后台服务后，这里会显示健康检查、设备与平台统计"。

### 2.2 安装与重装（S2）

**看到什么**：五阶段进度条 —— ① 下载（带字节数 / 速度 / 预计剩余）② 校验 sha256 ③ 解压 ④ 设置文件权限 ⑤ 启动并等健康检查。

| 阶段 | 你能做什么 |
|---|---|
| 下载 | 可以**取消安装**（取消不留任何文件） |
| 校验 / 解压 / 写权限 | 不能取消（只有几秒，界面会说明"正在写入磁盘，无法取消"） |
| 启动 | 可以**取消启动**（二进制与配置保留，不用重新下载） |

**安装前请知道你要装什么**（安装向导里也有一块同样的说明）：

- **来源**：GitHub Releases `toddpan/miloco-mcp-server-releases`（不可达时自动降级到 FOTA / 镜像 / 本地包）
- **校验**：同版本 `.sha256` 比对；**校验失败会删除已下载的文件并中止**
- **许可**：专有软件，仅在本机以你的用户身份运行；本项目**不再分发**它
- **权限**：监听本地端口，可读你的智能家居账号凭据（保存在本机数据目录）
- **卸载后残留什么**：数据目录里的凭据与配置（除非你选择"卸载并清空数据"）

**三种失败情形**（界面各自有专用卡片）：

| 情形 | 你会看到 | 你可以做什么 |
|---|---|---|
| 校验失败 | `下载的文件不完整，已为你删除` + 期望/实际校验和摘要 | 重新下载、改用镜像、复制校验详情 |
| macOS 拦下未签名二进制 | `macOS 阻止了这个后台服务` + 两条放行方式 | 系统设置 › 隐私与安全性 ›「仍要打开」；或复制 `xattr -dr com.apple.quarantine <安装目录>/versions/<版本>/miloco-mcp-server` 执行后重启服务。**受 MDM 管理的公司电脑无法绕过** |
| 磁盘/权限不足 | 明确写出需要多少、可用多少 | 清理旧版本（`versions/` 下的旧目录）、复制修复命令 |

### 2.3 升级与版本（S3）

**看到什么**：当前版本与安装位置、更新通道（稳定版/测试版）、有新版本卡片（版本号 / 发布日期 / 体积 / 更新内容 / **会中断什么**）、版本历史（每行可「查看变更」「回滚到此版本」）。

**能做什么**：

- 检查更新（状态条上的按钮也能触发）。
- 立即升级。**升级前会逐条列出会中断什么**：正在执行的触发规则、正在预览的摄像头、正在跑的定时任务。数据不会丢（凭据、设备、记忆、技能都在数据目录里），失败会自动回滚。
- 回滚到历史版本（本机已有该版本时才可用；没有则需要"下载并降级"）。
- 忽略某个版本（写入"已忽略的版本"，以后还能「恢复提醒」）。

**自动行为的边界**（这一条请放心）：

- **自动检查**：默认开。只会让状态条按钮文案变化，**不会弹窗**。
- **自动下载**：默认关。
- **自动安装**：**永久关闭**。DSH 里可能正有定时任务在依赖后台服务，插件不会替你点这个按钮。
- 升级期间，AI 的工具调用会返回同一句话：`后台服务正在升级（预计还需 N 秒），升级完成后自动恢复。`

### 2.4 端口与网络（S4）

| 字段 | 默认 | 说明 |
|---|---|---|
| HTTP 端口 | `38080` | 整数 1024–65535，且必须未被占用 |
| 绑定地址 | `仅本机（127.0.0.1）` | 改成"局域网"时会出现警告（见下） |
| 门面端口 | `38081` | 只读显示。它是 DSH 与后台服务之间的本机中继；**改它需要重启 DSH** |
| 数据目录 | `~/.dsh/dsh-feyagate` | **只读显示，不可改**。它同时是设备身份与授权的锚点，换目录 = 换一份设备 ID（见第 8 节） |

> WebSocket 端口（模板默认 `8765`）由插件在生成配置时写入，**MVP 不提供界面字段**；需要改动时请在对话里让 AI 用 `config/*` 工具处理，或等二期。

**改端口需要重启后台服务才生效**，界面上的按钮就叫「保存并重启服务」。正在运行的触发规则与摄像头预览会被中断。

**选「局域网」时的警告（必须读）**：

> ⚠ 局域网内其他设备可以访问你的后台服务，且本地接口不校验身份。仅在需要手机或音箱直连时开启，并确保你的 Wi-Fi 可信。

**常见疑问**："端口被占用怎么办？" → 界面会给出**占用它的进程 PID 与名字**（例如 `端口 38080 已被占用（PID 4123，node）`），并给三个动作：换一个端口 / 复制结束进程的命令 / 结束占用进程（危险，需二次确认）。

### 2.5 日志与诊断（S5）

**看到什么**：日志区（级别、行数、关键字过滤、自动滚动）+ 自检项清单。

**能做什么**：切日志级别（详细/调试/信息/警告/错误）、按行数查看、过滤、复制全部、下载日志文件。

**自检项会告诉你**：二进制在不在且可执行、版本戳与安装记录是否一致、sha256 是否已校验、命令通道是否可用、数据目录是否可写、端口是否被占用、磁盘空间是否充足。

> 诊断包导出是**二期**功能。届时它会打包日志、版本、平台状态、端口与自检结果，并明确标注**不含账号、密码、令牌与摄像头画面**。

### 2.6 危险区（S6）

不可逆操作唯一的入口，都在这里：

| 操作 | 影响 | 确认方式 |
|---|---|---|
| 停止服务 | 设备控制与 AI 调用立即不可用；凭据与配置保留 | 单击 + 内联二次确认 |
| 卸载服务 | 删除已下载的后台服务（约 30 MB）；平台账号、设备、许可证**不动** | 必须**输入确认词**「卸载」 |
| 卸载并清空数据 | 删除数据目录全部内容：服务、配置、**所有平台凭据**、记忆、技能、快照、日志 | 先显示"将被删除的清单"，再输入确认词「清空数据」 |
| 清除全部平台凭据 | 退出全部平台登录，设备列表清空，需要重新登录 | 二次点击即可 |
| 回滚版本 | 见升级页 | 模态确认 |

**卸载前请先停服务**，否则进程仍在、端口仍被占用。命令行卸载见 [README 运维手册](../README.md#运维手册)。

---

## 3. 账号总览 tab（只读）

**看到什么**：N 个平台的卡片，每张卡上是：登录状态（`账号已登录` / `账号未登录` / `登录已过期` / `当前不可用`）、设备数、试用状态、以及一个动作（`管理` / `去登录` / `重新登录` / `查看授权`）。

**MVP 能做什么**：**看**。平台清单与免费/试用规则由服务器下发，本地不写死 —— 没同步完时显示"正在从服务器同步授权规则…"，**不会**替你断言哪个平台可用。

**登录怎么做**：去 **「平台登录」tab**（下一节）点着走，或者在对话里让 AI 调工具 —— 两条路调的是**同一批工具**。每家的详情页（Token 剩余、会话保全提示、命令通道状态）仍在二期。

**常见疑问**

| 疑问 | 答案 |
|---|---|
| "为什么平台卡片是灰的" | 服务端下发了 `enabled=false`（例如该平台的试用策略变了）。卡片会写"当前不可用，请查看授权" |
| "我的账号密码会不会被上传" | 账号密码只发送给平台官方接口，加密后传输；凭据只保存在**本机**的数据目录，可随时退出登录清除 |
| "登录已过期是什么意思" | 凭据还在，但短期令牌失效了。有些平台能**自动恢复**（界面会写"正在用已保存的凭据自动恢复会话，不需要重新登录"），恢复不了才需要你重新登录一次 |
| "华为登录为什么弹验证码，我没收到短信" | **华为不发短信**。验证码显示在你已登录的华为手机/平板弹窗里，或「设置 › 华为帐号 › 帐号安全」 |
| "验证码明明通过了却提示失败？" | 这是本插件与后台服务专门修过的问题：验证码通过、只是云端换取令牌失败时，界面会显示"验证码已通过，会话已保留，正在自动重试 —— **不需要重新输入验证码**"。只有真的验证码错误才会让你改验证码 |

---

## 3b. 平台登录 tab（图形化登录）

**看到什么**：顶部一张凭据说明卡，下面**每家平台一张卡**（米家 / 涂鸦 / 美的 / 易微联 / 华为）。卡片标题右边是登录状态标签（`已登录` / `未登录` / `状态未知`），下面一行是区域与令牌剩余。

**哪些卡片能用，由后台服务说了算。** 界面启动时问一次后台服务"你有哪些授权工具"，没有的那家会显示：

> **本构建不支持** 本机后台服务（v1.2.19）没有华为登录工具 —— 上游在 v1.2.20 才加上。升级后台服务后这张卡片会自动出现，无需升级插件。

看到这句话时不要在界面上找华为入口，去 **服务 tab** 升级后台服务（`服务 › 升级与版本`）。

| 平台 | 你要做什么 | 说明 |
|---|---|---|
| **米家** | 选区域 → 「获取授权地址」→ 在新标签页登录小米账号 → 浏览器会跳到打不开的 `https://127.0.0.1/?code=…` → **把地址栏整段复制回来**贴进输入框 → 「完成授权」 | 页面打不开是正常的（`code` 只在地址栏里）；只粘 `code` 本身也可以。区域必须与账号实际使用的区域一致，且会用**你取地址时选的区域**去完成授权 |
| **涂鸦** | 填「用户代码」（涂鸦 App：我的 → 设置 → 账号与安全 → 用户代码）→ 「生成二维码」→ 用涂鸦 App 右上角「+ / 扫一扫」扫 → 在 App 里点「确认登录」 | 不用手动点"已扫码"：界面在服务端等着（单次最长 35 秒），扫到就自动变绿；二维码过期会明确提示重新生成 |
| **美的** | 选客户端（美居 / MSmartHome）+ 账号密码 → 「登录」 | 登录成功会显示同步到多少台设备 |
| **易微联** | 国家代码（默认 `+86`）+ 邮箱/手机号 + 密码 → 「登录」 | 国家代码填错会登录失败或看不到设备；格式不对界面会先拦住 |
| **华为** | 账号密码 → 「登录」→ 若提示需要验证码，输入**显示在已登录华为设备上**的验证码 → 「提交验证码」 | **华为不发短信**，别等短信。若界面提示"验证码已通过、会话已保留"，**不要重新输验证码**，那是云端换令牌的瞬时失败，重试也不需要新码 |

**退出登录**：卡片上有「退出登录」。米家**没有**这个按钮，并写明原因 —— 上游没有暴露米家退出接口（既有实现也没有工具/路由）；要换米家账号只能等上游补上，或清掉后台服务的数据目录。

**凭据去哪了（重要）**

| 问题 | 答案 |
|---|---|
| 密码会存到插件里吗 | **不会**。账号/密码/验证码只在本机回环内转给后台服务进程，插件不落盘、不写日志、不回显；密码框提交后立刻清空 |
| 那我能在哪看到它 | 看不到 —— 这是刻意设计（[ADR-0009](adr/0009-platform-login-in-settings-page.md)）。日志 tab 里也搜不到（有自动化断言守着） |
| 那它存在哪 | 后台服务自己会把令牌（美的/易微联还包括账号口令）写进 `~/.dsh/dsh-feyagate/data/`。这一份不在插件管辖范围，但界面上不会替你隐瞒 |
| 别的网站能调这些接口吗 | 不能。登录/退出/提交验证码都是 POST，一律校验 Origin，来源不符直接 403 |

**常见疑问**

| 疑问 | 答案 |
|---|---|
| 「后台服务未运行（连接被拒绝）」 | 去 **服务 tab** 启动服务。登录接口需要子进程在场 |
| 「当前授权不允许这个平台的登录操作」 | 这是**授权**问题不是密码问题：该平台试用到期或未授权。去 **授权 tab** 看试用剩余或写授权码 —— 别反复重输密码 |
| 服务升级后多了一张卡片 | 正常。卡片跟着后台服务的**实际能力**走 |
| 华为卡片一直说"本构建不支持" | 后台服务版本 < v1.2.20。`服务 › 升级与版本` 升级后即可（插件不用升级） |

---

## 4. 授权 tab

**看到什么**：当前版本（`免费版` / `授权版`）、授权状态、到期时间、授权码（已设置/未设置）、**各平台授权状态**（`免费` / `试用中 · 剩 N 天` / `试用已到期` / `订阅已过期` / `宽限还剩 N 天` / `到期 YYYY-MM-DD`）、设备 ID。

**能做什么**：输入授权码（格式 `FG-XXXX-XXXX-XXXX`）后点「写入授权码」，设备会向云端自动激活；清除授权（恢复免费版）；复制设备 ID。

**必须理解的一条规则**：

> **读操作始终可用，写操作在试用过期后需要授权。**
> 也就是说试用到期后，你仍然可以查看设备状态、看摄像头列表；但**控制设备**需要授权或有效试用。界面在每个平台卡上都会写明这一点 —— 不会笼统地说"功能不可用"，以免你以为数据也被锁了。

**常见疑问**

| 疑问 | 答案 |
|---|---|
| "试用到期会不会自动扣费" | 不会。没有订阅扣费机制；到期就是回到免费功能范围 |
| "宽限期是什么" | 授权到期后仍有几天宽限期（云端下发），宽限期内功能照常。`宽限还剩 N 天` 就是这个意思 |
| "我换了电脑/重装了，授权还在吗" | 授权与**设备 ID**绑定，而设备 ID 锚定在数据目录。**不要**删除或移动数据目录（尤其是 `license.json` 与 `device_id.txt` 所在位置），否则会被云端当成新设备、退回免费试用 |
| "读工具和写工具分别指什么" | 读：`get_*`、`device/list`、`xiaomi/camera_list`、`stats/*`、`license/status` 等；写：`set_*`、`execute_*`、`trigger/*`、`schedule/*` 等 |

---

## 5. 状态词表（界面唯一用词）

### 5.1 服务面

| 状态词 | 含义 | 你该做什么 |
|---|---|---|
| **未安装** | 还没有下载过后台服务 | 点「安装后台服务」 |
| **下载中** | 正在拉取压缩包 | 可以取消；等待时必须能看到字节数 |
| **校验中** | 正在比对 sha256 | 等（通常不到 3 秒） |
| **安装中** | 解压 / 写权限 | 等（不可取消） |
| **已停止** | 进程不存在（PID 文件已陈旧） | 点「启动服务」 |
| **启动中** | 进程已起，健康检查还没通过 | 可以取消启动（二进制保留） |
| **运行中** | `/health` 返回 2xx 且端口可连 | 正常；可停止 / 重启 / 看日志 |
| **降级运行** | 主进程健康，但**某个子系统不可用**（华为命令通道、摄像头子系统、Vision 未配 Key） | 点「查看原因」按指引修；不影响其它平台 |
| **异常** | 进程退出 / 健康检查连续失败 / 端口冲突 | 看日志 → 重启 → 重新安装（三出口） |
| **升级中** | 正在替换二进制 | 等 10–20 秒；仅下载阶段可取消 |
| **回滚中** | 正在恢复上一个版本 | 等；结束后看橙色横幅的结论 |
| **宿主离线** | 浏览器与运行 DSH 的那台电脑断开了 | 点「立即重连」；此时写操作被禁用 |

### 5.2 平台账号面

| 状态词 | 含义 | 你该做什么 |
|---|---|---|
| **账号未登录** | 这个平台还没登录过 | 去登录（MVP：在对话里让 AI 调工具） |
| **登录中** | 等你扫码 / 等浏览器回调 / 等验证码 | 按页面说明完成那一步 |
| **账号已登录** | 可以读也可以控制（受许可证约束） | 无 |
| **登录已过期** | 凭据在但令牌失效 | 看提示：能自动恢复就等；不能就重新登录一次 |
| **登录失败** | 上次尝试返回了错误 | 看原因行；密码错误会挂在密码字段下 |
| **需要验证码** | 华为两步验证进行中 | 去华为设备弹窗取 6 位安全验证码（**不发短信**） |
| **当前不可用** | 服务端下发该平台 `enabled=false` | 查看授权页 |

### 5.3 许可证 / 设备 / 摄像头 / 长任务

| 面 | 状态词 |
|---|---|
| 许可证 | `授权版` · `免费` · `试用中 · 剩 N 天` · `试用已到期` · `订阅已过期` · `宽限还剩 N 天` · `到期 YYYY-MM-DD`（**沿用既有原文，不改字**） |
| 设备 | `在线` · `离线` · `未分配` |
| 摄像头 | `未连接` · `正在连接...` · `实时预览中` · `重连中` · `连接失败，请重试` · `设备离线` |
| 长任务 | `空闲` · `进行中` · `已完成` · `失败` · `已取消` |

---

## 6. 错误码速查表

错误码格式 `FG-<域>-<三位号>`。域的含义：`NET` 网络/下载 · `PKG` 包/校验/解压 · `PERM` 系统权限 · `PORT` 端口 · `BOOT` 启动/健康/崩溃 · `PLAT` 平台账号 · `HW` 华为专项 · `LIC` 许可证 · `HOST` DSH 宿主 · `API` 管理接口。

错误码会显示在原因行的右侧灰字里 —— **报 issue 时请把它一起复制**。

| 错误码 | 一句话含义 | 处理办法 |
|---|---|---|
| `FG-NET-001` | 连不上下载服务器（GitHub 不通） | 重试；改用镜像地址；或改用本地包离线安装。常见于代理/防火墙/企业网络策略 |
| `FG-NET-002` | 下载超时（30 秒没有数据） | 继续下载（断点续传）或重新下载；换镜像地址 |
| `FG-NET-003` | 下载被中断 | 直接从断点继续；或重新下载 |
| `FG-NET-004` | 服务器没提供校验文件 | 出于安全**不会安装**未校验的文件。重试获取校验文件，或改用镜像/本地包 |
| `FG-PKG-001` | sha256 校验不通过（文件已删除） | 重新下载通常就好（网络中断或代理缓存导致）；必要时换镜像 |
| `FG-PKG-002` | 解压失败（压缩包损坏） | 重新下载并安装；安装目录已被清理干净，不会留下半套文件 |
| `FG-PKG-004` | 安装包缺少运行库（子进程刚启动就退出） | 产物漏带了二进制声明的依赖库，错误详情里附有服务自己打印的原文（如 `dyld: Library not loaded: @executable_path/lib/libyaml-cpp.0.9.dylib`）。这是发布包的问题，换一个版本；Linux 侧按 `error while loading shared libraries` 判断。子进程在就绪前退出时插件会**立即**失败，不等满健康检查预算 |
| `FG-PKG-003` | 磁盘空间不足 | 清理旧版本（每个版本约 6–30 MB）、按界面给的路径整理数据目录所在磁盘 |
| `FG-PERM-001` | macOS 拦下未签名二进制 | 系统设置 › 隐私与安全性 ›「仍要打开」；或按界面给的 `xattr` 命令处理后重启服务。MDM 机器无法绕过 |
| `FG-PERM-002` | 安装目录不可写 | 按界面给的一行命令修目录权限。**注意：不要改安装目录**（它同时是设备身份） |
| `FG-PORT-001` | HTTP 端口被占用 | 界面会给出占用进程的 PID 与名字。换端口 / 结束占用进程 |
| `FG-PORT-002` | WebSocket 端口不可用或与 HTTP 端口相同 | 换一个端口（例如 8766），或结束旧进程 |
| `FG-BOOT-001` | 启动后 60 秒内健康检查未通过 | 看日志；换端口重试；重新安装。三类常见原因：端口冲突 / 被安全策略拦 / 依赖缺失 |
| `FG-BOOT-002` | 服务运行中崩溃 | 重启服务；查看崩溃日志；导出诊断包。界面会给退出码与最后一条日志 |
| `FG-BOOT-003` | 依赖缺失导致能力降级（缺 `libmosquitto`） | 华为设备控制不可用（状态仍可读）。按指引 `brew install mosquitto` 后**重启服务**。这是降级，不是错误 |
| `FG-PLAT-001` | 平台登录凭据过期 | 重新登录该平台。若提示"正在自动恢复"，先等它自己恢复，不要重复登录 |
| `FG-PLAT-002` | 平台账号或密码不正确 | 重新输入（密码区分大小写）。账号密码不会保存到云端 |
| `FG-PLAT-003` | 云端没有响应（45 秒无返回） | 重试；改用其他区域；检查本地网络 |
| `FG-HW-001` | 华为安全验证码错误 | 在弹窗里直接改验证码重试；或重新获取一个新的。注意华为不发短信 |
| `FG-HW-002` | 验证码已通过但云端换取令牌失败（会话已保留） | **不要重新输入验证码**。稍等自动重试；必要时点「重试」 |
| `FG-LIC-001` | 平台试用已到期 | 查看授权页：状态仍可查看，控制设备需要授权或有效试用 |
| `FG-HOST-001` | 与 DSH 宿主的连接断开 | 立即重连 / 刷新页面；期间写操作被禁用，界面状态可能已过期 |
| `FG-API-403` | 没有权限执行这个操作 | 部署把设置设为只读，或页面不是从运行 DSH 的那台电脑打开的。写操作只能在后者上进行 |

> 说明：`FG-API-403` 的编号沿用了 UX 设计文档 `E-22` 的写法，与其它"三位号"不一致（规范要求三位号）。实现时应统一为 `FG-API-403` 之外的编号或明确例外 —— 见本文末尾「待确认」。

---

## 7. 升级与回滚

### 7.1 升级后台服务（插件能做）

1. 服务 › 升级与版本 → 检查更新（状态条上的「检查更新」也行）。
2. 有新版本时先看清三件事：**会中断什么**（逐条列出）、**数据会不会丢**（不会）、**失败了怎么办**（自动回滚）。
3. 点「立即升级」。过程五阶段：下载 → 校验 → 备份 → 替换二进制 → 重启并等健康检查（约 10–20 秒，期间后台服务不可用）。
4. **只有下载阶段可以取消**。取消后旧版本继续运行，等于什么都没发生。进入替换阶段后按钮会禁用并说明原因。

**升级失败会怎样**：自动回滚到上一个健康版本，服务恢复成升级前的样子，服务页顶部留一条**常驻橙色横幅**（不会用 4 秒 toast 糊弄你），给出「重试升级 / 查看失败日志 / 保留旧版本并忽略此版本」。

**断电了会怎样**：下次启动时插件发现上次激活没有确认成功，**自动回滚**到上一个健康版本。这就是"版本目录不可变 + 指针 + pending 标记"三件套的作用。

### 7.2 回滚 / 降级（两个不同的词）

| 词 | 含义 | 快慢 |
|---|---|---|
| **回滚** | 用**本机已有的**版本目录恢复 | 约 15 秒，不需要网络 |
| **下载并降级** | 重新下载一个历史版本的安装包再装 | 1–3 分钟，需要网络 |

版本历史里每行都有「回滚到此版本」（本机有该版本时）。确认框会告诉你：会停服务、替换二进制、重启，约 15 秒，**设备与平台凭据不受影响**。

> 如果新版本迁移过数据格式，降级前界面会拦截并提示可能丢失最近几天的记录，建议先备份。

### 7.3 升级插件本身（插件不能做）

插件的包版本升级必须**重启 DSH 进程**才生效（框架限制：JS 代码换代不能热替换）。所以 MVP 只做"检测到新版本 + 提示 + 给你一条可复制的命令"：

```bash
dsh plugin --profile <profile> add @dsh-external/dsh-feyagate-gateway@<version>
```

在 Desktop 壳里这件事交给壳处理。**升级插件 ≠ 升级后台服务**：前者要重启 DSH，后者不用。

---

## 8. 数据与隐私

### 8.1 哪些数据在本机、在哪个目录

安装根目录默认 `~/.dsh/dsh-feyagate`（设了 `$DSH_HOME` 就是 `$DSH_HOME/dsh-feyagate`）：

| 路径 | 里面是什么 | 敏感度 |
|---|---|---|
| `state.json` | 插件的账本：当前版本、上次健康版本、pending、端口 | 低（端口与版本号） |
| `config.yaml` | 后台服务的配置（端口、绑定地址、Vision Key、触发规则等）。**必须留在根目录**：它的目录就是设备身份 | **中—高**：Vision 的 API Key 明文在里面（文件权限 `0600`） |
| `data/`（含子目录与各 `*_token.json`） | 平台凭据与业务数据：小米/涂鸦/美的/易微联/华为 token、`license.json`、`device_id.txt`、记忆、技能、快照、Token 用量 | **高**：含登录凭据 |
| `logs/server.log` | 后台服务 stdout/stderr + 插件日志 | 中（可能含设备名、路径、错误堆栈） |
| `versions/<版本>/` | 可执行文件与它自带的库 | 低（就是那个二进制） |
| `cache/` | 下载的压缩包与解压暂存 | 低 |
| `current` | 一行版本号 | 低 |

**为什么 `config.yaml` 和 `data/` 是兄弟目录，而且都不能挪**：后台服务把它自己的所有相对路径（`license_file`、每个 `*_token_file`、`memory.data_dir`、`skill.*_dir`）按 `config.yaml` 所在目录展开，并且用同一个目录存放 `device_id.txt` 与 `token_usage.json`。也就是说 —— **`config.yaml` 所在的那个目录就是设备身份**。移动或重建它 = 换了设备身份 = 云端把你当新设备 = 退回免费试用。同理，也不要从别的机器上拷贝 `license.json` / `device_id.txt` 过来。要备份，就**整个根目录一起备**。

### 8.2 哪些数据会发到云端

插件本身**只**做三件联网的事：

1. 下载后台服务的产物（GitHub Releases / FOTA / 你配置的镜像）；
2. 检查后台服务与插件自身的新版本；
3. 在你点「写入授权码」时把授权码与设备 ID 发给许可证服务（`https://www.feyagate.com/api/v1/device`），用于激活与心跳。

**你的智能家居数据由后台服务直接与各平台云交互**（小米/涂鸦/美的/易微联/华为/Home Assistant），不经过本插件。哪些数据会离开本机，取决于你在各平台侧的功能与平台自身的策略：设备状态与控制命令必然要经过平台云（华为的控制命令走消息中心长连接）；摄像头画面通过米家 P2P 拉取到本机，**只有在你自己启用 Vision AI 并主动提问时**才会把抽帧发给**你自己配置的**模型服务（`vision.base_url`）。

### 8.3 DSH 的 credentials 与插件凭据

DSH 的 `credentials` 只用于**插件自己**的外部服务凭据（例如你配置的镜像源认证）。**平台账号凭据不走 DSH credentials** —— 它们由后台服务保存在本机数据目录里，权限 `0600`。

### 8.4 出错信息里的隐私

错误详情与（二期的）诊断包**都不包含**账号、密码、令牌与摄像头画面；日志里的本机用户名会被替换成 `~`。诊断包会明确列出包含什么、不含什么。

### 8.5 卸载前请备份

卸载并清空数据**不可恢复**。界面会先显示"将被删除的清单"（几个平台凭据、多少条记忆、多少个技能、多少张快照、日志多大），并要求你输入确认词。想留数据只想删二进制，选「卸载服务」而不是「卸载并清空数据」。

---

## 9. 已定案与待确认

**已定案（无需再拍板）**：

1. **数据位置**：`config.yaml` 在安装根目录，`data/` 是它的兄弟 —— 见第 8.1 节与 [`adr/0003`](adr/0003-generated-config.md)。这是实现拍板的，不是待定项。
2. **安装目录不可改**：它不是设置项，因为它同时是设备身份。

**待拍板**：

1. **`FG-API-403` 的编号**：与"三位号"规范不一致（UX 设计文档 `E-22` 的原文如此），需要统一为三位号或明确例外。
2. **WebSocket 端口（默认 8765）在 MVP 是否暴露给用户编辑**：MVP 里由插件生成、不在界面暴露。
3. **绑定地址开关是否在 MVP 就暴露**：若暴露，必须同时保留第 2.4 节那段局域网警告。
4. **界面截图**：本文里的截图位是占位符（本仓库不含图片文件）；发布前需要补真实截图或明确不放。