# AI 助手

NyaTerm 内置 AI 助手面板，可以从终端上下文、选中文本、文件操作或手动输入发起请求。它支持两种工作模式：**Ask** 和 **Agent**。

## 工作模式

### Ask 模式

Ask 是默认模式，处理单次问答：

- 生成命令
- 解释终端输出
- 分析错误
- 从选中文本推导修复命令

AI 返回的命令以结构化卡片展示，带有风险等级标注。

### Agent 模式

Agent 模式允许 AI 自主执行多步操作。它使用 ReAct 循环：观察终端输出 → 决定下一步命令 → 执行 → 再次观察，直到任务完成或达到步数上限。

Agent 模式的特点：

- 需要一个活跃的终端会话
- 每一步命令都会显示执行状态（运行中、已完成、失败、超时、需要审批、被安全策略阻止）
- 可在 **设置 → AI → Agent Settings** 中配置最大步数和单步超时
- 可通过 `Terminal Output Lines` 控制 AI 执行命令时在终端中内联展示多少行输出
- 高风险命令仍然需要人工审批后才能执行

## Agent 工具、计划与询问

Native Agent 与外部 MCP 共用能力契约、scope、风险评估、审批、输出分页与脱敏审计。Native 无需启动 MCP 服务或 helper；Claude/Codex 仍仅通过 MCP 使用能力。

Native 可查询环境与目标会话、执行终端命令、读取最近输出，使用 SFTP 列目录、查询属性和读取文本，并读取工具输出的后续分页。本阶段没有 SFTP 写工具。任务开始时固定可用目标，多目标调用必须明确选择目标。

多步骤任务可建立计划，使用稳定任务 ID 更新待办、进行中、完成或受阻状态；同时最多一个任务进行中。简单任务可直接完成。需要补充信息时，Agent 可提出 1–3 个问题，提供单选项或自由文本输入。答案不会自动提交；提交后在原 run 继续，取消则结束任务。切换会话保留等待状态。

每次工具决策（包括计划和询问）消耗一次 step 配额。达到上限后只能总结；等待审批或回答期间不计命令超时。最终回答明确标注已验证、未验证或受阻及验证说明，未完成的计划不能标记为已验证。

前台执行保留终端捕获，后台执行保留独立后端。quiet observation 的未知退出码、超时和输出丢失会明确呈现，不能当作成功退出。大输出按 run 或 MCP 连接隔离分页，结束任务、关闭连接或凭据失效时清理。

Run、计划和工具 transcript 仅保存在内存中，聊天历史保存展示文本，不恢复执行。设置、历史、审计和 MCP 协议格式保持兼容；能力审计不保存命令、输出、文件内容或用户回答。

## 会话管理

AI 助手支持多会话管理：

- **新建对话**：每次新建对话会创建独立的上下文
- **历史记录**：按时间分组（今天、昨天、最近 7 天、更早）浏览历史对话
- **搜索历史**：模糊搜索历史对话内容
- **删除会话**：清理不需要的历史记录

## 会话提及

在输入框中输入 `@` 可以提及其他终端会话，将它们的上下文引入当前 AI 对话。这在需要跨会话分析或对比时很有用。

## 命令卡片与风险控制

AI 返回的命令以结构化卡片展示，包含：

- 命令文本
- 风险等级（低风险 / 中风险 / 高风险 / 极高风险）
- 执行按钮或审批按钮
- 保存为快捷命令的选项

### 风险等级怎么定

一条命令的风险等级不是模型单方面说了算。NyaTerm 会取**模型自报等级**和**本地规则判定**中较高的一个作为生效等级，所以模型低估风险时本地规则仍会拦住它。命令卡片显示生效风险。

本地规则按四档划分，判定依据是命令的具体形态而不是命令名：

| 等级 | 命中示例 |
|------|----------|
| 极高风险 | `rm -rf /`、`mkfs`、`wipefs`、写块设备的 `dd`、fork bomb、`shutdown` / `reboot` / `poweroff`、停止 sshd |
| 高风险 | 任何 `sudo` 开头的命令、`rm -r` / `rm -f`、`chmod -R` / `chown -R`、包管理器安装卸载、`docker rm` / `system prune`、`kubectl delete` / `drain` / `apply`、`git reset --hard` |
| 中风险 | 裸 `chmod` / `chown`、重定向 `>` / `>>`、`cp` / `mv` / `mkdir` / `touch`、`git pull` / `merge`、`npm run`；未命中任何规则的命令也按中风险处理 |
| 低风险 | `ls`、`cat`、`ps`、`df`、`docker ps`、`kubectl get`、`git status` 等只读诊断命令 |

注意分档看的是命令形态：裸 `chmod` / `chown` 是中风险，带 `-R` 递归标志才升为高风险；`rm -rf /` 是极高风险，而 `rm -rf ./build` 是高风险。

你手动输入命令时也会走这套规则，见 [终端功能 → 命令风险评估](./terminal#命令风险评估)。

### 命令执行策略

生效等级决定命令能不能直接跑，取决于 **设置 → AI → Agent Settings** 里的 **命令执行策略**：

| 策略 | 行为 |
|------|------|
| 执行前确认 | 每条命令执行前都需要你确认 |
| 全自动 | 普通及敏感读取自动允许；仅分类明确且风险低于高风险的命令自动执行 |
| 智能放行 | 在全自动规则上进一步按 **智能模式自动执行上限** 收紧 |

所有 Native 模式下，未知或无法明确分类的命令以及高风险、极高风险命令均需审批。执行前确认模式对每条命令仅提供逐次批准；其他会话授权限定当前 run、目标、工具及相同参数。极高风险和破坏性操作始终逐次审批，不能由会话授权覆盖。审批后还会重新检查 scope、会话状态及执行禁用设置。

**设置 → AI** 中还可以配置：

- **智能模式自动执行上限**
- 是否开启命令风险检查
- 是否允许把生成命令保存为快捷命令

### 安全替代建议

当命令被判为高风险时，AI 可能会同时提供更安全的替代命令供选择。

## 最近输出与终端内联输出

AI 助手不仅能处理选中文本，也可以直接围绕“刚刚发生了什么”来工作。

- 在终端右键菜单中使用 **解释最近输出**，可以把当前会话最近的终端输出直接发送给 AI
- 在 Agent 模式下，AI 执行命令时会捕获命令执行事件，并把摘要后的输出以内联片段形式反馈到终端工作流附近
- `Terminal Output Lines` 决定这类终端内联反馈最多展示多少行；设为 `0` 则关闭

## 推理内容

如果使用的模型支持推理通道（如 DeepSeek R1、QwQ 等），AI 助手会在回复中展示推理过程。推理内容默认折叠，可以展开查看 AI 的思考链路。

## Provider 与模型配置

在 **设置 → AI** 中管理 provider 和模型：

### Provider 配置

- 支持内置 provider（OpenAI、Anthropic、Google、DeepSeek 等）
- 支持自定义 **OpenAI Compatible** provider
- 每个 provider 需要配置 API Key 和可选的 Base URL

### 模型管理

- 从 provider 拉取可用模型列表
- 手动添加 provider 未自动返回的模型
- 按 provider 与凭据分组显示
- 可单独启用 / 禁用每个模型
- 选择默认模型

### 其他设置

- **上下文行数**：发送给 AI 的终端输出行数上限
- **请求超时**：单次 AI 请求的超时时间
- **记录历史**：是否保存 AI 对话历史
- **敏感信息脱敏**：发送前对敏感内容做处理

## 从终端和文件浏览器唤起

AI 助手不只能从面板手动输入，还可以从以下入口唤起：

### 终端右键菜单

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

### 文件浏览器右键菜单

对 SFTP 文件浏览器中的文件，可以通过右键菜单将文件内容发送给 AI 进行分析（受文件大小限制，可在设置中调整上限）。

### 错误自动检测

当终端输出中检测到错误模式时，AI 助手会提示可以自动分析该错误。