KiloStar/README.md

KiloStar (千星)

开源通用多 Agent 协作平台

English | 更新日志 | 项目结构 | 未来展望

---

简介

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 安装解析，运行时按需加载
• 重型插件（Organization）：带独立工具集、多 Agent 团队与前端面板的垂直应用包，以"部门"身份接入系统内阁

🛡️ 安全设计

• JWT 鉴权：所有 API 端点（含 SSE 事件流）均走 Bearer Token 认证
• 归属校验：workflow / chat 资源严格绑定 user_id，跨用户访问返回 403
• fetch-based SSE：Token 走 Authorization header，不暴露在 URL 中

📦 生态子项目

项目	代号	功能	状态
kilostar-viceroy	总督	Skill 动态安装与全集群分发	✅ 已发布
kilostar-stardomain	星域	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

---

📁 项目结构

详见 docs/STRUCTURE.md。

---

🧪 测试

# 全量测试
uv run pytest tests -q

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

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

---

📄 开源协议

本项目基于 Apache License 2.0 开源。