让 CodeBuddy 从本地跑通走向生产可用

大家好,我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。

最近我在做一个图纸解析相关的项目时,又遇到一个很典型的问题。

Agent 在本地把脚本写出来了,功能也跑通了。读取图纸、提取表格、生成结果文件,看起来都没问题。

但一放到服务器环境,问题就开始冒出来:本地用的是一个 Python,服务器上调用的是另一个 Python;本地字体能正常渲染,服务器缺字体;本地依赖已经装好,生产环境版本不一致;有些命令在本地能跑,到了服务器上路径、权限、参数格式都开始报错。

这种问题很容易让人误判。

表面看,是某个库没装、某个路径写错、某个参数少了。真正往下看,核心其实是:Agent 写出来的代码没有站在一个确定的运行环境里。

代码智能体正在从“回答编程问题”,快速走向“直接完成任务”。它不只是补全一个函数,而是会读取文件、分析数据、安装依赖、编写 Python 程序、执行命令,再根据结果继续修改。

但我在实际使用中越来越强烈地感受到:

当 Agent 真正开始执行任务以后,模型能力只是上限,运行环境才是下限。

尤其是 Python。

很多 Agent 遇到临时数据处理、文件转换、接口调用、内容整理和自动化任务时,第一反应都是写一段 Python。Python 生态成熟、代码短、依赖丰富,确实适合让 Agent 快速解决问题。

问题是,一旦 Python 环境不稳定,任务很快就会变形。

它一会儿调用系统 Python,一会儿进入项目虚拟环境;缺少依赖时尝试临时安装,权限不足时又切换安装位置;本地能够执行,换一台机器却直接报错。

更麻烦的是,Agent 面对这种不确定性时,往往不会停下来重建环境,而是继续增加兜底方案。

最后,一个原本几十行就能完成的任务,可能长出三套实现、多个入口和一连串环境判断。代码看起来“考虑得很全面”,实际上已经失去了可维护性。

所以我最近开始给 CodeBuddy 明确准备一套稳定的 Python 运行环境。

我关心的不是把环境配置得多高级,而是先回答一个更基础的问题:

我们能不能让 Agent 每一次执行 Python 时,都站在同一块地板上?

一个简单任务,为什么会长出三套实现

来看一个常见场景。

假设我让 Agent 读取一批 Excel 文件,提取指定字段,合并数据后生成一份汇总结果。

这个任务本身不复杂。正常情况下,使用 pandas 和 openpyxl 很快就能完成。

但如果 Agent 不知道应该使用哪个 Python 环境,问题就开始了。

它先运行 python,发现系统里没有 pandas。于是尝试安装依赖,但当前用户没有写入权限。接下来,它可能改用用户级安装,或者寻找 python3、pip3,再检查项目里有没有虚拟环境。

如果这些尝试仍然不稳定,它还可能继续兜底:

  • 有 pandas 时使用 pandas;
  • 没有 pandas 时尝试把 Excel 转成 CSV;
  • 转换失败时再换其他库;
  • 依赖都不可用时,尝试用标准库解析文件;
  • 当前 Python 不可用时,继续搜索其他解释器。

站在 Agent 的角度,这种做法并非完全没有道理。

它拿到的目标是“完成任务”,而不是“治理环境”。当环境存在大量不确定性时,最直接的策略就是不断增加分支,提高当前任务成功的概率。

但站在工程角度,这会带来三个问题。

第一,代码复杂度被环境问题放大了。

原本应该只有一套业务实现,现在却混入大量版本检查、依赖判断和替代方案。真正的业务逻辑被埋在兜底分支里,后续很难阅读和修改。

第二,成功结果无法稳定复现。

Agent 在当前机器上碰巧找到了一套可用组合,不代表换到测试环境、云主机或者同事电脑上还能运行。

第三,错误被推迟到了交付阶段。

任务执行过程中没有彻底暴露环境问题,直到程序需要定时运行、迁移部署或者交给其他人维护时,问题才集中出现。

这个例子说明,Agent 写出多套实现,不一定是因为它喜欢过度设计。

更常见的原因是:它无法确定自己面对的执行条件,只能通过增加代码来对冲环境的不确定性。

Agent 的聪明兜底,也可能是技术债

当工程师看到依赖缺失,通常会先停下来判断:

这是环境没有初始化,还是依赖声明不完整?应该修改项目配置,还是当前机器安装错了?

Agent 的行为模式不太一样。

它更容易围绕当前目标继续推进。一个命令失败,就换另一种命令;一个库不可用,就换一个库;当前实现报错,就重新写一个替代版本。

单独看每一步都合理,但累积起来,项目里会逐渐出现:

  • 多套功能相近的实现;
  • 多种依赖安装方式;
  • 不一致的命令入口;
  • 针对不同机器的特殊判断;
  • 已经没人确定是否还需要的兼容代码。

这些代码短期内提高了“这一次跑通”的概率,却降低了长期可维护性。

这也是使用代码智能体时一个很容易被忽略的成本:

Agent 不只会放大开发速度,也会放大环境的不确定性。

如果执行条件清晰,它可以快速生成简洁方案;如果执行条件混乱,它也会更快地产生重复代码和临时补丁。

所以,限制 Agent 并不一定会降低它的能力。

有时候,越明确的边界,反而越能让它把能力集中在真正的问题上。

稳定环境,不等于机器上装了 Python

很多人说自己的 Python 环境很稳定,实际表达的是:“这台机器上可以运行 python3。”

但对 Agent 来说,这远远不够。

真正稳定的运行环境,至少要回答五个问题:

  1. 使用哪个 Python 版本?
  2. 依赖由谁声明,如何安装?
  3. Agent 通过什么入口执行程序?
  4. 任务完成后如何验证结果?
  5. Agent 可以访问哪些文件、网络和密钥?

如果这五个问题没有确定答案,Agent 每次执行任务时都要重新探索环境。

它需要判断解释器位置、检查依赖版本、尝试安装方式、寻找可写位置,还要猜测当前权限边界。模型大量的推理和执行步骤,都浪费在了本该由工程系统提前解决的问题上。

所以我理解的稳定环境,不是一台“装了很多库”的机器,而是一份明确的执行契约:

  • Python 版本固定;
  • 依赖来源唯一;
  • 执行入口统一;
  • 工作空间明确;
  • 验证方式固定;
  • 权限边界可预测。

稳定的核心不是“什么都有”,而是“不会随时变化”。

第一层约束:不要让 Agent 猜解释器

最先要解决的是 Python 入口问题。

一台开发机器上经常同时存在多个 Python:操作系统自带的 Python、用户自己安装的 Python、项目虚拟环境中的 Python、某个开发工具附带的 Python,甚至还有容器里的 Python。

人类工程师通常知道当前应该使用哪一个,但 Agent 未必知道。

如果只告诉它“运行这个 Python 程序”,它很可能从当前上下文里选择最容易找到的解释器。当前会话能运行,不代表下一次仍然会选中同一个。

因此,我更倾向于只给 Agent 一个明确入口。

例如,项目统一通过 uv run、项目任务命令或者固定的容器入口执行,而不是允许它自由组合 python、python3、pip 和 pip3。

这里的重点不在于一定要选择哪一个工具,而在于:

同一个项目只能有一条推荐执行路径。

如果团队采用虚拟环境,就让初始化、安装和执行都围绕这个虚拟环境进行;如果任务需要跨机器稳定运行,就进一步使用容器固定解释器与系统依赖。

不要一边维护虚拟环境,一边允许使用系统 Python,同时又保留用户级依赖作为兜底。

入口越多,Agent 的选择空间越大;选择空间越大,结果越难预测。

第二层约束:依赖必须可声明、可锁定

解释器固定以后,下一类问题通常来自依赖。

Agent 很擅长根据任务临时安装库,但“能安装”不等于“应该随时安装”。

如果允许它在任务执行过程中自由修改全局环境,很快会出现几个风险:

  • 今天安装的新版本破坏昨天的程序;
  • 不同任务依赖相互冲突;
  • 本地安装成功,部署环境版本不同;
  • 依赖来源不清楚,无法审计;
  • 环境越来越大,却没人知道哪些库仍在使用。

更可控的做法,是让项目明确声明依赖,并通过锁定文件记录实际版本。

当 Agent 判断需要新增第三方库时,不只是执行一次安装命令,还应该同步修改项目依赖,再运行验证。

这个变化看起来只是多了一步,实际把“当前机器上的偶然状态”变成了“项目可以复现的正式状态”。

还是前面的 Excel 处理任务。

如果 Agent 使用了 pandas 和 openpyxl,这两个依赖就应该进入项目声明。下一次换机器时,环境能够根据同一份声明恢复,而不是重新等待 Agent 发现缺什么、再临时补什么。

凡是影响任务执行结果的依赖,都不应该只存在于某次会话里。

第三层约束:把环境检查放到任务开始前

即使解释器和依赖都已经固定,也不能假设环境永远不会出问题。

依赖安装可能失败,系统库可能缺失,环境变量可能没有注入,文件权限也可能发生变化。

区别在于,我们应该让这些问题尽早暴露,而不是等 Agent 完成大量工作以后才发现程序无法执行。

我会给 Agent 准备一个轻量的启动检查,例如:

  • 当前 Python 版本是否符合要求;
  • 关键依赖能否正常导入;
  • 必要的环境变量是否存在;
  • 输入位置是否可读;
  • 输出位置是否可写;
  • 核心外部服务是否可连接。

如果是数据汇总任务,可以先跑一个几十秒内完成的冒烟验证:读取一份小样本、完成一次核心转换,再写出临时结果。

这个动作的价值,不是证明全部业务逻辑正确,而是提前确认执行地板没有塌。

如果启动检查失败,Agent 应该优先修复环境或者明确报告,而不是继续生成更多业务代码绕过问题。

一句话:

先证明环境可用,再扩大任务范围。

第四层约束:代码通过不等于任务完成

稳定运行环境还需要一个经常被忽略的部分:结果验证。

Agent 能顺利执行 Python 程序,只能说明没有立即报错,不能证明任务真的完成了。

比如,批量处理 100 个文件,程序退出状态为成功,但可能只处理了 93 个;生成数据报表,文件确实生成了,但关键字段为空;调用接口同步数据,请求返回成功,却可能写入了错误对象。

所以执行环境除了提供 Python,还要提供验证任务结果的方法。

这类验证可以很简单:

  • 预期生成几个文件;
  • 输入和输出记录数是否匹配;
  • 是否存在空值或重复数据;
  • 关键字段是否符合格式;
  • 失败项是否单独记录;
  • 程序退出状态是否能反映真实结果。

对 Agent 来说,验证标准越明确,它越不容易把“命令执行结束”误判成“任务已经完成”。

这也是 Agent 工程化和普通代码生成之间的重要区别。

代码生成关注的是实现,Agent 工程化关注的是整个执行闭环:环境准备、任务执行、结果验证、失败处理和状态记录。

Python 环境只是其中一层,却是最容易让整个闭环失真的一层。

第五层约束:稳定不能以放开权限为代价

为了让 Agent 少报错,最简单的办法似乎是给它更高权限。

安装失败就允许全局安装,文件读不到就扩大访问范围,网络请求受限就开放外网,命令执行失败就直接使用管理员权限。

这样确实容易“跑通”,但也会把环境问题变成安全问题。

Agent 生成的代码可能来自当前上下文,也可能使用刚刚安装的第三方依赖。只要它可以自由访问文件、网络和密钥,一个普通的编程错误就可能影响真实数据。

因此,稳定环境和安全边界必须一起设计。

我更倾向于让 Agent 在独立工作空间里执行,并遵循几个原则:

  • 默认使用普通用户权限;
  • 只开放任务需要的文件范围;
  • 密钥通过受控方式注入,不写进代码;
  • 对外网络访问按任务需要开放;
  • 对运行时间、内存和磁盘占用设置限制;
  • 重要数据写入前增加确认或校验。

这里存在一个现实取舍。

限制太严,Agent 会频繁因为权限不足中断;限制太松,任务虽然顺畅,风险却难以控制。

所以权限设计不能追求“一次配置解决所有任务”,而应该围绕任务分级。只读分析、内部文件生成、外部接口调用和生产数据写入,本来就不应该拥有相同权限。

稳定的含义不是 Agent 什么都能做,而是它能清楚知道自己可以做什么、不能做什么,以及越界时应该如何停止。

虚拟环境和容器,到底应该选哪个

谈到稳定 Python 环境,很容易直接走向容器。

但我的判断是,不是所有 Agent 任务都需要一开始就容器化。

如果只是个人电脑上的单项目任务,依赖简单,不涉及复杂系统组件,一个固定 Python 版本加独立虚拟环境,通常已经够用。

如果任务需要在多台机器上执行、长期定时运行,或者依赖浏览器、字体、音视频库、数据库客户端等系统组件,容器的价值就会明显提高。

可以简单这样判断:

  • 单机、低风险、短周期任务:先使用项目级虚拟环境;
  • 多人协作、需要复现的项目:增加依赖锁定和自动检查;
  • 跨机器、长期运行的任务:考虑容器化;
  • 涉及生产数据和高权限操作:增加隔离、审计与人工确认。

容器并不会自动解决所有问题。

如果镜像版本没有固定、依赖安装没有锁定、配置仍然依赖人工修改,那么只是把混乱从主机搬进了容器。

所以不要为了显得工程化而直接堆叠技术。

先把唯一入口、依赖声明和验证规则做好,再根据迁移和隔离需求决定是否使用容器,通常更务实。

我现在在实际项目里怎么做

在这个项目里,我最后没有继续让 Agent 围绕宿主机 Python 打补丁,而是把运行环境变成一个明确的交付物。

具体做法是:项目固定 Python 3.11,用 .python-version、pyproject.toml 和 uv.lock 约束版本和依赖;生产镜像基于 python:3.11-slim-bookworm,构建时通过 uv 按锁定文件安装依赖;渲染需要的 Matplotlib Agg 和中文字体也放进镜像里,不再临场去服务器上找字体、找系统库。

运行方式也做了收敛。

这个项目不是 Web 服务,不需要常驻容器。每次业务调用时,只启动一个临时容器:

1
业务程序 -> run_skill_docker.sh -> docker run --rm -> /app/run_skill.py

输入文件和输出目录通过 bind mount 挂载到容器里,任务结束后容器自动删除,结果留在服务器业务目录。

这样做以后,调用方不用再关心服务器上有没有合适的 Python、有没有装依赖、有没有中文字体。它只需要调用统一入口,传入技能 code、输入文件、参数和输出目录。

我还会把这些规则写进 AGENTS.md 或项目约束文件里,让 Agent 在动手前就知道边界。

例如在 Python 项目里,我会要求它只使用项目内 .venv,通过 uv run 执行命令;不能直接调用系统 python、python3、pip、pip3;新增依赖必须进入项目声明并更新锁定文件。到了 Docker 化阶段,再进一步约束它不要把本地 .venv、缓存、样例文件和输出目录打进镜像,只复制生产运行需要的代码、配置、字体和锁定文件。

这类约束看起来像是在限制 Agent,实际是在减少它的猜测空间。

它不用再猜“服务器到底用哪个 Python”,也不用在失败以后继续写第二套、第三套兼容实现。它只需要围绕一条路径工作:本地用同一套依赖验证,镜像用同一套锁定文件构建,服务器用同一个脚本启动容器。

这就是我现在对 Agent 工程化的一个基本判断:

不要只让 Agent 写代码,还要让它在被约束的环境里交付代码。

写到这里会发现,这件事表面上是在治理 Python 环境,本质上是在减少 Agent 执行任务时的变量。

Python 版本是变量,依赖版本是变量,工作空间是变量,权限是变量,输入格式和验收标准同样是变量。变量越多,Agent 越容易把精力花在探索和兜底上;边界越清楚,它越能把能力用在真正的业务问题上。

所以我现在评价 Agent 写的代码,不只看第一次生成得漂不漂亮,更看它能不能重复执行、换机器复现、失败后快速定位,以及人类接手时能不能看懂执行方式。

我会怎么做一个最小改造

如果你正在使用 CodeBuddy、Codex、Claude Code 或其他能够执行命令的智能体,我不建议一开始建设一套复杂平台。

可以先做三个最小动作。

1. 固定唯一执行入口

选定一个项目级 Python 入口,并明确告诉 Agent,所有 Python 任务都通过这个入口执行。

不要再让系统 Python、项目虚拟环境和用户级依赖同时承担正式任务。

2. 把依赖写进项目

检查当前程序依赖了哪些第三方库,把它们统一声明并锁定。

后续 Agent 新增依赖时,要求它同时更新项目配置,而不是只在当前机器临时安装。

3. 增加一个最小验证任务

准备一份小规模输入和明确的预期输出,让 Agent 每次修改后都先完成快速验证。

验证不仅检查程序是否报错,还要检查结果数量、关键字段和失败记录。

这三个动作并不复杂,却可以明显减少 Agent 在环境探索和重复兜底上的消耗。

等最小闭环稳定以后,再根据需要增加容器、资源限制、网络控制、日志采集和权限分级。

最后的判断

Agent 时代,很多软件工程基础并没有过时,反而变得更重要了。

过去,环境混乱主要消耗工程师的排查时间;现在,它还会诱导 Agent 不断生成补丁、分支和替代实现,以更快的速度积累技术债。

所以,为智能体提供稳定的 Python 运行环境,不只是一个开发便利问题。

它实际上是在建立一份执行契约:

什么环境可以使用,依赖如何管理,程序从哪里启动,结果怎样验证,权限边界在哪里。

这份契约越清楚,Agent 的执行越稳定;环境中的变量越少,它越有可能写出简洁、可复现、可维护的代码。

如果你今天就想开始验证,可以先检查三个问题:

  1. 你的 Agent 当前到底在调用哪个 Python?
  2. 换一台机器,能不能根据项目配置恢复同样的依赖?
  3. 程序没有报错以后,有没有办法证明任务真的完成了?

如果其中任何一个问题无法明确回答,就先别急着让 Agent 承担更长、更复杂的任务。

先把它脚下的地板铺平。

我是 WeiWill,深耕软件工程一线,专注 AI 应用落地与 Agent 开发。