client-yunjia/all-commons
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
all-commons/README.md

20 KiB
Raw Permalink Blame History

云嘉 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

Reference in New Issue View Git Blame Copy Permalink