<div align="center">

# 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) | [**未来展望**](./changelogs/ROADMAP.md)

</div>

---

## 简介

**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) 安装解析，运行时按需加载
- **重型插件（规划中）**：带独立 UI 的垂直应用包，把 KiloStar 改造成专用 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
```

---

## 📁 项目结构

```
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/                            # 设计文档
```

---

## 🧪 测试

```bash
# 全量测试
uv run pytest tests -q

# 仅单元测试
uv run pytest tests/unit -q

# 集成测试（标记 integration）
uv run pytest tests/integration -q
```

---

## 📄 开源协议

本项目基于 [Apache License 2.0](LICENSE) 开源。