---
title: "文件与笔记"
description: "通过 SFTP 浏览、预览和传输文件，把文件拖放或粘贴进远程终端，绑定 Obsidian 兼容库的 Markdown 编辑器，以及保存的片段。"
url: "https://docs.closex.org/zh/thinkterm/files-and-notes.html"
markdown_url: "https://docs.closex.org/zh/thinkterm/files-and-notes.md"
site: "CloseX Docs"
product: "ThinkTerm"
language: "zh-Hans"
last_updated: "2026-11-08T12:04:16.000Z"
alternates:
  en: "https://docs.closex.org/thinkterm/files-and-notes.md"
  zh-Hans: "https://docs.closex.org/zh/thinkterm/files-and-notes.md"
  ja: "https://docs.closex.org/ja/thinkterm/files-and-notes.md"
---

# 文件与笔记

> **文档编写中**
> 部分内容可能尚不完整。

终端旁边还有三个面板：一个本地与远程目录一视同仁的文件浏览器，一个绑定到你已有笔记库的 Markdown 编辑器，以及一个保存命令用的片段库。同一个右侧栏还可以放[状态](https://docs.closex.org/zh/thinkterm/agents.md)面板，以及[插件](https://docs.closex.org/zh/thinkterm/plugins.md)加进来的面板。

## 文件

文件浏览器为当前 Project 显示一棵目录树，为你选中的文件提供语法高亮预览，还有一个在整个 Project 里搜索的过滤框。从别处拖到面板上的文件会被复制进它落下的那个文件夹，把一行拖到终端上会粘贴它的路径；`打开方式` 可以把文件交给另一个应用处理。

过滤不是模糊匹配。它匹配文件名中的一段，不区分大小写；查询里一旦出现 `/`，就改为匹配相对于 Project 的路径，所以 `src/main` 能匹配 `src/main.rs`，却匹配不到 `tests/main.rs`。

### 搜索会看哪些文件

搜索按同一套规则遍历 Project，本地和远程都一样：

- 包含 `.github` 这类点文件
- 不跟随符号链接
- 跳过版本控制、构建和依赖目录：`.git`、`.hg`、`.svn`、`target`、`node_modules`、`.next`、`.nuxt`、`.turbo`、`.cache`、`dist`、`build`、`coverage`、`vendor`、`.venv`、`venv` 和 `__pycache__`
- Project 自己的 `.gitignore` 排除的内容不计入，除非把 `right_sidebar_search_respects_gitignore` 设为 `false`
- 遍历到 100,000 个条目就停下

`.gitignore` 这一条只作用于搜索：被忽略的文件仍然在树里，只是搜索时不会出现。被跳过的那些目录则不同 —— 本地 Project 的目录树里也不显示它们。

过滤框背后的那份列表在你第一次搜索时才建立，而不是面板一打开就建，所以大 Project 的第一次查询要稍等片刻。

### 目录树

面板显示期间，本地 Project 的目录树每 90 秒重新读一次。刷新按钮会立即重读，本地远程都一样。

每个 Project 记着自己的视图：切到别的 Project 再切回来，你展开过的文件夹、选中的文件、滚动到的位置和过滤框里的内容都会回来。这份记忆在 ThinkTerm 运行期间有效。

右键点一行，给出的都是针对这个文件本身的操作：

| 本地行 | 远程行 |
|---|---|
| `打开`（仅文件），用系统默认应用 | `下载`（文件和文件夹） |
| `在访达中显示` —— Windows 上是 `在文件资源管理器中显示`，Linux 上是 `在文件夹中显示` | `新建文件夹`（仅文件夹） |
| `复制路径` | `复制路径` |
| `重命名…` | `重命名…` |
| `移到废纸篓` | `删除…` |

重命名直接在行内进行；远程重命名遇到已被占用的名字会拒绝。

### 预览

选中一个文件，它的预览会在目录树左边一块更宽的窗格里打开。拖动两者之间的边缘可以改变宽度，ThinkTerm 会记住这个宽度。

预览显示什么，取决于文件：

| 文件 | 预览 |
|---|---|
| 文本 | 前 1.5 MiB，带语法高亮。更长的文件会注明 `预览已截断至 1.5 MiB` |
| 图片 —— PNG、JPEG、GIF、WebP、BMP、ICO、TIFF | 图片本身，文件最大 16 MiB，画面最多 1600 万像素 |
| 含有零字节的任何文件 | `Preview unavailable for binary file` |
| 不是 UTF-8 的文本 | `Preview unavailable for non-UTF-8 text` |

不超过 64 KiB 的文件打开时就已经上好色；更大的文件先以纯文本立即显示，过一会儿再补上颜色。文本预览可以左右滚动：用横向手势，或按住 Shift 滚动鼠标滚轮。

预览标题栏上有打开按钮，上面写着 `使用 … 打开` 和一个应用的名字：你上次从它的列表里选的那个；还没选过时，是这个文件的默认应用。旁边的箭头列出能打开这个文件的其他应用，以及 `使用其他应用打开…`，用来挑选电脑上的任意应用；这样挑出来的应用会加入列表。你选中的应用此后会成为每个文件这个按钮上的应用，直到你再选别的。

右键点本地预览，有 `复制`、`全部复制`、`复制路径`、显示位置那一项和 `打开方式`。远程预览则是 `复制`、`全部复制`、`复制路径` 和 `下载`：服务器上的文件得先下载下来，别的应用才能打开它。

### Markdown 预览

Markdown 文件默认以渲染后的样子预览，而不是源码。预览标题栏上的一个按钮在两者之间切换，这个选择会沿用到下一个文件。

渲染视图可以选中和复制，能打开链接，并在 Project 的文件之间解析 `[[wiki 链接]]`。匹配到多个文件的 wiki 链接会弹出一份候选清单让你挑；一个也匹配不到的则什么都不做，因为预览从不创建文件。代码块上有一个复制整块的按钮，和一个把它折叠起来的按钮。预览从不从网络上取图片。

### 在 Markdown 预览里编辑

预览能整份装下的本地 Markdown 文件 —— 不超过 1.5 MiB，且不是只读 —— 可以直接在渲染视图里编辑，按键与笔记相同（见[键盘](#键盘)）。点一下任务的复选框就会勾选，右键会先给出笔记的编辑菜单，再接上文件自己的菜单。Esc 把键盘还回去。远程文件、比预览能装下的更长的文件，以及没人有权写入的文件，仍然是只读的。

改动的保存方式与笔记相同：每次编辑后不久保存一次；离开这个文件、切换到源码视图或关闭窗口时再保存一次。同一个文件的笔记和预览，不论在本窗口还是别的窗口，共用同一份文本。使用 Windows 换行符的文件会保留它们。

文件每隔几秒检查一次。如果别的程序在它在这里打开时写了它，那一版会替换预览里的内容；检查开始之后你又输入过的除外。文件长到超过预览能装下的大小，或者被删除，会按它现在的样子重新加载。

保存失败，或文件变成了读不出来的样子时，编辑就会停止。文字上方有一行说明原因 —— 以 `没能保存，已停止编辑` 或 `文件被改过，现在读不出来，已停止编辑` 开头 —— 文字留在屏幕上，可以复制出去。读不出来的文件绝不会被覆盖。预览会一直留着，直到你离开它：点返回或关闭窗口，会先显示这一行，再来一次就放弃这些改动。

### 通过 SFTP 访问远程文件

当一个 Project 位于远程主机上时，同一个浏览器会通过 SFTP 工作。它支持：

- 浏览远程目录
- 上传与下载，包括整个目录的递归传输
- 传输失败后重试
- 把文件直接拖到远程终端上以上传到那里
- 用同一个过滤框搜索远程 Project

默认情况下，面板不会自己去连主机。在你开口之前，它显示 `未连接` 和一个 `连接` 按钮；拨号时显示 `正在连接…`，失败了显示 `连接失败` 和 `重试`。一旦你连过某台主机，ThinkTerm 在本次运行期间会自己重连它，重启之后再问你一次。把文件拖放或粘贴进那台主机的终端，也算开口。

也可以让某台主机不等你开口就连接。在它的[编辑器](https://docs.closex.org/zh/thinkterm/remote.md#远程主机页面)里打开 `文件面板自动连接` 后，只要那台主机的终端出现在旁边，面板就会连上去，不论这个终端是直接连到主机，还是经由它的 ThinkTerm Connect 域。这个开关按主机设置，不打开就是关闭的。它只对 ThinkTerm 自己列表里的主机提供；只出现在 `~/.ssh/config` 里的主机，始终要等 `连接`。

传输从不覆盖服务器上的任何东西。上传时名字已被占用，会直接失败而不是替换那个文件；文件夹上传遇到第一个这样的名字就停下，并说明进行到哪里。下载也从不覆盖你电脑上的任何东西：名字已被占用时会加上 ` (1)`、` (2)` 等，文件加在扩展名之前，文件夹加在末尾。

下载保存到 `设置 › 工作区 › 下载文件夹`。若未指定，或者点过 `使用系统下载文件夹`，ThinkTerm 就用系统的下载文件夹。

### 搜索远程 Project

远程 Project 不是通过 SFTP 一个目录一个目录地遍历的。第一次搜索时，ThinkTerm 会请那台主机自己列出 Project：通过文件浏览器已经持有的那条 SSH 连接，在那里运行 `thinkterm list-files`。之后的输入只在返回的列表里搜索；列表放久了，会重新列一次。远程文件的 Markdown 预览也用同一份列表来解析 wiki 链接。

所以搜索需要主机上装有 ThinkTerm，而且版本新到带有 `list-files`。主机设置了 `remote_wezterm_path` 时 ThinkTerm 就运行它，否则在常见的安装位置里找。没有 ThinkTerm 或版本太旧的主机，会得到一条请你更新那里的 ThinkTerm 再刷新的提示，而不是一个空结果。列表超过 20 秒还没完成就会放弃。

### 空闲连接会自行关闭

长时间未使用的 SFTP 连接会被关闭，而不是一直挂着。超时时间在 `设置 › 工作区 › 远程文件连接空闲超时`，默认为 **15 分钟**，可在 1 到 120 分钟之间设置。超时之后重新打开远程目录会直接重连，不再询问 —— 只要连上之后 ThinkTerm 没有重启过；不会丢失任何东西。

### 不只是看，也能改

文件可以改名、复制路径、删除 —— 本地和远程一样。新建文件夹只能在远程主机上做，新文件夹起名为 `untitled folder`；本地请用访达或你的文件管理器。

有一个不对称值得记住：本地删除是把文件移进废纸篓，而通过 SFTP 删除是永久的，因为远端没有废纸篓可以兜底。这种情况下 ThinkTerm 会先问一句，并数清将要消失的条目 —— 一个文件夹算它自己加上它下面的全部内容。

## 拖放与粘贴文件

从访达或文件管理器拖来的文件最终去哪里，取决于它落在什么上：

| 落在 | 结果 |
|---|---|
| 笔记编辑器上，且它持有焦点 | 图片被复制进库，并在笔记里加上链接 —— 见[笔记里的图片](#笔记里的图片) |
| 本地目录树 | 复制进指针下的文件夹；落在文件行上，指的是装着它的那个文件夹；落在空白处，指的是 Project 根目录 |
| 远程目录树 | 按同样的规则，通过 SFTP 上传到指针下的文件夹。面板必须先连上 |
| 当前 Project 所在远程主机上的终端 | 上传到远程拖放目标，并把上传后的路径粘贴到提示符处 |
| 其他终端 | 粘贴本地路径，按 shell 的规则加引号 |

往本地目录树复制时，如果会撞上已有的名字，就会停下，对整次拖放只问一次：`替换 N 个现有文件`、`跳过 N 个现有文件`，或者 `取消复制`。

### 拖到终端上即上传

拖到远程会话的终端上，如果只是粘贴一个本地路径，那毫无用处，因为服务器上没有这个文件。所以当这个终端和当前远程 Project 属于同一台主机时 —— 无论走 ThinkTerm Connect 还是普通 SSH 主机 —— ThinkTerm 会先上传文件，再粘贴它们在服务器上的路径，按 POSIX 规则加引号，不管 `quote_dropped_files` 怎么设。Mosh 会话的终端运行在你的电脑上，所以拖到那里仍然粘贴本地路径。

文件会传到 `设置 › 工作区 › 远程拖放目标`，默认是 `~/ThinkTerm_Uploads`，服务器上没有这个文件夹时会自动创建。把它设成 `cwd`，就改为上传到 shell 的当前目录，以 shell 最近一次报告的为准；还没报告过当前目录的 shell，文件会去 `~/ThinkTerm_Uploads`。拖过去的文件从不覆盖任何东西：名字被占用时依次变成 `name (1).ext`、`name (2).ext`，粘贴的是它实际得到的那个路径。拖过去的文件夹会整个上传。

### 粘贴文件和图片

粘贴时，除了文本，还会从剪贴板读取文件和图片。在当前远程 Project 所在主机的终端里，在访达或文件管理器里复制的文件，会像拖过去一样上传；复制的图片 —— 比如一张截图 —— 会转成 PNG，以 `Pasted 2026-10-02 at 14.03.05.png` 这样带粘贴日期和时间的名字上传，再粘贴它的路径。在本地 shell 里，复制的文件会粘贴成加了引号的本地路径，复制的图片则什么都不做。文本照旧粘贴。

### 文件夹与传输条

文件夹会在任何东西动起来之前被完整读一遍，所以工作量事先就知道；往本地目录树复制时，还会在写入第一个字节之前找出所有重名。超过 1,000 项的文件夹会先问一句 —— `上传 N 个项目` 或 `下载 N 个项目` —— 因为服务器上的每一项都要一次往返。读取在电脑上的文件夹到 100,000 项为止，服务器上的到 10,000 项为止。文件夹里的符号链接不会被跟随，而是跳过，并在传输里说明跳过了几个。

传输和本地复制会在文件面板的一条传输条里显示为带进度的行。已完成的行会给新行让位，正在进行的传输从不被挤掉，放不下的行只计数、不显示。点一下正在进行的行会取消它；点已完成的行会给出 `重试` 和 `关闭`，没有可重试的内容时直接清掉。

## 笔记

笔记面板是一个 Markdown 编辑器，绑定到一个**库** —— 一个存放普通 Markdown 文件的目录，采用 Obsidian 使用的那种结构。不导入、不转换：ThinkTerm 只记录绑定关系，并就地编辑那些文件。同一个库可以同时在 Obsidian 里打开。

编辑器把 Markdown 画成它读起来的样子，并在光标所在之处重新显示语法，方便编辑。它支持：

- 标题、强调、~~删除线~~、列表和引用
- 任务列表，画成复选框
- 表格
- 语法高亮的代码块
- 分隔线
- 笔记开头的 front matter 块，显示为一组属性
- `> [!warning]` 这样的 callout，画成卡片
- `#标签` 和 `^my-block` 这样的块 ID
- 图片，包括从远程 URL 加载的图片
- `[[wiki 链接]]`，在整个库范围内解析；`![[嵌入]]` 会内联渲染
- 拼写检查，仅限 macOS
- 自动保存，每次编辑后不久

文字按文档的样子排：正文用常规字重，粗体用半粗，标题更大且加粗；标题、列表和空行前后留有间距，行内代码衬在圆角底色上。表格的单元格会换行，装在圆角边框里；只有连最长的词都放不下时，表格才会左右滚动。文件面板里渲染后的 Markdown 预览也是这样排的。

点开一个没有对应文件的链接，会按它的名字创建那篇笔记 —— 除非这个名字在当前平台上不能作为文件名，那时 ThinkTerm 宁可拒绝，也不会背着你换一个名字。

它新建的笔记只有你自己可读。已经存在的文件保留原有权限，所以你有意设成同组可读的库不会被改动。

因为库就是一个普通目录，你可以随意移动它、同步它、或者把它纳入版本管理。如果 ThinkTerm 打不开某个库，它会说明原因，而不是显示一个空面板：找不到的文件夹会报为丢失 —— 被移动、改名还是删除，它无法区分；能找到但读不了的，会报为权限问题，并给出你所在平台该检查什么，以及 `选择其他库…`、`新建库…` 和 `重试` 三条出路。

### 绑定一个库

一个 Space 绑定一个库。还没有库时，笔记面板给出两个按钮：`选择现有库…` 让这个 Space 指向一个你已经在用的笔记目录，`新建库…` 为新库挑一个位置，目录不存在时会创建它。无论哪种，绑定目录之外的任何内容都不会被触碰。之后要换，用笔记菜单里的 `选择其他库…`。

在一个 Space 里，每个 Project 记着自己上次打开的笔记，所以切换 Project 也会切换笔记。一个 Project 第一次打开笔记时，会显示库里的一篇笔记；库里一篇都没有时，则新建 `Untitled.md`。

### 笔记菜单

笔记工具栏上的菜单按钮里有：

| 菜单项 | 作用 |
|---|---|
| `新建笔记` | 在库的根目录创建 `Untitled.md`，名字被占用时依次是 `Untitled 2.md` 等，并打开它 |
| `保存` | 立即保存，不等自动保存 |
| `源码模式` | 显示纯 Markdown，而不是画出来的笔记；开启时打勾 |
| `显示库侧栏` / `隐藏库侧栏` | 在笔记旁边显示或隐藏库里的文件列表。面板窄到放不下两者时，这一项变成 `显示库` / `隐藏库`，用列表替换掉笔记 |
| `选择其他库…` | 把这个 Space 绑定到另一个目录 |
| `在访达中显示` | 在访达中显示库 —— Windows 上是 `在文件资源管理器中显示`，Linux 上是 `在文件夹中显示` |

在库的列表里选一个 Markdown 文件，会把它作为笔记打开；其他文件用各自的默认应用打开。

工具栏上的另一个按钮把笔记移到侧栏左边一块更宽的窗格里，库的列表留在侧栏，再点一次移回来。ThinkTerm 会记住你的选择；拖动之后，也会记住窗格的宽度。在宽窗格里，正文栏最宽到 `note_reading_max_width`，默认 820，并居中显示。

### 键盘

macOS 上快捷键用 Cmd；Windows 和 Linux 上用 Ctrl。

| 按键 | 作用 |
|---|---|
| Cmd S | 立即保存 |
| Cmd E | 在画出来的笔记和源码之间切换 |
| Cmd B / Cmd I | 用 `**粗体**` / `*斜体*` 包住选区 |
| Cmd Z / Shift Cmd Z | 撤销 / 重做；Windows 和 Linux 上 Ctrl Y 也是重做 |
| Cmd A、Cmd C、Cmd X、Cmd V | 全选、复制、剪切、粘贴 |
| Home / End | 行首 / 行尾 |
| macOS 上 Cmd ← / Cmd → | 到所见这一行的行首 / 行尾：在自动换行的段落里，是这一行而不是整个逻辑行 |
| macOS 上 Cmd ↑ / Cmd ↓，其他平台 Ctrl Home / Ctrl End | 笔记开头 / 结尾 |
| ↑ / ↓ | 上下移动一行，屏幕外的行也算。在第一行按 ↑ 到笔记开头，在最后一行按 ↓ 到笔记结尾 |
| Page Up / Page Down | 翻一页；光标留在原处 |
| macOS 上 Option ← / Option →，其他平台 Ctrl ← / Ctrl → | 按词移动；配合 Backspace，删除光标前的一个词；配合 Delete，删除光标后的一个词 |
| macOS 上 Cmd Backspace | 向前删到这一行的行首 |
| macOS 上 Ctrl A / Ctrl E / Ctrl K | 行首 / 行尾 / 删到行尾 |
| macOS 上 Ctrl B、F、P、N 和 Ctrl D、H | 同 ← → ↑ ↓ 和 Delete、Backspace |
| Enter | 换行，并延续列表、引用、编号列表或任务列表；在空的条目上，结束列表 |
| Tab / Shift Tab | 在表格里，跳到下一个 / 上一个单元格。在列表或引用行上，或者跨多行时，缩进 / 取消缩进。其他地方 Tab 插入四个空格 |
| Esc | 离开编辑器 |

按住 Shift 再按移动键，会扩展选区。

输入是按词撤销的：一次撤销会收回刚输入的那个词和它后面的空格。连续按 Backspace 或 Delete 算一步。停顿超过两秒、移动光标，或者撤销、重做之后，都会另起一步；粘贴则整段一起撤销。输入法提交的一段文字单独算一步。

输入法还在组字的文字会出现在光标处，用笔记自己的字体，这一行其余的内容为它让开位置。在它被提交，或用 Esc 取消之前，在编辑器里点击没有任何效果。

### 链接与代码块

点一下链接就会打开它。匹配到多篇笔记的 wiki 链接会弹出一份候选清单让你挑，而不是去猜。每个代码块上都有一个复制整块的按钮，和一个把它折叠起来的按钮。

### 笔记里的图片

笔记编辑器持有焦点时，拖到窗口上的图片会被复制进笔记旁边的 `attachments` 文件夹，并在光标处插入 `![diagram](attachments/diagram.png)` 这样的链接。那个文件夹里已被占用的名字会变成 `diagram-2.png`，依此类推。接受 25 MiB 以内的 PNG、JPEG、GIF、WebP、BMP、ICO 和 TIFF 文件；其他文件不予理会。

用 `http://` 或 `https://` 地址链接的图片会被取回并画出来，最大 16 MiB，而且只从公网地址取 —— 从不访问你自己的机器或局域网。`note_remote_images_enabled = false` 让笔记什么都不去取。

### 拼写

拼写检查用的是 macOS 系统的拼写检查器，所以 Windows 和 Linux 上没有；`note_spellcheck_enabled = false` 在 macOS 上也会把它关掉。右键点一个拼错的词，会给出最多五条建议、`忽略拼写`（让这个词在这篇笔记里放行）和 `记住拼写`（把它加进系统词典）。选中文字时，`查询` 会为它打开 macOS 词典。

### Mermaid 图表

标注为 `mermaid` 的围栏代码块会被画成对应的图表，笔记里和 Markdown 文件预览里都一样。在笔记里，光标位于代码块内、或者结束的围栏还没写上时，代码块会重新显示源码，方便编辑。图表跟随笔记的浅色或深色外观，图表里引用的图片从不加载。

无法解析的代码块，或者大到画不了的 —— 源码超过 16 KB 或连线超过 150 条 —— 会保持为代码，标题栏会注明是哪一种情况。

## 片段

第三个面板是一个保存命令与文本的库 —— 每一条都是一个标题加一段正文，可以在面板里搜索。片段可以粘贴进你当前所在的 pane，也可以直接运行。

`新建片段` 打开编辑器。`操作说明` 是标题，可以留空，留空时用脚本第一个非空行代替，截到 48 个字符；你自己输入的标题最多保留 80 个字符。`脚本` 是正文，必填。在列表里点一个片段会打开它进行编辑，垃圾桶按钮会立即删除它，不会询问。

最新的片段排在最上面。搜索会查看标题和正文，不区分大小写。

运行时，正文的每一行末尾都会补一个回车，所以多行片段是逐行执行的，而不是整块送过去。首尾的空行会被去掉。

运行和粘贴会发往按下按钮那一刻聚焦的 pane，而不是文本到达时恰好聚焦的那个。如果那个 pane 在此之前已经没了，就什么也不发送。

片段存放在 ThinkTerm 数据目录下的 `snippets.json` 里，位于运行桌面端的那台电脑上；在 macOS 和 Linux 上这个文件只有你自己可读。它不是密钥库，里面的内容没有加密。面板自己不保存副本：片段属于 ThinkTerm 的插件服务端，「片段」是其中的一个内置插件，每个窗口 —— 以及浏览器里的「片段」标签 —— 显示的都是那个服务端里的内容。连接到某台主机的浏览器，看到的是那台主机上保存的片段。插件服务端见 [插件](https://docs.closex.org/zh/thinkterm/plugins.md)。

## 面板都是可选的

`设置 › 侧栏与插件` 决定右侧栏提供哪些面板。全部关掉，侧边栏本身就消失了。「片段」在那里的开关，同时也是「片段」插件的开关。

git 仓库里的改动由 Diff 插件显示，而不是由文件面板显示；见 [插件](https://docs.closex.org/zh/thinkterm/plugins.md)。

## 相关

- [远程](https://docs.closex.org/zh/thinkterm/remote.md) —— 连接到你正在浏览其文件的那台主机
- [配置](https://docs.closex.org/zh/thinkterm/configuration.md) —— 库的绑定关系记录在哪里
- [插件](https://docs.closex.org/zh/thinkterm/plugins.md) —— 片段所在的插件服务端，以及 Diff 这样的面板
- [Agent 状态](https://docs.closex.org/zh/thinkterm/agents.md) —— 第四个内置面板