\# 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\`        | 后端服务主入口              |