Emacs 用久了的人都有一个共同的体验一旦习惯了键盘流和可编程的编辑环境再回到普通编辑器就会觉得处处别扭。但这两年 AI 编程助手铺天盖地绝大多数都做成了独立应用或者 VS Code 插件Emacs 用户反而成了被遗忘的群体。agent-shell 这个项目就是冲着这个缺口来的——它把 AI Agent 的能力直接嵌进 Emacs 的 shell 缓冲区里让 AI 对话、代码生成、命令执行都发生在你熟悉的那个窗口里不用切来切去。这篇内容适合两类人看一类是 Emacs 老用户想知道怎么把 AI 工作流接进自己的配置另一类是对 AI Agent 架构感兴趣的人想看看一个编辑器插件是怎么把 Agent 循环、工具调用、会话管理这些东西串起来的。我会从设计动机讲到核心机制再给出一套可复现的配置思路和实操中容易踩的坑。1. 为什么要在 Emacs 里跑 AI Agent1.1 编辑器集成 AI 的两种路线之争把 AI 接进编辑器业界大致走了两条路。一条是外挂式AI 助手作为独立进程或独立窗口存在编辑器只负责把选中代码发过去、把结果贴回来。另一条是原生式AI 能力直接长在编辑器的缓冲区模型里和编辑、补全、执行命令共享同一套交互范式。agent-shell 明显属于后者。这两条路的差别不是界面好不好看的问题而是工作流断裂程度的问题。外挂式方案里你每次和 AI 交互都要经历切窗口、复制、粘贴、切回来的循环这个循环在一天里重复几十次累积起来就是巨大的注意力损耗。原生式方案把 AI 对话变成一个普通的 buffer你可以用 Emacs 里所有已有的操作去处理它——搜索、跳转、kill-ring、宏录制全都适用。agent-shell 选择原生路线的另一个原因是 Emacs 本身的可编程性。Emacs Lisp 允许你把任意函数挂到任意 hook 上这意味着 AI 的输出可以直接触发后续的编辑动作而不需要你手动搬运。这种AI 输出即编辑指令的能力是外挂式方案很难做到的。1.2 agent-shell 到底解决了什么具体问题说具体一点。假设你在写一个 Python 脚本遇到一个报错传统流程是复制报错信息打开浏览器或独立 AI 应用粘贴等回复复制修复代码切回 Emacs找到位置粘贴。agent-shell 把这个流程压缩成在 shell buffer 里输入问题AI 回复直接出现在同一个 buffer你可以用 Emacs 的编辑命令直接操作回复内容。更关键的是上下文保持。独立 AI 应用每次对话都是孤立的你得反复粘贴项目背景。agent-shell 跑在 Emacs 里理论上可以把当前 buffer 内容、项目结构、甚至最近的编辑历史作为上下文喂给 Agent。这就从问答工具变成了结对编程伙伴。从热词里能看到 ai agent、ai 编程、ai 工程实践 这些词频繁出现说明大家关心的已经不是AI 能不能写代码而是怎么把 AI 写代码这件事工程化。agent-shell 的价值就在于它提供了一个工程化的容器——Agent 的会话状态、工具调用记录、错误重试都在一个可控的 buffer 里可追溯、可复现。1.3 目标用户画像与使用场景这个项目不是给所有人用的。如果你只是偶尔让 AI 帮你写个正则表达式那用网页版就够了没必要折腾 Emacs 配置。agent-shell 真正发挥价值的是这几类场景长时间沉浸式编码你一天有六七个小时在 Emacs 里任何需要离开 Emacs 的操作都是打断。多文件项目重构需要 AI 理解项目结构、跨文件修改而不是单文件问答。可复现的 AI 工作流你希望把让 AI 做某件事的流程固化成 Emacs 命令一键触发。对数据流向有要求你希望清楚知道哪些内容被发给了 AI哪些没有而不是黑盒。这几类场景的共同点是AI 是工作流的一部分而不是一个需要专门去访问的外部服务。agent-shell 的设计哲学就是让 AI 变成 Emacs 里的一个普通工具像 grep 或 compile 一样自然。2. agent-shell 的核心机制拆解2.1 shell buffer 作为 Agent 的宿主容器agent-shell 最核心的设计决策是把 Agent 跑在一个 shell buffer 里。这个选择乍看奇怪——shell buffer 不是用来跑命令行程序的吗但仔细想shell buffer 天然适合做 Agent 宿主原因有几个。第一shell buffer 本身就是输入-执行-输出的循环模型这和 Agent 的接收指令-调用工具-返回结果循环在结构上同构。第二shell buffer 支持异步输出AI 的流式回复可以像命令输出一样逐行追加不需要阻塞 Emacs 主线程。第三shell buffer 里的内容天然是文本可以被 Emacs 的任何文本处理功能操作。具体实现上agent-shell 会在 Emacs 里创建一个特殊的 buffer这个 buffer 的 major mode 继承自 shell-mode 或 comint-mode但重写了输入发送逻辑。当你在这个 buffer 里输入内容并回车时内容不是发给系统 shell而是发给 Agent 后端。Agent 的回复也不是直接打印而是经过一层解析区分出普通文本、工具调用请求、需要用户确认的操作等不同类型分别处理。这种设计的巧妙之处在于复用了 comint 的成熟机制。comint 已经解决了异步进程通信、输入历史、补全、字体锁定等一系列问题agent-shell 只需要在关键节点插入自己的逻辑不用从零造轮子。2.2 ACP 协议在编辑器与 Agent 之间的角色关键词里出现了 ACP这是理解 agent-shell 架构的关键。ACP 是 Agent Client Protocol 的缩写它定义了一套编辑器客户端和 AI Agent服务端之间的通信规范。你可以把它理解成 LSP 在 AI Agent 领域的对应物——LSP 让编辑器不用为每个语言单独写支持ACP 让编辑器不用为每个 AI 后端单独写适配。没有 ACP 的时候每接一个 AI 服务都要写一套适配代码这个服务的 API 格式是这样那个服务的流式响应是那样第三个服务的工具调用协议又不一样。有了 ACP编辑器只需要实现一次协议所有兼容 ACP 的 Agent 都能接进来。agent-shell 作为客户端负责把 Emacs 里的用户输入翻译成 ACP 消息把 ACP 响应翻译成 buffer 里的文本。Agent 作为服务端负责实际的模型调用、工具执行、上下文管理。这个分层让两边可以独立演进——Emacs 这边可以专注做交互体验Agent 那边可以专注做能力增强。从工程角度看ACP 的价值还在于它把会话这个概念标准化了。一个会话有 ID、有状态、有历史可以暂停、恢复、切换。这让 agent-shell 支持多会话并行成为可能——你可以开一个 buffer 让 AI 帮你重构代码同时开另一个 buffer 让 AI 帮你写文档互不干扰。2.3 Lisp 层如何编排 Agent 的输入输出Emacs 的灵魂是 Lispagent-shell 自然要用 Lisp 来做编排。这里的编排分几个层次。最底层是进程通信层用 Emacs 的make-process或start-process启动 Agent 进程建立管道。这一层要处理编码问题、换行符问题、进程退出重连问题都是些琐碎但必须做对的事。中间层是协议解析层把 ACP 消息解析成 Lisp 数据结构通常是 plist 或 alist再根据消息类型分发到不同的处理函数。这一层要处理流式响应的拼接、错误消息的识别、工具调用请求的拦截。最上层是交互层定义用户可见的命令和快捷键。比如agent-shell-send-region把选中区域发给 Agentagent-shell-insert-response把 AI 回复插入当前 bufferagent-shell-clear-session清空会话。这些命令都是普通的 Emacs 交互函数可以被绑定到任意快捷键也可以被其他 Lisp 代码调用。这种分层的好处是每一层都可以单独测试和替换。你想换个 Agent 后端只动进程通信层你想改交互方式只动交互层。对于想深入定制的人来说这个结构非常友好。2.4 会话状态管理与上下文窗口控制AI Agent 和普通问答最大的区别是它有状态。agent-shell 需要管理的不只是当前对话还有工具调用历史、文件修改记录、待确认操作队列等。这些状态如果管理不好就会出现AI 忘了刚才说过什么或者重复执行同一个操作的问题。上下文窗口控制是另一个难点。大模型的上下文长度有限不可能把整个项目都塞进去。agent-shell 的策略通常是分层加载当前文件内容优先相关文件按需加载项目结构摘要常驻。具体加载哪些、加载多少可以通过配置调整。这里有个实操中很容易忽略的点上下文不是越多越好。塞太多无关内容进去不仅浪费 token还会稀释真正重要的信息导致 AI 抓不住重点。我的经验是与其把十个文件都塞进去不如把最相关的一个文件完整塞进去再加一份项目结构说明。这个取舍需要根据具体任务调整没有万能公式。3. 从零搭一套可用的 agent-shell 工作流3.1 环境准备与依赖梳理动手之前先把依赖理清楚。agent-shell 本身是 Emacs 包但它依赖一个 ACP 兼容的 Agent 后端。这个后端可以是本地进程也可以是远程服务取决于你的部署方式。本地部署的好处是响应快、数据不出本机远程部署的好处是不占本地资源、可以用更大的模型。Emacs 版本方面建议用 28 以上。27 也能跑但 28 的 native-comp 和 JSON 解析性能提升明显对 agent-shell 这种频繁解析协议消息的场景帮助很大。如果你还在用 26建议先升级否则可能会遇到性能瓶颈。包管理用 straight.el 或 package.el 都行。straight.el 的优势是能锁定版本适合追求可复现配置的人。package.el 更简单适合快速试用。我个人的做法是先用 package.el 跑通确认好用之后再迁移到 straight.el 锁定版本。还需要确认的一件事是 Agent 后端的启动方式。有些后端是命令行程序直接make-process启动就行有些需要先起一个服务再连接。这个差异会影响你的配置写法动手前先看后端的文档。3.2 最小可用配置的逐行解读下面是一份最小可用配置的骨架我逐段解释为什么这么写。(use-package agent-shell :straight (:host github :repo owner/agent-shell) :commands (agent-shell agent-shell-send-region) :custom (agent-shell-backend-command (agent-backend --acp)) (agent-shell-default-session-name main) :config (setq agent-shell-auto-scroll t) (setq agent-shell-stream-timeout 60))agent-shell-backend-command指定后端启动命令。这里用列表而不是字符串是为了避免 shell 解析带来的转义问题。如果你的后端路径里有空格用列表形式就不用担心。agent-shell-default-session-name给默认会话起个名字。别小看这个当你开了多个会话之后能一眼看出哪个是哪个比一堆无意义的 buffer 名强太多。agent-shell-auto-scroll控制是否自动滚动到最新输出。流式回复的时候自动滚动能让你看到实时进展但如果你正在往上翻看历史自动滚动会把你拽回去。我的建议是默认开需要的时候用agent-shell-toggle-auto-scroll临时关掉。agent-shell-stream-timeout是流式响应的超时时间。设太短长回复会被截断设太长后端卡住的时候你要等很久。60 秒是个比较平衡的值具体可以根据你的后端响应速度调整。3.3 快捷键绑定与交互习惯养成配置跑通之后下一步是把常用操作绑到顺手的快捷键上。这里的关键是顺手的定义因人而异不要照抄别人的键位要根据你自己的肌肉记忆来。我自己的绑定方案是这样的C-c a s打开 agent-shell bufferC-c a r把选中区域发给 AgentC-c a i把 AI 回复插入当前 bufferC-c a c清空会话。这套键位的好处是都在C-c a前缀下不会和主流 major mode 冲突。养成交互习惯比配置本身更重要。我的建议是给自己定几条规则第一遇到报错先问 Agent不要直接搜网页第二让 Agent 改代码之前先让它解释思路第三Agent 给的代码不要直接粘贴先读一遍再决定。这几条规则看起来简单但能显著降低AI 给了错误答案我还照抄的概率。还有一个习惯值得培养把 Agent 的回复当成草稿而不是成品。AI 生成的代码经常有微妙的 bug或者不符合你项目的代码风格。把它当成一个起点你来打磨比直接信任要靠谱得多。3.4 多会话并行与项目隔离策略当你同时处理多个任务时单会话就不够用了。agent-shell 支持多会话每个会话有独立的上下文和历史。这里的关键是隔离策略——什么情况下该开新会话什么情况下该复用。我的经验是不同项目开不同会话同一项目的不同任务可以复用会话但要主动清理上下文。比如你在改 A 项目的登录模块同时要修 B 项目的样式问题这两个任务应该开两个会话否则 AI 会把两个项目的上下文混在一起给出莫名其妙的建议。会话命名也有讲究。用项目名-任务名的格式比如 myapp-auth、myapp-ui比 session-1、session-2 强太多。当你开了五六个会话之后能一眼找到想要的那个。清理上下文的时机也很重要。一个任务做完之后如果下一个任务和它无关应该清空会话或者开新会话。否则历史消息会占用上下文窗口挤掉真正有用的信息。agent-shell 通常提供agent-shell-clear-session之类的命令养成任务切换时清理的习惯。4. 实操中绕不开的那些坑4.1 流式响应卡顿与 buffer 刷新问题流式响应是 agent-shell 体验的核心但也是最容易出问题的地方。最常见的症状是AI 的回复一个字一个字往外蹦但 Emacs 界面卡住不刷新等全部回复完了才一次性显示出来。这个问题的根因通常是 buffer 刷新时机不对。Emacs 的 redisplay 是惰性的如果你在进程过滤器里直接插入文本但不触发刷新界面就不会更新。解决办法是在插入文本后调用redisplay或者用with-silent-modifications配合定时刷新。另一个可能的原因是字体锁定font-lock开销太大。每次插入新文本都触发重新字体化文本多了之后就会卡。解决办法是流式输出期间临时关闭 font-lock输出完成后再打开。这个优化在长回复场景下效果非常明显。还有一个隐蔽的坑是 GC垃圾回收。Emacs Lisp 的 GC 在对象多了之后会频繁触发导致卡顿。可以通过调大gc-cons-threshold来缓解但别调太大否则内存占用会飙升。我的经验值是 100MB 左右具体看你的机器配置。4.2 上下文丢失与 token 超限的排查路径AI 忘了刚才说的话是 agent-shell 用户最常见的抱怨之一。这个问题要分两种情况排查。第一种情况是会话状态真的丢了。可能是后端进程崩溃重启了也可能是会话 ID 变了。排查方法是看 agent-shell 的日志 buffer确认会话 ID 是否一致。如果 ID 变了说明会话被重建了历史自然就没了。第二种情况是上下文被截断了。大模型的上下文窗口有限当对话历史超过窗口大小时早期的消息会被丢弃。这个问题的表现是AI 记得最近几轮但忘了更早的。排查方法是看后端返回的 token 计数确认是否接近上限。解决上下文截断的思路有几个一是主动清理无关历史把重要的信息用摘要形式保留二是把关键上下文写进系统提示词这样不会被历史截断影响三是用支持更长上下文的模型。这三个思路可以组合使用具体看你的场景。4.3 工具调用权限与安全边界设置Agent 能调用工具是它强大的原因也是它危险的原因。如果 Agent 能执行任意 shell 命令、修改任意文件那一个错误的工具调用就可能造成不可逆的损失。agent-shell 通常提供权限控制机制让你决定哪些操作需要确认、哪些可以自动执行。我的建议是读操作可以自动写操作必须确认删除操作双重确认。这个策略看起来保守但能避免绝大多数事故。具体配置上一般有一个agent-shell-auto-approve之类的变量可以设置成白名单模式——只有列表里的操作自动执行其他都要确认。白名单要尽量小只放那些你完全信任的只读操作。还有一个容易被忽略的点是工作目录限制。Agent 执行命令时的当前目录应该是项目根目录而不是你的 home 目录。否则一个rm -rf打错路径后果不堪设想。agent-shell 一般允许你配置工作目录务必设对。4.4 后端进程崩溃后的恢复流程后端进程崩溃是难免的关键是怎么快速恢复。好的 agent-shell 实现应该有自动重连机制但自动重连不一定能恢复会话状态。我的做法是平时把重要的对话内容用agent-shell-save-session之类的命令导出到文件崩溃后先看能不能恢复不能恢复就从导出文件里找回关键信息。这个习惯看起来麻烦但真出事的时候能救命。另外后端崩溃往往有征兆比如响应变慢、报错增多。平时留意这些征兆在彻底崩溃前主动重启比崩溃后手忙脚乱要好。可以设一个定时任务每天重启一次后端进程保持状态干净。日志也是排查崩溃原因的重要依据。agent-shell 的日志 buffer 里通常有进程的 stderr 输出崩溃原因往往就在里面。养成崩溃后先看日志的习惯能省下很多瞎猜的时间。5. 把 agent-shell 用出花来的进阶思路5.1 用 Lisp 宏封装重复的 Agent 交互模式用了一段时间之后你会发现有些交互模式反复出现。比如把当前函数发给 Agent让它写单元测试把测试插入新 buffer这个流程每次都手动操作很烦。这时候就该用 Lisp 宏把它封装起来。(defun my/agent-generate-test () Send current function to agent and insert generated test. (interactive) (let ((func (thing-at-point defun t))) (agent-shell-send-string (format Write a unit test for this function:\n%s func)) (agent-shell-insert-response-into-new-buffer (format *test-%s* (buffer-name)))))这个函数把三步操作合成一步绑到快捷键上一键生成测试。类似的封装可以做很多一键生成文档、一键重构、一键解释代码。封装得越多你的 AI 工作流就越顺手。封装的时候注意一点不要把交互做得太魔法。如果封装后的行为不透明出了问题很难排查。我的原则是封装后的命令要有清晰的日志输出让你知道它到底发了什么给 Agent、Agent 回了什么。5.2 结合项目结构做上下文自动注入手动选择上下文很累更好的做法是根据项目结构自动注入。比如你在改src/auth/login.pyagent-shell 可以自动把同目录下的相关文件、项目的 README、依赖清单一起注入上下文。实现这个需要一点项目结构感知能力。简单做法是按目录约定——同目录文件自动加载父目录的 README 自动加载。复杂做法是解析 import 语句把被依赖的文件也加载进来。自动注入的度要把握好。注入太多会浪费 token注入太少 AI 又不够了解上下文。我的经验是当前文件必注入直接依赖注入间接依赖按需注入。这个策略在大多数项目里都能work。还有一个技巧是把项目结构摘要作为常驻上下文。用tree命令生成一份目录树精简后放进系统提示词让 AI 随时知道项目里有哪些文件。这个成本很低但效果很好。5.3 多 Agent 协作在 Emacs 里的落地方式热词里有 多 ai 协作这在 agent-shell 里是可以落地的。思路是开多个会话每个会话用不同的 Agent 后端或不同的提示词让它们各司其职。比如一个会话专门做代码生成提示词强调写简洁高效的代码另一个会话专门做代码审查提示词强调找 bug 和边界情况第三个会话专门做文档提示词强调写清楚易懂的说明。你写完代码先让审查会话过一遍再让文档会话生成说明最后自己整合。多 Agent 协作的关键是信息传递。会话之间不能直接通信需要你手动搬运关键信息。这看起来麻烦但好处是每一步都可控不会出现 Agent 之间互相误导的情况。进阶玩法是用 Lisp 写一个编排函数自动把 A 会话的输出发给 B 会话实现半自动的流水线。这个需要你对两个会话的协议都熟悉但一旦搭好效率提升很明显。5.4 会话记录导出与知识沉淀AI 对话里有很多有价值的信息——解决方案、代码片段、思路分析。如果不导出关掉 Emacs 就没了。养成导出习惯把这些信息沉淀下来长期看价值很大。导出的格式建议用 org-mode。org 支持代码块、标签、链接适合做知识管理。agent-shell 的回复可以直接导出成 org 格式代码块自动带上语言标记方便后续检索。导出之后还要做整理。我的做法是每周花半小时把这一周的会话记录过一遍把有价值的片段摘出来归到对应的主题文件里。这个习惯坚持几个月你就有了一份自己的 AI 辅助编程知识库。检索也很重要。org-mode 配合org-agenda或deft可以做全文检索需要的时候快速找到之前的解决方案。比重新问一遍 AI 要快得多而且答案是你验证过的更可靠。6. 我对 agent-shell 这类工具的真实看法用了几个月 agent-shell 之后我的感受是它不是一个让 AI 帮你写代码的工具而是一个让 AI 成为你编辑环境一部分的工具。这个区别很关键。前者你还是在用 AI后者 AI 变成了你工作流里的一个函数。它最适合的场景是那些需要频繁在写代码和问 AI之间切换的任务。如果你的工作流本来就是大段大段地写代码中间很少需要外部帮助那 agent-shell 的价值有限。但如果你经常遇到这个 API 怎么用来着、这段报错什么意思、帮我写个正则这类小问题agent-shell 能把每次切换的成本从十几秒降到一两秒累积起来很可观。配置上我的建议是循序渐进。先跑通最小配置用一周找到自己最常用的几个操作再针对性地优化。不要一上来就抄一份几百行的配置那样你既不知道每行是干嘛的出了问题也无从排查。最后分享一个我踩过的坑不要在生产环境的 Emacs 配置里直接试 agent-shell。用一个独立的配置文件或者emacs -Q加载最小配置来试确认稳定后再合并到主配置。我当初就是直接在主配置里改结果 agent-shell 的一个 bug 导致 Emacs 启动就卡死排查了半天才发现是它的问题。这个教训值得记住。