# agent-domo

**Repository Path**: adent_sun/agent-domo

## Basic Information

- **Project Name**: agent-domo
- **Description**: 扫地机器人智能客服
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 软件文档

本文档用于快速理解项目的整体架构、核心模块与主要调用流程，并给出推荐的源码阅读顺序。

## 1. 架构设计概述

本项目是一个“基于 Streamlit 的智能客服 + LangChain Agent + RAG 检索增强”的组合式架构，核心由以下三层组成：

- **UI 交互层**：`app.py` 基于 Streamlit 实现对话界面与流式输出。
- **Agent 编排层**：`agent/react_agent.py` 负责创建 Agent、注入工具与中间件，并提供流式执行接口。
- **能力与数据层**：
  - 工具层：`agent/tools/*.py` 提供 RAG、天气、用户信息等工具函数。
  - RAG 层：`rag/*` 提供向量检索与上下文总结。
  - 模型与配置：`model/factory.py`、`config/*.yml`、`utils/*.py` 负责模型工厂、配置读取、路径与日志等支撑能力。

整体流程是：**UI 收集用户问题 → Agent 组织提示词与工具调用 → 工具执行（RAG/外部数据等）→ 模型生成回答 → UI 流式展示**。

## 2. 核心模块与实现逻辑概述

### 2.1 UI 入口：`app.py`

- 负责初始化 `ReactAgent`，管理对话历史。
- 使用 `agent.execute_stream()` 进行流式输出，模拟打字机效果。
- 每次问答结束后将对话写入 `session_state` 以便回显。

### 2.2 Agent 组装：`agent/react_agent.py`

- 使用 `create_agent` 构建代理，注入：
  - **模型**：`model.factory.chat_model`
  - **系统提示词**：`utils.prompts_loader.load_system_prompts()`
  - **工具**：`agent_tools.py` 中的工具函数（RAG、天气、用户信息等）
  - **中间件**：`middleware.py` 中的监控、日志、提示词切换
- `execute_stream()` 将用户输入包装成消息列表，调用 `self.agent.stream()` 以流式方式获取结果。

### 2.3 工具与中间件：`agent/tools/agent_tools.py`、`agent/tools/middleware.py`

- **工具层**：
  - `rag_summarize`：调用 RAG 检索并总结回答。
  - `get_weather` / `get_user_id` / `get_user_location` / `get_current_month`：示例工具。
  - `generate_external_data` / `fetch_external_user_data`：从外部 CSV 读取并缓存用户行为数据。
  - `fill_context_for_report`：配合中间件用于“报告生成模式”提示词切换。
- **中间件层**：
  - `monitor_tool`：工具调用前后记录日志，并可修改运行时上下文（例如设置 `report=True`）。
  - `log_before_model`：模型调用前日志。
  - `report_prompt_switch`：根据运行时上下文切换系统提示词或报告提示词。

### 2.4 RAG 逻辑：`rag/rag_service.py`、`rag/vectory_store.py`

- `VectoryStoreService` 初始化 Chroma 向量库与文档切分器。
- `load_docs()` 从数据目录加载文本/PDF，切分后入库，并用 MD5 去重。
- `RagSummarizeService`：
  - 使用 `retriever.invoke()` 检索相关文档。
  - 构造 `context` + `question` 交给提示词模板与模型链条生成回答。

## 2.5 主流程与 RAG 流程图

下面用 Mermaid 描述主对话流程及 RAG 子流程：

```mermaid
flowchart TD
    A[用户输入] --> B[Streamlit UI app.py]
    B --> C[ReactAgent.execute_stream]
    C --> D{需要工具?}
    D -- 否 --> E[模型直接生成]
    D -- 是 --> F[工具调用]
    F --> G[中间件监控/日志/上下文]
    G --> H[工具执行完成]
    H --> I[模型生成回答]
    E --> J[流式输出到 UI]
    I --> J

    subgraph RAG 子流程
        F --> R1[rag_summarize 工具]
        R1 --> R2[VectoryStoreService.retriever]
        R2 --> R3[检索文档]
        R3 --> R4[拼接 context]
        R4 --> R5[Prompt + Model + Parser]
        R5 --> H
    end
```

## 3. 推荐源码阅读顺序与步骤

建议按“入口 → Agent → 工具 → RAG → 配置与基础工具”的顺序阅读：

1. **入口与交互**：`app.py`
   - 了解对话 UI、流式输出、会话状态管理。
2. **Agent 构建与执行**：`agent/react_agent.py`
   - 关注 `create_agent` 参数：模型、提示词、工具、中间件。
3. **工具层与中间件**：`agent/tools/agent_tools.py`、`agent/tools/middleware.py`
   - 看工具如何被 `@tool` 暴露，如何利用中间件切换提示词。
4. **RAG 实现**：`rag/vectory_store.py`、`rag/rag_service.py`
   - 看向量库加载与检索、Prompt 组织与总结链条。
5. **模型与配置**：`model/factory.py`、`config/*.yml`
   - 理解模型工厂与配置体系（模型、提示词、向量库等）。
6. **通用工具**：`utils/*.py`
   - 包括配置读取、日志、路径、文件与 MD5 工具，辅助理解运行细节。