---
sidebar_position: 3
---

# 终端功能

NyaTerm 的终端体验围绕“在同一个工作区里高频处理远程与本地会话”设计。它基于 xterm.js，但实际体验并不只是一块终端画布，还包括搜索、命令历史、建议、AI 辅助、可选增强项、录制和 SSH 辅助能力。

## 基础操作

### 搜索、复制与右键菜单

终端右键菜单可直接执行这些高频操作：

- 复制 / 粘贴
- 粘贴选中的文本
- 查找文本
- 在线搜索选中文本
- 按 provider 翻译选中文本
- 交给 AI Assistant 解释或分析
- 清屏 / 全部清除
- 全选

在 **设置 → 交互** 中，你还可以调整：

- **选中即复制**
- **右键粘贴**
- 单词分隔符
- 默认字符编码

### 回滚缓冲区、字体与缩放

- 回滚缓冲区默认保留 **10000 行** 输出
- 可自定义字体族、字号、普通字重、粗体字重、光标样式与闪烁
- 可通过菜单或快捷键放大、缩小、重置终端缩放；终端根节点会协调缩放，避免嵌套工作区重复处理
- **硬件加速**为可选项，默认并未开启；如果你希望对比渲染效果，可在 **设置 → 终端** 中手动切换

### 粘贴与输入兼容

- 终端可以按设置处理图片路径粘贴，适合把截图或本地图片路径快速带入命令行工具
- macOS 下如遇输入法组合文本、候选词或特殊按键行为异常，可在 **设置 → 交互** 中开启 IME 兼容选项
- 在 vim、less、top 等交互式程序中，NyaTerm 会抑制命令建议，避免历史建议覆盖程序自己的输入体验

## 命令历史与建议

NyaTerm 会为会话工作流提供两类辅助：

### 命令历史

- 自动记录终端输入过的命令
- 支持模糊检索
- 可从右侧的 **命令历史** 面板回看历史输入
- 搜索栏会保留近期查询，便于重复查找同一类日志或错误

### 终端查找

`Ctrl / Cmd + Shift + F` 会打开终端查找框。查找框支持：

- 上一个 / 下一个结果跳转
- 当前结果与总结果数提示
- 无结果、搜索中和正则错误反馈
- 重复使用近期查询，不必每次重新输入完整关键词

### 输入建议

输入时会基于历史命令给出建议，适合重复执行运维命令、构建命令或排障脚本。

如果你的历史里有很多超长命令、一次性脚本或噪音条目，可以在 **设置 → 交互** 中进一步控制：

- 是否启用命令建议
- 建议参与匹配的**最小历史命令长度**
- 建议参与匹配的**最大历史命令长度**

需要注意：

- 这两个长度过滤只影响**历史命令建议**
- 它们不会影响右侧命令历史面板中的已有记录
- 它们也不会影响**快捷命令**本身的可用性

## AI Assistant

NyaTerm 在右侧面板中内置了 **AI Assistant**，并且可以从终端上下文直接唤起。

### 常见用法

- **生成命令**：告诉它你想完成什么，由它生成命令卡片
- **解释最近输出**：针对当前会话最近的终端输出做说明，不必手动复制日志片段
- **解释选中内容**：对选中的日志、报错或片段做解释
- **分析错误**：把错误上下文交给 AI 生成修复建议
- **修复选中内容**：从选中报错推导下一步命令

### 命令卡片与风险控制

AI 返回的命令可以以结构化卡片形式展示，并带有风险等级。你可以根据 **设置 → AI** 中的配置决定：

- 哪些风险等级允许直接执行
- 是否开启风险检查
- 是否允许把生成命令保存为快捷命令
- 是否记录 AI 历史

### 终端内联输出

当 Agent 模式执行命令时，NyaTerm 可以捕获命令执行事件，并把摘要后的输出以内联形式展示在终端工作流附近，方便你连续跟进多步操作的结果。

这个行为由 **设置 → AI → Agent Settings** 中的 `Terminal Output Lines` 控制：

- `Terminal Output Lines` 表示每次 AI 执行命令后，在终端中额外展示多少行输出
- 设为 `0` 时，关闭终端内联输出展示
- 这个设置不会影响真实命令本身的执行，只影响 AI 工作流中的附加可视化反馈

### Provider 与模型

AI 能力支持：

- 内置 provider 配置
- 自定义 **OpenAI Compatible** provider
- 按模型启用 / 禁用
- 默认模型选择
- 上下文行数限制与超时控制

如果你准备在生产环境或受限网络下使用，建议先到 **设置 → AI** 完成 provider、模型和风险门槛配置。

更详细的 AI 助手功能说明见 [AI 助手](./ai-assistant)。

## 命令风险评估

NyaTerm 可以在你手动输入命令时进行实时风险评估。当检测到高风险命令模式（如 `chmod`、`chown`、`rm -rf` 等）时，会弹出风险提示，显示：

- 风险等级
- 命令说明
- 更安全的替代建议

你可以选择继续执行或使用替代命令。此功能需要在 **设置 → AI** 中开启 **命令风险检查**。

## 可选终端增强项

下面这些能力都需要你按需开启，而不是默认全部打开。

### 行号与时间戳 gutter

在 **设置 → 终端** 中可分别开启：

- **显示行号**
- **显示时间戳**

开启后，终端左侧会出现 gutter，用于辅助阅读长日志、命令输出或回放录制内容。

### 动作链接

动作链接默认关闭，开启后可识别并点击常见文本模式，包括：

- IPv4 地址，例如 `192.168.1.10`
- `host:port`，例如 `db.internal:5432`
- 压缩包文件名，例如 `backup.tar.gz`

注意：

- 需要先在 **设置 → 终端** 中开启 **动作链接**
- 打开链接时需要使用 **Ctrl / Cmd + 点击**，避免和普通选中操作冲突
- 三类 matcher 可以分别启用或关闭

### 关键词高亮

关键词高亮同样默认关闭。启用后，NyaTerm 会先应用内置规则，再叠加你的自定义规则。

内置规则覆盖的内容不只限于错误关键字，还包括：

- error / warn / success / info / debug 等常见状态词
- 日期时间
- 数字、大小、持续时间
- 地址、URL、UUID、版本号等结构化文本
- 提示符（`$` / `#`）

你也可以自定义规则：

- 自定义规则名称
- 分别设置深色 / 浅色主题颜色
- 每行填写一个匹配模式
- 可选择是否跨折行继续匹配

#### 导入自定义高亮规则

在 **设置 → 终端 → 自定义规则** 中点击 **导入**，可以从 JSON 文件导入自定义高亮规则。

导入会和现有规则合并，不会清空已有列表：

- 相同 `id` 的规则会被更新
- 不存在的 `id` 会追加为新规则
- `id` 为空时会自动生成
- `name` 为空或没有有效 `patterns` 的规则会被跳过

推荐的 JSON 结构如下，也兼容直接使用规则数组作为文件顶层：

```json
{
  "keyword_highlights": [
    {
      "id": "deploy-errors",
      "name": "Deploy Errors",
      "patterns": ["deploy failed", "rollback required", "fatal"],
      "color_dark": "#ff7b72",
      "color_light": "#cf222e",
      "enabled": true
    }
  ]
}
```

### 大输出保护

当某个会话输出量过大时，NyaTerm 会临时进入保护模式，优先保证终端可交互性。

在这个阶段，应用会暂时抑制部分高开销装饰能力，并提示已经跳过的排队字符数；待输出压力回落后再恢复正常显示。这个机制主要用于日志洪峰或持续刷屏的场景。

### 大输出 drain

终端输出现在会先经过批量 drain，再交给 xterm.js 渲染。这样在 `tail -f`、编译日志、压测输出等高吞吐场景下，界面会更稳定地保留输入响应、滚动和搜索体验。

这不是一个需要手动开启的设置，而是终端输出管线的默认行为。它会和大输出保护、行号 / 时间戳 gutter、命令建议等功能配合工作。

## SSH 相关辅助能力

### Keep-Alive

对 SSH 会话，可以在 **设置 → 终端** 中配置 Keep-Alive 间隔：

- 默认值为 **60 秒**
- 设为 `0` 表示关闭
- 适合降低长时间空闲连接被远端回收的概率

### 远程主机监控面板

NyaTerm 为 SSH 会话提供了四类右侧监控面板：**资源监控**、**GPU 监控**、**进程管理**、**Docker 管理**。它们有一些共同点：

- 只在当前是 **SSH 会话** 时才有意义，并且只绑定到真正处于活动状态的 SSH 会话
- 各自由 **设置 → 终端** 中的开关控制是否显示；关闭对应开关会同时隐藏它的活动栏图标
- 轮询间隔可调，范围为 **3 秒到 120 秒**
- 面板会在连续轮询失败若干次后停止刷新，避免对不支持的主机反复请求

#### 资源监控

远程资源监控默认开启。要看到数据，需要同时满足：

1. 当前是一个 **SSH 会话**
2. 在 **设置 → 终端** 中开启 **显示远程资源信息**

启用后，右侧 **资源监控** 图标会显示，面板会按设定间隔轮询主机信息；默认轮询间隔为 **3 秒**，可手动调整。

面板会显示的内容包括：

- 主机名、系统、架构、运行时长
- Load Average
- CPU 使用率
- 内存使用情况
- 网络吞吐速率

#### GPU 监控

**GPU 监控** 面板用于查看远端主机上的 NVIDIA GPU 状态，默认关闭，可在 **设置 → 终端** 中开启 **显示 GPU 监控**（默认轮询间隔 3 秒）。

面板会显示：

- 驱动版本与 CUDA 版本
- 汇总信息：GPU 数量、最高使用率、显存占用、最高温度
- 每张 GPU 卡：编号、型号、性能状态（pstate）、使用率与显存占用条，展开后可看 UUID、温度、功耗、风扇转速、空闲显存；使用率超过 **70% / 90%** 时会有不同的颜色提示
- 可搜索的 GPU 进程列表（按 PID、GPU 编号、用户或进程名过滤），按显存占用排序

如果远端没有 NVIDIA GPU 或缺少 `nvidia-smi`，面板会给出对应的空状态提示。

#### 进程管理

**进程管理** 面板显示远端主机的实时进程列表，默认关闭，可在 **设置 → 终端** 中开启 **显示进程管理**（默认轮询间隔 5 秒）。

主要能力：

- 进程总数与搜索框（可按 PID、用户、状态、命令、完整命令行过滤）
- 自适应布局，根据面板宽度增减列；可按进程名、PID、CPU%、内存%、用户排序
- 展开某个进程可查看 PID/PPID、用户、状态、CPU%、内存%、RSS、运行时长与完整命令行，并支持调整 nice 值（`-20` 到 `19`）后 **应用**（renice）
- 行操作菜单可复制 PID / 命令，或发送 `TERM` / `HUP` / `STOP` / `CONT` 信号；`KILL` 会先弹出确认对话框并展示对应的 `kill` 命令

若远端主机不支持进程查询，面板会给出单独的提示。

#### Docker 管理

**Docker 管理** 面板用于管理远端主机上的 Docker，默认关闭，可在 **设置 → 终端** 中开启 **显示 Docker 管理**（默认轮询间隔 10 秒）。

主要能力：

- 概览：运行中 / 已停止容器数、镜像数，标题栏显示 Docker 引擎版本
- 全局搜索，以及容器、镜像、数据卷、网络、Compose（可用时）等标签页，标签过多时收进 **更多** 下拉
- **容器**：按状态排序的虚拟化列表，行菜单可查看日志（在终端里运行 `docker logs -f`）、进入容器（打开 shell）、启动 / 停止 / 重启 / 杀死（确认）/ 删除（确认）；点击行可打开实时刷新的详情对话框
- **镜像 / 数据卷 / 网络**：按需加载，每行支持删除（确认）
- **Compose**：列出项目，展开后按需加载服务，支持项目级 up / restart / down 与服务级 logs / enter / up / stop / restart
- **更多** 菜单提供 `docker system prune`（危险操作，需确认）

日志与进入容器会发送到真实的终端会话中执行；删除、杀死、Compose down、prune 等破坏性操作都会通过确认对话框展示将要执行的具体命令。

## 翻译与在线搜索

在终端中选中文本后，你可以直接通过右键菜单：

- 使用自定义搜索引擎做在线搜索
- 使用已启用的翻译 provider 打开翻译对话框

### 搜索引擎

在 **设置 → 搜索** 中，你可以维护自定义搜索引擎列表，为它们设置：

- 名称
- URL 模板（使用 `%s` 占位）
- 图标
- 是否显示在搜索菜单中

### 翻译 provider

翻译 provider 的可见性取决于设置：

- **Google**、**Microsoft** 无需额外配置
- **DeepL / 百度 / 阿里 / 有道** 需要先在 **设置 → 翻译** 中填写凭据

## 录制与工作流配合

NyaTerm 支持会话录制，适合：

- 保留排障步骤
- 给同事复现问题
- 截取有时间顺序的终端示例

录制文件默认可保存到系统下载目录，也可以在 **设置 → 传输** 中为录制单独指定保存路径，便于把演示素材、排障日志和普通下载文件分开管理。

在 **设置 → 传输** 中，还可以进一步配置录制行为：

- **自动开始录制**：会话一打开就自动开始录制，避免对那些总是需要留档的会话忘记手动开启
- **包含时间戳**：在保存的录制文稿中写入时间戳，便于审计或把输出与实际时间对应起来

也可以在单个连接的表单中配置录制选项。适合把“生产堡垒机总是录制”“实验设备不录制”这类策略绑定到连接本身，而不是每次打开会话后手动切换。

如果你准备录制文档素材，通常可以把这些能力组合起来：

- 行号 / 时间戳 gutter
- 关键词高亮
- 动作链接
- 命令历史
- AI Assistant
- 资源监控

这样更容易拍出“终端在真实工作流中使用”的截图，而不是单独展示某个开关。