Skip to content

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.

Python
8.5 KB
Raw Blame

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 pytest instead of running pytest directly to ensure that dependencies from the uv-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:

  1. Build the Web frontend (runs npm run build in jiuwenswarm/channels/web/frontend)
  2. Build the main package jiuwenswarm.whl
  3. If bun is detected, continue to build the TUI native binary and jiuwenswarm-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:

  1. Clean dist/, build/, and jiuwenbox.egg-info under jiuwenbox/ (triggered by --clean)
  2. Run uv build --wheel in the jiuwenbox/ directory, outputting artifacts to jiuwenbox/dist/

Artifact: ./jiuwenbox/dist/jiuwenbox-<version>-py3-none-any.whl

Note: build_python_packages.py builds the main package, TUI sidecar, and jiuwenbox by default. Use --skip-root --skip-sidecar only when you need to produce the jiuwenbox package alone. If all three are skipped (passing --skip-root --skip-sidecar --skip-jiuwenbox together), the script exits with an error.

Note: jiuwenbox requires 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

  • uv and Node.js installed
  • 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:

  1. Install Python dependencies (uv sync --extra dev)
  2. Build the Web frontend (npm run build)
  3. Package with PyInstaller to generate JiuwenSwarm.app
  4. Create a DMG installer image using hdiutil

Output: dist/JiuwenSwarm-<version>.dmg