Emacs 控制技能

使用 emacsctl 与正在运行的 Emacs 进行交互。

CLI 使用方式

emacsctl [选项]... [参数]...

选项：
  -i, --insert                执行插入操作
  -r, --replace               执行替换操作
  -b, --buffer BUFFER         指定用于插入或替换的 buffer；默认为当前 buffer
  -s, --save                  在插入或替换后保存 buffer
  -p, --position INSERT_POSITION
  -l, --line INSERT_LINE
  -c, --column INSERT_COLUMN
      --start-position REPLACE_START_POSITION
      --end-position REPLACE_END_POSITION
      --start-line REPLACE_START_LINE
      --end-line REPLACE_END_LINE
  -h, --help

emacsctl 需要在 agent 端和 Emacs 端均完成配置。请参考 https://github.com/calsys456/emacsctl 完成正确设置；若检测到 emacsctl 未安装或连接失败，请及时向用户提示。

求值（Eval）

基本原理是：emacsctl 从第一个参数或 stdin 获取一段 S-expression 字符串，然后在 Emacs 中通过 progn 对其执行 read 和 eval，最后打印最后一个表达式的返回值。

emacsctl '(emacs-version)'
# 使用管道
echo '(emacs-version)' | emacsctl 
# => "GNU Emacs XX.X.XX"

# 使用 HEREDOC 输入多行内容或含引号的内容
# 注意：HEREDOC 末尾会自动添加换行符
emacsctl < return-to-me

请谨慎使用交互式或阻塞式函数（例如 read-string、y-or-n-p），否则会导致命令挂起。

若操作出错，建议用户手动执行撤销（undo）或回退（revert）；仅当确认无重要修改或完全有把握时，才可自行调用 emacsctl '(undo)' 执行撤销。

执行 EVAL 时务必谨慎！

插入（Insert）

当指定 -i 时，emacsctl 将根据给定字符串、文件或 stdin 内容执行插入操作：

# 在 buffer emacsctl.el 的第 50 行第 15 列（位置 100）插入 "Hello"
emacsctl -i -b "emacsctl.el" -l 50 -c 15 -p 100 "Hello"

# 在当前 buffer 的位置 100 插入 your-code
emacsctl -i -p 100 <
EOF

# 将文件 ~/gpl-3.0.txt 的内容插入至当前 buffer 当前点位置，并保存 buffer
emacsctl -i -s ~/gpl-3.0.txt

替换（Replace）

当指定 -r 时，emacsctl 支持两种替换模式：按范围替换与按文本内容替换。

按范围替换

通过指定 --start-position 与 --end-position，或 --start-line 与 --end-line 来定义待替换区域：

# 将 buffer emacsctl.el 的前 5 个字符替换为 "XXXXX"
emacsctl -r -b "emacsctl.el" --start-position 1 --end-position 5 "XXXXX"

# 将当前 buffer 的第 50 至 100 行替换为 your-code，并保存 buffer
emacsctl -r --start-line 50 --end-line 100 -s <
EOF

按文本内容替换

提供两个字符串或两个文件，将第一个（旧文本）替换为第二个（新文本）：

# 将 buffer emacsctl.el 中距离当前点最近的 "(require 'function)" 形式替换为 ~/function.el 的内容
emacsctl -r -b "emacsctl.el" "(require 'function)" ~/function.el

# 将当前 buffer 中的 `to-be-refined` 函数替换为 `refined` 函数
emacsctl -r <(cat <
若存在多个匹配的旧文本，仅替换距离当前点最近的一个。如需批量替换或基于正则表达式的替换，请直接编写 ELisp 代码实现。
接口（Interface）
以下是一组专为 agent 设计的 ELisp 函数，均以 emacsctl- 开头，返回结构清晰、信息丰富的 Lisp plist。如条件允许，可通过 Eval 调用。
光标点（Point）与标记（Mark）
使用 (emacsctl-point-info &optional (surrounding 2)) 和 (emacsctl-mark-info &optional (surrounding 2)) 获取光标点与标记位置的信息及其上下文内容。
当前光标点以字符 “█” 标记，当前标记以字符 “▄” 标记。
Buffer
使用 (emacsctl-buffer-info &optional (buffer (current-buffer))) 获取 buffer 的状态与元数据。
使用 (emacsctl-buffer-imenu &optional (buffer (current-buffer))) 获取 buffer 的概览信息（如函数/变量列表等）。
使用 (emacsctl-buffer-list &optional match) 模糊匹配普通 buffer；类似地，使用 (emacsctl-hidden-buffer-list &optional match) 匹配隐藏 buffer。
Grep Buffer
使用 (emacsctl-grep pattern &optional (buffer (current-buffer))) 在 buffer 中搜索指定模式，返回匹配结果及其上下文。
使用 Emacs 特有的正则表达式语法。若构造复杂正则式有困难，推荐使用 rx 或 regexp-* 系列函数辅助生成。
读取 Buffer
函数签名：
(emacsctl-read-buffer &key (buffer (current-buffer))                              line (start-line line) (end-line line)                             position (start-position (or position (point-min))) (end-position (or position (point-max)))                             (surrounding 2)                             full-p)
示例：
;; 读取一个区域
(emacsctl-read-buffer :start-position  :end-position )
;; 读取若干行
(emacsctl-read-buffer :start-line  :end-line )
;; 读取某一行及其周围 20 行
(emacsctl-read-buffer :line  :surrounding 20)
;; 获取 buffer 的完整内容（请谨慎使用）
(emacsctl-read-buffer :buffer  :full-p t)

Window
使用 (emacsctl-query-window) 查看当前 frame 的窗口布局；使用 (emacsctl-select-window ) 根据 query-window 返回的索引切换至对应窗口。
Kill Ring（剪贴板）
使用 (emacsctl-query-kill-ring) 快速查看 kill-ring 内容概览；如需深度检索，请自行编写 ELisp 代码实现。
环境查询
搜索符号：使用 (emacsctl-search-symbol )；  
搜索命令：使用 (emacsctl-search-command )；  
搜索函数：使用 (emacsctl-search-function )；  
搜索变量：使用 (emacsctl-search-variable )。  
上述函数均返回包含丰富信息的结果。
查询模式（pattern）将按连字符（-）分段，并进行子串匹配；越精确的查询，返回的信息越详细。
使用提示
Emacs 控制技能并非用于替代其他工具调用。Emacs 是为具身人类设计的，而非为你服务。请优先使用高效、面向文件的其他工具完成工作；仅在确有必要或用户明确要求时，才使用 emacsctl。