#+TITLE: Emacs 代理 Shell #+AUTHOR: Álvaro Ramírez

[[https://melpa.org/#/agent-shell][file:https://melpa.org/packages/agent-shell-badge.svg]]

👉 [[https://github.com/sponsors/xenodium][通过 GitHub Sponsors 支持此项目]] 由 [[https://github.com/xenodium][@xenodium]] 提供（请查看我的 [[https://xenodium.com][博客]]）

[[file:agent-shell.png]]

• 本项目需要您的资助

在您为那些有用的 LLM token 付费的同时，不妨考虑[[https://github.com/sponsors/xenodium][赞助]]本项目的开发与维护。有了您的帮助，我可以让这项工作更加[[https://github.com/sponsors/xenodium][可持续]]。

感谢您！

[[https://xenodium.com/][Alvaro]]

• agent-shell

一个原生的 Emacs shell，用于与基于 ACP（[[https://agentclientprotocol.com][代理客户端协议]]）的 LLM 代理进行交互。

借助 agent-shell，您可以与 Gemini CLI、Claude Agent、Auggie、Mistral Vibe 或任何其他受 ACP 驱动的代理进行对话。

请观看[[https://www.youtube.com/watch?v=R2Ucr3amgGg][YouTube]]上的视频

[[https://www.youtube.com/watch?v=R2Ucr3amgGg][file:yt.png]]

• 新闻

• [[https://xenodium.com/agent-shell-0-47-1-updates][agent-shell 0.47 更新]]。
• [[https://xenodium.com/agent-shell-0-25-updates][agent-shell 0.25 更新]]。
• [[https://xenodium.com/agent-shell-016-improvements-melpa][agent-shell 0.17 改进 + MELPA]]。
• [[https://xenodium.com/agent-shell-0-5-improvements][agent-shell 0.5 改进]]。
• [[https://xenodium.com/introducing-agent-shell][介绍 Emacs 代理 Shell（基于 ACP）]]。
• [[https://xenodium.com/introducing-acpel][介绍 acp.el]]。

• 相关项目

=agent-shell= 依赖于[[https://github.com/xenodium/acp.el][acp.el]]，通过 ACP（[[https://agentclientprotocol.com/][代理客户端协议]]）与代理进行通信。

我们现在还有一些额外的包来扩展 =agent-shell= 的体验：

• [[https://github.com/xenodium/emacs-skills][emacs-skills]]：适用于 Emacs 的 Claude Agent 技能。
• [[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]：通过 Slack，从您的手机或其他设备与 =agent-shell= 会话互动。
• [[https://github.com/Embedded-Focus/agent-circus][agent-circus]]：在沙盒化的 Docker 容器中运行 AI 编码代理。
• [[https://github.com/cmacrae/agent-shell-sidebar][agent-shell-sidebar]]：=agent-shell= 的侧边栏插件。
• [[https://github.com/dcluna/agent-shell-bookmark][agent-shell-bookmark]]：为 agent-shell 会话提供书签支持。
• [[https://github.com/gveres/agent-shell-workspace][agent-shell-workspace]]：专门用于管理多个 =agent-shell= 会话的标签栏工作区。
• [[https://github.com/jethrokuan/agent-shell-manager][agent-shell-manager]]：=agent-shell= 缓冲区的表格视图和管理工具。
• [[https://github.com/nineluj/agent-review][agent-review]]：=agent-shell= 的代码审查界面。
• [[https://github.com/ultronozm/agent-shell-attention.el][agent-shell-attention.el]]：=agent-shell= 的模式行注意力跟踪器。
• [[https://github.com/xenodium/agent-shell-knockknock][agent-shell-knockknock]]：通过[[https://github.com/konrad1977/knockknock][knockknock.el]]为 =agent-shell= 提供通知。
• [[https://github.com/zackattackz/agent-shell-notifications][agent-shell-notifications]]：为 =agent-shell= 事件提供桌面通知。
• [[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]：一个用于 =agent-shell= 的多代理协调系统，具备代理间通信、任务跟踪和项目级调度功能。
• [[https://github.com/cxa/agent-shell-macext][agent-shell-macext]]：专为 =agent-shell= 设计的 macOS 特定增强功能。

• 图标

感谢[[https://github.com/lobehub/lobe-icons][Lobe Icons]]提供的精美图标。

• 设置

** 外部依赖

*** Claude Agent SDK

对于 Anthropic 的[[https://code.claude.com/docs/en/overview][Claude Agent]]（前身为 Claude Code），请遵循[[https://github.com/agentclientprotocol/claude-agent-acp][claude-agent-acp 指南]]，通常如下所示：

#+begin_src bash npm install -g @agentclientprotocol/claude-agent-acp #+end_src

注意： 使用 =-g= 标志是为了将二进制文件全局安装，使其位于您的 PATH 中。安装完成后，请通过在终端中运行 =which claude-agent-acp= 来验证其是否可用。

可选：如果您想使用 Claude 订阅，可能还需要[[https://code.claude.com/docs/en/overview][Claude Agent]]本身（至少在 Emacs 外部运行一次 CLI 以登录您的订阅，然后才能在 Emacs 中使用 =agent-shell=）。请按照 Claude Agent 的[[https://code.claude.com/docs/en/overview#get-started][入门指南]]进行安装。

*** Codex

对于 OpenAI 的 Codex，安装[[https://github.com/zed-industries/codex-acp][zed/codex-acp]]，并确保 codex-acp 可执行文件位于 PATH 中。

*** Gemini CLI

对于 Google 的[[https://github.com/google-gemini/gemini-cli][Gemini CLI]]，请确保获取支持 =--experimental-acp= 标志的最新版本。

*** Goose

对于 Goose CLI，安装[[https://block.github.io/goose/docs/getting-started/installation][goose]]，并确保 goose 可执行文件位于 PATH 中。

*** Cursor

对于 Cursor 代理，安装命令如下：

#+begin_src bash npm install -g @blowmage/cursor-agent-acp #+end_src

详情请参见 https://github.com/blowmage/cursor-agent-acp-npm。

*** Kiro CLI

对于 Kiro CLI，安装命令如下：

#+begin_src bash curl -fsSL https://cli.kiro.dev/install | bash #+end_src

详情请参见 https://kiro.dev/docs/cli/acp/。

*** Qwen Code

对于 Qwen Code，安装命令如下：

#+begin_src bash npm install -g @qwen-code/qwen-code@latest #+end_src

详情请参见 https://github.com/QwenLM/qwen-code。

*** Auggie

对于 Auggie CLI，安装命令如下：

#+begin_src bash npm install -g @augmentcode/auggie #+end_src

详情请参见 https://docs.augmentcode.com/cli/overview。

*** Mistral Vibe

对于 Mistral Vibe，安装命令如下：

#+begin_src bash uv tool install mistral-vibe #+end_src

详情请参见 https://github.com/mistralai/mistral-vibe。

*** Factory Droid

对于 Factory Droid，安装 =droid-acp= 客户端：

#+begin_src bash npm install -g droid-acp #+end_src

详情请参见 https://github.com/yaonyan/droid-acp。

*** Pi

对于 Pi 编码代理，安装 =pi-acp= 适配器：

#+begin_src bash npm install -g pi-acp #+end_src

详情请参见 https://github.com/svkozak/pi-acp。

** 安装

=agent-shell= 由内置的 =comint-shell= 提供支持，通过[[https://github.com/xenodium/shell-maker][shell-maker]]实现，可在[[https://melpa.org/#/shell-maker][MELPA]]上找到。

目前，[[https://melpa.org/#/agent-shell][agent-shell]]及其依赖项[[https://melpa.org/#/acp][acp.el]]均已上线 MELPA。

您可以通过以下方式安装：

#+begin_src emacs-lisp (use-package agent-shell :ensure t :ensure-system-package ;; 在此处添加代理安装配置 ((claude . "brew install claude-code") (claude-agent-acp . "npm install -g @agentclientprotocol/claude-agent-acp"))) #+end_src

这将自动安装所需的依赖项（[[https://melpa.org/#/acp][acp.el]] 和 [[https://melpa.org/#/shell-maker][shell-maker]])。

*** Doom Emacs

如果您使用的是 Doom Emacs，并希望使用 =package!= 宏：

#+begin_src emacs-lisp (package! shell-maker) (package! acp) (package! agent-shell) #+end_src

运行 =doom sync= 并重启。

在配置之前加入 =require=：

#+begin_src emacs-lisp (require 'acp) (require 'agent-shell) ;; 其余配置... #+end_src

** 配置

为您想要使用的代理提供商配置身份验证。

*** 环境变量

通过自定义 agent-shell-*-environment 变量并使用 agent-shell-make-environment-variables，可以将环境变量传递给启动的代理进程。该助手接受键值对，并在代理启动时导出这些变量。

#+begin_src emacs-lisp (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key") "HTTPS_PROXY" "http://proxy.example.com:8080")) #+end_src

**** 继承环境变量

默认情况下，代理进程会以最小化的环境启动。若要继承父级 Emacs 进程中的环境变量，可在 agent-shell-make-environment-variables 中使用 :inherit-env t 参数：

#+begin_src emacs-lisp (setenv "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key"))

(setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :inherit-env t)) #+end_src

这样可以确保来自 Emacs 会话的 PATH、HOME 等环境变量对代理进程可用，同时仍允许您覆盖或添加特定变量。

**** 从文件加载环境变量

您可以使用 :load-env 参数从 .env 文件中加载环境变量。此功能支持单个文件和多个文件：

#+begin_src emacs-lisp ;; 从单个 .env 文件加载 (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :load-env "~/.env" "CUSTOM_VAR" "custom_value"))

;; 从多个 .env 文件加载 (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables :load-env '("~/.env" ".env.local") :inherit-env t)) #+end_src

.env 文件应包含格式为 KEY=value 的变量，每行一个变量。以 # 开头的注释行和空行会被忽略。

*** Anthropic Claude

对于基于登录的身份验证（默认）：

#+begin_src emacs-lisp (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :login t)) #+end_src

对于 API 密钥身份验证：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :api-key "your-anthropic-api-key-here"))

;; 使用函数 (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "anthropic-api-key")))) #+end_src

对于 OAuth 令牌身份验证（即我们从 claude setup-token 获取的 =CLAUDE_CODE_OAUTH_TOKEN=）：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :oauth "your-oauth-token-here"))

;; 使用函数 (setq agent-shell-anthropic-authentication (agent-shell-anthropic-make-authentication :oauth (lambda () (auth-source-pass-get "secret" "anthropic-oauth-token")))) #+end_src

对于替代的 Anthropic 兼容 API 端点，可通过环境变量进行配置：

#+begin_src emacs-lisp (setq agent-shell-anthropic-claude-environment (agent-shell-make-environment-variables "ANTHROPIC_BASE_URL" "https://api.moonshot.cn/anthropic" "ANTHROPIC_MODEL" "kimi-k2-turbo-preview" "ANTHROPIC_SMALL_FAST_MODEL" "kimi-k2-turbo-preview")) #+end_src

*** Google Gemini

对于基于登录的身份验证（默认）：

#+begin_src emacs-lisp (setq agent-shell-google-authentication (agent-shell-google-make-authentication :login t)) #+end_src

对于 API 密钥身份验证：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-google-authentication (agent-shell-google-make-authentication :api-key "your-google-api-key-here"))

;; 使用函数 (setq agent-shell-google-authentication (agent-shell-google-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "google-api-key")))) #+end_src

对于 Vertex AI 身份验证：

#+begin_src emacs-lisp (setq agent-shell-google-authentication (agent-shell-google-make-authentication :vertex-ai t)) #+end_src

*** OpenAI Codex

对于基于登录的身份验证（默认）：

#+begin_src emacs-lisp (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :login t)) #+end_src

对于 API 密钥身份验证：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :api-key "your-openai-api-key-here"))

;; 使用函数 (setq agent-shell-openai-authentication (agent-shell-openai-make-authentication :api-key (lambda () (auth-source-pass-get 'secret "openai-api-key")))) #+end_src

*** Goose

对于 OpenAI API 密钥身份验证：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-goose-authentication (agent-shell-make-goose-authentication :openai-api-key "your-openai-api-key-here"))

;; 使用函数 (setq agent-shell-goose-authentication (agent-shell-make-goose-authentication :openai-api-key (lambda () (auth-source-pass-get 'secret "openai-api-key")))) #+end_src

*** Qwen Code

对于基于 OAuth 登录的身份验证：

#+begin_src emacs-lisp (setq agent-shell-qwen-authentication (agent-shell-qwen-make-authentication :login t)) #+end_src

*** Auggie

对于基于登录的身份验证（默认）：

#+begin_src emacs-lisp (setq agent-shell-auggie-authentication (agent-shell-make-auggie-authentication :login t)) #+end_src

对于无需身份验证的情况（当使用其他身份验证方法时）：

#+begin_src emacs-lisp (setq agent-shell-auggie-authentication (agent-shell-make-auggie-authentication :none t)) #+end_src

*** Mistral Vibe

对于 API 密钥身份验证：

#+begin_src emacs-lisp ;; 使用字符串 (setq agent-shell-mistral-authentication (agent-shell-mistral-make-authentication :api-key "your-mistral-api-key-here"))

;; 使用函数（复用 vibe 中配置的 API 密钥） (setq agent-shell-mistral-authentication (agent-shell-mistral-make-authentication :api-key (lambda () (string-trim (shell-command-to-string "source ~/.vibe/.env; echo $MISTRAL_API_KEY"))))) #+end_src

*** 自定义可用代理

默认情况下，=agent-shell= 包含所有受支持代理的配置（Claude Agent、Gemini CLI、Codex、Goose、Qwen Code 和 Auggie）。你可以通过 =agent-shell-agent-configs= 变量自定义哪些代理可用。

** 使用方法

*** 快速入门

=M-x agent-shell= - 启动或复用任何已知的代理。

你可以通过 =agent-shell= 的交互式命令选择并启动任何已知的代理 shell（参见 =agent-shell-agent-configs=），并在现有 shell 可用时复用它们。如果使用前缀参数（=C-u M-x agent-shell=），则会强制启动一个新的 shell 会话，从而实例化多个代理 shell。

*** 特定代理命令

直接启动特定代理的 shell 会话：

• =M-x agent-shell-anthropic-start-claude-code= - 启动 Claude Agent 会话
• =M-x agent-shell-auggie-start-agent= - 启动 Auggie 代理会话
• =M-x agent-shell-openai-start-codex= - 启动 Codex 代理会话
• =M-x agent-shell-google-start-gemini= - 启动 Gemini 代理会话
• =M-x agent-shell-goose-start-agent= - 启动 Goose 代理会话
• =M-x agent-shell-cursor-start-agent= - 启动 Cursor 代理会话
• =M-x agent-shell-kiro-start-agent= - 启动 Kiro CLI 代理会话
• =M-x agent-shell-mistral-start-vibe= - 启动 Mistral Vibe 代理会话
• =M-x agent-shell-qwen-start= - 启动 Qwen Code 代理会话
• =M-x agent-shell-droid-start-agent= - 启动 Factory Droid 代理会话
• =M-x agent-shell-pi-start-agent= - 启动 Pi 编码代理会话

*** 设置所有新 shell 的默认代理

你可以设置一个默认代理，用于通过 =agent-shell= 启动的所有新 shell，如下所示：

#+begin_src emacs-lisp (setq agent-shell-preferred-agent-config (agent-shell-anthropic-make-claude-code-config)) #+end_src

*** 配置 MCP 服务器

你可以通过 =agent-shell= 直接配置 MCP 服务器。这样可以避免在你使用的每个代理中重复配置。

#+begin_src emacs-lisp (setq agent-shell-mcp-servers '(((name . "notion") (type . "http") (headers . []) (url . "https://mcp.notion.com/mcp")))) #+end_src

** 在 Devcontainers / Docker 容器中运行代理（实验性）

=agent-shell= 提供了在容器中运行代理和 shell 命令的基本支持。

使用 =agent-shell-command-prefix= 来为启动代理的命令或需要在容器内执行的 shell 命令添加前缀。

*** 静态命令列表

#+begin_src emacs-lisp (setq agent-shell-command-prefix '("devcontainer" "exec" "--workspace-folder" ".")) #+end_src

*** 基于函数的配置

对于动态的每代理容器，可以提供一个函数，该函数接收当前的 agent-shell 缓冲区并返回命令列表：

#+begin_src emacs-lisp (setq agent-shell-command-prefix (lambda (buffer) (let ((config (agent-shell-get-config buffer))) (pcase (map-elt config :identifier) ('claude-code '("docker" "exec" "claude-dev" "--")) ('gemini-cli '("docker" "exec" "gemini-dev" "--")) (_ '("devcontainer" "exec" ".")))))) #+end_src

*** 每会话容器

你可以为不同的 shell 会话使用不同的容器，即使是相同类型的代理：

#+begin_src emacs-lisp (setq agent-shell-command-prefix (lambda (buffer) ;; 根据项目选择不同的容器 if (string-match "project-a" (buffer-name buffer)) '("docker" "exec" "project-a-dev" "--") else '("docker" "exec" "project-b-dev" "--")))) #+end_src

请注意，你可能传递给 =acp-make-client= 的任何 =:environment-variables= 不会应用到容器内的代理进程。预期应通过你的 devcontainer 配置 / Dockerfile 注入环境变量。

接下来，设置一个 =agent-shell-path-resolver-function=，用于解析本地工作目录中的容器路径，反之亦然。 Agent shell 提供了专门用于 devcontainers 的 =agent-shell-devcontainer-resolve-path= 函数：它读取 =.devcontainer/devcontainer.json= 中指定的 =workspaceFolder=，否则使用默认值 =/workspaces/=。

#+begin_src emacs-lisp (setq agent-shell-path-resolver-function #'agent-shell-devcontainer-resolve-path) #+end_src

请注意，这允许代理访问你本地文件系统上的文件。尽管已经采取措施限制对本地工作目录中文件的访问，但恶意代理仍有可能绕过这一限制。

可选：为了完全阻止容器内的代理访问你的本地文件系统，并使其直接在容器内读取或修改文件，除了设置解析函数外，还可以禁用“读写文本文件”的客户端能力：

#+begin_src emacs-lisp (setq agent-shell-text-file-capabilities nil) #+end_src

*** 数据存储位置

默认情况下，agent-shell 会将每个项目的数据（转录本、截图等）存储在项目根目录下的 =.agent-shell/= 目录中，并在首次创建该目录时自动将其添加到 =.gitignore= 中。这是一次性操作：从 =.gitignore= 中移除该条目并不会导致其再次被添加。

你可以通过设置 =agent-shell-dot-subdir-function= 为自定义函数来更改数据的存储位置。该函数接收一个参数 SUBDIR（例如 ="screenshots"=），并必须返回该子目录的绝对路径（无需创建该目录）。

例如，要将数据存储在 =user-emacs-directory= 而不是项目树中，将项目路径扁平化为目录名称：

#+begin_src emacs-lisp (defun my/agent-shell-dot-subdir (subdir) (let* ((cwd (string-remove-suffix "/" (agent-shell-cwd))) (sanitized (replace-regexp-in-string "/" "-" (string-remove-prefix "/" cwd)))) (expand-file-name subdir (locate-user-emacs-file (concat "agent-shell/" sanitized)))))

(setopt agent-shell-dot-subdir-function #'my/agent-shell-dot-subdir) #+end_src

这样，数据将存储在类似 =~/.emacs.d/agent-shell/home-user-src-myproject/screenshots/= 的路径下。

*** 从剪贴板发送截图

你可以使用 =agent-shell-send-clipboard-image= 将剪贴板中的截图发送到你的 shell。调用时使用 =C-u= 可以选择将截图发送到你的哪个 shell。agent-shell 依赖外部程序将剪贴板中的图像按 =agent-shell-clipboard-image-handlers= 中的配置写入文件。预配置的处理程序包括：

• =wl-paste= 用于 Wayland 桌面，
• =xclip= 用于 Xorg，
• =pngpaste= 用于 MacOS。

*** 写文件时抑制次要模式

某些次要模式（例如 =aggressive-indent-mode=）可能会干扰代理的编辑操作。Agent Shell 可以在应用编辑时临时禁用选定的每缓冲区次要模式。

#+begin_src emacs-lisp (setopt agent-shell-write-inhibit-minor-modes '(aggressive-indent-mode)) #+end_src

以上所有设置都可以通过[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html][目录局部变量]]在每个项目的基础上进行应用。

** 键绑定

• =RET= - 提交提示。
• =M-J= - 插入新行。
• =C-c C-c= - 中断当前代理操作
• =TAB 和 Shift-TAB= - 导航交互式元素

要自定义 =RET= 的绑定行为，可以使用如下代码：

#+begin_src emacs-lisp :lexical no (use-package agent-shell :bind (:map agent-shell-mode-map ("RET" . newline) ("M-RET" . shell-maker-submit))) #+end_src

或者，如果你更倾向于用 C-c C-c 来发送命令、用 C-c C-k 来中断，则可以使用以下配置：

#+begin_src emacs-lisp :lexical no (use-package agent-shell :bind (:map agent-shell-mode-map ("RET" . newline) ("C-c C-c" . shell-maker-submit) ("C-c C-k" . agent-shell-interrupt))) #+end_src

*** Evil Evil 用户可能希望重新绑定 RET 键：在 =插入模式= 下插入新行，在 =普通模式= 下提交命令。

此外，在查看差异（尚未接受更改时）时，每次都需要进入 =插入模式= 才能输入键值（~y/n/p/q 等），这可能会让人感到不便。如果是这种情况，可以让这些缓冲区默认以 Emacs 模式打开；如果需要切换到 Evil 模式，只需使用 C-z 即可。 #+begin_src emacs-lisp (use-package agent-shell :config ;; 根据 Evil 状态定制 RET 行为：插入模式下为 newline，普通模式下为 send (evil-define-key 'insert agent-shell-mode-map (kbd "RET") #'newline) (evil-define-key 'normal agent-shell-mode-map (kbd "RET") #'comint-send-input)

;; 配置 *agent-shell-diff* 缓冲区默认以 Emacs 模式启动
(add-hook 'diff-mode-hook
          (lambda ()
            (when (string-match-p "\\*agent-shell-diff\\*" (buffer-name))
              (evil-emacs-state)))))

#+end_src

• 自定义选项

#+BEGIN_SRC emacs-lisp :results table :colnames '("自定义变量" "描述") :exports results (let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^agent-shell" (symbol-name symbol)) (custom-variable-p symbol)) (push `(,symbol ,(car (split-string (or (documentation-property symbol 'variable-documentation) (get (indirect-variable symbol) 'variable-documentation) (get symbol 'variable-documentation) "") "\n"))) rows)))) (sort rows (lambda (a b) (string< (symbol-name (car a)) (symbol-name (car b)))))) #+END_SRC

#+RESULTS: | 自定义变量 | 描述 | |-----------------------------------------------+---------------------------------------------------------------------------------| | agent-shell-agent-configs | 已知代理配置的列表。 | | agent-shell-anthropic-authentication | Anthropic 身份验证的配置。 | | agent-shell-anthropic-claude-acp-command | Anthropic Claude 客户端的命令及参数。 | | agent-shell-anthropic-claude-command | Anthropic Claude 客户端的命令及参数。 | | agent-shell-anthropic-claude-environment | Anthropic Claude 客户端的环境变量。 | | agent-shell-anthropic-default-model-id | 默认的 Anthropic 模型 ID。 | | agent-shell-anthropic-default-session-mode-id | 默认的 Anthropic 会话模式 ID。 | | agent-shell-auggie-acp-command | Auggie 客户端的命令及参数。 | | agent-shell-auggie-authentication | Auggie 身份验证的配置。 | | agent-shell-auggie-environment | Auggie 客户端的环境变量。 | | agent-shell-buffer-name-format | 生成代理 Shell 缓冲区名称时使用的格式。 | | agent-shell-busy-indicator-frames | 忙碌指示器动画的帧。 | | agent-shell-clipboard-image-handlers | 将剪贴板图像保存到文件的处理程序。 | | agent-shell-completion-mode-hook | 进入或退出 ‘agent-shell-completion-mode’ 后执行的钩子。 | | agent-shell-command-prefix | 在容器中执行命令时使用的命令前缀。 | | agent-shell-context-sources | 确定 M-x agent-shell 自动上下文时考虑的来源。 | | agent-shell-cursor-acp-command | Cursor 代理客户端的命令及参数。 | | agent-shell-cursor-environment | Cursor 代理客户端的环境变量。 | | agent-shell-display-action | 代理 Shell 缓冲区的显示行为。 | | agent-shell-droid-acp-command | Factory Droid ACP 客户端的命令及参数。 | | agent-shell-droid-authentication | Factory Droid 身份验证的配置。 | | agent-shell-droid-environment | Factory Droid ACP 客户端的环境变量。 | | agent-shell-embed-file-size-limit | 使用 ContentBlock::Resource 嵌入的最大文件大小（字节）。 | | agent-shell-file-completion-enabled | 非 nil 值会在启动 Shell 时自动启用文件补全功能。 | | agent-shell-github-acp-command | GitHub Copilot 代理客户端的命令及参数。 | | agent-shell-github-default-model-id | 默认的 GitHub Copilot 模型 ID。 | | agent-shell-github-default-session-mode-id | 默认的 GitHub Copilot 会话模式 ID。 | | agent-shell-github-environment | GitHub Copilot 代理客户端的环境变量。 | | agent-shell-google-authentication | Google 身份验证的配置。 | | agent-shell-google-gemini-acp-command | Gemini 客户端的命令及参数。 | | agent-shell-google-gemini-environment | Google Gemini 客户端的环境变量。 | | agent-shell-goose-acp-command | Goose 客户端的命令及参数。 | | agent-shell-goose-authentication | Goose 身份验证的配置。 | | agent-shell-goose-environment | Goose 客户端的环境变量。 | | agent-shell-header-style | 代理 Shell 缓冲区标题的样式。 | | agent-shell-highlight-blocks | 是否高亮显示源代码块。 | | agent-shell-mcp-servers | 创建新会话时要初始化的 MCP 服务器列表。 | | agent-shell-mistral-acp-command | Mistral Vibe 客户端的命令及参数。 | | agent-shell-mistral-authentication | Mistral AI 身份验证的配置。 | | agent-shell-mistral-default-model-id | 默认的 Mistral AI 模型 ID。 | | agent-shell-mistral-default-session-mode-id | 默认的 Mistral AI 会话模式 ID。 | | agent-shell-mistral-environment | Mistral Vibe 客户端的环境变量。 | | agent-shell-openai-authentication | OpenAI 身份验证的配置。 | | agent-shell-openai-codex-acp-command | OpenAI Codex 客户端的命令及参数。 | | agent-shell-openai-codex-environment | OpenAI Codex 客户端的环境变量。 | | agent-shell-openai-default-model-id | 默认的 Codex 模型 ID。 | | agent-shell-openai-default-session-mode-id | 默认的 Codex 会话模式 ID。 | | agent-shell-opencode-acp-command | OpenCode 客户端的命令及参数。 | | agent-shell-opencode-authentication | OpenCode 身份验证的配置。 | | agent-shell-opencode-default-model-id | 默认的 OpenCode 模型 ID。 | | agent-shell-opencode-default-session-mode-id | 默认的 OpenCode 会话模式 ID。 | | agent-shell-opencode-environment | OpenCode 客户端的环境变量。 | | agent-shell-path-resolver-function | 用于解析本地文件系统上的远程路径，以及反向解析的函数。 | | agent-shell-permission-icon | 当 Shell 命令需要权限才能执行时显示的图标。 | | agent-shell-pi-acp-command | Pi ACP 客户端的命令及参数。 | | agent-shell-pi-environment | Pi 客户端的环境变量。 | | agent-shell-prefer-session-resume | 当同时存在 ACP 会话恢复和会话加载时，优先选择 ACP 会话恢复。 | | agent-shell-prefer-viewport-interaction | 非 nil 值会使 ‘agent-shell’ 更倾向于视口交互而非 Shell 交互。 | | agent-shell-preferred-agent-config | 所有新 Shell 的默认代理配置。 | | agent-shell-qwen-acp-command | Qwen Code 客户端的命令及参数。 | | agent-shell-qwen-authentication | Qwen Code 身份验证的配置。 | | agent-shell-qwen-environment | Qwen Code 客户端的环境变量。 | | agent-shell-screenshot-command | 用于截取屏幕截图的程序。 | | agent-shell-section-functions | 应用叠加层后运行的异常钩子（实验性）。 | | agent-shell-session-strategy | 启动新 Shell 时如何处理会话。 | | agent-shell-show-busy-indicator | 非 nil 值会在标题栏和模式行显示忙碌指示器动画。 | | agent-shell-show-config-icons | 是否在代理配置选择中显示图标。 | | agent-shell-show-context-usage-indicator | 非 nil 值会在标题栏和模式行显示上下文使用情况指示器。 | | agent-shell-show-usage-at-turn-end | 代理回合结束时是否显示使用信息。 | | agent-shell-show-welcome-message | 非 nil 值会显示欢迎消息。 | | agent-shell-text-file-capabilities | 代理是否被初始化为具有读写文本文件的能力。 | | agent-shell-thought-process-expand-by-default | 思考过程部分是否应默认展开。 | | agent-shell-thought-process-icon | AI 思考过程中显示的图标。 | | agent-shell-tool-use-expand-by-default | 工具使用部分是否应默认展开。 | | agent-shell-transcript-file-path-function | 用于生成完整转录文件路径的函数。 | | agent-shell-ui-mode-hook | 进入或离开 ‘agent-shell-ui-mode’ 后执行的钩子。 | | agent-shell-user-message-expand-by-default | 用户消息部分是否应默认展开。 | | agent-shell-write-inhibit-minor-modes | 在 ‘fs/write_text_file’ 编辑期间要禁用的次要模式命令列表。 |

• 命令

#+BEGIN_SRC emacs-lisp :results table :colnames '("绑定" "命令" "描述") :exports results (let ((rows)) (mapatoms (lambda (symbol) (when (and (string-match "^agent-shell" (symbol-name symbol)) (commandp symbol)) (push `(,(string-join (seq-filter (lambda (symbol) (not (string-match "menu" symbol))) (mapcar (lambda (keys) (key-description keys)) (or (where-is-internal (symbol-function symbol) comint-mode-map nil nil (command-remapping 'comint-next-input)) (where-is-internal symbol agent-shell-mode-map nil nil (command-remapping symbol)) (where-is-internal (symbol-function symbol) agent-shell-mode-map nil nil (command-remapping symbol))))) " 或 ") ,(symbol-name symbol) ,(car (split-string (or (documentation symbol t) "") "\n"))) rows)))) (sort rows (lambda (a b) (string< (cadr a) (cadr b))))) #+END_SRC

#+RESULTS: | 绑定 | 命令 | 描述 | |-----------------+---------------------------------------------------------+-------------------------------------------------------------------------------| | | agent-shell | 启动或复用现有的代理 Shell。 | | | agent-shell--display-buffer | 切换代理 SHELL-BUFFER 的显示。 | | | agent-shell-anthropic-start-claude-code | 启动交互式的 Claude 代理 Shell。 | | | agent-shell-auggie-start-agent | 启动交互式的 Auggie 代理 Shell。 | | | agent-shell-clear-buffer | 清空当前的 Shell 缓冲区。 | | | agent-shell-completion-mode | 切换带有 @ 或 / 前缀的代理 Shell 补全功能。 | | | agent-shell-cursor-start-agent | 启动交互式的 Cursor 代理 Shell。 | | C- | agent-shell-cycle-session-mode | 在当前 agent-shell 会话中循环切换可用的会话模式。 | | | agent-shell-delete-interaction-at-point | 删除光标处的交互内容（请求和响应）。 | | | agent-shell-droid-start-agent | 启动交互式的 Factory Droid 代理 Shell。 | | | agent-shell-fakes-load-session | 从文件加载并回放流量会话。 | | | agent-shell-github-start-copilot | 启动交互式的 GitHub Copilot 代理 Shell。 | | | agent-shell-google-start-gemini | 启动交互式的 Gemini CLI 代理 Shell。 | | | agent-shell-goose-start-agent | 启动交互式的 Goose 代理 Shell。 | | | agent-shell-help-menu | agent-shell 命令的临时菜单。 | | | agent-shell-insert-file | 将文件插入到 agent-shell 中。 | | | agent-shell-insert-shell-command-output | 执行 Shell 命令并将输出以代码块形式插入。 | | C-c C-c | agent-shell-interrupt | 中断正在进行的请求，并拒绝所有待处理的权限。 | | | agent-shell-jump-to-latest-permission-button-row | 跳转到最新的权限按钮行。 | | | agent-shell-mistral-start-vibe | 启动交互式的 Mistral Vibe 代理 Shell。 | | | agent-shell-mode | 代理 Shell 的主模式。 | | | agent-shell-new-shell | 启动一个新的代理 Shell。 | | S- | agent-shell-newline | 插入一个换行符，并将光标移动到新行的左边界。 | | C- 或 M-n | agent-shell-next-input | 按顺序向前循环浏览输入历史记录。 | | n 或 TAB | agent-shell-next-item | 移动到下一个项目。 | | | agent-shell-next-permission-button | 跳转到下一个按钮。 | | | agent-shell-open-transcript | 打开当前 agent-shell 缓冲区的对话记录文件。 | | | agent-shell-openai-start-codex | 启动交互式的 Codex 代理 Shell。 | | | agent-shell-opencode-start-agent | 启动交互式的 OpenCode 代理 Shell。 | | C-c C-o | agent-shell-other-buffer | 切换到另一个相关缓冲区（视口与 Shell 之间）。 | | C- 或 M-p | agent-shell-previous-input | 按顺序向后循环浏览输入历史记录，并保存输入。 | | p 或 | agent-shell-previous-item | 移动到前一个项目。 | | | agent-shell-previous-permission-button | 跳转到前一个按钮。 | | | agent-shell-prompt-compose | 在专用缓冲区中编写 agent-shell 提示词。 | | | agent-shell-queue-request | 根据 Shell 的繁忙状态，将请求加入队列或立即发送。 | | | agent-shell-qwen-start | 启动交互式的 Qwen Code CLI 代理 Shell。 | | | agent-shell-remove-pending-request | 移除所有待处理的请求，或根据 REMOVE-INDEX 移除特定的请求。 | | C-x x r | agent-shell-rename-buffer | 重命名当前的 Shell 缓冲区。 | | | agent-shell-reset-logs | 重置所有日志缓冲区。 | | | agent-shell-resume-pending-requests | 恢复处理队列中的待处理请求。 | | | agent-shell-run-all-tests | 以批处理模式运行所有 agent-shell 测试。 | | M-r | agent-shell-search-history | 搜索之前的输入历史。 | | | agent-shell-send-current-file | 将文件插入到 agent-shell 中。 | | | agent-shell-send-dwim | 将区域或光标处的错误发送到项目中最近访问过的 Shell 缓冲区。 | | | agent-shell-send-file | 将文件插入到 agent-shell 中。 | | | agent-shell-send-other-file | 提示用户发送文件到 agent-shell。 | | | agent-shell-send-region | 将区域发送到项目中最近访问过的 Shell 缓冲区。 | | | agent-shell-send-screenshot | 截取屏幕截图并将其插入到 agent-shell 中。 | | C-c RET | agent-shell-set-session-mode | 设置会话模式（如果有可用的模式）。 | | C-c C-v | agent-shell-set-session-model | 设置会话模型。 | | RET | agent-shell-submit | 提交当前的输入内容。 | | | agent-shell-toggle | 切换代理 Shell 的显示状态。 | | | agent-shell-toggle-logging | 切换日志记录功能。 | | | agent-shell-ui-backward-block | 跳转到上一个区块。 | | | agent-shell-ui-forward-block | 跳转到下一个区块。 | | | agent-shell-ui-mode | 用于 SUI 区块导航的次级模式。 | | | agent-shell-ui-toggle-fragment-at-point | 切换光标处片段内容的可见性。 | | | agent-shell-version | 显示 agent-shell 模式的版本号。 | | | agent-shell-view-acp-logs | 查看代理 Shell 的 ACP 日志缓冲区。 | | | agent-shell-view-traffic | 查看代理 Shell 的流量缓冲区。 | | | agent-shell-viewport-compose-cancel | 取消提示词的编写过程。 | | | agent-shell-viewport-compose-send | 将视口编写的提示词发送到代理 Shell。 | | | agent-shell-viewport-compose-send-and-kill | 将视口编写的提示词发送到代理 Shell，并关闭编写缓冲区。 | | | agent-shell-viewport-compose-send-and-wait-for-response | 将视口编写的提示词发送到代理 Shell，并在视口中显示响应。 | | | agent-shell-viewport-cycle-session-mode | 循环切换可用的会话模式。 | | | agent-shell-viewport-edit-mode | 用于编写代理 Shell 提示词的主模式。 | | | agent-shell-viewport-interrupt | 中断当前的代理 Shell 请求。 | | | agent-shell-viewport-next-item | 移动到下一个项目。 | | | agent-shell-viewport-next-page | 显示下一次交互（请求/响应）。 | | | agent-shell-viewport-previous-item | 移动到前一个项目。 | | | agent-shell-viewport-previous-page | 显示前一次交互（请求/响应）。 | | | agent-shell-viewport-refresh | 使用来自 Shell 的当前项目刷新视口缓冲区内容。 | | | agent-shell-viewport-reply | 作为后续回复并编写另一个提示词/查询。 | | | agent-shell-viewport-set-session-mode | 设置会话模式。 | | | agent-shell-viewport-set-session-model | 设置会话模型。 | | | agent-shell-viewport-view-last | 显示最近一次请求/响应的交互内容。 | | | agent-shell-viewport-view-mode | 用于查看代理 Shell 提示词的主模式（只读）。 |

• 提交问题 提交问题时，请保留[[https://github.com/xenodium/agent-shell/blob/main/.github/ISSUE_TEMPLATE/issue.md][问题模板]]中的复选框，并根据实际情况勾选。这些复选框有助于确保我获得足够的信息来提供帮助。

在提交问题或功能请求之前，请仔细阅读本节内容。只有当我掌握足够的信息时，才能为您提供帮助。本节将说明如何获取我所需的详细信息。

• 版本信息：您当前运行的 =agent-shell=、=acp.el=、ACP 包（例如 =claude-code-acp=）以及代理 CLI（例如 =claude=、=gemini=）分别是什么版本？
• 复现步骤：导致该问题的具体操作步骤是什么？请详细说明您执行了哪些操作以及它们的顺序。
• ACP 流量：请参阅上方的[[https://github.com/xenodium/agent-shell?tab=readme-ov-file#how-do-i-viewget-agent-client-protocol-traffic][如何查看/获取 ACP 流量]]。这是诊断问题时最有用的信息。
• 截图：截图有助于将您看到的内容与协议数据对应起来。
• 您的 agent-shell 配置：请分享您 Emacs 配置中与 =agent-shell= 相关的变量设置。
• 性能分析数据（针对性能问题）：使用 =M-x profiler-start= 启动性能分析，复现问题后，再使用 =M-x profiler-report=（并 =M-x profiler-stop=）生成报告。请一并提供该报告。

** 为什么 =agent-shell= 不会提供 CLI 代理中所有可用的斜杠命令/技能？

=agent-shell= 只能提供代理通过[[https://agentclientprotocol.com][代理客户端协议]]公开的斜杠命令和技能。要查看您的代理暴露了哪些内容，请展开“Available /commands”部分。如果您想要的命令未列出，请考虑向相应的代理（如 Gemini CLI）或其 ACP 层（如 claude-code-acp）提交功能请求。

[[file:slash-commands.png]]

** 能否添加对其他代理的支持？

该代理是否支持 ACP（[[https://agentclientprotocol.com][代理客户端协议]]）？如果支持，=agent-shell= 很有可能能够兼容该代理。有些代理内置了 ACP 支持（如 [[https://github.com/google-gemini/gemini-cli][gemini-cli]]），而另一些则需要单独的 ACP 包（如 [[https://github.com/zed-industries/claude-code-acp][claude-code-acp]] 用于 [[https://github.com/anthropics/claude-code][claude-code]]）。在提交添加新代理的功能请求时，请附上支持[[https://agentclientprotocol.com][代理客户端协议]]的项目链接（无论是内置还是独立的包）。

不支持 ACP 的代理不在 =agent-shell= 的集成范围内。不过，如果您构建了一个类似 =claude-agent-acp= 的 ACP 层，那么 =agent-shell= 就可以与其配合使用。

** =agent-shell= 行为不符合预期？

这可能是代理本身缺少[[https://agentclientprotocol.com][代理客户端协议]]相关功能，也可能是 =agent-shell= 缺少该功能，或者两者都有问题 :) 那到底是哪一方的问题呢？除非我们查看两者之间的[[https://agentclientprotocol.com][代理客户端协议]]流量，否则很难判断。

** 如何查看/获取[[https://agentclientprotocol.com][代理客户端协议]]流量？

1. 使用 =M-x agent-shell-toggle-logging= 开启日志记录。
2. 复现问题。
3. 使用 =M-x agent-shell-view-traffic= 查看流量。

浏览流量数据，看看是否能找到问题所在。例如，如果代理发送了一个请求，要求用户授权，但 =agent-shell= 并未提示用户进行授权，那么很可能 =agent-shell= 缺少相应功能。

以下是从流量查看器中显示的一个[[https://agentclientprotocol.com/protocol/schema#session%2Frequest-permission][session/request_permission]]请求示例。

[[file:traffic.png]]

有时，在问题中附上流量截图就足够了；而在另一些情况下，则需要提供完整的流量数据。您可以通过流量查看器使用 =M-x acp-traffic-save-to= 将流量保存为 =.traffic= 文件。

** 我应该在哪里提交 bug 或功能请求？

*** 代理相关的问题或功能请求

如果您确定问题是由于代理在其[[https://agentclientprotocol.com][代理客户端协议]]实现中缺少功能（或存在 bug），请直接向代理团队提交问题。例如：

• [[https://github.com/agentclientprotocol/claude-agent-acp][claude-agent-acp]]：适用于 Claude Agent。
• [[https://github.com/zed-industries/codex-acp][codex-acp]]：适用于 Codex。
• [[https://github.com/google-gemini/gemini-cli][Gemini CLI]]。
• [[https://block.github.io/goose/docs/getting-started/installation][Goose]]。
• [[https://github.com/QwenLM/qwen-code][Qwen Code]]。

*** =agent-shell= 相关的问题或功能请求

另一方面，如果您发现 =agent-shell= 缺少某些功能（或存在 bug），请前往[[https://github.com/xenodium/agent-shell/issues][提交 =agent-shell= 的问题]]。

*** 不确定该在哪里提交问题？

您可以先将问题提交到[[https://github.com/xenodium/agent-shell/issues][=agent-shell= 的仓库]]，但请尽量提供详细信息，以便我能判断是 =agent-shell= 还是代理本身需要改进。流量数据在此非常有帮助。如果您认为有帮助，请提供截图或 .traffic 文件。请参阅[[https://github.com/xenodium/agent-shell?tab=readme-ov-file#how-do-i-viewget-agent-client-protocol-traffic][如何获取 ACP 流量]]。

• 贡献说明

请参阅[[file:CONTRIBUTING.org][CONTRIBUTING.org]]。

• 贡献者

#+HTML: #+HTML: #+HTML:

由[[https://contrib.rocks][contrib.rocks]]制作。

agent-shell 快速上手指南

agent-shell 是一个原生的 Emacs Shell，基于 ACP (Agent Client Protocol) 协议，让你可以直接在 Emacs 中与各类 LLM 智能体（如 Claude Agent、Gemini CLI、Codex 等）进行交互。

1. 环境准备

系统要求

• Emacs: 建议最新版本
• 包管理器: 需配置好 MELPA 源
• Node.js / npm: 大多数 ACP 客户端依赖 Node.js 环境
• Python / uv: 部分客户端（如 Mistral Vibe）可能需要

前置依赖安装

在使用 agent-shell 前，必须先安装对应 AI 模型的 ACP 适配器。请根据你想使用的模型选择安装：

Claude Agent (Anthropic)

npm install -g @agentclientprotocol/claude-agent-acp
# 验证安装
which claude-agent-acp

注：如需使用订阅服务，请先在终端运行 claude 命令完成登录。

OpenAI Codex 确保安装 codex-acp 并将其加入 PATH。

Google Gemini CLI 需安装支持 --experimental-acp 标志的最新版本。

Cursor Agent

npm install -g @blowmage/cursor-agent-acp

Qwen Code (通义千问)

npm install -g @qwen-code/qwen-code@latest

Mistral Vibe

uv tool install mistral-vibe

其他模型 (Auggie, Kiro, Goose 等) 请参考项目 README 中的 "External dependencies" 章节安装对应的 CLI 工具。

---

2. 安装步骤

agent-shell 及其依赖 (acp.el, shell-maker) 均已托管在 MELPA 上。

方式一：使用 use-package (推荐)

在你的 Emacs 配置文件 (init.el 或 config.el) 中添加：

(use-package agent-shell
    :ensure t
    :ensure-system-package
    ;; 可选：自动安装系统依赖示例
    ((claude . "brew install claude-code")
     (claude-agent-acp . "npm install -g @agentclientprotocol/claude-agent-acp")))

方式二：Doom Emacs

在 packages.el 中添加：

(package! shell-maker)
(package! acp)
(package! agent-shell)

执行 doom sync 并重启 Emacs。

在配置文件中加载：

(require 'acp)
(require 'agent-shell)

---

3. 基本配置与使用

认证配置

在启动 Agent 前，需配置对应的 API Key 或登录状态。以 Anthropic Claude 为例：

方案 A：使用 API Key (字符串)

(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication :api-key "your-anthropic-api-key-here"))

方案 B：使用 auth-source 安全读取 (推荐)

(setq agent-shell-anthropic-authentication
      (agent-shell-anthropic-make-authentication
       :api-key (lambda () (auth-source-pass-get 'secret "anthropic-api-key"))))

方案 C：继承当前环境变量 如果已在终端导出过 ANTHROPIC_API_KEY，可直接继承：

(setq agent-shell-anthropic-claude-environment
      (agent-shell-make-environment-variables :inherit-env t))

其他模型（Google, OpenAI 等）配置方式类似，只需将 anthropic 替换为 google 或 openai。

启动 Agent

配置完成后，在 Emacs 中执行以下命令即可启动会话：

1. 按下 M-x (Alt + x)。
2. 输入 agent-shell 并回车。
3. 选择你要使用的 Agent 类型（例如 claude, gemini, cursor 等）。

此时会打开一个标准的 Comint Shell 缓冲区，你可以像使用普通终端一样与 AI 对话、发送代码或执行任务。

进阶提示

• 环境变量管理: 可使用 agent-shell-make-environment-variables 加载 .env 文件或设置代理。
• 多会话管理: 配合 agent-shell-workspace 或 agent-shell-manager 插件可更好地管理多个并发会话。