Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_27_从本地开发到 PyPI发布WeClaw 的 Python 包标准化之旅系列文章第 27 篇- 从pip install weclawpy说起揭秘一个 AI 桌面智能体的 PyPI发布全流程与血泪教训 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用本系列共 30 篇分为八大模块 模块一【通讯架构设计】(3 篇)混合通讯、设备绑定、请求路由 模块二【核心技术实现】(4 篇)WebSocket 路由、心跳重连、离线队列️ 模块三【安全与治理】(3 篇)密钥管理、Token 吊销、速率限制 模块四【调试与监控】(2 篇)全链路追踪、日志分析 模块五【问题诊断实战】(3 篇)典型问题排查与修复⚙️ 模块六【性能优化】(1 篇)启动速度、内存优化 模块七【主动陪伴系统】(3 篇)决策引擎、防骚扰机制、渐进式建档️ 模块八【工具系统设计】(3 篇)意图识别、工具暴露、Schema 优化模块九【PyPI发布实战】(2 篇)打包发布、依赖管理、安装引导模块定位PyPI发布实战 · 第 1 篇共 2 篇前置知识了解 Python 基础、pip 使用经验关联文章第 26 篇意图识别、第 28 篇PyPI 安装后的依赖补充方案 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“让工具扩展像添加配置一样简单让开发者专注于业务逻辑” 摘要本文结构概览本文首先从三个真实的安装后无法启动场景出发分析 WeClaw 从本地项目到 PyPI 包的标准化改造全过程然后用飞机托运比喻讲解 hatchling 构建系统的原理接着通过 pyproject.toml 的 147 行配置详解依赖分级策略随后还原 自定义 build.py 导致打包失败的真实排查过程最后给出安装后依赖补充方案和最佳实践。背景WeClaw 作为一个拥有 64 个工具、28 个 UI 模块、10 个核心模块的复杂 AI 桌面应用如何在 PyPI 上优雅地分发用户执行pip install weclawpy后为什么经常遇到ModuleNotFoundError: No module named ‘PySide6’核心问题如何将包含敏感配置、开发文档、测试数据的复杂项目打包成干净的 PyPI 包如何平衡安装包体积与功能完整性的矛盾用户安装后如何正确补充依赖确保 GUI 启动和工具功能解决方案采用 hatchling 构建系统 可选依赖分级gui/automation/browser/voice/all .env.example 脱敏 sdist 排除规则 安装后依赖补充清单。关键成果构建产物从 150MB → 2.3MBwheel 包支持 5 种可选依赖组合按需安装100% 脱敏无 .env、无.qoder/、无 logs/提供 3 套安装方案最小化/完整版/按需定制适合读者有 Python 基础想要发布自己的 PyPI 包或遇到安装后缺依赖问题的开发者阅读时长约 25 分钟关键词PyPI发布、hatchling、可选依赖、pyproject.toml、wheel、依赖管理一、从本地运行正常到安装后无法启动1.1 场景重现三个让人抓狂的缺依赖案例想象一下这些对话场景案例 1GUI 启动失败# 用户执行pipinstallweclawpy weclaw-gui# 报错ModuleNotFoundError: No module namedPySide6用户不是说好安装就能用吗案例 2语音功能缺失# 用户说帮我录音并转写成文字# 系统报错ImportError: numpy is requiredforaudio processing 用户我要用语音功能怎么还要装 numpy案例 3浏览器自动化罢工# 代码调用fromweclaw.toolsimportbrowser# 报错ImportError:playwrightisnotinstalled 用户文档里没说还要单独装 playwright 啊问题的本质为了减小安装包体积我们将 GUI、语音、浏览器等模块设为可选依赖但用户安装时并不知道还需要额外装什么。1.2 四种打包方案对比方案像什么比喻优点缺点适用场景全量打包把所有行李都塞进箱子用户安装即用包体积巨大100MB很多依赖用户根本用不到小型工具最小核心✅只带必需品其他现场买包体积小~2MB灵活需要清晰的安装指引大型应用分多个包拆分成多个小包裹职责清晰维护成本高版本同步困难微服务架构动态下载用时再下载按需加载实现复杂网络依赖在线应用┌─────────────────────────────────────────────────────────────────────┐ │ 包体积与用户体验权衡 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 包体积10MB 50MB 100MB 150MB │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ 策略 [最小核心] [适度拆分] [全量打包] [不可接受] │ │ │ │ WeClaw 选择2.3MB wheel 可选依赖分级 │ └─────────────────────────────────────────────────────────────────────┘1.3 核心挑战既要体积小又要能运行我们的目标是设计一套方案满足轻量化wheel 包 5MB快速下载完整性用户知道如何补充依赖以启用特定功能灵活性支持最小安装、“完整安装”、按需安装多种策略安全性不包含 .env、logs/、generated/ 等敏感数据二、pyproject.toml147 行的配置艺术2.1 整体架构从项目元数据到依赖分级让我们用飞机托运来理解 pyproject.toml 的配置┌─────────────────────────────────────────────────────────────────────┐ │ pyproject.toml 配置结构 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ [build-system] # 用什么工具打包hatchling │ │ │ │ │ ▼ │ │ [project] # 基本信息名字、版本、作者 │ │ │ │ │ ├─ dependencies # 核心依赖必装 │ │ │ │ │ └─ [optional-dependencies] # 可选依赖选装 │ │ │ │ │ ├─ gui # GUI 相关 │ │ ├─ automation # 自动化相关 │ │ ├─ browser # 浏览器相关 │ │ ├─ voice # 语音相关 │ │ ├─ all # 全部打包 │ │ │ │ │ ▼ │ │ [tool.hatch.build] # 打包规则排除哪些文件 │ │ │ └─────────────────────────────────────────────────────────────────────┘2.2 核心依赖 vs 可选依赖核心依赖必须安装dependencies [ litellm1.40, # LLM 调用 openai1.30, # OpenAI SDK mss9.0, # 截图 Pillow10.0, # 图片处理 rich13.0, # 终端美化 pyyaml6.0, # YAML 解析 jinja23.1, # 模板引擎 apscheduler3.10, # 定时任务 aiosqlite0.20, # SQLite 异步支持 ]为什么这些是核心✅ 所有功能都要用到如 litellm、openai✅ 基础能力不可或缺如 Pillow 处理图片✅ 体积极小总共 10MB可选依赖按需安装[project.optional-dependencies] gui [ PySide66.7, # Qt GUI 框架~200MB qasync0.27, # asyncio Qt 集成 keyring25.0, # 密钥管理 pynput1.7, # 键盘鼠标控制 ] automation [ pyautogui0.9, # 自动化控制 pywinauto0.6, # Windows 自动化 pyperclip1.8, # 剪贴板 winotify1.1, # Windows 通知 ] browser [ playwright1.44, # 浏览器自动化~150MB ] voice [ openai-whisper20240930, # 语音识别~3GB pyttsx32.90, # TTS sounddevice0.4.6, # 音频设备 scipy1.11, # 科学计算 numpy1.24, # 数值计算 ]为什么要分开❌ PySide6 占 200MB但只用 CLI 的用户不需要❌ Whisper 占 3GB不用语音功能的用户不想装❌ playwright 占 150MB纯文件操作场景用不到2.3 依赖分级表依赖组体积用途推荐场景core~10MBLLM 调用、基础 IO所有用户必装gui~200MB图形界面需要 GUI 的用户automation~50MB自动化控制需要模拟键鼠browser~150MB浏览器自动化需要网页操作voice~3GB语音识别合成需要语音交互all~3.4GB全部功能开发者/完整体验三、hatchling 构建系统避开那些坑3.1 为什么选择 hatchling我们对比过几种构建工具工具配置方式排除规则现代程度社区采用setuptoolssetup.py复杂⭐⭐传统项目poetrypyproject.toml简单⭐⭐⭐⭐新兴项目hatchling✅pyproject.toml简单⭐⭐⭐⭐⭐FastAPI/pip 采用flitpyproject.toml简单⭐⭐⭐小型库hatchling 的优势✅ 纯声明式配置无需 setup.py✅ 排除规则直观glob 模式✅ 构建速度快✅ 被主流项目采用FastAPI、httpx3.2 排除规则保护敏感数据[tool.hatch.build.targets.sdist] exclude [ /.git, # Git 历史 /.qoder, # Qoder 配置含 API keys /weclaw_link_web, # Next.js 官网源码 /weclaw_server, # 远程服务器代码 /winclaw_server - 副本, # 备份目录 /generated, # 生成的文档可能含隐私 /logs, # 日志文件含用户数据 /docs, # 开发文档 /tests, # 测试代码 /scripts, # 运维脚本 /tools, # 开发工具 *.log, # 日志文件 __pycache__, # Python 缓存 *.pyc, # 编译字节码 .env, # 环境变量含密钥 dist, # 构建产物 build, # 临时构建目录 ]为什么排除 docs/ docs/ 包含 200 篇开发文档占用 50MB 部分文档含内部讨论记录不宜公开 用户可以通过官网查看3.3 真实案例自定义 build.py 导致的打包失败问题现象$ python-mbuild Traceback(most recent call last): File.../build/__main__.py, line70,inmodulesys.exit(build())File.../weclaw/build.py, line15,inbuild# 这是我们的自定义构建脚本不是 hatchling 的AttributeError: modulehatchling.buildhas no attributebuild根本原因项目中存在build.py自定义脚本用于旧版打包当执行python -m build时Python 会优先导入当前目录的build.py而不是标准的 build 模块。排查日志2026-03-24 09:15:32 | DEBUG | 尝试导入 build 模块 2026-03-24 09:15:32 | ERROR | 意外导入 ./build.py本地文件 2026-03-24 09:15:32 | ERROR | hatchling.build 没有 build 属性解决方案# ❌ 错误做法python-mbuild# ✅ 正确做法python-mhatchling build# 或者临时重命名 build.pymvbuild.py build_script.py python-mbuildmvbuild_script.py build.py教训总结避免在项目根目录使用标准库名作为文件名如 build.py、logging.py、test.py四、构建与验证从源码到 wheel4.1 完整构建流程# 第一步清理旧构建产物rm-rfdist/ build/# 第二步使用 hatchling 构建python-mhatchling build# 输出dist/ ├── weclawpy-2.14.1-py3-none-any.whl(2.3MB)└── weclawpy-2.14.1.tar.gz(2.1MB)# 第三步twine 检查twine check dist/*# 输出Checking weclawpy-2.14.1-py3-none-any.whl: PASSED Checking weclawpy-2.14.1.tar.gz: PASSED4.2 构建产物验证验证 wheel 包内容$unzip-ldist/weclawpy-2.14.1-py3-none-any.whl Archive: dist/weclawpy-2.14.1-py3-none-any.whl Length Date Time Name --------- ---------- ----- ----1232026-03-24 09:00 src/__init__.py56782026-03-24 09:00 src/app.py123452026-03-24 09:00 src/core/prompts.py...仅包含 src/ 目录 --------- -------234567828files验证 tar.gz 内容$tar-tzfdist/weclawpy-2.14.1.tar.gz|head-20weclawpy-2.14.1/ weclawpy-2.14.1/src/ weclawpy-2.14.1/pyproject.toml weclawpy-2.14.1/README.md# ✅ 无 .env、无.qoder/、无 logs/4.3 隐私检查清单发布前必须验证以下内容检查项验证方法期望结果无 .env 文件unzip -l dist/*.whlgrep .env无 .qoder/目录tar -tzf dist/*.tar.gzgrep .qoder无 logs/目录unzip -l dist/*.whlgrep logs无 generated/目录tar -tzf dist/*.tar.gzgrep generated无 tests/目录unzip -l dist/*.whlgrep tests五、用户视角安装后的依赖补充5.1 三种安装策略策略 1最小化安装推荐 CLI 用户pipinstallweclawpy# 仅安装核心依赖~10MB# 可用功能LLM 对话、文件操作、搜索等基础工具策略 2完整安装推荐开发者pipinstallweclawpy[all]# 安装所有可选依赖~3.4GB# 可用功能GUI、语音、浏览器、自动化等全部 64 个工具策略 3按需安装推荐生产环境# 需要 GUI 浏览器pipinstallweclawpy[gui,browser]# 需要语音功能pipinstallweclawpy[voice]# 需要办公自动化pipinstallweclawpy[gui,automation]5.2 依赖补充清单安装后必读场景 1GUI 无法启动# 报错ModuleNotFoundError: No module named PySide6# 解决pipinstallweclawpy[gui]# 或单独安装pipinstallPySide6 qasync keyring pynput场景 2语音功能缺失# 报错ImportError: numpy is required# 解决pipinstallweclawpy[voice]# 或单独安装pipinstallnumpy scipy sounddevice openai-whisper pyttsx3场景 3浏览器自动化报错# 报错ImportError: playwright is not installed# 解决pipinstallweclawpy[browser]playwrightinstall# 安装浏览器内核5.3 完整依赖分类表功能模块必需依赖可选增强命令GUI 启动PySide6, qasynckeyring, pynputpip install weclawpy[gui]语音识别numpy, scipy, sounddeviceopenai-whisperpip install weclawpy[voice]语音合成pyttsx3-包含在 [voice] 中浏览器playwright-pip install weclawpy[browser]自动化pyautogui, pywinautopyperclip, winotifypip install weclawpy[automation]OCRrapidocr-onnxruntime-pip install weclawpy[ocr]MCPmcp-pip install weclawpy[mcp]六、Do’s Don’ts6.1 推荐做法 ✅# ✅ 使用 pyproject.toml 而非 setup.py [build-system] requires [hatchling] build-backend hatchling.build # ✅ 明确定义核心依赖 dependencies [ litellm1.40, openai1.30, ] # ✅ 使用可选依赖分组 [project.optional-dependencies] gui [PySide66.7] all [weclawpy[gui,automation,browser,voice]] # ✅ 排除敏感目录 [tool.hatch.build.targets.sdist] exclude [/.env, /.qoder, /logs]# ✅ 使用 hatchling 构建python-mhatchling build# ✅ twine 验证twine check dist/*# ✅ 提供清晰的安装指引pipinstallweclawpy[gui]# GUI 用户pipinstallweclawpy[voice]# 语音用户6.2 避免做法 ❌# ❌ 在 dependencies 中包含巨型库 dependencies [ PySide66.7, # 200MB不应该在这里 openai-whisper20240930, # 3GB绝对不要 ] # ❌ 忘记排除敏感文件 exclude [ # 没有排除 .env导致 API Key 泄露 ] # ❌ 使用自定义 build.py 与标准工具冲突 # 项目根目录有 build.py导致 python -m build 失败# ❌ 使用错误的构建命令python-mbuild# 可能与自定义 build.py 冲突# ❌ 不提供安装指引pipinstallweclawpy# 用户然后呢怎么用不了七、总结与展望7.1 核心要点回顾1 个核心公式优雅的 PyPI发布 hatchling 构建 依赖分级 隐私排除 安装指引关键数字wheel 包体积150MB →2.3MB减少 98%可选依赖分组7 个gui/automation/browser/voice/ocr/mcp/all排除目录15 个.env/.qoder/logs/generated/…构建时间~30 秒三大原则最小核心只包含所有功能都需要的依赖按需扩展大体积依赖PySide6/Whisper作为可选依赖安全第一排除所有敏感配置和用户数据7.2 经验教训血泪教训 Top 3自定义 build.py 导致打包失败教训避免使用标准库名作为文件名解决改用python -m hatchling build.env 文件差点被打包教训必须在 exclude 中明确列出.env解决只提供.env.example模板用户安装后无法启动 GUI教训核心依赖不应包含 PySide6太大解决提供清晰的可选依赖安装指引7.3 后续主题下一篇《第 28 篇PyPI 安装后的依赖补充方案 — 三层指引让用户不再迷茫》 安装指引设计CLI 弹窗、README 高亮、文档链接 依赖检查脚本自动检测缺失并提示 渐进式功能启用缺依赖时优雅降级下下篇《第 29 篇从 0 到 1 发布第一个 PyPI 包》 账号注册、API Key 配置 twine upload 实战 发布数据统计与分析附录 Apyproject.toml 完整配置以下是 WeClaw v2.14.1 的完整 pyproject.toml节选关键部分[build-system] requires [hatchling] build-backend hatchling.build [project] name weclawpy version 2.14.1 description Weclaw - 轻量级跨平台 AI 桌面智能体Windows/macOS/Linux readme README.md requires-python 3.11 license { text MIT } authors [ { name Yonggang Weng, email wyg5208126.com } ] keywords [AI, desktop, agent, assistant, automation, LLM, tools] # 核心依赖9 个 dependencies [ litellm1.40, openai1.30, mss9.0, Pillow10.0, rich13.0, pyyaml6.0, jinja23.1, apscheduler3.10, aiosqlite0.20, ] # 可选依赖7 组 [project.optional-dependencies] gui [PySide66.7, qasync0.27, keyring25.0, pynput1.7] automation [pyautogui0.9, pywinauto0.6, pyperclip1.8, winotify1.1] browser [playwright1.44] voice [openai-whisper20240930, pyttsx32.90, sounddevice0.4.6, scipy1.11, numpy1.24] voice-glm [httpx0.25.0, tenacity8.2.0] voice-all [weclawpy[voice,voice-glm]] ocr [rapidocr-onnxruntime1.3] mcp [mcp1.0] dev [pytest8.0, pytest-asyncio0.23, mypy1.10, ruff0.4] all [weclawpy[gui,automation,browser,voice,ocr,mcp,dev]] # 排除规则15 类 [tool.hatch.build.targets.sdist] exclude [ /.git, /.qoder, /weclaw_link_web, /weclaw_server, /generated, /logs, /docs, /tests, /scripts, *.log, __pycache__, *.pyc, .env, dist, build, ]附录 B快速命令参考构建相关# 清理旧构建rm-rfdist/ build/# 构建 wheel 和 tar.gzpython-mhatchling build# 验证分发包twine check dist/*# 查看 wheel 内容unzip-ldist/weclawpy-*.whl# 查看 tar.gz 内容tar-tzfdist/weclawpy-*.tar.gz安装相关# 最小化安装pipinstallweclawpy# 完整安装pipinstallweclawpy[all]# 按需安装pipinstallweclawpy[gui,browser]# 开发环境安装pipinstallweclawpy[dev]# 从源码安装pipinstall-e.验证相关# 检查已安装依赖pip list|grepweclaw# 验证 GUI 启动weclaw-gui# 验证 CLI 启动weclaw--help附录 C参考资料[Hatchling 官方文档][PEP 621 - pyproject.toml 规范][Twine 使用指南]上一篇《第 26 篇意图识别与工具智能路由》下一篇《第 28 篇PyPI 安装后的依赖补充方案》版权声明本文为 WeClaw 团队原创文章遵循 CC 4.0 BY-SA 版权协议转载请附上原文出处链接及本声明。互动环节思考题如果你的项目也依赖庞大如 TensorFlow/PyTorch你会如何设计依赖分级策略如何在 CI/CD 流水线中自动化执行构建 → 验证 → 发布流程对于不小心打包了 .env 文件的情况除了从 PyPI 撤包还有哪些补救措施讨论话题你在发布 PyPI 包时遇到过哪些坑是如何解决的欢迎在评论区分享你的经验下期预告《第 28 篇PyPI 安装后的依赖补充方案》 三层指引CLI 弹窗 / README 高亮 / 文档链接 自动化检查启动时检测缺失依赖并提示 优雅降级缺依赖时禁用相关功能而非崩溃 用户行为分析统计最常见的安装组合敬请期待
