# 售前报价Agent

**Repository Path**: lkx2000/quotation-agent

## Basic Information

- **Project Name**: 售前报价Agent
- **Description**: 针对水处理厂设备集成商的客户定制的售前报价Agent系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 报价 Agent 智能系统

> 从检索到生成：设备集成商报价数据智能化解决方案

***

## 目录

- [1. 项目简介](#1-项目简介)
- [2. 业务背景与痛点](#2-业务背景与痛点)
- [3. 核心价值](#3-核心价值)
- [4. 版本演进路线](#4-版本演进路线)
- [5. V1 检索系统](#5-v1-检索系统)
- [6. V2 智能 Agent](#6-v2-智能-agent)
- [7. 项目亮点](#7-项目亮点)
- [8. 技术栈全景](#8-技术栈全景)
- [9. 快速开始](#9-快速开始)
- [10. 目录结构](#10-目录结构)
- [11. 性能与评测](#11-性能与评测)
- [12. 演进路线](#12-演进路线)
- [13. 许可证](#13-许可证)

***

## 1. 项目简介

本项目面向**设备集成商行业的客户**，针对历史沉淀的 **7000+ 份 Excel 报价单**，分阶段实现从"找案例"到"自动生成"的全链路智能化。

系统以**历史报价数据**为底座，以**大语言模型 + 检索增强生成（RAG）为引擎，结合**Human-in-the-Loop机制，让售前工程师从"重复劳动"中解放出来，专注于高价值决策。

***

## 2. 业务背景与痛点

| 角色        | 痛点                     | 现状           |
| --------- | ---------------------- | ------------ |
| **售前工程师** | 新报价时需要从记忆中搜索"之前做过类似项目" | 找案例耗 5-10 分钟 |
| **项目经理**  | 不同工程师报价风格不统一，质量参差      | 复用难、标准化难     |
| **公司**    | 7000+ 份历史报价单沉淀在共享盘，无索引 | 数据资产沉睡       |
| **客户**    | 报价响应慢、易出错、缺乏历史参考依据     | 体验差          |

***

## 3. 核心价值

| 价值点      | V1（已实现）    | V2（已实现）        |
| -------- | ---------- | -------------- |
| **检索效率** | 5 分钟 → 5 秒 | —              |
| **草稿生成** | 手动         | 自动（LLM 智能生成）   |
| **多轮修改** | 不支持        | 自然语言多轮迭代       |
| **质量管控** | 无          | 置信度分级 + 强制反馈   |
| **数据闭环** | 无          | 反馈数据反哺 V3 规则挖掘 |

***

## 4. 版本演进路线

```
V1 检索版 ✅（已完成）
  │   解决"找案例难"
  │
  │  V1 → V2 契机：用户反馈"找案例之后还要自己改，太累"
  ↓
V2 Agent 版 ✅（已完成）
  │   解决"生成草稿难"
  │
  │  V2 → V3 契机：用户反馈积累 + 修改数据积累
  ↓
V3 规则挖掘版（规划中）
  │   解决"规则沉淀难"
  │
  │  V3 → V4 契机：规则覆盖率提升 + 业务标准化
  ↓
V4 端到端自动（规划中）
    解决"高置信场景全自动"
```

**演进哲学**：**让模型先学会"做"，再学会"做对"，最后学会"自动做对"**。

***

## 5. V1 检索系统

### 5.1 架构总览

```
报价 Excel 文件
       ↓
[Excel 解析] src/core/excel_parser.py
       ↓
[SQLite 数据库] data/demo_quotes.db
       ↓
[特征提取] src/core/feature_builder.py（智能去噪音）
       ↓
[词汇学习] src/core/vocabulary_manager.py（自动学习）
       ↓
[向量生成] src/search/embedding_service.py
       ↓
[混合检索] src/search/hybrid_search.py（60% BM25 + 40% 向量）
       ↓
[向量索引] ChromaDB
       ↓
[Web 应用] src/app.py（Flask + Tailwind CSS）
```

### 5.2 核心功能

- **Excel 数据解析与入库**
  - 支持 `.xls` / `.xlsx` / `.zip` 批量上传
  - 自动识别多 Sheet 和子表结构
  - 智能提取表头、行项目、备注和金额
  - 数据结构化存储到 SQLite
- **智能特征工程**
  - 自动移除行数、Sheet 名、合计金额等无关信息
  - 从历史数据中自动学习专业词汇，支持增量扩展
  - 调用 Embedding 模型生成 1024 维向量
  - 向量持久化到 ChromaDB
- **BM25 + 向量混合检索**
  - 双引擎融合：60% BM25 精确匹配 + 40% 向量语义相似度
  - 自然语言查询："循环水系统，预算 15 万，需要加药泵" 即可检索
  - 文件名 / 设备名称 / 品牌的高权重匹配
  - 技术参数 / 项目描述的语义理解
- **数据埋点与分析**
  - 用户行为数据云端存储
  - Session 追踪：关联完整行为链路
  - 一键导出 Excel 分析报告

### 5.3 性能指标

| 指标          | 数值        |
| ----------- | --------- |
| Excel 解析成功率 | ≥ 95%     |
| 特征提取速度      | \~100 表/秒 |
| 向量生成速度      | \~4 表/秒   |
| 检索响应时间      | < 500ms   |
| 向量维度        | 1024      |

***

## 6. V2 智能 Agent

### 6.1 背景

V1 检索系统解决了"找案例"的问题，但用户仍需手动：

1. 对比需求与历史案例的差异
2. 调整设备型号、品牌、数量
3. 生成新的报价单

**V2 目标**：让 Agent 自动完成上述工作，生成可直接使用的报价草稿。

### 6.2 系统架构

```mermaid
flowchart TB
    subgraph Frontend["🖥️ 前端层"]
        Simple["简易版<br/>HTML + Alpine.js"]
        React["React 版<br/>React 18 + TypeScript + Ant Design"]
    end

    subgraph Backend["⚡ Flask 后端"]
        API["app_agent.py<br/>API 路由"]
        EP1["/api/agent/generate<br/>生成报价草稿"]
        EP2["/api/agent/clarify<br/>追问补充"]
        EP3["/api/agent/revise<br/>修改草稿"]
        EP4["/api/agent/feedback<br/>提交反馈"]
        EP5["/api/agent/download<br/>下载 Excel"]
    end

    subgraph Agent["🤖 LangGraph Agent"]
        direction LR
        Parse["parse_requirements<br/>需求解析"] --> Check["check_params<br/>参数检查"]
        Check -->|参数完整| Retrieve["retrieve_cases<br/>案例检索"]
        Check -->|参数缺失| Clarify["clarify<br/>🛑 Human-in-the-loop 追问"]
        Clarify --> Check
        Retrieve --> Generate["generate_draft<br/>草稿生成"]
        Generate --> Render["render_quote<br/>模板渲染"]
    end

    subgraph Tools["🔧 工具层"]
        SKU["sku_lookup.py<br/>SKU 查询工具"]
        Search["hybrid_search<br/>混合检索（复用 V1）"]
    end

    subgraph Data["📁 数据层"]
        SQLite["SQLite<br/>会话/反馈存储"]
        Cases["历史案例库<br/>Supabase"]
    end

    Frontend -->|HTTP API| Backend
    Backend --> Agent
    Agent --> Tools
    Agent --> Data
    Tools --> Data
```

### 6.3 Agent 工作流

```mermaid
stateDiagram-v2
    [*] --> parse_requirements: 用户输入需求
    parse_requirements --> check_params: LLM 提取关键参数
    
    state check_params {
        [*] --> 验证参数完整性
        验证参数完整性 --> 参数完整: 所有关键参数已具备
        验证参数完整性 --> 参数缺失: 缺少品牌/流量/扬程等
    }
    
    check_params --> clarify: 参数缺失
    clarify --> check_params: 用户补充后重新验证
    check_params --> retrieve_cases: 参数完整
    retrieve_cases --> generate_draft: 检索到历史案例
    generate_draft --> render_quote: 输出 JSON 草稿
    
    state render_quote {
        [*] --> JSON转Excel
        JSON转Excel --> HTML预览
    }
    
    render_quote --> user_action: 展示草稿
    user_action --> download: 强制反馈后才可下载草稿
    user_action --> revise: 修改草稿
    revise --> revise_draft: 提交修改意见
    revise_draft --> generate_draft: 基于意见重新生成
    download --> save_session: 保存会话
    save_session --> [*]: END
```

### 6.4 核心功能

- **需求解析**：从自然语言中提取关键参数（流量、扬程、品牌、预算等），结构化 JSON 输出
- **Human-in-the-Loop 追问**：关键参数缺失时主动追问，使用 LangGraph `interrupt` 机制暂停等待
- **智能草稿生成**：对比用户需求与历史案例，自动调整不匹配设备，标注低置信度项供人工审核
- **多轮对话修改**：支持自然语言修改意见，每轮只需"当前草稿 + 修改意见"，不维护长上下文
- **强制反馈收集**：必须点赞 / 点踩才能下载，点踩需选择问题类型，为后续优化积累数据

### 6.5 双前端架构

| 前端版本        | 技术栈                                       | 适用场景       | 特点       |
| ----------- | ----------------------------------------- | ---------- | -------- |
| **简易版**     | HTML + Alpine.js + Tailwind CDN           | 快速演示、单文件部署 | 零依赖、即开即用 |
| **React 版** | React 18 + TypeScript + Vite + Ant Design | 生产级应用、可扩展  | 组件化、状态管理 |

***

## 7. 项目亮点

### 7.1 三明治架构（V2 Agent）

```
┌──────────────────────────────────────┐
│  🧠 灵魂层：LLM Prompt（业务理解）    │   ← prompts.py
├──────────────────────────────────────┤
│  🦴 骨架层：LangGraph 工作流          │   ← quote_agent.py
├──────────────────────────────────────┤
│  💪 血肉层：业务规则 + SKU 校验        │   ← nodes.py + sku_lookup.py
└──────────────────────────────────────┘
```

**设计哲学**：**LLM 负责理解、规则负责兜底**。任何一环出错都有补救措施，不依赖单一技术。

### 7.2 强 HITL 设计

- **流程可控**：参数不完整必追问，绝不猜测
- **多轮可逆**：草稿可多次修改，回退无忧
- **强制反馈门控**：不反馈不能下载，保证数据闭环
- **结构化归因**：5 类点踩原因 + 自由文本，支撑 V3 规则挖掘

### 7.3 混合检索策略（V1 复用）

- **60% BM25**：精确匹配品牌、型号、文件名
- **40% 向量**：语义理解场景、需求描述
- **混合优势**：既保证精准度，又兼顾召回率

### 7.4 置信度分级

| 等级         | 含义             | 处理策略   |
| ---------- | -------------- | ------ |
| 高（≥ 0.8）   | SKU 库匹配 + 规则通过 | 可直接使用  |
| 中（0.5-0.8） | 部分参数缺失         | 建议人工复核 |
| 低（< 0.5）   | 规则违反 / SKU 缺失  | 必须人工确认 |

### 7.5 完整数据闭环

```
用户输入 → Agent 解析 → 案例检索 → 草稿生成
    ↑                                       ↓
    └── 反馈数据 ←── 强制反馈门控 ←── 用户决策
            ↓
        V3 规则挖掘（规划中）
            ↓
        自动沉淀业务规则
            ↓
        提升下次生成质量
```

***

## 8. 技术栈全景

### 8.1 后端

| 层级           | 技术                            | 用途               |
| ------------ | ----------------------------- | ---------------- |
| **Web 框架**   | Flask                         | REST API 路由      |
| **Agent 框架** | LangGraph 1.0                 | 工作流编排 + 状态机      |
| **LLM 客户端**  | langchain-ollama / OpenRouter | 大模型调用            |
| **Excel 解析** | pandas + xlrd + openpyxl      | 历史报价单解析          |
| **混合检索**     | BM25 + 向量                     | 案例检索             |
| **向量模型**     | Ollama（qwen3-embedding）       | 1024 维 Embedding |
| **向量数据库**    | ChromaDB                      | 向量索引与检索          |
| **数据存储**     | SQLite                        | 会话/反馈/案例元数据      |
| **远程存储**     | Supabase                      | 用户行为埋点           |
| **渲染引擎**     | openpyxl + Jinja2             | Excel + HTML 渲染  |
| **日志**       | Python logging                | 分级日志（文件 + 控制台）   |
| **分词**       | jieba                         | 中文分词             |

### 8.2 前端

| 层级        | 技术                    | 用途        |
| --------- | --------------------- | --------- |
| **框架**    | React 18 + TypeScript | 组件化、强类型   |
| **构建**    | Vite                  | 极速 HMR    |
| **UI 组件** | Ant Design            | 企业级组件库    |
| **样式**    | Tailwind CSS 3        | 原子化样式     |
| **状态管理**  | Zustand 5             | 轻量级 store |
| **HTTP**  | fetch + SSE           | 流式响应      |

### 8.3 简易前端

| 技术               | 用途           |
| ---------------- | ------------ |
| HTML 5           | 静态页面骨架       |
| Alpine.js        | 轻量响应式        |
| Tailwind CSS CDN | 原子化样式（CDN 版） |

***

## 9. 快速开始

### 9.1 环境要求

- **Python** 3.11+
- **Node.js** 18+（React 前端需要）
- **Ollama**（本地向量模型）或 **OpenRouter API Key**
- 浏览器（推荐 Chrome / Edge）

### 9.2 安装步骤

```bash
# 1. 创建并激活虚拟环境
conda create -n py311 python=3.11

conda activate py311

# 2. 安装后端依赖
pip install -r requirements.txt

```

### 9.3 启动 V1 检索系统

```bash
python run.py --port 5001
```

访问：**<http://127.0.0.1:5001>**

### 9.4 启动 V2 Agent

```bash

python run_v2.py                      # 默认端口 5002
python run_v2.py --port 5003          # 自定义端口
python run_v2.py --host 0.0.0.0 --port 5002  # 允许外部访问
python run_v2.py --debug              # 调试模式

# 终端 2：启动 React 前端
cd quote-agent-frontend
npm install
npm run dev
```

访问：

- 简易版：自动打开 `demo.html`
- React 版：**<http://localhost:5173>**

***

## 10. 目录结构

```
售前报价agent/
├── README.md                  # 本文件（项目总览）
├── requirements.txt           # 后端 Python 依赖清单
├── openapi.yaml               # 后端 RESTful 接口契约（前后端共用）
├── vocabulary.json            # 业务词典（品牌/设备等标准词）
├── run.py                     # V1 检索系统启动入口（端口 5001）
├── run_v2.py                  # V2 Agent 启动入口（端口 5002）推荐
├── demo.html                  # V2 简易前端（HTML + Alpine.js）
├── .env.example               # 环境变量模板
├── .gitignore                 # Git 忽略配置
│
├── config/                    #  业务配置（独立目录，方便热更新）
│   └── business_rules.json    # 业务规则配置（泵-变频器匹配、品牌一致性等）
│
├── docs/                      #  详细文档
│   ├── V1_RETRIEVAL.md        # V1 检索系统详细指南
│   ├── V2_AGENT.md            # V2 Agent 详细指南
│   ├── evaluation_report.md   # 自动化评测报告
│   ├── supabase_config.md     # Supabase 配置说明
│   ├── 分析项目源代码1.md       # 源码深度分析
│   └── 分析项目源代码2.md       # 源码深度分析
│
├── src/                       # 后端 Python 源码
│   ├── app.py                 # V1 主应用（Flask）
│   ├── core/                  # 核心业务（V1/V2 共用）
│   │   ├── excel_parser.py    # Excel 解析引擎
│   │   ├── feature_builder.py # 特征提取（去噪音）
│   │   └── vocabulary_manager.py # 智能词汇管理
│   ├── search/                #  检索引擎（V1/V2 共用）
│   │   ├── bm25_search.py     # BM25 精确匹配
│   │   ├── embedding_service.py # 向量生成（Ollama / DashScope）
│   │   ├── hybrid_search.py   # 混合检索（60% BM25 + 40% 向量）
│   │   └── vector_index.py    # 向量索引（ChromaDB）
│   ├── v2_agent/              #  V2 Agent 核心
│   │   ├── app_agent.py       # Flask 路由（API 入口）
│   │   ├── llm_client.py      # LLM 客户端封装（Ollama/OpenRouter）
│   │   ├── nodes.py           # 工作流节点函数实现
│   │   ├── prompts.py         # LLM Prompt 模板
│   │   ├── quote_agent.py     # LangGraph 工作流编排
│   │   ├── quote_renderer.py  # JSON → Excel/HTML 渲染
│   │   ├── rules_loader.py    # 业务规则加载器
│   │   ├── sku_lookup.py      # SKU 查询工具
│   │   ├── state.py           # Agent 状态定义（TypedDict）
│   │   └── supabase_client.py # Supabase 数据同步
│   ├── utils/                 #  通用工具函数
│   ├── analytics/             #  数据分析
│   │   └── export_analytics.py # 行为分析报告导出
│   └── __init__.py
│
├── quote-agent-frontend/      #  V2 React 前端
│   ├── .traerules             # Trae IDE AI 开发规则
│   ├── .gitignore
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   ├── eslint.config.js
│   ├── README.md              # 前端独立说明
│   └── src/
│       ├── main.tsx           # React 入口
│       ├── App.tsx            # 根组件
│       ├── App.css / index.css
│       ├── api/
│       │   └── agentApi.ts    # 后端 API 封装（含 SSE 流式）
│       ├── store/
│       │   └── agentStore.ts  # Zustand 全局状态
│       ├── types/
│       │   └── index.ts       # TypeScript 类型定义
│       ├── components/
│       │   ├── chat/          #  聊天区
│       │   │   ├── InputArea.tsx
│       │   │   ├── MessageList.tsx
│       │   │   └── WelcomeScreen.tsx
│       │   ├── clarification/ #  追问卡片
│       │   │   └── ClarificationCard.tsx
│       │   ├── draft/         #  草稿区
│       │   │   ├── BomTable.tsx
│       │   │   └── DraftCard.tsx
│       │   ├── feedback/      #  反馈弹窗
│       │   │   └── FeedbackModal.tsx
│       │   ├── layout/        #  布局
│       │   │   ├── Header.tsx
│       │   │   └── Sidebar.tsx
│       │   └── thinking/      #  思考过程可视化
│       │       ├── SearchRefs.tsx
│       │       └── ThinkingProcess.tsx
│       └── assets/            # 静态资源
│
├── scripts/                   #  运维脚本
│   ├── create_quote_template.py   # 创建 Excel 报价模板
│   ├── init_agent_tables.py       # V2 数据库表初始化
│   ├── reset_demo.py              # 重置演示数据
│   ├── run_evaluation.py          # 自动化评测运行
│   └── test_supabase.py           # Supabase 连接测试
│
├── data/                      #  数据目录（运行产物，.gitignore 排除）
│   ├── demo_quotes.db         # V1 SQLite 案例库
│   ├── agent_data.db          # V2 SQLite 业务库（会话/反馈）
│   ├── vocabulary.json        # 学习后的业务词典
│   ├── chroma_db/             # ChromaDB 向量索引
│   ├── generated_quotes/      # 生成的 Excel 报价草稿
│   └── uploaded_files/        # 用户上传的原始文件
│
├── log/                       #  日志目录（.gitignore 排除）
│   ├── agent.log              # Agent 运行日志
│   └── agent_debug.log        # 调试日志
│
├── templates/                 #  Excel 模板
│   └── quote_template.xlsx    # 报价单生成模板
│
├── dataset/                   #  测试数据集（.gitignore 排除）
│   ├── STD_quotations/        # 6 份标准报价单样本
│   ├── sku_library.json       # SKU 知识库
│   └── golden_test_cases.md   # 黄金测试集
│
├── static/                    # V1 静态资源
│   └── search.js              # V1 检索前端脚本
│
└── docs/                      # （见上方 docs/ 说明）
```

### 10.1 新增成员快速定位

| 你想看什么      | 看这个文件                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------- |
| 业务如何理解需求   | [src/v2\_agent/prompts.py](src/v2_agent/prompts.py)                                          |
| 工作流怎么编排    | [src/v2\_agent/quote\_agent.py](src/v2_agent/quote_agent.py)                                 |
| 节点逻辑怎么写    | [src/v2\_agent/nodes.py](src/v2_agent/nodes.py)                                              |
| API 怎么暴露   | [src/v2\_agent/app\_agent.py](src/v2_agent/app_agent.py)                                     |
| Excel 怎么渲染 | [src/v2\_agent/quote\_renderer.py](src/v2_agent/quote_renderer.py)                           |
| 前端状态怎么管    | [quote-agent-frontend/src/store/agentStore.ts](quote-agent-frontend/src/store/agentStore.ts) |
| 前端如何调 API  | [quote-agent-frontend/src/api/agentApi.ts](quote-agent-frontend/src/api/agentApi.ts)         |
| 业务规则在哪配置   | [config/business\_rules.json](config/business_rules.json)                                    |

***

## 11. 性能与评测

### 11.1 V1 性能指标

| 指标          | 数值        |
| ----------- | --------- |
| Excel 解析成功率 | ≥ 95%     |
| 特征提取速度      | \~100 表/秒 |
| 向量生成速度      | \~4 表/秒   |
| 检索响应时间      | < 500ms   |

### 11.2 V2 自动化评测（2026-01-04）

| 指标        | 数值        |
| --------- | --------- |
| **测试用例数** | 5         |
| **通过率**   | **100%**  |
| **平均得分**  | **87.2%** |

#### 各用例得分

| 用例    | 场景          | 得分  |
| ----- | ----------- | --- |
| TC-01 | 简单生成（完整参数）  | 84% |
| TC-02 | 追问流程（参数不完整） | 91% |
| TC-03 | 参数迁移（南方泵业）  | 89% |
| TC-04 | 草稿修改（用户反馈）  | 81% |
| TC-05 | 档次切换（经济→豪华） | 91% |

#### 评测维度

| 维度         | 权重 | 平均得分 |
| ------------ | ---- | -------- |
| 参数提取     | 20%  | 89.6%    |
| SKU 验证     | 20%  | **100%** |
| 业务约束     | 25%  | **100%** |
| 响应时间     | 15%  | 64%      |
| 过程可解释性 | 20%  | 96%      |

**结论**：业务流程相关维度（SKU 验证、业务约束、可解释性）表现优秀，**参数提取准确率**与**响应时间**是后续优化重点。

***

## 12. 演进路线

### V3 规则挖掘版（规划中）

**目标**：从 V2 积累的反馈数据中自动挖掘业务规则

**核心工作**：

- 收集 V2 的 `feedback` 表数据（点赞 / 点踩 + 原因 + 详情）
- 用 LLM 分析点踩原因，挖掘新的业务规则
- 规则化后回写到 `business_rules.json`
- 让 V3 的生成质量在 V2 基础上自动提升

**预期收益**：

- 业务约束覆盖率从 25% 提升到 60%+
- 参数提取准确率从 79.6% 提升到 90%+

### V4 端到端自动（远期）

**目标**：高置信场景实现完全自动化

**核心工作**：

- 用户偏好记忆（常用品牌 / 预算 / 场景）
- 草稿一键应用历史修改
- 多人协同审批（采购 / 技术 / 财务）
- 完全自动化（高置信场景无需人工介入）

***

## 13. 许可证

本项目基于 **MIT License** 开源。

***

## 联系与反馈

- **GitHub Issues**：欢迎提交 Bug 报告与功能建议
- **Pull Requests**：欢迎贡献代码
- **邮箱**：见 GitHub Profile

***

**最后更新**：2026-06-18\
**当前版本**：V2.0\
**下一版本**：V3 规则挖掘版（规划中）