hunzi/PLAN.md

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 接口