Emacs光标管理库cursory：实现情境感知的自动切换与主题集成

1. 项目概述：一个为Emacs设计的轻量级光标库

如果你和我一样，是个长期泡在Emacs里的开发者，那你肯定没少折腾过光标。默认的竖线光标看久了眼睛累，块状光标在特定模式下又不够显眼。更别提在不同主题、不同缓冲区之间切换时，光标样式不统一带来的割裂感了。今天要聊的这个项目——protesilaos/cursory，就是来解决这些“细枝末节”却又实实在在影响编码体验的问题的。它不是一个庞大的框架，而是一个设计精巧、高度可配置的库，专门用于管理Emacs中的光标样式。简单来说，它让你能像换衣服一样，轻松地为不同的编辑模式、不同的主题，甚至是你一天中不同的工作时段，换上最舒服、最护眼的光标“皮肤”。

这个项目出自Protesilaos Stavrou之手，这位开发者以出品高质量、设计考究的Emacs配置包而闻名。cursory延续了他一贯的风格：代码简洁、文档详尽、配置直观。它不试图接管你的整个Emacs，而是专注于做好光标管理这一件事。通过它，你可以定义多种光标预设（比如“细线”、“方块”、“闪烁块”、“横线”），并基于缓冲区模式、主题名称等条件自动切换，实现真正的“情境感知”光标。对于追求极致个性化工作环境和视觉舒适度的Emacs用户来说，这绝对是一个值得放入工具箱的利器。

2. 核心设计理念与架构拆解

2.1 为什么需要专门的光标管理库？

在深入cursory之前，我们先得明白，Emacs本身不是已经能改光标了吗？用(setq-default cursor-type 'bar)或者(set-cursor-color \"red\")不就行了？确实，基础修改是可行的。但问题在于管理和扩展性。当你想要实现以下场景时，原生配置就会显得力不从心：

1. 模式化切换：在prog-mode（编程模式）下使用细竖线光标便于精确定位，在org-mode下使用方块光标更醒目，在term-mode下又需要恢复成块状光标。
2. 主题联动：使用深色主题时，希望光标是亮色（如白色、黄色）；切换到浅色主题时，光标自动变为深色（如黑色、深灰色），以确保始终有足够的对比度。
3. 预设与快速切换：定义好几套自己喜欢的光标样式（例如“专注模式-不闪烁细线”、“阅读模式-柔和方块”），并能通过一个命令或快捷键快速切换。
4. 状态感知：在Emacs失去焦点（focus-out-hook）时，将光标隐藏或变为极细线，重新获得焦点时再恢复，减少干扰。

cursory的设计正是为了优雅地解决这些问题。它的核心思想是“预设（Presets）+ 调度器（Dispatcher）”。你将各种光标样式定义为命名的预设，然后通过可定制的调度逻辑，决定在何时、何地使用哪个预设。

2.2 核心架构与组件解析

cursory的架构非常清晰，主要包含以下几个部分：

1. 预设（Presets）：这是一个关联列表（alist），是库的核心数据。每个预设都有一个名字（如‘block’，‘bar’）和一系列属性值。这些属性不仅包括Emacs原生的cursor-type（如‘box’，‘bar’，‘hbar’），还扩展了cursor-color、blink-cursor-mode的开关、甚至blink-cursor-blinks（闪烁次数）和blink-cursor-interval（闪烁间隔）等。这意味着你可以全方位定义光标的行为和外观。

2. 调度器（Dispatcher）：这是库的大脑。它是一组函数和钩子（hooks），负责在特定事件发生时，评估当前环境（如当前主模式、激活的主题、缓冲区名称等），并从预设列表中选择最匹配的一个应用到当前缓冲区。cursory内置了基于缓冲区主模式和主题名称的调度逻辑，并允许用户轻松添加自定义的调度规则。

3. 配置接口：提供了友好的变量和函数供用户配置。最重要的是cursory-presets变量，用于存放你的所有预设。以及cursory-mode，一个全局次要模式，开启后便会激活整个调度系统。

4. 主题集成：这是cursory的一大亮点。它能够与流行的主题系统（如modus-themes，ef-themes， 以及任何遵守常见约定的主题）深度集成。你可以在预设中指定:cursor-color为一个函数，该函数能根据当前背景色动态计算出一个高对比度的前景色，从而实现光标颜色与主题的智能适配。

这种架构的优势在于解耦和可扩展性。定义样式和决定何时应用样式是两件独立的事。你可以随意增加预设，也可以编写自己的调度函数，而两者互不干扰。这种设计使得cursory既能满足开箱即用的简单需求，也能经得起深度定制的考验。

3. 从安装到基础配置：快速上手指南

3.1 安装与引入

假设你使用的是straight.el或use-package来管理配置（这也是当前Emacs社区的主流方式），安装cursory非常简单。

;; 使用 use-package 和 straight.el 的示例 (use-package cursory :straight (:host github :repo \"protesilaos/cursory\") :config ;; 基础配置放在这里 )

或者，如果你使用的是package.el并从MELPA等仓库安装，则可以先M-x package-install RET cursory RET，然后在配置中(require 'cursory)。

我个人强烈建议将cursory的配置放在Emacs早期初始化的阶段，因为光标样式是UI的基础部分，尽早设置可以避免启动时的样式闪烁。

3.2 定义你的第一组预设

配置的核心是cursory-presets。我们先从一组基础但实用的预设开始：

(setq cursory-presets ‘( ;; 预设1：细竖线，适用于常规编程和文本编辑 (bar :blink-cursor-mode 1 ; 开启光标闪烁 :blink-cursor-blinks -1 ; 无限闪烁 :blink-cursor-interval 0.5 ; 闪烁间隔0.5秒 :cursor-type (bar . 2) ; 竖线，宽度2像素 :cursor-color \"#00ff00\") ; 绿色光标 ;; 预设2：实心方块，适用于阅读或需要突出光标位置的模式 (block :blink-cursor-mode 0 ; 关闭闪烁（更专注） :cursor-type box ; 方块光标 :cursor-color \"#ff6600\") ; 橙色光标 ;; 预设3：横线，模拟某些现代编辑器的下划线光标 (underscore :blink-cursor-mode 1 :cursor-type (hbar . 3) ; 横线，高度3像素 :cursor-color \"#66ccff\") ; 蓝色光标 ;; 预设4：小方块，折中方案 (small-block :blink-cursor-mode 1 :cursor-type (box . 1) ; 1像素宽的方块 :cursor-color nil) ; 颜色为nil，将由主题或调度器决定 ))

这里定义了四个预设，分别命名为bar，block，underscore和small-block。每个预设都是一个列表，以预设名开头，后面跟着一系列的键值对。键以冒号开头（如:cursor-type），是cursory定义的属性关键字。

注意：cursor-type的值可以是符号（如‘box’），也可以是(形状 . 尺寸)的cons cell。尺寸单位通常是像素，但取决于你的Emacs版本和图形系统。cursor-color可以是颜色字符串（如\"#FF0000\"），也可以是nil。为nil时，cursory的调度器可能会根据主题为其赋予一个智能值。

3.3 启用cursory-mode并设置默认预设

定义好预设后，我们需要启用cursory-mode，并告诉它默认使用哪个预设。

(cursory-mode 1) ; 全局启用cursory次要模式 ;; 设置默认预设。这将在没有其他调度规则匹配时生效。 (setq cursory-latest-state-preset ‘bar)

此时，如果你重启Emacs或重新加载配置，应该能看到光标变成了绿色的细竖线。你可以通过命令M-x cursory-set-preset来交互式地切换预设，试试看效果。

4. 高级配置：实现情境感知的自动切换

基础配置只是静态切换，cursory的真正威力在于自动调度。我们将配置两个最常用的自动切换场景：按模式切换和随主题切换。

4.1 基于缓冲区主模式的自动切换

我希望在编程时用细竖线，在写Org文档时用不闪烁的方块，在终端里用回传统块状光标。

;; 首先，确保我们有一个适合终端的预设 (add-to-list ‘cursory-presets ‘(term-block :blink-cursor-mode 1 :cursor-type box :cursor-color \"#ffffff\") t) ; 终端里常用白色 ;; 然后，配置模式调度器 (setq cursory-mode-actions ‘( ;; 所有派生自prog-mode的模式（elisp， python， go等）使用‘bar‘预设 (prog-mode . bar) ;; org-mode使用‘block‘预设（我们之前定义的关闭闪烁的方块） (org-mode . block) ;; 终端模式使用专门的‘term-block‘预设 (vterm-mode . term-block) (eshell-mode . term-block) (term-mode . term-block) ;; 对于其他所有模式，可以指定一个回退预设，比如‘small-block‘ (t . small-block) )) ;; 最后，将这个调度器添加到cursory的调度列表中 (add-to-list ‘cursory-dispatch-alist ‘(cursory-dispatch-by-mode . ,cursory-mode-actions))

原理说明：cursory-mode-actions是一个关联列表，将主模式符号映射到预设名。cursory-dispatch-by-mode是一个内置的调度函数，它会检查当前缓冲区的主模式，并在cursory-mode-actions中查找匹配项。我们将这个调度对(函数 . 配置)添加到cursory-dispatch-alist中。当cursory需要决定应用哪个预设时，它会按顺序遍历这个列表中的每个调度器，并使用第一个返回非nil结果的调度器所对应的预设。

4.2 与主题深度集成：智能颜色匹配

这是cursory最出色的功能之一。我们可以让光标颜色自动适应主题，始终保持高对比度。

;; 首先，定义一个使用动态颜色的预设 (add-to-list ‘cursory-presets ‘(auto-theme-bar :blink-cursor-mode 1 :cursor-type (bar . 2) ;; 关键在这里：cursor-color 是一个函数 :cursor-color (lambda () (face-attribute ‘cursor :background nil t))) t) ;; 解释：这个lambda函数返回当前‘cursor‘face的背景色。 ;; 一个设计良好的主题，其‘cursor‘face的背景色通常会设定为一个与主背景色对比鲜明的颜色。 ;; 因此，直接使用这个颜色作为光标颜色，是最简单的智能适配。 ;; 更高级的适配：使用cursory内置的辅助函数 (add-to-list ‘cursory-presets ‘(smart-block :blink-cursor-mode 0 :cursor-type box ;; protesilaos 提供的颜色选择函数，通常能给出极佳对比度 :cursor-color (lambda () (cursory-complement-color (face-attribute ‘default :background nil t)))) t)

为了让主题切换时能自动应用新颜色，我们需要配置基于主题的调度。

(setq cursory-theme-actions ‘( ;; 当使用modus-operandi（亮色主题）时，使用‘smart-block‘预设 (modus-operandi . smart-block) ;; 当使用modus-vivendi（暗色主题）时，使用‘auto-theme-bar‘预设 (modus-vivendi . auto-theme-bar) ;; 对于所有ef-themes系列主题，使用一个自定义函数决定 (ef-themes . (lambda (theme) (if (string-suffix-p \"-light\" (symbol-name theme)) ‘bar ; 亮色ef主题用细竖线 ‘block))) ; 暗色ef主题用方块 )) (add-to-list ‘cursory-dispatch-alist ‘(cursory-dispatch-by-theme . ,cursory-theme-actions))

实操心得：动态颜色函数在主题加载后才会被求值。因此，如果你在Emacs启动过程中就启用了cursory-mode，可能会在主题加载前看到一个默认颜色（可能是黑色或白色）的光标，主题加载后才会修正。这通常不是问题，但如果你追求完美的启动体验，可以考虑将cursory-mode的启用放在主题加载之后，或者使用(add-hook ‘after-load-theme-hook #‘cursory-refresh)在主题切换后强制刷新光标。

5. 实战技巧与疑难排查

5.1 组合多个调度条件

cursory-dispatch-alist的顺序决定了优先级。通常，更具体的条件应该放在前面。例如，你可能希望vterm-mode的规则优先于prog-mode的规则（因为vterm也派生自prog-mode？实际上vterm是独立模式，但这里只是举例）。你可以通过调整add-to-list的顺序来控制。

;; 清空后按优先级添加 (setq cursory-dispatch-alist nil) (add-to-list ‘cursory-dispatch-alist ‘(cursory-dispatch-by-mode . ,cursory-mode-actions)) (add-to-list ‘cursory-dispatch-alist ‘(cursory-dispatch-by-theme . ,cursory-theme-actions)) ;; 最后可以加一个保底的默认调度器 (add-to-list ‘cursory-dispatch-alist ‘(cursory-dispatch-latest . cursory-latest-state-preset))

5.2 调试与查看当前预设

当自动切换不符合预期时，调试很有必要。

• 命令：M-x cursory-debug-preset。这个命令会在回显区显示当前缓冲区应用的是哪个预设，以及是哪个调度器做出的决定。这是排查问题的一线工具。
• 变量：cursory-latest-state-preset。这个变量记录了全局最后使用的一个预设名。当所有调度器都返回nil时，就会使用这个预设。
• 手动覆盖：使用M-x cursory-set-preset设置的预设会具有最高优先级，直到下一次触发调度（如切换缓冲区、切换主题）。你可以用M-x cursory-restore-latest-state来恢复自动调度。

5.3 常见问题与解决方案

5.4 性能考量与最佳实践

cursory的调度逻辑在缓冲区切换、主题切换等事件时运行。为了保持Emacs的响应速度，应遵循以下原则：

1. 保持调度函数轻量：自定义调度函数应避免进行复杂的计算或IO操作。cursory-dispatch-by-mode和cursory-dispatch-by-theme这种基于哈希查找的内置函数效率很高。
2. 精简预设数量：预设列表不宜过长，通常5-10个完全足够。过多的预设会增加内存占用，尽管影响微乎其微。
3. 慎用全局钩子：除非必要，不要将cursory的刷新函数添加到post-command-hook这类高频触发的钩子上，这会导致性能下降。cursory默认的调度触发点（如window-state-change-hook，after-change-major-mode-hook）是经过考量的。

6. 超越默认：编写自定义调度函数

当内置的调度器无法满足你的复杂需求时，你可以编写自己的调度函数。这是一个高级功能，但能带来极大的灵活性。

假设你想实现：在工作时间（9:00-18:00）使用一种醒目的光标，在其他时间使用一种柔和的光标。

(defun my/cursory-dispatch-by-time () “根据当前时间返回预设名。” (let ((hour (string-to-number (format-time-string \"%H\")))) (if (and (>= hour 9) (< hour 18)) ‘daytime-block ; 白天使用这个预设 ‘nighttime-bar))) ; 晚上使用这个预设 ;; 定义这两个预设 (add-to-list ‘cursory-presets ‘(daytime-block :blink-cursor-mode 1 :cursor-type box :cursor-color \"#ff0000\") t) ; 白天用红色方块 (add-to-list ‘cursory-presets ‘(nighttime-bar :blink-cursor-mode 1 :cursor-type (bar . 1) :cursor-color \"#aaaaaa\") t) ; 晚上用灰色细线 ;; 将自定义调度器加入列表，可以放在比较靠前的位置以获得高优先级 (add-to-list ‘cursory-dispatch-alist ‘(my/cursory-dispatch-by-time . nil) t) ; 注意这里值是nil，因为函数直接返回预设名

关键点：自定义调度函数应返回一个预设名（符号），或者返回nil表示不匹配。在cursory-dispatch-alist中，其配置部分（cdr）被忽略，因为函数返回值直接用作预设名。

为了让这个时间调度能动态更新，你还需要一个定时器来定期刷新光标。这需要更精细的控制，但展示了cursory作为平台的可扩展性。

(defvar my/cursory--time-timer nil) (defun my/cursory-refresh-by-time () “强制根据时间调度刷新当前缓冲区光标。” (when cursory-mode (cursory-restore-latest-state))) ; 这个命令会重新运行所有调度器 ;; 在启用cursory-mode时启动定时器（每小时检查一次） (add-hook ‘cursory-mode-hook (lambda () (when cursory-mode (setq my/cursory--time-timer (run-at-time nil 3600 #‘my/cursory-refresh-by-time))) ; 3600秒 = 1小时 (unless cursory-mode (when my/cursory--time-timer (cancel-timer my/cursory--time-timer) (setq my/cursory--time-timer nil)))))

这个例子稍复杂，它展示了如何将外部状态（系统时间）与cursory的调度机制结合。在实际使用中，你可能不需要如此精细的时间控制，但这个模式可以应用于任何你能想到的条件：电池电量、外部光照传感器数据、当前项目类型等等。