83 lines
8.5 KiB
Markdown
83 lines
8.5 KiB
Markdown
# RemoteConn MiniProgram（稳定基线 v3.0.1）
|
||
|
||
状态：`已对齐核心功能，当前稳定基线为 v3.0.1`
|
||
目标版本：`v3.0.1`
|
||
|
||
本次 `v3.0.1` 主要收口小程序使用手册与主题口径：使用手册补成图文版，正文前置“为什么需要这个APP？”，并接入 `guide-mobile-*` 配图；主题预设补齐到与 Web 一致的 `21` 套，主题名称支持随语言切换且尽量压短为单词短名。当前版本不引入新的同步协议、终端协议或配置字段，继续沿用 `v3.0.0` 已明确的能力边界。
|
||
|
||
## 1. 当前已完成范围
|
||
|
||
1. 页面骨架：`connect`、`server settings`、`terminal`、`logs`、`records`、`settings`、`plugins`。
|
||
2. 数据基础层：服务器/设置/闪念以“本地 storage + Gateway 同步”双层持久化，日志与插件运行记录仍保留本地存储；已补齐 `updatedAt / category / contextLabel / processed / discarded`。
|
||
3. 传输：`wx.connectSocket` 网关连接、心跳、收发、断开。
|
||
4. 分页：日志与闪念均为 15 条/页。
|
||
5. 语音区：Frame2256 交互 + `/ws/asr` 实时采集上行 + 结果回填，支持分类选择、未连接可记录闪念、写入 `服务器名称-项目名` 快照。
|
||
6. 闪念页：搜索、分类过滤、左滑废弃 / 已处理 / 复制 / 删除、正文编辑、分类快速改写、导出。
|
||
7. 配置页：`记录 -> 闪念分类` 管理，支持新增、设默认、删除、按住拖动排序。
|
||
8. 服务器：配置页支持自定义标签（逗号分隔），服务器卡片底部展示项目标签与自定义标签，并支持左滑复制 / 删除单台服务器。
|
||
9. 插件：运行时启停/重载/移除、JSON 导入导出、命令执行、运行日志。
|
||
10. 资源：图标路径统一版本 query（`v=2026022701`）。
|
||
11. 终端：已按 xterm 风格完成 cell 光标模型重构，补齐真实 `cols/rows`、宽字符 continuation、自绘 caret、固定列宽渲染与双 probe 宽度测量，当前中文/英文混排输入已稳定。
|
||
12. 会话续接：终端页返回其他页面后默认保活 `15` 分钟，可在设置页调到 `1~60` 分钟；回到同一服务器会优先复用原会话并恢复尾部缓冲。首次恢复优先使用保存时的 `lines + bufferCols / bufferRows` 还原当前屏幕，仅在后续真实几何变化时再使用 `replayText` 重建，避免顶部空白与裸露 `5;2H` 一类控制串回归。
|
||
13. 连接反馈：服务器列表“连接”按钮与底栏 `shell` 按钮在活动连接态统一切到高饱和实底高亮，便于快速识别当前连接状态。
|
||
14. 跳转主机：服务器配置页已支持跳板机主机、端口、用户名、认证方式与独立凭据；目录选择与终端连接链路均可透传第一跳/第二跳配置。
|
||
15. AI 快速启动：服务器列表 `AI` 按钮和终端左上角 AI 按钮都会按“全局配置 -> 连接 -> AI连接”的默认 AI 直接启动；终端页支持 Codex 目录预检、二进制预检与连接后自动启动。当前同一条终端会话内新增了 AI 前台互斥保护，AI 运行期间重复点击会直接提示而不再把启动命令写进前台 TUI；当 Codex / Copilot 正常退出回到 shell 后，保护会自动解除。
|
||
16. 终端语音与主题视觉已继续收口：展开语音区按钮默认全透明、分类胶囊改为贴文字高度、录音中输入框上方新增脉冲提示；终端顶栏与语音区按钮继续按 UI / Shell 双域规则渲染。
|
||
|
||
## 2. 当前说明
|
||
|
||
1. 机读对齐清单已更新为 `done`，见 `apps/miniprogram/parity.v2.6.0.json`。
|
||
2. 小程序终端 VT 能力已进入 P0 基线：双缓冲、备用屏幕切换、`DSR / CPR / DA1 / DA2 / DECSTR`、基础局部重绘和移动端常用原始按键编码已接入。
|
||
3. normal buffer 的 live tail 与最大滚动值已统一到同一口径，回到底部后不会再继续把当前命令行往上推。
|
||
4. 当前仍建议通过微信开发者工具和真机做交互验收，尤其是服务器卡片左滑复制 / 删除、闪念左滑废弃 / 已处理 / 复制 / 删除、分类切换、语音记录链路，以及 `top / less / vim` 一类终端程序的抽样验证。
|
||
5. 终端字号修改后仍存在偶发“吃字/显示不完整”遗留问题，当前版本在设置页增加了“修改字号后建议断开重连”的提示，作为临时规避方案。
|
||
6. 当前业务数据采用“双层持久化”：
|
||
服务器配置、用户设置与闪念记录会先写入小程序本地 storage，并在同步配置完整时通过 Gateway + SQLite 同步到服务端；
|
||
日志、插件运行记录与终端会话缓冲仍仅保留在本地。
|
||
通过 `npm run mini` 生成的 preview 预览二维码，不作为正式版跨设备同步与本地缓存连续性的验证依据。
|
||
7. Gateway 的同步 SQLite 目前启用 `WAL` 模式：
|
||
`data/remoteconn-sync.db-wal` 是写前日志，文件体积不直接等于当前有效同步数据量；
|
||
需要结合 checkpoint 后的主库体积、`user_settings / user_servers / user_records` 行数与字段大小一起判断。
|
||
8. 当前版本最重要的交互修复是：小程序终端在 `Codex` 持续输出期间，底部提示块缺行、状态行被裁掉与区域反复闪动的问题已收口；normal buffer viewport 会保留光标行之后仍真实存在的 footer，`CSI ? 2026 h/l` 同步刷新窗口也已做兼容。
|
||
9. 同一轮交互修复还收口了高亮块透底细线问题：像 `> Use /skills to list available skills` 和代码块这类整行统一背景区域，背景优先提升到 line 层绘制，不再在行与行之间露出底色细缝，也没有新增渲染节点。
|
||
10. 此前点击 Codex 连接选项后的首回显迟滞与等待期间按钮阻塞问题已收敛，当前版本不再将其作为已知遗留问题保留。
|
||
11. 当前另记录一个低频连接时序遗留问题：偶发新连接后首屏只显示光标、提示符稍后才出现；初步定位为 `connected` 状态与光标可见时机早于首个可见 `stdout / prompt`，后续再继续优化。
|
||
12. 会话续接恢复口径已明确：首次回到终端页时，以挂起前屏幕快照和当时终端几何作为权威来源；被裁剪过的 `replayText` 不再参与首次恢复，避免历史区顶部空白和定位参数残片再次出现。
|
||
13. 时延诊断浮窗已收口成单张双轴平滑曲线图：左轴显示网关响应，右轴显示网络时延；顶部只保留两张摘要卡，面板配色跟随终端主题反相推导，深色终端会自动切到更深的蓝橙曲线与指标色；同一服务器断开重连后会尽量延续最近 `30` 个采样点。
|
||
14. 当前小程序终端语音播报仍属于待优化能力：播报文本提取与轮次稳定判定还不够准确，长时间 `Codex` 交互时也会放大小程序端响应压力；现阶段暂不建议默认使用，先作为遗留问题保留。
|
||
15. 当前另记录一个 AI 交互期输入遗留问题：在 `Codex` 等 AI 持续输出期间，点击 shell 激活区弹出软键盘后，输入框/激活区仍可能发生跳跃，导致无法稳定连续输入；该问题尚未完成稳定修复，先按已知遗留问题登记。
|
||
|
||
## 3. 对齐清单
|
||
|
||
机读清单：`apps/miniprogram/parity.v2.6.0.json`
|
||
|
||
## 4. 实施依据
|
||
|
||
1. `docs/records-enhancement-plan-2026-03-06.md`
|
||
2. `docs/miniprogram-config-implementation-plan-2026-02-28.md`
|
||
3. `docs/xterm-cursor-algorithm-2026-03-07.md`
|
||
4. `docs/miniprogram-terminal-cursor-gap-analysis-2026-03-07.md`
|
||
5. `docs/ssh-jump-encryption-diagram-2026-03-07.md`
|
||
6. `docs/miniprogram-terminal-vt-guardrails-2026-03-08.md`
|
||
7. `docs/miniprogram-terminal-vt-implementation-plan-2026-03-08.md`
|
||
8. `docs/miniprogram-codex-footer-flicker-optimization-plan-2026-03-11.md`
|
||
|
||
## 5. 本地调试
|
||
|
||
1. 使用微信开发者工具打开 `apps/miniprogram` 目录。
|
||
2. 如需连通网关，在 `apps/miniprogram/.env` 中配置运维配置：至少包含 `GATEWAY_URL` 和 `GATEWAY_TOKEN`（可参考 `apps/miniprogram/.env.example`，该配置不对最终用户展示）。
|
||
3. 回到“服务器”页创建服务器并进入终端测试连通性。
|
||
|
||
## 6. 命令行预览
|
||
|
||
在仓库根目录可直接使用以下脚本：
|
||
|
||
1. `npm run mini`
|
||
在终端输出小程序预览二维码；若终端二维码首次渲染失败，会自动在 shell 中重画一次。
|
||
|
||
说明：
|
||
|
||
1. 该命令会先读取 `apps/miniprogram/.env`，并生成 `apps/miniprogram/utils/opsEnv.js` 供小程序运行时使用。
|
||
2. 默认使用仓库根目录私钥：`./private.wxa0e7e5a27599cf6c.key`。
|
||
3. 执行前，需要在微信公众平台完成上传密钥下载和 IP 白名单配置。
|