**文件**标签是 Explorer 面板的主视图 —— 项目里所有文件的虚拟滚动树,加上每文件查看器,以及 Cockpit 把代码片段喂给 AI 的内联评注面。

| 章节 | 内容 |
|---|---|
| [文件树](#文件树) | 导航、右键菜单、多根目录、忽略规则 |
| [代码查看器](#代码查看器) | 语法高亮、Vi 模式、文件内搜索、跳转定义 |
| [预览](#预览) | 图片、PDF、Markdown、JSON、CSV、音视频 |
| [评注](#评注) | 划词加评论 → 喂给 AI |

## 文件树

Explorer 面板（`Cmd+2`）是看项目文件和 Git 状态的入口。打开时顶部有 5 个 tab，每个 tab 用不同视角看同一份文件。

### 五个 tab

| Tab | 你看到什么 |
|---|---|
| **目录树** | 完整项目文件树，虚拟滚动 —— 再大的仓库滚起来都不卡。点文件在右侧打开；点文件夹展开。 |
| **搜索** | 项目级内容搜索。打字符串或正则，得到每个文件里的匹配行。 |
| **最近** | 你最近打开或编辑过的文件，新的在上。回到"我刚才看的是什么"最快的路径。 |
| **变更** | 你的 Git 工作区 —— staged、unstaged、untracked 文件。点任意文件看 diff；行里的控件做 stage / unstage / discard。 |
| **历史** | Git 提交日志。点任意提交展开详情（改了哪些文件 + diff）。 |

### 目录树 tab（默认）

标准树视图，特性：

- **虚拟滚动** —— 1 万文件的仓库也不卡。
- **按扩展名显示文件图标**，方便快速扫一眼。
- **文件夹展开 / 折叠** 单击；展开状态在刷新后保留。
- **单击选中**，单击文件在右侧 pane 打开。

#### 右键菜单

右键任意文件或文件夹弹出菜单，分两组,一气铺开,没有子菜单。

**文件操作:**

- **新建文件** —— 在这个目录下创建。
- **复制文件 / 复制文件夹** —— 把文件本身放进剪贴板,用于粘贴到树里别处。
- **粘贴到这里** —— 剪贴板里有东西时显示。
- **删除文件 / 删除文件夹** —— 操作前会有确认对话框。

**复制路径 / 名字** (5 项,每项点一下复制到剪贴板):

- **复制相对路径** —— 如 `src/utils/parser.ts`。
- **复制绝对路径** —— 如 `/Users/me/code/proj/src/utils/parser.ts`。
- **复制相对目录路径** —— 该文件所在目录的相对路径(文件用其父目录;文件夹用自身)。
- **复制绝对目录路径** —— 同上,绝对版。
- **复制文件名 / 复制文件夹名** —— 如 `parser.ts`。

### 变更 tab —— Git 工作区

三个分组：

| 分组 | 装什么 |
|---|---|
| **Staged** | 下次提交会带上的改动。 |
| **Unstaged** | 已改动但还没 stage 的文件。 |
| **Untracked** | Git 还没见过的新文件。 |

点任意分组里的任意文件，右侧 pane 显示它的 diff（见 [Diff 视图](/zh/docs/explorer/changes/#diff-视图)）。每行还有常用动作的快捷按钮：stage / unstage / discard。

### 历史 tab —— 提交日志

可滚动的提交列表，新的在上，带作者和短 SHA。点任意提交展开**提交详情面板**：完整消息、文件列表、逐文件 diff。

从 Blame 某行点"查看提交"也会打开这个视图 —— 见 [Blame](/zh/docs/explorer/history/#blame)。

### 快速打开文件

跟 tab 无关，在 Cockpit 任何地方按 **`Cmd+P`** 都能模糊匹配文件名跳过去。见 [快速打开文件](/zh/docs/explorer/search/#快速打开文件)。


## 代码查看器

在 Explorer 里点任意文件，Cockpit 在右边的**代码查看器**里打开它。默认只读 —— 带语法高亮、行号，没有意外。要编辑就一点切换或在 Vi 模式下打字。

这一页讲阅读、编辑、搜索、Vi。

### 你看到什么

- 左边**行号**永远在。
- **语法高亮** 覆盖所有常见语言 —— JavaScript / TypeScript / Python / Go / Rust / JSON / Markdown 等几十种。按文件扩展名识别。
- **默认只读** —— 可以滚动、选中、复制，但打字没反应，直到切到编辑模式。

### 编辑模式

Cockpit 的代码查看器有意做轻 —— 它是带编辑的快速查看器，不是完整 IDE 替代品。深度编辑工作还是留在 VS Code / Cursor / 你自己的编辑器。"就想改一行"用 Cockpit 够了。

| 动作 | 怎么做 |
|---|---|
| **进入编辑模式** | 在文件内容区点一下，或 Vi 模式下打 `i` |
| **保存** | `Cmd+S` —— 写回磁盘 |
| **放弃未保存的改动** | 从 Files tab 重新加载文件 |

文件有未保存改动时，标题显示一个小圆点。

### 文件内查找

`Cmd+F` 打开搜索栏。

| 选项 | 效果 |
|---|---|
| **纯文本**（默认） | 字面匹配 |
| **Regex** 开关 | 当正则处理 |
| **大小写敏感** 开关 | 区分大小写 |
| **整词** 开关 | 只匹配整词 |

输入至少 2 个字符，匹配就地高亮。上 / 下按钮在匹配间导航。

替换功能没内置 —— 要查找替换的话回你常用的编辑器做。

### Vi 模式

用 vi 键位的人，在代码查看器头部打开 Vi 模式开关。然后：

- `i`、`a`、`I`、`A`、`o`、`O` —— 进插入模式（`Esc` 回 normal）
- `h` `j` `k` `l` —— 移动
- `w` `b` `e` —— word 跳转
- `gg` / `G` —— 文件首 / 尾
- `0` / `^` / `$` —— 行首 / 行尾
- `dd`、`yy`、`p` —— 行级操作
- `v` / `V` —— visual 模式
- `/` —— 搜索（跟 `Cmd+F` 是同一个）

光标位置会被跟踪并在切 tab 时保留。

### 跳到特定行

几个入口会把你推到具体行：

- **Quick File Open（`Cmd+P`）** 然后点 —— 在文件顶部打开。
- **点 Blame 某行** —— 跳到查看器里那行。
- **点搜索结果** —— 跳到那个匹配。
- **点 Git 历史某文件** —— 在改动的行打开 diff。

`Cmd+P` **没有** `:line:col` 跳转语法。Vi 模式里可以按 vi 方式打 `:42` 回车跳到 42 行。


## 预览

在 Explorer 点一个文件，接下来发生什么取决于文件类型。源代码 Cockpit 用 [代码查看器](/zh/docs/explorer/file-tree/#代码查看器) 打开。少数几种文件类型走更丰富的**预览**：Markdown 渲染成文档、图片显示为图片、JSON 显示为可浏览的树。

### Markdown

点任意 `.md` 文件就看到它被渲染成文档 —— 标题、列表、表格、代码块、链接，全套。TOC（目录）在侧边栏，方便浏览长文档。

| 你能做什么 |  |
|---|---|
| **阅读** | 默认就是渲染过的 Markdown 视图。 |
| **加评注** | 选中任意一段文字加评注，跟在代码上加评注的方式一样。评注锚在你选的行上，跟代码评注一样呈现。 |
| **看源码** | 预览头部一键切到原始 `.md` 源码。 |

你拿不到：Mermaid 图渲染、LaTeX 公式。Markdown 里依赖这些的话，预览会在代码块里显示源文本，不会渲染图。

### 图片

点任意图片文件（`.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.svg` 等）在图片预览里打开。自适应可用空间。

### JSON

JSON 文件有专属预览，两种视图可切（默认 Raw，按需切到 Readable）：

- **Raw**（原始，默认）—— 文件纯文本带语法高亮。要复制或想看磁盘上的原样格式时用。
- **Readable**（可读）—— 格式化、缩进、每个 object 和 array 可折叠。值里能搜，定位某个 key 或字符串。

非常大的 JSON Readable 视图也保持响应 —— 折叠你不需要的部分。

### **没有**的预览（暂时）

下面这些 Cockpit 在代码查看器里以纯文本打开，没有专门预览：

- PDF
- CSV / TSV
- Office 格式（`.docx`、`.xlsx`、`.pptx`）
- 音频 / 视频文件
- 二进制文件（会显示"binary file"而不是试图渲染乱码）

要看这些用你平时的工具开。


## 评注

**评注**是 Cockpit 里给有意思的代码加书签的方式，也是把一组精选的代码引用交给 AI 而不用一行行复制粘贴的方式。选行、写备注、跨文件重复、然后把整包发到聊天里。

### 怎么加评注

任何能看代码的地方 —— 代码查看器、Code Map、Diff 视图、Markdown 预览 —— 用鼠标选中一段文字。选区旁边出现一个小浮动工具栏：

- **Add Comment** —— 弹出小文本框；打备注、保存。
- **Send to AI** —— 把你当前选区加上你加过的所有评注打包成格式化块，准备粘到聊天里。

评注锚在你选的行上。每条评注记录：

- 文件路径和行号范围。
- 你选中时文本的快照（之后文件改了你也还有原文）。
- 你写的备注。
- 创建和更新时间。

### 评注存在哪

评注存在你 Cockpit 数据目录下，按项目隔离。Cockpit 重启它们还在，不同步到任何地方 —— 是你当前项目的私人工作笔记。

### 评注列表

有个**评注**模态一次性显示当前项目所有评注 —— 按文件分组，附上每条评注指向的代码预览。从这里能：

- 点评注跳到对应文件和行。
- 编辑备注。
- 单条删除，或全部清空。

也是**一次性把全部发到 AI**的地方 —— 你花十分钟标了 6 个文件，想让 AI 一次吃完时用。

### "Send to AI" 实际怎么走

按 Send to AI 时，Cockpit 把你的评注格式化成 Markdown 块：

```
### Code References

[1] src/parser.ts:42-45
\`\`\`
for (let i = 0; i < items.length; i++) {
  // ...
}
\`\`\`
Note: 这是 O(n²) —— 需要重写成单次遍历。

[2] src/lexer.ts:120-128
\`\`\`
...
\`\`\`
Note: ...
```

这段文本**复制到你的剪贴板** —— Cockpit 不会自动注入到聊天。切到 Agent 面板、粘贴、在块后面打你的实际问题、发送。这个有意的复制步骤让你选哪个 chat tab 收引用、配什么问题。

### 在哪些地方能用

评注在这些界面可用：

- ✅ 代码查看器（普通源文件）
- ✅ Code Map / BlockViewer
- ✅ Diff 视图
- ✅ Markdown 预览（锚在渲染后的文本上，不是原始源码）

### 注意

- 评注是**纯文本** —— 备注正文不支持 Markdown 格式。
- 你编辑下方的代码时评注**不会移动**。在评注上方插 10 行后，行号范围仍指向原编号；保存的选中文本快照看起来对，但实时高亮可能偏。
- 内部用一个叫 `__chat__` 的虚拟文件给"想附上这段"的聊天内容直接加评注 —— 你正常看不到这些。

