OpenMesh/打包流程说明.md

OpenMesh 打包流程说明

概述

OpenMesh 是一个基于 Python (FastAPI) + React (Vite) 的 AI 智能助手平台，最终交付形态为 Windows 绿色免安装版。打包产物位于 dist/openmesh/ 目录，用户双击 启动 OpenMesh.bat 即可运行。

---

打包产物目录结构

dist/openmesh/
├── openmesh-server.exe      # 后端服务主程序（PyInstaller one-dir 模式）
├── openmesh-static.exe      # 前端静态文件服务器
├── _internal/               # PyInstaller 运行时依赖（Python 解释器 + 所有库）
├── frontend/                # 前端构建产物（React + Vite）
│   ├── index.html
│   └── assets/
├── data/                    # 用户数据目录（首次启动后生成配置）
│   ├── config.toml
│   ├── coworker.db
│   ├── chat.db
│   └── skills/              # 已安装的 skills（从 skills/ 初始化复制）
├── skills/                  # 预置内置 skills（首次启动复制到 data/skills）
├── workspace/               # 默认工作目录
├── tools/                   # 第三方命令行工具（pandoc, tesseract, libreoffice）
├── .venv/                   # Python 虚拟环境（用于 skill 脚本执行）
├── 启动 OpenMesh.bat        # 一键启动脚本
├── 卸载 OpenMesh.bat        # 卸载脚本
└── 使用说明.txt             # 使用说明

---

打包步骤总览

完整打包分为 4 个阶段，顺序执行：

阶段1: 前端构建 → 阶段2: 后端 PyInstaller 打包 → 阶段3: 静态服务器打包 → 阶段4: 组装发布包

---

阶段 1：前端构建

目的

将 React + Vite 前端项目编译为静态 HTML/CSS/JS 资源。

前置条件

• Node.js >= 16
• 已执行 npm install

操作命令

cd surfaces/gui
npm run build

输入

• surfaces/gui/src/ — 前端源码
• surfaces/gui/index.html — HTML 模板

输出

• surfaces/gui/dist/ — 构建产物
  • index.html
  • assets/index-*.js
  • assets/index-*.css
  • 其他静态资源（字体、图片等）

配置文件

• surfaces/gui/vite.config.ts — Vite 配置
  • base: "./" — 相对路径，支持从文件系统直接加载
  • 构建输出到 dist/

---

阶段 2：后端服务 PyInstaller 打包

目的

将 Python 后端服务（FastAPI + uvicorn）打包为独立的 Windows 可执行程序及运行时目录。

前置条件

• Python 3.10+
• 虚拟环境已安装所有依赖：pip install -e .
• pyinstaller 已安装

操作命令

pyinstaller dist/openworker-server.spec

Spec 文件说明

路径：dist/openworker-server.spec

关键配置：

• 入口：packaging/server_entry.py → 调用 coworker.server.run:main
• 模式：one-dir（exe + _internal/ 目录），比 onefile 启动快 6-7 秒
• 控制台：console=True（uvicorn 需要 stdout，窗口通过 CREATE_NO_WINDOW 隐藏）
• 收集的包：coworker, aisuite, mcp, ddgs, uvicorn, certifi, websockets, pypdf, pypdfium2, boto3, botocore 等
• 排除：tkinter, matplotlib, PIL, PyQt5 等不需要的库

输出

• dist/openmesh-server/
  • openmesh-server.exe — 主程序
  • _internal/ — Python 运行时 + 所有依赖库

---

阶段 3：静态文件服务器打包

目的

打包一个极简的 HTTP 服务器，用于托管前端静态文件。

Spec 文件

路径：openmesh-static.spec 或 static-server.spec

入口：packaging/static_server.py

输出：dist/openmesh-static.exe 或 dist/static-server/static-server.exe

---

阶段 4：组装发布包

目的

将前端、后端、工具、配置等所有组件组装到 dist/openmesh/ 目录，形成最终可交付的绿色版。

组装清单

源位置	目标位置	说明
dist/openmesh-server/openmesh-server.exe	dist/openmesh/openmesh-server.exe	后端服务
dist/openmesh-server/_internal/	dist/openmesh/_internal/	Python 运行时
surfaces/gui/dist/	dist/openmesh/frontend/	前端构建产物
dist/openmesh-static.exe	dist/openmesh/openmesh-static.exe	静态文件服务器
skills/ (项目内置)	dist/openmesh/skills/	预置 skills
tools/ (pandoc 等)	dist/openmesh/tools/	第三方工具
dist/config.template.toml	dist/openmesh/data/config.toml	默认配置
—	dist/openmesh/workspace/	工作目录（空）
—	dist/openmesh/data/	数据目录（空）
启动 OpenMesh.bat	dist/openmesh/启动 OpenMesh.bat	启动脚本
卸载 OpenMesh.bat	dist/openmesh/卸载 OpenMesh.bat	卸载脚本
使用说明.txt	dist/openmesh/使用说明.txt	使用说明

启动脚本逻辑

文件：dist/openmesh/启动 OpenMesh.bat

关键环境变量：

set DATA_DIR=%SCRIPT_DIR%data        :: COWORKER_STATE_DIR 指向 data 目录
set SKILLS_DIR=%DATA_DIR%\skills    :: 实际 skills 目录
set BUILTIN_SKILLS=%SCRIPT_DIR%skills :: 内置 skills 源
set COWORKER_DISABLE_AUTH=1         :: 禁用认证（本地使用）
set COWORKER_STATE_DIR=%DATA_DIR%   :: 状态目录
set COWORKER_SCRATCH_BASE=workspace :: 临时文件基准目录

启动顺序：

1. 创建 data、skills、workspace 目录
2. 首次启动时，将内置 skills 复制到 data/skills
3. 启动 openmesh-server.exe --port 8765 --cwd workspace（后端，端口 8765）
4. 启动 openmesh-static.exe frontend（前端静态服务器，端口 3000）
5. 打开浏览器访问 http://localhost:3000

---

重新打包操作清单

当代码修改后需要重新打包时，按以下顺序执行：

仅前端修改

npm run build → 复制到 dist/openmesh/frontend/

仅后端修改

pyinstaller dist/openworker-server.spec → 复制 exe 和 _internal/ 到 dist/openmesh/

前后端都修改

1. cd surfaces/gui && npm run build
2. pyinstaller dist/openworker-server.spec
3. 组装到 dist/openmesh/

---

注意事项

1. data/skills 与 skills/：内置 skills 仅首次启动时复制。修改内置 skills 后，需删除用户 data/skills/ 目录才能生效，或手动更新。

2. PyInstaller 增量构建：build 目录会缓存，重复构建时速度较快。完全干净构建可删除 build/ 目录。

3. .venv 目录：发布包中的 .venv 用于 skill 脚本执行（如 Python 脚本），与 PyInstaller 打包的运行时是两套独立环境。

4. 端口冲突：默认后端 8765，前端 3000。可在 data/config.toml 中修改。

5. UPX 压缩：server 端默认关闭 UPX（upx=False），避免某些库加载失败。static 端开启了 UPX。

---

相关文件索引

文件	作用
pyproject.toml	Python 项目配置、依赖、入口点
dist/openworker-server.spec	后端 PyInstaller 配置
openmesh-static.spec	静态服务器 PyInstaller 配置
dist/server_entry.py	后端打包入口
surfaces/gui/vite.config.ts	前端构建配置
surfaces/gui/package.json	前端依赖和脚本
dist/openmesh/启动 OpenMesh.bat	启动脚本
coworker/server/run.py	后端服务主入口