first commit

PLAN_origin.md

@@ -0,0 +1,576 @@
+# 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` + 导入导出 + 完整测试。