124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
# Hunzi（混子/草鱼）自动化智能体框架 — 架构设计
|
||
|
||
## 概述
|
||
|
||
Hunzi 是一个轻量级、可扩展的自动化智能体框架，支持多 Agent 协作、工具调用、工作流编排和可视化操作界面。
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|------|------|
|
||
| 后端 | Python 3.10+ / FastAPI |
|
||
| 数据库 | SQLite + SQLAlchemy ORM |
|
||
| 前端 | 纯 HTML/CSS/JS (SPA, 由 FastAPI 静态服务) |
|
||
| 任务队列 | asyncio + APScheduler |
|
||
| LLM | OpenAI 兼容 API (支持文本+图片) |
|
||
| 部署 | 单进程，端口 16051 |
|
||
|
||
## 架构分层
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 前端 (SPA) │
|
||
│ Dashboard │ Agent管理 │ 对话 │ 工具 │ 工作流 │ 监控 │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ REST API (FastAPI) │
|
||
│ /api/agents /api/chat /api/tools /api/workflows │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 业务层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
||
│ │ Agent │ │ Workflow │ │ Scheduler │ │
|
||
│ │ Engine │ │ Engine │ │ │ │
|
||
│ └──────────┘ └──────────┘ └──────────────┘ │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 核心层 │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
|
||
│ │ LLM │ │ Tool │ │ Memory │ │
|
||
│ │ Client │ │ System │ │ System │ │
|
||
│ └──────────┘ └──────────┘ └──────────────┘ │
|
||
├─────────────────────────────────────────────────────┤
|
||
│ 数据层 (SQLite + SQLAlchemy) │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心模块
|
||
|
||
### 1. Agent 引擎
|
||
- **Agent 定义**：名称、系统提示词、模型、温度、关联工具
|
||
- **工具系统**：Python 函数注册，支持参数描述和自动调用
|
||
- **记忆系统**：对话历史、向量记忆（可扩展）
|
||
- **多 Agent 协作**：Agent 间消息传递、角色分配
|
||
|
||
### 2. 工作流编排
|
||
- **流程定义**：YAML/JSON 定义步骤、条件、循环
|
||
- **执行引擎**：顺序执行、并行分支、条件路由
|
||
- **状态管理**：步骤状态持久化、断点恢复
|
||
|
||
### 3. LLM 客户端
|
||
- OpenAI 兼容接口封装
|
||
- 支持文本和图片输入（base64/URL）
|
||
- 流式响应（SSE）
|
||
- 多模型配置管理
|
||
|
||
### 4. 调度系统
|
||
- 定时任务（Cron）
|
||
- 事件触发
|
||
- 任务队列管理
|
||
|
||
### 5. API 层
|
||
- RESTful API
|
||
- SSE 流式推送
|
||
- WebSocket 实时通信
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
hunzi/
|
||
├── app/
|
||
│ ├── __init__.py
|
||
│ ├── main.py # FastAPI 入口
|
||
│ ├── config.py # 配置管理
|
||
│ ├── database.py # 数据库 (SQLAlchemy)
|
||
│ ├── models.py # 数据模型
|
||
│ ├── llm/
|
||
│ │ ├── __init__.py
|
||
│ │ └── client.py # LLM 客户端
|
||
│ ├── agent/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── engine.py # Agent 引擎
|
||
│ │ ├── tools.py # 工具注册系统
|
||
│ │ └── memory.py # 记忆系统
|
||
│ ├── workflow/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── engine.py # 工作流引擎
|
||
│ │ └── models.py # 工作流模型
|
||
│ ├── scheduler/
|
||
│ │ ├── __init__.py
|
||
│ │ └── tasks.py # 调度任务
|
||
│ ├── api/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── agents.py
|
||
│ │ ├── chat.py
|
||
│ │ ├── tools.py
|
||
│ │ ├── workflows.py
|
||
│ │ └── health.py
|
||
│ └── utils/
|
||
│ ├── __init__.py
|
||
│ └── helpers.py
|
||
├── web/ # 前端静态文件
|
||
│ ├── index.html
|
||
│ ├── css/
|
||
│ └── js/
|
||
├── config.yaml # 配置文件
|
||
├── requirements.txt
|
||
└── run.py # 启动脚本
|
||
```
|
||
|
||
## 扩展点设计
|
||
|
||
1. **工具扩展**：装饰器注册 `@tool(name, description)` 即可新增工具
|
||
2. **Agent 扩展**：继承 `BaseAgent` 类，自定义行为
|
||
3. **LLM 扩展**：抽象 `BaseLLMClient` 接口，支持多后端
|
||
4. **工作流扩展**：自定义步骤类型
|
||
5. **记忆扩展**：抽象 `BaseMemory` 接口
|