环境配置：Python 版本、虚拟环境与依赖冲突排查

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

AgentScope 2.0 环境配置：版本、虚拟环境与依赖冲突排查

这篇讲的是装不上、装错了、装完互相打架这三件事。

不是"怎么装 AgentScope"，是"装完之后你怎么确认自己装对了"。三个坑串成一条因果链，最后给一个可以离线跑、不需要真装包的判定脚本。

一、环境与运行

• Python 3.8+（本文实跑用 3.13.12）
• 演示脚本纯标准库零依赖，不需要真装任何框架、不需要真建 venv
• 系统：Windows / WSL / Linux / macOS 均可

"会不会打架"这件事，用版本区间求交集就能判定，不需要先装一遍看红字。

这也是本文和多数「环境配置教程」的区别：它们在教你怎么装，这篇在教你怎么判断该不该装在一起。前者靠手速和运气，后者靠一次可复算的计算。

二、第一步不是装，是读

遇到环境问题，第一条命令不该是 pip install –force-reinstall。

先读三个东西：

which python # 我在哪个解释器（Windows: where python）
pip -V # pip 会装到哪
pip check # 装完之后有没有互相矛盾

三条都不改状态，只回答"现在是什么"。用 Python 拿同样的信息：

import sys

def env_report():
sp = next((p for p in sys.path if p.lower().endswith("site-packages")), "N/A")
in_venv = sys.prefix != getattr(sys, "base_prefix", sys.prefix)
return {"python": sys.executable, "prefix": sys.prefix,
"site_packages": sp, "in_venv": in_venv}

在 Windows 本地（不在 venv）实跑：

— 1. 我现在在哪 —
解释器 : F:\\data\\CodeBuddy\\config\\binaries\\python\\versions\\3.13.12\\python.exe
sys.prefix : F:\\data\\CodeBuddy\\config\\binaries\\python\\versions\\3.13.12
site-packages : F:\\data\\CodeBuddy\\config\\binaries\\python\\versions\\3.13.12\\Lib\\site-packages
在 venv 中 : 否 ⚠️（装包会进全局）

sys.prefix != sys.base_prefix 是判断"在不在 venv"最稳的一行，比看提示符前面的括号可靠——提示符可以改，sys.prefix 改不了。

三、坑 1：建了文件夹，包全进了全局

现象

mkdir venv_x
cd venv_x
pip install agentscope

打出十几行 Successfully installed …，一切正常。过几天打开 venv_x 一看：空的。

根因

pip install 只装进"当前激活的解释器"的 site-packages，跟你 cd 到哪个目录完全无关。文件夹只是文件夹。

缺的那一步是 python3 -m venv：它会在目录里生成 bin/（Windows 是 Scripts/）、lib/、pyvenv.cfg，把这堆东西建出来，目录才变成真环境。

修法

python3 -m venv venv_x # ① 建环境（不是 mkdir）
source venv_x/bin/activate # ② 激活，提示符前出现 (venv_x)
pip install agentscope # ③ 这时才装进 venv_x
which python # ④ 验证：应指向 venv_x/bin/python
deactivate # 用完退出

验证标准：ls venv_x/ 能看到 bin/（或 Scripts/）、lib/、pyvenv.cfg；pip -V 的路径在这个目录下。

为什么它是三个坑里最阴的

它全程不报错。 你看到的是成功，看不到的是"这些包全进了全局"。

而这就是坑 2、坑 3 的温床：所有框架挤在同一个全局 Python 里。

为什么 Successfully installed 会骗人

那行提示是 pip 打的，它汇报的对象是**“这次安装操作”**，不是"你的环境状态"。

拆开看它到底保证了三件事：

它不保证：写进的是你想要的那个 site-packages。

所以"装成功但装错地方"不是 pip 的 bug，是它的汇报口径本来就只到这一步。要确认装到哪，只能自己读 sys.prefix。

四、坑 2：两个框架抢一个依赖

装 CrewAI 之后，安装末尾出现：

openai-agents 0.22.0 requires openai<4,>=3.0.0, but you have openai 2.54.0
which is incompatible.

依赖区间是互斥的：

• CrewAI：openai >= 2.30.0, < 3.0.0
• openai-agents：openai >= 3.0.0, < 4.0.0

不存在任何一个 openai 版本能同时满足。 pip 的 resolver 只能二选一：谁后装，版本往谁那边拉，另一个标红。

但它还能跑

这一点最容易误判。openai-agents 的 Runner / handoffs / swarm 基础路径走自定义 AsyncOpenAI 桥接（OpenAIChatCompletionsModel），不依赖 openai 3.x 专有 API。

metadata 级冲突 ≠ runtime 硬崩。

修法：分家

python3 -m venv venv_crewai
source venv_crewai/bin/activate
pip install crewai redis
deactivate

主 venv 保留 openai>=3 阵营，venv_crewai 单独跑 crewai 相关脚本。

五、坑 3：第二条冲突轴

装 AutoGen：

pip install -U "autogen-agentchat" "autogen-ext[openai]"

装成功了，但 pip 把 protobuf 6.33.6 卸掉、装了 5.29.6，末尾一行红：

googleapis-common-protos 1.75.1 requires protobuf<8.0.0,>=6.33.5,
but you have protobuf 5.29.6 which is incompatible.

这次 openai 没打架。 AutoGen 只要 openai>=1.93，主环境的 2.54.0 满足。

打架的是 protobuf：autogen-core 0.7.5 要 ~=5.29.3（>=5.29.3, <5.30.0），Google 系要 >=6.33.5。又是一对空交集。

这条轴更隐蔽

平时只走 DeepSeek / 百炼这类 OpenAI 兼容接口，从不 import google.genai，所以脚本照跑。等哪天要跑 Gemini，import 那一刻才报 Descriptor 版本不匹配。

六、把"会不会打架"变成一次计算

上面两个坑的判定，本质是同一件事：沿某条轴求区间交集，空则不能同居。

def v(s):
"""'2.30.0' -> (2, 30, 0)"""
return tuple(int(x) for x in s.split("."))

def can_coexist(*ranges):
"""ranges: [(名字, lo, hi)]，hi=None 表示无上界。返回 (能否同居, 交集)。"""
lo = max(v(r[1]) for r in ranges)
his = [v(r[2]) for r in ranges if r[2] is not None]
hi = min(his) if his else None
if hi is None or lo < hi:
return True, (lo, hi)
return False, None

三个用例实跑（含一个反例）：

— 2. 能不能同居：沿轴求交集 —
openai 轴
crewai[2.30.0,3.0.0) ∩ openai-agents[3.0.0,4.0.0)
→ ❌ 空交集，必须分家
openai 轴（反例）
crewai[2.30.0,3.0.0) ∩ 某宽松库[1.0.0,∞)
→ ✅ 可同居，交集 [2.30.0, 3.0.0)
protobuf 轴
autogen-core[5.29.3,5.30.0) ∩ google 系[6.33.5,8.0.0)
→ ❌ 空交集，必须分家

那个反例是我故意加的。 它证明"不同框架不一定冲突"——只要交集非空就能同居。

这条很重要，因为它挡住了另一个极端：踩过坑之后变成"一个框架一个 venv"。每个 venv 是几百兆的依赖副本，你很快会记不清哪个 venv 里有什么。

规则是按"依赖兼容族"分家，不是按框架分。

七、pip check 的红字，按轴归类

pip check 会给你一屏红字，但它不告诉你"这是几个问题"。

我加了一个按轴归类的函数：

AXES = ("protobuf", "openai", "pydantic", "httpx", "numpy")

def classify_axis(line):
low = line.lower()
for ax in AXES:
if ax in low:
return ax
return "未识别"

两条真实红字喂进去：

— 3. pip check 红字按轴归类 —
[openai ] openai-agents 0.22.0 has requirement openai<4,>=3.0.0, but…
[protobuf ] googleapis-common-protos 1.75.1 has requirement protobuf<8…

两条红字、两条轴、两个互不相干的冲突。如果只看到"一屏红字"就以为是一个问题，你会用同一个办法去治两种病。

八、分家决策：三步

装新框架前后，我现在固定跑三步：

第三步的细节：不要先卸旧的再装新的。卸了如果还不行，你连"原来能不能跑"都回不去了。先建新 venv 验证，确认新框架能跑，再决定旧环境怎么处理。

九、多环境怎么协同

分家之后马上会遇到下一个问题：两个 venv 里的东西怎么一起用？

一个 venv 里装的包，在另一个 venv 里 import 不到——这是设计如此，不是缺陷。所以"把 crewai 挪出去"之后，原来那个脚本如果同时用到两边，就会断。

三种接法，按成本排：

最不该做的是"想办法同时 import 两个 venv"——改 sys.path、装两遍、软链接 site-packages，这些都试过，最后都是更乱。

原则：venv 之间通过"进程边界"通信，不通过"路径技巧"通信。

Windows / WSL 两个细节

• 路径不同：venv/bin/python（Linux/macOS）vs venv\\Scripts\\python.exe（Windows）
• 激活命令不同：source venv/bin/activate vs venv\\Scripts\\activate

判断"在不在 venv"别依赖提示符括号，两个平台都用这一行最稳：

import sys
print(sys.prefix != sys.base_prefix) # True = 在 venv 里

十、常见报错速查

最后一行值得单独说：pip -V 和 which python 指向不同地方，是"装了却 import 不到"最常见的原因。 用 conda / pyenv / 系统 Python 混着来的时候尤其容易。

十一、两个边界

边界一：pip check 红 ≠ 跑不了。

坑 2、坑 3 都是 metadata 级冲突，实际代码路径没踩到，脚本照跑。处理方式是"知道它在，别走那条路"，不是"立刻大修"。

边界二：这套判定依赖依赖声明是准的。

如果某个包把版本约束写错（声明 >=1.0 实际只支持 >=2.0），区间交集会骗你。这时候只能靠实测。声明是地图，实测是地面，地图错了以地面为准。

十二、一句话总结

三个坑一条链：把文件夹当环境 → 全挤进全局 → 装一个降级一个。

治本不是"多建几个文件夹"，是两件事：

而这两件事的共同点是——它们都在"装"之前或之后，唯独不在"重装"里。