zhaoxi
9b73ae4db4
Bug fixes: - fix(dao): AsyncSession.delete 补齐漏掉的 await（provider/user/individual 共 4 处） - fix(worker): result.data.output → result.output.output（pydantic-ai 1.x API 适配） - fix(api): 删除 create_worker_from_template 死端点（ORM 字段不匹配必崩） - fix(api): /provider/test 按 provider_type 分支适配 Anthropic/Gemini/OpenAI 三种协议 - fix(chat): SSE 流式聊天在 distributed 模式 fallback 到非流式，避免 asyncio.Queue 序列化崩溃 Features (previously unstaged): - feat(provider): Provider 管理页重做（品牌图标、5 种类型、Test Connection、编辑模式） - feat(provider): 新增 Gemini provider_type 支持 - feat(workflow): Finalize 节点输出 blackboard 摘要 + 失败原因；步骤完成/失败实时推送 SSE - feat(i18n): regulatory_node 提示词从路由模式改为直接对话模式（中英双语） - feat(consciousness): dynamic_prompt 支持 locale 国际化 - feat(logs): SystemLogsView 自动刷新 + 暂停按钮 Docs: - docs: README/README-EN 统一为"开源通用多 Agent 协作平台"口径 - docs: ROADMAP 按 v0.1.x / v0.2.x / v0.3.x 重组 - docs: project.md 重写为结构化项目介绍 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
205 lines
8.8 KiB
Markdown
205 lines
8.8 KiB
Markdown
<div align="center">
|
||
|
||
# KiloStar (千星)
|
||
|
||
开源通用多 Agent 协作平台
|
||
|
||
[](https://www.python.org/)
|
||
[](https://docs.ray.io/)
|
||
[](https://ai.pydantic.dev/)
|
||
[](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) 开源。
|