JiuwenSwarm

JiuwenSwarm documentation is organized into five main sections to guide users from initial setup to advanced development:

1. Installation (安装): Covers basic installation, environment preparation, TUI (Terminal User Interface) mode setup, and quick start guides.
2. Basic Usage (基础使用): Explains core features such as the Web interface, chat/dialogue, agent management, session history, scheduled tasks, skills, channels, configuration, browser services, logs, and MCP (Model Context Protocol) settings.
3. Advanced Operations (高阶操作): Details advanced capabilities including context compression, self-evolving skills, tool security/permissions, E2A/A2A protocols, multi-agent collaboration (Agent Teams), memory systems, and the TUI command architecture.
4. Appendix (附录): Provides technical details for packaging EXE files, desktop auto-update designs (Windows/macOS), and developer guides for source code debugging and secondary development.
5. Development Practices (开发实践): Showcases real-world Agent application cases, such as Code Review Assistants and Daily Report Generators, to serve as templates for building your own applications.

What is jiuwenbox?

jiuwenbox is a lightweight Linux sandbox service designed to run agent tools and code snippets in a layered, isolated environment. It provides a FastAPI-based service for managing sandbox lifecycles, file transfers, file searching, and command execution.

Key Features

• Process Isolation: Uses bubblewrap for secure process isolation.
• Filesystem Control: Static policy-based filesystem access control.
• Storage: Managed backend storage located at ~/.jiuwenbox/workspace.
• Network Isolation: Optional Linux network namespace and firewall isolation.
• Security Controls: Supports Linux capabilities, Landlock filesystem constraints (when supported by kernel), and Seccomp syscall filtering.
• Runtime Support: Executes Python and JavaScript code when runtimes are present.
• Privacy Proxy: Includes an Inference Privacy Proxy for LLM API request routing and automatic API key injection.
• Auditing: Provides audit logs and persistent sandbox lifecycle state.

JiuwenSwarm documentation is organized into five primary functional areas to help users from initial setup to advanced development:

1. Installation: Covers basic installation, environment preparation, TUI (Terminal User Interface) mode, and quick start guidance.
2. Basic Usage: Focuses on daily operations including Web UI navigation, conversations, agent management, sessions, scheduled tasks, skills, channels, configuration, browser services, logs, and MCP (Model Context Protocol) settings.
3. Advanced Operations: Details complex capabilities like context compression, skill self-evolution, security/permissions, communication protocols (E2A/A2A), multi-agent collaboration (Teams), memory systems, and TUI slash commands.
4. Appendix: Provides technical details on packaging (EXE), auto-update mechanisms for Windows/macOS, and developer-specific setup guides.
5. Development Practices: Showcases real-world Agent application cases (e.g., Code Review Assistants, Daily Report Generators) to guide secondary development.

The deepep-to-cam-converter skill is designed to migrate Mixture of Experts (MoE) code from DeepEP-based implementations to Ascend NPU environments. It automates the identification of DeepEP dispatch and combine operators and performs communication domain conversion (NCCL $\rightarrow$ HCCL), device adaptation (CUDA $\rightarrow$ NPU), and operator replacement.

Core Principles for Users

• Chain-of-Thought First: The system will output its analysis and self-check results before making any code modifications.
• In-place Modification: By default, changes are made directly to your specified files; new files are not created unless explicitly requested.
• Runtime Value Priority: The tool prioritizes actual runtime parameter values over hardcoded defaults in argparse or config.yaml to ensure constraint validation is accurate.
• Mandatory Interaction: The tool will pause to ask for user input regarding operator mode selection (e.g., A3 Ordinary vs. Shmem) and how to handle unsupported features.

A Skill is an installable, manageable, and reusable module that extends the core capabilities of a JiuwenSwarm agent. While the base agent provides fundamental capabilities like chat, file operations, web search, and code execution, Skills allow the agent to perform complex, multi-step workflows.

Workflow Lifecycle:

1. User Request: The user provides a prompt.
2. Identification: The agent identifies the need for a specific capability.
3. Loading: The agent loads the matched Skill.
4. Execution: The Skill executes its specific workflow.
5. Result: The agent returns the result to the user.

Example Scenarios:

• GitCode PR: Instead of manually managing branches and APIs, a single command like "open a PR" triggers an automated flow.
• PPT Building: A PPT skill allows generating a full slide deck directly from a prompt.
• PR Review: A skill can fetch comments, patch code, and reply to comments automatically.

JiuwenSwarm operates using different runtime modes, each defining a specific tool set, permission policy, and memory behavior. These modes determine the underlying AgentServer runtime profile and which Rails (safety/logic constraints) are active.

Available Modes

| Mode | Code | Description |
|------|------|-------------|
| Agent (Plan) | `agent.plan` | Default mode. Full tools + proactive memory, focused on reasoning and planning |
| Agent (Fast) | `agent.fast` | Full tools + passive memory, focused on quick responses |
| Code (Normal) | `code.normal` | Code mode + coding memory, focused on code execution |
| Code (Team) | `code.team` | Team collaboration launched from the Code profile |
| Team | `team` | Multi-agent collaboration mode, based on the `team` definition in config |

A2UI (Agent-to-UI) is an optional capability in JiuwenSwarm designed for the Web channel. It allows agents to return standardized UI messages (such as forms, confirmations, structured details, or comparisons) within a conversation.

When enabled, the model can include <a2ui-json>...</a2ui-json> blocks in its response. The Web frontend parses these blocks to render interactive UI components. User interactions with these components (like clicking a button or submitting a form) are sent back to the backend as structured chat content, which the agent_adapter converts into model-readable prompts to continue the conversation.

Note: A2UI is natively supported only by the Web channel. Non-Web channels (like CLI or other integrations) bypass all A2UI logic and continue using standard text/Markdown paths.

<!-- Example of the expected model output format -->
<a2ui-json>
{
  "type": "form",
  "fields": [...]
}
</a2ui-json>