# agents

**Repository Path**: tgh621/agents

## Basic Information

- **Project Name**: agents
- **Description**: 这是一个合同审查项目，帮助用户快速了解合同的规范性、帮助用户审查合同漏洞给
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档审核与票据校验系统

一个**前后端分离的全栈应用**，专业处理合同审核和发票校验，集成 AI Agent 和 OCR 技术。

## 📋 功能概览

- **发票审查**：发票图片 → OCR 识别 → 结构化提取 → 多维度校验报告
- **合同审查**：合同文本 → 信息提取 → 专业风险审核 → 详细建议
- **完整前端 UI**：React + Vite 的现代化交互界面
- **AI 驱动**：基于 LangChain 的多 Agent 智能审查系统

## 🗂️ 项目结构

```
D:\302\agents/
├── backend/                              # FastAPI + Python 后端服务
│   ├── main.py                          # FastAPI 主程序（~512 行）
│   ├── requirements.txt                 # 后端依赖
│   ├── modules/                         # 核心业务逻辑模块
│   │   ├── __init__.py
│   │   ├── invoice_verification.py      # 发票 OCR 识别
│   │   ├── invoice_validation.py        # 发票多维度校验
│   │   ├── contract_extraction.py       # 合同信息提取
│   │   └── contract_audit.py            # 合同审核规则
│   ├── samples/                         # 示例数据
│   │   ├── invoice.png
│   │   └── invoice_extracted.json
│   └── uploads/                         # 用户上传文件（运行时生成）
│
├── frontend/                             # React + Vite 前端应用
│   ├── src/
│   │   ├── components/                  # React 组件库
│   │   ├── services/api.ts              # API 调用层
│   │   ├── App.tsx & main.tsx           # 应用入口
│   │   └── ...
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── node_modules/
│
├── 配置文件
│   ├── .env                             # 全局环境变量配置（唯一的API Key来源）
│   └── README.md                        # 项目文档
│
└── 根目录脚本（保留用于命令行测试）
    ├── contract_audit_prompt_professional.py    # 合同审核脚本（副本）
    ├── contract_info_extraction.py              # 合同提取脚本（副本）
    ├── invoice_verification (2).py              # 发票识别脚本（副本）
    └── invoice_validation_agents.py             # 发票校验脚本（副本）
```

> **说明**：根目录的脚本副本用于直接命令行测试；实际后端使用的模块在 `backend/modules/` 目录

## ⚙️ 环境要求

- **Python**：3.10+
- **Node.js**：18+
- **API Key**：OpenAI 或阿里云 DashScope（至少一个）

## 🚀 快速开始

### 前置步骤：配置 API Key

在项目根目录创建或编辑 `.env` 文件：

```bash
# 方式1：使用 OpenAI
OPENAI_API_KEY=sk-proj-your-key-here
OPENAI_BASE_URL=https://api.openai.com/v1

# 方式2：使用阿里云 DashScope
DASHSCOPE_API_KEY=sk-de06116e-your-key-here

# 可选：指定模型
OPENAI_MODEL=gpt-4o-mini
```

### 方式 A：启动完整的前后端应用（推荐 ⭐）

**这样可以在浏览器中上传文档并查看审查结果。**

#### 第 1 步：启动后端（FastAPI）

打开 **第一个终端窗口**：

```bash
# 进入后端目录
cd D:\302\agents\backend

# 安装依赖（首次运行）
pip install -r requirements.txt

# 启动后端服务
python main.py
```

等待看到输出：
```
================================
文档审核系统 - FastAPI 后端服务
================================
INFO: Started server process [XXXX]
INFO: Uvicorn running on http://0.0.0.0:8000
```

#### 第 2 步：启动前端（React + Vite）

打开 **第二个终端窗口**：

```bash
# 进入前端目录
cd D:\302\agents\frontend

# 安装依赖（首次运行）
npm install

# 启动前端开发服务器
npm run dev
```

等待看到输出：
```
➜  Local:   http://localhost:3000/
```

#### 第 3 步：打开浏览器

访问 **`http://localhost:3000`**，你会看到：

- 📄 **发票审查**面板：拖入或选择发票图片 → 自动 OCR → 显示识别结果和校验报告
- 📋 **合同审查**面板：上传或粘贴合同文本 → 自动分析 → 显示风险提示和改进建议

### 方式 B：命令行测试（快速验证后端）

如果你只想快速测试后端逻辑，不启动完整应用：

#### 测试合同审核

```bash
cd D:\302\agents

# 1. 查看合同审核规则和提示词
python contract_audit_prompt_professional.py

# 2. 提取合同要素信息
python contract_info_extraction.py
```

#### 测试发票审查

```bash
cd D:\302\agents

# 1. 发票 OCR 识别（需要 invoice.png）
python "invoice_verification (2).py"
# 输出：invoice_extracted.json

# 2. 发票多维度校验
python invoice_validation_agents.py
```

## 📡 系统架构

```
浏览器 (http://localhost:3000)
    ↓ 用户上传文档
前端 React 应用
    ↓ HTTP 请求
后端 FastAPI (http://localhost:8000)
    ↓ 调用业务逻辑模块
backend/modules/ (核心脚本)
    ↓ 调用 LLM
OpenAI / DashScope
    ↓ 返回分析结果
前端展示审查结果
```

## 🔧 核心脚本说明

### 后端模块位置：`backend/modules/`

| 模块 | 功能 | 被导入于 |
|------|------|---------|
| `contract_audit.py` | 定义合同审核规则和提示词 | backend/main.py |
| `contract_extraction.py` | 从合同提取关键要素 | backend/main.py |
| `invoice_verification.py` | 发票图片 → OCR → JSON | backend/main.py |
| `invoice_validation.py` | 发票多 Agent 校验系统 | backend/main.py |

### Python 使用示例

```python
# 方式 1：通过后端 API（推荐）
# 启动后端后，通过浏览器或 curl 调用 REST API

# 方式 2：直接导入模块
import sys
sys.path.insert(0, 'D:/302/agents/backend')

# 合同信息提取
from modules.contract_extraction import extract_contract_info_dict
info = extract_contract_info_dict("你的合同全文")
print(info)

# 发票校验
from modules.invoice_validation import InvoiceValidationSystem
system = InvoiceValidationSystem(enable_llm_validation=False)
report = system.validate_invoice(your_invoice_dict)
system.print_report(report)
```

## 🎯 前端 API 接口

前端通过以下 REST API 与后端通信（访问 `http://localhost:8000/docs` 可查看 Swagger 交互式文档）：

| 方法 | 端点 | 功能 |
|------|------|------|
| POST | `/api/invoice/upload` | 上传发票图片 → OCR 识别 |
| POST | `/api/invoice/validate` | 发票多维度校验 |
| POST | `/api/contract/overview` | 上传合同 → 提取概览信息 |
| POST | `/api/contract/audit` | 合同专业审核 |
| GET | `/api/health` | 健康检查 |

详见：`frontend/src/services/api.ts`

## 🐛 常见问题与排查

### 问题 1：后端启动失败，提示 "API_KEY 未配置"

**解决**：
```bash
# Windows PowerShell
$env:OPENAI_API_KEY="sk-proj-your-key"

# Windows CMD
set OPENAI_API_KEY=sk-proj-your-key

# 或编辑 .env 文件
OPENAI_API_KEY=sk-proj-your-key
```

### 问题 2：前端无法连接后端

**检查项**：
- [ ] 后端是否运行在 `http://localhost:8000`
- [ ] 前端是否在 `http://localhost:3000`
- [ ] 浏览器控制台有无 CORS 错误
- [ ] 防火墙是否阻止了 8000 端口

### 问题 3：发票 OCR 失败

**原因可能**：
- `invoice.png` 路径不正确
- API Key 无效或达到配额
- 网络连接问题

**解决**：
```bash
# 检查文件
ls -la D:\302\agents\backend\samples\invoice.png

# 测试 API 连接
python -c "import os; print(os.getenv('OPENAI_API_KEY', 'NOT SET'))"
```

### 问题 4：npm install 失败

**解决**：
```bash
# 清除缓存
npm cache clean --force

# 使用淘宝源（如在中国）
npm config set registry https://registry.npmmirror.com

# 重新安装
npm install
```

## 📝 工作流示例

### 发票审查工作流

1. **上传发票**：在前端点击"发票审查" → 上传 JPG/PNG 图片
2. **OCR 识别**：后端调用 OpenAI Vision → 提取结构化数据
3. **多维度校验**：
   - 完整性检查（必填字段）
   - 格式检查（字段格式）
   - 计算检查（金额计算）
   - 业务规则检查（税率、日期等）
4. **显示报告**：前端展示详细的校验结果和建议

### 合同审查工作流

1. **上传合同**：在前端点击"合同审查" → 上传或粘贴合同文本
2. **信息提取**：后端提取：合同类型、当事人、金额、日期等
3. **专业审核**：应用预定义规则，识别风险条款
4. **显示结果**：前端展示审核问题、严重级别和改进建议

## 🔄 依赖关系

```
frontend/
├── React 18 + TypeScript
├── Vite 6.3（快速构建）
├── Tailwind CSS（样式）
└── Radix UI（组件库）

backend/
├── FastAPI（Web 框架）
├── Uvicorn（ASGI 服务器）
├── Pydantic（数据验证）
├── LangChain（AI Agent 框架）
└── OpenAI / DashScope SDK
```

## 📚 关于本项目

这个项目展示了如何使用 **LangChain + FastAPI + React** 构建一个完整的 AI 应用：

- **后端**：多 Agent 系统，每个 Agent 负责不同的校验维度
- **前端**：实时反馈的交互式界面
- **集成**：通过 REST API 实现前后端分离，易于扩展和部署

## 🤝 扩展建议

1. **数据库集成**：存储审查历史和报告
2. **WebSocket**：实时进度反馈（长流程处理）
3. **多语言支持**：国际化前端和 API
4. **部署**：Docker + Kubernetes 部署到云平台
5. **缓存**：Redis 缓存频繁查询结果
6. **认证**：JWT 或 OAuth 用户认证

---

**开始使用**：按上述"快速开始"步骤启动应用，即可体验完整的文档审核系统！