remoteconn-gitea/apps/miniprogram

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 白名单配置。