# remote ssh 实现方案（PLAN）

重要：这份文档只使用与第一次构建。迭代后没有更新。已经不适用。作为历史文档保留

## 1. 目标与范围

### 1.1 产品目标
- 提供可在 `Web`、`小程序`、`iOS Hybrid(App)` 使用的 SSH 连接终端。
- iOS 端支持原生 SSH 能力，连接后在终端内一键进入 Codex 工作流（`cd <项目目录>` + `codex`）。
- 支持多服务器管理、认证方式管理、最近连接日志、主题定制、中文输入。
- 支持插件扩展能力（参考 Obsidian），允许用户按规范在 `~/.remoteconn/plugins` 增加功能。

### 1.2 本期范围（MVP + 可扩展）
- 必做（MVP）：
  - SSH 连接建立与交互（密码 + 私钥）。
  - 服务器配置增删改查。
  - xterm.js 终端渲染与基础设置（字体/字号/配色）。
  - “Codex 模式”一键执行。
  - 最近连接记录与会话日志。
  - iOS 原生 SSH 插件接入。
- 二期：
  - 证书认证（OpenSSH certificate）。
  - 小程序网关高可用、审计、限流。
  - 高级主题编辑（背景自动对比优化、导入导出主题）。
  - 插件系统（本地插件加载、插件 API、权限沙箱、插件市场/导入导出）。

### 1.3 非目标（当前不做）
- 远程文件管理器（SFTP UI）。
- 多人协作会话（共享同一终端）。
- 本地离线执行（必须依赖远程 SSH 主机）。

## 2. 核心技术选型

### 2.1 前端与终端
- `Vue 3 + TypeScript`：统一 UI 与状态逻辑。
- `xterm.js`：终端渲染核心。
- 建议配套插件：
  - `xterm-addon-fit`：自适应布局。
  - `xterm-addon-webgl`：性能优化（可降级 canvas）。
  - `xterm-addon-search`：日志检索。
  - `xterm-addon-unicode11`：中文宽字符兼容。

### 2.2 多端容器
- Web：Vite 构建 SPA。
- iOS：`Capacitor` + 原生 Swift SSH 插件。
- 小程序：使用 `WSS SSH Gateway`（小程序无法直接发起原始 TCP SSH，需网关中转）。

### 2.3 SSH 实现策略
- iOS：原生 SSH 客户端能力（Swift 封装 libssh2 或 SwiftNIO SSH，先做 POC 选型）。
- Web/小程序：统一走 `WSS Gateway -> SSH Server`。
- 统一抽象 `TerminalTransport` 接口，屏蔽底层差异。

## 3. 总体架构

### 3.1 分层设计
- `UI 层`：连接页、服务器管理页、终端页、设置页。
- `应用层`：连接状态机、命令编排（Codex 模式）、日志服务、主题服务。
- `传输层`：
  - iOS：Native SSH Channel。
  - Web/小程序：WebSocket Channel（对接 SSH 网关）。
- `存储层`：
  - 配置数据：本地数据库（IndexedDB/SQLite）。
  - 密钥与密码：系统安全存储（iOS Keychain / Web 安全策略）。

### 3.2 关键模块
- `server-profile`：服务器配置 CRUD、分组、最近使用时间。
- `auth-manager`：密码/私钥/证书认证参数组织与安全存取。
- `session-manager`：连接生命周期（连接、重连、断开、心跳）。
- `terminal-engine`：xterm 绑定、输入输出转发、编码处理。
- `codex-orchestrator`：登录后自动执行项目目录切换与 `codex` 启动。
- `logbook`：最近任务和会话日志归档、检索。
- `theme-engine`：字体、字号、配色、背景对比度计算。
- `plugin-runtime`：插件发现、校验、生命周期、错误隔离。
- `plugin-api`：命令注册、会话事件、UI 扩展、插件存储。
- `plugin-security`：权限模型、沙箱执行、风控策略。

## 4. 详细功能方案

### 4.1 多服务器管理（增删改查）
- 数据模型建议：
  - `ServerProfile`: `id`, `name`, `host`, `port`, `username`, `authType`, `projectPresets[]`, `tags[]`, `lastConnectedAt`。
  - `CredentialRef`: `id`, `type(password/key/cert)`, `secureStoreKey`, `createdAt`, `updatedAt`。
- 交互要点：
  - 新建时连通性检测（可选）。
  - 列表支持搜索/排序（最近连接优先）。
  - 删除前二次确认，避免误删凭据引用。

### 4.2 认证方式
- 支持：
  - 密码认证。
  - 私钥认证（含 passphrase）。
  - 证书认证（二期）。
- 安全要求：
  - 凭据不落明文文件。
  - iOS 使用 Keychain；Web 使用受限存储并提示风险。
  - 首次连接需主机指纹确认（known_hosts 机制）。

### 4.3 终端交互与中文支持
- 输入处理：
  - 开启 xterm 中文宽字符能力（Unicode11）。
  - 验证拼音输入法、中文标点、组合键（Ctrl/Cmd）兼容性。
- 输出处理：
  - ANSI 颜色、光标控制、清屏、大输出滚动性能。
  - 终端尺寸变化（横竖屏切换）触发远端 `pty resize`。

### 4.4 Codex 模式
- 入口：终端页主按钮 “Codex 模式”。
- 执行流程：
  1. SSH 连接成功后读取用户预设项目路径（支持从 `~` 下候选目录选择）。
  2. 发送 `cd <path>`（路径安全转义）。
  3. 发送 `command -v codex` 检测。
  4. 若存在则发送 `codex` 并进入交互；否则提示安装指引。
- 容错逻辑：
  - `cd` 失败时给出“目录不存在/权限不足”提示。
  - `codex` 异常退出时记录退出码并允许一键重试。

### 4.5 最近连接任务日志
- 日志结构：
  - `SessionLog`: `sessionId`, `serverId`, `startAt`, `endAt`, `status`, `commandMarkers[]`, `error`。
- 展示策略：
  - 最近 50 条摘要，详情按需加载。
  - 支持按服务器过滤。
  - 提供导出文本（脱敏）。

### 4.6 主题与界面自定义
- 可配置项：
  - 字体、字号、行高、光标样式。
  - 终端配色（16 色/扩展色关键字段）。
  - UI 外观：背景色、文本色、强调色、按钮色；UI 与 Shell 独立配色域，互不干扰。
  - 背景自动对比：根据前景色计算最佳对比背景（WCAG 对比度优先，`pickBestBackground`）。
  - 按钮色自动推导：`pickBtnColor(bg, text)` 在背景与文字之间线性插值（t=0.72，偏文本侧），切换预设或自动优化背景时联动更新。
  - SVG 图标按钮通过 CSS `mask-image` + `background-color: var(--btn)` 统一随按钮色变化。
- 设置即时生效：
  - 所有设置项调整后立即应用（CSS 变量实时写入 `document.documentElement`）。
  - 变更后 400ms 防抖自动持久化到 IndexedDB，**无需手动点击保存**。
  - 刷新页面后从 DB 恢复，初始化阶段通过 `initialized` 标志位防止预设联动 watcher 覆盖已保存的自定义值。
- 默认策略：
  - 首次使用加载"tide"主题，`uiBtnColor` 由 `pickBtnColor` 自动推导（默认 `#adb9cd`）。
  - 用户主题本地持久化（IndexedDB），支持重置默认。

## 5. 跨平台实现路径

### 5.1 Web
- 通过网关建立 WSS 会话，浏览器仅负责终端渲染与输入转发。
- 重点处理浏览器断网重连、页面切后台心跳恢复。

### 5.2 iOS（Hybrid）
- Capacitor 提供 WebView 容器和插件桥接。
- 原生插件职责：
  - 建立 SSH 会话（认证/pty/shell/channel）。
  - 读写流双向桥接到 JS。
  - 连接状态、错误码、重连事件上报。
- JS 层职责：
  - 页面逻辑、xterm 渲染、Codex 编排。

### 5.3 小程序
- 通过 `WSS Gateway` 访问 SSH。
- 网关最小能力：
  - 鉴权（token/session）。
  - 连接到目标 SSH 主机并建立 channel。
  - 双向转发终端数据帧。
  - 会话超时与限流控制。

## 6. 网关服务设计（Web/小程序共用）

### 6.1 协议建议
- WebSocket 消息类型：
  - `init`：目标主机、端口、用户名、认证引用。
  - `stdin`：用户输入。
  - `stdout`：远端输出。
  - `resize`：终端尺寸变化。
  - `control`：心跳、断开、错误。

### 6.2 安全与合规
- 强制 WSS。
- 不在网关长期保存明文凭据。
- 审计日志仅记录元信息（不记录完整命令正文，避免敏感泄露）。
- 增加 IP/账号级限流和失败次数保护。

### 6.3 兼容性
- 目标兼容：
  - OpenSSH（主流版本）。
  - Dropbear。
  - Bitvise。
  - Windows OpenSSH。
- 通过算法协商与回退策略处理差异（KEX、HostKey、Cipher）。

## 7. 里程碑与迭代计划

### M1：脚手架与基础架构（1 周）
- 交付：
  - Vue3 + TS + xterm.js 基础工程。
  - 统一 `TerminalTransport` 接口。
  - 页面骨架（连接/终端/设置）。
- 验收：
  - 本地可打开终端页并完成假数据输入回显。

### M2：服务器管理与本地存储（1 周）
- 交付：
  - ServerProfile CRUD。
  - 凭据引用模型与安全存储接口。
- 验收：
  - 可新增/编辑/删除服务器并持久化。

### M3：iOS 原生 SSH 插件 POC（1-2 周）
- 交付：
  - 建立真实 SSH 连接并完成收发。
  - 错误码映射与状态事件回传。
- 验收：
  - iOS 真机成功连接 Linux 主机并执行命令。

### M4：网关服务 MVP（1-2 周）
- 交付：
  - WSS -> SSH 双向通道。
  - 基础鉴权、心跳、断开处理。
- 验收：
  - Web 可通过网关连接并稳定交互 30 分钟。

### M5：Codex 模式与日志（1 周）
- 交付：
  - 一键进入 Codex 编排流程。
  - 最近连接/任务日志列表与详情。
- 验收：
  - 单击按钮后可自动 `cd` 并进入 `codex`。

### M6：主题、中文输入与兼容性完善（1 周）
- 交付：
  - 主题系统 + 自动对比背景。
  - 中文输入兼容修复与回归。
  - SSH 服务端兼容性测试报告。
- 验收：
  - 在目标服务端矩阵中通过率达到约定阈值（建议 >= 95%）。

### M7：插件系统 MVP（1-2 周）
- 交付：
  - 插件目录扫描与 `manifest.json` 校验。
  - `main.js` 生命周期加载（`onload`/`onunload`）与 `styles.css` 注入。
  - 插件 API（命令注册、会话事件、插件私有存储）。
  - 插件启停管理页（启用/禁用/失败日志）。
- 验收：
  - 手工放入一个符合规范的插件后可成功加载并注册命令。
  - 单插件崩溃不会影响 SSH 主链路与终端会话。

## 8. 测试与质量保障

### 8.1 测试分层
- 单元测试：
  - 状态机、命令编排、主题对比度算法、日志序列化。
- 集成测试：
  - Transport 层收发、断线重连、resize。
- 端到端测试：
  - 真机 iOS + Web + 小程序核心链路。

### 8.2 兼容矩阵
- 服务端维度：OpenSSH / Dropbear / Bitvise / Windows OpenSSH。
- 认证维度：密码 / 私钥 / 证书（二期）。
- 终端维度：中文输入、复制粘贴、快捷键、长日志滚动。

### 8.3 验收标准（DoD）
- 核心流程通过：
  - 配置服务器 -> 连接 -> 终端交互 -> Codex 模式 -> 断开 -> 日志可查。
- 崩溃率、连接失败率、重连成功率达到设定阈值。
- 安全检查通过（凭据保护、主机指纹校验、传输加密）。

## 9. 风险与应对

### 9.1 小程序网络限制风险
- 风险：不能直接 SSH TCP。
- 应对：网关中转作为必选架构，提前做容量与延迟评估。

### 9.2 SSH 库兼容性风险（iOS）
- 风险：不同算法和服务端实现差异导致连接失败。
- 应对：M3 做双库 POC，保留切换空间；建立兼容性回归集。

### 9.3 凭据安全风险
- 风险：本地泄露或日志误记敏感信息。
- 应对：安全存储 + 脱敏日志 + 最小权限 + 定期安全审计。

### 9.4 Codex 可用性风险
- 风险：远端未安装 codex 或 PATH 异常。
- 应对：启动前检测并给出安装与修复指引。

### 9.5 插件安全与稳定性风险
- 风险：第三方插件读取敏感数据、阻塞主线程或污染全局样式。
- 应对：权限模型 + 沙箱执行 + 运行时超时熔断 + 样式作用域隔离 + 默认禁用高危权限。

## 10. 实施顺序建议（小步迭代）
- 第一步：先打通单平台（iOS 或 Web）端到端连接链路。
- 第二步：抽象共用层（状态机、命令编排、主题、日志）。
- 第三步：接入第二平台并复用核心模块。
- 第四步：补齐小程序网关与兼容性验证。
- 第五步：做稳定性、性能与安全收敛后再扩展证书认证。

## 11. 需要产品/团队尽快确认的决策
- 小程序目标平台范围（微信/支付宝/字节）及对应发布优先级。
- iOS SSH 库最终选型标准（许可证、性能、维护活跃度）。
- 日志保留周期与隐私策略（是否允许命令内容落盘）。
- Codex 模式默认工作目录来源（手选/记忆上次/项目列表同步）。
- 插件发布策略（仅本地安装/官方市场/私有市场）与审核机制。
- 插件权限默认策略（安装即授权 or 首次调用时授权）。
- Web 与 iOS 端插件目录映射策略（是否支持跨端同步）。

## 12. UI 详细设计（MVP 可落地）

### 12.1 设计目标
- 让用户在 3 步内完成连接：选服务器 -> 认证 -> 进入终端。
- 终端页优先级最高，减少非必要干扰。
- 支持 Web、iOS、小程序统一体验，交互模型一致，视觉密度按端适配。

### 12.2 视觉方向
- 风格关键词：液态、通透、流动、层次感、高可读。
- 视觉语言：`液态渐变背景 + 玻璃卡片 + 软阴影`，以“可视层级”替代“重边框”。
- 字体建议：`Outfit`（UI）+ `JetBrains Mono`（终端与日志）。
- 圆角：容器 `20px`，卡片 `14px`，输入框 `10px`，标签 `999px`。
- 动效：按钮反馈 `180ms`，抽屉/弹窗 `240ms`，背景流体动画 `8-20s` 可配置。
- 移动端策略：优先保证单手操作区，关键按钮放置在拇指热区（屏幕下半部分）。

### 12.3 设计令牌（Design Tokens）
- `--bg: #192b4d`（主背景，随 `uiBgColor` 实时更新）
- `--surface: rgba(20,32,56,0.64)`（液态面板）
- `--surface-border: rgba(118,156,213,0.2)`（卡片边框）
- `--text: #e6f0ff`（主文本，随 `uiTextColor` 实时更新）
- `--muted: #9cb1cf`（次文本）
- `--accent: #5bd2ff`（主强调色，随 `uiAccentColor` 实时更新）
- `--btn: #adb9cd`（按钮/图标色，随 `uiBtnColor` 实时更新；SVG 图标通过 `mask + background-color: var(--btn)` 染色）
- `--success: #79f3bd`
- `--danger: #ff7f92`

### 12.4 信息架构
- 一级导航：`连接`、`终端`、`日志`、`设置`。
- Web/iPad：左侧导航 + 右侧内容区。
- 手机/小程序：底部 Tab + 顶部标题栏。
- 全局入口：`+ 新建服务器`、全局搜索、连接状态指示器。

### 12.5 页面级设计

#### 12.5.1 连接页（服务器列表）
- 顶部区：搜索框、筛选（标签/认证类型）、排序（最近连接优先）。
- 内容区：服务器卡片列表，显示名称、`user@host:port`、认证类型、最近连接时间、标签。
- 卡片操作：`连接`（主按钮）、`编辑`、`更多`（复制/删除）。
- 快速入口：支持 `新建服务器`，默认生成草稿并自动定位到配置表单。
- 空状态：引导文案 + `新建第一台服务器`。
- 错误状态：网络错误、凭据失效、网关不可达，均提供 `重试`。

#### 12.5.2 新建/编辑服务器页
- 字段分组：基础信息、认证、Codex 预设、高级选项。
- 必填项：名称、主机、端口、用户名、认证类型。
- 认证区：密码/私钥二选一；私钥支持 passphrase。
- 高级项：连接超时、心跳间隔、启动后默认目录。
- 易用性：按认证类型动态展示字段，隐藏无关输入，减少误填。
- 底部固定操作栏：`测试连接`、`保存`。
- 校验策略：失焦即时校验 + 保存前全量校验。

#### 12.5.3 终端页（核心）
- 顶部工具栏：会话名、延迟指示、重连、复制、清屏、字体缩放、设置。
- 主区：xterm 终端占满可视区，支持横竖屏与窗口 resize。
- 侧边抽屉（Web）/底部抽屉（移动端）：会话信息、快捷命令、日志标记。
- 主按钮：`Codex 模式`，首次点击弹出确认说明。
- 断线态：覆盖层提示 + `自动重连中` + `手动重连`。
- 预览联动：设置页调整字体、行高、主题后，终端区实时预览变化。

#### 12.5.4 日志页
- 列表项字段：服务器名、开始/结束时间、状态、耗时、错误摘要。
- 过滤器：服务器、状态、时间范围。
- 详情页：时间线展示关键事件（连接、认证、Codex 启动、断开）。
- 操作：`导出脱敏文本`。

#### 12.5.5 设置页
- 分区：用户界面（UI 外观）、Shell（终端显示 + 缓冲）、连接策略、日志。
- 外观项：主题预设（切换自动联动颜色）、背景色、文本色、强调色、按钮色（自动推导，可手动覆盖）。
- Shell 项：字体、字号、行高、光标样式、宽字符支持、终端缓冲阈值。
- 连接策略：自动重连、重连上限、主机指纹策略、凭据记忆策略、超时参数、服务器预填值。
- 日志项：保留天数、日志脱敏。
- **即时生效**：所有项更改后立即反映到 UI（CSS 变量实时写入根节点），400ms 防抖后自动写入 IndexedDB，无手动保存按钮。
- 自动优化背景：`pickBestBackground` 推导最优背景色，同时联动更新 `uiBtnColor`（`pickBtnColor`）。

### 12.6 关键组件规范
- `ServerCard`：高度 `88px`，主信息左对齐，主按钮固定右侧。
- `ConnectButton`：默认 `连接`，加载态 `连接中...`，失败态 `重试`。
- `AuthTypeSegment`：密码/私钥分段选择，切换保留已输入内容。
- `TerminalToolbar`：图标按钮最小点击区 `40x40`。
- `HostKeyConfirmModal`：显示指纹、算法、首次发现时间；按钮 `信任并继续` / `取消`。
- `ThemePresetSelect`：切换后同步更新颜色、透明度、模糊参数，支持用户再微调。
- `ConfigTabs`：固定五分组（基础/认证/终端/液态主题/安全），避免长表单滚动疲劳。

### 12.7 关键交互流程（连接与 Codex）
1. 用户在连接页点击目标服务器 `连接`。
2. 前端进入 `connecting` 状态，展示进度并允许取消。
3. 若为首次连接，弹出主机指纹确认弹窗。
4. 认证成功后进入终端并自动执行 `fit`。
5. 顶部出现 `Codex 模式` 入口。
6. 用户点击后依次执行 `cd <path>`、`command -v codex`、`codex`。
7. 任一步失败时，在终端输出可读错误，并配合 toast 提示。

### 12.8 状态机与反馈规范
- 会话状态：`idle`、`connecting`、`auth_pending`、`connected`、`reconnecting`、`disconnected`、`error`。
- 状态反馈：每个状态具备统一颜色、提示文案、按钮可用性规则。
- 消息反馈：信息 `3s` 自动消失，警告 `5s`，错误默认需手动关闭。

### 12.9 响应式布局规则
- `>=1280`：三栏（导航/列表/详情）。
- `768-1279`：两栏（导航/内容）。
- `<768`：单栏 + 底部 Tab。
- 终端最小可用区：宽 `320px`、高 `220px`。

### 12.10 可用性与无障碍
- 文本与关键 UI 对比度满足 WCAG AA。
- 关键操作支持键盘可达与焦点可视化。
- 错误提示需定位到字段级，不仅显示“操作失败”。
- 配置面板「实时生效 + 自动保存」（400ms 防抖写 IndexedDB，刷新不丢失）；对比度满足 WCAG AA。

### 12.11 配置能力清单（MVP 必备）
- 服务器配置：名称、主机、端口、用户名、标签、项目目录、超时、心跳。
- 认证配置：密码、私钥、证书；按类型动态展示所需字段。
- 终端配置：字体、字号、行高、光标、Unicode11、自动重连。
- 主题配置：预设主题、背景/文本/强调/按钮色自定义（按钮色自动推导）、自动优化背景。所有项实时生效，自动持久化。
- 安全配置：主机指纹策略、日志保留时长、日志脱敏、凭据记忆策略。

## 13. 插件系统实现方案（参考 Obsidian）

### 13.1 目标与边界
- 目标：
  - 让用户通过本地目录增加插件，不改主程序即可扩展功能。
  - 插件覆盖命令扩展、会话事件处理、轻量 UI 扩展、样式增强。
  - 插件失败可隔离，不能拖垮核心 SSH 链路。
- 非目标（MVP 不做）：
  - 插件可执行任意系统命令。
  - 插件直接访问凭据明文（密码、私钥内容）。
  - 复杂插件依赖解析（如 npm 依赖在线安装）。

### 13.2 目录与文件规范
- 默认根目录：`~/.remoteconn`。
- 插件目录：`~/.remoteconn/plugins/<plugin-id>/`。
- 每个插件最少三个文件：
  - `manifest.json`
  - `main.js`
  - `styles.css`
- 推荐目录结构：
  - `~/.remoteconn/plugins/<plugin-id>/data.json`（插件私有配置，可选）
  - `~/.remoteconn/plugins/<plugin-id>/README.md`（插件说明，可选）
- 约束：
  - `<plugin-id>` 只能包含小写字母、数字、短横线，正则：`^[a-z0-9][a-z0-9-]{1,62}$`。
  - 不允许符号链接跳出插件目录（防止路径穿越）。

### 13.3 manifest.json 规范（MVP）
- 必填字段：
  - `id`: 插件唯一标识，必须与目录名一致。
  - `name`: 插件展示名。
  - `version`: 语义化版本（SemVer）。
  - `minAppVersion`: 最低主程序版本。
  - `description`: 简介。
  - `entry`: 入口文件，固定 `main.js`。
  - `style`: 样式文件，固定 `styles.css`。
  - `permissions`: 权限数组。
- 可选字段：
  - `author`、`homepage`、`keywords`、`mobileSupported`、`desktopSupported`。
- 示例：
```json
{
  "id": "codex-shortcuts",
  "name": "Codex Shortcuts",
  "version": "0.1.0",
  "minAppVersion": "0.1.0",
  "description": "提供常用 Codex 快捷命令",
  "entry": "main.js",
  "style": "styles.css",
  "permissions": ["commands.register", "session.read", "session.write"]
}
```

### 13.4 运行时架构
- `PluginManager`：扫描目录、触发加载/卸载、处理启停状态。
- `PluginRegistry`：维护插件清单、版本、权限、运行状态。
- `PluginValidator`：校验 manifest、文件存在性、版本兼容、权限白名单。
- `PluginHost`：创建插件执行上下文，注入受限 API。
- `PluginStyleManager`：注入/移除插件样式，处理作用域和冲突。
- `PluginErrorBoundary`：捕获插件异常并熔断单插件实例。
- 插件状态机：
  - `discovered` -> `validated` -> `loading` -> `active` -> `stopped` / `failed`

### 13.5 加载与卸载流程
1. 启动时扫描 `~/.remoteconn/plugins/*/manifest.json`。
2. 校验 `manifest.json` 与目录结构；不合法则标记 `failed` 并记录错误。
3. 校验权限是否在白名单内；高危权限要求用户确认。
4. 先注入 `styles.css`（带命名空间），再执行 `main.js`。
5. 若 `main.js` 导出 `onload(ctx)`，则调用并等待完成（设置超时，例如 3000ms）。
6. 用户禁用或退出时调用 `onunload()`，清理命令注册、事件监听、样式节点。
7. 插件异常仅影响自身，主应用继续运行。

### 13.6 main.js 接口约定（MVP）
- 导出对象：
  - `onload(ctx)`：初始化插件。
  - `onunload()`：释放资源。
- `ctx` 结构：
  - `ctx.app`: 主应用只读元信息（版本、平台）。
  - `ctx.commands.register(command)`：注册命令。
  - `ctx.session.on(event, handler)`：订阅会话事件。
  - `ctx.session.send(input)`：发送终端输入（需 `session.write` 权限）。
  - `ctx.storage.get/set`：插件私有 KV 存储（命名空间隔离）。
  - `ctx.ui.showNotice(message, level)`：统一通知接口。
  - `ctx.logger.info/warn/error`：插件日志。
- 命令对象建议字段：
  - `id`、`title`、`handler`、`when`（可见性条件，可选）。

### 13.7 权限模型（首版）
- 权限白名单：
  - `commands.register`
  - `session.read`
  - `session.write`
  - `ui.notice`
  - `ui.statusbar`
  - `storage.read`
  - `storage.write`
  - `logs.read`
- 权限原则：
  - 最小权限默认拒绝。
  - 未声明权限时按无权限处理。
  - 插件启用时展示权限摘要。
  - 后续新增权限必须二次确认。

### 13.8 沙箱与安全策略
- 运行隔离：
  - 插件不能直接拿到 `window`、`document`、`localStorage` 原始对象。
  - 仅通过 `ctx` 暴露的受限 API 与主程序交互。
- 执行控制：
  - `onload`/事件回调设置超时阈值，超时自动熔断并禁用插件。
  - 连续异常（例如 3 次）自动转 `failed`，需要用户手动恢复。
- 数据安全：
  - 明确禁止插件读取凭据明文。
  - 插件日志默认脱敏（host、token、私钥路径）。
- 样式安全：
  - `styles.css` 注入时添加插件命名空间根节点，避免全局污染。
  - 禁止覆盖全局 reset（如 `* {}`、`body {}`）或在校验时告警。

### 13.9 插件管理页（设置 -> 插件）
- 列表字段：
  - 名称、版本、作者、状态、权限摘要、最后错误时间。
- 操作项：
  - 启用、禁用、重载、查看日志、打开目录。
- 安装方式（MVP）：
  - 手动放入 `~/.remoteconn/plugins` 后点击“刷新插件列表”。
- 失败可观测性：
  - 展示加载阶段（解析失败/权限拒绝/运行异常）和错误栈摘要。

### 13.10 跨端路径映射策略
- Desktop（macOS/Linux）：直接使用 `~/.remoteconn`。
- iOS Hybrid：映射到应用沙箱目录（如 `Library/Application Support/remoteconn`），在 UI 中仍展示逻辑路径 `~/.remoteconn`。
- Web：浏览器无法直接访问用户主目录；采用“导入插件包(zip)/导出插件包”方案并存储在 IndexedDB。
- 统一抽象：
  - 引入 `PluginFsAdapter`，屏蔽不同平台的文件系统差异。

### 13.11 数据模型草案
- `PluginManifest`：
  - `id`, `name`, `version`, `minAppVersion`, `permissions[]`, `entry`, `style`, `author?`, `description`
- `PluginRecord`：
  - `id`, `enabled`, `installedAt`, `updatedAt`, `lastError`, `lastLoadedAt`
- `PluginRuntimeState`：
  - `id`, `status`, `loadDurationMs`, `errorCount`, `lastHeartbeatAt`

### 13.12 测试与验收
- 单元测试：
  - manifest 校验、权限校验、状态机转换、API 权限拦截。
- 集成测试：
  - 插件加载/卸载、命令注册、样式注入与清理、异常隔离。
- 端到端测试：
  - 放置插件 -> 启用 -> 执行命令 -> 卸载 -> 重载，核心链路可复现。
- DoD：
  - 非法插件不会进入 active。
  - 插件异常不影响 SSH 会话。
  - 权限未授权时敏感 API 被拒绝且有明确提示。

### 13.13 迭代计划（插件专项）
- P1（2-3 天）：目录扫描、manifest 校验、插件列表页（只读）。
- P2（2-3 天）：`main.js` 生命周期 + 命令 API + 样式注入。
- P3（2-3 天）：权限模型 + 插件存储 + 错误熔断。
- P4（2-3 天）：跨端 `PluginFsAdapter` + 导入导出 + 完整测试。