@dadigua/web-terminal 0.1.3 → 0.1.5

package/API.md

@@ -12,6 +12,10 @@ HTTP 请求使用 `Authorization: Bearer <token>`。GET /api/auth 验证 token
 
 WebSocket 同源 /ws，不使用 query token。连接后 5 秒内发送 `auth`（`protocol: 2`）；服务端先发送 `snapshot`（画面、行列数、尺寸控制权），再发送 `ready`，后续增量为 `output`。快照与增量必须顺序写入 xterm。终端查询由服务端统一响应，浏览器拦截自动响应，避免多端重复回传。
 
+标签状态使用独立只读订阅：发送 `{type:"auth",protocol:2,token,scope:"sessions"}`，接收 `{type:"sessions",sessions:SessionInfo[]}`。订阅覆盖全部会话，不连接 PTY、不占用尺寸控制权。`running` 表示后端 Shell 存活，`outputActive` 由后端在真实 PTY 输出时置为 true，800ms 无输出后置为 false；历史快照不会触发。创建、退出、删除及输出活动变化立即推送，前台命令和目录每 5 秒刷新。连接和重连先收到当前完整状态，前端不再根据本地终端连接或输出计时推断标签状态。
+
+`title` 来自 CLI 的 OSC 0/2 标题序列，前端保留原文。可选 `progress:{state:1|2|3|4,value:number}` 来自 OSC 9;4：1 为百分比进度、2 为错误、3 为不确定进度、4 为暂停或警告，value 为 0–100。状态 0、终端重置或 Shell 退出清除 progress；服务重启不恢复旧进度。进度与 outputActive 独立，随会话状态推送并在重连时返回当前值。
+
 第一个连接控制尺寸。`resize` 更新该窗口期望尺寸，只有控制窗口会改变 PTY；`claim` 在用户操作时转交控制权。所有窗口按服务端行列数显示，窄窗口可滚动，尺寸变化发送新快照。键盘使用 `input`；文字、图片路径使用 `paste`（`text`、`submit`），由服务端按当前粘贴模式编码，提交回车在粘贴结束标记之外。
 
 未认证关闭码为 4401，协议版本不匹配为 4406（刷新页面），会话结束为 4404。断网自动指数退避重连；已访问会话切换时保留连接。

package/README.md

@@ -48,16 +48,22 @@ CLI 默认使用 `~/.web-terminal/config.yaml`，相对路径以配置文件所
 
 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. 粘贴截图、拖入图片，或点击工具栏的附件按钮。图片保存到服务器的 `.data/uploads/<会话ID>/`，附件区显示预览、上传状态与移除按钮；点击“发送”时，将文字与附件路径一起送入当前终端。支持多图和全部清除。
+3. 粘贴截图、拖入图片，或点击工具栏的附件按钮。图片默认保存到服务器的 `~/.web-terminal/uploads/<12位短文件名>.png`（扩展名随图片格式变化，可通过 `uploadDir` 配置目录），附件区显示预览、上传状态与移除按钮；点击“发送”时，将文字与附件路径一起送入当前终端。支持多图和全部清除。
 4. 悬停图片路径查看缩略图；在浏览器中点击文件路径，弹出图片或文本预览对话框，可复制路径、下载文件，按 Esc 或点击遮罩关闭。Markdown、代码和 YAML 等文本按原文显示，最多 1 MiB。VS Code 内点击路径会交给编辑器打开文件。
 5. VS Code、Electron 和浏览器连接同一服务器并选择同一会话，就会共用一个终端；两端输入会进入同一个 Shell，当前操作的窗口控制尺寸，其他窗口按相同行列数显示。关闭浏览器不会结束会话。默认直接运行 Shell，重启 Web 服务会结束普通 Shell；点击会话的结束按钮才会终止 Shell 并删除该会话上传的图片。
 
 会话首次选中时加载终端和连接，之后切换只隐藏或显示，不重新连接；各会话独立保留草稿、滚动位置、上传和文件预览。隐藏会话继续接收输出，不抢焦点或上报尺寸；关闭会话或退出登录时释放资源。
 
+标签栏采用 12px 文字和紧凑间距。右键标签或点击标签上的“⋯”，可创建分组、移至已有分组或移出分组；分组可编辑名称和颜色，点击组名折叠或展开。拖动标签和组名可排序，拖到组名上加入分组；菜单还提供置前和前后移动。分组、顺序及折叠状态只保存在当前客户端，各设备独立定制，刷新后保留；折叠和取消分组均保留终端运行及草稿。
+
 底部草稿区默认一行，随内容向上浮动展开，最多约 10 行，超出后内部滚动；输入区和上传提示不挤占终端高度。Enter 发送、Shift+Enter 换行；发送成功清空后缩回一行，断线时保留草稿。工具栏提供图片上传、Esc 和 Ctrl+C，触屏设备另提供 Tab 和方向键。
 
 图片支持 PNG、JPEG、WebP、GIF，每张最多 20 MiB；解码限制为 6400 万像素。上传路径插入与 Codex 识别成附件是两个阶段；遇到 CLI 未自动附加的情况，可以在提示中明确要求读取该绝对路径。服务不读取或同步系统剪贴板，上传由浏览器的粘贴/拖拽动作触发。
@@ -90,11 +96,21 @@ ssh -N -L 3840:127.0.0.1:3840 user@server
 
 ### 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 package:vscode
+pnpm install: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` 调整。
+也可运行 `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”，以附件形式加入当前会话，带有文件路径、语言与行号。点击发送后送入终端。
 
@@ -105,7 +121,7 @@ pnpm electron
 pnpm package:electron:win
 ```
 
-开发命令打开桌面客户端；Windows 命令生成 `release/Web-Terminal-0.1.3-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` 生成。
+开发命令打开桌面客户端；Windows 命令生成 `release/Web-Terminal-0.1.5-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 嵌入。
 

package/config.example.yaml

@@ -5,3 +5,5 @@ port: 3840
 # defaultCwd: /home/yourname/projects
 # shell: /bin/zsh
 dataDir: .data
+# 图片默认保存在 ~/.web-terminal/uploads，可指定其他目录。
+# uploadDir: /home/yourname/.web-terminal/uploads