KiloStar 是一款基于 Ray 构建的下一代分布式多 Agent 协作系统。项目采用"中心监管 + 边缘执行"的异构集群模式，通过大参数 MoE 模型进行高层逻辑推理，并协同微调后的轻量化模型高效完成具体任务。借助 Pydantic-AI 提供的强类型约束与 FastAPI 异步网关，KiloStar 实现了任务从需求拆解、资源调度到自动化执行的全链路闭环。
当前版本：
v0.1.1-alpha
✨ 核心特性
🧠 异构协作体系
- 多智能体集群：内置监控 (Regulatory)、意识 (Consciousness)、控制 (Control)、生长 (Growth) 核心节点
- Worker 动态派生：根据任务需求动态拉起 Ordinary 或 Skill 类型的 Worker Individual
🚀 分布式性能保障
- Ray 驱动：跨进程、跨机器的 Actor 通讯，轻松应对高并发任务流
- 本地化优先：深度适配 vLLM，支持本地私有化模型部署
🔄 工作流引擎
- pydantic-graph 驱动：基于有向图的工作流编排，支持条件分支与循环
- 跨进程持久化：PostgreSQL 状态快照，支持 workflow 中断后恢复（resume）
- 人工介入 (HITL)：内置 HumanApproval 节点，支持审批挂起与幂等恢复
🛡️ 安全设计
- JWT 鉴权：所有 API 端点（含 SSE 事件流）均走 Bearer Token 认证
- 归属校验：workflow / chat 资源严格绑定 user_id，跨用户访问返回 403
- fetch-based SSE：Token 走 Authorization header，不暴露在 URL 中
📦 生态子项目
| 项目 | 代号 | 功能 | 状态 |
|---|---|---|---|
| kilostar-viceroy | 总督 | Skill 动态安装与全集群分发 | ✅ 已发布 |
| kilostar-thought | 思绪 | Agent 增强记忆系统 | 开发中 |
🚀 快速开始
Docker Compose（推荐）
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
docker compose up -d
启动后访问：
- Web 控制台：http://localhost:8000
- Ray Dashboard：http://localhost:8265
本地开发
# 后端
uv sync
cp config/.env.example .env # 编辑数据库和密钥配置
uv run python main.py
# 前端
cd frontend && npm install && npm run dev
📁 项目结构
KiloStar/
├── main.py # 应用入口（FastAPI + Ray 初始化）
├── pyproject.toml # Python 依赖与项目元数据
├── Dockerfile / docker-compose.yml # 容器化部署
├── alembic/ # 数据库迁移脚本
├── config/ # 环境配置模板
├── kilostar/ # 后端核心包
│ ├── api/ # FastAPI 路由层
│ │ ├── system.py # /health 系统健康检查
│ │ ├── workflow.py # /workflow CRUD + SSE + resume
│ │ ├── chat.py # /chat 会话管理
│ │ ├── agent.py # /agent Worker 管理
│ │ └── resource.py # /resource Skill/Toolset 管理
│ ├── core/ # 核心业务逻辑
│ │ ├── individual/ # 各类 Agent 节点实现
│ │ │ ├── consciousness_node/ # 意识节点（任务规划）
│ │ │ ├── regulatory_node/ # 监管节点（质量把关）
│ │ │ ├── control_node/ # 控制节点（路由调度）
│ │ │ └── growth_node/ # 生长节点（能力扩展）
│ │ ├── work/ # 工作执行层
│ │ │ ├── workflow/ # 工作流引擎（pydantic-graph）
│ │ │ ├── chat/ # 对话处理
│ │ │ └── task/ # 单任务执行
│ │ ├── global_state_machine/ # 全局状态机（Provider/Config）
│ │ ├── global_workflow_manager/ # 工作流消息队列 Actor
│ │ └── postgres_database/ # PostgreSQL DAO 层
│ ├── adapter/ # 模型适配器（OpenAI/vLLM/...）
│ ├── plugin/ # 工具插件
│ │ └── tool_plugin/ # Tavily / FileReader / Approval
│ ├── utils/ # 工具函数
│ │ ├── access.py # JWT 认证
│ │ ├── ray_hook.py # Ray Actor 句柄获取
│ │ └── check_user/ # 角色鉴权
│ ├── worker_cluster/ # Worker 集群管理
│ └── worker_individual/ # Worker 个体生命周期
├── frontend/ # React 前端（Vite + Tailwind）
│ └── src/
│ ├── api/ # Axios client + SSE 封装
│ ├── components/ # UI 组件
│ │ ├── Chat/ # 工作流面板 + 实时图
│ │ ├── Agent/ # Worker/Provider 管理
│ │ ├── Plugin/ # Skill/Tool 配置
│ │ └── Settings/ # 系统设置
│ ├── i18n/ # 国际化（中/英）
│ ├── store/ # Zustand 状态管理
│ └── types/ # TypeScript 类型定义
├── tests/ # 测试套件（249+ 用例）
│ ├── unit/ # 单元测试
│ └── integration/ # 集成 smoke 测试
└── docs/ # 设计文档
🧪 测试
# 全量测试
uv run pytest tests -q
# 仅单元测试
uv run pytest tests/unit -q
# 集成测试（标记 integration）
uv run pytest tests/integration -q
📄 开源协议
本项目基于 Apache License 2.0 开源。