# KiloStar (千星) 开源通用多 Agent 协作平台 [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/) [![Ray](https://img.shields.io/badge/Distributed-Ray-0288d1.svg)](https://docs.ray.io/) [![Pydantic-AI](https://img.shields.io/badge/Framework-Pydantic--AI-ff69b4.svg)](https://ai.pydantic.dev/) [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE) [English](./README-EN.md) | [**更新日志**](./changelogs/CHANGELOG.md) | [**项目结构**](docs/STRUCTURE.md) | [**未来展望**](./changelogs/ROADMAP.md)
--- ## 简介 **KiloStar** 是一个开源的通用多 Agent 协作平台，提供从模型接入、Agent 编排、工作流执行到插件扩展的完整能力栈。系统基于 **Ray** 实现分布式执行，基于 **Pydantic-AI** 提供类型安全的 Agent 开发框架，并通过 **FastAPI** 网关对外暴露统一接口。 平台同时支持云端 API 模型与本地微调模型，内置多 Agent 协作的核心节点（监管、意识、控制、生长），并通过**重型插件**机制允许使用者把平台改造成面向具体场景的专用 Agent 应用。 > **当前版本**：`v0.1.1-alpha` ## 项目特色 - **本地微调小模型一等公民**：内置 vLLM 适配，支持将本地微调模型部署为系统中的 Agent 节点，与云端 API 模型在调用层面对等 - **重型插件机制**：插件可附带独立前端页面、工具组与 API 接口，将 KiloStar 改造为编程辅助、学习助手、数据分析等专用 Agent 应用 - **多 Agent 协作内核**：监管 / 意识 / 控制 / 生长四类系统节点 + 动态派生的 Worker 个体，原生支持任务拆解、调度、监督的分工模式 - **分布式与单机统一**：standalone 与 distributed 双模式共享同一套代码，单机零依赖起步，集群按需横向扩展 - **私有化部署友好**：所有组件可在用户自有环境内运行，不强制依赖任何第三方服务 --- ## ✨ 核心能力 ### 🧠 多 Agent 协作 - **核心节点分工**：监管 (Regulatory)、意识 (Consciousness)、控制 (Control)、生长 (Growth) 四类系统节点 - **Worker 动态派生**：根据任务需求拉起 Ordinary / Skill / Special 三种 Worker 个体 - **强类型通信**：基于 Pydantic-AI 将 LLM 输出约束为结构化数据，避免多 Agent 协作中的非结构化文本黑盒 ### 🚀 分布式执行 - **Ray Actor 模型**：跨进程、跨机器协作，支持高并发任务流 - **异构资源标签**：`kilostar_node_cpu` / `core` / `gpu` 调度不同 Worker 到合适节点 - **standalone 模式**：单机零依赖起步，与分布式模式共享同一套业务代码 ### 🔄 工作流引擎 - **pydantic-graph 驱动**：基于有向图的工作流编排，支持条件分支与循环 - **跨进程持久化**：PostgreSQL 状态快照，支持 workflow 中断后恢复（resume） - **人工介入 (HITL)**：内置 HumanApproval 节点，支持审批挂起与幂等恢复 ### 🧩 插件体系 - **工具插件**：标准 Tool 调用，支持 MCP 协议接入第三方服务 - **Skill（兼容 Anthropic Agent Skills 标准）**：通过 [viceroy](https://github.com/zhaoxi826/viceroy) 安装解析，运行时按需加载 - **重型插件（Organization）**：带独立工具集、多 Agent 团队与前端面板的垂直应用包，以"部门"身份接入系统内阁 ### 🛡️ 安全设计 - **JWT 鉴权**：所有 API 端点（含 SSE 事件流）均走 Bearer Token 认证 - **归属校验**：workflow / chat 资源严格绑定 user_id，跨用户访问返回 403 - **fetch-based SSE**：Token 走 Authorization header，不暴露在 URL 中 ### 📦 生态子项目 | 项目 | 代号 | 功能 | 状态 | |:--|:--|:--|:--| | [kilostar-viceroy](https://github.com/zhaoxi826/viceroy) | 总督 | Skill 动态安装与全集群分发 | ✅ 已发布 | | [kilostar-stardomain](./subprojects/stardomain) | 星域 | Skill / 插件脚本沙箱执行 | 开发中 | | [kilostar-thought](https://github.com/zhaoxi826/thought) | 思绪 | Agent 增强记忆系统 | 开发中 | --- ## 🚀 快速开始 ### Docker Compose（推荐） ```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 ``` 启动后访问： - Web 控制台：http://localhost:8000 - Ray Dashboard：http://localhost:8265 ### 本地开发 ```bash # 后端 uv sync cp config/.env.example .env # 编辑数据库和密钥配置 uv run python main.py # 前端 cd frontend && npm install && npm run dev ``` --- ## 📁 项目结构 详见 [docs/STRUCTURE.md](docs/STRUCTURE.md)。 --- ## 🧪 测试 ```bash # 全量测试 uv run pytest tests -q # 仅单元测试 uv run pytest tests/unit -q # 集成测试（标记 integration） uv run pytest tests/integration -q ``` --- ## 📄 开源协议 本项目基于 [Apache License 2.0](LICENSE) 开源。