# WispTerm

一款用 Zig 编写、由 libghostty-vt 驱动的现代 Windows & macOS 终端。

下载最新版本 在 GitHub 查看

支持 Windows 与 macOS（Apple Silicon & Intel）。Linux 版本正在开发中。

wispterm — pwsh
pwsh
wsl
ssh: workstation

    PS C:\Users\you> wispterm --theme Poimandres
      从 %APPDATA%\wispterm\config 加载配置
      字体：Cascadia Code（DirectWrite + FreeType）
      主题：内置 453 款
      就绪。

    PS C:\Users\you> git status
    当前分支：main
    工作区干净，无可提交内容

    PS C:\Users\you> ▌

## 为日常工作而生

WispTerm 在 Ghostty 的终端核心之上叠加了实用功能：分屏、标签、AI Agent 工具、文件浏览器、主题、背景图，以及可选的远程访问客户端。

### Ghostty 模拟内核

使用 `libghostty-vt` 解析 VT 序列与维护终端状态，行为与 Ghostty 高度一致。

### 原生字体栈

DirectWrite 字体发现 + 逐字符回退，FreeType 渲染，沿用 Ghostty 的字体度量。

### 分屏与标签

横竖分屏、标签栏、焦点跟随鼠标、均分尺寸、空间方向焦点切换。

### AI Agent 标签

AI Chat 可以变成桌面 Agent：读取终端快照、运行本地 Shell 命令（Windows 用 PowerShell，macOS 用 shell）、配合 WSL/SSH 会话、加载本地 Skills，在 WispTerm 内完成工具确认，并导出完整或 clean Markdown 记录。查看 AI 工作流，或看 使用案例。

### 内置 453 款主题

兼容 Ghostty 主题文件，默认 Poimandres。可以先在 主题预览页 查找，再到命令面板里切换。

### 背景图片

支持 PNG/JPG/BMP/GIF/TGA 壁纸，带逐单元格透明度混合，四种缩放模式。

### 文件浏览器与预览

浏览本地、WSL 与 SSH 文件，无需离开终端即可预览 Markdown、文本、CSV、TSV 与图片文件。

### 内嵌浏览器

WebView2 侧边面板打开 `http(s)` 链接（仅 Windows）。SSH 会话会自动建立 loopback 端口隧道。

### Kitty Graphics 协议

通过 `imgcat.py` / `pdfcat.py` 在远程 Shell 中显示内嵌图片与 PDF。

### 自定义 GLSL 着色器

兼容 Ghostty 的后处理着色器，效果同时作用于终端内容与背景图。

### 精灵图渲染

任意尺寸下都清晰的方框绘制、块元素、盲文图案与 Powerline 符号。

### 可选的远程访问

通过 Cloudflare 中继分享会话密钥，默认关闭——Shell 始终保留在本地。

### 配置热重载

按 `Ctrl`+`,` 编辑配置；保存即生效，无需重启。

## 安装

每个版本提供 Windows 与 macOS 预构建包，按平台和需求选择。

Windows · 推荐

### 便携版

单可执行文件——下载 zip，解压后直接运行 `wispterm.exe`。

最新版本 →
Windows · 含浏览器

### 便携版 + WebView2

额外捆绑 `WebView2Loader.dll`，用于内嵌浏览器侧边面板。

最新版本 →
macOS · Beta

### macOS DMG

经过签名与公证的 `.dmg`，支持 Apple Silicon 与 Intel，需要 macOS 13+。打开 DMG，将 `WispTerm.app` 拖入"应用程序"即可。

最新版本 →
源码

### 从源码构建

克隆仓库后用 Zig 构建。Windows 用 `zig build`，macOS 用 `zig build macos-app -Dtarget=aarch64-macos`。

    git clone https://github.com/xuzhougeng/wispterm
    cd wispterm
    # Windows
    zig build -Doptimize=ReleaseFast
    # macOS（Apple Silicon）
    zig build macos-app -Dtarget=aarch64-macos

## 一个文件搞定配置

WispTerm 使用 Ghostty 兼容的 `key = value` 配置文件。默认路径：Windows 为 `%APPDATA%\wispterm\config`，macOS 为 `~/Library/Application Support/wispterm/config`。按 `Ctrl`+`,`（macOS 用 `Cmd`+`,`）打开编辑；命令行参数会覆盖文件内的值。

    font-family            = Cascadia Code
    font-size              = 14
    cursor-style           = bar
    cursor-style-blink     = true
    theme                  = Poimandres

    window-width           = 120
    window-height          = 32
    scrollback-limit       = 10000000

    custom-shader          = path\to\shader.glsl
    background-image       = C:\Users\me\Pictures\wallpaper.png
    background-opacity     = 0.85
    background-image-mode  = fill

    # 可选的远程访问（默认关闭）
    remote-enabled         = false
    remote-server-url      = https://remote.example.com
    remote-device-name     = Workstation
    remote-session-key     = Workstation

    # AI Chat Agent 工具
    ai-agent-enabled       = true
    ai-agent-permission    = confirm   # confirm | full
    ai-agent-output-limit  = 16384

运行 `wispterm --help` 查看完整参数列表，或 `wispterm --show-config-path` 打印解析后的配置路径。

## 键盘快捷键

默认快捷键定义在 `src/keybind.zig`。模态浮层优先拦截按键。`Ctrl/Cmd` 表示 Windows/Linux 用 Ctrl，macOS 用 Cmd；`Alt/Opt` 表示 Windows/Linux 用 Alt，macOS 用 Option。`Ctrl`+``` 与 `Ctrl`+`Tab` 在所有平台保持 Ctrl。

打开命令面板 `Ctrl/Cmd` `Shift` `P`
新建会话（启动器）`Ctrl/Cmd` `Shift` `T`
新建窗口 `Ctrl/Cmd` `Shift` `N`
切换标签侧栏 `Ctrl/Cmd` `Shift` `B`
切换文件浏览器 `Ctrl/Cmd` `Shift` `Alt/Opt` `E`
向右分屏 `Ctrl/Cmd` `Shift` `O`
均分分屏尺寸 `Ctrl/Cmd` `Shift` `Z`
关闭面板 / 标签 / 窗口 `Ctrl/Cmd` `Shift` `W`
最大化 / 还原窗口 `Alt/Opt` `Enter`
按方位移动焦点 `Alt/Opt``←``↑``↓``→`
上一个面板 `Ctrl/Cmd` `Shift``[`
下一个面板 `Ctrl/Cmd` `Shift``]`
上一个标签 `Ctrl` `Shift` `Tab`
下一个标签 `Ctrl` `Tab`
跳转到第 1–9 个标签 `Alt/Opt` `1`…`9`
放大字号 `Ctrl/Cmd``+`
缩小字号 `Ctrl/Cmd``−`
复制选中内容 `Ctrl/Cmd` `Shift` `C`
粘贴文本 `Ctrl/Cmd` `V`
粘贴剪贴板图片 `Ctrl/Cmd` `Shift` `V`
打开配置文件 `Ctrl/Cmd``,`
显示 / 隐藏 Quake 下拉窗口 `Ctrl````

## 常见问题

### 默认 PowerShell 为什么不是管理员？

子 Shell 会继承 WispTerm 进程的权限级别。普通双击或开始菜单启动通常是非提升令牌（即使用户在 Administrators 组，UAC 下也是如此）。WispTerm 不会自动为新标签提权。

### 如何以管理员身份使用终端？

右键 `wispterm.exe` 或快捷方式，选择以管理员身份运行，该窗口内新建标签会继承提升后的令牌。若只需临时开一个提升的控制台，可在任意 Shell 中执行 `Start-Process pwsh -Verb RunAs`（会弹 UAC，且是新窗口，不会替换当前标签）。

### 如何实现选中即复制、右键即粘贴？

在配置文件（Windows：`%APPDATA%\wispterm\config`，macOS：`~/Library/Application Support/wispterm/config`）中设置 `copy-on-select = true` 和 `right-click-action = paste` 即可。如果你希望”有选区时右键复制、没选区时右键粘贴”，则把它改成 `right-click-action = copy-or-paste`。

### 如何兼容老堡垒机或老 SSH 服务器？

在配置文件中设置 `ssh-legacy-algorithms = true`。它会为仍依赖 `ssh-rsa`、`ssh-dss`、旧版 Diffie-Hellman KEX 或 CBC cipher 的主机补上兼容选项。

### 为什么 SSH 相对路径下载或拖拽上传找不到当前目录？

WispTerm 只有在远端 shell 上报 OSC 7 时，才能下载 SSH 相对路径，并把拖拽文件上传到当前交互 shell 的真实目录。如果没有 OSC 7，辅助 `ssh.exe` / `scp.exe` 命令会启动一个新会话，通常只能看到登录目录，而不是你 `cd` 之后的目录。请让远端 shell 输出 OSC 7；配置片段见 README 说明。

### AI Chat / Agent 的 prompt 长度上限是多少？

WispTerm 现在允许 AI Chat / Agent 输入框中的单次草稿最长达到 `65536 bytes`。这是你按 Enter 发送前的单条输入上限，不是整段对话上下文的总长度上限。

### 为什么手机上的 Remote 会沿用本地终端大小？

因为本地 WispTerm 是终端状态的权威来源：PTY、Ghostty VT 状态、scrollback、光标位置和 split layout 都在本地维护，再以 layout snapshot 和 output bytes 同步给浏览器。Remote Web 可以把面板重新排成适合手机的显示方式，比如只显示当前 surface，但目前不会创建一套独立的手机端 terminal grid。真正按手机宽度重排，需要改成本地终端跟着 resize，或新增独立的 remote PTY / viewport 模型。

## 致谢

- 原始项目：arya-s/phantty — 基于 Zig 与 libghostty-vt 的 Windows 终端核心。
- 终端模拟：ghostty-org/ghostty，通过 `libghostty-vt`。
- 图像解码：stb_image（随 Ghostty 依赖一并引入）。