功能

一览

每项功能下面有一行，说怎么用到它：默认按键、命令名（在命令面板 Ctrl+p 里输入它就能执行），以及能改它的设置。所有按键都能改。

01打开与切换

文件列表

项目里的文件排成一棵树，展开到你正在读的那个文件，下面预览选中的文件。一打字，树就变成所有路径的平铺列表，边打边筛；把输入清空，又回到你离开时的那一行。每一行按 Git 的状态上色。

• 在目录上按 Enter 就地展开或收起，在文件上按就打开它。双击一行等于按 Enter，这里和大多数列表都一样
• 什么都没输入时，Right 展开目录，已展开的就进到它里面；Left 收起目录，或者回到这一行所在的目录
• Alt+i 显示项目忽略的文件，Alt+. 显示隐藏文件（点开头的，以及 .git）
• Alt+n 给选中的文件或目录改名、挪位置

按键F1命令open-file设置ignored_files hidden_files

打开着的东西

所有打开着的东西——文件、对话、笔记、终端——按打开的先后排着，带预览。有没保存改动的文件标 •，对话会显示 agent 是不是在干活，笔记那一行显示还有几条没做完。Ctrl+w 关掉你停着的那一行，列表还开着。仓库有别的 worktree 时，Tab 切到 Worktrees 标签页。

按键F2命令switch-document

改过的文件

文件列表的另一个标签页：Git 说自上次提交以来改过的每个文件，旁边是加了几行、删了几行。改过名的会写出原来叫什么，删掉的文件打开就是上次提交时的样子。什么都没改的时候，这个键什么也不做。

按键F3命令open-changed-file

项目与欢迎页

给一个文件，它所在的仓库就是项目；给一个目录，这个目录就是项目。什么都没给——比如从桌面菜单启动——它会问开哪个项目：最近在这里选过的二十个，新的在前，或者输入一个路径，带补全，补全走到项目就停。close-project 放下手上的一切，回到这个页面。什么都没打开时，欢迎页列出起步的几个键，读的是你自己的键表，改了键，它显示的就是改过的。

命令close-project

上次开着的，下次还在

每个 worktree 记着在它上面开过什么——文件连同光标和滚动位置、笔记、对话，以及哪个在最前面——下次再打开。某个提交时的文件、终端、已经不在的文件不会重新打开。几个窗口开在同一棵树上时，最后改动打开内容的那个算数。

设置reopen

新建、改名、保存、关闭

• new-file 立刻在磁盘上建出文件，缺的目录一并建好，然后打开它
• rename-file 给文件改名或挪位置，并让语言服务器把引用它的地方一起改掉；这些改动是没保存的，你能先看再决定，也能撤销
• Ctrl+s 先看磁盘。要是在你打开之后别的东西改过这个文件，由你选是用你的盖掉它，还是取磁盘上的（撤销能找回你的）；要是文件被删了，选写回去还是放掉
• Ctrl+w 关之前会问没保存的改动；Ctrl+r 从磁盘重新读一遍
• 文件在磁盘上变了——agent 写的、格式化工具跑的、分支切了——会自己重新加载，位置不动；除非你有没保存的改动，那时状态行会说它被挪走或删掉了，你的东西一点不丢

按键Ctrl+s Ctrl+w Ctrl+r命令new-file rename-file save-file close-document reload-file

02阅读

编辑器

从左到右：标出 Git 认为改过的行的边栏、行号、一列折叠标记、正文、一列显示整个文件改动分布的小地图、滚动条。改动边栏、折叠列和小地图只在有东西可显示时才出现。光标所在那一行的末尾，写着这行最后是谁改的、多久以前。

• 长行默认伸出右边，打开换行后会在词与词之间折行
• 鼠标滚轮滚动视图，光标留在原地；翻页键移动光标
• 单击放光标，双击选词，三击选行，拖动选择；点一下改动标记就展开那处改动

设置wrap tab_width blame_margin

折叠

折叠光标所在的那一块，或者文件里所有的块。哪里能折由缩进决定，所以每种语言都一样；折起来的块保留收尾的括号：if ready { … }。在折叠列上点一下标记也能折。

按键Alt+f命令fold fold-all unfold-all

markdown 和日志预览

markdown 文件排成便于阅读的样子：标题、列表、引用、表格，代码块按它自己的语言高亮。日志文件排成几列——Obelus 自己的日志、syslog、Web 服务器的访问日志——靠内容认出来，不看文件名。再按一次回到原文。

按键Ctrl+d命令toggle-preview

语法高亮

二十多种语言，用 tree-sitter：Rust、Go、C、C++、Python、JavaScript、TypeScript、TSX、Java、C#、Ruby、PHP、Scala、Swift、Haskell、OCaml、Julia、Agda、Bash、HTML、CSS、JSON、TOML、YAML 和 Markdown。代码里嵌的代码也上色——markdown 里的代码块、HTML 里的脚本。语言服务器在跑的时候，它的语义着色叠在上面。

代码有多少行

按语言、按文件数项目的行数——文件数、总行数、代码、注释、空行，大的在前——跳过 .gitignore 忽略的。文件标签页是一棵树，可以一路点进去，打开某个文件，Right 和 Left 像在文件列表里一样展开、收起；先选一种语言，就只看它的文件。

命令count-lines

03查找

搜索：当前文件、所有文件、所有名字

一个搜索界面三个标签页，各有一个键：你正在读的文件、项目里的所有文件、语言服务器知道的所有名字。切标签页时输入的内容跟着走，列表下面的预览把每处命中放在原处给你看。文字按原样匹配，不是模糊匹配。

• Alt+r 用正则，Alt+w 全词匹配，Alt+c 区分大小写（默认是打了大写字母才区分）
• 在名字那个标签页，Alt+o 把项目外面的名字也算上，比如依赖里的
• 项目搜索和文件列表一样，按忽略文件、隐藏文件的设置来

按键F5 F6 F8命令search-file search-project search-symbols

大纲

这个文件定义的每个函数、类型、常量，按代码里的层次排好，打开时停在你所在的那一个。有语言服务器时问它，没有就用语法树，所以服务器还在建索引时也能用。

按键F7命令show-outline

跳行、括号、后退前进

• Ctrl+l 按行号跳
• Alt+m 跳到和光标下括号配对的那一个，跳过字符串和注释里的括号
• Alt+← 回到跳过来之前的地方，Alt+→ 再前进——跨文件、定义、搜索结果、改动都算

命令go-to-line go-to-bracket go-back go-forward

04语言服务器

服务器

Obelus 问的是你已经装好、在 PATH 上的语言服务器：rust-analyzer、gopls、clangd、pylsp、typescript-language-server、bash-language-server，以及 VS Code 给 CSS、HTML、YAML 的那几个。它一个也不替你装，也一个都不启动，除非你在设置里打开 language_servers：定义在哪、谁调用了它，agent 已经能告诉你，而服务器是每种语言、每个窗口各一个进程。打开以后，打开项目里某种语言的文件时，对应的服务器就启动；关着的时候，restart-server 照样能启动眼前这个文件所用语言的那个。状态行显示它的名字和状态——启动中、就绪、已退出——建索引时转圈。没有服务器也照样有高亮、大纲、折叠和搜索。

命令restart-server stop-server open-server-log设置language_servers

定义、引用、实现

F11 跳到光标下这个名字定义的地方。Alt+Enter 列出服务器能回答的关于它的每个问题——类型的定义、实现、引用、调用——只列它答得了的。只有一个结果就直接跳过去，有好几个就开一个带预览的列表。

按键F11 Alt+Enter命令go-to-definition ask-about-symbol go-to-type-definition go-to-implementation find-references

谁调用了谁

一棵树，列出调用光标下这个函数的地方；另一个标签页是它调用了谁。Enter 展开一层；树上更高处已经出现过的调用标 ↩，按它就跳过去，不再绕一圈。

命令show-calls

悬停、签名、补全

• Alt+h，或者鼠标在一个词上停一会儿，显示服务器说它是什么
• 打 ( 之后显示这次调用的参数，标出你正在写的那一个；已经写好的调用，Alt+s 把它叫出来
• 边打字边弹出补全；Enter 选中，Tab 在代码片段留下的占位之间跳
• 服务器推断出的类型和参数名画在行里，但选不中也复制不了，因为它们不在文件里

按键Alt+h Alt+s命令describe-symbol show-signature complete-here设置hover_delay inlay_hints

code action 与重命名

Alt+a 列出服务器对这一行或选中部分提供的修复和改动，其中包括针对问题的快速修复。Alt+r 在所有地方改一个名字：涉及的每个文件都打开并改好，但不保存，所以你先看过再写盘，撤销也能退回去。保存时格式化、保存时应用服务器的整文件修复，都有，默认关着，要你自己打开。

按键Alt+a Alt+r命令do-something-here rename-symbol设置format_on_save code_actions_on_save

问题

每个问题都画下划线，光标所在行的问题说明展开在它下面。Alt+e 列出当前文件或整个项目的问题，Alt+[ 和 Alt+] 一个个走过去。Obelus 自己的抱怨也进同一个列表：设置文件里看不懂的一行、什么都没绑上的按键、读不出来的主题。

按键Alt+e Alt+[ Alt+]命令show-problems go-to-previous-problem go-to-next-problem设置diagnostics

05Git

边栏上的改动

和上次提交不一样的行标在边栏上，滚动条旁的小地图显示它们在文件的哪些位置。Alt+d 把旧行就地展开在新行上面，再按一次收起；光标可以进到旧行里，从里面复制。Alt+n 和 Alt+p 跳到下一处、上一处改动。

按键Alt+d Alt+n Alt+p命令show-change go-to-next-change go-to-previous-change

这行是谁写的

在光标所在那一行的末尾：最后是谁改的，多久以前。只显示这一行，边栏保持安静。

设置blame_margin

文件和项目的历史

F9 列出改过这个文件的每个提交——改名前的也算——第二个标签页是分支和标签。F10 列出项目的每个提交，在一个提交上按 Enter 展开它改过的文件。每一行是标题、多久以前、短 id；远端还没有的提交另外上色。预览里是完整的提交说明，以及加了多少、删了多少。整个历史在后台读完，所以全部都能搜。

按键F9 F10命令show-file-history show-project-history

某个提交时的文件

从历史里选一个文件，打开的就是那个提交留下的样子，边栏标出那次提交做了什么——对比的是它的上一个提交，不是今天。状态行写着是哪个提交。它只用来读：不能保存，也不去问语言服务器。

Pull request 和 issue

仓库里开着的 pull request 和 issue，两个标签页，通过 gh 拿。每一行是编号、标题、标签、谁、什么时候，以及有没有被批准；预览里有描述、评论、review 和 CI 检查。选一个，就开一段和 agent 的对话，准备好审这个 pull request 或者起草对 issue 的回复，在你按 Enter 之前什么都不发。不经你在卡片上点头，什么都不会到 GitHub：批准、要求修改或评论；发出去、发出去并关闭，或者什么都不发。

按键F12命令review-pull-request

06笔记

在一行上按 Alt+t 记一条关于它的笔记；Ctrl+t 打开全部。笔记可以对着一行，也可以对着整个项目，还能一条挂在另一条底下，最多四层。笔记记着写下时的提交，所以文件改过之后还找得到它那一行；那一行没了，就写 gone。

• 笔记页随时可以打字：Enter 开一条新的，Tab 把它挂到上一条底下，Shift+Tab 再拿出来
• Alt+Space 打勾；打了勾的留在列表里，直到你删掉
• Alt+o 跳到它指着的那一行，Alt+a 开一段关于它的对话，Alt+↑ Alt+↓ 挪位置
• 有对话的笔记会标出来；你改了笔记，agent 会被告知改了什么

所有 worktree 共用

笔记存在 Obelus 自己的目录里，不在你的仓库里，所以永远不会混进提交，同一个仓库的每个 worktree 看到的是同一份。两个窗口同时写也不会互相盖掉。一条笔记的对话在别的窗口开着时，这里的它是只读的，你和 agent 都改不了，直到那个窗口放手。

按键Alt+t Ctrl+t命令todo-add todo

07Agent

Obelus 自己没有模型。它通过 ACP（Agent Client Protocol）和你选的 agent 说话，再通过 MCP 给它几样 Obelus 自己的工具。

选一个、装一个

设置页的 Agents 标签页列出 ACP 注册表里的每个 agent，带说明、版本和许可证。在一个上按 Enter：安装它（通过 npm、uv，或者下载一个按哈希校验过的文件）、更新它，或者设为正在用的那个。你装的第一个就是正在用的。同一时间只有一个：换一个，正在跑的那个就停掉。agent 旁边，设置页写着新对话从什么开始——它的模式、它的模型——用的是 agent 自己的说法。

命令open-settings设置agent agents

对话

对话是一个文档，和文件一样：今天放下，明天接着聊。F4 列出所有对话，新的在前，分在今天、昨天、本周、更早底下，最上面是新建一段。每一行写着它是关于什么的——哪条笔记，或者审的哪个 pull request——以及多久以前。一段对话同一时间只在一个窗口里开着；别的窗口拿着的，显示为锁住。重新接上一段对话时，agent 能回放就回放，不能的话会说回来了多少。

按键F4命令choose-conversation new-conversation设置conversation_days

agent 做了什么

agent 已经做了的改动只占一行，写着加了几行、删了几行：改动本身在文件里看，在边栏上。它还在请求做的改动，会把那几行列出来。它跑的命令，原样显示跑的是什么、打印了什么，以及怎么结束的。双击提到某个文件的那一行，就跳到那个文件。

• 连着三次以上同一类调用，收成一行，展开才看得到
• 在输入框顶上再按 ↑，光标进到对话记录里，可以选中、复制；Tab 跳到下一个能操作的行，在一次调用上按 Enter 打开它碰过的文件
• agent 的思考过程照样显示，不藏起来
• 状态行显示 agent 的上下文用了多少、花了多少钱，前提是 agent 报了这些

卡片上的问题

agent 请求权限或者问你什么时，一张卡片换掉输入框：选一个的列表、可以勾好几个的列表、开关、输入框，或者数字。Enter 回答，Esc 整个问题都不答。

模式、命令、排队的消息

• Enter 发送，Alt+Enter 或 Shift+Enter 换行
• Shift+Tab 在 agent 自己的模式之间切换；在输入框开头打 /，列出它自己的命令；输入框下面那一行放着它别的选项，比如模型
• agent 在干活时你发的消息，在对话里排着，等它干完一起作为一条发出去；在排着的消息上按 Enter 把它拿回来
• Esc 叫停 agent，连同它正在跑的命令；Ctrl+Enter 叫停它并把输入框里的发出去

图片

把图片粘进输入框，把图片文件拖到窗口上，或者在终端版里粘一个图片路径。它跟着你的消息一起发出去，太大的先缩小。不收图片的 agent，在你加图片时就会说。

登录

需要你登录的 agent，会用一张卡片问你怎么登录；要靠一个程序登录的，那个程序在 Obelus 自己的终端里跑，你在里面选账号或者粘一个码。然后对话从停下的地方接着走。

Obelus 给它的工具

通过 MCP，agent 能读你的笔记、加笔记、给一条打勾、改写一条、在你屏幕上打开某个文件的某一行、读项目的工作流、关掉它所在的对话。其中会改东西的，它都先在卡片上问你；工具本身从不自己问。完整列表在参考里。

工作流

agent 动手改项目之前，被要求怎么做。feature-branch，默认：在自己的 worktree 里开分支，改之前和改之后都跑测试，你试过，审过，再合并或者开 pull request——首页上一步一步写着。in-place：同样的步骤，但就在你正在读的这份代码里改，每处改动都落在你打开的文件里，Ctrl+z 能撤。none：agent 怎么做都行。项目可以有它自己的设定。

设置workflow

08从聊天里用

人不在电脑前，也能在手机上的 Slack 或飞书（Lark）里接着同一段对话。每段对话是一个话题，你开一个新话题就开了一段新对话。agent 的问题在聊天里显示成按钮和列表，点一下就是回答。

• 设置页的 Remote 标签页一步步带你在聊天平台那边建好应用；token 存在系统的钥匙串里，不写进文件
• 配对时，Obelus 给出一个六位的码，五分钟有效；在应用所在的群里发这个码，那个群和你就算接入了。别人说话它不理
• 同一时间只有一个窗口连着聊天，就是你让它连的那个，它的状态行显示连接情况

命令connect-remote disconnect-remote

没有界面的 Obelus

ob --headless 在一个项目上跑 Obelus，什么都不画，也不占终端，只为从聊天里找到它——放在一台一直开着的机器上。--connect-remote 让一个普通窗口启动时就连上聊天。

09Worktree 与多窗口

仓库的每个 worktree，各带它的分支，每棵底下一行一个开在它上面的 Obelus，写着它在读什么。窗口版里，在树上按 Enter 在那里开一个新窗口，在窗口那一行上按就把那个窗口叫到前面，Ctrl+Enter 把当前窗口挪到那棵树上。终端版里，Enter 把这个 Obelus 挪过去。挪之前都会先问没保存的文件。

没告诉 Git 就删掉的树显示 Missing。窗口所在的那棵树被删了，会有一页盖住整个窗口说明这件事，Enter 问你接下来开哪个项目。

按键F2 再按 Tab命令switch-worktree

一个项目开好几个窗口

Obelus 没有分屏：想并排看两样东西，就开两个窗口。所以一个项目上开好几个是常态，它们互不碍事。

• 笔记是共用的，一个窗口写的，别的窗口马上看到
• 一段对话同一时间只在一个窗口里开着，崩溃了也不会把它卡住
• 保存前会看磁盘，一个窗口不会悄悄盖掉另一个的
• 在一个窗口里改了设置，或者手改了设置文件，每个窗口都会跟上
• 每个窗口有自己的语言服务器和自己的 agent

窗口之间共享编译任务数

机器上所有的 Obelus 共用一个编译任务池，并把它交给自己启动的东西——agent、语言服务器、终端——所以三个窗口各跑一个 cargo，不会各自占满所有核。默认这个池是机器的一半。

设置build_jobs

10终端

你的 shell，开在项目里，在打开着的东西里是一个单独的文档。有程序在跑时，所有键都给它，Esc 和 Ctrl+c 也一样，只有 Obelus 留着的几个除外：功能键、Ctrl+p、关掉它的 Ctrl+w、退出的 Ctrl+q，以及粘贴。

• 滚出屏幕的内容留一万行，用滚轮或 PageUp PageDown 往回看
• 拖动选中打印出来的内容，Ctrl+c 复制；什么都没选时，Ctrl+c 照样发给程序
• 用鼠标的程序拿得到鼠标；按住 Shift 照样能选
• 有东西在跑时关掉它或者退出，会先问

命令open-terminal

11编辑

没有模式。每个键什么时候按都是同一个意思，像 VS Code 和 Emacs，不像 vim 和 helix：方向键移动，加 Shift 就是选择，Ctrl+z 撤销，打字就是打字。撤销按你在做的事退——一串打字、一串删除——而不是一个字一个字地退。其余的只够改一两行用：括号和引号成对打出，按语法扩大选区（Alt+w），挪行（Alt+↑ Alt+↓），注释掉（Alt+c），改写（Insert）。没有多光标，没有宏：大改动是 agent 的活。

剪贴板

Ctrl+c、Ctrl+x、Ctrl+v 走系统剪贴板，什么都没选时复制整行。Ctrl+Insert 和 Shift+Insert 也行。复制的东西在 Obelus 退出后还在，终端版通过 ssh 也能复制到你自己的机器上。

只读

如果改动全交给 agent，就把你自己的键从文件上拿掉：打字、粘贴、撤销和挪行这类命令在文件里都不起作用；agent 的改动照样进来，保存照样能用，写消息、搜索、记笔记的输入框也照样能打字。

设置read_only

12按键与设置

命令面板

所有命令，按名字，分成六个标签页：文件、搜索、代码、编辑、Git、Obelus 自己。名字以它做的事开头——open-file、show-calls——所以先打动词。在当前位置做不了事的命令是灰的，它的键也不起作用。有自己按键的列表，底部是此刻能用的那些。

按键Ctrl+p命令run-command

设置页

每个设置都带一行说明，边打边筛，一改就存。项目可以在 .obelus/config.toml 里带自己的设置，叠在你的上面——但只有你能决定的那些它碰不了，比如跑哪个 agent、你的键放在哪。手改这两个文件，存盘时 Obelus 就会读到；它看不懂的一行会标成一个问题。

命令open-settings open-project-settings open-settings-file

改键

Keys 标签页列出每个命令和它的每个键：在某个键上按 Enter，再按新的键，就把它换掉；按 Ctrl+Enter 再加一个。被别的命令占用的键，或者 Obelus 根本不会交给键位表的键，会被拒绝并告诉你为什么。键盘上没有一排功能键的，mnemonic 布局把那十二个按单词的首字母放到 Ctrl 和 Alt 上。

设置keys_from [keys]

主题

内置 dark 和 light，~/.config/obelus/themes/ 里的每个 .toml 文件也是一个主题，每种颜色都可以不写。注释是斜体，哪些种类的代码用斜体也由主题来定。在列表里上下移动就逐个试穿；Esc 换回你原来的。

命令choose-theme设置theme

窗口版还是终端版

obg 是窗口，ob 跑在终端里，就像 gvim 和 vim：界面一样，按键一样。窗口版分得清终端分不清的键（Ctrl+i 和 Tab、Ctrl+m 和 Enter），自带图标，光标和列表是滑过去的，输入法拼字时直接显示在页面上。它的字体和字号是设置；在终端里，用的是终端自己的，图标要装 Nerd Font。

设置fonts font_size animation icons

更新与日志

Obelus 每天问一次 GitHub 有没有新版本，有的话只在欢迎页上说；关掉它就什么都不发。它自己的日志和语言服务器的日志都能当文件打开，预览会把日志排成几列。

命令open-log open-server-log设置new_versions