remoteconn-gitea/PLAN_origin.md

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。
• 示例：

{
  "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 + 导入导出 + 完整测试。