577 lines
26 KiB
Markdown
577 lines
26 KiB
Markdown
# 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` + 导入导出 + 完整测试。
|