# KiloStar 项目介绍

## 简介

**KiloStar（千星）** 是一个开源的通用多 Agent 协作平台，提供从模型接入、Agent 编排、工作流执行到插件扩展的完整能力栈。系统基于 [Ray](https://www.ray.io/) 实现分布式执行，基于 [Pydantic-AI](https://ai.pydantic.dev/) 提供类型安全的 Agent 开发框架，并通过 [FastAPI](https://fastapi.tiangolo.com/) 网关对外暴露统一接口。

平台同时支持云端 API 模型与本地微调模型，内置多 Agent 协作的核心系统节点，并通过**重型插件**机制允许使用者把平台改造成面向具体场景的专用 Agent 应用。

---

## 项目特色

1. **本地微调小模型一等公民**：内置 vLLM 适配，本地微调模型在调用层与云端 API 模型对等，使用者可以为不同 Agent 节点绑定不同的本地模型。
2. **重型插件机制**：插件可附带独立前端页面、工具组与 API 接口，将 KiloStar 改造为编程辅助、学习助手、数据分析等专用 Agent 应用。
3. **多 Agent 协作内核**：监管 / 意识 / 控制 / 生长四类系统节点 + 动态派生的 Worker 个体，原生支持任务拆解、调度、监督的分工模式。
4. **standalone / distributed 双模式**：单机零依赖起步，集群按需横向扩展，业务代码在两种模式下完全一致。
5. **私有化部署友好**：所有组件可在用户自有环境内运行，不强制依赖任何第三方服务。

---

## 系统组成

### 节点体系

| 节点类型 | 职责 |
|:--|:--|
| **Regulatory Node** | 监管节点。承担用户对话入口、意图判断、对话模式的工具调用，以及对工作流执行结果的监督 |
| **Consciousness Node** | 意识节点。负责复杂任务的拆解、规划与工作流构建 |
| **Control Node** | 控制节点。负责工作流执行过程中的路由调度与状态监控 |
| **Growth Node** | 生长节点。负责集群与子个体的扩张 |
| **Worker Individual** | Worker 个体。包括 Ordinary（基础 Agent）、Skill（携带专业技能的 Agent）、Special（与外部世界交互的特殊 Agent，例如 embedding / TTS） |

### 模块布局

```
KiloStar/
├── kilostar/
│   ├── api/                          # FastAPI 路由层
│   ├── core/
│   │   ├── individual/               # 各类系统节点实现
│   │   ├── work/                     # 工作流 / 对话 / 任务执行层
│   │   ├── global_state_machine/     # 全局状态机（Provider / Config 等）
│   │   ├── global_workflow_manager/  # 工作流消息队列 Actor
│   │   └── postgres_database/        # PostgreSQL DAO 层
│   ├── adapter/                      # 模型适配器
│   ├── plugin/                       # 工具插件
│   ├── worker_cluster/               # Worker 集群管理
│   ├── worker_individual/            # Worker 个体生命周期
│   └── utils/                        # 鉴权 / Ray 句柄 / 配置等
├── frontend/                         # React + Vite 前端
├── subprojects/                      # Rust 子项目（viceroy / stardomain）
├── alembic/                          # 数据库迁移
├── tests/                            # 单元 + 集成测试
└── docs/                             # 设计文档
```

---

## 技术栈

| 层级 | 选型 | 说明 |
|:--|:--|:--|
| 分布式运行时 | **Ray** | Actor 模型、跨进程跨机器通信、自定义资源调度 |
| Agent 框架 | **Pydantic-AI** | LLM 输出强类型约束，避免多 Agent 协作中的非结构化文本黑盒 |
| Web 网关 | **FastAPI + Ray Serve** | 异步 HTTP 网关与 SSE 事件流 |
| 工作流引擎 | **pydantic-graph** | 有向图工作流编排，支持条件分支、循环、人工介入 |
| 状态持久化 | **PostgreSQL + Alembic** | workflow 中断恢复、Agent 配置、Provider 注册等 |
| 前端 | **React 19 + Vite + Tailwind + Zustand** | TypeScript 单页应用 |
| 子项目 | **Rust** | viceroy（Skill 安装）、stardomain（沙箱执行） |

---

## 运行模式

### standalone 单机模式

通过 `KILOSTAR_MODE=standalone` 启动，所有 Actor 退化为普通 Python 异步实例，无需安装 Ray，适合个人使用与开发调试。

### distributed 分布式模式

默认模式。Ray 启动后将系统节点部署为命名 Actor，WorkerCluster 按 `kilostar_node_cpu` / `core` / `gpu` 自定义资源调度到对应物理节点，支持跨机器横向扩展。

两种模式共享同一套业务代码，通过 `kilostar.utils.standalone_proxy` 在 Actor Handle 层做透明适配。

---

## 安全设计

- **JWT 鉴权**：所有 API 端点（含 SSE 事件流）均走 Bearer Token 认证
- **资源归属校验**：workflow / chat 等用户资源严格绑定 user_id，跨用户访问返回 403
- **fetch-based SSE**：Token 走 `Authorization` header，不暴露在 URL 中
- **生产模式密钥校验**：未提供有效 SECRET_KEY 时拒绝以 production 模式启动

---

## 生态子项目

| 项目 | 代号 | 功能 | 状态 |
|:--|:--|:--|:--|
| [kilostar-viceroy](https://github.com/zhaoxi826/viceroy) | 总督 | Skill 动态安装与全集群分发 | ✅ 已发布 |
| [kilostar-stardomain](../subprojects/stardomain) | 星域 | Skill / 插件脚本沙箱执行 | 开发中 |
| [kilostar-thought](https://github.com/zhaoxi826/thought) | 思绪 | Agent 增强记忆系统 | 开发中 |