# terminal-manage

**Repository Path**: levy_de/terminal-manage

## Basic Information

- **Project Name**: terminal-manage
- **Description**: 该项目是一个支持多终端管理的开源项目，支持自定义终端布局，主题切换，字体大小，工作区保存和恢复
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-16
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Terminal Manager

Terminal Manager 是一个面向 Windows 的多终端工作区桌面应用。它基于 Electron、Vue 3、xterm.js 和 node-pty 构建，可以在一个窗口中管理多个真实 shell 会话，并支持分屏布局、工作区保存恢复、终端配置和自定义终端类型。

## 功能特性

- 多终端会话：支持同时打开多个 PowerShell、cmd、Git Bash、WSL 或自定义终端。
- 分屏布局：支持向右、向下分屏，并可拖拽调整分屏比例。
- 工作区保存与恢复：保存当前终端布局、工作目录、环境变量、终端标题和启动命令。
- 工作区管理：支持列表查看、重命名、删除、导入、导出和自定义存储目录。
- 终端配置：支持默认终端类型、默认工作目录、默认环境变量、字体、字号和配色方案。
- 自定义终端类型：可在设置中添加自定义 shell 命令和启动参数。
- 终端操作：支持重命名、重启、关闭、搜索输出、复制、粘贴和清屏。
- 主题模式：支持暗色和亮色应用主题，终端配色可独立选择。
- Windows 打包：提供 electron-builder 打包、NSIS 安装包和手动便携版脚本。

## 技术栈

- Electron 33
- electron-vite
- Vue 3
- TypeScript
- xterm.js
- node-pty
- Vitest
- electron-builder
- pnpm

## 环境要求

- Windows 10/11
- Node.js 22 或兼容版本
- pnpm 10.x
- PowerShell

项目依赖 `node-pty` 创建真实伪终端，会使用原生预构建产物。首次安装依赖时请确保网络和包管理器环境正常。

## 安装依赖

```powershell
pnpm install
```

## 开发运行

```powershell
pnpm dev
```

开发模式会启动 electron-vite，并打开 Electron 桌面窗口。应用需要在 Electron 环境中运行；直接用浏览器打开渲染页面时，终端相关 API 不可用。

## 常用脚本

```powershell
pnpm dev
pnpm run typecheck
pnpm test
pnpm run build
pnpm run preview
```

脚本说明：

| 命令 | 说明 |
| --- | --- |
| `pnpm dev` | 启动开发环境 |
| `pnpm run typecheck` | 运行 Vue/TypeScript 类型检查 |
| `pnpm test` | 运行 Vitest 测试 |
| `pnpm run build` | 类型检查并构建 Electron 应用 |
| `pnpm run preview` | 预览构建后的应用 |

## Windows 打包

项目提供三种 Windows 打包命令。

```powershell
pnpm run package:win
pnpm run package:win:installer
pnpm run package:win:manual
```

脚本说明：

| 命令 | 输出 | 说明 |
| --- | --- | --- |
| `pnpm run package:win` | `dist-builder/win-unpacked` | 使用 electron-builder 生成解包目录 |
| `pnpm run package:win:installer` | `dist-builder/TerminalManager-0.1.0-Setup.exe` | 生成 NSIS 安装包 |
| `pnpm run package:win:manual` | `dist/TerminalManager` | 手动组装便携版目录 |

`node-pty` 会被配置为 asar unpack，以确保原生模块在打包后可以正常加载。

## 项目结构

```text
.
├── assets/                  # 应用图标资源
├── scripts/                 # Windows 打包脚本
├── src/
│   ├── main/                # Electron 主进程
│   │   ├── app-settings.ts  # 用户设置读写
│   │   ├── index.ts         # 应用入口和窗口创建
│   │   ├── ipc.ts           # IPC 注册
│   │   ├── profiles.ts      # 内置和自定义终端类型
│   │   ├── pty-manager.ts   # node-pty 会话管理
│   │   ├── window-options.ts
│   │   └── workspace-store.ts
│   ├── preload/             # 安全暴露给渲染进程的 API
│   ├── renderer/            # Vue 渲染进程
│   │   └── src/
│   │       ├── App.vue      # 主界面和业务状态
│   │       ├── components/
│   │       ├── layout.ts    # 分屏布局纯函数
│   │       └── styles.css
│   └── shared/              # 主进程/渲染进程共享类型
├── tests/                   # Vitest 测试
├── electron.vite.config.ts
├── package.json
└── tsconfig.json
```

## 数据存储

默认情况下，设置和工作区会存储在 Electron 的 `userData` 目录下。

- 设置文件：`settings.json`
- 工作区目录：`workspaces/`
- 日志目录：`logs/`

可以在应用设置中选择新的工作区存储目录。工作区文件是 JSON 格式，导入导出也使用同一结构。

## 快捷键

| 快捷键 | 功能 |
| --- | --- |
| `Ctrl+Shift+N` | 新建终端 |
| `Ctrl+Shift+S` | 保存工作区 |
| `Ctrl+Shift+O` | 恢复工作区 |
| `Ctrl+Shift+W` | 关闭当前激活终端 |

## 测试

```powershell
pnpm test
```

测试覆盖：

- 分屏布局纯函数
- 应用设置读写
- 工作区保存、加载、重命名、删除和自定义存储目录
- Electron 窗口安全选项
- Windows 下 PowerShell/cmd 的 node-pty 创建、写入、resize、退出和环境变量隔离

PTY 相关测试只在 Windows 平台运行。

## 开发说明

- 主进程通过 `PtyManager` 创建和管理 shell，会将输出和退出事件广播到所有窗口。
- preload 通过 `contextBridge` 暴露 `window.terminalApi`，渲染进程不直接访问 Node.js。
- 渲染进程使用 `LayoutNode` 树表示分屏结构，工作区保存时会持久化布局和可见终端会话信息。
- 恢复工作区时会重新创建终端会话，并把旧 session id 映射到新的 session id。
- 终端输出由 xterm.js 渲染，FitAddon 负责根据面板大小同步 cols/rows。

## 常见问题

### 浏览器里打开页面不能创建终端

终端创建依赖 Electron preload 暴露的 `window.terminalApi`。请使用 `pnpm dev` 启动桌面窗口，或者运行打包后的应用。

### Git Bash 没有出现在终端类型列表里

应用会检查常见 Git Bash 安装路径：

- `C:\Program Files\Git\bin\bash.exe`
- `C:\Program Files (x86)\Git\bin\bash.exe`
- `%USERPROFILE%\AppData\Local\Programs\Git\bin\bash.exe`

如果 Git 安装在其他目录，可以在设置中添加自定义终端类型。

### WSL 选项无法启动

WSL 终端类型会调用 `wsl.exe`。请确认系统已安装并启用 WSL。

### 打包后 node-pty 无法加载

请确认使用项目内置打包脚本或 electron-builder 配置。`node-pty` 需要被放在 asar 外部，并保留对应的 `prebuilds` 原生文件。

## 许可证

本项目使用 Apache License 2.0。详见 [LICENSE](./LICENSE)。