@dadigua/web-terminal 0.0.0-stage → 0.1.4

package/API.md

@@ -0,0 +1,19 @@
+# 前后端接口
+
+HTTP 请求使用 `Authorization: Bearer <token>`。GET /api/auth 验证 token 返回 `{ok:true}`，无效 401。验证成功才将 token 写入 localStorage (`web-terminal.token`)。`/api/*` 均鉴权。`GET /health` 无需 token，仅返回服务标识 `@dadigua/web-terminal`、版本、管理协议版本、实例 ID、PID 和是否由 CLI 管理；不返回 token、路径或配置。客户端检查该身份后才连接或启动服务。错误统一 `{error:string}`。
+
+- GET /api/info → ServerInfo
+- GET /api/sessions → SessionInfo[]
+- POST /api/sessions，JSON `{name?:string,cwd?:string}` → SessionInfo (201)，默认目录由 info 提供，不自动执行 Codex。
+- DELETE /api/sessions/:id → `{ok:true}`，会结束 shell，前端需用户明确点结束并确认。
+- GET /api/sessions/:id/files/meta?path=... → FileInfo。相对路径按该会话当前 cwd 解析；可传 base=已知的绝对 cwd 固定解析基准。
+- GET /api/sessions/:id/files/content?path=...&thumbnail=1 → 图片缩略图。省略 thumbnail 获取原图或原始文件，可加 download=1 下载。使用鉴权 fetch 转 blob URL，不将 token 放 URL。
+- POST /api/sessions/:id/uploads，multipart 字段 file → FileInfo (201)，上传后保留在附件区，点击发送时与文字一起提交。支持图像 PNG/JPEG/WebP/GIF，最大 20MiB。
+
+WebSocket 同源 /ws，不使用 query token。连接后 5 秒内发送 `auth`（`protocol: 2`）；服务端先发送 `snapshot`（画面、行列数、尺寸控制权），再发送 `ready`，后续增量为 `output`。快照与增量必须顺序写入 xterm。终端查询由服务端统一响应，浏览器拦截自动响应，避免多端重复回传。
+
+第一个连接控制尺寸。`resize` 更新该窗口期望尺寸，只有控制窗口会改变 PTY；`claim` 在用户操作时转交控制权。所有窗口按服务端行列数显示，窄窗口可滚动，尺寸变化发送新快照。键盘使用 `input`；文字、图片路径使用 `paste`（`text`、`submit`），由服务端按当前粘贴模式编码，提交回车在粘贴结束标记之外。
+
+未认证关闭码为 4401，协议版本不匹配为 4406（刷新页面），会话结束为 4404。断网自动指数退避重连；已访问会话切换时保留连接。
+
+服务端保留会话，浏览器断开不结束进程。Web 服务重启会结束普通 Shell。字体、路径 hover、图片粘贴、文件预览对话框、上传进度、手机按钮由前端实现。路径 provider 要考虑软换行、中文、引号和路径中的空格；尽可能用单一解析 helper 并加测试。支持图片与文本预览，其他文件可下载；VS Code 内通过插件打开对应文件。不要将服务端文字插入 innerHTML。

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# Web Terminal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+为远程 Codex 等 CLI 提供浏览器终端、图片粘贴上传和路径图片预览。首次输入 token，验证成功后保存在当前浏览器、当前站点的 `localStorage`；刷新或再次打开时自动验证。点击退出登录会清除本机保存的 token。
+
+## 启动
+
+需要 Node.js 22+、pnpm 11，推荐 Linux/WSL。安装 node-pty 时可能需要 Python 3、make 和 C++ 编译工具。
+
+```bash
+pnpm install
+pnpm build
+pnpm start
+```
+
+打开 http://localhost:3840 。首次启动自动生成 token，另开终端读取后粘贴到登录页：
+
+```bash
+cat .data/token
+```
+
+也可以在启动时通过 `WEB_TERMINAL_TOKEN` 指定非空 token。token 不放入页面 URL、图片链接或 WebSocket URL。
+
+开发模式使用 `pnpm dev`，前后端共用 3840 端口。`pnpm test` 验证文件访问、认证、真实 PTY 和断线重连；`pnpm check` 做类型检查。
+
+## 全局 CLI 与本地 link
+
+服务包名为 `@dadigua/web-terminal`，命令名为 `web-terminal`。npm 上的无 scope 同名包是其他项目，不要安装它。安装服务：
+
+```bash
+npm install -g @dadigua/web-terminal
+web-terminal start
+```
+
+本地开发使用 link：
+
+```bash
+pnpm build
+npm link
+web-terminal start
+web-terminal status
+web-terminal restart
+web-terminal stop
+```
+
+link 指向当前项目；服务端或前端源码修改后执行 `pnpm build`，再重启服务。安装命令为 `npm install -g @dadigua/web-terminal`。
+
+CLI 默认使用 `~/.web-terminal/config.yaml`，相对路径以配置文件所在目录为准；每个端口的 token、状态和日志分别位于 `~/.web-terminal/servers/<端口>/data/token`、`server.yaml` 和 `server.log`。首次登录读取对应 token 文件。可用 `--url http://localhost:3841` 选择端口、`--config /path/config.yaml` 指定配置，`--home /path/state` 指定管理目录。CLI 启动为后台进程，关闭客户端不会结束服务；重启保留 token，但结束普通 Shell 会话。
+
+CLI 只停止自己登记且启动标识匹配的进程，不接管 `pnpm start` 或 systemd 启动的外部服务。外部服务可以连接，重启时会提示使用原管理器。
+
+## 发布
+
+推送与 `package.json` 版本一致的 `v*` 标签后，`.github/workflows/publish.yaml` 自动检查、构建、打包，并通过 npm Trusted Publishing 发布，再创建 GitHub Release 和上传附件。npm 仅信任 `laopo001/web-terminal` 仓库中的此工作流，不需要发布 token。手动运行工作流只验证和生成产物。
+
+## 使用
+
+1. 首次打开时选择已有会话，或点击“新建 Shell”进入普通命令行；不会自动接入第一条历史会话。通过“＋”选择工作目录；VS Code 中可快捷选择工作区目录。
+2. 在终端里运行 `codex`，照常操作 CLI。 底部输入框点击“发送”或按 Enter 会写入文字并提交一次；中文输入法选词时不会提交。
+3. 粘贴截图、拖入图片，或点击工具栏的附件按钮。图片默认保存到服务器的 `~/.web-terminal/uploads/<12位短文件名>.png`（扩展名随图片格式变化，可通过 `uploadDir` 配置目录），附件区显示预览、上传状态与移除按钮；点击“发送”时，将文字与附件路径一起送入当前终端。支持多图和全部清除。
+4. 悬停图片路径查看缩略图；在浏览器中点击文件路径，弹出图片或文本预览对话框，可复制路径、下载文件，按 Esc 或点击遮罩关闭。Markdown、代码和 YAML 等文本按原文显示，最多 1 MiB。VS Code 内点击路径会交给编辑器打开文件。
+5. VS Code、Electron 和浏览器连接同一服务器并选择同一会话，就会共用一个终端；两端输入会进入同一个 Shell，当前操作的窗口控制尺寸，其他窗口按相同行列数显示。关闭浏览器不会结束会话。默认直接运行 Shell，重启 Web 服务会结束普通 Shell；点击会话的结束按钮才会终止 Shell 并删除该会话上传的图片。
+
+会话首次选中时加载终端和连接，之后切换只隐藏或显示，不重新连接；各会话独立保留草稿、滚动位置、上传和文件预览。隐藏会话继续接收输出，不抢焦点或上报尺寸；关闭会话或退出登录时释放资源。
+
+底部草稿区默认一行，随内容向上浮动展开，最多约 10 行，超出后内部滚动；输入区和上传提示不挤占终端高度。Enter 发送、Shift+Enter 换行；发送成功清空后缩回一行，断线时保留草稿。工具栏提供图片上传、Esc 和 Ctrl+C，触屏设备另提供 Tab 和方向键。
+
+图片支持 PNG、JPEG、WebP、GIF，每张最多 20 MiB；解码限制为 6400 万像素。上传路径插入与 Codex 识别成附件是两个阶段；遇到 CLI 未自动附加的情况，可以在提示中明确要求读取该绝对路径。服务不读取或同步系统剪贴板，上传由浏览器的粘贴/拖拽动作触发。
+
+当前一台服务对应一台机器，远程使用应将服务部署在 Codex 所在机器。终端内再 SSH 到其他机器后，其路径不会自动映射回当前文件服务。绝对路径最可靠；没有输出时工作目录信息的历史相对路径无法保证还原当时含义。
+
+## 远程访问和配置
+
+服务默认仅监听 `127.0.0.1`。可通过 SSH 转发访问：
+
+```bash
+ssh -N -L 3840:127.0.0.1:3840 user@server
+```
+
+然后在本机打开 http://localhost:3840 。也可放到已有 HTTPS 反向代理后，代理需支持 WebSocket 并保留 Host。直接用远程 HTTP 地址时，浏览器的部分剪贴板能力可能不可用。
+
+复制 `config.example.yaml` 为 `config.yaml`，按需配置监听地址、端口、默认目录。环境变量支持 `HOST`、`PORT`、`WEB_TERMINAL_CONFIG`、`WEB_TERMINAL_DATA_DIR`、`WEB_TERMINAL_TOKEN`。相对配置路径以启动目录为基准。
+
+登录者拥有服务运行用户的终端权限。`.data/` 保存 token、会话元数据和上传图片，不应提交到 Git。
+
+需要时在终端里手动运行 `tmux`，再运行其他命令；Web 服务重启后可新建终端并执行 `tmux attach`。
+
+## 当前验证
+
+已通过类型检查、生产构建和集成测试（含客户端）。共享 Windows Chrome 中验证了 token 保存与刷新恢复、原生文件上传、图片剪贴板粘贴、中文及空格路径的 hover、图片与文本弹窗预览，以及 VS Code 文件打开桥接。Codex CLI 0.159.2 的实际输入框已识别上传图片为 `[Image #1]`，并保留原有文字；测试未提交模型请求。
+
+## VS Code 与 Electron
+
+两个客户端加载独立的 Node.js 服务，共用端口检测、身份检查和 CLI 启动逻辑；不打包前端副本或终端运行时。本机端口未启动时自动调用全局 CLI，冲突或缺少安装会明确报错；远程地址只连接。
+
+### VS Code
+
+安装全局 CLI 后，用一条命令安装 npm 包自带的插件：
+
+```bash
+web-terminal install-vscode
+```
+
+自动安装到检测到的 VS Code Stable 和 Insiders；WSL 下同时安装 WSL 扩展宿主和 Windows 宿主。已打开的窗口需运行 `Developer: Reload Window` 加载插件。可用 `web-terminal install-vscode --vsix /path/web-terminal.vsix` 安装指定文件。
+
+本地开发打包并安装：
+
+```bash
+pnpm install:vscode
+```
+
+也可运行 `pnpm package:vscode`，在 VS Code 的扩展菜单选择“从 VSIX 安装”，打开 `release/web-terminal.vsix`。点击活动栏终端图标或运行 `Web Terminal: Show Sidebar` 打开侧边窗口；`Web Terminal: Open` 在编辑器标签页打开。两处均加载现有 Web 页面。默认地址为 `http://localhost:3840`；通过 `Web Terminal: Set Server URL` 或设置 `webTerminal.serverUrl` 修改，`Web Terminal: Reload` 重载；侧栏及编辑器标题栏的重启按钮重启后台并等待就绪。Remote WSL/SSH 在扩展宿主所在机器检测和启动，再使用 VS Code 的端口转发能力。Windows 本机默认先查本机全局 CLI，再查默认 WSL；可通过 `webTerminal.runtime` 和 `webTerminal.cliPath` 调整。
+
+选中编辑器中的文本后，右键选择“发送选中文本到 Web Terminal”，以附件形式加入当前会话，带有文件路径、语言与行号。点击发送后送入终端。
+
+### Electron
+
+```bash
+pnpm electron
+pnpm package:electron:win
+```
+
+开发命令打开桌面客户端；Windows 命令生成 `release/Web-Terminal-0.1.4-win-x64.zip`，解压后运行 `Web Terminal.exe`。菜单“连接 → 打开连接配置”打开 `client.yaml`，只需修改 `serverUrl`，再选择“重新加载服务器”；“重启后台服务”通过全局 CLI 重启。`client.yaml` 的 `runtime` 可选 auto、native、wsl，`cliPath` 可指定本机 CLI 路径。也可用 `WEB_TERMINAL_URL` 临时覆盖地址。Linux 目录包通过 `pnpm package:electron:linux` 生成。
+
+浏览器、VS Code、Electron 各自首次在同一 Web 登录页输入 token，验证后保存在各自 Webview 的持久 localStorage 中。客户端配置不保存 token。Electron 远程页面开启 sandbox/contextIsolation、关闭 Node 集成；VS Code 通过专用 `/?embed=vscode` 入口加载，普通入口仍禁止 iframe 嵌入。
+
+客户端验证：Windows VS Code 开发宿主中已实际显示 Web 登录页；Electron 在 WSL 的真实渲染器中恢复 token 并连接已有终端。Windows ZIP 已完成打包及内容检查，应用归档仅有 `main.cjs` 和 `package.json`，未包含后端依赖。

package/bin/web-terminal.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist-server/cli.js';

package/config.example.yaml

@@ -0,0 +1,9 @@
+# 复制为 config.yaml 后修改。token 首次启动自动生成，保存在 .data/token。
+host: 127.0.0.1
+port: 3840
+# 默认工作目录为当前用户的 home，可按需指定绝对路径。
+# defaultCwd: /home/yourname/projects
+# shell: /bin/zsh
+dataDir: .data
+# 图片默认保存在 ~/.web-terminal/uploads，可指定其他目录。
+# uploadDir: /home/yourname/.web-terminal/uploads