# shell-go

**Repository Path**: zhReimu/shell-go

## Basic Information

- **Project Name**: shell-go
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-08-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ShellGo

ShellGo 是基于 Go、Wails v2 和 Vue 3 的桌面终端工具。应用把本地终端、SSH 会话、远程文件管理、Docker 管理、SSH 隧道和 AI 对话放在同一套标签页工作区中。

## 主要功能

### 连接与终端

- 保存并按组管理 SSH、本地终端和 AI 三类连接入口；一个 SSH 连接可打开多个终端标签页。
- SSH 支持密码、指定私钥、默认私钥和 SSH Agent 认证。首次连接默认按 TOFU 保存主机密钥；首选项可开启 SHA256 指纹严格确认，并同时覆盖普通连接和 AI SSH 目标。
- SSH 可经 SOCKS5 或用户态 WireGuard 网络连接；连接表单可生成 ed25519 密钥对并复制公钥。
- 基于 xterm.js 提供 SSH、本地和 Docker 容器交互式终端，支持尺寸自适应、链接识别、JetBrains Mono 连字和终端内容快捷操作。
- 标签页支持拖动排序、右侧拆分和中键关闭；远程脚本可在复用 SSH 连接的独立终端中执行。
- 连接后可查看主机、CPU、内存、磁盘、磁盘 IO 和网络趋势，并按需查看 CPU Top 进程。
- SSH 隧道支持本地端口转发、远程端口转发和动态 SOCKS5 转发，也可查询远端 TCP 监听端口。

本地终端默认在用户主目录启动：Windows 使用 `cmd.exe`，macOS/Linux 使用登录 Shell；也可在首选项中配置可执行文件和参数。

### 远程文件

- 通过 SFTP 浏览远程目录，创建、删除、重命名、复制和移动文件或目录，并管理路径书签。
- 上传文件或目录、下载文件，显示统一传输进度并支持取消；拖拽时可选择移动或复制。
- 权限不足时可为当前 SSH 会话启用提权 SFTP，并支持 `chmod`、`chown`。
- 使用 Monaco Editor 编辑文本；可比较两个文件并跳转差异、联动滚动或折叠未变化区域。
- 预览图片、PDF、音视频、Markdown 和压缩包；Markdown 支持代码高亮与 Mermaid。
- 创建 `tar`、`tar.gz`、`tar.bz2`、`zip` 压缩包，并浏览或解压受支持的压缩包。

### Docker 与 Compose

Docker 功能通过 SSH 的 `direct-streamlocal@openssh.com` 通道访问远端 Docker socket，不要求在本机暴露 Docker TCP API。

- 容器：列表、创建、启动、停止、重启、暂停、恢复、删除、提交镜像、详情检查、资源监控、交互式 exec 和容器内文件管理。
- 镜像：拉取、构建、导入、导出、打标签、推送、运行和删除。
- 网络与卷：列表、创建、检查和删除。
- 系统：Docker Info、版本、磁盘占用和资源清理，清理结果按资源类型展示。
- 通用 Docker 命令先解析为参数并逐项转义，执行前展示规范化命令和 Docker daemon 高权限风险，用户确认后才会提交。
- Compose：从容器标签自动发现项目，也可按远端项目目录手动添加；栈列表展示按 Compose 服务名去重的服务数量，并支持 Up、Down、Restart、Pull、Build 和服务列表。后端优先使用 `docker compose`，不存在时回退到 `docker-compose`。

容器日志与 Compose 日志共用同一个日志浏览器。Compose 日志会在主工作区打开独立标签页，而不是一次性输出弹窗。两类日志均支持：

- 历史日志按页向前加载、虚拟滚动和实时跟随；每页至少 20 行且不设上限，已加载历史不设总行数上限。
- 暂停或恢复跟随、自动滚动、起止时间过滤、刷新，以及 TXT/JSON 导出。
- 普通文本或正则搜索、区分大小写，并按每个关键字命中逐项前后跳转。
- 保留 ANSI 颜色；所有候选使用浅色高亮，当前命中使用更深的高亮。
- 首次加载和向前分页都有可见加载状态，状态栏也可手动请求更早日志。

### AI 对话

- 连接 OpenAI 兼容的 Chat Completions 或 Responses 接口，可配置 Base URL、API Key、模型、自定义 Header 和 System Prompt。
- 支持流式响应、思考内容、Token 用量、Markdown、代码高亮、Mermaid，以及图片和 UTF-8 文本附件。
- 会话、消息和 Token 用量保存在 IndexedDB，支持历史会话、消息编辑/删除/分支和上下文自动 Compact；运行中切换历史不会中断原会话，其他会话仍可独立发送并并行运行。后台会话需要 Ask 回答或工具审批时只在历史列表显示待确认图标，切回对应会话后才弹窗；Compact 过程会作为不发送给模型的系统事件保留在历史中。
- 对话输入区的发送按钮左侧可设置 `default`、`minimal`、`low`、`medium`、`high` 推理强度，选择按 AI 连接保存；`default` 不向接口发送推理强度字段。
- AI 工具只可访问连接配置中的白名单目标（本地或 SSH）。Shell 支持命令预览、按需授权和可记忆的命令前缀规则；本地 Shell 配置为 PowerShell/pwsh 且未显式设置执行模式时，会在首选项额外参数之后补充默认 `-Command`。Read 可按 `startLine`–`endLine` 读取带行号的内容，Search 可在文件或目录中按多个关键字或正则查找命中文件，Write、Patch 可覆盖/追加写入或以 unified diff 修改文本文件。Patch 的 schema 和描述要求 `target`、`path`、`patch` 同时非空，并提供包含 `@@` hunk 头的最小合法示例。面对未知大小或尚未定位内容的文件，工具描述要求模型先 Search，再分段 Read；只有确认文件较短且需要完整上下文时才省略范围。工具描述也会引导模型优先使用专用文件工具而非 Shell 模拟文件操作；PowerShell 文件内容命令会被要求显式指定 UTF-8 编码。文件修改支持独立的按需授权和精确路径记忆规则。Ask 可在实现方向需要确认时展示带解释的候选项，第一项标记为推荐，并始终允许用户提交自定义答案。
- 每次工具调用都可设置 `timeoutSeconds`（默认 120 秒，范围 1–1800 秒）。停止按钮会取消 AI 请求、Compact、授权等待和执行中的工具；SSH 命令通过信号及关闭 channel 尽力终止。工具输出支持安全渲染 ANSI 颜色；Windows 本地 cmd/PowerShell 的工具描述会提示 AI 先切换为 UTF-8 输出编码。

### 应用数据与更新

- 首选项可管理终端、文件预览、Markdown、日志、状态栏和 AI 工具授权等行为。
- 连接配置、首选项和 AI 历史可选择性导出为 gzip 压缩 JSON（`.json.gz`），也可合并或替换导入。v2 备份默认排除 SSH/代理密码、WireGuard 私钥/预共享密钥、AI API Key 和敏感 Header；勾选「包含敏感信息」并再次确认后仍可完整导入导出这些密码和密钥。导入继续兼容 v1 gzip 备份，但不兼容旧的纯 JSON 文件。
- Windows 支持后台检查更新并安装唯一的 `.exe` 或 `.7z` Release 附件；安装 `.7z` 附件需要系统可执行 `7z` 或 `7za`。macOS/Linux 只提供版本详情入口。
- 应用界面默认禁止选择控件文字，只在输入框、日志、命令输出、Markdown、AI 正文等内容区域开放文本选择。

## Portable 模式

在可执行文件同目录放置名为 `PORTABLE` 的普通文件即可启用 Portable 模式。Windows 下的主要目录为：

```text
data/
├── webview2/ # WebView2 用户数据，包括 IndexedDB 和 localStorage
└── logs/     # 按天归档的应用日志
```

当前连接、主机指纹、首选项和 AI 历史统一保存在 WebView profile 内名为 `shell-go-data` 的 IndexedDB；文件书签和 Compose 项目列表等少量页面状态保存在同一 profile 的 localStorage。`preferences.json` 只可能作为旧版本首选项的迁移来源暂时存在，成功写入 IndexedDB 后会删除，不是当前持久化目标。

密码、代理密码、WireGuard 密钥、AI API Key 和敏感 Header 在 WebView profile 中未额外加密。遮罩输入只减少界面旁观风险，不改变本地存储边界；完整说明见[安全边界与审计](docs/security.md)。

Portable 模式不会自动迁移原有 WebView profile。用户选择的私钥、下载目录、导出文件和本地终端工作目录仍属于用户文件，不会被强制移动到 `data/`。

Windows 会把 WebView2 profile 指向 `data/webview2/`。macOS/Linux 当前只把后端日志及旧首选项迁移路径放到 `data/`，WebView 的 IndexedDB/localStorage 仍使用 Wails 的平台默认 profile，因此不能视为完整的前端数据便携模式。普通模式也使用 WebView profile 中的 `shell-go-data`，不会持续把首选项写入 JSON。

## Windows WebView2 排查

ShellGo 在启动 UI 前检查 WebView2 Runtime，最低版本为 `94.0.992.31`。遇到白屏或渲染进程崩溃时，可使用以下启动参数：

| 参数                                        | 行为                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `--diagnose`                                | 采集 Windows、WebView2、策略、安全软件、崩溃转储和相关事件信息后退出                       |
| `--disable-gpu`                             | 禁用 WebView2 GPU 加速                                                                     |
| `--webview-safe-mode`                       | 禁用 GPU，并使用隔离的 `safe` 用户数据目录                                                 |
| `--webview-disable-renderer-code-integrity` | 高级兼容模式：禁用 GPU、关闭 Renderer Code Integrity，并使用隔离的 `advanced` 用户数据目录 |

Portable 模式下，这两个兼容模式目录分别位于 `data/webview2/safe/` 和 `data/webview2/advanced/`。

## 远程环境要求

普通 SSH 终端与 SFTP 只要求远端提供可用的 SSH 服务。Docker 管理和 SSH 隧道还依赖 SSH 转发能力，建议检查远端 `sshd_config`：

```text
AllowTcpForwarding yes
AllowStreamLocalForwarding yes
```

远程端口转发如需监听 `0.0.0.0`、`::` 或其他非回环地址，还需要按实际策略配置 `GatewayPorts`、防火墙和云安全组。

Docker 管理要求当前 SSH 用户能够读写远端 Docker socket（默认 `/var/run/docker.sock`）。Compose 功能还要求远端安装 Docker Compose v2 插件或 `docker-compose` v1，并且项目文件位于远端主机上。

## 技术栈

| 范围         | 当前实现                                         |
| ------------ | ------------------------------------------------ |
| 桌面运行时   | Wails v2.15、Go 1.26                             |
| 前端         | Vue 3.5、TypeScript 6、Vite 8、Pinia 4           |
| UI 与可视化  | UnoCSS、ECharts 6、Material Design Icons         |
| 终端与编辑器 | xterm.js 6、Monaco Editor 0.56                   |
| Markdown     | marked、highlight.js、Mermaid、DOMPurify         |
| 远程能力     | `golang.org/x/crypto/ssh`、`github.com/pkg/sftp` |
| Docker       | Docker Go SDK 28；Compose 通过远端 CLI 执行      |
| 测试         | Go `testing`、Vitest 4、jsdom                    |

依赖的精确版本以 [`go.mod`](go.mod) 和 [`frontend/package.json`](frontend/package.json) 为准。

## 开发环境

- Go 1.26 或更高版本
- Node.js `>=22.12.0`，以及 npm `>=10`
- Go Task 3.45.3 或更高版本
- Wails CLI 2.15.x
- Git（构建版本号由 Git tag 和工作区状态计算）
- 对应平台的 Wails 原生构建依赖；Windows 运行时需要 WebView2，Linux 需要 GTK/WebKit2GTK 开发库

安装常用命令行工具：

```bash
go install github.com/go-task/task/v3/cmd/task@latest
go install github.com/wailsapp/wails/v2/cmd/wails@v2.15.0
```

## 开发与验证

```bash
# 首次克隆或锁文件变化后安装依赖
task setup

# 启动 Wails 开发模式（包含前端热更新）
task dev

# 运行格式检查、静态检查、前后端测试和前端生产构建
task check

# 构建当前平台桌面产物
task build
```

`task setup` 使用 `go mod download` 和 `npm ci` 按锁文件安装依赖。`task build` 只构建，不会安装依赖、执行 `go mod tidy` 或修改源码；前端构建会生成 `frontend/dist.zip` 并嵌入桌面程序，桌面产物位于 `build/bin/`。

### Task 任务

| 任务                    | 行为                                                       |
| ----------------------- | ---------------------------------------------------------- |
| `task setup`            | 执行 `go mod download` 和 `npm ci`                         |
| `task tidy`             | 单独执行 `go mod tidy`                                     |
| `task frontend:install` | 在 `frontend/` 按 lockfile 执行 `npm ci`                   |
| `task frontend:build`   | 构建前端并生成 `frontend/dist.zip`                         |
| `task frontend:check`   | 前端格式检查、类型检查、测试和生产构建                     |
| `task frontend:dev`     | 只启动 Vite 开发服务器                                     |
| `task dev`              | 启动 Wails 开发模式                                        |
| `task build`            | 构建当前 OS/ARCH                                           |
| `task build-all`        | 枚举 Windows/Linux/macOS × amd64/arm64 六个构建目标        |
| `task release`          | 使用 UPX 构建当前平台 Release                              |
| `task release-all`      | 使用 UPX 枚举六个平台/架构 Release                         |
| `task generate`         | 重新生成 `frontend/wailsjs` 绑定                           |
| `task test`             | 执行 `go test ./...`                                       |
| `task check`            | 非写入式检查、静态检查、前后端测试和前端生产构建           |
| `task fix`              | 格式化 Go/前端代码并运行固定版本 `modernize -fix`          |
| `task fmt:check`        | 非写入式检查 Go 格式                                       |
| `task fmt` / `task vet` | 格式化 Go 代码 / 运行 `go vet`                             |
| `task clean`            | 执行 `go clean`，并删除本地 Wails 产物、前端输出和资源归档 |
| `task version`          | 输出当前构建版本号                                         |

`release` 和 `release-all` 需要预先安装 UPX。`build-all`/`release-all` 只负责展开构建矩阵，宿主机仍需具备 Wails 对目标平台要求的 SDK、CGO 工具链和交叉编译条件。

版本号规则：当 `HEAD` 正好位于 tag 且工作区干净时，使用去掉 `v` 前缀后的 tag；其他情况使用 `0.0.0`。构建期间 Task 会临时更新 `wails.json`，并在成功或失败后恢复原文件。

## 目录结构

```text
.
├── main.go                 # Wails 启动与前端资源嵌入
├── internal/
│   ├── app/                # Wails 绑定入口与应用装配
│   ├── application/        # DTO 和应用服务
│   ├── domain/             # 领域实体
│   ├── infrastructure/     # SSH、SFTP、Docker、本地终端实现
│   ├── interfaces/wails/   # 前端调用适配层
│   └── pkg/                # 日志、首选项、应用数据等通用包
├── frontend/
│   ├── src/features/       # 按 AI、连接、Docker、文件等功能组织的页面与逻辑
│   ├── src/services/       # Wails 绑定的前端封装
│   ├── src/shared/         # 共享组件、composable 与工具
│   └── wailsjs/            # Wails 自动生成绑定
├── build/                  # Wails 平台资源、前端归档工具与构建输出
├── docs/                   # 架构与设计规范
└── Taskfile.yml            # 开发、测试和构建任务
```

## 设计文档

- [架构设计](docs/architecture.md)
- [安全边界与审计](docs/security.md)
- [设计规范](docs/design-system.md)
- [前端开发说明](frontend/README.md)
- [构建目录说明](build/README.md)

## 许可证

[MIT](LICENSE)