OopenJiuwen-botdocs(jiuwenswarm): Update documents related to JiuwenSwarm

开发者指南

本文档面向 JiuwenSwarm 项目的开发者，介绍如何从源码搭建开发环境并运行测试。

环境要求

依赖项	版本要求	说明
操作系统	Windows 10/11, macOS 10.15+, Linux	支持主流操作系统
Python	≥3.11, ❤️.14	推荐 Python 3.11
Git	最新版本	用于克隆源码
Node.js	≥18.x	用于前端界面
Bun	最新版本	用于编译 TUI 前端包

1. 克隆项目

git clone <repository-url> jiuwenswarm
cd jiuwenswarm

2. 使用 `uv` 搭建开发环境

安装 `uv` 方式安装

如果尚未安装 uv，请先安装：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

创建虚拟环境

使用 uv 新建虚拟环境（支持 3.11、3.12、3.13 任一版本）：

uv venv --python=3.11

激活环境

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

执行 uv 同步操作

在项目根目录 jiuwenswarm/ 执行：

uv sync

该命令会根据 pyproject.toml 和 uv.lock 安装所有依赖，包括开发依赖（如 pytest、pytest-cov、pytest-asyncio 等）。

3. 安装 Bun（编译 TUI 前端包）

TUI 前端包需要使用 Bun 进行编译。安装方式：

# macOS、Linux 和 WSL
curl -fsSL https://bun.sh/install | bash

# Windows（通过 PowerShell）
powershell -c "irm bun.sh/install.ps1 | iex"

# 也可通过 npm 安装
npm install -g bun

安装完成后，验证：

bun --version

4. 开发

完成环境搭建后，即可开始源码及测试用例的开发。

项目结构概览

jiuwenswarm/
├── jiuwenswarm/           # 项目源码
├── tests/
│   ├── unit_tests/       # 单元测试
│   ├── system_tests/     # 系统测试
│   └── ...
├── docs/                 # 文档
├── pyproject.toml        # 项目配置与依赖声明
├── uv.lock               # 依赖锁定文件
└── pytest.ini            # pytest 配置

添加依赖

运行时依赖：uv add <package>
开发依赖（测试、lint 等工具）：uv add --dev <package>

例如：

uv add --dev pytest-cov pytest-asyncio

自验证开发流程

修改代码后，需要根据修改的内容类型进行对应的构建和验证：

后端代码修改

修改后端 Python 代码后，执行以下命令重新初始化并启动服务：

uv run jiuwenswarm-init
uv run jiuwenswarm-start

前端代码修改

修改前端代码后，需要重新构建前端资源：

npm run build

TUI 修改

修改 TUI（终端用户界面）相关代码后，运行开发模式进行调试：

npm run dev

5. 验证测试用例

重要：务必使用 uv run pytest 而非直接运行 pytest，以确保使用 uv 管理的虚拟环境中的依赖。

运行全部单元测试

uv run pytest tests/unit_tests/

运行全部系统测试

uv run pytest tests/system_tests/

运行指定测试文件

uv run pytest tests/unit_tests/agentserver/test_team_config_loader.py

常见问题排查

问题：ModuleNotFoundError: No module named 'xxx'

原因：直接运行了系统的 pytest，未使用 uv 环境。解决方案：

# 错误写法 - 使用了系统 Python
pytest tests/

# 正确写法 - 通过 uv 运行
uv run pytest tests/

问题：error: unrecognized arguments: --cov=...

原因：pytest.ini 中配置了 --cov 参数，但当前环境未安装 pytest-cov。解决方案：

uv add --dev pytest-cov pytest-asyncio

问题：测试间状态泄漏导致莫名失败

如果某个测试单独运行通过但在全量运行时失败，通常是因为某个测试文件在模块级别修改了 sys.modules 或全局状态，影响了后续测试的收集或执行。排查时可使用二分法定位：

# 单独运行通过
uv run pytest tests/unit_tests/xxx/test_foo.py

问题：如何安装 Node.js

前端开发需要 Node.js 环境。推荐通过 nvm（Node Version Manager）安装：

# 安装 nvm（macOS / Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc

# 安装并使用 Node.js 18
nvm install 18
nvm use 18

Windows 用户可使用 nvm-windows 或直接从 Node.js 官网下载安装。

安装完成后，验证版本：

node --version
# 预期输出：v18.x.x 或更高

6. 编译包

项目支持两种分发形式：Python wheel 包（.whl）和桌面可执行文件（.exe / .app）。

6.1 wheel 包构建

项目包含两个独立的 wheel 包：

包名	说明	配置文件
`jiuwenswarm`	后端服务主包（含 Web 前端构建产物）	`pyproject.toml`
`jiuwenswarm-tui`	TUI 终端界面 sidecar 包（含 Bun 编译的原生二进制）	`packages/jiuwenswarm-tui/pyproject.toml`

6.1.1 一键构建全部（推荐）

在项目根目录执行：

# macOS / Linux
bash scripts/build.sh

该脚本会依次执行：

编译 Web 前端（jiuwenswarm/channels/web/frontend 目录下执行 npm run build）
构建主包 jiuwenswarm.whl
如果检测到 bun 命令，继续构建 TUI 原生二进制和 jiuwenswarm-tui.whl

产物输出到两个目录：

./dist/jiuwenswarm-<version>-py3-none-any.whl（主包）
./packages/jiuwenswarm-tui/dist/jiuwenswarm_tui-<version>-<platform>.whl（TUI sidecar 包）

6.2 桌面版 EXE / DMG 打包

桌面版通过 PyInstaller 将 Python 应用打包为独立可执行文件。

6.2.1 前置条件

已安装 uv、Node.js
通过 uv sync --extra dev 安装开发依赖（包含 PyInstaller）

6.2.2 Windows 平台打包（EXE）

使用批处理脚本（推荐）：

scripts\build-exe.bat

使用 PowerShell 脚本：

.\scripts\build-exe.ps1

产物目录：dist\jiuwenswarm\jiuwenswarm.exe

6.2.3 macOS 平台打包（DMG）

bash scripts/build-macos.sh