more_dots/README.md

# LangChain + LangGraph Scaffolding

一个使用 LangChain 和 LangGraph 构建的 AI 应用脚手架项目，提供模块化的代理和工作流管理。

## 特性

- 🚀 **模块化架构**: 基于代理和工作流的模块化设计
- 🔧 **工具集成**: 支持自定义工具和函数调用
- 💬 **多轮对话**: 内置对话状态管理和上下文维护
- 📊 **工作流管理**: 多种工作流类型，支持会话和工具使用
- ⚙️ **配置管理**: 统一的环境变量和配置管理
- 🧩 **FastAPI 接入**: 提供 HTTP 接口对外服务
- 🧭 **Nacos 注册**: 支持服务注册与心跳
- 🧪 **测试支持**: 包含基础测试和示例代码

## 项目结构

```
more_dots/
├── agent/                 # Agent 核心逻辑层
│   ├── graph.py           # LangGraph 图结构定义
│   ├── nodes.py           # 节点执行逻辑
│   ├── state.py           # Agent 状态定义
│   ├── conversation.py    # 对话代理
│   └── tool.py            # 工具代理
├── api/                   # API 接口层
│   ├── endpoints.py       # FastAPI 路由定义
│   └── dependencies.py    # API 依赖注入
├── services/              # 服务层
│   ├── llm_factory.py     # LLM 实例工厂
│   └── nacos_service.py   # Nacos 集成
├── schemas/               # 数据模型层
│   ├── agent_input.py     # 输入模型
│   └── agent_output.py    # 输出模型
├── config/                # 配置层
│   └── settings.py        # 配置读取
│   └── prompts.yaml        # 提示词配置
│   └── ragflow_templates/  # RAGFlow 模板（表名 -> 模板列表）
│   └── table_metadata_prompts/ # 表模型元数据提示词
├── tools/                 # 工具模块
│   ├── calculator.py      # 计算器工具
│   └── web_search.py      # 网络搜索工具（占位符）
├── workflows/             # 工作流管理
│   └── workflow_manager.py
├── examples/              # 使用示例
│   └── basic_usage.py
├── tests/                 # 测试文件
│   └── test_basic.py
├── requirements.txt       # 依赖包列表
├── config/
│   ├── config.ini.example  # 配置文件示例
│   ├── config.ini          # 本地配置（需自行创建）
│   └── prompts.yaml        # 提示词配置
├── server.py               # FastAPI 服务入口
├── main.py                 # CLI 入口
└── README.md               # 项目说明
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置 config.ini

```bash
# 复制配置文件
cp config/config.ini.example config/config.ini

# 编辑 config/config.ini，设置你的 API Key，并可添加多个模型配置
[General]
DEFAULT_MODEL_SECTION = gpt-4o
MAX_RETRIES = 3
TIMEOUT = 30

[gpt-4o]
MODEL_NAME = gpt-4o
OPENAI_API_KEY = your_openai_api_key_here

[gpt-3.5-turbo]
MODEL_NAME = gpt-3.5-turbo
OPENAI_API_KEY = your_openai_api_key_here
```

### 3. 运行示例

```bash
# 运行基础示例
python examples/basic_usage.py

# 运行交互式 CLI（默认模型）
python main.py

# 运行交互式 CLI（指定模型配置段）
python main.py gpt-3.5-turbo

# 运行 FastAPI 服务
python server.py
```

## 使用指南

### 基础用法

```python
from workflows.workflow_manager import WorkflowManager, WorkflowType

# 创建工作流管理器（默认模型）
manager = WorkflowManager()

# 创建工作流管理器（指定模型配置段）
manager_alt = WorkflowManager(default_model_section="gpt-3.5-turbo")

### FastAPI 接口

启动服务后，可使用以下接口：

- `GET /health`：健康检查
- `GET /nacos/status`：查看 Nacos 注册状态
- `POST /api/workflows`：执行工作流

示例请求体：

```json
{
    "input": "你好，帮我算 1 + 2",
    "session_id": null,
    "workflow_type": "conversation"
}
```

### Nacos 配置

在 `config/config.ini` 中开启 Nacos：

```ini
[nacos]
enabled = true
server = localhost:8848
namespace = public
group_name = DEFAULT_GROUP
cluster_name = DEFAULT
heartbeat_interval = 5
```

### RAGFlow 模板同步

模板文件位于 `config/ragflow_templates`，每个 JSON 对应一个表名与模板列表。
同步脚本：

```bash
python scripts/sync_ragflow_templates.py
```

请在 `config/config.ini` 中配置 `ragflow.upload` 上传接口。

# 使用对话工作流
result = manager.execute_workflow(
    WorkflowType.CONVERSATION,
    "Hello! How can you help me?"
)

# 使用工具工作流
result = manager.execute_workflow(
    WorkflowType.TOOL_USING,
    "Calculate 15 * 3 + 7"
)
```

### 自定义工具

创建新的工具类：

```python
from langchain_core.tools import BaseTool

class CustomTool(BaseTool):
    name = "custom_tool"
    description = "A custom tool for specific tasks"
    
    def _run(self, input: str) -> str:
        # 实现工具逻辑
        return f"Processed: {input}"
```

### 扩展代理

创建新的代理类型：

```python
from agents.base_agent import BaseAgent

class CustomAgent(BaseAgent):
    def _build_graph(self):
        # 实现自定义图结构
        pass
    
    def _custom_node(self, state):
        # 自定义节点逻辑
        return state
```

## 工作流类型

| 工作流类型 | 描述 | 适用场景 |
|-----------|------|----------|
| `conversation` | 多轮对话代理 | 聊天机器人、客服系统 |
| `tool_using` | 工具使用代理 | 任务执行、数据分析 |

## 开发指南

### 添加新功能

1. **新工具**: 在 `tools/` 目录下创建新的工具类
2. **新代理**: 在 `agents/` 目录下继承 `BaseAgent` 类
3. **新工作流**: 在 `workflows/` 目录下扩展工作流管理器

### 测试

```bash
# 运行所有测试
python -m pytest tests/

# 运行特定测试
python -m pytest tests/test_basic.py
```

### 调试

项目使用标准的 Python 日志系统，可以通过设置环境变量启用调试模式：

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 依赖项

主要依赖包：

- `langchain-core`: LangChain 核心功能
- `langchain`: LangChain 主包
- `langgraph`: LangGraph 图工作流
- `langchain-openai`: OpenAI 集成
- `pydantic`: 数据验证

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！