文件与笔记
文档编写中
部分内容可能尚不完整。
终端旁边还有三个面板：一个本地与远程目录一视同仁的文件浏览器，一个绑定到你已有笔记库的 Markdown 编辑器，以及一个保存命令用的片段库。同一个右侧栏还可以放 Agent 面板，以及插件加进来的面板。
文件
文件浏览器为当前 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 在本次运行期间会自己重连它，重启之后再问你一次。把文件拖放或粘贴进那台主机的终端，也算开口。
也可以让某台主机不等你开口就连接。在它的编辑器里打开 文件面板自动连接 后，只要那台主机的终端出现在旁边，面板就会连上去，不论这个终端是直接连到主机，还是经由它的 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-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 的插件服务端，「片段」是其中的一个内置插件，每个窗口 —— 以及浏览器里的「片段」标签 —— 显示的都是那个服务端里的内容。连接到某台主机的浏览器，看到的是那台主机上保存的片段。插件服务端见 插件。
面板都是可选的
设置 › 侧栏与插件 决定右侧栏提供哪些面板。全部关掉，侧边栏本身就消失了。「片段」在那里的开关，同时也是「片段」插件的开关。
git 仓库里的改动由 Diff 插件显示，而不是由文件面板显示；见 插件。