cursor-agent.el

cursor-agent.el

增强的用于Emacs的Cursor CLI代理集成。此软件包提供了一个全面的界面，用于与 游标CLI代理 直接来自Emacs。

注： 此插件是使用创建的 光标 -AI驱动的代码编辑器，有助于加速开发。

特性

• 独立安装 -直接从Emacs安装Cursor CLI
• 安装和身份验证 -检查设置状态
• 交互式和非交互式模式 -灵活的使用模式
• 会话管理 -恢复之前的对话
• 模型选择 -选择您喜欢的AI模型
• 输出格式选项 -文本、JSON或流JSON格式
• Shell模式支持 -快速执行命令
• MCP服务器管理 -管理模型上下文协议服务器
• ANSI颜色支持 -输出缓冲区中的自动颜色处理
• 终端兼容性 -适用于GUI和终端Emacs

需求

• Emacs 27.1或更高版本
• Cursor CLI代理（可以通过软件包安装）
• 可选： vterm 用于更好的终端仿真的软件包（回退到 shell-mode 如果不可用）

安装

方法1：手动安装

1. 克隆此存储库或下载 cursor-agent.el
2. 添加到Emacs配置中：

(add-to-list 'load-path "/path/to/cursor-agent.el")
(require 'cursor-agent)

方法2：包装安装

M-x package-install-file RET /path/to/cursor-agent.el RET

方法3：使用软件包（如果已安装）

(use-package cursor-agent
  :load-path "/path/to/cursor-agent"
  :config
  (setq cursor-agent-default-model "gpt-5"))

快速开始

1. 安装Cursor CLI （如果尚未安装）：

   M-x cursor-agent-install

1. 验证:

   M-x cursor-agent-login

1. 验证设置:

   M-x cursor-agent-verify-setup

1. 开始使用:

   M-x cursor-agent-prompt

用法

基本命令

高级命令

示例：处理代码区域

1. 选择一个代码区域
2. 跑 M-x cursor-agent-region
3. 代理将处理代码并显示结果

示例：交互式会话

1. 跑 M-x cursor-agent-interactive
2. 直接在终端中键入提示
3. 使用标准终端导航

配置

自定义包行为：

;; Set default model
(setq cursor-agent-default-model "gpt-5")

;; Set default output format
(setq cursor-agent-default-output-format "json")  ; or "text", "stream-json"

;; Enable --force flag for file modifications
(setq cursor-agent-use-force t)

;; Change the command name (if different)
(setq cursor-agent-command "my-agent")

键绑定

默认情况下，该包不定义键绑定。添加您自己的：

;; Example keybindings
(global-set-key (kbd "C-c a a") 'cursor-agent-prompt)
(global-set-key (kbd "C-c a i") 'cursor-agent-interactive)
(global-set-key (kbd "C-c a r") 'cursor-agent-region)
(global-set-key (kbd "C-c a I") 'cursor-agent-install)
(global-set-key (kbd "C-c a L") 'cursor-agent-login)
(global-set-key (kbd "C-c a s") 'cursor-agent-status)

或与 use-package:

(use-package cursor-agent
  :bind (("C-c a a" . cursor-agent-prompt)
         ("C-c a i" . cursor-agent-interactive)
         ("C-c a r" . cursor-agent-region)
         ("C-c a I" . cursor-agent-install)
         ("C-c a L" . cursor-agent-login)
         ("C-c a s" . cursor-agent-status)))

可选依赖关系

vterm（推荐用于GUI Emacs）

为了在交互模式下更好地模拟终端（仅限GUI Emacs）：

M-x package-install RET vterm RET

重要提示：

• vterm需要GUI Emacs，无法在终端模式下工作
• 在终端模式下，包会自动使用 shell-mode （内置）
• 回退是无缝的-无需配置
• 所有函数在有或没有vterm的情况下都能正常工作

Doom Emacs用户： 如果你有 :term vterm 模块已启用，vterm已可用。

Doom-Emacs集成

此软件包与Doom-Emacs无缝协作。以下是推荐的集成方法：

方法1：本地包（推荐）

地方 cursor-agent.el 在Doom配置目录中并加载它：

1. 将文件复制到Doom配置中：

   cp cursor-agent.el ~/.config/doom/

1. 添加到 ~/.config/doom/config.el:

   ;; Load cursor-agent
   (load! "cursor-agent")

   ;; Optional: Configuration
   (setq cursor-agent-default-model "gpt-5")

   ;; Keybindings using Doom's map! macro
   (map! :leader
         (:prefix "c"  ; Code prefix
          (:prefix ("A" . "cursor-agent")
           :desc "Cursor Agent Install" "I" #'cursor-agent-install
           :desc "Cursor Agent Prompt" "a" #'cursor-agent-prompt
           :desc "Cursor Agent Interactive" "i" #'cursor-agent-interactive
           :desc "Cursor Agent Region" "r" #'cursor-agent-region
           :desc "Cursor Agent Resume" "R" #'cursor-agent-resume
           :desc "Cursor Agent List Sessions" "l" #'cursor-agent-list-sessions
           :desc "Cursor Agent Status" "s" #'cursor-agent-status
           :desc "Cursor Agent Login" "L" #'cursor-agent-login
           :desc "Cursor Agent List Models" "m" #'cursor-agent-list-models
           :desc "Cursor Agent MCP List" "M" #'cursor-agent-mcp-list
           :desc "Cursor Agent Shell Mode" "S" #'cursor-agent-shell-mode
           :desc "Cursor Agent Update" "u" #'cursor-agent-update
           :desc "Cursor Agent Verify Setup" "v" #'cursor-agent-verify-setup)))

1. 重新启动Emacs -没有 doom sync 本地文件需要！

方法2:Git仓库（用于更新）

如果你想通过Git跟踪包并获取更新：

1. 添加到 ~/.config/doom/packages.el:

   (package! cursor-agent
     :recipe (:host github
              :repo "chocoelho/cursor-agent.el"
              :files ("cursor-agent.el")))

1. 跑 doom sync 安装

1. 将配置添加到 ~/.config/doom/config.el --使用 after! cursor-agent 仅供 setq 以及密钥绑定。 不要 unload-feature 或 load 包裹在 after!；这会导致递归加载错误（请参见 已知问题):

   (after! cursor-agent
     (setq cursor-agent-default-model "gpt-5")
     
     ;; Keybindings
     (map! :leader
           (:prefix "c"
            (:prefix ("A" . "cursor-agent")
             "a" #'cursor-agent-prompt
             "i" #'cursor-agent-interactive
             "r" #'cursor-agent-region
             "I" #'cursor-agent-install
             "L" #'cursor-agent-login
             "s" #'cursor-agent-status)))

方法3：本地目录（用于开发）

如果您正在开发或希望将其保存在单独的目录中：

1. 添加到 ~/.config/doom/packages.el:

   (package! cursor-agent
     :recipe (:local-repo "/path/to/cursor-agent.el"   ; or "~/workspaces/personal/cursor-agent.el"
              :files ("cursor-agent.el")
              :build (:not compile)))   ; optional: faster iteration when not byte-compiling

1. 跑 doom sync

1. 在中配置 ~/.config/doom/config.el 如方法2中所示。 不要 unload-feature 或 load 游标代理 after! --它会导致递归负载错误。

随着 :local-repo，Doom/Straight在启动时可能只会自动加载一些命令。跑 M-x cursor-agent-install （或任何自动加载的命令）加载一次完整文件；之后，所有命令都可用。看 已知问题.

Doom Emacs键绑定

Doom-Emacs推荐的键绑定布局：

• SPC c A I -安装Cursor CLI
• SPC c A a -提示
• SPC c A i -互动环节
• SPC c A r -工艺区域
• SPC c A R -恢复会话
• SPC c A l -列出会话
• SPC c A s -状态
• SPC c A L -登录
• SPC c A m -列出型号
• SPC c A M -MCP服务器
• SPC c A S -外壳模式
• SPC c A u -更新CLI
• SPC c A v -验证设置

为什么 SPC c A?

• SPC c 是Doom的代码前缀（已用于代码操作）
• A （资本）保持人工智能相关命令的组织性
• 嵌套在代码前缀中用于逻辑分组

Doom Emacs提示

• 不 doom sync 需要 对于方法1（本地文件）-只需重新启动Emacs
• 使用 after! 宏 用于使用时的包配置 package! --只为 setq 以及密钥绑定， 不 为了 unload-feature 或 load 游标代理（导致递归负载）
• 使用 map! 宏 用于键绑定（Doom的DSL）
• vterm模块：如果你有末日 :term vterm 模块启用后，vterm将自动可用

已知问题

Doom Emacs/Straight：首次使用前命令不可用

《毁灭与直》(package! 和 :local-repo 或 :host github)，中只能显示命令的一个子集 M-x 在启动时。 跑 M-x cursor-agent-install （或任何其他自动加载的命令） 一次 装载整个包裹；之后，所有命令都可用。这来自Doom/Straight如何生成和应用自动加载；包裹本身具有 ;;;###autoload 所有命令。

Doom-Emacs：不要在配置中卸载/重新加载

不要 使用 unload-feature 和 load （或 load-file)of cursor-agent.el 内部A after! cursor-agent 块。这导致了 递归负载 在直构建路径和源路径之间（例如工作区或 :local-repo).使用 after! cursor-agent 仅用于配置(setq，键绑定）。该包已由Doom/Straight加载。

兼容性

这个包裹是 主要为vanilla Emacs设计和测试。它只使用标准的Emacs功能，没有特定于发行版的依赖关系。

支持的环境

• 香草Emacs 27.1+ （主要目标）

- GUI Emacs（X11、macOS、Windows） - 终端Emacs（交互式和非交互式会话）

• Emacs发行版 （兼容但不是专门针对的）

- Doom-Emacs（见上文Doom-Emacs集成部分） - Spacemacs - 任何其他Emacs发行版

设计原则

• 香草优先：所有代码都是针对vanilla Emacs编写和测试的
• 仅标准功能：仅使用内置的Emacs功能
• 无分布假设：不依赖于Doom Emacs、Spacemacs或其他发行版的功能
• 通用兼容性：适用于GUI和终端Emacs环境
• 优美的倒退：当可选软件包（如 vterm)不可用

文档

基于Cursor CLI官方文档：

• Cursor CLI概述
• 安装指南
• 使用指南

故障排除

找不到代理命令

1. 跑 M-x cursor-agent-install 安装
2. 确保 ~/.local/bin 在你的路径中
3. 安装后重新启动Emacs

身份验证问题

1. 跑 M-x cursor-agent-login 鉴定
2. 检查状态 M-x cursor-agent-status
3. 使用验证设置 M-x cursor-agent-verify-setup

vterm不可用

包裹将自动退回 shell-mode。为了获得更好的体验，请安装vterm：

M-x package-install RET vterm RET

测试

测试包括在 cursor-agent-test.el 使用ERT（Emacs Lisp回归测试）。在本地运行测试：

M-x load-file RET cursor-agent-test.el RET
M-x ert RET cursor-agent-test-.* RET

或者从命令行：

emacs --batch -l ert -l cursor-agent.el -l cursor-agent-test.el \
  --eval "(ert-run-tests-batch-and-exit 'cursor-agent-test-.* t)"

所有推送和拉取请求的测试都会在GitHub Actions上自动运行。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

此程序是自由软件：您可以重新分发和/或修改它 根据发布的GNU通用公共许可证条款 自由软件基金会，许可证版本3，或 （由您选择）任何更高版本。

看 许可证 文件以获取详细信息。

作者

• 巧克力 -

致谢

• 基于 光标CLI 文档
• 受需要更好地将Emacs与AI工具集成的启发
• 此插件是使用创建的 光标 -AI驱动的代码编辑器