fix: 修复 5 项确定 bug + Provider UX 重做 + 文档统一
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>
This commit is contained in:
+94
-26
@@ -1,34 +1,102 @@
|
||||
## kilostar项目
|
||||
# KiloStar 项目介绍
|
||||
|
||||
#### 简介
|
||||
**kilostar**是一款python开发，实现将小模型进行微调后整理为一个大型集群，从而实现低算力情况下高复杂度任务的实现。
|
||||
系统模型分为以下部分：
|
||||
- **监管节点**：负责基本交流和简单任务执行；
|
||||
- **管控节点**：负责调度系统资源；
|
||||
- **意识节点**：负责复杂任务的处理；
|
||||
- **生长节点**：负责扩张集群和子个体；
|
||||
- **特殊子个体**：与外界交互的模型，如embedding模型，tts模型等；
|
||||
- **专家子个体**：携带有专业skill的agent对象；
|
||||
- **基础子个体**：普通的agent对象；
|
||||
---
|
||||
#### 项目介绍
|
||||
**kilostar** 是一款基于分布式计算平台 **Ray** 和 agent开发框架**pydantic-AI** 开发的多智能体协作平台，通过多智能体的协作和任务拆解，实现复杂任务的高质量完成。
|
||||
## 简介
|
||||
|
||||
**kilostar**使用 **python**著名的高性能后端框架 **Fastapi** 来作为整个系统对用户暴露接口的网关。在**kilostar**运行过程中，用户通过发送请求至fastapi从而包装为 `kilostarEvent`对象，并且发往`regulatory_node`，由**regulatory_node**进行简单的意图判断，如果判断用户只是简单交流比如聊天等，**regulatory_node**会直接对用户进行回复结束事件。
|
||||
，如果判断用户想要完成复杂的任务，**regulatory_node**会选择将从`workflow_template(工作流模板)`中选择一个或者不选择,然后将event挂到`全局状态机`实现追溯方便并发往`Workflow_Running_Engine`的异步队列，被协程对象取走后，由**consciousness_node**创建为`kilostarWorkflow`对象，挂载到实例化的`WorkflowEngine`进行执行。完成任务后返回给用户。
|
||||
**KiloStar（千星）** 是一个开源的通用多 Agent 协作平台，提供从模型接入、Agent 编排、工作流执行到插件扩展的完整能力栈。系统基于 [Ray](https://www.ray.io/) 实现分布式执行，基于 [Pydantic-AI](https://ai.pydantic.dev/) 提供类型安全的 Agent 开发框架，并通过 [FastAPI](https://fastapi.tiangolo.com/) 网关对外暴露统一接口。
|
||||
|
||||
平台同时支持云端 API 模型与本地微调模型，内置多 Agent 协作的核心系统节点，并通过**重型插件**机制允许使用者把平台改造成面向具体场景的专用 Agent 应用。
|
||||
|
||||
---
|
||||
#### 技术架构背景
|
||||
|
||||
- 分布式大脑：利用 Ray 框架实现 Actor 模型，将不同的智能体节点（Node）部署为独立运行的分布式 Actor，具备跨节点通信和动态调度的能力。
|
||||
- 强类型通信协议：引入 PydanticAI 作为智能体开发框架，核心目的在于将大语言模型（LLM）产生的非结构化文本，通过 Pydantic 模型转化为强类型的结构化数据（JSON），确保多智能体协作时数据传输的工业级稳定性。
|
||||
- 推理驱动路由：系统针对最新的**deepseek-v4**系列进行了适配，实现灵活调用
|
||||
## 项目特色
|
||||
|
||||
1. **本地微调小模型一等公民**：内置 vLLM 适配，本地微调模型在调用层与云端 API 模型对等，使用者可以为不同 Agent 节点绑定不同的本地模型。
|
||||
2. **重型插件机制**：插件可附带独立前端页面、工具组与 API 接口，将 KiloStar 改造为编程辅助、学习助手、数据分析等专用 Agent 应用。
|
||||
3. **多 Agent 协作内核**：监管 / 意识 / 控制 / 生长四类系统节点 + 动态派生的 Worker 个体，原生支持任务拆解、调度、监督的分工模式。
|
||||
4. **standalone / distributed 双模式**：单机零依赖起步，集群按需横向扩展，业务代码在两种模式下完全一致。
|
||||
5. **私有化部署友好**：所有组件可在用户自有环境内运行，不强制依赖任何第三方服务。
|
||||
|
||||
---
|
||||
#### 项目背景
|
||||
###### 1.多智能体架构的需求
|
||||
随着任务复杂度的提升，单一**Agent**一定程度上以及满足不了人们对于人工智能完成复杂任务的需求。模仿人类社会中的团队合作，kilostar以**Ray**作为底座，从而实现一种多智能体协作的设计。
|
||||
###### 2.对于大语言模型输出内容约束的需求
|
||||
LLM 输出的非结构化文本在多智能体交互中极易崩溃。所以，**kilostar**没有选择如**LangChain**这种老牌智能体开发框架，而是选择了新兴的**pydanticAI**这种强约束框架，使得多智能体协作避免黑盒化。
|
||||
**PydanticAI**是一款基于**Pydantic**的智能体开发框架，**Pydantic**是**python**中著名的数据类型约束库，**Pydantic**官方通过**Pydantic**的强约束，实现了对于LLM的生成约束。
|
||||
|
||||
## 系统组成
|
||||
|
||||
### 节点体系
|
||||
|
||||
| 节点类型 | 职责 |
|
||||
|:--|:--|
|
||||
| **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 增强记忆系统 | 开发中 |
|
||||
|
||||
Reference in New Issue
Block a user