feat: initial release - Hunzi agent framework v0.1.0

2026-07-15 16:36:49 +08:00
parent bc6b267ef3
commit 0c45d3823e
1 changed files with 123 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 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` 接口