第 1 课 · 约 10 分钟
收件箱只用得上 4 个模块,启动时却加载了 33 个。这不是谁写错了,是 Python 包的一条规则决定的。学完这一课,你能自己验证这句话,也能判断一次改动会不会让收件箱起不来。
你的收件箱启动时执行的是这一句:
import digital_avatar.geweapi.inbox_service
就这一句。但加载完之后,内存里躺着 33 个模块,其中包括 vision(看图)、firecrawl(爬网页)、memory(记忆)、application(分身主逻辑)——收件箱一个都用不上。
这个数字是实测的,不是估的。你自己也能测:PYTHONPATH=src python3 -c "import sys,importlib; b=set(sys.modules); importlib.import_module('digital_avatar.geweapi.inbox_service'); print(len([m for m in set(sys.modules)-b if m.startswith('digital_avatar')]))"
导入
parent.one时,会隐式执行parent/__init__.py。— Python 语言参考 · The import system,原文:“Importing
parent.onewill implicitly executeparent/__init__.py”
「隐式」是这条规则的全部重点:你没写这行代码,Python 替你执行了。
要理解它,先分清两个词:
| 词 | 是什么 | 你项目里的例子 |
|---|---|---|
| 模块 | 一个 .py 文件 | vision.py、webhook.py |
| 包 | 一个装着 __init__.py 的目录 | geweapi/ 这个目录 |
inbox_service.py 住在 geweapi/ 这个包里面。所以要拿到它,Python 必须先把这个包打开——也就是先执行 geweapi/__init__.py。
它的第一行是:
from .deepseek_transport import DeepSeekTransport, ModelAnswerError
deepseek_transport 是调用大模型用的。收件箱根本不调模型。
但这一行在 __init__.py 里,而 __init__.py 会被隐式执行,所以它一定会跑。这个文件里一共有 16 行这样的 import,把包里 29 个模块几乎全拉了进来。
连锁就是这么发生的:
你写的: import ...geweapi.inbox_service
↓
Python 先做: 执行 geweapi/__init__.py
↓
那里面有: from .deepseek_transport import ...
from .vision import ...
from .media import ... (共 16 行)
↓
结果: 33 个模块全部加载完毕
加载一个模块,意味着执行它顶部的 import。vision.py 顶上如果写着 import pillow,那么加载它就要求这台机器上装了 pillow。
装不了?整句 import 失败,收件箱起不来,群消息全部进不去——而它根本不看图。
你在自己电脑上不会发现,因为你电脑上装了那个库。
三道题,凭理解答,答错了看解释再来。
1 · 你在 vision.py 里加了一行 import pillow,代码同步到了预发布,但那台机器上没装 pillow。重启收件箱会怎样?
收件箱启动的第一件事就是加载整个包,vision 在其中。加载 vision.py 就要执行它顶部的 import pillow,这一步找不到库就抛 ModuleNotFoundError,整个启动中断。「用到才崩」的前提是它被延迟加载了,而 __init__.py 的导入没有延迟。
2 · 假设改掉 __init__.py,让 inbox_service 直接从它真正需要的那几个模块导入,不再经过包的集中导入。改完之后?
连锁的源头就是 __init__.py 里那 16 行。断掉它,Python 就只加载真正被 import 到的那条链,vision、firecrawl 这些再也不会被牵连——它们的文件可以完全不上传到那台机器。顺带一提,加载的东西少了,启动只会更快,不会更慢。
3 · 官方文档用哪个词描述「__init__.py 被自动跑了一遍」这个行为?
原文是 “this __init__.py file is implicitly executed”。记住 implicitly(隐式)这个词很有用——以后你在报错或文档里再看到它,就知道是「你没写,但它跑了」。lazily evaluated(延迟求值)恰好是相反的行为,也正是这个问题的解法方向。
下次看到一次改动,问自己一句:这次改动有没有引入新的第三方依赖?
那条自检命令在 术语表 底部,也在你项目的 docs/agents/runtime-configuration.md 里。
Python 教程 · 6. Modules —— 比语言参考好读,十五分钟能过一遍。只读 6.4「Packages」那一节就够,前面讲的是模块基础,你已经会了。