feat: 新增工具插件、系统日志、workflow配置及前端优化
1. 新增工具插件(edit_file, python_executor, search_file, shell_executor, write_file) 2. 新增系统事件日志模块和API 3. 新增workflow配置文件和详情API 4. 前端增加SSE、错误边界、设置引导等组件 5. 优化认证加密、速率限制、配置加载等工具模块 6. 删除废弃的cluster和health API 7. 补充单元测试和集成测试 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
<div align="center">
|
||||
<div align="center">
|
||||
|
||||
# KiloStar (千星)
|
||||
|
||||
@@ -9,99 +9,176 @@
|
||||
[](https://ai.pydantic.dev/)
|
||||
[](LICENSE)
|
||||
|
||||
[**项目架构**](./docs/ARCHITECTURE.md) | [**更新日志**](./changelogs/CHANGELOG.md) | [**未来展望**](./changelogs/ROADMAP.md)
|
||||
[English](./README-EN.md) | [**更新日志**](./changelogs/CHANGELOG.md) | [**未来展望**](./changelogs/ROADMAP.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
**KiloStar** 是一款基于 **Ray** 构建的下一代分布式多 Agent 协作系统。项目采用“中心监管 + 边缘执行”的异构集群模式，通过大参数 MoE 模型进行高层逻辑推理，并协同微调后的轻量化模型高效完成具体任务。借助 **Pydantic-AI** 提供的强类型约束与 FastAPI 异步网关，kilostar 实现了任务从需求拆解、资源调度到自动化执行的全链路闭环，为个人提供可靠的人工智能助手服务。
|
||||
|
||||
**KiloStar** 是一款基于 **Ray** 构建的下一代分布式多 Agent 协作系统。项目采用"中心监管 + 边缘执行"的异构集群模式，通过大参数 MoE 模型进行高层逻辑推理，并协同微调后的轻量化模型高效完成具体任务。借助 **Pydantic-AI** 提供的强类型约束与 FastAPI 异步网关，KiloStar 实现了任务从需求拆解、资源调度到自动化执行的全链路闭环。
|
||||
|
||||
> **当前版本**：`v0.1.1-alpha`
|
||||
|
||||
---
|
||||
|
||||
## ✨ 核心特性
|
||||
|
||||
### 🧠 异构协作体系
|
||||
- **多智能体集群**：内置监控 (Regulatory)、意识 (Consciousness)、控制 (Control) 、 生长(Growth)核心节点，实现比单 Agent 系统更严谨的决策链。
|
||||
- **Worker 动态派生**：根据任务需求动态拉起 Ordinary 或 Skill 类型的 Worker Individual，实现资源的按需分配。
|
||||
- **多智能体集群**：内置监控 (Regulatory)、意识 (Consciousness)、控制 (Control)、生长 (Growth) 核心节点
|
||||
- **Worker 动态派生**：根据任务需求动态拉起 Ordinary 或 Skill 类型的 Worker Individual
|
||||
|
||||
### 🚀 分布式性能保障
|
||||
- **Ray 驱动**：底层基于 Ray 构建，支持跨进程、跨机器的 Actor 通讯，轻松应对高并发任务流。
|
||||
- **本地化优先**：深度适配 **vLLM**，支持本地私有化模型部署，在保障隐私的同时大幅降低 API 调用成本。
|
||||
- **Ray 驱动**：跨进程、跨机器的 Actor 通讯，轻松应对高并发任务流
|
||||
- **本地化优先**：深度适配 vLLM，支持本地私有化模型部署
|
||||
|
||||
### 🛠️ 工业级工程设计
|
||||
- **强类型契约**：基于 Pydantic-AI 实现 Tool 与 Agent 的接口定义，确保 AI 输出的确定性与安全性。
|
||||
- **自动化流**：内置工作流引擎 (Workflow Engine)，实现从需求发现到自动化执行的闭环。
|
||||
### 🔄 工作流引擎
|
||||
- **pydantic-graph 驱动**：基于有向图的工作流编排，支持条件分支与循环
|
||||
- **跨进程持久化**：PostgreSQL 状态快照，支持 workflow 中断后恢复（resume）
|
||||
- **人工介入 (HITL)**：内置 HumanApproval 节点，支持审批挂起与幂等恢复
|
||||
|
||||
### 📦 KiloStar 生态子项目 (Sub-projects)
|
||||
### 🛡️ 安全设计
|
||||
- **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-thought](https://github.com/zhaoxi826/thought) | 思绪 | Agent 增强记忆系统 | 开发中 |
|
||||
|
||||
| 项目名称 | 代号 | 功能定位 | 当前状态 |
|
||||
|:-----------------------------------------------------------|:--------| :--- | :--- |
|
||||
| **[kilostar-viceroy](https://github.com/zhaoxi826/viceroy)** | **总督** | **资源管理**：负责系统 Skill 的动态安装、元数据解析与全集群分发。 | ✅ 已发布 |
|
||||
| **[kilostar-thought](https://github.com/zhaoxi826/thought)** | **思绪** | **记忆系统**：增强agent的记忆系统。 | 开发中 |
|
||||
---
|
||||
## 🚀 快速开始 (Quick Start)
|
||||
|
||||
> **当前版本**：`v0.1.0-alpha` (开发预览版)
|
||||
> 本项目目前处于快速迭代阶段，欢迎提交 Issue 或 Pull Request。
|
||||
## 🚀 快速开始
|
||||
|
||||
### 方式一：使用 Docker Compose (推荐)
|
||||
这是部署 **kilostar 应用** 及其配套 **PostgreSQL 数据库** 最简单、最完整的方式。
|
||||
### Docker Compose（推荐）
|
||||
|
||||
1. **准备配置文件**：在本地创建一个目录，并新建 `docker-compose.yml`：
|
||||
```yaml
|
||||
services:
|
||||
db:
|
||||
image: postgres:16-alpine
|
||||
container_name: kilostar_db
|
||||
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
|
||||
```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.0alpha
|
||||
container_name: kilostar
|
||||
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 # 请在生产环境中修改此密钥
|
||||
```
|
||||
|
||||
2. **启动服务**
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 方式二：使用 Docker
|
||||
1. **启动服务**
|
||||
```bash
|
||||
docker run -d \
|
||||
--name kilostar \
|
||||
-p 8000:8000 \
|
||||
-p 8265:8265 \
|
||||
-e POSTGRES_HOST=你的数据库IP \
|
||||
-e POSTGRES_USER=postgres \
|
||||
-e POSTGRES_PASSWORD=postgrespassword \
|
||||
-e POSTGRES_DB=kilostar \
|
||||
-e SECRET_KEY=your_secret_key \
|
||||
zhaoxi5699/kilostar:v0.1.0alpha
|
||||
```
|
||||
|
||||
## 🔍 访问与验证
|
||||
服务启动后，可以通过以下地址进行操作：
|
||||
- Web 控制台 / API 文档: http://localhost:8000
|
||||
- Ray 任务仪表盘: http://localhost:8265
|
||||
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) 开源。
|
||||
|
||||
Reference in New Issue
Block a user