zhaoxi
a53ffebe0e
1. 新增工具插件(edit_file, python_executor, search_file, shell_executor, write_file) 2. 新增系统事件日志模块和API 3. 新增workflow配置文件和详情API 4. 前端增加SSE、错误边界、设置引导等组件 5. 优化认证加密、速率限制、配置加载等工具模块 6. 删除废弃的cluster和health API 7. 补充单元测试和集成测试 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
178 lines
7.0 KiB
Markdown
178 lines
7.0 KiB
Markdown
<div align="center">
|
|
|
|
# KiloStar
|
|
|
|
A distributed multi-agent collaboration system built with Python
|
|
|
|
[](https://www.python.org/)
|
|
[](https://docs.ray.io/)
|
|
[](https://ai.pydantic.dev/)
|
|
[](LICENSE)
|
|
|
|
[中文](./README.md) | [**Changelog**](./changelogs/CHANGELOG.md) | [**Roadmap**](./changelogs/ROADMAP.md)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
**KiloStar** is a next-generation distributed multi-agent collaboration system powered by **Ray**. It adopts a "central oversight + edge execution" heterogeneous cluster model, leveraging large MoE models for high-level reasoning while coordinating fine-tuned lightweight models for efficient task execution. Built on **Pydantic-AI** with strong typing and a FastAPI async gateway, KiloStar delivers end-to-end automation from requirement decomposition to resource scheduling and execution.
|
|
|
|
> **Current version**: `v0.1.1-alpha`
|
|
|
|
---
|
|
|
|
## ✨ Key Features
|
|
|
|
### 🧠 Heterogeneous Agent Architecture
|
|
- **Multi-agent cluster**: Built-in Regulatory, Consciousness, Control, and Growth core nodes
|
|
- **Dynamic Worker spawning**: On-demand creation of Ordinary or Skill-type Worker Individuals
|
|
|
|
### 🚀 Distributed Performance
|
|
- **Ray-powered**: Cross-process, cross-machine Actor communication for high-concurrency workloads
|
|
- **Local-first**: Deep vLLM integration for private model deployment
|
|
|
|
### 🔄 Workflow Engine
|
|
- **pydantic-graph based**: Directed-graph workflow orchestration with conditional branching
|
|
- **Cross-process persistence**: PostgreSQL state snapshots enabling workflow resume after interruption
|
|
- **Human-in-the-Loop (HITL)**: Built-in HumanApproval node with idempotent resume semantics
|
|
|
|
### 🛡️ Security
|
|
- **JWT authentication**: All API endpoints (including SSE streams) require Bearer Token auth
|
|
- **Ownership enforcement**: Workflow/chat resources are user-bound; cross-user access returns 403
|
|
- **fetch-based SSE**: Token transmitted via Authorization header, never exposed in URLs
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Docker Compose (Recommended)
|
|
|
|
```yaml
|
|
services:
|
|
db:
|
|
image: postgres:16-alpine
|
|
environment:
|
|
POSTGRES_USER: postgres
|
|
POSTGRES_PASSWORD: postgrespassword
|
|
POSTGRES_DB: kilostar
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "pg_isready -U postgres -d kilostar"]
|
|
interval: 5s
|
|
timeout: 5s
|
|
retries: 5
|
|
|
|
kilostar:
|
|
image: zhaoxi5699/kilostar:v0.1.1alpha
|
|
ports:
|
|
- "8000:8000"
|
|
- "8265:8265"
|
|
depends_on:
|
|
db:
|
|
condition: service_healthy
|
|
environment:
|
|
- POSTGRES_USER=postgres
|
|
- POSTGRES_PASSWORD=postgrespassword
|
|
- POSTGRES_HOST=db
|
|
- POSTGRES_PORT=5432
|
|
- POSTGRES_DB=kilostar
|
|
- SECRET_KEY=changethiskey12345
|
|
```
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
Once running:
|
|
- Web Console: http://localhost:8000
|
|
- Ray Dashboard: http://localhost:8265
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Backend
|
|
uv sync
|
|
cp config/.env.example .env # Configure database and secret key
|
|
uv run python main.py
|
|
|
|
# Frontend
|
|
cd frontend && npm install && npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
KiloStar/
|
|
├── main.py # App entrypoint (FastAPI + Ray init)
|
|
├── pyproject.toml # Python dependencies & metadata
|
|
├── Dockerfile / docker-compose.yml # Container deployment
|
|
├── alembic/ # Database migrations
|
|
├── config/ # Environment config templates
|
|
├── kilostar/ # Backend core package
|
|
│ ├── api/ # FastAPI route layer
|
|
│ │ ├── system.py # /health system health checks
|
|
│ │ ├── workflow.py # /workflow CRUD + SSE + resume
|
|
│ │ ├── chat.py # /chat session management
|
|
│ │ ├── agent.py # /agent Worker management
|
|
│ │ └── resource.py # /resource Skill/Toolset mgmt
|
|
│ ├── core/ # Core business logic
|
|
│ │ ├── individual/ # Agent node implementations
|
|
│ │ │ ├── consciousness_node/ # Task planning
|
|
│ │ │ ├── regulatory_node/ # Quality oversight
|
|
│ │ │ ├── control_node/ # Routing & dispatch
|
|
│ │ │ └── growth_node/ # Capability expansion
|
|
│ │ ├── work/ # Work execution layer
|
|
│ │ │ ├── workflow/ # Workflow engine (pydantic-graph)
|
|
│ │ │ ├── chat/ # Chat processing
|
|
│ │ │ └── task/ # Single-task execution
|
|
│ │ ├── global_state_machine/ # Global state (Provider/Config)
|
|
│ │ ├── global_workflow_manager/ # Workflow message queue Actor
|
|
│ │ └── postgres_database/ # PostgreSQL DAO layer
|
|
│ ├── adapter/ # Model adapters (OpenAI/vLLM/...)
|
|
│ ├── plugin/ # Tool plugins
|
|
│ │ └── tool_plugin/ # Tavily / FileReader / Approval
|
|
│ ├── utils/ # Utilities
|
|
│ │ ├── access.py # JWT authentication
|
|
│ │ ├── ray_hook.py # Ray Actor handle retrieval
|
|
│ │ └── check_user/ # Role-based authorization
|
|
│ ├── worker_cluster/ # Worker cluster management
|
|
│ └── worker_individual/ # Worker individual lifecycle
|
|
├── frontend/ # React frontend (Vite + Tailwind)
|
|
│ └── src/
|
|
│ ├── api/ # Axios client + SSE wrapper
|
|
│ ├── components/ # UI components
|
|
│ │ ├── Chat/ # Workflow panel + live graph
|
|
│ │ ├── Agent/ # Worker/Provider management
|
|
│ │ ├── Plugin/ # Skill/Tool configuration
|
|
│ │ └── Settings/ # System settings
|
|
│ ├── i18n/ # Internationalization (zh/en)
|
|
│ ├── store/ # Zustand state management
|
|
│ └── types/ # TypeScript type definitions
|
|
├── tests/ # Test suite (249+ cases)
|
|
│ ├── unit/ # Unit tests
|
|
│ └── integration/ # Integration smoke tests
|
|
└── docs/ # Design documents
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
uv run pytest tests -q
|
|
|
|
# Unit tests only
|
|
uv run pytest tests/unit -q
|
|
|
|
# Integration tests
|
|
uv run pytest tests/integration -q
|
|
```
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the [Apache License 2.0](LICENSE).
|