Mesop 框架本地开发环境搭建指南Bazel/ibazel、uv、venv 与 pre-commit 全流程【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop本指南基于 docs/internal/development.md 整理面向计划在本地积极参与 Mesop 框架开发的开发者完整覆盖从 Bazel/ibazel、uv、pre-commit 环境初始化到通过./scripts/cli.sh启动带热重载的本地开发服务器再到 Python venv 与 IDE 类型检查Pylance、依赖更新、代码提交钩子以及 MkDocs 文档站本地预览的全套开发工作流。读完本文你将能够在本仓库中搭建出一套可复现、可持续迭代的 Mesop 开发环境并理解每一步背后的构建系统与源码依据。开发环境概览Mesop 是一个用 Python 快速构建 AI 应用的框架其代码库由 Python 后端、Angular 前端mesop/web/src与 protobuf 定义共同构成。因此本地开发需要同时打通三套工具链构建系统使用 Bazel通过 bazelisk 固定版本并以 ibazel 提供文件变更监听与增量重建能力Python 依赖管理使用 uv 与 Bazel 的compile_pip_requirements规则维护requirements.txt/requirements_lock.txt代码质量使用 pre-commit 在提交前统一执行格式化与 lintruff、buildifier、prettier、biome 等。官方文档建议如果你计划积极开发 Mesop最好完整阅读并执行本指南中的所有步骤。Setup初始化构建与依赖工具Bazel / ibazel仓库以 Bazel 作为构建系统构建目标定义分散在BUILD与.bzl文件中例如根目录的 BUILD.bazel、mesop/cli/BUILD、build_defs/BUILD。为保证不同开发者使用完全一致的 Bazel 版本请务必使用 bazelisk 而非直接调用bazel仓库根目录的 .bazelversion 文件内容为6.6.0bazelisk 会据此自动下载并切换到对应版本运行本地开发服务器时依赖 ibazel 做文件监听官方文档提醒如果 ibazel 出现问题而 bazel 本身工作正常可以参考 bazel-watcher 项目 issue #588 中的讨论该 issue 提供了一种修复 ibazel 监听失效的社区方案。TIP官方原文如果构建因为 npm 相关的错误神秘失败尝试执行bazel clean --expunge rm -rf node_modules。Bazel 与 Yarn 在升级 npm 模块时存在缓存 bug此命令可强制清理后重建。uvPython 依赖的解析与安装使用 uvAstral 出品的极速 Python 包管理器。请按照 uv 官方文档的 Getting Started 说明完成安装。uv 在本仓库中的主要用途是配合 Bazel 的 pip 规则生成并更新锁定文件见下文「Third-party packages (PIP)」一节。Commit hooks首次安装安装 pre-commit在仓库根目录执行pre-commit install将钩子注册到本地 git。仓库根目录的 .pre-commit-config.yaml 定义了提交钩子的完整清单本文后续「Commit hooks」一节会展开讲解各钩子职责。Run local development一键启动本地开发服务器对大多数 Mesop 框架开发场景官方推荐直接运行./scripts/cli.shNOTE官方原文该命令会自动启动serveAngular 应用。查看 scripts/cli.sh 的源码可以还原它的具体行为# Uses editor_cli which provides a faster development cycle than the regular cli target. (lsof -t -i:32123 | xargs kill) || true \ ibazel run //mesop/cli:editor_cli -- --pathmesop/mesop/example_index.py --reload_demo_modules脚本做了三件事清理端口用lsof找到占用32123端口的进程并 kill|| true保证没有进程时脚本不报错调用 editor_cli通过ibazel run //mesop/cli:editor_cli启动编辑器模式的 CLI——注释明确指出 editor_cli 相比常规clitarget 提供更快的开发循环传入启动参数--pathmesop/mesop/example_index.py指定默认启动的示例应用--reload_demo_modules开启 demo 模块热加载。其中editor_cli与cli两个 target 的定义位于 mesop/cli/BUILDcliProd CLI依赖//mesop/web/src/app/editor:web_package与//mesop/web/src/app/prod:web_package并带有ibazel_notify_changestag——该 tag 指示 ibazel 通过 stdin 向进程推送变更事件从而实现前端资源的热更新editor_cli仅打包//mesop/web/src/app/editor:web_package是开发循环更快的编辑器形态。如果希望手动拆分开前端与后端两个进程仓库还提供了 scripts/dev.sh它会并行运行 scripts/run_web_dev.sh监听 4200 端口通过MESOP_SERVER_HOSThttp://localhost:32123把 Angular dev server 指向后端与 scripts/run_py_dev.shibazel run //mesop/cli:dev_cli并在输出中为两路日志分别打上[WEB]/[PY]前缀便于区分。Python 开发环境Third-party packages (PIP)更新依赖锁定文件Python 第三方依赖的声明文件是 build_defs/requirements.txt。官方文档规定如果你修改了该文件必须运行bazel run //build_defs:pip_requirements.update该命令会重新解析requirements.txt并生成对应的锁定文件 build_defs/requirements_lock.txt。从 build_defs/BUILD 可以看到这一能力来自 rules_python 的compile_pip_requirements规则compile_pip_requirements( name pip_requirements, requirements_in :requirements.txt, requirements_txt :requirements_lock.txt, )requirements.txt按用途对依赖做了分组注释便于开发者判断某次改动会波及哪些环节核心运行时flask、absl-py、deepdiff8.6.1,9、msgpack、protobuf、pydantic、python-dotenv可选懒加载依赖sqlalchemy、flask-sock以及因架构原因在 Bazel 锁定文件机制下无法自动安装架构特定版本的greenlet开发/测试mypy-protobuf、pytest文档mkdocs-material、mkdocstrings[python]示例firebase-admin、google-genai、matplotlib、pandas以及若干由 Snyk 安全扫描固定版本下限的传递依赖werkzeug、fonttools、pillow、requests、urllib3、zipp等。venv为 IDE 类型检查Pylance建立虚拟环境为了在 VS Code 中获得 Python 类型检查Pylance支持仓库使用 Aspect 的 rules_py 生成 venv targetbazel run //mesop/cli:cli.venv然后激活虚拟环境source .cli.venv/bin/activate接着需要为 proto 生成物建立符号链接才能让 Python IDE 识别 protobuf 相关的类型提示./scripts/setup_proto_py_modules.sh该脚本的实现见 scripts/setup_proto_py_modules.sh会先通过bazel info bazel-bin定位生成目录然后为mesop/、mesop/protos/、mesop/components/及其所有子目录补建空的__init__.py使 Bazel 生成的 proto 存根可以被 Python 解释器与类型检查器正确识别为包bazel_bin_path$(bazel info bazel-bin) touch ${bazel_bin_path}/mesop/__init__.py \ touch ${bazel_bin_path}/mesop/protos/__init__.py \ touch ${bazel_bin_path}/mesop/components/__init__.py \ find ${bazel_bin_path}/mesop/components/ -type d -exec touch {}/__init__.py \;随后按官方文档的检查清单继续确认正在使用 venv 的 python执行which python应指向.cli.venv下的解释器路径把该解释器路径粘贴进 VS Code在 VS Code 中选中此 Python 解释器即可获得对源码与 proto 存根的 Pylance 类型检查安装第三方依赖pip install -r build_defs/requirements_lock.txtNOTE官方原文如果遇到权限拒绝错误尤其是_distutils_hack相关报错可能需要用sudo执行该命令。Commit hooks提交前的自动格式化与 lintMesop 使用 pre-commit 在代码提交前自动完成格式化与 lint从而保证仓库代码风格统一。Setup安装 pre-commit配置 git hookpre-commit install。仓库根目录的 .pre-commit-config.yaml 定义了完整的钩子流水线可以看到 Mesop 的工程化实践相当细致基础卫生类pre-commit/pre-commit-hooksv3.2.0trailing-whitespace清理行尾空白但排除/goldens/目录golden 文件需保持原始输出以便比对end-of-file-fixer保证文件末尾换行同样排除/snapshots/|/goldens/快照与基线文件check-added-large-files阻止提交超过 2000KB 的大文件check-case-conflict防止大小写冲突文件名跨平台文件系统友好Python 类astral-sh/ruff-pre-commitv0.5.4ruff --fix --exit-non-zero-on-fix自动修复并格式化 Python 代码ruff-format执行格式化Bazel 类wwwillchen/pre-commit-buildifier0.1.1buildifier格式化 BUILD / .bzl 文件前端类pre-commit/mirrors-prettierv3.1.0prettier统一前端与文档格式本地钩子biome-lint对.ts文件执行yarn biome lint mesop --apply-unsafe--apply-unsafe允许 Biome 应用不安全的自动修复通过language: system直接调用本机安装的 yarn 工具链。这条流水线恰好覆盖了 Mesop 代码库的四种主要文件类型Python、Bazel 构建文件、TypeScript 前端与 Markdown 文档是进入开发前值得完整了解的一部分。Docs本地预览文档站Mesop 的文档站由 Mkdocs Material。按官方文档启动本地文档预览只需两步先激活前面创建的 venv见上文「venv」一节即source .cli.venv/bin/activate且 venv 中已通过requirements_lock.txt安装了mkdocs-material与mkdocstrings[python]运行mkdocs serve即可在本机实时渲染并预览docs/目录下的全部文档包括本指南所属的 docs/internal 内部开发文档系列如 architecture.md、ci.md、hot-reload.md 等。常见问题速查现象处理方式依据npm 相关错误导致构建神秘失败bazel clean --expunge rm -rf node_modules后重新构建官方文档 TIPibazel 失效但 bazel 正常参考 bazel-watcher issue #588 的社区修复方案官方文档提示修改了build_defs/requirements.txt运行bazel run //build_defs:pip_requirements.update重新生成锁定文件build_defs/BUILDPylance 无法识别 proto 类型运行./scripts/setup_proto_py_modules.sh并在 VS Code 中选中.cli.venv解释器scripts/setup_proto_py_modules.shpip install报权限错误_distutils_hack使用sudo重试官方文档 NOTE小结Mesop 的本地开发环境以「Bazel/ibazel 驱动构建与热重载、uv 管理依赖解析、venv 支撑 IDE 类型检查、pre-commit 统一代码质量」为四条主线。无论你是想为框架新增组件可参考 docs/internal/new-component.md 与 scripts/component_template 脚手架模板还是调试运行时与热重载机制见 docs/internal/hot-reload.md先按本文完成环境搭建都是正确的第一步运行./scripts/cli.sh获得最快开发循环用mkdocs serve随时校验文档改动让 ibazel 与 pre-commit 替你处理重复性的构建与格式工作。【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mesop 框架本地开发环境搭建指南：Bazel/ibazel、uv、venv 与 pre-commit 全流程
Mesop 框架本地开发环境搭建指南Bazel/ibazel、uv、venv 与 pre-commit 全流程【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop本指南基于 docs/internal/development.md 整理面向计划在本地积极参与 Mesop 框架开发的开发者完整覆盖从 Bazel/ibazel、uv、pre-commit 环境初始化到通过./scripts/cli.sh启动带热重载的本地开发服务器再到 Python venv 与 IDE 类型检查Pylance、依赖更新、代码提交钩子以及 MkDocs 文档站本地预览的全套开发工作流。读完本文你将能够在本仓库中搭建出一套可复现、可持续迭代的 Mesop 开发环境并理解每一步背后的构建系统与源码依据。开发环境概览Mesop 是一个用 Python 快速构建 AI 应用的框架其代码库由 Python 后端、Angular 前端mesop/web/src与 protobuf 定义共同构成。因此本地开发需要同时打通三套工具链构建系统使用 Bazel通过 bazelisk 固定版本并以 ibazel 提供文件变更监听与增量重建能力Python 依赖管理使用 uv 与 Bazel 的compile_pip_requirements规则维护requirements.txt/requirements_lock.txt代码质量使用 pre-commit 在提交前统一执行格式化与 lintruff、buildifier、prettier、biome 等。官方文档建议如果你计划积极开发 Mesop最好完整阅读并执行本指南中的所有步骤。Setup初始化构建与依赖工具Bazel / ibazel仓库以 Bazel 作为构建系统构建目标定义分散在BUILD与.bzl文件中例如根目录的 BUILD.bazel、mesop/cli/BUILD、build_defs/BUILD。为保证不同开发者使用完全一致的 Bazel 版本请务必使用 bazelisk 而非直接调用bazel仓库根目录的 .bazelversion 文件内容为6.6.0bazelisk 会据此自动下载并切换到对应版本运行本地开发服务器时依赖 ibazel 做文件监听官方文档提醒如果 ibazel 出现问题而 bazel 本身工作正常可以参考 bazel-watcher 项目 issue #588 中的讨论该 issue 提供了一种修复 ibazel 监听失效的社区方案。TIP官方原文如果构建因为 npm 相关的错误神秘失败尝试执行bazel clean --expunge rm -rf node_modules。Bazel 与 Yarn 在升级 npm 模块时存在缓存 bug此命令可强制清理后重建。uvPython 依赖的解析与安装使用 uvAstral 出品的极速 Python 包管理器。请按照 uv 官方文档的 Getting Started 说明完成安装。uv 在本仓库中的主要用途是配合 Bazel 的 pip 规则生成并更新锁定文件见下文「Third-party packages (PIP)」一节。Commit hooks首次安装安装 pre-commit在仓库根目录执行pre-commit install将钩子注册到本地 git。仓库根目录的 .pre-commit-config.yaml 定义了提交钩子的完整清单本文后续「Commit hooks」一节会展开讲解各钩子职责。Run local development一键启动本地开发服务器对大多数 Mesop 框架开发场景官方推荐直接运行./scripts/cli.shNOTE官方原文该命令会自动启动serveAngular 应用。查看 scripts/cli.sh 的源码可以还原它的具体行为# Uses editor_cli which provides a faster development cycle than the regular cli target. (lsof -t -i:32123 | xargs kill) || true \ ibazel run //mesop/cli:editor_cli -- --pathmesop/mesop/example_index.py --reload_demo_modules脚本做了三件事清理端口用lsof找到占用32123端口的进程并 kill|| true保证没有进程时脚本不报错调用 editor_cli通过ibazel run //mesop/cli:editor_cli启动编辑器模式的 CLI——注释明确指出 editor_cli 相比常规clitarget 提供更快的开发循环传入启动参数--pathmesop/mesop/example_index.py指定默认启动的示例应用--reload_demo_modules开启 demo 模块热加载。其中editor_cli与cli两个 target 的定义位于 mesop/cli/BUILDcliProd CLI依赖//mesop/web/src/app/editor:web_package与//mesop/web/src/app/prod:web_package并带有ibazel_notify_changestag——该 tag 指示 ibazel 通过 stdin 向进程推送变更事件从而实现前端资源的热更新editor_cli仅打包//mesop/web/src/app/editor:web_package是开发循环更快的编辑器形态。如果希望手动拆分开前端与后端两个进程仓库还提供了 scripts/dev.sh它会并行运行 scripts/run_web_dev.sh监听 4200 端口通过MESOP_SERVER_HOSThttp://localhost:32123把 Angular dev server 指向后端与 scripts/run_py_dev.shibazel run //mesop/cli:dev_cli并在输出中为两路日志分别打上[WEB]/[PY]前缀便于区分。Python 开发环境Third-party packages (PIP)更新依赖锁定文件Python 第三方依赖的声明文件是 build_defs/requirements.txt。官方文档规定如果你修改了该文件必须运行bazel run //build_defs:pip_requirements.update该命令会重新解析requirements.txt并生成对应的锁定文件 build_defs/requirements_lock.txt。从 build_defs/BUILD 可以看到这一能力来自 rules_python 的compile_pip_requirements规则compile_pip_requirements( name pip_requirements, requirements_in :requirements.txt, requirements_txt :requirements_lock.txt, )requirements.txt按用途对依赖做了分组注释便于开发者判断某次改动会波及哪些环节核心运行时flask、absl-py、deepdiff8.6.1,9、msgpack、protobuf、pydantic、python-dotenv可选懒加载依赖sqlalchemy、flask-sock以及因架构原因在 Bazel 锁定文件机制下无法自动安装架构特定版本的greenlet开发/测试mypy-protobuf、pytest文档mkdocs-material、mkdocstrings[python]示例firebase-admin、google-genai、matplotlib、pandas以及若干由 Snyk 安全扫描固定版本下限的传递依赖werkzeug、fonttools、pillow、requests、urllib3、zipp等。venv为 IDE 类型检查Pylance建立虚拟环境为了在 VS Code 中获得 Python 类型检查Pylance支持仓库使用 Aspect 的 rules_py 生成 venv targetbazel run //mesop/cli:cli.venv然后激活虚拟环境source .cli.venv/bin/activate接着需要为 proto 生成物建立符号链接才能让 Python IDE 识别 protobuf 相关的类型提示./scripts/setup_proto_py_modules.sh该脚本的实现见 scripts/setup_proto_py_modules.sh会先通过bazel info bazel-bin定位生成目录然后为mesop/、mesop/protos/、mesop/components/及其所有子目录补建空的__init__.py使 Bazel 生成的 proto 存根可以被 Python 解释器与类型检查器正确识别为包bazel_bin_path$(bazel info bazel-bin) touch ${bazel_bin_path}/mesop/__init__.py \ touch ${bazel_bin_path}/mesop/protos/__init__.py \ touch ${bazel_bin_path}/mesop/components/__init__.py \ find ${bazel_bin_path}/mesop/components/ -type d -exec touch {}/__init__.py \;随后按官方文档的检查清单继续确认正在使用 venv 的 python执行which python应指向.cli.venv下的解释器路径把该解释器路径粘贴进 VS Code在 VS Code 中选中此 Python 解释器即可获得对源码与 proto 存根的 Pylance 类型检查安装第三方依赖pip install -r build_defs/requirements_lock.txtNOTE官方原文如果遇到权限拒绝错误尤其是_distutils_hack相关报错可能需要用sudo执行该命令。Commit hooks提交前的自动格式化与 lintMesop 使用 pre-commit 在代码提交前自动完成格式化与 lint从而保证仓库代码风格统一。Setup安装 pre-commit配置 git hookpre-commit install。仓库根目录的 .pre-commit-config.yaml 定义了完整的钩子流水线可以看到 Mesop 的工程化实践相当细致基础卫生类pre-commit/pre-commit-hooksv3.2.0trailing-whitespace清理行尾空白但排除/goldens/目录golden 文件需保持原始输出以便比对end-of-file-fixer保证文件末尾换行同样排除/snapshots/|/goldens/快照与基线文件check-added-large-files阻止提交超过 2000KB 的大文件check-case-conflict防止大小写冲突文件名跨平台文件系统友好Python 类astral-sh/ruff-pre-commitv0.5.4ruff --fix --exit-non-zero-on-fix自动修复并格式化 Python 代码ruff-format执行格式化Bazel 类wwwillchen/pre-commit-buildifier0.1.1buildifier格式化 BUILD / .bzl 文件前端类pre-commit/mirrors-prettierv3.1.0prettier统一前端与文档格式本地钩子biome-lint对.ts文件执行yarn biome lint mesop --apply-unsafe--apply-unsafe允许 Biome 应用不安全的自动修复通过language: system直接调用本机安装的 yarn 工具链。这条流水线恰好覆盖了 Mesop 代码库的四种主要文件类型Python、Bazel 构建文件、TypeScript 前端与 Markdown 文档是进入开发前值得完整了解的一部分。Docs本地预览文档站Mesop 的文档站由 Mkdocs Material。按官方文档启动本地文档预览只需两步先激活前面创建的 venv见上文「venv」一节即source .cli.venv/bin/activate且 venv 中已通过requirements_lock.txt安装了mkdocs-material与mkdocstrings[python]运行mkdocs serve即可在本机实时渲染并预览docs/目录下的全部文档包括本指南所属的 docs/internal 内部开发文档系列如 architecture.md、ci.md、hot-reload.md 等。常见问题速查现象处理方式依据npm 相关错误导致构建神秘失败bazel clean --expunge rm -rf node_modules后重新构建官方文档 TIPibazel 失效但 bazel 正常参考 bazel-watcher issue #588 的社区修复方案官方文档提示修改了build_defs/requirements.txt运行bazel run //build_defs:pip_requirements.update重新生成锁定文件build_defs/BUILDPylance 无法识别 proto 类型运行./scripts/setup_proto_py_modules.sh并在 VS Code 中选中.cli.venv解释器scripts/setup_proto_py_modules.shpip install报权限错误_distutils_hack使用sudo重试官方文档 NOTE小结Mesop 的本地开发环境以「Bazel/ibazel 驱动构建与热重载、uv 管理依赖解析、venv 支撑 IDE 类型检查、pre-commit 统一代码质量」为四条主线。无论你是想为框架新增组件可参考 docs/internal/new-component.md 与 scripts/component_template 脚手架模板还是调试运行时与热重载机制见 docs/internal/hot-reload.md先按本文完成环境搭建都是正确的第一步运行./scripts/cli.sh获得最快开发循环用mkdocs serve随时校验文档改动让 ibazel 与 pre-commit 替你处理重复性的构建与格式工作。【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考