1. 为什么我在 Emacs 里给 AI 开了一个“shell”这两年 AI 编程工具铺天盖地从 IDE 里的自动补全到独立 AI 编辑器每个人都想给 AI 找个合适的“工位”。我试过各种 Copilot 系的补全插件也折腾过 Cursor 这类全家桶但总有一种使不上劲的感觉——补全只是把 AI 当成一个更聪明的输入法而我想让它真正参与干活读代码、跑测试、查日志、改文件、分析构建错误。这些事不是光标附近几行代码能搞定的它需要 AI 拥有对整个项目上下文的感知能力。就在这时候我注意到 Emacs 生态里一个叫 agent-shell 的工具。名字很直白把 AI 接到 Emacs 的 shell 环境里让模型以“agent”的身份在你的工作台里实际执行任务。和传统的补全型 AI 工具不同它不盯着你的光标而是盯着你的终端上下文——你可以让 AI 自己去跑 grep、看 buffer、读编译输出再基于这些真实的执行结果给出判断。这个思路我第一时间就觉得对味了因为我需要的是一个能在 Emacs 里帮我把活干了的“搭档”不是只会接话的聊天机器人。这篇文章我就把我从安装配置到实际使用 agent-shell 的完整过程拆开包括核心操作、自定义 workflow、踩过的坑、以及我理解的“AI 工作台自我进化”到底进化在哪。无论你是 Emacs 老玩家还是刚接触 AI agent 编程的新手看完这篇你应该能自己搭一套可用的 agent 工作流出来。2. agent-shell 的核心设计思路为什么是“shell”而不是“补全”2.1 传统 AI 编程工具的两个盲区市面上大多数 AI 编程助手本质上解决的是“下一个字符/下一段代码是什么”的问题。它们把你的光标位置和周围代码塞进上下文然后预测你要写什么。这套路在写样板代码时确实快但一旦遇到跨文件逻辑、编译错误排查、测试失败分析它就显得无能为力——因为模型根本看不到程序运行时的真实输出看不到构建失败的具体报错更不可能主动去 grep 一下某个函数在哪定义。另一个盲区是工具链割裂。AI 建议你改了某个函数签名但你不确定影响范围得手动去搜引用AI 说“应该跑一下测试”但测试命令是什么、在哪个目录执行它完全不知道。整个流程中AI 只是动嘴动手的全是你。agent-shell 的设计出发点就是打破这种割裂让 AI 直接持有 shell 的执行能力读、查、跑然后基于真实反馈继续思考。2.2 agent-shell 的“agent”是怎么实现的agent-shell 的底层逻辑并不复杂但设计得很聪明。它本质上是一个桥梁把 Emacs 里的 buffer 内容、shell 执行结果、git 变更等状态包装成结构化的消息发给配置好的大模型 API模型返回的内容里可以包含“执行某条 shell 命令”的请求Emacs 端拿到这个请求后真的去执行再把执行结果回传给模型形成带真实反馈的循环。这里最关键的机制是工具调用tool calling / function calling。大模型本身不会执行命令但它可以输出一个结构化指令比如{tool: shell, command: grep -r \def foo\ .}agent-shell 负责解析这个指令、在当前 Emacs 的 shell 环境里运行、把 stdout/stderr 打包回传给模型。模型看到命令输出之后就能继续推理下一步。这就像你雇了一个实习生他看不懂代码的地方会自己去翻资料、跑命令然后把结果整理给你看而不是坐在那儿等你想办法。2.3 为什么这个方案适合 EmacsEmacs 作为宿主环境有几个天然优势是其他编辑器难以替代的。第一是 buffer 即上下文当前打开的文件、编译输出 buffer、shell buffer都是可以被 agent 直接读取的“状态”。agent-shell 可以把这些状态序列化后塞进 prompt模型看到的是和你屏幕上一致的现场而不是靠 你 粘贴代码片段。第二是扩展性Emacs Lisp 可以随时注册新的工具函数让 agent 不止能跑 shell还能操作 dired 文件列表、解析 org-mode 文档结构、读取 magit 的 git 状态——只要你想可以给 agent 装越来越多的“手”。我实操下来的感受是agent-shell 更像一个“让 AI 接入现有工作流”的粘合层。它不强求你改变使用习惯而是在你熟悉的 Emacs 环境中增加一个能对话、能执行、能反馈的 agent 会话。这种模式的可控性和透明度也更高每一步命令执行你都能看到出问题随时可以接管不会出现“AI 偷偷改了一堆文件你完全不知道”的情况。3. 从零配置 agent-shell环境准备与核心参数选择3.1 安装与最小可运行配置我的环境是 Emacs 29 以上版本macOS 系统使用 use-package 管理插件。agent-shell 目前在 MELPA 上可以直接安装配置起来很直接(use-package agent-shell :ensure t :after (shell) :bind ((C-c a s . agent-shell) (C-c a d . agent-shell-delete-session) (C-c a r . agent-shell-rename-session)) :custom (agent-default-model gpt-4o-mini) (agent-openai-api-base https://api.openai.com/v1) (agent-max-tokens 2048))注意API Key 我是通过环境变量OPENAI_API_KEY注入的不写死在配置里。这样做的好处是安全性和灵活性兼顾——同一份 Emacs 配置可以配合不同的 API 供应商只要切换环境变量就行。如果你用的是国内大模型服务商把agent-openai-api-base改成对应兼容地址即可大多数服务都兼容 OpenAI 的 chat completion 协议。装好之后M-x agent-shell就能开一个 agent 会话 buffer。首次会提示你输入 system prompt我通常用一段固定的“身份定义 工具说明”后文会给模板。3.2 关键参数调优模型、上下文长度和工具调用这里有几个参数是必须理解的直接决定 agent 好不好用。第一个是模型选择。agent-shell 的默认模型往往不是最强的那款但“强”和“好用”是两回事。代码分析场景需要一个指令遵循能力强的模型还需要它懂得什么时候该调用工具、调用什么工具。我用gpt-4o-mini做日常快速任务成本低响应快做复杂的跨文件重构时会切到gpt-4o或者更聪明的模型。你可以给自己的 workflow 里指定模型不用全局统一。第二个是agent-max-tokens。这个值限制模型单次回复的最大 token 数但这个数与工具调用的输出长度是两回事。模型生成一条 shell 命令然后 agent-shell 把执行结果可能很长塞回对话上下文里这才真正吃掉上下文窗口。所以真正需要关注的是agent-context-limit这类上下文上限设置我个人建议设成模型上下文窗口的三分之二左右留出余量给工具输出和对话历史。第三个容易被忽略的是工具调用的“确认模式”。agent-shell 默认会询问是否执行 model 请求的命令这个设置对安全性至关重要。我建议第一次使用不要关掉确认模式等熟悉了工具的输出规律再考虑对于只读命令如 grep、ls关闭确认写操作命令如 rm、sed -i永远保留确认。3.3 定义你的第一个 agent身份、技能、行为准则一个只有工具没有性格的 agent 用起来会很难受。我强烈建议花十分钟认真写 system prompt这决定了 agent 从“指令机器人”进化为“懂你的协作伙伴”的分水岭。我这边的模板供参考你是一个资深软件开发 agent工作环境是 Emacs。你可以通过工具执行 shell 命令、读取当前 buffer 内容、查看 git 状态。你的行为准则如下 1. 接到任务先理解需求不确定的地方先用 shell 命令探查代码结构不要瞎猜。 2. 每一步操作前简述你的意图给用户一个确认/干预的机会。 3. 优先使用项目现有的构建和测试命令不要新建临时脚本。 4. 如果一条命令的输出超过 200 行先截断重点再分析不要原文刷屏。 5. 修改文件前先输出 diff 预览。 6. 遇到错误信息把关键错误行和上下文贴出来再解释原因。 7. 回答尽量简洁结论在前过程在后。这段 prompt 解决了我最初使用 agent 时最烦的几个问题不听指令乱操作、输出爆炸式刷屏、改文件前不告知。其实把 agent 当成一个刚入职的实习生来立规矩你会发现自己需要制定的规则非常具体。4. agent-shell 核心操作拆解从会话管理到自定义工具调度4.1 会话管理多个 agent 并行处理不同任务agent-shell 的会话设计让我觉得很舒服的是它支持多会话隔离。我经常同时开三个 agent一个在处理前端代码的 bug一个在分析后端测试失败还有一个在帮我整理项目文档。每个会话有独立的上下文和历史互不干扰。操作上M-x agent-shell创建新会话并命名M-x agent-shell-delete-session删除不需要的会话M-x agent-shell-rename-session可以给会话改个有意义的别名。配合 Emacs 的consult或ivy插件M-x agent-shell-switch-session可以快速切换到任意会话。一个实用的技巧是给不同会话绑定不同的模型和 system prompt。我在处理前端 bug 的会话里用更严格的代码审查 prompt在写文档的会话里用更自由开放的文风 prompt。agent-shell 支持每个会话独立配置不会互相污染。4.2 上下文注入让 agent 真正“看到”你在看什么agent 与纯 ChatGPT 网页版的本质区别在于它可以实时读取 Emacs 里的状态。在我每天的使用中最常用的三个上下文注入手段是M-x agent-insert-buffer把当前 buffer 的内容插入对话让模型分析整个文件。M-x agent-insert-region只插入选中区域适合处理超大文件里的局部逻辑。M-x agent-shell-command直接执行一条 shell 命令并把输出插入对话相当于把终端“接入”agent 视野。组合起来的场景很典型我打开一个报错的 Vue 组件agent-insert-buffer把代码喂过去然后让 agent 自己跑npm run test复现问题。它能看到代码、测试输出、报错堆栈推理链条是完整的。这种“先让 AI 看到现场再让它动手验证最后提出修复方案”的模式比直接在网页版粘贴十几段代码问“哪里有问题”要高效太多了。有个小习惯插入 buffer 之前我会先M-x agent-clear-context清一下会话上下文避免上一个任务残留影响下一个任务。不同文件的编码、缩进风格差异会让模型产生错误联想上下文干净是稳定输出的前提。4.3 工具调度表给 agent 装上更多“手”agent-shell 内置的 shell 工具已经覆盖大多数场景但真正让它“自我进化”的是你自定义的工具。我使用最多的自定义工具有这么几个工具函数作用给我的价值agent-tool-git-diff查看当前分支的未提交变更让 agent 评审我的本地修改agent-tool-rg-search用 ripgrep 做全项目关键字搜索比 grep 更快路径更准确agent-tool-run-tests执行项目测试命令并捕获输出模型自主验证修改是否破坏功能agent-tool-read-buffer读取指定 buffer 的完整内容跨文件分析时直接投喂上下文注册一个自定义工具并不难核心是把 Emacs Lisp 函数包装成 agent 可调用的“函数描述”包括名称、参数说明、返回值。例如注册 ripgrep 工具(defun agent-tool-rg-search (query optional dir) Search QUERY in DIR using ripgrep, return matching lines. (shell-command-to-string (format rg -n --no-heading \%s\ %s query (or dir ./)))) (agent-tools-register :name rg_search :description Search codebase with ripgrep, returns file paths and matching lines. :execute #agent-tool-rg-search)模型在判断需要全局搜索时会自己调这个工具而不必经过我的agent-shell-command间接调用。这种“工具 模型自主决策”的组合就是 agent 从“问答机器人”转向“自主执行体”的关键一步——它不再事事问我“可以搜索吗”而是在任务范围内自行调度工具只在关键决策点找我确认。4.4 会话上下文的清洗与持久化一个我踩过的坑是长会话使用几小时后上下文越来越臃肿模型开始记错前面的内容。agent-shell 虽然有一定的上下文截断机制但默认策略往往是保留前面的旧消息这对代码分析场景并不总是最优。我的经验是当任务告一段落就清理对话历史但保留一份摘要作为“备忘”。做法很简单让 agent 自己总结当前会话的关键成果和未完成事项然后把这段总结复制到一个单独的 org 文件里再M-x agent-shell-clear-history清空该会话。下次继续时第一步先把摘要贴进对话让 agent 以此为起点。这相当于给 agent 做了“记忆压缩”既保留有效信息又不让上下文无限膨胀。这个习惯也符合我一直强调的理念agent 应该被当成临时协作者而不是长期记忆库。重要的判断和结论永远要沉淀到自己的笔记系统里。5. 工作流实战用 agent-shell 解决真实开发问题5.1 场景一编译错误定位与修复建议假设你在一个 Rust 项目里跑cargo build爆出一堆 borrow checker 错误。传统做法是逐个看错误行手动跳转到对应文件。现在我的流程是(agent-shell-command cargo build 21 | head -100)把编译输出插入 agent 会话接着告诉 agent“分析这段编译错误指出 root cause并给出对应的代码修改建议。”模型会调用rg_search在项目里搜索相关代码位置把文件片段读进来分析最后给你一份带具体行号、修改思路的回答。有意思的地方在于borrow checker 的错误经常牵涉多个变量、多个生命周期标注网页版对话需要你反复粘贴上下文而 agent-shell 可以让模型自己去翻代码。改完后还可以让它跑cargo test验证是否真的修好了。整个闭环都在 Emacs 里完成不用切窗口、不用复制粘贴。5.2 场景二跨文件重构前的影响面分析“帮我看看如果把UserService的getUserInfo改成异步会影响哪些地方”——这种任务在 agent-shell 里特别好使。让模型先rg_search getUserInfo找到所有引用点再逐个read_buffer读取相关文件的关键片段最后输出一份带影响等级直接报错、需要改调用、无影响的清单。这事的难点不在“搜代码”而在“理解引用关系和影响的传播路径”。模型需要结合多个文件的上下文做推理agent-shell 的 buffer 读取能力让这种跨文件分析轻松很多。实际操作时我会要求 agent 按照“调用链路径”而不是“文件列表”来组织回答这样我能快速判断哪些调用点需要重点关注。5.3 场景三写测试用例agent 自己跑、自己改这是我日常觉得最“值回票价”的场景。让 agent 为某个函数写单元测试它先读源文件、理解逻辑、生成测试代码然后我让它自己跑测试。如果断言失败它会看到pytest的输出分析失败原因修正测试代码或通知我源文件可能有 bug再重新跑。几轮循环下来它往往能自己搞定测试的正确性。实现方式是给 agent 一个明确的任务指令请为 src/parser.py 中的 parse_config 函数编写单元测试。 先用 rg 找现有的测试文件格式保持风格一致。 写完后运行 pytest tests/test_parser.py 验证。 如果有失败先分析是测试问题还是源问题修复后重新运行直到通过。这需要 agent 具备在一个循环里“工具调用 → 用户确认 → 工具执行 → 结果反馈 → 再决策”的能力。agent-shell 的确认机制在这里不是负担反而帮我看清每一步它想干什么防止它修改源文件来讨好测试。基本上每轮我都要盯着它到底改了哪个文件。5.4 场景四日志分析让 AI 当你的排障副驾驶还有一类场景让我觉得 agent-shell 价值极大线上日志或复杂构建日志的排查。日志文件经常几千行直接贴给 AI 既不现实也没效率。我把日志文件路径告诉 agent让它用 shell 工具自行采样、grep 关键字、统计频次。有一段真实的经历某个接口在高峰期偶发超时我让 agent 分析 nginx 访问日志。它用了tail、awk统计耗时超过 500ms 的请求再用rg找出某个 user-agent 的特征最后结合代码仓库里的超时设置给出“这个异常集中在老旧客户端发起的无认证请求上”的结论。这种分析一个月前我可能要手动做半小时现在交给 agent 十几分钟就出结果了。6. 我踩过的坑与排查实录6.1 工具调用超时模型“卡住”怎么办我最开始遇到的典型问题是模型偶尔会在某个工具调用上“卡住”表现为等很久也不见后续输出对话 buffer 里只有一个半截的命令行。排查后发现是 API 请求的 timeout 设置太紧模型在思考工具调用时要花的时间比普通对话长。解决方式是调大 Emacs HTTP 请求的超时时间可以用url-http的相关变量或者plstore缓存但最直接的办法是换一个响应更快的模型作为默认。另外如果你是自建 API 网关或使用复杂的代理配置模型返回结果会经过额外一跳超时现象更明显。这个可以通过agent-shell-request-timeout参数不同版本名称略有差异调整但经验是别把超时设太短长一点的等待好过模型推理到一半被切断。6.2 输出乱码与编码问题UTF-8 是 Emacs 的默认编码但项目里总有几个文件是 GBK 或者其他编码。agent 通过 shell 工具读取这些文件时输出很可能是乱码模型分析起来也会受影响。我的解决方案是在读取非 UTF-8 文件前先用iconv转换编码再喂给模型。我给 agent 的工具描述里明确写了“处理文件前先确认编码必要时转成 UTF-8”模型会在调用 shell 时自动加上iconv -f gbk -t utf-8。另一个相关问题是 Windows 环境下的换行符CRLF会被模型识别成奇怪的字符建议统一用sed -i s/\r$//或者让 agent 用dos2unix处理后再读取。6.3 上下文太长模型开始“健忘”这是一个缓慢恶化的问题。一开始你觉得模型分析得很准后来它频繁重复问你“这个文件是什么来着”。这通常是上下文溢出了。agent-shell 的截断策略是给你保留早期系统消息和最近的用户消息但丢掉中间的关键信息。所以核心任务是别让上下文垃圾积累及时清理、及时摘要、每一项任务独立会话。我还习惯用一个“项目速览”文件把项目的目录结构、核心模块说明、常用命令写在一个AGENT_CONTEXT.md里。开新会话时第一件事就是让它读这个文件相当于给它一本“入职手册”。这个小习惯让模型的很多“低级错误”直接消失。6.4 bash 环境不一致命令明明在手动跑没问题agent 跑就报错这里面隐藏最深的坑就是 shell 环境的差异。Emacs 里shell-command运行命令时的 PATH 和你终端登录 shell 的 PATH 可能完全不同尤其 macOS 上 Emacs 不继承 GUI 应用的环境变量。agent 执行python或node时报 command not found 很常见。查了很多资料后我的固定解决思路是在 Emacs 配置里手动同步 PATH从 shell 启动 Emacs 或使用exec-path-from-shell插件把登录 shell 的 PATH 导入。配置好之后agent 执行命令的成功率大幅提升。如果你用的是 nvm/fnm 这类 node 版本管理器这个更是必须做的——否则 agent 永远找不到npm。6.5 权限与安全问题只给 agent 该给的能力为了保证安全我总结了三个硬规矩永远不关掉写操作的确认。让 model 运行rm、mv、sed -i这类命令前必须经过我确认。工具描述里明确标注哪些命令是只读的、哪些是危险的。模型在调用“只读工具”时我会允许它自动执行但“危险工具”一定会要求用户确认。不把生产环境的密钥、线上数据库连接方式放进 Emacs 环境变量。agent 能触达的环境等同于你的 shell 权限给 agent 配一个权限受限的专用环境是最稳妥的做法。我甚至给 agent 单独建了一个低权限的 Linux 容器来跑它生成的代码避免它在宿主机上搞出不可控的问题。虽然 agent-shell 本身的机制是透明的但 LLM 的决策总是有小概率不可预测保持防护意识总没错。7. agent 工作台的“自我进化”从单命令到多 agent 协作7.1 进化第一层从“你写命令”到“你说意图”刚开始用 agent-shell你可能会不自觉地把它当成一个“能 chat 的 shell 包装器”。你想好命令让它执行它回答你。但真正的分水岭是当它开始“理解意图”后自己选工具、自己编排命令序列。第一步建立信任第二步放手让它自主调度第三步只审核结果。我给自己的一个“进化标记”是当我发现自己不再想“用什么命令实现”而是直接告诉 agent“我要知道这个接口最近被谁改过”时说明工作方式已经变了。它帮我从“命令合成者”变成了“结果评审者”注意力更集中在判断和决策上。7.2 进化第二层把常用协作流程固化为 workflowagent-shell 允许你把常用的任务模式固化成模板。我现在有一个“review-flow”模板用在每次提交代码之前1. 先 git status 和 git diff 查看变更 2. 逐文件读取变更评估是否潜在引入 bug 3. 检查是否有未更新的测试用例 4. 给出精简的 review 结论包括风险点和改进建议 5. 如果发现测试失败主动运行对应测试输出结果。这并非 agent-shell 内置功能而是我把这段文本保存成 snippet每次开新 agent 会话时粘贴一下。但效果非常稳定相当于给 agent 上了一套“行为程序”。经过一段时间迭代这个 flow 会越来越贴合你的项目特点这就是工作流的进化。7.3 进化第三层多 agent 分工会话我在处理复杂项目时会开多个会话并让它们各司其职一个“架构师 agent”负责理解全局设计、回答模块关系问题一个“编码 agent”负责具体文件修改一个“审查 agent”负责 review 编码 agent 的改动。这三个会话各自有独立上下文避免了单个会话信息过载。多 agent 之间的“协作”目前还是靠我在中间传话——把架构师 agent 的结论贴给编码 agent再把编码 agent 的产出交给审查 agent。这已经比单会话通吃一切高效很多但还有改进空间。我注意到 agent-shell 后续版本在探索 agent 间沟通协议未来很可能实现真正的 agent-to-agent 消息传递到时候作为人类的中枢协调角色会进一步减轻。7.4 进化第四层用 agent 维护 agent 本身说到“自我进化”最贴合的一点是我现在可以让一个 agent 会话来分析我配置的 agent 行为数据指出哪些工具经常被误用、哪些提示词让它产生误解然后直接修改 workflow 模板。这很像“AI 维护自己的使用手册”。举个例子有段时间我发现 agent 在做 git 操作时总是先git pull再考虑git rebase导致频繁出现冲突。我让一个专门的会话分析工具调用历史日志里都有总结规律后更新了它的系统 prompt限制对共享分支的 pull 操作优先 fetch merge 指定分支。从这以后这类问题就少多了。agent 在工作中的经验能够反向沉淀到它的知识库里这已经具备“自我进化”的雏形。我用 agent-shell 最深的体会是真正有价值的不是某一次灵光一闪的回答而是你让 agent 参与到工作流之后它慢慢“长”出来的项目经验和操作习惯。人的判断力、AI 的执行力经过 agent-shell 这个桥梁融合成了一套越来越顺的协作系统。8. 亲历者的最终建议与扩展方向8.1 给第一次使用 agent-shell 的人几个明确建议如果你准备开始折腾 agent-shell我最后的建议浓缩成这几条第一个任务不要挑战复杂的重构先用它读代码、跑测试、分析日志这类“低风险高回报”的场景建立信任感。系统 prompt 多花点心思写。与其换更强的模型不如先给现在的模型立好规矩。善用会话隔离一个任务一个会话上下文干净问题定位快速。不要把 agent 当成“不用验证结果的权威”它还是会犯错的。关键修改一定要 review diff、跑测试。注意上下文摘要沉淀。用 org 文件记录每个重要会话的结论这些结论才是长期资产。8.2 可以继续扩展的想象空间agent-shell 的价值天花板远不止“在 Emacs 里跑几条 shell 命令”。它让我看到一条清晰的路让 Agent 不只是“写代码工具”而成为“维护开发者认知负载的助手”。比如当你在一个不熟悉的模块里迷路时agent 能陪你一起读代码逐步建立心智模型当你面对大量日志时agent 能先帮你把噪音过滤掉只保留线索当你从 React 项目切换到 Rust 项目时agent 能根据语言生态自动调整工具组合和代码风格建议。更进一步agent 与 dired 的联动可以做文件管理自动化与 org-mode 的结合可以做会议纪要整理、任务自动拆解与 magit 的配合可以做自动 commit message 生成和代码审查。这些我都试过一些D 的效果不错但还远没到稳定的生产级。每个方向都正在快速迭代中值得保持关注。最后分享一个小技巧每次 agent 完成一项复杂任务后我会让它写一句“你学到了什么”总结然后追加到项目里的AGENT_NOTES.md。天长日久这本笔记成了我最独特的项目文档——它记录的不只是“代码怎么写的”还有“这个项目开发过程中踩过的坑、绕过的弯、做过的决策”。这是 agent 和人类一起沉淀下来的项目史也是我认为“AI 工作台自我进化”最有价值的果实。