kind: build_system name: 多语言构建与容器化发布体系（Python/Node/Electron/Docker/CI） category: build_system scope: - '**' source_files: - pyproject.toml - requirements-lock.txt - Dockerfile - docker-compose.yml - frontend/package.json - desktop/electron/package.json - .github/workflows/test.yml - .github/workflows/desktop-windows.yml - .github/workflows/wiki-deploy.yml - tools/ci_grep_gates.sh
1. 使用的系统与工具¶
- Python 包管理：基于
pyproject.toml（setuptools），通过pip install -e .安装；依赖锁定使用requirements-lock.txt，以--require-hashes强制校验。 - 前端构建：
frontend/使用 Vite + TypeScript + Tailwind，脚本为npm run build（先tsc -b再vite build），测试用 Vitest。 - 桌面端打包：
desktop/electron/使用 Electron 43 + electron-builder 26，通过npm run pack:win生成 NSIS 安装包，产物命名含版本与架构。 - 容器化：根目录
Dockerfile采用三阶段构建（frontend-build→builder→runtime），运行时镜像仅携带预编译 venv 与静态资源，不保留编译器。 - 编排：
docker-compose.yml提供vibe-trading（后端+前端静态）和可选的frontend（热重载开发服务）两个 service，并声明只读根文件系统、tmpfs、内存/CPU/PID 限制等安全加固项。 - CI/CD：GitHub Actions 定义在
.github/workflows/： test.yml：Linux 上运行 Python 3.11 单元测试、前端构建与测试、Windows 后台进程回归、Electron 桌面生命周期冒烟测试。desktop-windows.yml：在 Windows Server 2022 上构建 NSIS 安装包并输出 SHA-256 校验文件。wiki-deploy.yml：将wiki/通过 Cloudflare Wrangler 部署到 Pages。
2. 关键文件¶
| 文件 | 作用 |
|---|---|
pyproject.toml |
Python 包元数据、入口点 (vibe-trading, vibe-trading-mcp)、可选 extras、pytest/ruff/coverage 配置 |
requirements-lock.txt |
哈希锁定的 Python 依赖清单，CI 与 Docker builder 均据此安装 |
Dockerfile |
三阶段构建镜像，暴露 8899 端口，默认执行 vibe-trading serve --host 0.0.0.0 --port 8899 |
docker-compose.yml |
本地开发/部署编排，挂载 runs/sessions/uploads/home 卷，限制资源并启用 read_only 根文件系统 |
frontend/package.json |
Vite/Tailwind/Vitest 脚本与依赖 |
desktop/electron/package.json |
Electron 应用脚本、electron-builder 配置（NSIS 目标、asar、extraResources） |
.github/workflows/test.yml |
主 CI 流水线（Python + Node + Desktop smoke） |
.github/workflows/desktop-windows.yml |
Windows 桌面打包流水线 |
.github/workflows/wiki-deploy.yml |
Wiki 站点 Cloudflare Pages 部署 |
tools/ci_grep_gates.sh |
CI 代码安全门禁（grep 规则禁止 unsafe yaml.load、商标词、敏感信息泄露等） |
3. 架构与约定¶
- 分层镜像：
builder阶段安装build-essential编译 wheel 并创建/opt/venv；runtime阶段仅复制该 venv 及必要的共享库（weasyprint PDF 渲染所需 Pango/HarfBuzz/Cairo 等），体积最小化。 - 可编辑安装：
pip install -e .使运行时仍指向源码树，便于调试；同时把agent/src/**、backtest/**、cli*以及 skills/templates 等作为 package-data 打包。 - 前端资源内嵌：Docker 构建时先在
frontend-build阶段npm run build产出dist/，再复制到 runtime 镜像中，由 API server 作为静态文件提供。 - 非 root 运行：镜像创建
vibe用户与vibe-sandbox系统账户，runner.py以 sandbox 用户执行 LLM 生成的子进程；Compose 层进一步启用read_only、cap_drop: ALL、no-new-privileges。 - 版本同步：Python 包版本与前端版本均在各自
package.json/pyproject.toml中维护（当前均为0.1.13），Docker image label 也显式标注。 - 可选依赖拆分：通过
[project.optional-dependencies]按功能域（ibkr,longbridge,mt5,stats,channels,dev等）切分，基础安装保持精简，按需启用。
4. 约定与约束¶
- 依赖必须哈希锁定：CI 步骤
Verify hash-locked dependencies以--dry-run --require-hashes验证requirements-lock.txt，任何未加哈希的依赖都会导致构建失败。 - Python 版本范围受控：
requires-python = ">=3.11,<3.14"，CI 主任务固定 3.11，Windows 背景回归使用 3.14，Docker 镜像基于python:3.11-slim。 - Node 版本固定：Docker 使用
node:22-slim，CI 使用actions/setup-node@... node-version: "22"，frontend/package.json的engines.node >= 22.22.0。 - 测试路径与标记：pytest 配置
testpaths = ["agent/tests"]，区分unit与integrationmarker；CI 显式--ignore=agent/tests/e2e_backtest与test_e2e_harness_v2.py，避免误跑真实 LLM 调用。 - 覆盖率统计范围：
tool.coverage.run.source = ["agent"]，排除 tests 与__init__.py。 - Lint 规则：Ruff target py311，行宽 120，仅启用 E/F/W 规则，忽略 E501；alpha zoo 文件豁免 F401。
- 桌面端产物命名：electron-builder 输出
Vibe-Trading-Desktop-Unofficial-${version}-${arch}.${ext}，CI 会计算并写入release/SHA256SUMS.txt。 - Wiki 部署触发：仅当
wiki/**或对应 workflow 变更时触发，通过wrangler pages deploy从wiki/工作目录部署，确保 Functions 被正确编译而非当作静态文件上传。