mirror of
https://github.com/nyakang/nyaterm.git
synced 2026-11-15 00:08:07 +00:00
Kang
ec59a5dbe3
- Moved agent tool definitions and schemas into a new harness module, improving organization and maintainability. - Updated agent tool functions to utilize a shared registry for tool schemas, enhancing flexibility and reducing redundancy. - Introduced new fields in the AiRequestOptions and AiToolCall structs to support ephemeral context and thought signatures, improving the tracking of agent actions. - Enhanced the handling of tool calls in various AI provider request bodies, ensuring better integration with the new context management features. - Improved risk assessment logic to incorporate new agent approval decisions, streamlining command execution policies.
161 lines
8.0 KiB
Markdown
161 lines
8.0 KiB
Markdown
# 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 助手会提示可以自动分析该错误。
|