# 运行时、传输与存储开发

NyaTerm 没有独立的 Web 后端。原生应用的领域逻辑、协议运行时和持久化按职责拆分在多个 Rust crate 中，并通过有类型的接口与 GPUI 桌面层协作。

## Crate 边界

| Crate | 放置的行为 |
|------|------------|
| `nyaterm-core` | 纯模型、解析、策略、兼容格式和 schema-neutral 序列化 |
| `nyaterm-transport` | PTY、SSH、SFTP、Telnet、串口、隧道、远程操作和传输运行时 |
| `nyaterm-store` | redb、事务、存储 worker、加密适配和兼容性读取 |
| `nyaterm-terminal` | 终端状态机、快照、控制序列、编码和图形协议 |
| `nyaterm-remote-desktop` | RDP/VNC 会话管理、framebuffer 与输入模型、证书策略、剪贴板状态和 helper IPC 合约 |
| `nyaterm-rdp-helper` / `nyaterm-vnc-helper` | 隔离的 helper 进程，持有各自的协议解码器 |
| `nyaterm-otp` | HOTP/TOTP 兼容实现 |

低层 crate 不导入 GPUI 或桌面呈现类型。需要跨边界时定义小型 typed adapter，不把 application-wide model 下沉到 transport 或 store。

解析服务器控制字节的协议解码器只放在 helper crate 里。`nyaterm-remote-desktop` 自己不含解码器，两个 helper 必须把解码器 panic 转换成致命 IPC 错误上报。详见 [架构说明 → RDP / VNC 的进程隔离](./architecture#rdp--vnc-的进程隔离)。

## 会话与传输运行时

`nyaterm-transport` 的 `SessionManager` 管理活动会话，并为本地 PTY、SSH、Telnet、raw TCP、串口、RDP 和 VNC 提供统一生命周期入口。

会话输出通过 `SessionEvent` 返回：

- `Output` / `OutputDropped`
- `CwdChanged`
- `CommandAccepted`
- `Exited`
- `Error`

事件队列按原始事件顺序限制高吞吐输出：单个大 `Output` 会拆成有界 chunk，8/4 MiB 高低水位通过 producer wait 提供正常运行期的无损背压，不合并相邻 raw output。桌面层批量 drain 事件，而不是让后台线程直接修改 GPUI state。新增会话事件时使用有类型的 enum variant，并同时测试正常顺序、队列上限和关闭路径。

关闭单个 session 时，manager 必须先取消该 session 并唤醒 queue waiter，再关闭 transport 和 join reader；取消会清除该 session 的已排队事件并拒绝后续事件，但不能影响其他 session。manager 整体析构必须先全局关闭 queue、唤醒 producer 和 blocking consumer，再关闭并 join 全部 session。全局关闭后的空 blocking drain 立即返回；这些 shutdown 丢弃边界不改变正常过载的无损与 8/4 MiB 滞回契约。

SSH、SFTP、隧道、远程进程和 Docker 等操作也应保持异步或运行在专用 worker 上。不要让 transport 依赖窗口、对话框或桌面 feature 类型。

## 终端运行时

wire bytes 由 transport 送入 `nyaterm-terminal`。该 crate 维护网格、scrollback、模式、OSC 标记、搜索结果和图形协议状态，并生成 UI-neutral snapshot。

键盘和鼠标的协议编码中，与终端语义相关的部分留在 terminal/core 边界；像素尺寸、GPUI key event 和绘制逻辑留在 `nyaterm-terminal-gpui`。

## StoreRuntime 与持久化

`nyaterm-store::StoreRuntime` 拥有数据库 worker。桌面层通过 `StoreUiClient` 或 `StoreBlockingClient` 提交实现 `StoreRequest` 的 typed request，再以 task result 更新 UI。

数据库实现集中在 `nyaterm-store/src/storage/`。修改存储时必须保持：

- 现有 redb table 名、key 和文档 key
- 序列化字段名及未知字段处理
- 主密钥 wrapping、加密前缀和 fallback 解密
- `.nya` 备份、portable snapshot 和 Dragonfly 兼容读取
- 验证成功前不覆盖用户现有数据

纯兼容模型和策略属于 `nyaterm-core`；数据库 transaction、文件 I/O 和兼容 reader 属于 `nyaterm-store`。

## AI、同步与原生 HTTP

AI provider、翻译、云同步和更新检查通过原生 HTTP adapter 运行。请求构造、风险策略和 schema-neutral provider 设置尽量保持在 `nyaterm-core`，桌面层负责凭据遮罩、交互状态和任务协调。

云同步以 portable snapshot 为兼容合约。拉取数据必须先解密、解析和验证，再提交应用；冲突、重试和错误通过 typed result 返回 UI。

## 错误与安全

低层库返回 typed error，桌面适配层再决定用户提示。不要在错误、日志或 `Debug` 输出中包含密码、私钥、OTP、API secret 或未脱敏的终端上下文。

后台任务必须处理取消、窗口关闭和 runtime shutdown。退出时由 `AppShell` 请求 store flush/shutdown，避免 UI 已关闭后仍写入数据库。

## 测试

- pure parsing、策略和兼容格式测试放在 `nyaterm-core`。
- PTY、SSH、SFTP、Telnet、串口、隧道和事件队列测试放在 `nyaterm-transport`。
- 终端解析、快照、graphics 和 encoding 测试放在 `nyaterm-terminal`。
- 存储修改需要新数据 round trip、代表性旧数据、错误密码和损坏数据测试。
- RDP/VNC 的协议、framebuffer、输入映射、IPC、证书、剪贴板和重连测试放在 `nyaterm-remote-desktop`、`nyaterm-rdp-helper` 或 `nyaterm-vnc-helper`。两个 helper crate 的 `tests/lifecycle.rs` 覆盖握手、正常断开和崩溃 / 挂起回收，IPC 合约变更时同步更新两边。
- 跨 crate 行为优先测试小型 adapter，不依赖真实凭据或生产服务。