第 6 章 · SpectrAI 桌面端 v1.0.4终端与文件
SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 6 章
SpectrAI 内置了真实的 Shell 终端和文件管理器，让你无需离开应用就能查看 AI 的所有改动、运行命令、对比文件差异、预览文档和搜索代码。本章介绍终端面板、文件树、文件预览、AI 改动追踪、Diff 视图和全文搜索的使用方法。
6.1 概述
SpectrAI 的终端基于 node-pty 实现，在 Windows 上使用 ConPTY、macOS/Linux 上使用原生伪终端，提供真实交互式 Shell。文件管理器以树形结构展示项目目录，支持右键菜单、内联重命名、新建文件和拖拽引用，并能在标签内直接预览图片、PDF、Office 文档和 Markdown。
AI 修改文件时，SpectrAI 自动追踪变更——你可以在「会话改动」面板中查看 Diff，或直接打开内置终端跑命令。
6.2 核心概念
- PTY 终端：真正的伪终端，交互式命令（如
vim、top、pythonREPL）可正常使用，支持 ANSI 颜色和 256 色。 - 文件变更追踪：AI 通过工具修改文件时自动记录新增 / 修改 / 删除，标记同时出现在文件树节点和「会话改动」面板。
- Diff 视图：以类
git diff格式展示差异，新增行绿色、删除行红色、上下文行正常。 - 文件预览：图片、PDF、Office 文档、Markdown、HTML 都能在标签内直接预览，无需外部程序。
- 全文搜索：跨文件搜索支持正则、大小写敏感、全词匹配和 glob 过滤，结果可跳转。
6.3 打开和切换终端面板
6.3.1 唤出终端
按 Ctrl/Cmd+` 显示或隐藏终端面板。终端以标签页形式管理多个 Shell 实例。在工作格布局下，终端也可作为「终端视角」从左侧活动栏拖入主区（见 第 2 章）。
6.3.2 新建标签页
点击终端面板右上角的 + 新建 Shell 标签页。若检测到多个可用 Shell，点 + 右侧的下拉箭头可指定 Shell。新标签默认继承当前 AI 会话的工作目录，标签标题自动显示 Shell 名称。
6.3.3 切换与关闭标签
按 Ctrl+Tab 切换到下一个终端标签；右键标签选 关闭，或点标签上的 × 关闭当前标签。
6.3.4 重命名标签
右键点击标签页选 重命名，进入内联编辑输入自定义名称，方便在多个终端间识别。
6.3.5 关闭面板
点击终端面板右上角的折叠按钮，或再次按 Ctrl/Cmd+` 隐藏面板。面板状态会被记住，下次打开应用时恢复。
6.4 使用文件树
文件树位于界面左侧。打开或创建会话后，文件树自动显示该会话工作目录的结构。
6.4.1 展开与打开
- 单击目录：展开或折叠该目录。
- 单击文件：在右侧编辑器中打开该文件。
- 双击文件：用系统默认程序打开该文件。
6.4.2 文件筛选
文件树顶部有筛选输入框，输入关键词实时过滤文件名，未匹配项隐藏；点 × 清除筛选。
6.4.3 右键菜单
在文件或目录上右键打开上下文菜单：
| 菜单项 | 说明 |
|---|---|
| 新建文件 | 在当前目录下创建新文件，创建后自动打开 |
| 新建文件夹 | 在当前目录下创建新文件夹 |
| 重命名 | 进入内联重命名（也可按 F2） |
| 删除 | 移至系统回收站（也可按 Delete） |
| 复制名称 | 复制文件名到剪贴板 |
| 复制相对路径 | 复制相对项目根目录的路径 |
| 复制绝对路径 | 复制完整绝对路径 |
| 在资源管理器中显示 | 在系统文件管理器中打开所在目录 |
| 在 CMD 中打开 / 在 PowerShell 中打开 | Windows：用外部 CMD / PowerShell 在该目录打开 |
| 在终端中打开 | macOS/Linux：用外部系统终端在该目录打开 |
| 用系统程序打开 | 用系统默认程序打开（仅文件） |
| 刷新 | 重新加载当前目录内容 |
6.4.4 拖拽引用
把文件树中的文件拖到对话输入框，会生成文件引用卡片，AI 可直接读取该文件内容。
6.4.5 工作区模式
如果当前会话属于工作区（Workspace），文件树会显示工作区下所有仓库的目录树，主仓库标记 ★。
6.5 在编辑器中查看与预览文件
单击文件在右侧标签内打开。不同类型的文件按类型呈现：
- 代码 / 文本：Monaco 编辑器，支持查看、编辑与 Ctrl/Cmd+S 保存。
- Markdown：右上角切换 源码 / 双栏 / 预览 三种视图；预览中的文件路径可点击，直接跳转到对应文件。
- 图片：在标签内直接预览（浏览器不支持的格式如 HEIC 可用系统默认应用打开）。
- PDF：内置查看器（
spectrai-pdf://协议）内联渲染，无需外部程序。 - Office 文档：Word、PPT、Excel 可在标签内做轻量预览；点右上角按钮可用系统默认应用打开。
- HTML：可在标签内预览渲染效果。
6.5.1 文件标签右键菜单
在打开的文件标签上右键：复制文件路径、在文件树中定位、关闭其他 / 关闭左侧 / 关闭右侧 / 关闭已保存 / 关闭所有 标签页。
6.5.2 代码预览 AI 灰字补全
在文件预览的 Monaco 编辑器中，可以启用 Copilot 风格的 AI 灰字补全：模型以灰字预览补全内容，按 Tab 接受、Esc 拒绝。
- 入口：设置 → 模型分配 → 代码预览 AI 灰字补全，选择一个 Provider 即启用（默认关闭，仅支持 HTTP Provider，建议选延迟低的小模型）。
- 只读文件、超过 1MB 的大文件、以及
.env/.pem/.key等敏感文件不会触发补全。
6.6 追踪 AI 文件变更
6.6.1 会话改动面板
文件树顶部有「会话改动」面板，折叠时显示改动文件数量。展开后列出当前会话 AI 改动过的所有文件。
6.6.2 改动标识
| 标识 | 含义 |
|---|---|
| 绿色 新增 | 文件为 AI 新建 |
| 蓝色 修改 | 文件为 AI 修改 |
| 红色 删除 | 文件为 AI 删除 |
| 黄色警告 | 多会话同时修改了同一文件（并发冲突提示） |
文件树中对应节点右侧也会显示蓝色圆点，表示该文件已被当前会话的 AI 改动。
6.6.3 查看 Diff 与跳转
在「会话改动」面板中点击文件展开内联 Diff：新建文件显示「新建文件，暂无 diff 记录」，删除文件显示「文件已删除」，修改文件显示类 git diff 差异。点面板中的文件可直接打开源码，Diff 弹窗支持「打开源码第 N 行」跳转到对应位置。若 worktree 已清理或文件已删除，会提示无法打开源码。
6.6.4 子 Agent 文件改动汇总
在有子 Agent 的父会话里，对话区会聚合展示「子 Agent 汇总」条：按 Agent 分组列出各自改动的文件与新增 / 修改 / 删除计数，支持点击定位产物、查看差异。多会话或多 Agent 同时改同一文件时会给出并发提示。
6.7 对话产物预览
AI 在对话中产出的文件（产物）会以可点击的链接或产物卡片呈现。点击可在应用内直接预览图片、Markdown、HTML 等，或用统一的打开工具定位到文件路径，无需先到文件树里找。会话右侧还有常驻的产物面板，用多个标签管理本次会话生成的产物。
6.8 文件搜索
6.8.1 全项目搜索
按 Ctrl/Cmd+Shift+F 打开全项目搜索面板。搜索面板与文件树共享侧边栏空间，输入关键词后按 Enter 开始搜索，结果按文件分组显示。
6.8.2 搜索选项
搜索框旁提供切换按钮：正则表达式、区分大小写、全词匹配、文件过滤（glob）（如 *.ts 仅搜索 TypeScript 文件）。
6.8.3 查看与跳转
结果按文件分组，点文件名展开匹配行，点匹配行跳转到编辑器对应位置。
6.8.4 替换功能
点搜索面板的 显示替换 展开替换输入框：
- 逐文件替换：点文件右侧的 替换此文件中的所有匹配。
- 全部替换：按 Ctrl+Enter，替换前会二次确认（直接写磁盘、不可撤销）。
- 替换预览：开启替换模式后，每个匹配行下方显示替换后的预览。
6.8.5 快速打开文件
按 Ctrl/Cmd+P 打开快速打开对话框，以模糊搜索列出项目中所有文件。用 ↑↓ 导航、Enter 打开、Esc 关闭。
6.9 在终端中运行命令
6.9.1 切换 Shell
新建终端标签时，点 + 右侧下拉菜单选择 Shell。SpectrAI 会自动检测系统中已安装的 Shell 并显示在列表中；未检测到时显示「未检测到可用 Shell」。常见候选：
| 平台 | 可用 Shell（示例） |
|---|---|
| Windows | PowerShell、CMD、Git Bash、WSL |
| macOS | Zsh、Bash、Fish |
| Linux | Bash、Zsh、Fish、Sh |
6.9.2 复制与粘贴
- 复制：选中文本后按 Ctrl+C（未选中时 Ctrl+C 发送中断信号）。
- 粘贴：右键菜单或 Ctrl+V。
- 清屏：输入
clear（Unix）或cls（Windows）。
终端里的链接点击后走系统默认浏览器打开。
6.9.3 终端工作目录
新建终端标签默认工作目录为当前选中 AI 会话的工作目录；未选中会话时回退到用户主目录。
6.9.4 AI 驱动终端与手动终端
AI 在会话中通过 bash / shell 类工具自动执行命令，输出实时显示在对话视图中。终端面板是供用户手动交互的独立环境，AI 不会直接操作它。
6.10 配置项
| 字段名 | 类型 | 默认值 | 作用 | 入口位置 |
|---|---|---|---|---|
fontSize | number | 14 | 对话区字体大小（px），影响编辑器文字大小 | 设置 → 常规 |
fileIconTheme | string | "material" | 文件树图标主题：minimal / material / seti | 设置 → 常规 |
collapseProcessMessages | boolean | true | 折叠 AI 中间过程，只显示最终总结 | 设置 → 常规 |
aiInlineCompletionProviderId | string | "" | 代码预览 AI 灰字补全的 Provider（空 = 关闭） | 设置 → 模型分配 → 代码预览 AI 灰字补全 |
autoWorktree | boolean | false | 新建任务默认启用 Git Worktree 隔离 | 设置 → 常规 → 基本 → Git Worktree 隔离 |
6.11 常见问题
终端启动失败，提示「未检测到可用 Shell」
系统路径中找不到可用的 Shell 可执行文件。确认已安装至少一种 Shell（PowerShell、CMD、Git Bash 等），检查 PATH 是否包含 Shell 所在目录；Windows 用户可安装 Git for Windows（自带 Git Bash），然后重启 SpectrAI。
AI 修改的文件没有显示蓝色圆点
改动追踪依赖 AI 通过 SpectrAI 工具接口修改文件。如果 AI 通过系统命令直接改文件可能追踪不到。确认会话使用 SpectrAI 内置工具链，点文件树顶部 刷新，并检查「会话改动」面板是否处于折叠状态。
Office / PDF 文件预览不出来怎么办
Office 为轻量预览，复杂排版可能与原文有差异，点右上角按钮用系统默认应用打开即可看到完整效果；PDF 用内置查看器渲染，若文件损坏或超大，同样可用系统程序打开。
终端输出中文字符乱码
终端编码与 Shell 输出编码不一致。Windows 上用 PowerShell 或 Git Bash 通常能正确显示中文；用 CMD 可输入 chcp 65001 切到 UTF-8。
6.12 相关章节
- 第 2 章 项目与工作区 — Worktree 隔离、工作格视角与内置浏览器
- 第 3 章 AI 会话基础 — 会话改动追踪与后台任务在会话区的呈现
- 第 5 章 工具与 MCP — AI 如何通过工具读写文件
- 第 9 章 设置与快捷键 — 字体、图标主题、AI 灰字补全等设置项