浅谈JiuwenSwarm安装

一、安装方式

重要提醒： 安装完成并不代表直接可用，需要先完成模型配置。请参考配置信息进行模型配置

方式一：桌面安装包（dmg / exe）

适用于 Windows 和 macOS 用户，希望开箱即用、不想自行配置 Python / Node.js 环境。从 gitcode Release 下载对应平台的安装包即可。从 Release 页面下载。

平台	下载产物
Windows	`JiuwenSwarm-setup-<version>.exe`
macOS	`JiuwenSwarm-<version>.dmg`

下载地址：https://gitcode.com/openJiuwen/jiuwenswarm/releases

1. macOS：用 curl 下载 dmg（推荐）

⚠️ 重要：从浏览器下载的 .dmg 会被 macOS 打上隔离标签（com.apple.quarantine），打开时触发 GateKeeper 检查，可能提示「已损坏，无法打开」或「无法验证开发者」。改用终端 curl 下载，文件不会带隔离标签，可正常挂载安装。

bash 复制代码

# 把 <version> 替换为目标版本号
curl -L --fail -o JiuwenSwarm-<version>.dmg \
  https://gitcode.com/openJiuwen/jiuwenswarm/releases/download/JiuwenSwarm<version>/JiuwenSwarm-<version>.dmg

2. 安装与首次启动

macOS ：双击挂载 dmg，将 JiuwenSwarm.app 拖入 Applications。如果 macOS 阻止首次启动，请在 Finder 中右键选择「打开」。
Windows ：双击下载的安装包（.exe）按提示安装，安装时会自动初始化工作区。如果使用便携式 onedir 版本，需要手动运行一次 jiuwenswarm.exe init。

首次启动后，系统会创建配置目录 ~/.jiuwenswarm/。

方式二：pip 安装

环境检查

桌面安装包已包含运行所需的 Python 运行时和前端静态资源，无需执行本节检查。本节仅适用于 pip 安装和源码安装；二者均支持 Windows 10/11、macOS 10.15+ 和 Linux。

依赖项	版本要求	适用方式	说明
Python	≥3.11,	pip 安装、源码安装	推荐使用 Python 3.11
Node.js	18.x 或更高版本	仅源码安装	用于构建 Web 前端；pip 包已包含前端静态资源
Git	最新版本	仅源码安装	用于克隆和更新源码

在终端中运行以下命令检查对应环境：

bash 复制代码

# pip 安装和源码安装：检查 Python 版本
python --version
# 预期输出：Python 3.11.x、3.12.x 或 3.13.x

# 仅源码安装：检查 Node.js 版本
node --version
# 预期输出：v18.x.x 或更高

# 仅源码安装：检查 Git 版本
git --version
# 预期输出：git version 2.x.x

1. 安装步骤

bash 复制代码

# 创建虚拟环境（推荐）
python -m venv jiuwenswarm-env

# 激活虚拟环境
# Windows:
jiuwenswarm-env\Scripts\activate
# macOS/Linux:
source jiuwenswarm-env/bin/activate

# 安装 JiuwenSwarm
## 方式一：默认安装
pip install jiuwenswarm

## 方式二：使用国内镜像源（推荐）
# 清华源
pip install jiuwenswarm -i https://pypi.tuna.tsinghua.edu.cn/simple

# 阿里源
pip install jiuwenswarm -i https://mirrors.aliyun.com/pypi/simple/

2. 首次启动

bash 复制代码

# 初始化 JiuwenSwarm（首次启动）
jiuwenswarm-init

# 启动 JiuwenSwarm
jiuwenswarm-start

首次启动后，系统会自动创建配置目录 ~/.jiuwenswarm/。

3. 启动后验证

启动成功后，请按以下步骤验证安装是否正确：

打开 Web 端 ：在浏览器中访问 http://localhost:5173
进入配置页面：点击左侧导航栏「配置信息」
完成模型配置 ：参考配置信息完成模型 API 配置
验证安装成功 ：
- Web 页面可正常访问
- 完成模型配置后可进行一次基础对话（根据配置可能会使用工具/MCP）

💡 提示：如果 Web 页面无法访问，请检查日志文件 ~/.jiuwenswarm/logs/ 是否有错误信息。

4. 重新启动服务

如果关闭 JiuwenSwarm 后需要再次使用：

bash 复制代码

# 再次启动
jiuwenswarm-start

卸载

卸载jiuwenclaw的命令：

bash 复制代码

pip uninstall jiuwenclaw

方式三：源码安装（uv 方式）

1. 环境准备

请先完成环境检查中源码安装所需的 Python、Node.js 和 Git 检查。

确保已安装 uv。如未安装，请参考 uv 官方文档自行安装。

复制代码

# 检查 uv 是否已安装
uv --version

# 预期输出：uv 0.x.x

2. 克隆并安装

复制代码

# 克隆代码仓库
git clone https://gitcode.com/openJiuwen/jiuwenswarm.git

# 进入项目目录
cd jiuwenswarm

# 使用 uv 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

3. 构建前端

⚠️ 重要：源码安装（editable install）需要手动构建前端，否则启动时会报错 dist directory not found。构建产物位于源码目录的 jiuwenswarm/channels/web/frontend/dist，运行时会直接读取该目录，无需复制到 ~/.jiuwenswarm/。以下正斜杠路径可在 Windows PowerShell/CMD 和 macOS/Linux shell 中直接使用。

复制代码

# Windows / macOS / Linux：从项目根目录进入前端目录
cd jiuwenswarm/channels/web/frontend

# 安装前端依赖
npm install

# 构建前端
npm run build

# 返回项目根目录
cd ../../../..

说明：

uv pip install -e . 是 editable install，直接指向源码目录
源码中的 frontend/dist 被 .gitignore 忽略，仓库不包含构建产物
jiuwenswarm/channels/web/app_web.py 会直接读取源码树中的 frontend/dist

4. 首次启动

复制代码

# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# 初始化 JiuwenSwarm（首次启动）
jiuwenswarm-init
# 启动
jiuwenswarm-start

5. 启动后验证

验证步骤见启动后验证。

6. 重新启动服务

复制代码

# 激活虚拟环境后启动
jiuwenswarm-start

方式四：源码安装（conda 方式）

1. 环境准备

请先完成环境检查中源码安装所需的 Python、Node.js 和 Git 检查。

确保已安装 conda。如未安装，请参考 Miniconda 官方文档自行安装。

复制代码

# 检查 conda 是否已安装
conda --version
# 预期输出：conda 23.x.x 或更高

2. 创建 conda 环境

复制代码

# 创建虚拟环境
conda create -n jiuwenswarm python=3.11

# 初始化环境（首次）
conda init
# 初始化之后，关闭窗口。再重新打开会话执行激活命令

# 激活环境
conda activate jiuwenswarm

3. 克隆并安装

复制代码

# 克隆代码仓库
git clone https://gitcode.com/openJiuwen/jiuwenswarm.git

# 进入项目目录
cd jiuwenswarm

# 安装依赖
pip install -e .

4. 构建前端

⚠️ 重要：源码安装（editable install）需要手动构建前端，否则启动时会报错 dist directory not found。构建产物位于源码目录的 jiuwenswarm/channels/web/frontend/dist，运行时会直接读取该目录，无需复制到 ~/.jiuwenswarm/。以下正斜杠路径可在 Windows PowerShell/CMD 和 macOS/Linux shell 中直接使用。

复制代码

# Windows / macOS / Linux：从项目根目录进入前端目录
cd jiuwenswarm/channels/web/frontend

# 安装前端依赖
npm install

# 构建前端
npm run build

# 返回项目根目录
cd ../../../..

说明：

pip install -e . 是 editable install，直接指向源码目录
源码中的 frontend/dist 被 .gitignore 忽略，仓库不包含构建产物
jiuwenswarm/channels/web/app_web.py 会直接读取源码树中的 frontend/dist

5. 首次启动

复制代码

# 初始化 JiuwenSwarm（首次启动）
jiuwenswarm-init
# 启动
jiuwenswarm-start

6. 启动后验证

验证步骤见启动后验证。

7. 重新启动服务

复制代码

# 激活环境后启动
conda activate jiuwenswarm
jiuwenswarm-start

二、版本升级

当前版本范围	升级方式	说明
常规版本（如0.1.8 → 0.1.9，不跨0.1.7版本）	常规版本升级	直接升级，无需备份
重大版本（如<0.1.7 → >0.1.7，跨0.1.7版本）	重大版本升级	需要先备份数据

常规版本升级

pip 安装升级

复制代码

# 激活虚拟环境
# 然后执行升级
pip install --upgrade jiuwenswarm

源码安装升级

复制代码

# 进入项目目录
cd jiuwenswarm

# 拉取最新代码
git pull

# 重新安装
pip install -e