zhaoxi
9b73ae4db4
Bug fixes: - fix(dao): AsyncSession.delete 补齐漏掉的 await（provider/user/individual 共 4 处） - fix(worker): result.data.output → result.output.output（pydantic-ai 1.x API 适配） - fix(api): 删除 create_worker_from_template 死端点（ORM 字段不匹配必崩） - fix(api): /provider/test 按 provider_type 分支适配 Anthropic/Gemini/OpenAI 三种协议 - fix(chat): SSE 流式聊天在 distributed 模式 fallback 到非流式，避免 asyncio.Queue 序列化崩溃 Features (previously unstaged): - feat(provider): Provider 管理页重做（品牌图标、5 种类型、Test Connection、编辑模式） - feat(provider): 新增 Gemini provider_type 支持 - feat(workflow): Finalize 节点输出 blackboard 摘要 + 失败原因；步骤完成/失败实时推送 SSE - feat(i18n): regulatory_node 提示词从路由模式改为直接对话模式（中英双语） - feat(consciousness): dynamic_prompt 支持 locale 国际化 - feat(logs): SystemLogsView 自动刷新 + 暂停按钮 Docs: - docs: README/README-EN 统一为"开源通用多 Agent 协作平台"口径 - docs: ROADMAP 按 v0.1.x / v0.2.x / v0.3.x 重组 - docs: project.md 重写为结构化项目介绍 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
205 lines
9.4 KiB
Markdown
205 lines
9.4 KiB
Markdown
<div align="center">
|
|
|
|
# KiloStar
|
|
|
|
An open-source general-purpose multi-agent collaboration platform
|
|
|
|
[](https://www.python.org/)
|
|
[](https://docs.ray.io/)
|
|
[](https://ai.pydantic.dev/)
|
|
[](LICENSE)
|
|
|
|
[中文](./README.md) | [**Changelog**](./changelogs/CHANGELOG.md) | [**Roadmap**](./changelogs/ROADMAP.md)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
**KiloStar** is an open-source general-purpose multi-agent collaboration platform that provides a complete capability stack covering model integration, agent orchestration, workflow execution, and plugin extension. The system uses **Ray** for distributed execution, **Pydantic-AI** for type-safe agent development, and exposes a unified API surface through **FastAPI**.
|
|
|
|
The platform supports both cloud API models and locally fine-tuned models, ships with built-in core nodes for multi-agent collaboration (Regulatory, Consciousness, Control, Growth), and provides a **heavy plugin** mechanism that lets users reshape the platform into purpose-built agent applications.
|
|
|
|
> **Current version**: `v0.1.1-alpha`
|
|
|
|
## Highlights
|
|
|
|
- **Local fine-tuned models as first-class citizens**: Built-in vLLM adapter; locally fine-tuned models are interchangeable with cloud API models at the call site, allowing different agent nodes to bind different local models.
|
|
- **Heavy plugin mechanism**: Plugins can ship their own frontend pages, tool sets, and API endpoints — turning KiloStar into specialized agent applications such as coding assistants, learning helpers, or data analysis tools.
|
|
- **Multi-agent collaboration core**: Four system node types (Regulatory / Consciousness / Control / Growth) plus dynamically spawned Worker individuals, with task decomposition, scheduling, and supervision built in.
|
|
- **standalone / distributed dual mode**: Zero-dependency single-machine startup; horizontal scaling on demand. Business code is identical across both modes.
|
|
- **Private deployment friendly**: Every component runs inside the user's own environment without mandatory third-party dependencies.
|
|
|
|
---
|
|
|
|
## ✨ Core Capabilities
|
|
|
|
### 🧠 Multi-Agent Collaboration
|
|
- **System node specialization**: Regulatory, Consciousness, Control, and Growth nodes each cover a distinct responsibility
|
|
- **Worker dynamic spawning**: On-demand creation of Ordinary / Skill / Special Worker individuals
|
|
- **Strongly-typed communication**: Pydantic-AI constrains LLM output to structured data, eliminating the unstructured-text black box in multi-agent flows
|
|
|
|
### 🚀 Distributed Execution
|
|
- **Ray Actor model**: Cross-process and cross-machine collaboration for high-concurrency workloads
|
|
- **Heterogeneous resource labels**: `kilostar_node_cpu` / `core` / `gpu` route Workers to the right physical nodes
|
|
- **Standalone mode**: Zero external dependencies for single-machine startup; shares the same business code as distributed mode
|
|
|
|
### 🔄 Workflow Engine
|
|
- **pydantic-graph driven**: Directed-graph workflow orchestration with conditional branching and loops
|
|
- **Cross-process persistence**: PostgreSQL state snapshots enable workflow resume after interruption
|
|
- **Human-in-the-Loop (HITL)**: Built-in HumanApproval node with idempotent resume semantics
|
|
|
|
### 🧩 Plugin System
|
|
- **Tool plugins**: Standard tool calls; MCP protocol support for third-party services
|
|
- **Skill (compatible with Anthropic Agent Skills spec)**: Installed and parsed via [viceroy](https://github.com/zhaoxi826/viceroy), loaded on demand at runtime
|
|
- **Heavy plugins (planned)**: Vertical application packages with dedicated UI that reshape KiloStar into specialized platforms
|
|
|
|
### 🛡️ 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 is transmitted via the `Authorization` header, never exposed in URLs
|
|
|
|
### 📦 Companion Subprojects
|
|
|
|
| Project | Codename | Purpose | Status |
|
|
|:--|:--|:--|:--|
|
|
| [kilostar-viceroy](https://github.com/zhaoxi826/viceroy) | Viceroy | Skill installation and cluster-wide distribution | ✅ Released |
|
|
| [kilostar-stardomain](./subprojects/stardomain) | Stardomain | Sandbox execution for Skill / plugin scripts | In progress |
|
|
| [kilostar-thought](https://github.com/zhaoxi826/thought) | Thought | Augmented memory system for agents | In progress |
|
|
|
|
---
|
|
|
|
## 🚀 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).
|