commit 729e4442c5a48877d8346f94f1692424996c0a2b Author: chendelian <116870791@qq.com> Date: Wed Jun 3 11:09:52 2026 +0800 docs: add yunjia project overview README diff --git a/README.md b/README.md new file mode 100644 index 0000000..2a8e310 --- /dev/null +++ b/README.md @@ -0,0 +1,546 @@ +# 云嘉 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 比对 | +| 数据存储 | PostgreSQL `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` · 供应商信息建档 + +**功能描述：** +将通过筛选的供应商信息结构化入库，建立完整档案，持续更新价格历史和合作记录。 + +**输入：** +- 筛选后的供应商数据 + +**输出：** +- 结构化供应商档案（PostgreSQL） + +**技术细节：** + +| 技术点 | 说明 | +|--------|------| +| 数据模型 | 供应商主表 + 产品报价子表 + 联系人子表 + 合作记录表 | +| 价格历史 | 每次比价结果自动记录，支持价格趋势分析 | +| 标签分类 | 按产品类别、地区、规模、资质等级打标签 | +| 文件存储 | 营业执照、认证文件等附件存 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均支持） +- **数据库：** PostgreSQL 15+ +- **任务队列：** 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* \ No newline at end of file diff --git a/release.ps1 b/release.ps1 new file mode 100644 index 0000000..8d1b4e1 --- /dev/null +++ b/release.ps1 @@ -0,0 +1,34 @@ +[CmdletBinding()] +param( + [string]$Prefix = "v", + [string]$Message = "正式发布", + [switch]$AutoCommit, + [switch]$RequireClean, + [string]$CommitMessage, + [switch]$DryRun +) + +Set-StrictMode -Version Latest +$ErrorActionPreference = "Stop" + +$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$candidates = @( + (Join-Path $scriptDir "..\jiangchang-platform-kit\tools\release.ps1"), + (Join-Path $scriptDir "..\..\jiangchang-platform-kit\tools\release.ps1") +) +$sharedScript = $null +foreach ($c in $candidates) { + $resolved = [System.IO.Path]::GetFullPath($c) + if (Test-Path $resolved) { + $sharedScript = $resolved + break + } +} + +if ($null -ne $sharedScript) { + & $sharedScript @PSBoundParameters + exit $LASTEXITCODE +} + +Write-Host "Release failed: jiangchang-platform-kit/tools/release.ps1 not found." -ForegroundColor Red +exit 1