Emacs 集成 AI 代理：基于 ACP 协议打造智能工作台

1. 为什么要在 Emacs 里折腾一个 AI 工作台用 Emacs 的人大概都有过这种体验写代码写到一半想问问 AI 这段逻辑对不对于是切到浏览器、登录某个网页、粘贴代码、等回复、再切回来。来回几次之后思路断得七零八落。更别提有些项目需要多个 AI 模型协作一个负责生成、一个负责审查、一个负责补测试光是窗口切换就够让人烦躁的。agent-shell这个项目要解决的就是这个问题。它把 AI 代理直接嵌进 Emacs 的 buffer 里让你在写代码的同一个界面里跟 AI 对话、让 AI 执行任务、查看执行结果。核心关键词是Emacs、agent-shell、AI、ACP、Lisp——这五个词基本勾勒出了整个项目的轮廓用 Emacs Lisp 写的一个 shell 层通过 ACP 协议跟 AI 代理通信最终在 Emacs 里形成一个可交互的 AI 工作台。说白了它想做的事情是让 Emacs 从一个编辑器进化成一个 AI 工作台。你不需要离开 Emacs就能完成代码生成、代码审查、任务编排、结果验证这一整套流程。适合谁来参考三类人一是重度 Emacs 用户想把 AI 能力无缝接入现有工作流二是对 AI 代理编排感兴趣的开发者想看看 ACP 协议在实际项目里怎么落地三是喜欢折腾工具链的人想理解一个编辑器插件如何演变成工作台。我自己的感受是这类项目的价值不在于“又一个 AI 聊天窗口”而在于它把 AI 代理当成了 Emacs 的一等公民——可以像调用一个函数一样调用 AI可以把 AI 的输出直接插入 buffer可以让多个 AI 代理在同一个会话里协作。这种“自我进化”的思路比单纯加一个聊天面板要有意思得多。2. 项目整体设计与思路拆解2.1 核心思路把 AI 代理当成 Emacs 的“子进程”传统编辑器集成 AI 的方式大多是在侧边栏开一个 webview里面加载一个网页版聊天界面。这种做法的好处是开发简单坏处是 AI 和编辑器之间隔了一层AI 看不到你的 buffer 内容你也很难把 AI 的输出直接用到代码里。agent-shell走的是另一条路它把 AI 代理当成一个子进程来管理。Emacs 通过 ACP 协议跟这个子进程通信发送请求、接收响应、处理流式输出。这个设计思路跟 Emacs 里管理 LSP 服务器的方式很像——你不是在“打开一个网页”而是在“启动一个服务”然后通过标准协议跟它交互。为什么选 ACP 而不是直接调 HTTP API我的理解是ACP 是一个面向代理交互的协议它天然支持多轮对话、工具调用、流式输出这些 AI 代理场景需要的特性。如果直接用 HTTP API你得自己处理会话管理、上下文维护、工具调用解析这些琐事而 ACP 把这些都标准化了。另一个好处是ACP 是协议层面的抽象意味着底层可以换不同的 AI 后端而上层的 Emacs 集成代码不用大改。2.2 为什么用 Emacs Lisp 而不是外部脚本有人可能会问为什么不用 Python 写一个中间层然后 Emacs 调用这个中间层这样不是更灵活吗我试过类似方案结论是对于深度集成场景直接用 Emacs Lisp 更合适。原因有三点。第一Emacs Lisp 可以直接操作 buffer、point、mark 这些编辑器核心概念不需要通过 IPC 来回传数据。第二Emacs Lisp 的异步进程管理能力足够强make-process和make-network-process可以很好地处理子进程通信。第三少一层中间层就少一层故障点调试起来也简单——出问题了直接edebug或者message打日志不用跨语言排查。当然代价是 Emacs Lisp 的生态不如 Python 丰富一些复杂的文本处理可能需要自己写。但对于 agent-shell 这个场景核心逻辑是“转发请求、解析响应、渲染输出”这些用 Emacs Lisp 完全够用。2.3 自我进化的含义从工具到工作台标题里“自我进化”这个词值得展开说说。我理解它有两层含义。第一层是功能层面的进化agent-shell 不只是一个聊天窗口它还能让 AI 代理执行任务、调用工具、修改 buffer。这意味着 Emacs 从一个“被动编辑工具”变成了一个“主动工作台”——AI 可以在里面干活你可以在旁边看着也可以随时介入。第二层是架构层面的进化因为 ACP 是协议化的所以底层 AI 代理可以替换、可以升级、可以组合。今天用一个模型明天换一个更强的后天让两个模型协作上层的 Emacs 集成不需要重写。这种“协议稳定、实现可变”的架构让整个系统具备了持续进化的能力。2.4 方案选型的取舍与边界任何设计都有取舍。agent-shell 这种方案的优势是集成度高、响应快、可编程性强。但它的边界也很明显它假设用户是 Emacs 用户假设用户愿意配置 ACP 代理假设用户能接受在终端环境里跟 AI 交互。对于习惯图形界面、不想碰配置文件的人来说这个方案的学习曲线是陡的。另外把 AI 代理嵌入编辑器也带来一些新的问题比如 AI 修改了 buffer 内容你怎么知道改了哪些AI 执行了危险操作你怎么拦截这些在传统聊天窗口里不存在的问题在 agent-shell 场景下都需要考虑。项目本身可能提供了一些机制但作为使用者心里要有数。3. 核心细节解析与实操要点3.1 ACP 协议在 Emacs 里的落地方式ACP 的全称是 Agent Client Protocol它定义了一套客户端和代理之间通信的消息格式。在 agent-shell 里Emacs 扮演的是客户端角色AI 代理是服务端。通信方式通常是基于 stdio 的 JSON-RPC——Emacs 启动一个子进程通过标准输入输出跟它交换 JSON 消息。为什么用 stdio 而不是 TCP因为 stdio 更简单、更安全。子进程的生命周期跟 Emacs 绑定Emacs 退出子进程也跟着退出不会留下孤儿进程。而且 stdio 不需要处理端口占用、网络权限这些问题配置起来省心。实操中你需要确认几件事代理可执行文件的路径是否正确、启动参数是否匹配、JSON 消息的编码是否是 UTF-8。我踩过的坑是某些代理在启动时会往 stdout 打日志这些日志会污染 JSON 流导致解析失败。解决办法是看代理文档把日志重定向到 stderr 或者文件。3.2 会话管理与上下文维护AI 代理的核心是会话。一个会话里包含多轮对话、工具调用记录、上下文状态。agent-shell 需要管理这些会话的生命周期创建、切换、保存、恢复。这里的关键设计是会话隔离。不同项目、不同任务的会话应该分开避免上下文串味。我自己的做法是按项目目录创建会话每个会话绑定一个工作目录AI 代理在这个目录下执行操作。这样既保证了上下文的相关性也限制了 AI 的操作范围。另一个细节是上下文窗口管理。AI 模型的上下文长度是有限的对话轮次多了之后早期内容会被截断。agent-shell 如果提供了上下文压缩或摘要功能要善用如果没有就需要自己控制对话轮次或者定期开新会话。3.3 流式输出的渲染处理AI 生成内容是流式的一个字一个字往外蹦。在 Emacs 里渲染流式输出需要处理好几个问题。首先是性能。如果每收到一个字符就刷新一次 bufferEmacs 会卡。合理的做法是批量更新比如每收到 50 毫秒或者积累到一定字符数再刷新。其次是光标位置。流式输出时光标应该跟着内容走但不能影响用户在其他地方的操作。agent-shell 可能用了 overlay 或者 marker 来标记输出区域具体实现要看代码。还有一个容易被忽略的点是错误处理。流式输出中途如果代理崩溃了buffer 里可能留下半截内容。好的实现会检测到进程退出然后给出明确提示而不是让用户对着半截输出发呆。3.4 工具调用与权限控制AI 代理不只是聊天它还能调用工具——读文件、写文件、执行命令。这是 agent-shell 强大的地方也是危险的地方。从设计角度工具调用需要经过几个环节代理发起调用请求、客户端展示请求内容、用户确认或拒绝、客户端执行工具、结果返回给代理。其中“用户确认”这一步很关键它给了你一个拦截危险操作的机会。我的建议是默认开启确认除非你完全信任当前任务。比如让 AI 重构一个文件你可以允许它直接写但让 AI 执行 shell 命令最好还是看一眼再放行。另外工具调用的日志要保留方便事后审计——AI 到底改了哪些文件、执行了哪些命令这些记录在出问题时能救命。3.5 多代理协作的编排思路热词里提到了“多 AI 协作”这在 agent-shell 场景下是可行的。基本思路是启动多个代理进程每个代理负责不同的角色然后通过某种方式协调它们。一种简单的编排方式是串行流水线代理 A 生成代码代理 B 审查代码代理 C 写测试。每个代理的输出作为下一个代理的输入。这种方式实现简单但灵活性差。另一种是并行加汇总多个代理同时处理同一个任务然后由一个汇总代理整合结果。这种方式适合需要多视角的场景比如代码审查时让多个模型分别找问题然后合并去重。实操中多代理协作的难点不在启动多个进程而在结果整合和冲突处理。两个代理给出矛盾的建议时谁来裁决我的做法是引入一个“仲裁”步骤把矛盾点列出来人工决定或者让一个更强的模型来裁决。4. 实操过程与核心环节实现4.1 环境准备与依赖安装假设你已经有一个可用的 Emacs 环境建议 27 以上版本因为需要较好的异步进程支持。第一步是确认 Emacs 的版本和特性emacs --version然后确认你的 Emacs 是否支持make-process和json-parse-string。这两个是 agent-shell 类项目的基础依赖。可以在 Emacs 里执行(fboundp make-process) (fboundp json-parse-string)如果返回t说明支持。如果json-parse-string不支持可能需要升级 Emacs 或者安装json库作为替代。接下来是安装 agent-shell 本身。如果它发布在 MELPA 上可以用package-install如果是源码形式就 clone 下来加到load-path(add-to-list load-path /path/to/agent-shell) (require agent-shell)4.2 配置 ACP 代理连接这一步是核心。你需要告诉 agent-shell 去哪里找代理可执行文件、用什么参数启动。配置通常是一个 alist 或者 plist类似这样(setq agent-shell-profiles ((default :command your-agent-binary :args (--acp --stdio) :workdir /path/to/project)))参数说明:command是代理可执行文件路径:args是启动参数:workdir是工作目录。不同代理的参数可能不同具体看代理文档。配置好之后启动代理(agent-shell-start default)如果一切正常你会看到一个新的 buffer里面是代理的交互界面。如果启动失败先检查*Messages*buffer 里的错误信息常见问题包括可执行文件路径不对、参数不匹配、代理启动时崩溃。4.3 发送请求与接收响应启动代理后就可以发送请求了。基本流程是在 agent-shell buffer 里输入内容按某个快捷键发送然后等待响应。发送请求的底层实现通常是构造一个 JSON-RPC 消息写入子进程的 stdin(process-send-string (get-process agent-shell-default) (json-encode ((jsonrpc . 2.0) (method . chat/send) (params . ((message . 帮我看看这段代码)) (session . session-1)) (id . 1))))接收响应则是通过 process filter 或者 sentinel。process filter 处理流式数据sentinel 处理进程状态变化。一个简化的 filter 可能长这样(defun agent-shell-filter (proc output) (let ((lines (split-string output \n t))) (dolist (line lines) (when (not (string-empty-p line)) (let ((msg (json-parse-string line))) (agent-shell-handle-message msg))))))这段代码把输出按行分割逐行解析 JSON然后交给处理函数。实际项目中还需要处理缓冲区拼接、错误恢复、消息乱序等问题。4.4 工具调用的完整链路工具调用是 agent-shell 最有价值的功能之一。完整链路是这样的代理决定调用某个工具发送tool/call请求包含工具名和参数。客户端收到请求展示给用户确认。用户确认后客户端执行工具比如读文件、写文件、执行命令。客户端把执行结果封装成tool/result消息返回给代理。代理根据结果继续推理。以读文件为例客户端执行工具的核心代码可能是(defun agent-shell-execute-tool (tool-name params) (pcase tool-name (read_file (with-temp-buffer (insert-file-contents (alist-get path params)) (buffer-string))) (write_file (with-temp-file (alist-get path params) (insert (alist-get content params))) ok) (run_command (shell-command-to-string (alist-get command params)))))这里要注意路径安全。AI 代理可能传入任意路径如果不做校验它可能读到敏感文件或者写到不该写的地方。建议限制在工作目录内或者至少对路径做规范化检查。4.5 多代理协作的实操配置如果你想尝试多代理协作可以启动多个 profile(setq agent-shell-profiles ((generator :command agent-a :args (--acp) :workdir /project) (reviewer :command agent-b :args (--acp) :workdir /project) (tester :command agent-c :args (--acp) :workdir /project)))然后写一个简单的编排函数(defun agent-shell-pipeline (task) (let* ((code (agent-shell-send-sync generator task)) (review (agent-shell-send-sync reviewer code)) (tests (agent-shell-send-sync tester code))) (list :code code :review review :tests tests)))agent-shell-send-sync是一个同步发送并等待响应的辅助函数实现上可以用accept-process-output循环等待。实际使用中同步调用可能会阻塞 Emacs更好的做法是用异步加回调。5. 常见问题与排查技巧实录5.1 代理启动失败怎么办这是最常见的问题。排查顺序如下现象可能原因排查方法启动后立即退出可执行文件路径错误在终端手动执行命令看是否报错启动后无响应参数不匹配检查代理文档确认 ACP 模式参数报 JSON 解析错误stdout 被日志污染把代理日志重定向到 stderr报权限错误工作目录不可写检查目录权限或换一个目录我遇到过一次代理启动后一直卡住最后发现是代理在等一个交互式确认而 stdio 模式下没法输入。解决办法是加一个--non-interactive参数。5.2 流式输出卡顿或乱码卡顿通常是刷新太频繁导致的。可以加一个节流机制(defvar agent-shell-refresh-timer nil) (defun agent-shell-schedule-refresh () (unless agent-shell-refresh-timer (setq agent-shell-refresh-timer (run-with-idle-timer 0.05 nil #agent-shell-refresh)))) (defun agent-shell-refresh () (setq agent-shell-refresh-timer nil) (with-current-buffer (get-buffer *agent-shell*) (let ((inhibit-read-only t)) (goto-char (point-max)) (insert agent-shell-pending-output) (setq agent-shell-pending-output ))))乱码通常是编码问题。确认子进程的编码系统设置正确(set-process-coding-system proc utf-8-unix utf-8-unix)5.3 工具调用被拒绝或超时工具调用被拒绝可能是用户没确认也可能是代理没收到结果。检查两件事一是确认界面是否正常弹出二是结果消息是否正确发送。超时问题通常是代理在等结果而客户端在等用户确认双方僵住了。解决办法是加一个超时机制比如 30 秒没确认就自动拒绝并通知代理。5.4 会话上下文丢失如果发现 AI 忘记了之前的对话可能是会话 ID 变了或者上下文被截断了。检查会话 ID 是否在每轮请求里保持一致检查代理的上下文窗口设置。我的经验是长对话定期开新会话。与其让 AI 在超长上下文里挣扎不如把关键信息摘要出来开一个新会话继续。这样既省 token又避免上下文污染。5.5 性能优化的小技巧几个实测有效的优化点减少 buffer 刷新频率用 idle timer 批量刷新而不是每次收到数据就刷新。关闭不必要的语法高亮agent-shell buffer 里如果开了 font-lock流式输出时会很卡。限制历史记录长度buffer 里保留最近 N 轮对话即可太老的可以归档到文件。用inhibit-read-only批量插入比逐字符插入快很多。6. 我对这个项目的一些个人体会折腾 agent-shell 这类项目最大的收获不是“多了一个 AI 工具”而是理解了编辑器作为工作台的可能性。传统上我们把编辑器当成写代码的地方AI 当成查资料的地方两者是分开的。agent-shell 把这两者合到一起让 AI 成为编辑器的一部分这种思路上的转变比具体功能更有价值。另一个体会是协议化设计的重要性。ACP 把客户端和代理解耦让底层可以换、上层可以复用。这种设计在快速变化的 AI 领域特别重要——今天流行的模型明天可能就过时了但协议层是稳定的。如果你在自建类似工具建议也走协议化的路子别把业务逻辑和具体模型绑死。最后分享一个小技巧agent-shell 的 buffer 内容可以定期导出到文件作为项目的工作日志。我现在的做法是每次会话结束自动保存一份 markdown里面包含对话记录、工具调用、代码变更。过一段时间回头看这些日志本身就是很好的项目文档。这个习惯坚持了几个月比事后补文档靠谱得多。