Skip to content

WEBTTY.md

Latest commit

 

History

History
89 lines (69 loc) · 2.99 KB

WEBTTY.md

File metadata and controls

89 lines (69 loc) · 2.99 KB

WebTTY 最简终端文档

本文档说明 webtty 子命令的当前能力、实现边界与后续迭代路线。目标是保持“最小可用 + 可持续演进”，按一次一个能力推进。

1. 当前能力（已实现）

  • 启动本地 WebTTY：webtty --addr 127.0.0.1:18081 --open=true|false
  • 基于 WebSocket + PTY 暴露本地 shell（/ws）
  • 终端输入/输出桥接与窗口 resize 同步
  • 控制键处理：Ctrl+C、Ctrl+Z 优先走信号转发（失败时回退原始字节写入）
  • 文件上传：
    • 点击上传与拖拽上传
    • 多文件批量上传
    • 可配置并发上传与总进度
    • 上传调度策略（FIFO/小文件优先/大文件优先）
    • 支持指定相对目录 dir
    • 上传进度展示与失败重试
    • 支持单文件取消与全部取消
  • 文件下载：
    • GET /api/files?dir=... 列目录
    • GET /download?path=... 下载文件
    • GET /download-zip?dir=... 目录打包下载（zip）
  • 会话重连：
    • 前端自动重连（指数退避）
    • 支持手动“重连会话”

2. 接口概览

路径 方法 用途
/ GET WebTTY 前端页面
/ws GET 终端 WebSocket 通道
/upload POST 文件上传（multipart）
/api/files GET 列出目录文件
/download GET 下载单个文件
/download-zip GET 打包下载目录（zip）

2.1 上传请求约定

  • Content-Type: multipart/form-data
  • 文件字段：file（支持多文件）
  • 目录参数：dir（可选，相对路径）

路径安全规则：

  • dir 必须是相对路径。
  • 禁止 .. 越界与绝对路径。
  • 文件名会进行清洗，避免路径穿越与控制字符污染。

3. 架构简图

flowchart LR
    B[浏览器 xterm.js] -->|ws| W[/ws]
    W --> P[PTY master/slave]
    P --> S[本地 shell]

    B -->|multipart| U[/upload]
    U --> FS[(工作目录)]

    B -->|GET| L[/api/files]
    B -->|GET| D[/download]
    L --> FS
    D --> FS
Loading

4. 迭代节奏（一次一个能力）

已完成阶段（MVP+）：

  1. 终端会话打通（/ + /ws）
  2. 上传能力（点击、拖拽、批量、目录、进度、重试）
  3. 上传能力增强（并发上传、总进度、单文件/全部取消）
  4. 上传调度能力（FIFO/小文件优先/大文件优先）
  5. 下载能力（文件列表 + 单文件下载 + 目录 zip）
  6. 会话重连（自动重连 + 手动重连）
  7. 控制键信号可靠性（Ctrl+C/Ctrl+Z）

建议后续阶段（按顺序逐项推进）：

  1. 鉴权开关（本地 token）与访问来源限制
  2. 来源限制（Origin/Host 白名单）
  3. 会话级恢复（重连后恢复到同一 shell 实例）

5. 开发约定

  • 每次只做一个能力点，避免横向大改。
  • 每次改动同时补最小回归测试。
  • 若改动到交互或流程，先更新 docs/DESIGN.md，再更新本文件。