JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.
Developer Guide
This document is intended for developers of the JiuwenSwarm project, covering how to set up a development environment from source and run tests.
Prerequisites
| Dependency | Version Requirement | Description |
|---|---|---|
| Operating System | Windows 10/11, macOS 10.15+, Linux | Mainstream OS supported |
| Python | ≥3.11, <3.14 | Python 3.11 recommended |
| Git | Latest | For cloning the repository |
| Node.js | ≥18.x | For frontend interface |
| Bun | Latest | For building TUI frontend packages |
1. Clone the Repository
git clone <repository-url> jiuwenswarm
cd jiuwenswarm
2. Set Up Development Environment with uv
Install uv
If you haven't installed uv yet, install it first:
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Create a Virtual Environment
Use uv to create a new virtual environment (supports Python 3.11, 3.12, or 3.13):
uv venv --python=3.11
Activate the Environment
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
Run uv Sync
Run the following command in the project root directory jiuwenswarm/:
uv sync
This command installs all dependencies based on pyproject.toml and uv.lock, including development dependencies (such as pytest, pytest-cov, pytest-asyncio, etc.).
3. Install Bun (For Building TUI Frontend Packages)
The TUI frontend packages require Bun for compilation. Installation methods:
# macOS, Linux, and WSL
curl -fsSL https://bun.sh/install | bash
# Windows (via PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
# Or install via npm
npm install -g bun
After installation, verify:
bun --version
4. Development
Once the environment is set up, you can start developing the source code and test cases.
Project Structure Overview
jiuwenswarm/
├── jiuwenswarm/ # Project source code
├── tests/
│ ├── unit_tests/ # Unit tests
│ ├── system_tests/ # System tests
│ └── ...
├── docs/ # Documentation
├── pyproject.toml # Project configuration and dependency declarations
├── uv.lock # Dependency lock file
└── pytest.ini # pytest configuration
Adding Dependencies
- Runtime dependencies:
uv add <package> - Development dependencies (testing, linting, etc.):
uv add --dev <package>
For example:
uv add --dev pytest-cov pytest-asyncio
Self-Verification Development Workflow
After modifying code, you need to build and verify according to the type of changes made:
Backend Code Changes
After modifying backend Python code, run the following commands to reinitialize and start the service:
uv run jiuwenswarm-init
uv run jiuwenswarm-start
Frontend Code Changes
After modifying frontend code, rebuild the frontend assets:
npm run build
TUI Changes
After modifying TUI (Terminal User Interface) related code, run the development mode for debugging:
npm run dev
5. Running Tests
Important: Always use
uv run pytestinstead of runningpytestdirectly to ensure that dependencies from theuv-managed virtual environment are used.
Run All Unit Tests
uv run pytest tests/unit_tests/
Run All System Tests
uv run pytest tests/system_tests/
Run a Specific Test File
uv run pytest tests/unit_tests/agentserver/test_team_config_loader.py
Troubleshooting
Issue: ModuleNotFoundError: No module named 'xxx'
Cause: The system pytest was run directly without using the uv environment. Solution:
# Wrong - uses system Python
pytest tests/
# Correct - runs through uv
uv run pytest tests/
Issue: error: unrecognized arguments: --cov=...
Cause: pytest.ini is configured with the --cov parameter, but pytest-cov is not installed in the current environment. Solution:
uv add --dev pytest-cov pytest-asyncio
Issue: Tests fail unexpectedly due to state leakage between tests
If a test passes when run individually but fails during a full test run, it is usually because a test file modifies sys.modules or global state at the module level, affecting the collection or execution of subsequent tests. You can use binary search to locate the issue:
# Runs successfully on its own
uv run pytest tests/unit_tests/xxx/test_foo.py
Issue: How to install Node.js
Frontend development requires Node.js. It is recommended to install via nvm (Node Version Manager):
# Install nvm (macOS / Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# Reload shell configuration
source ~/.bashrc
# Install and use Node.js 18
nvm install 18
nvm use 18
Windows users can use nvm-windows or download the installer directly from the Node.js website.
After installation, verify the version:
node --version
# Expected output: v18.x.x or higher
6. Building Packages
The project supports two distribution formats: Python wheel packages (.whl) and desktop executables (.exe / .dmg).
6.1 Building Wheel Packages
The project contains two independent wheel packages:
| Package | Description | Config File |
|---|---|---|
jiuwenswarm |
Backend service main package (includes Web frontend build artifacts) | pyproject.toml |
jiuwenswarm-tui |
TUI terminal interface sidecar package (includes Bun-compiled native binaries) | packages/jiuwenswarm-tui/pyproject.toml |
6.1.1 Build All (Recommended)
Run from the project root directory:
# macOS / Linux
bash scripts/build.sh
The script will execute the following steps in order:
- Build the Web frontend (runs
npm run buildinjiuwenswarm/channels/web/frontend) - Build the main package
jiuwenswarm.whl - If
bunis detected, continue to build the TUI native binary andjiuwenswarm-tui.whl
Artifacts are output to two directories:
./dist/jiuwenswarm-<version>-py3-none-any.whl(main package)./packages/jiuwenswarm-tui/dist/jiuwenswarm_tui-<version>-<platform>.whl(TUI sidecar package)
6.1.2 Build the jiuwenbox Package Alone
jiuwenbox is a standalone sandbox system package (config file: jiuwenbox/pyproject.toml). You can skip the main package and TUI sidecar via scripts/build_python_packages.py to build only the jiuwenbox wheel:
python scripts/build_python_packages.py --skip-root --skip-sidecar --clean
This command will:
- Clean
dist/,build/, andjiuwenbox.egg-infounderjiuwenbox/(triggered by--clean) - Run
uv build --wheelin thejiuwenbox/directory, outputting artifacts tojiuwenbox/dist/
Artifact: ./jiuwenbox/dist/jiuwenbox-<version>-py3-none-any.whl
Note:
build_python_packages.pybuilds the main package, TUI sidecar, and jiuwenbox by default. Use--skip-root --skip-sidecaronly when you need to produce the jiuwenbox package alone. If all three are skipped (passing--skip-root --skip-sidecar --skip-jiuwenboxtogether), the script exits with an error.
Note:
jiuwenboxrequires Python>=3.11. If the build machine's system Python is below this version, explicitly invoke the script with a 3.11 interpreter (e.g.python3.11 scripts/build_python_packages.py --skip-root --skip-sidecar --clean); otherwise the build fails due to dependency resolution errors.
6.2 Desktop EXE / DMG Packaging
The desktop version uses PyInstaller to package the Python application into a standalone executable.
6.2.1 Prerequisites
uvandNode.jsinstalled- Install development dependencies via
uv sync --extra dev(includes PyInstaller)
6.2.2 Windows Packaging (EXE)
Using batch script (recommended):
scripts\build-exe.bat
Using PowerShell script:
.\scripts\build-exe.ps1
Output: dist\jiuwenswarm\jiuwenswarm.exe
6.2.3 macOS Packaging (DMG)
bash scripts/build-macos.sh
The script will execute the following steps in order:
- Install Python dependencies (
uv sync --extra dev) - Build the Web frontend (
npm run build) - Package with PyInstaller to generate
JiuwenSwarm.app - Create a DMG installer image using
hdiutil
Output: dist/JiuwenSwarm-<version>.dmg