# miniAgent

**Repository Path**: cyddcydd/mini-agent

## Basic Information

- **Project Name**: miniAgent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-14
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 CyddAgent - 个人专属对话助手

基于千问大模型的长期记忆代理系统，提供高度个性化的对话服务。

## ✨ 核心特性

- **长期记忆代理**：记录用户习惯、偏好，提供个性化服务
- **RAG增强生成**：结合向量检索和生成式AI
- **结构化数据库**：完整的数据存储和管理系统
- **多模态接口**：支持命令行、REST API、Web界面
- **LangChain集成**：使用LangChain框架进行工作流管理
- **上下文维护**：智能的上下文理解和维护机制

## 🚀 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <repository-url>
cd cyddAgent

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置API密钥

编辑项目根目录下的环境配置文件，设置您的千问API密钥：

```bash
# 创建环境变量文件
cp .env.example .env
# 编辑 .env 文件，设置您的API密钥
```

或者直接设置环境变量：
```bash
export DASHSCOPE_API_KEY="your-apikay"
```

### 3. 初始化数据库

```bash
python main.py init
```

### 4. 运行应用

#### 命令行聊天
```bash
python main.py chat
```

#### REST API服务
```bash
python main.py api
# API将在 http://localhost:8000 启动
```

#### Web界面
```bash
python main.py web
# Web界面将在浏览器中打开
```

#### 功能测试
```bash
python main.py test
```

## 📚 API使用

### REST API接口

#### 发送消息
```bash
curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "user_input": "你好",
    "user_id": "user123",
    "enable_rag": true,
    "enable_personalization": true
  }'
```

#### 获取对话历史
```bash
curl "http://localhost:8000/conversations/user123"
```

### Python SDK

```python
from cyddAgent.core import chat_with_cydd_agent

# 简单对话
response = chat_with_cydd_agent(
    user_input="你好",
    user_id="user123"
)

print(response["response"])
```

## 🏗️ 系统架构

```
cyddAgent/
├── core/                 # 核心模块
│   ├── conversation_manager.py  # 对话管理
│   ├── context_manager.py       # 上下文维护
│   └── dialogue_engine.py       # 对话引擎
├── database/             # 数据层
│   ├── models.py         # 数据模型
│   ├── connection.py     # 数据库连接
│   └── crud.py          # CRUD操作
├── rag/                  # RAG系统
│   ├── embeddings.py     # 向量化
│   ├── vector_store.py   # 向量存储
│   ├── retriever.py      # 检索器
│   └── generator.py      # 生成器
├── langchain/            # LangChain集成
│   ├── llm.py           # LLM包装器
│   ├── memory.py        # 记忆管理
│   └── chains.py        # 链和代理
├── api/                  # API接口
│   └── rest_api.py      # REST API
├── web/                  # Web界面
│   └── app.py           # Streamlit应用
└── utils/                # 工具模块
    └── prompts.py       # 提示词工程
```

## 🔧 配置说明

### 环境变量

- `DASHSCOPE_API_KEY`: 千问API密钥（必需）
- `DATABASE_URL`: 数据库连接URL（默认SQLite）
- `LOG_LEVEL`: 日志级别（默认INFO）
- `MAX_HISTORY_LENGTH`: 最大对话历史长度（默认100）

### 数据库模型

系统包含以下核心数据模型：

- **User**: 用户信息
- **Conversation**: 对话会话
- **Message**: 对话消息
- **UserMemory**: 用户记忆
- **UserPreference**: 用户偏好
- **KnowledgeBase**: 知识库
- **VectorIndex**: 向量索引

## 🎯 使用示例

### 1. 基础对话

```python
from cyddAgent.core import chat_with_cydd_agent

response = chat_with_cydd_agent(
    user_input="我喜欢喝咖啡",
    user_id="alice"
)
print(response["response"])  # 系统会记住Alice喜欢喝咖啡
```

### 2. 个性化服务

```python
# 下次对话时
response = chat_with_cydd_agent(
    user_input="推荐一个饮料",
    user_id="alice"
)
# 系统会基于Alice喜欢咖啡的记忆来推荐
```

### 3. RAG增强问答

```python
response = chat_with_cydd_agent(
    user_input="如何学习Python编程？",
    user_id="bob",
    enable_rag=True
)
```

## 🧪 测试

运行完整的功能测试：

```bash
python main.py test
```

## 📝 开发指南

### 添加新的记忆类型

```python
from cyddAgent.database import create_memory

# 在context_manager.py中添加新的记忆提取逻辑
def extract_custom_memory(self, conversation_text: str):
    # 自定义记忆提取逻辑
    pass
```

### 扩展RAG功能

```python
from cyddAgent.rag import add_to_vector_store

# 添加新的知识到向量数据库
add_to_vector_store(
    vector_id="custom_doc_001",
    text="您的自定义文档内容",
    metadata={"source": "custom"}
)
```

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

## 🙏 致谢

- 感谢[千问](https://dashscope.aliyun.com/)提供的大模型API
- 感谢[LangChain](https://www.langchain.com/)框架
- 感谢[FAISS](https://github.com/facebookresearch/faiss)向量检索库