1. 为什么要在 Emacs 里造一个 AI 工作台第一次听说有人把 AI 代理塞进 Emacs我的反应是这不是多此一举吗终端里跑个命令行工具浏览器里开个网页版哪个不比在 Emacs 里折腾舒服但用了两周 agent-shell 之后我改主意了。这东西解决的不是“能不能用 AI”的问题而是“AI 能不能长在你的工作流里”的问题。Emacs 用户大概都有这种体验写代码写到一半想查个 API 用法切到浏览器搜一下复制粘贴回来思路断了。想重构一段函数选中代码切到 AI 对话框粘贴等回复再复制回来又断了。每一次上下文切换都是一次注意力税。agent-shell 的核心价值就一句话让 AI 代理变成 Emacs 里的一个 buffer像编辑文件一样自然地跟它交互。这个项目基于 ACPAgent Client Protocol协议用 Lisp 写成本质上是在 Emacs 里实现了一个 AI 代理的客户端。你可以把它理解成“AI 版的 shell”——就像M-x shell让你在 Emacs 里跑终端命令一样M-x agent-shell让你在 Emacs 里跟 AI 代理对话、让它读写文件、执行代码、甚至自主完成多步任务。适合谁看三类人一是重度 Emacs 用户日常写代码、写文档、做笔记都在 Emacs 里完成想让 AI 无缝融入二是对 AI 代理感兴趣但不想被某个特定平台绑死的开发者ACP 协议意味着你可以接不同的后端三是喜欢折腾 Lisp、想看看怎么用纯文本配置搞定复杂交互的人。如果你只是偶尔用用 AI 写个邮件那确实没必要折腾这个网页版够用了。我踩过的第一个坑就是以为它只是个聊天窗口。实际上 agent-shell 的设计思路是“代理工作台”——它不只是让你跟 AI 说话而是让 AI 能操作你的项目文件、运行测试、查看 git 状态形成一个闭环。这个区别很关键后面会展开讲。2. 核心架构拆解ACP 协议到底解决了什么问题2.1 从“绑定模型”到“绑定协议”的思路转变早期在 Emacs 里接 AI主流做法是直接调某个厂商的 HTTP API。你写个函数拼 JSON发请求解析响应渲染到 buffer 里。能用但有个致命问题换一个模型或服务商代码就得大改。请求格式不一样认证方式不一样流式响应的解析方式也不一样。agent-shell 走的是另一条路它不直接跟模型对话而是跟一个实现了 ACP 协议的代理进程对话。这个代理进程可以是本地的也可以是远程的可以接这个模型也可以接那个模型。对 Emacs 来说它只需要会说 ACP 这一种“语言”剩下的交给代理去处理。这个设计的好处类比一下就很清楚。直接调 API 就像你每次点外卖都要记住每家店的电话、菜单、营业时间ACP 就像你用一个统一的外卖平台平台背后接了多少家店你不需要关心你只需要会点“下单”这一个操作。代理进程就是那个平台。提示ACP 是 Agent Client Protocol 的缩写核心思路是定义一套标准的消息格式让客户端这里是 Emacs和代理AI 后端之间的通信规范化。它不规定代理内部怎么实现只规定双方怎么说话。2.2 为什么用 Lisp 而不是外部进程有人会问既然代理是独立进程为什么客户端要用 Lisp 写用 Python 写个脚本Emacs 调一下不就行了能跑但体验差很多。Emacs 的强项是缓冲区即界面。用 Lisp 写agent-shell 可以直接把 AI 的输出渲染成一个原生 buffer支持 Emacs 的所有编辑操作光标移动、搜索、折叠、复制粘贴、甚至用键盘宏批量处理。如果用外部脚本输出只能以文本形式插入失去了 Emacs 的交互能力。更关键的是状态同步。AI 代理在执行多步任务时状态是不断变化的——正在读哪个文件、执行到第几步、有没有报错。用 Lisp 写这些状态可以直接映射到 Emacs 的变量和 buffer 局部变量上实现实时更新。用外部进程你就得自己维护一套状态同步机制复杂度陡增。还有一个实际考量Emacs 用户本来就熟悉 Lisp。出问题了C-h v查变量C-h f查函数edebug单步调试整套工具链都是现成的。如果核心逻辑在 Python 脚本里调试就得两头跑效率大打折扣。2.3 代理进程的职责边界理解 agent-shell 的架构关键要搞清楚代理进程负责什么、Emacs 负责什么。代理进程负责跟具体 AI 服务通信、管理对话历史、执行工具调用读文件、跑命令、搜索代码、维护任务状态。Emacs 负责提供用户界面、发送用户输入、渲染代理返回的内容、处理用户对代理输出的操作比如点击一个文件链接直接跳转。这个分工的好处是职责清晰。代理可以独立升级换模型、加工具、改策略都不影响 Emacs 端的代码。Emacs 端也可以独立演化改界面、加快捷键、优化渲染不需要动代理。我实际用下来最舒服的一点是代理在后台跑任务时Emacs 完全不卡。因为通信是异步的代理在那边慢慢处理Emacs 这边该干嘛干嘛结果回来了再更新 buffer。这比在 Emacs 里同步调 API 的体验好太多——后者一旦请求发出去整个编辑器就冻住了只能干等。3. 从零搭建环境准备与核心配置3.1 前置条件检查清单在动手之前先确认几件事。这些是我踩过坑之后总结的缺一个都可能卡住。检查项要求检查方法Emacs 版本27.1 及以上M-x emacs-version包管理器package.el 或 straight.elM-x package-list-packages能打开即可代理进程已安装并可执行终端里直接运行代理命令确认有输出网络能访问代理所需的服务取决于代理配置本地代理通常不需要外网Lisp 基础会看简单的配置代码能看懂setq、add-hook就行Emacs 版本这条特别说一下。27.1 是分水岭之前的版本对异步进程和 JSON 解析的支持不够完善agent-shell 用到的某些功能会报错。如果你还在 26.x建议先升级。我试过在 26.3 上硬跑能启动但流式输出会丢字符排查了半天才发现是版本问题。代理进程这块agent-shell 本身不绑定特定的代理实现。你需要根据自己用的 AI 服务准备对应的代理。常见的选择是官方提供的代理或者社区维护的兼容实现。安装方式通常是包管理器或者直接下载二进制具体看代理的文档。3.2 安装 agent-shell 的两种路径安装方式取决于你用哪个包管理器。我用的是 straight.el因为对 git 仓库的支持更直接。如果你用 package.el也不复杂。路径一package.el适合新手先把 MELPA 加到源里如果还没加的话(require package) (add-to-list package-archives (melpa . https://melpa.org/packages/) t) (package-initialize)然后M-x package-refresh-contents再M-x package-install RET agent-shell RET。装完之后在配置里加一行(require agent-shell)就算启用了。路径二straight.el适合已经用 straight 管理配置的人(straight-use-package (agent-shell :type git :host github :repo 你的仓库地址))straight 的好处是更新方便M-x straight-pull-all就能拉到最新代码。而且如果 agent-shell 依赖了其他包straight 会自动处理不用手动一个个装。注意不管用哪种方式装完之后建议先M-x agent-shell试一下能不能启动。如果报错说找不到某个函数或变量大概率是依赖没装全看看错误信息里提到的包名手动补上。3.3 最小可用配置agent-shell 的配置哲学是“默认能用按需定制”。下面是我建议的最小配置先跑起来再慢慢加东西。(require agent-shell) ;; 设置代理可执行文件的路径 (setq agent-shell-program 你的代理可执行文件路径) ;; 设置代理启动参数如果有的话 (setq agent-shell-args (--some-flag value)) ;; 绑定快捷键方便快速唤起 (global-set-key (kbd C-c a) agent-shell) ;; 设置默认的工作目录代理会在这个目录下操作文件 (setq agent-shell-default-directory ~/projects/)agent-shell-program这个变量是关键它告诉 Emacs 去哪里找代理进程。如果你把代理装在了非标准路径或者用了版本管理工具比如 asdf、nvm 之类的这里要写绝对路径不能只写命令名。我一开始写的是my-agent结果 Emacs 的 PATH 跟终端不一样死活找不到改成/usr/local/bin/my-agent就好了。agent-shell-default-directory也值得说一下。代理在执行文件操作时是相对于这个目录的。如果你经常在不同项目之间切换可以把它设成一个函数根据当前 buffer 的文件路径动态决定。比如(setq agent-shell-default-directory (lambda () (if buffer-file-name (file-name-directory buffer-file-name) default-directory)))这样代理就会自动以当前文件所在目录为工作目录省得每次手动切换。3.4 验证安装是否成功配置写完之后重启 Emacs或者 eval 一下配置然后M-x agent-shell。如果一切正常应该会弹出一个新的 buffer显示代理的欢迎信息或者提示符。如果没反应按这个顺序排查M-x list-processes看看有没有代理进程在跑。如果没有说明启动命令有问题。切到*Messages*buffer看看有没有报错信息。常见的错误包括“找不到可执行文件”、“权限不足”、“参数格式错误”。在终端里手动运行代理命令确认代理本身能正常工作。如果终端里都跑不起来Emacs 里肯定也不行。检查agent-shell-program的路径是否正确。可以用M-: (executable-find agent-shell-program)来验证返回 nil 就是路径不对。我遇到过一次诡异的情况终端里跑代理没问题Emacs 里就是不行。后来发现是环境变量的问题——代理依赖某个环境变量终端里设置了但 Emacs 启动时没继承。解决办法是在配置里显式设置(setenv SOME_VAR value)4. 日常使用把 AI 代理变成你的结对伙伴4.1 基本交互模式agent-shell 的交互方式跟普通 shell 很像但多了几个针对 AI 场景的优化。启动之后你会看到一个 prompt直接输入问题或者指令回车发送。代理的回复会流式显示在 buffer 里不用等全部生成完。这个流式体验很重要——AI 生成一段长回复可能要十几秒如果等全部完成再显示你会以为它卡死了。流式显示让你能看到它“正在想”心理上舒服很多。发送多行输入用C-j而不是回车。这个跟comint-mode的习惯一致回车是发送C-j是换行。刚开始可能会不习惯用几次就顺了。中断代理的输出用C-c C-c。有时候代理理解错了你的意思开始长篇大论你不想等了直接中断。中断之后可以重新输入更明确的指令。清空当前对话用C-c C-l具体快捷键可能因配置而异。这不会杀掉代理进程只是清掉 buffer 里的显示内容相当于“新开一个话题”。4.2 让代理操作你的项目文件这是 agent-shell 跟普通聊天窗口最大的区别。代理不只是“说”它还能“做”。比如你输入“帮我看一下 src/utils.py 里那个 parse_config 函数有没有明显的 bug。”代理会自己去读那个文件分析代码然后告诉你结果。你不需要手动复制粘贴代码。再比如“把 tests/ 目录下所有测试跑一遍看看有没有失败的。”代理会执行测试命令收集输出汇总结果。如果测试失败它还能进一步分析失败原因。这个能力的背后是代理的“工具调用”机制。代理不是直接访问你的文件系统而是通过一组预定义的工具读文件、写文件、执行命令、搜索来操作。每次调用工具都会在 buffer 里显示出来你能看到它做了什么。这个透明度很重要——你始终知道代理在干什么不会出现“它怎么把我文件改了”的惊吓。提示代理操作文件时默认是在agent-shell-default-directory下。如果你想让它操作其他目录的文件要么在指令里写绝对路径要么先切换工作目录。我常用的一个场景是代码审查。写完一个函数选中它M-x agent-shell-send-region然后输入“review this”。代理会分析选中的代码指出潜在问题。比手动复制到网页版快多了而且上下文不会丢。4.3 多轮对话与上下文管理agent-shell 会维护对话历史代理能看到之前的交互。这意味着你可以进行多轮对话逐步细化需求。比如第一轮“帮我写一个函数解析 CSV 文件。”代理给了一个版本。第二轮“加上错误处理如果文件不存在就返回空列表。”代理会在之前的基础上修改。第三轮“再加个参数控制是否跳过表头。”代理继续改。这个过程中代理始终记得之前的代码和你的要求不需要你重复说明。这比每次重新描述需求高效得多。但上下文也不是越长越好。对话太长之后代理的响应会变慢而且容易“忘记”早期的内容。我的经验是一个话题聊了十几轮之后如果还没搞定不如清空重来把最终需求整理清楚再问。这样反而更快。上下文管理还有一个技巧用 buffer 来隔离不同任务。M-x agent-shell每次都会新建一个 buffer每个 buffer 有独立的对话历史。你可以开一个 buffer 写代码另一个 buffer 写文档互不干扰。这比在一个超长对话里混着聊要清晰得多。4.4 快捷键与效率优化默认的快捷键已经够用但如果你想更顺手可以自定义一些。;; 在 agent-shell buffer 里用 C-c C-s 发送当前 region (with-eval-after-load agent-shell (define-key agent-shell-mode-map (kbd C-c C-s) agent-shell-send-region)) ;; 用 C-c C-p 发送当前 buffer 的文件路径 (define-key agent-shell-mode-map (kbd C-c C-p) agent-shell-send-file-path) ;; 用 C-c C-d 发送当前目录路径 (define-key agent-shell-mode-map (kbd C-c C-d) agent-shell-send-directory)这几个自定义快捷键是我用得最多的。agent-shell-send-region让你选中一段代码直接发给代理不用复制粘贴。agent-shell-send-file-path把当前文件的路径发过去代理就能直接读这个文件。agent-shell-send-directory类似发目录路径。还有一个提效技巧用 yasnippet 或 tempel 做指令模板。有些指令你经常用比如“解释这段代码”、“找 bug”、“写测试”可以做成模板输入几个字符就展开成完整指令。我定义了几个aiexplain→ “请解释以下代码的功能和实现思路”aibug→ “请检查以下代码是否有 bug如果有请指出并给出修复建议”aitest→ “请为以下代码写单元测试覆盖主要分支”这样每次只需要输入模板名选中代码发送一气呵成。5. 进阶玩法让代理真正“自主”起来5.1 多步任务与自主执行agent-shell 最让我惊喜的能力是代理可以自主执行多步任务。你给一个高层目标它自己拆解、执行、验证。举个例子。我输入“把项目里所有用 print 调试的地方改成 logging。”代理会搜索所有包含print(的文件逐个读取判断哪些是调试输出、哪些是正常输出对调试输出替换成logging.debug(...)检查文件头部有没有 import logging没有就加上汇总修改了哪些文件整个过程它自己完成我只需要在最后 review 一下改动。这个能力在重构、批量修改、代码迁移等场景下特别有用。但自主执行也有风险。代理可能会改错文件或者做出你不想要的改动。我的做法是先让它“只读”分析确认方案后再让它“写入”。比如先问“列出所有需要修改的地方”确认列表没问题再说“按这个列表修改”。这样多一步确认但安全很多。注意代理执行文件写入操作时建议先确保项目在版本控制下git 等。万一改错了git diff一看就知道git checkout就能回滚。没有版本控制的话代理改了什么你都不知道。5.2 自定义工具与扩展agent-shell 的代理通常支持自定义工具。你可以定义一些项目特定的操作让代理调用。比如你的项目有一套自定义的构建流程可以定义一个工具叫build-project代理需要构建时调用这个工具而不是自己拼命令。这样既保证了构建方式的一致性也避免了代理“发明”奇怪的命令。自定义工具的定义方式取决于代理的实现。通常是在代理的配置文件里写一段声明指定工具名、参数、执行的命令。Emacs 这边不需要改任何代码因为工具调用是通过 ACP 协议传输的对客户端透明。我定义过一个run-linter工具封装了项目的 lint 命令。代理在修改代码后会自动调用它检查如果 lint 报错就继续修直到通过。这个闭环非常爽——你只需要说“把这个函数重构一下确保 lint 通过”剩下的它自己搞定。5.3 与其他 Emacs 包的协同agent-shell 不是孤岛它可以跟其他 Emacs 包配合形成更强大的工作流。跟 projectile 配合projectile 知道当前项目的根目录、文件列表、项目类型。你可以写个函数把 projectile 的信息发给代理让它了解项目结构。(defun my/agent-shell-send-project-info () 把当前 projectile 项目的信息发送给 agent-shell。 (interactive) (let ((root (projectile-project-root)) (files (projectile-current-project-files))) (agent-shell-send-string (format 当前项目根目录%s\n项目文件列表\n%s root (mapconcat #identity files \n)))))跟 magit 配合magit 是 Emacs 里的 git 客户端。你可以让代理查看 git diff、生成 commit message、甚至执行 git 操作。(defun my/agent-shell-review-diff () 让 agent-shell 审查当前的 git diff。 (interactive) (let ((diff (magit-diff-buffer-file))) (agent-shell-send-string (format 请审查以下 git diff指出潜在问题\n%s diff))))跟 flycheck 配合flycheck 做实时语法检查。当 flycheck 报错时你可以一键把错误信息发给代理让它分析原因并给出修复建议。这些集成的核心思路是一样的把 Emacs 里已有的信息以代理能理解的形式发给它。代理不需要自己去发现这些信息你直接喂给它效率更高。5.4 性能调优与资源管理用久了之后你可能会发现 agent-shell 变慢。常见原因和解决办法对话历史太长。代理每次都要处理全部历史token 消耗大响应慢。解决办法是定期清空对话或者把长对话拆成多个短对话。代理进程占用内存过高。有些代理实现会缓存大量数据。可以在配置里限制缓存大小或者定期重启代理进程。M-x agent-shell-restart可以重启当前 buffer 的代理。流式输出卡顿。如果代理返回的内容很长Emacs 渲染可能跟不上。可以调整agent-shell-stream-delay如果存在这个变量增大延迟减少渲染频率。或者干脆关掉流式显示等全部生成完再显示。文件操作慢。如果项目很大代理搜索文件可能很慢。可以在代理配置里排除一些目录比如node_modules、.git、venv减少搜索范围。我自己的配置里加了一个自动清理机制当 buffer 里的行数超过 5000 行时自动清空前半部分。这样既保留了最近的上下文又不会让 buffer 无限膨胀。(defun my/agent-shell-trim-buffer () 当 agent-shell buffer 太长时删除前半部分内容。 (when ( (line-number-at-pos (point-max)) 5000) (let ((inhibit-read-only t)) (goto-char (point-min)) (forward-line 2500) (delete-region (point-min) (point))))) (add-hook agent-shell-mode-hook (lambda () (add-hook after-change-functions (lambda (rest _) (my/agent-shell-trim-buffer)) nil t)))6. 常见问题与排查实录6.1 启动失败类问题问题M-x agent-shell报错 “Searching for program: No such file or directory”这是最常见的启动错误原因是 Emacs 找不到代理可执行文件。Emacs 的 PATH 环境变量可能跟终端不一样尤其是 macOS 上通过 GUI 启动的 Emacs。解决办法用绝对路径。先在终端里which 你的代理命令找到完整路径然后(setq agent-shell-program /完整/路径/代理命令)如果路径里有空格或特殊字符用expand-file-name处理一下。问题代理启动了但立刻退出看*Messages*buffer 里的错误信息。常见原因代理需要的某个环境变量没设置或者代理版本跟 agent-shell 不兼容。环境变量问题这样解决(setenv PATH (concat (getenv PATH) :/usr/local/bin)) (setenv ANTHROPIC_API_KEY 你的密钥) ; 如果代理需要的话版本兼容问题看看 agent-shell 的文档里有没有说明支持的代理版本范围。太新或太旧的代理都可能有问题。问题代理启动了但 buffer 里没输出可能是代理在等待输入但 prompt 没显示出来。试着直接输入点什么回车看有没有反应。如果还是没输出检查代理的日志通常在~/.cache/或~/.local/share/下看看有没有报错。6.2 交互异常类问题问题中文输入显示乱码这是编码问题。Emacs 和代理之间的通信编码要一致通常都是 UTF-8。检查(setq default-process-coding-system (utf-8-unix . utf-8-unix))如果代理那边可以配置编码也确认一下是 UTF-8。问题流式输出时字符丢失或重复通常是渲染频率太高导致的。如果 agent-shell 有agent-shell-stream-delay之类的变量调大一点。或者关掉流式显示(setq agent-shell-streaming nil)问题发送长文本时卡住Emacs 在发送大量数据时可能会阻塞。可以分批次发送或者用异步发送函数如果 agent-shell 提供了的话。另一个办法是把长文本写到临时文件让代理去读文件而不是直接发送文本。6.3 代理行为异常类问题问题代理不执行文件操作只是“说”它会执行这通常是代理的工具调用权限没开。检查代理的配置确认文件读写、命令执行等工具是启用状态。有些代理默认只读需要显式开启写入权限。问题代理修改了不该修改的文件这是最危险的情况。预防措施确保项目在版本控制下代理操作前先让它列出计划修改的文件定期git diff检查改动。如果已经改错了git checkout -- 文件名可以恢复单个文件git reset --hard恢复全部慎用会丢失所有未提交的改动。问题代理“忘记”了之前的对话上下文窗口满了。代理能处理的 token 数量有限超出之后早期的内容会被丢弃。解决办法是清空对话重新开始或者把关键信息整理成一段简短的说明放在新对话的开头。6.4 性能问题速查表症状可能原因解决办法响应越来越慢对话历史太长清空对话或开新 buffer输入卡顿流式渲染太频繁调大 stream delay 或关闭流式文件搜索慢项目太大搜索范围广在代理配置里排除无关目录内存占用高代理缓存过多定期重启代理进程启动慢代理初始化耗时长检查代理配置减少启动时的加载项6.5 我踩过的三个坑坑一在错误的目录下启动代理。第一次用的时候我在 home 目录下M-x agent-shell然后让代理“找一下项目里的配置文件”。它在 home 目录下搜了半天把各种无关的配置文件都翻出来了。后来我养成了习惯先cd到项目目录再启动 agent-shell。或者配置agent-shell-default-directory自动跟随当前文件。坑二让代理执行危险命令。有一次我让代理“清理一下临时文件”它执行了rm -rf /tmp/*把我正在用的某个 socket 文件删了导致另一个程序崩溃。教训是给代理的指令要具体不要用模糊的“清理”、“优化”这类词。明确说“删除 /tmp/myapp/ 下超过 7 天的日志文件”而不是“清理临时文件”。坑三忽略代理的“思考过程”。agent-shell 会显示代理的中间步骤比如“正在读取文件 X”、“正在执行命令 Y”。我一开始觉得这些信息很烦想关掉。后来发现这些信息是排查问题的关键。代理行为异常时看它的思考过程就能知道是哪一步出了问题。现在我会保留这些显示只是把字体调小减少视觉干扰。7. 我对 agent-shell 的一些个人看法用了几个月之后我对 agent-shell 的定位越来越清晰它不是要替代终端里的 AI 工具也不是要替代网页版。它解决的是一个特定场景的问题——当你的主要工作环境是 Emacs 时如何让 AI 以最低的摩擦成本融入这个环境。这个场景可能只覆盖一部分人。如果你平时用 VS Code、IntelliJ 或者纯终端agent-shell 对你来说可能没什么吸引力。但如果你像我一样一天有六七个小时泡在 Emacs 里写代码、记笔记、管理任务、甚至收发邮件都在 Emacs 里完成那 agent-shell 带来的效率提升是实实在在的。它最大的价值不是“功能多强大”而是“不打断”。你不需要离开 Emacs不需要切换窗口不需要复制粘贴。AI 就在你的编辑器里像另一个 buffer 一样自然。这种“无感融入”的体验是任何外部工具都给不了的。当然它也有不完善的地方。配置门槛不低对新手不够友好代理的行为有时候不可预测需要花时间调教性能在长对话下会下降。但考虑到它还在快速迭代这些问题应该会逐步改善。如果你决定试试我的建议是从最简单的配置开始先跑通基本对话再逐步加功能。不要一上来就搞复杂的自定义工具和集成那样容易受挫。先用它帮你解释代码、写测试、查文档等熟悉了它的脾气再让它做更复杂的事。最后分享一个我最近发现的小技巧把 agent-shell 的 buffer 固定在一个专门的 window 里用display-buffer-alist控制它的显示位置。这样它就不会乱弹始终在屏幕右侧的一个固定区域像 IDE 的侧边栏一样。用熟了之后感觉就像 Emacs 长出了一个 AI 副驾驶。