使用说明

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：手动安装

克隆此存储库或下载 cursor-agent.el
添加到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"))

快速开始

安装Cursor CLI （如果尚未安装）：
```
M-x cursor-agent-install
```
验证:
```
M-x cursor-agent-login
```
验证设置:
```
M-x cursor-agent-verify-setup
```
开始使用:
```
M-x cursor-agent-prompt
```

用法

基本命令

命令	描述
`cursor-agent-install`	安装Cursor CLI代理
`cursor-agent-prompt`	使用提示运行代理
`cursor-agent-interactive`	开始互动会话
`cursor-agent-region`	处理选定区域
`cursor-agent-resume`	恢复之前的对话
`cursor-agent-login`	使用游标进行身份验证
`cursor-agent-status`	显示身份验证状态
`cursor-agent-verify-setup`	验证安装和身份验证

高级命令

命令	描述
`cursor-agent-list-sessions`	列出所有以前的会话
`cursor-agent-list-models`	列出可用型号
`cursor-agent-mcp-list`	列出MCP服务器
`cursor-agent-shell-mode`	启动shell模式
`cursor-agent-update`	更新游标CLI
`cursor-agent-readme`	显示README文件

示例：处理代码区域

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

示例：交互式会话

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

配置

自定义包行为：

;; 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配置目录中并加载它：

将文件复制到Doom配置中：
```
cp cursor-agent.el ~/.config/doom/
```

添加到 ~/.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)))

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

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

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

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

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

跑 doom sync 安装

将配置添加到 ~/.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：本地目录（用于开发）

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

添加到 ~/.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

跑 doom sync
在中配置 ~/.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官方文档：

故障排除

找不到代理命令

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

身份验证问题

跑 M-x cursor-agent-login 鉴定
检查状态 M-x cursor-agent-status
使用验证设置 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，或（由您选择）任何更高版本。

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

作者

巧克力 - GitHub

致谢

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