# 桌面端使用指南

这篇文档介绍 Coder Studio 桌面端界面结构和使用方式。桌面端是功能最完整的使用方式。

![桌面端工作区](assets/screenshot-desktop-workspace-full.png)

## 这篇文档解决什么问题

了解桌面端界面布局、快捷键、专注模式和核心操作。

## 前置条件

- 已安装 Coder Studio 并成功启动（`coder-studio open`）
- 使用桌面浏览器访问（Chrome、Firefox、Safari 等）

## 桌面端界面结构

![桌面端四区域布局](assets/screenshot-desktop-workspace-full.png)

### 顶栏

顶栏显示当前所有工作区标签，以及常用操作按钮：

- 工作区标签（可点击切换）
- + 按钮（新建工作区）
- Quick Actions（搜索和命令面板）
- 终端面板切换按钮
- 文件面板切换按钮
- 设置按钮
- 全屏按钮

### 左侧面板

包含两个标签：

- **Files**：文件树，浏览和创建文件/文件夹
- **Git**：当前分支和变更列表

### 中央工作区

根据当前状态显示：

- 编辑器（打开文件时）
- Git 差异视图（查看某个文件的变更时）
- Agent 面板（无文件选中时）

### 底部终端面板

包含多个终端标签，每个工作区有独立的终端集合。

## 操作步骤

### 切换工作区

点击顶栏中对应的工作区标签即可切换。

### 新建工作区

点击顶栏的 **+** 按钮，在弹出的目录选择器中选择新项目目录。

### Quick Actions

点击搜索图标（或按 `Ctrl/Cmd + K`）打开命令面板，可以快速搜索命令、文件、切换设置等。

### 显示 / 隐藏面板

顶栏右侧的图标按钮可以快速切换左侧面板和底部终端面板的显示状态。

### 浏览文件

在左侧面板的 Files 标签下，你可以：

- 浏览项目文件树
- 点击文件打开到编辑器
- 点击文件夹展开/折叠

### 新建文件夹和文件

左侧面板顶部的工具栏有三个按钮：

- 新建文件
- 新建文件夹
- 刷新

点击对应按钮后会弹出输入框，输入相对于工作区根目录的路径。

### 查看 Git 状态

切换到 Git 标签可以看到当前分支名称和文件变更列表。文件前面的图标表示状态（新增、修改、删除等）。

### 获取远程分支

左侧面板标题里的分支名按钮会打开分支选择器，显示本地分支和远程分支。状态栏里的 **Fetch** 按钮会立即执行一次远程 `git fetch`，并刷新分支列表。

当页面处于前台、且当前工作区正显示在界面上时，Coder Studio 还会为这个活动工作区周期性执行远程 fetch，用来让分支选择器里的远程分支保持最新。

#### 高级：调整自动 fetch 周期

高级设置键 `git.autofetchPeriodSec` 控制活动工作区的周期性远程 fetch，默认值是 `180` 秒；设为 `0` 会关闭周期性 fetch，但不会影响打开工作区时的自动 fetch，也不会影响手动点击 **Fetch**。

当前设置页还没有这个高级键的图形化入口。如需手动调整，可以直接编辑本地状态目录里的 `settings.json`。默认路径通常是 `~/.coder-studio/data/state/settings.json`；如果你通过 `coder-studio config --state-dir ...` 改过状态目录，请使用你自己的路径。

```bash
node -e '
const fs = require("node:fs");
const path = require("node:path");
const file = path.join(process.env.HOME, ".coder-studio", "data", "state", "settings.json");
const doc = fs.existsSync(file)
  ? JSON.parse(fs.readFileSync(file, "utf8"))
  : { version: 1, settings: {} };
doc.version = 1;
doc.settings = { ...(doc.settings || {}), "git.autofetchPeriodSec": 60 };
fs.mkdirSync(path.dirname(file), { recursive: true });
fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
'
```

### 查看变更内容

点击 Git 列表中的某个文件，中央区域会显示差异视图。

### 创建会话

当没有文件处于编辑状态时，中央区域显示 Agent 面板。点击创建会话按钮，选择 Provider（Claude 或 Codex）即可启动。

### 切换会话

左侧会话列表中点击对应的会话卡片即可切换。

### 分屏

使用快捷键：

- `Ctrl/Cmd + D`：垂直分屏
- `Ctrl/Cmd + Shift + D`：水平分屏

### 查看和编辑文件

点击文件树中的文件，编辑器打开对应文件。编辑后使用 `Ctrl/Cmd + S` 保存。

### 打开终端

点击底部的终端面板，或点击顶栏的终端图标。

### Shell 终端和 Agent 终端的区别

- **Shell 终端**：你自己创建的终端，用于手动运行命令
- **Agent 终端**：Agent 会话对应的终端，显示 Agent 的执行输出

## 快捷键与专注模式

### 常用快捷键

| 快捷键 | 操作 |
|--------|------|
| `Ctrl/Cmd + K` | 打开命令面板 |
| `Ctrl/Cmd + S` | 保存当前文件 |
| `Ctrl/Cmd + N` | 新建工作区 |
| `Ctrl/Cmd + Shift + [` | 切换到上一个工作区 |
| `Ctrl/Cmd + Shift + ]` | 切换到下一个工作区 |
| `Ctrl/Cmd + D` | 垂直分屏 Agent 面板 |
| `Ctrl/Cmd + Shift + D` | 水平分屏 Agent 面板 |
| `F` | 切换专注模式 |

### 专注模式

按 `F` 键进入专注模式，会隐藏左侧面板和底部终端面板，只保留中央工作区。按 `Escape` 退出专注模式。

### 原生全屏

点击设置按钮右侧的全屏按钮可进入浏览器原生全屏。处于全屏时，同一位置的按钮会切换为退出全屏，按 `Escape` 也可以退出。

如果同时开启了专注模式和原生全屏，`Escape` 会先退出原生全屏，再退出专注模式。

## 常见问题

**Q：如何找回被关闭的面板？**
点击顶栏对应的面板切换图标即可。

**Q：快捷键可以自定义吗？**
可以。进入设置 → Shortcuts 页面自定义。

## 下一步

- [常见工作流](workflows.md) — 任务式操作指南
- [CLI 参考](cli.md) — 命令行命令速查
