入门指南

本指南将引导你从安装开始，直至使用第一个终端并开展首次 AI 智能体会话。这些内容足以让你开始工作；各项功能的详细信息请参阅手册系列的其他部分（参见 手册概览）。

1. 什么是 VelaTerm

一句话概括：这是为 AI 智能体时代打造的终端管理工具。它将分散的终端会话整理成 项目 → 组 → 会话的层级结构，并将 Claude Code 和 Codex 等编程智能体视为核心组件——你可以实时查看它们是正在工作、请求输入还是已完成任务，重新打开会话后会自动继续之前的对话。再加上浏览器远程访问和 SSH 远程开发功能，你便可以随时随地掌控自己的会话。

2. 安装

请从 下载页面 获取适用于你平台的软件包：

该应用会自动检查更新（也有“检查更新…”菜单选项），因此能始终保持在最新版本。

3. 首次启动时：导入项目

首次启动时窗口为空，左侧边栏会提示你导入目录。点击侧边栏顶部的文件夹按钮（或按 ⌘O），选择工作目录——它将成为树中的第一个“项目”。也可以使用“从 Git 克隆”，直接通过仓库 URL 创建项目。

项目添加后，你可以在其下创建 groups（嵌套层级可任意深，例如 frontend / backend / testing），并在其中创建 sessions。树结构如下所示：

4. 打开你的第一个终端

有以下三种方式：

1. 按 ⌘T（在 Windows/Linux 中为 Ctrl+Alt+T）——即可立即打开一个临时终端标签页。终端一律是草稿：只存在于中间面板，不会加入树结构，关闭即丢弃，也正因如此才适合执行快速命令。
2. 在侧边栏把鼠标移到项目、组或会话那一行，点 ＋ 按钮 → “New Terminal Session”。建出来的还是同一种草稿，区别只是它从该节点的工作目录启动。组的右键菜单里也有这一项。
3. 当中间面板为空时，直接点击“Create Terminal”按钮即可。

5. 打开你的第一个 AI 智能体会话

右键点击项目或组 → “新建 Claude 会话”（该菜单还提供 Codex，其余选项则在“更多智能体会话”下）。VelaTerm 会在该项目的目录中启动 Claude Code，并自动注入其状态报告钩子：

从那一刻起，你将获得三项功能：

• 状态点：侧边栏中会话旁边的小点可实时反映智能体的状态——绿色表示正在工作，黄色表示需要你的操作（如提问或请求授权），洋红色表示它已回复且你已看到回复。无需再通过多个窗口逐一查看。
• 系统通知：当智能体停止运行并等待你的输入或确认时，系统会发出通知；而当你正在查看该会话时，则不会显示通知。
• 自动续传：关闭标签页——或退出整个应用程序——下次再次打开该会话节点时，对话会从上次中断的地方继续。如需全新对话，则需创建一个新的会话节点。

这要求已安装相应的 CLI。如果未安装，也不会导致问题：会话中会显示安装指南卡片，其中包含针对你所用平台的推荐安装命令、一键安装选项以及重试按钮。

6. 用户界面导览

• 左侧侧边栏：项目树 + 搜索框 + 四个顶部按钮（导入项目、从 Git 克隆、全局搜索、归档的会话）。
• 中间面板：标签栏 + 终端区域。标签栏的功能类似浏览器：默认情况下，点击树结构中的某个会话会复用当前标签页；切换离开的标签页会在后台继续运行；只有关闭标签页才会真正终止该进程。标签页还可以拆分为多个面板（向右按 ⌘D，向下按 ⌘⇧D）。
• 右侧面板：随当前会话变化，包含三个标签页——文件（文件树）、信息（基本信息、模型信息、使用情况、资源占用情况）以及 Git（分支与更改记录）。
• 状态栏：会话数量、当前会话状态、Git 分支信息、通知开关，以及全局的“进行中/待处理/已查看”计数器——点击其中一项即可将侧边栏筛选为处于该状态的会话。
• 标题栏右侧：浅色/深色主题切换、远程访问、连接到远程服务器、设置。

7. 后续学习方向

• 关于树结构与标签页的详细内容（拆分、归档、全局搜索、多选批量操作）：界面与会话管理。
• 终端功能（搜索、图片粘贴、Windows shell 选择）：终端使用指南。
• 不同智能体的功能差异、续传/分叉/权限模式：AI 智能体会话。
• 让智能体将子任务拆分为独立的任务树并并行处理：会话创建与 Git 协作。
• 在手机或其他设备上继续使用这些功能：远程开发与管理。