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>
103 lines
5.4 KiB
Markdown
103 lines
5.4 KiB
Markdown
# 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 增强记忆系统 | 开发中 |
|