# 云嘉 AI 智能体系统 · 外贸全链路自动化平台

> 面向全球IT配件经销商的 AI+RPA 智能体系统，覆盖从客户开发到采购备货的完整业务闭环。

---

## 目录

- [项目背景](#项目背景)
- [系统架构总览](#系统架构总览)
- [技能模块详解](#技能模块详解)
  - [销售模块](#销售模块)
  - [采购模块](#采购模块)
- [数据流与模块关系](#数据流与模块关系)
- [共享基础设施](#共享基础设施)
- [部署方式](#部署方式)
- [目录结构规范](#目录结构规范)
- [接口与集成说明](#接口与集成说明)

---

## 项目背景

本系统为云嘉科技定制开发，服务于其全球IT配件经销业务。  
核心目标：用 AI 智能体替代人工重复劳动，打通销售开发与采购备货两条业务线，实现数据互通、报价与成本自动对齐、全流程可追踪。

**适用角色：**

| 角色 | 关注点 |
|------|--------|
| 技术开发人员 | 各模块技术实现、接口规范、依赖关系 |
| 测试人员 | 各技能的输入输出、边界条件、异常处理 |
| 项目经理 | 模块划分、交付顺序、依赖关系 |
| 客户/业务方 | 系统能做什么、解决什么问题 |
| AI编程工具 | 仓库职责边界、数据结构、调用关系 |

---

## 系统架构总览

```
┌─────────────────────────────────────────────────────────────┐
│                        销售模块（7个技能）                    │
│                                                             │
│  search-buyers → mine-emails → send-outreach                │
│       ↓               ↓              ↓                      │
│  profile-customer ← track-followup → generate-quote         │
│                           ↓                                 │
│                    schedule-tasks                           │
└──────────────────────────┬──────────────────────────────────┘
                           │ 共享数据层（all-commons）
┌──────────────────────────┴──────────────────────────────────┐
│                        采购模块（7个技能）                    │
│                                                             │
│  search-suppliers → screen-suppliers → archive-suppliers    │
│                           ↓                                 │
│  compare-prices → calculate-pricing → trigger-stocking      │
│                           ↓                                 │
│                    track-purchase                           │
└─────────────────────────────────────────────────────────────┘
```

**核心设计原则：**
- 每个仓库是一个独立可运行的 Python 技能单元
- 所有技能通过 `all-commons` 共享数据结构、配置和工具函数
- 销售报价（generate-quote）自动拉取采购成本（calculate-pricing），实现利润闭环
- 每个技能支持单独触发，也支持串联编排

---

## 技能模块详解

### 销售模块

---

#### `search-buyers` · 多平台海外采购商搜索

**功能描述：**  
从谷歌、领英、海关数据三大渠道自动搜索目标海外采购商，聚合去重后写入客户线索库。

**输入：**
- 产品关键词（如：`network switch`, `SFP module`）
- 目标国家/地区
- 采购商规模筛选条件

**输出：**
- 结构化客户线索（公司名、官网、国家、联系人、来源渠道）
- 写入共享客户库

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 谷歌搜索采集 | Google Custom Search API 或 SerpAPI，支持 dork 语法（`site:linkedin.com "IT distributor"`） |
| 领英采集 | 基于 Playwright 模拟登录，支持多账号轮换，绕过频率限制 |
| 海关数据 | 对接 ImportYeti / Panjiva / 国内海关数据 API |
| 反爬策略 | 随机 User-Agent、请求间隔随机化（2~8秒）、代理IP池轮换 |
| 多账号管理 | 账号池配置，按任务分配账号，失败自动切换 |
| 指纹管理 | 使用 Playwright 的 stealth 插件，模拟真实浏览器指纹（Canvas、WebGL、字体） |
| 去重逻辑 | 以公司官网域名为唯一键，入库前做 MD5 比对 |
| 数据存储 | MySQL 8.0 `leads` 表，字段含来源渠道标记 |

---

#### `mine-emails` · 邮箱挖掘与清洗

**功能描述：**  
从目标公司官网、领英主页、Hunter.io 等多源渠道抓取联系人邮箱，经格式校验和MX记录验证后入库。

**输入：**
- 公司官网URL列表（来自 `search-buyers` 输出）

**输出：**
- 有效邮箱列表（联系人姓名、职位、邮箱、来源）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 官网爬取 | Playwright 动态渲染 + BeautifulSoup 静态解析，提取 mailto 和文本邮箱 |
| 邮箱发现API | Hunter.io API、Snov.io API 作为补充数据源 |
| 格式校验 | 正则匹配标准邮箱格式 |
| MX记录验证 | 通过 DNS 查询验证域名 MX 记录是否存在 |
| SMTP验证 | 可选：SMTP VRFY 命令验证邮箱是否真实存在（需控制频率） |
| 反垃圾邮件过滤 | 过滤 noreply、info@、webmaster@ 等无效地址 |
| 去重 | 邮箱地址全局唯一，已存在则更新置信度分数 |

---

#### `send-outreach` · 智能开发信生成与发送

**功能描述：**  
基于客户画像（行业、国家、产品类型）用 LLM 生成个性化英文开发信，通过多邮箱账号自动发送，记录发送状态。

**输入：**
- 客户信息（来自客户库）
- 产品信息（来自产品库）
- 邮件模板配置

**输出：**
- 邮件发送记录（时间、账号、状态）
- 触发 `track-followup` 监听回复

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 邮件生成 | 调用 LLM（GPT-4o / Claude）按 prompt 模板生成个性化内容 |
| 多邮箱账号管理 | 支持配置多个 Gmail / Outlook / 企业邮箱，按发送量均匀分配 |
| 发送频率控制 | 每账号每天限额（默认≤50封），避免触发邮件服务商封号 |
| 邮件预热 | 新账号支持预热模式，从低频开始逐步提升发送量 |
| SMTP / API发送 | 优先使用 SendGrid / Mailgun API，备用 SMTP 直连 |
| 追踪像素 | 嵌入1x1追踪像素，记录邮件打开事件 |
| 链接追踪 | 对邮件中的链接做重定向追踪，记录点击行为 |
| 退订管理 | 自动处理退订请求，标记客户状态 |
| 黑名单管理 | 全局退订列表，发送前自动过滤 |

---

#### `track-followup` · 回复解析与分层跟进

**功能描述：**  
监听多邮箱账号的收件箱，用 LLM 解析回复内容，判断意向等级，自动触发对应跟进动作。

**输入：**
- 邮箱收件箱（IMAP 监听）
- 历史沟通上下文

**输出：**
- 意向分级标签（A/B/C/无效）
- 触发下一步动作（再次发信 / 生成报价 / 标记放弃）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| IMAP监听 | 使用 `imaplib` 实时轮询或 IMAP IDLE 推送 |
| 回复解析 | LLM 提取意向信号关键词，判断：感兴趣 / 需更多信息 / 拒绝 / 无关 |
| 意向分层 | A类（明确需求）→ 立即报价；B类（模糊兴趣）→ 追问产品细节；C类（冷淡）→ 30天后再跟进 |
| 上下文管理 | 维护每个客户的完整对话历史，LLM 调用时携带上下文 |
| 自动回复生成 | 针对不同意向等级，LLM 生成对应回复草稿，人工审核后发送或全自动发送 |
| 跟进时间规则 | 可配置：发信后3天无回复自动发第二封，7天无回复发第三封 |

---

#### `generate-quote` · 报价单自动生成

**功能描述：**  
根据客户询盘内容、产品库信息、采购成本和汇率，自动计算报价并生成专业格式报价单（PDF/Excel）。

**输入：**
- 客户询盘（产品型号、数量）
- 产品库成本价（来自 `calculate-pricing`）
- 汇率接口实时数据

**输出：**
- 报价单文件（PDF + Excel）
- 报价记录写入数据库

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 成本拉取 | 实时调用 `calculate-pricing` 接口获取当前最低采购成本 |
| 利润率规则 | 可配置：按客户等级、产品类别、数量阶梯设定不同利润率 |
| 汇率实时获取 | 对接 ExchangeRate-API 或中国银行汇率接口 |
| 报价单生成 | 使用 `openpyxl` 生成 Excel，`reportlab` 或 `WeasyPrint` 生成PDF |
| 模板管理 | 支持多套报价单模板（按品牌/客户定制） |
| 有效期管理 | 报价单自动标注有效期，过期后在系统中标记失效 |
| 版本控制 | 同一询盘支持多版本报价，记录历史修改 |

---

#### `profile-customer` · 客户画像建档

**功能描述：**  
聚合各渠道获取的客户信息，构建结构化客户档案，持续更新互动记录，支持客户价值评分。

**输入：**
- 各技能产生的客户交互数据

**输出：**
- 完整客户档案（CRM记录）
- 客户价值评分（RFM模型）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 数据聚合 | 订阅各技能的事件，自动更新客户档案 |
| RFM评分 | 按最近互动时间、互动频率、询盘金额计算客户价值分 |
| 公司信息补全 | 调用 Clearbit API 或 ZoomInfo 自动补全公司规模、行业、员工数 |
| 去重合并 | 同一公司多个联系人自动归并到同一客户账户下 |
| 标签体系 | 支持自定义标签：行业、产品偏好、国家、合作状态 |

---

#### `schedule-tasks` · 任务调度与提醒

**功能描述：**  
管理所有跟进节点的时间计划，到期自动提醒相关人员，同步至外部日历，超期任务自动升级处理。

**输入：**
- 各技能触发的任务事件

**输出：**
- 提醒通知（邮件/企微/钉钉）
- 日历事件

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 任务队列 | 使用 Celery + Redis 管理定时任务 |
| 通知渠道 | 企业微信 Webhook、钉钉机器人、邮件 SMTP |
| 日历同步 | Google Calendar API / Outlook Calendar API |
| 超期升级 | 任务超期未处理自动通知上级，支持配置升级规则 |
| 任务优先级 | A类客户任务自动置顶，C类客户任务自动降级 |

---

### 采购模块

---

#### `search-suppliers` · 全网供应商搜寻

**功能描述：**  
自动聚合1688、阿里巴巴国际站、慧聪网、行业垂直平台的供应商信息，按产品分类整理入库。

**输入：**
- 产品型号 / 品牌 / 关键词
- 采购数量参考区间

**输出：**
- 供应商候选列表（名称、平台、产品范围、联系方式）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 平台爬取 | Playwright 模拟登录 + API 接口双通道 |
| 多账号管理 | 每个平台维护独立账号池，避免账号被封 |
| 指纹管理 | 浏览器指纹随机化，模拟不同设备环境 |
| 代理IP | 按平台地域选择对应IP（国内平台用国内IP） |
| 反爬策略 | 随机滑块验证码处理（打码平台对接）、请求频率控制 |
| 结果去重 | 以供应商官网/统一社会信用代码为唯一键去重 |

---

#### `screen-suppliers` · 资质筛选与风控评估

**功能描述：**  
对候选供应商进行多维度资质核查，输出可信度评分，过滤高风险供应商。

**输入：**
- 供应商候选列表（来自 `search-suppliers`）

**输出：**
- 供应商评分报告
- 推荐/排除标记

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 工商信息核查 | 对接天眼查/企查查 API，验证营业执照、经营状态、法人信息 |
| 平台信用分 | 抓取1688/阿里平台综合评分、成交量、回购率 |
| 认证核查 | ISO / CE / FCC 等认证资料核实 |
| 负面信息筛查 | 检查失信被执行人名单、行政处罚记录 |
| 历史合作记录 | 与内部系统历史采购记录关联比对 |
| 评分模型 | 加权评分（资质40% + 平台信用30% + 价格竞争力30%） |

---

#### `archive-suppliers` · 供应商信息建档

**功能描述：**  
将通过筛选的供应商信息结构化入库，建立完整档案，持续更新价格历史和合作记录。

**输入：**
- 筛选后的供应商数据

**输出：**
- 结构化供应商档案（MySQL 8.0）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 数据模型 | 供应商主表 + 产品报价子表 + 联系人子表 + 合作记录表 |
| 价格历史 | 每次比价结果自动记录，支持价格趋势分析 |
| 标签分类 | 按产品类别、地区、规模、资质等级打标签 |
| 文件存储 | 营业执照、认证文件等附件存 MinIO / 阿里OSS |
| 变更追踪 | 供应商信息变更自动记录变更日志 |

---

#### `compare-prices` · 比价与价格汇总

**功能描述：**  
针对同一产品型号，自动聚合多供应商报价，生成比价表，识别最优采购方案。

**输入：**
- 产品型号 + 采购数量
- 供应商库

**输出：**
- 比价汇总表（Excel/在线看板）
- 推荐最优供应商

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 实时询价 | 自动向已建档供应商发送询价请求（邮件/平台消息） |
| 历史价格参考 | 结合历史采购价格，识别当前报价是否合理 |
| 阶梯价处理 | 支持不同采购数量对应不同单价的阶梯价比较 |
| 汇率换算 | 外币报价自动换算为人民币统一比较 |
| 可视化报表 | 输出 Excel 比价表，包含价格趋势折线图 |

---

#### `calculate-pricing` · 规则报价引擎

**功能描述：**  
基于采购成本、运费、汇率、目标利润率规则，自动计算对外销售报价，供 `generate-quote` 调用。

**输入：**
- 采购成本（来自 `compare-prices`）
- 定价规则配置

**输出：**
- 建议销售价（含不同利润率版本）
- 最低可接受价（成本线）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 定价规则引擎 | 支持按客户等级、产品类别、数量区间配置不同利润率 |
| 成本构成 | 采购价 + 头程运费 + 关税 + 仓储费 + 平台佣金 |
| 汇率对接 | 实时汇率接口，支持配置汇率浮动保护系数 |
| 最低价保护 | 低于成本线的报价自动预警，需人工确认 |
| 规则版本管理 | 支持不同时期定价策略的版本切换 |

---

#### `trigger-stocking` · 锁货备货决策

**功能描述：**  
根据销售端询盘量预测和库存安全线规则，自动判断是否需要提前锁货备货，并触发采购流程。

**输入：**
- 当前库存数据
- 近期询盘数据（来自销售模块）
- 供应商交期数据

**输出：**
- 备货建议单
- 自动触发采购订单（或推送人工审核）

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 需求预测 | 基于历史询盘量和季节性规律，用简单时序模型预测未来30天需求 |
| 安全库存计算 | 安全库存 = 日均销量 × 供应商交期天数 × 安全系数 |
| 备货触发规则 | 库存 ≤ 安全库存时自动触发，支持手动调整阈值 |
| 供应商优选 | 自动选取综合评分最高且库存充足的供应商 |
| 审批流 | 金额超过阈值的备货单推送微信/钉钉审批，低于阈值自动执行 |

---

#### `track-purchase` · 采购进度跟踪

**功能描述：**  
全程追踪采购订单的付款、发货、物流、到货各节点状态，异常自动预警，数据同步至销售端。

**输入：**
- 采购订单信息

**输出：**
- 实时订单状态
- 异常预警通知

**技术细节：**

| 技术点 | 说明 |
|--------|------|
| 物流追踪 | 对接 17Track / 快递100 API，自动抓取物流轨迹 |
| 状态机 | 订单状态流转：待付款→已付款→备货中→已发货→运输中→已到货→已验收 |
| 异常预警 | 超期未发货、物流停滞超48小时自动触发预警 |
| 通知推送 | 关键节点变更自动推送企微/钉钉通知 |
| 与销售联动 | 到货确认后自动更新产品库存，解锁报价能力 |

---

## 数据流与模块关系

```
【销售端触发链路】
search-buyers
    → mine-emails
        → send-outreach
            → track-followup（监听回复）
                ├── A类客户 → generate-quote（拉取 calculate-pricing 成本）
                ├── B类客户 → schedule-tasks（安排再次跟进）
                └── 所有客户 → profile-customer（更新画像）

【采购端触发链路】
search-suppliers
    → screen-suppliers
        → archive-suppliers
            → compare-prices
                → calculate-pricing（输出成本价给销售端）
                → trigger-stocking（触发备货）
                    → track-purchase（跟踪到货）
                        → 库存更新 → 解锁 generate-quote

【销采闭环】
generate-quote ←→ calculate-pricing
（销售报价实时调用采购成本，利润实时可见）
```

---

## 共享基础设施

仓库：`all-commons`

```
all-commons/
├── config/
│   ├── settings.py          # 全局配置（数据库、API Key、邮箱账号池）
│   ├── proxy_pool.py        # 代理IP池管理
│   └── account_pool.py      # 多账号池管理（领英、平台账号）
├── db/
│   ├── models.py            # 所有数据表模型定义（SQLAlchemy）
│   └── migrations/          # 数据库迁移文件（Alembic）
├── utils/
│   ├── llm_client.py        # LLM统一调用封装（支持切换GPT/Claude）
│   ├── browser.py           # Playwright浏览器封装（含指纹管理）
│   ├── email_client.py      # 邮件发送/接收统一封装
│   ├── notify.py            # 企微/钉钉/邮件通知统一封装
│   └── exchange_rate.py     # 汇率查询封装
├── schemas/
│   └── data_models.py       # 技能间传递的数据结构定义（Pydantic）
└── README.md
```

**核心数据表：**

| 表名 | 说明 |
|------|------|
| `leads` | 客户线索库 |
| `customers` | 客户档案（含画像、评分） |
| `contacts` | 联系人（邮箱、职位） |
| `email_logs` | 邮件发送/接收记录 |
| `quotes` | 报价单记录 |
| `suppliers` | 供应商档案 |
| `supplier_prices` | 供应商历史报价 |
| `purchase_orders` | 采购订单 |
| `inventory` | 产品库存 |
| `tasks` | 跟进任务队列 |

---

## 部署方式

- **运行环境：** Python 3.11+，本地私有服务器（Windows/Linux均支持）
- **数据库：** MySQL 8.0+
- **任务队列：** Redis + Celery
- **浏览器自动化：** Playwright（Chromium）
- **文件存储：** 本地路径 或 MinIO
- **进程管理：** Supervisor 或 systemd

每个技能仓库均包含：
```
├── main.py          # 技能入口
├── requirements.txt # 依赖列表
├── .env.example     # 环境变量示例
├── README.md        # 技能单独说明
└── tests/           # 测试用例
```

---

## 接口与集成说明

| 外部服务 | 用途 | 技能 |
|----------|------|------|
| SerpAPI / Google CSE | 谷歌搜索采集 | search-buyers |
| Hunter.io / Snov.io | 邮箱挖掘 | mine-emails |
| SendGrid / Mailgun | 邮件发送 | send-outreach |
| OpenAI / Anthropic | LLM生成内容 | send-outreach, track-followup, generate-quote |
| 天眼查 / 企查查 | 工商信息核查 | screen-suppliers |
| 17Track / 快递100 | 物流追踪 | track-purchase |
| ExchangeRate-API | 实时汇率 | generate-quote, calculate-pricing |
| 企业微信 / 钉钉 | 通知推送 | schedule-tasks, trigger-stocking, track-purchase |
| Google / Outlook Calendar | 日历同步 | schedule-tasks |

---

*文档版本：v1.0 · 最后更新：2026-06-03 · 维护方：云嘉科技 × 匠厂AI*