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`

### 操作命令
```bash
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` 已安装

### 操作命令
```bash
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`

关键环境变量：
```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` | 后端服务主入口 |