参考

01按键与命令

没有模式，所以下面每个键什么时候按都是同一个意思——像 VS Code、Emacs，不像 vim、helix。按键分三类：功能键、Ctrl、Alt，记住每一类管什么，具体的键就好记了。这里是默认按键（也就是下面的 obelus 方案），每个都能改，见设置。

四套按键方案

从哪套按键出发，由设置 keys_from 决定，一共四套。obelus 就是本页各表。mnemonic 把十二个功能键按单词首字母挪到 Ctrl 和 Alt 上，给没有那一排键的键盘用，别的都不动。vscode 和 textmate 在 Obelus 有同样命令的地方用那两个编辑器教会你的键，完全不用功能键；其余的 Ctrl、Alt 键和下面一样。它们是按 Obelus 有的东西改编的，不是照搬。

字母上的 Shift 会明写出来：Ctrl+Shift+p。多数终端发不出字母上的 Ctrl+Shift，只会发普通的 Ctrl+p，所以这些键旁边都另有一个每个终端都能发的 Alt 键。obg 收到的就是按下的键本身。在 Mac 上的 obg 里，每套方案的 Ctrl 都是 Cmd：本页写 Ctrl+p 的地方按 Cmd+p，屏幕上也写 Cmd。Ctrl 本身在那里照样能用；设置文件里仍写 Ctrl，因为终端里的 ob 读的是同一个文件，而终端会把 Cmd 留给自己。别的系统上 Super 键（Windows 键）从不当作 Ctrl，它是桌面的。

在 Mac 的终端里，要把 Option 设成 Meta 键，终端才会发 Alt：Terminal 在 设置 → 描述文件 → 键盘 里勾选将 Option 键用作 Meta 键；iTerm2 在 Settings → Profiles → Keys 里把 Left Option key 设为 Esc+。不设的话，Option 会打出一个字符（Option+Shift+p 是 ∏），Obelus 里所有 Alt 键都不起作用。obg 不需要设置。

切换方案：打开 open-settings，在 Keys 下选 Layout。每一行都写着这套方案把打开文件和命令面板放在哪个键上。没有设置文件时第一次启动 Obelus，会问一次；Esc 保留 obelus，下次启动还会再问；选了任何一套（包括 obelus）都马上写进设置，以后不再问。你在 [keys] 里写的键叠在方案之上，所以换方案不会丢掉你自己的键。

F1–F12：打开要看的东西

四个一组，跟键盘上的分组一样：F1–F4 打开要读的东西，F5–F8 是搜索，F9–F12 是 Git 历史、跳转定义，以及 PR 和 issue。功能键都不带修饰键，因为 Shift+F5 这类组合在不同终端里发出来的东西不一样，在这台机器上能用，换一台就不行了。

Ctrl：对当前文件做事

Alt：问光标下面是什么，或者在结果之间跳

还有两个不带修饰键的

Insert 是 toggle-replace：打的字会盖掉光标下的字，而不是插在前面，开着的时候状态行会写着 Replacing。Esc 取消选择，或者关掉最上面那个东西。

移动光标，以及在列表里

移动光标不算命令，所以不在上面的表里：方向键、PageUp/PageDown、Home/End（行首、行尾）、Ctrl+Home/Ctrl+End（文件开头、结尾）、Ctrl+↑/Ctrl+↓（视图滚一行，光标不动）。上下是按屏幕上看到的行走的，长行折过来以后也一样。Shift 不对应任何命令，只用来扩大选区。

在列表里（各种选择列表、设置页、代码行数统计页）：打字筛选，↑↓ 选，PageUp/PageDown 翻页，Home/End 到头、到尾，Enter 选定当前这一行，Esc 取消。列表下面有预览时，两者分着用键：↑↓ 和 Ctrl+PageUp/Ctrl+PageDown 动列表，PageUp/PageDown 和 Ctrl+↑/Ctrl+↓ 滚预览。列表有自己的按键时，底部那一行会写出它们。功能键在整屏的视图里也能按，会直接换成它对应的视图：在文件列表里按 F6 就换成搜索，F3 是文件列表的另一个 tab。

在对话里

Enter 发送，Alt+Enter 换行（终端支持的话 Shift+Enter 也行）。在关于笔记的对话里，输入框空着时按 →，会填进一句建议的开场白。Shift+Tab 切换 agent 自己的模式，显示在最底下那一行。Esc 让 agent 停下，它正在跑的命令也一起停。Alt+t 跳到这段对话所属的笔记。agent 问你问题时是一张卡片：↑↓ 选，Enter 回答。

在笔记页

笔记页随时可以直接打字：Enter 开始下一条，Alt+Enter 或 Shift+Enter 在一条里面换行。Tab 把一条挪到上一条底下，Shift+Tab 再挪出来。其余操作笔记的键都在 Alt 上：Alt+Space 打勾，Alt+o 跳到它指着的那一行，Alt+a 打开它的对话，Alt+↑Alt+↓ 调整顺序，Alt+← 删掉。

在终端里

open-terminal 在项目目录里打开你的 shell，它是一个单独的文档；agent 要你登录时，登录程序也在这样的终端里跑。程序在跑的时候，按键都交给程序，Esc、Ctrl+c 也是。Obelus 只留下功能键、命令面板（Ctrl+p；vscode 和 textmate 方案里是 Ctrl+Shift+p 和 Alt+Shift+p，这两套没有功能键，Ctrl+p 交给程序）、退出用的 Ctrl+q、粘贴用的 Ctrl+v 或 Shift+Insert，以及关掉终端的 Ctrl+w（程序还在跑的话会先问一句）。

想往回看已经滚走的输出：滚轮，PageUp/PageDown 一次一屏，Ctrl+Home/Ctrl+End 到最前、最后，这几个键归 Obelus，不发给程序。拖动鼠标能选中输出的文字，Ctrl+c 或 Ctrl+Insert 复制；没选中东西时，Ctrl+c 照常发给程序。程序自己要用鼠标时（比如编辑器、进程列表），左键和滚轮交给它，按住 Shift 还能自己选。程序在跑时退出 Obelus 会先问一句，程序结束后按键都还给 Obelus。

命令

按 Ctrl+p，输入名字。名字都以动词开头，所以先打动词。命令面板分六个标签页，大致按用的先后排：打开文件 → 在里面找 → 问代码是什么意思 → 改 → 看改了什么 → 最后是 Obelus 自己的杂事。

02给 agent 的工具

通过 ACP，agent 本来就能读文件、请求许可，但碰不到你的笔记。所以 Obelus 通过 MCP 另外给它几个工具。工具本身不会问你什么：要问的是 agent，在调用之前用一张卡片问。

另外三个：open_file 在你同意后把一个文件打开到某一行（Alt+← 回到原处）；read_workflow 在 agent 动手改之前，告诉它这个项目用的是哪套工作流；close_conversation 在你同意后关掉这段对话。

03设置与主题

两个文件

没有文件就用默认值；有一行 Obelus 不认识，那一项也用默认值——配置里一个笔误，不该让编辑器打不开。只有一种情况例外：整个文件解析不了。这时 Obelus 不再往这个文件里写，免得把它没读懂的设置覆盖掉；它会告诉你，等文件能解析了再自动恢复。

它还会告诉你是哪一行的问题。配置文件解析不了、某个键绑不上、项目设了无权设的项、主题名字找不到对应的文件——都会标在出问题的那一行上，和语言服务器报的错放在同一个列表里，所以 Alt+e 和 Alt+[ Alt+] 照样能找到它们。

能设的项

有几项只对窗口版或只对终端版有效。设置页只列出对你当前这一版有效的，免得你改了却看不到任何变化；文件里则全都留着，因为同一台机器上的另一版也读这个文件。

改键

只写你要改的：改了一个键，其他的照旧用默认，以后 Obelus 加的新键你也能用上。一个命令可以绑好几个键，写成列表就行，排第一的是屏幕上显示的那个。空字符串或空列表表示去掉它所有的键。任何键都能绑，不管是不是每个终端都发得出来，只有几种 Obelus 根本不会交给键位表的键除外：不带修饰键的字符、Esc、Enter（Alt+Enter 可以绑）、Tab、Backspace、Delete，以及不带 Alt 的移动键。命令名就是上面那些；键的写法和屏幕上显示的一样，不区分大小写：Ctrl+P 就是 ctrl+p，Shift 要写成 shift+。你写的这些叠在 keys_from 指定的方案之上，换方案也还在。

theme = "light"
wrap = true
blame_margin = false

[keys]
open-file = "Ctrl+o"
show-change = "Alt+g"
run-command = ["Ctrl+Shift+p", "Alt+Shift+p"]   # 两个键都行
quit = ""            # 把这个绑定拿掉

设置页的 Keys 标签里，一个命令绑的每个键各占一行。Enter 是改键：再按一个键就把它换掉。在命令的任何一行上按 Ctrl+Enter，给它再加一个键；还没有键的命令，也是用它绑第一个。不支持键盘协议的终端会把 Ctrl+Enter 当成 Enter 发出来，在那里要加键（包括给还没有键的命令绑第一个），就写进设置文件。Alt+Backspace 去掉这一行的键，Alt+r 把这个命令恢复成布局的默认键，Alt+Shift+r 问过之后把所有命令都恢复。用 Alt 是因为过滤框不用 Alt 键，Backspace 和 Delete 是过滤框的。键和布局默认不一样的命令，名字旁边会写 Changed；底栏的这些键只在真正有用时才出现。

主题

内置 dark、light 和一排常见配色，choose-theme 切换，马上生效。另外，~/.config/obelus/themes/ 下的每个 .toml 文件都是一个主题，名字就是文件名（mine.toml → mine）；那里的一个目录只要放了 theme.toml，也是一个主题，名字就是目录名——主题就是这样把一张图片和配色放在一起的。你自己的主题和内置的同名时，用你的。每个颜色都可以不写，没写的沿用它所基于的内置主题——所以以后 Obelus 多了新颜色，你的旧主题文件不用改也能用。

注释用斜体显示。哪些种类的代码用斜体，由主题在 [syntax] 下按颜色的名字来写：italic = ["comment", "keyword"]，写 italic = [] 就都不用斜体。没写的，沿用它所基于的内置主题。

在窗口里，主题可以带一张铺在页面下面的壁纸。主题文件里单独写一节，除了 file 都可以不写：

[wallpaper]
file = "rain.jpg"     # 和 theme.toml 放在一起
opacity = 85          # 页面底色盖在图上的程度，0 到 100
fit = "cover"         # cover、contain、stretch、center 或 tile
anchor = "center"     # 哪一处不动：top-left、top、top-right、left、
                      # center、right、bottom-left、bottom 或 bottom-right

图片露出多少，你也可以调：设置里的 picture_strength 是 opacity 让图片露出那部分的百分比，所以 opacity = 85 配 picture_strength = 200，露出的就从十五变成三十。终端里没有像素可画，所以 ob 只用配色。Obelus 用不了的那一行会标出来并退回默认值，图片不在也会标出来。

更多主题在设置的 Themes 页：一组是为 Obelus 做的主题，一组是 omarchy 官方的主题转成的 Obelus 主题。Enter 安装或更新光标所在的主题，第一次装的主题装好就直接换上，Delete 把它删掉，正在用的那个除外；列表里已经没有的主题会一直留着，直到你删掉它，这要按两次 Delete。装来的主题和你自己的 ~/.config/obelus/themes/ 分开存放，同名时你自己的优先。每个主题列表的最后一项都是 More themes，选它就到这一页；列表里找不到的名字，按 Enter 也会带着它来到这一页的筛选框里。

只要 omarchy 为 Obelus 写出了主题，列表里就会有 omarchy；仓库里的 contrib/omarchy/ 就是让它写出主题的模板，这样桌面换主题时，Obelus 的颜色跟着换。

04多个窗口

Obelus 不分屏，所以同时开好几个 Obelus 窗口是常态：同一个项目开几个，不同的 worktree 各开一个，旁边还有你自己的 shell。实际用起来是这样的：

• 同一个仓库的所有 worktree 共用一份笔记，一个窗口里写的，别的窗口自己就会出现。
• 两个窗口改同一个文件，不会互相抹掉：每次改动都以那一刻磁盘上的内容为准。保存之前，Obelus 会先检查你打开之后，别的窗口、agent 或格式化工具有没有改过这个文件。
• 一段对话同时只能在一个窗口里打开。占用跟着进程走，窗口崩了占用也就没了，不会出现对话「卡住打不开」。
• 在一个窗口里改了设置，或者直接改了设置文件，所有窗口都会跟着变。
• 窗口所在的 worktree 被删掉了（在 shell 里删的，或者 git worktree remove），整个窗口会弹出一页说明这件事。按 Enter 放下这个项目里打开的一切（已经没有地方可存了），再选下一个要打开的项目；按 Ctrl+q 退出。
• worktree 列表里（按 F2 再按 Tab），和主 checkout 并排的 worktree 显示它自己的名字，在主 checkout 里面的显示往下的路径，别处的显示完整路径。没通过 Git 就被删掉的 worktree 显示 Missing，选不了。
• 每个窗口有自己的语言服务器和自己的 agent。同一个 Rust 项目开三个窗口，就是三个 rust-analyzer。