4torm

# 4torm > Locally deployed multi-agent collaboration platform — Make AI exist like company employees, collaborate on demand <p align="center"> <img src="./public/4TORM.png" alt="4torm" width="160" /> </p> <p align="center"> <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /> <img src="https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/React-19-61DAFB?logo=react" alt="React 19" /> <img src="https://img.shields.io/badge/Vite-646CFF?logo=vite" alt="Vite" /> <img src="https://img.shields.io/badge/Fastify-5-000000?logo=fastify" alt="Fastify 5" /> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs Welcome" /> </p> <p align="center"> Monsoon Chat · Convection Meeting · Cyclone Studio · TradeWind Workflow · Tide Automation </p> <p align="center"> <a href="https://github.com/ccde141/4torm/issues">Report Bug</a> · <a href="https://github.com/ccde141/4torm">Project Repository</a> · <a href="https://space.bilibili.com/406091025">Bilibili Space</a> </p> --- ## Design Philosophy 4torm's starting point is simple: Agents are more like employees than disposable chat windows. In a company, employees are hired for long-term existence - some tasks are done by one person, some require team discussions, some follow a process, and some require regular inspections. 4torm allows AI Agents to work like this: create once, configure once, and deploy where needed. **Reuse** — The same Agent can be used for chatting today, joining a workflow tomorrow, and being triggered by a scheduled task the day after. Tools and skills are reusable across modes. **Flexibility** — Five modes are not five separate products, but five ways to organize the same set of Agents. Choose the most suitable mode for the task at hand. ## Five Collaboration Modes | Mode | Code Name | One Sentence | |------|------|--------| | Chat | Monsoon Chat | Single Agent multi-turn dialogue + tool invocation + sub-task delegation | | Meeting | Convection | One-time multi-Agent roundtable meeting, human-hosted, with private chat for the chair | | Studio | Cyclone | Permanent studio: role-based "workstations" can be privately chatted, multiple group chat rooms can be opened as needed, and a shared workspace is available | | Workflow | TradeWind | Visual canvas-based DAG, node serial/parallel execution | | Automation | Tide | Scheduled triggering, Agent autonomous execution, rolling archiving | > Convection and Cyclone are both multi-Agent group chats, but with different focuses: **Convection is a one-time meeting** (disbands after completion), **Cyclone is a permanent studio** (fixed role workstations, private chats available, multiple group chat rooms can be opened, and a shared workspace). ### Mode Selection Reference ``` Do you want an Agent to do something for you? → Monsoon Chat (Chat) Do several Agents need to discuss and reach a conclusion temporarily? → Convection (Meeting Room) Do a batch of fixed roles need to collaborate long-term, with private chats and group chats? → Cyclone (Studio) Do multiple Agents need to complete a task in sequence? → TradeWind (Workflow) Do you want Agents to perform automated inspections/reporting on a schedule? → Tide (Automation) ``` ## Core Features ### Agent Persistent Entity Each Agent has its own independent role prompt words, model configuration, tool list, skill list, and workspace directory. Created Agents persist long-term and can be reused across modes. ### Shared ReAct Engine All collaboration modes share the same ReAct loop: Think → Act → Observe → Loop → Output Response. Tool invocation, sub-task delegation, and streaming output are all unified. ### Tools, Skills, and MCP Extensible - **Tools**: Registered through `data/tools/registry.json` + `data/tools/executors/*.js`. Built-in file read/write, directory browsing, command execution, web scraping, etc. - **Skills**: Defined through `data/skills/{id}/SKILL.md`, professional prompt words, Agents load through `use_skill` tool as needed, without occupying permanent context - **MCP (Model Context Protocol)**: Connect external MCP servers on the "MCP" page (stdio + JSON-RPC), tools injected into the unified tool pool with `mcp:service_name:tool_name`, Agents can call with `mcp:service_name:*` ### Long-term Memory Trigger Agent workspace `.workspace/MEMORY.md` file, automatically injects conversation context when user messages hit keywords like "memory / remember / previous / last / history / recall". ### Streaming Output Throughout LLM streaming tokens, tool invocations, sub-task dispatch - all pushed to the front-end via SSE. Conversations can be resumed when the window is reopened (TradeWind nodes and meeting rooms support). ### Sandbox-level Isolation Agent file operations restricted by sandbox levels (`strict` / `relaxed` / `unrestricted`, default `relaxed`), path access constrained by level. ### Desktop Shell and Native Dragging Optional Electron desktop shell: reuse the same web application (local HTTP within the window), additionally unlock file absolute paths not available in browsers - through `preload` exposing `webUtils.getPathForFile`, drag-and-drop files are handed over to Agents with real paths (fallback to base64 in browsers). Production mode self-hosted by Fastify (`@fastify/static`). ## Interface Preview ### Console — Agent Management Centralized management of all registered Agents, configure models, tools, skills, and sandbox levels. <p align="center"> <img src="./public/screenshots/控制台.png" alt="Console" width="100%" /> </p> --- ### Monsoon Chat — Single Agent Dialogue Multi-turn dialogue + tool invocation + Sub-Agent delegation. Delegate sub-tasks to independent Sub-Agents through the `delegate` tool. <p align="center"> <img src="./public/screenshots/季风-Subagent调用1.png" alt="Monsoon Chat - Sub-Agent Invocation" width="100%" /> </p> <p align="center"> <img src="./public/screenshots/季风-Subagent调用2.png" alt="Monsoon Chat - Sub-Agent In Progress" width="100%" /> </p> <p align="center"> <img src="./public/screenshots/季风-Subagent调用3.png" alt="Monsoon Chat - Sub-Agent Completion" width="100%" /> </p> --- ### Convection — Multi-Agent Roundtable Meeting One-time meeting: human-hosted, multiple Agents respond in sequence, each meeting has an independent workspace, the chair (pure text, no tool advice) privately chats on the side. <p align="center"> <img src="./public/screenshots/对流会议室.png" alt="Convection Meeting Room" width="100%" /> </p> --- ### Cyclone — Permanent Studio Set up a batch of Agents as fixed "workstations", long-term collaboration, with the ability to privately chat like Monsoon and hold group chats: - **Workstation (Seat)**: Role abstraction (not the Agent itself): bind an Agent + role prompt words + a job description; the same Agent can sit in multiple workstations, each independent - **Private Chat**: Each workstation has an independent, permanent 1:1 private chat session, can be dialogued at any time - **Group Chat Room**: Open multiple rooms in the studio as needed, choose `build` (readable and writable tools) or `plan` (read-only tools) mode, specify participating workstations and speaking order - **Chair's Private Chat**: Studio-level chair Agent, overview meeting snapshots, and provide advice in a separate drawer on the right (not entering group chat) > Screenshots to be added. --- ### TradeWind — Visual Workflow DAG orchestration + real-time node status feedback + envelope circulation + meeting room nodes. <p align="center"> <img src="./public/screenshots/信风工作流.png" alt="TradeWind Workflow" width="100%" /> </p> --- ### Tide — Scheduled Automation Trigger Agents to execute at fixed intervals, support self-looping + rolling window archiving. <p align="center"> <img src="./public/screenshots/潮汐自动化.png" alt="Tide Automation" width="100%" /> </p> --- ### Tools and Skills System <p align="center"> <img src="./public/screenshots/Tools.png" alt="Tool Management" width="49%" /> <img src="./public/screenshots/Skills.png" alt="Skill Management" width="49%" /> </p> --- ### Model Provider Configuration Supports OpenAI compatible interfaces, unified management of multiple providers. <p align="center"> <img src="./public/screenshots/模型提供商.png" alt="Model Provider" width="100%" /> </p> --- ### MCP Server Connection Fill in the server name, startup command, and parameters (stdio) on the "MCP" page to connect to an external MCP server; connection status, available tools displayed in real-time, support enable/disable, delete, and one-click reconnection. Imported tools automatically merged into the tool pool, quoted by any Agent with `mcp:service_name:*`. ## Quick Start ### Environment Requirements - Node.js 20+ - npm 9+ ### Installation ```bash cd I:\A_Test_zone\4torm npm install cd server npm install cd .. ``` ### Running ```bash # Browser development: Fastify (:3001) + Vite (:5173), hot update npm run dev # → http://localhost:5173 # Desktop development: start Electron window on top of the above npm run electron:dev # Browser production self-hosting: built and hosted by Fastify in a single process npm run build && npm run start:prod # → http://localhost:3001 # Desktop production: Electron automatically pulls up the self-hosted service npm run build && npm run electron:prod ``` ### Initial Configuration 1. **Add LLM Provider** — Console → Provider Management, fill in API endpoint and key (OpenAI compatible format) 2. **Create Agent** — Console → New Agent → Select model, write role prompt words, check tools and skills 3. **Start Chat** — Switch to "Monsoon" in the sidebar → Select Agent → Send message > Preset support OpenAI compatible services. Use Anthropic / domestic manufacturers and other non-standard APIs, can be used through [one-api](https://github.com/songquanpeng/one-api) or [LiteLLM](https://github.com/BerriAI/litellm) as a translation layer. ## Tech Stack | Layer | Technology | |----|------| | Front-end | React 19 + Vite + XY Flow (canvas) | | Back-end | Fastify 5 + TypeScript + tsx | | Desktop | Electron 42 (optional shell, native file path + production self-hosting) | | LLM Communication | Native fetch, OpenAI Chat Completions compatible format | | Streaming | SSE (`text/event-stream`) throughout | | Extension Protocol | MCP (stdio + JSON-RPC, handwritten client, no additional SDK dependency) | | Data Storage | File system JSON, no database dependency | | Process Model | Development `concurrently` and start server + Vite; production Fastify (`@fastify/static`) single-process self-hosting | ## Project Structure ``` 4torm/ ├── electron/ ← Desktop shell (main.cjs + preload.cjs, native file path) ├── src/ ← Front-end (React 19 + Vite) │ ├── engine/ ← Client-side engine (parsing, prompt, streaming) │ ├── convection/ui/ ← Convection meeting page │ ├── cyclone/ui/ ← Cyclone studio page (workstation / group chat room / chair drawer) │ ├── tradewind/ui/ ← TradeWind canvas + node + panel │ ├── tide/ui/ ← Tide management panel │ └── components/mcp/ ← MCP server management page ├── server/ ← Back-end (Fastify 5 + TypeScript) │ └── src/ │ ├── engine/ │ │ ├── shared/ ← Shared layer (llm-bridge, agent-lock, exec-tool, mcp-client/manager) │ │ ├── conversation/ ← Monsoon chat engine (SessionRunner + ReAct) │ │ ├── convection/ ← Convection meeting engine │ │ ├── cyclone/ ← Cyclone studio engine (seat / room / chair / contact runner) │ │ └── tradewind/ ← TradeWind workflow engine (orchestrator + node) │ ├── services/tide/ ← Tide scheduler + runner │ └── routes/ ← HTTP routing layer (including /api/mcp) ├── data/ ← Runtime data (JSON file storage, no database) │ ├── agents/ ← Agent registry + each Agent workspace/session │ ├── tools/ ← Tool definition + executor │ ├── skills/ ← Skill module │ ├── convection/ ← Convection meeting session │ ├── cyclone/ ← Cyclone studio / workstation / room (gitignore) │ ├── mcp/ ← MCP server configuration (servers.json, gitignore) │ ├── tradewind/ ← Workflow definition + running archive │ └── tide/ ← Tide task + running record └── docs/ ← Documentation station (VitePress: getting started / five modes / extension development / architecture) ``` ## Documentation The complete documentation is the **VitePress site** under `docs/`, already built into the application - top navigation bar "Documentation" button direct access, hosted by Fastify at `/docs/` path (`base: '/docs/'`). `npm run dev` will automatically `docs:build` (`predev` hook), `npm run build` also includes a `vitepress build`, no need to manually build to view in the application. Separate writing / tuning documentation: ```bash npm run docs:dev # Independent preview (:5174, staggered with Vite's :5173) npm run docs:build # Build static site → docs/.vitepress/dist npm run docs:preview # Preview built product (:5174) ``` Site structure: - **Getting Started** — Introduction and design philosophy / quick start / core concepts - **Five Modes** — Monsoon chat / Convection meeting / Cyclone studio / TradeWind workflow / Tide automation - **Extension Development** — Tool making / skill making / MCP connection - **Architecture** — Overall architecture / data directory / security and isolation / desktop Electron > Cyclone studio (including private chat, group chat room, chair private chat) has complete user guidance, see "Five Modes → Cyclone". ## Security - **Sensitive data isolation**: `data/providers.json` (API key), `data/mcp/servers.json` (MCP configuration), `data/cyclone/` are all in `.gitignore`, not in the repository - **Agent mutex lock**: Prevent the same Agent from being driven by multiple tasks/sessions simultaneously, causing state pollution - **LLM concurrency limit**: Global maximum 3-path concurrent call (signal queue) - **Sandbox verification**: File operations limit accessible paths according to Agent sandbox level - **MCP tool name purification**: Injecting `mcp:service:tool` and other illegal function names, reversible purification before LLM, restore when returning, avoid crossing names ## How to Contribute Welcome to submit issues and pull requests! - Search for existing issues before submitting - Local development: `npm install` → `cd server && npm install` → `npm run dev` - Code style: TypeScript strict mode ## License [MIT](./LICENSE) © Ccde141 ## Contact - **Bilibili**: [space.bilibili.com/406091025](https://space.bilibili.com/406091025) - **GitHub Issues**: [github.com/ccde141/4torm/issues](https://github.com/ccde141/4torm/issues) - **Project Address**: [github.com/ccde141/4torm](https://github.com/ccde141/4torm)