外贸报价单生成器 (Quotation-Builder)

基于 skill-creator 构建的本地 AI Skill，负责 Excel 报价单的生成。支持标准单列表格和横向 3 列布局两种模式。

快速开始

1. 前置准备

确保已安装依赖：

cd price-list-generator
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

准备配置文件：
- 创建 config/company.json 写入公司信息（见下方数据格式）
- 创建 data/local_products.csv 写入本地产品库

2. 典型调用流程

场景：从本地库生成报价单

python main.py --action search_csv --query "mouse"
# 获得产品数据后
python main.py --action generate_excel --output ./output/quote.xlsx

场景：Claude Code 一体化调用（推荐）
Claude Code 可以直接构造 JSON 参数调用：

python main.py --json '{"action":"generate_excel","products":[...],"company_info":{...}}'

场景：使用规则包抓取 1688 并生成报价

# 调用 dg-1688 规则包
from rules.dg_1688.build_quote_from_detail import build_quote
output = build_quote("https://detail.1688.com/offer/xxx.html", fx=7.2)
print(output)  # ./output/dg1688_template_quote_xxx.xlsx

数据格式规范

ProductDict（产品字典）

生成 Excel 时传入的产品数据格式：

{
  "sku": "MS-001",
  "name": "Wireless Mouse 2.4G",
  "image_url": "https://example.com/mouse.jpg",
  "price": 25.00,
  "specs": "Color: Black; DPI: 1600",
  "moq": 100,
  "remarks": "Lead time: 7 days",
  "source": "csv"
}

字段说明：
- sku: 产品唯一标识（可选）
- name: 产品名称（必填）
- image_url: 图片 URL 或本地路径（可选）
- price: 最终报价（必填，已包含 markup 和汇率换算）
- specs: 规格描述（可选）
- moq: 最小起订量（可选，默认 1）
- remarks: 备注（可选）
- source: 数据来源标记（可选，"csv" 或 "web"）

CompanyInfo（公司信息）

配置文件 config/company.json 格式：

{
  "name": "Global Trade Co., Ltd.",
  "logo_path": "./assets/logo.png",
  "website": "https://www.example.com",
  "contact_name": "Jane Smith",
  "phone": "+86-138-0000-0000",
  "whatsapp": "+86-138-0000-0000",
  "email": "sales@example.com",
  "address": "Room 101, Building A, Shenzhen, China"
}

规则包机制（Rules）

本 Skill 支持通过规则包扩展对不同电商网站的抓取支持。

规则包结构

rules/
├── dg-1688/                    # 1688.com 专用规则
│   ├── SKILL.md               # 规则说明文档
│   ├── extract_sku_selection.js    # 标准 SKU 提取脚本
│   ├── extract_sku_separated.js    # 分离式（颜色/尺码分开）提取脚本
│   └── build_quote_from_detail.py  # Python 执行入口
└── {new-rule}/               # 新增规则包目录
    ├── SKILL.md
    └── ...

当前内置规则

调用规则包

# 方式 1：直接调用规则包
from rules.dg_1688.build_quote_from_detail import build_quote
output = build_quote(detail_url, fx=DEFAULT_FX)

# 方式 2：通过主入口动态执行（推荐，适合多客户规则解耦）
python main.py --action run_rule --rule dg-1688 --url "https://detail.1688.com/offer/xxx.html"

# 方式 3：主入口 + 扩展参数
python main.py --action run_rule \
  --rule dg-1688 \
  --url "https://detail.1688.com/offer/xxx.html" \
  --rule-params '{"fx":7.2}'

规则加载约定：
- 每个规则包目录：rules/{rule-name}/
- 入口文件：build_quote_from_detail.py
- 入口函数：build_quote(url, **kwargs) -> output_path
- 支持 - 与 _ 规则名互通（例如 dg-1688 与 dg_1688）

命令参考

search_csv

从本地 CSV 检索产品。

python main.py --action search_csv --query "mouse"

参数：
- --query: 搜索关键词（SKU 精确匹配 或 Name 模糊匹配）
- --csv: CSV 文件路径（可选，默认 ./data/local_products.csv）

返回：

{
  "status": "ok",
  "query": "mouse",
  "results": [...],
  "count": 2
}

generate_excel

生成 Excel 报价单。

方式 1：使用配置文件中的公司信息和全部产品

python main.py --action generate_excel --output ./output/quote.xlsx

方式 2：指定产品和公司信息（JSON 传参）

python main.py --action generate_excel \
  --products '[{"sku":"MS-001","name":"Mouse","price":25,"specs":"DPI:1600","moq":100}]' \
  --company '{"name":"My Co.","website":"https://example.com"}' \
  --output ./output/quote.xlsx

参数：
- --products: 产品列表 JSON 字符串（可选，默认使用 CSV 全部产品）
- --company: 公司信息 JSON 字符串（可选，默认使用配置文件）
- --output: 输出文件路径（可选，默认 ./output/quotation_{timestamp}.xlsx）
- --temp-dir: 临时图片目录（可选，默认 ./tmp/images）

返回：

{
  "status": "ok",
  "file_path": "./output/quotation_20260326_143052.xlsx",
  "warnings": []
}

JSON 一体化传参模式

适合 Claude Code 直接调用，单条命令完成所有操作：

python main.py --json '{
  "action": "generate_excel",
  "products": [
    {
      "sku": "MS-001",
      "name": "Wireless Mouse 2.4G",
      "image_url": "https://example.com/mouse.jpg",
      "price": 25.00,
      "specs": "Color: Black; DPI: 1600",
      "moq": 100,
      "remarks": "Lead time: 7 days"
    }
  ],
  "company_info": {
    "name": "Global Trade Co., Ltd.",
    "logo_path": "./assets/logo.png",
    "website": "https://www.example.com",
    "contact_name": "Jane Smith",
    "phone": "+86-138-0000-0000",
    "whatsapp": "+86-138-0000-0000",
    "email": "sales@example.com"
  },
  "output_path": "./output/quotation.xlsx",
  "temp_dir": "./tmp/images"
}'

与 web-access Skill 协同

本 Skill 不直接抓取网页，需要配合 web-access Skill 使用。

完整工作流示例：

1. Claude Code 接收用户指令：
   > "抓取这个 1688 链接 https://example.com/product 生成报价单，利润加 30%"

2. Claude Code 调用 web-access 抓取商品信息：
   - 使用 web-access 的 /navigate 打开页面
   - 使用 /scroll 滚动加载图片
   - 使用 /eval 提取产品标题、价格、图片 URL

3. Claude Code 在内存中处理数据：
   - 提取价格字段
   - 应用 30% markup：price * 1.30
   - 转换为美元（如需要）

4. Claude Code 构造 ProductDict 并调用本 Skill：
   bash python main.py --json '{"action":"generate_excel","products":[...],"company_info":{...}}'

5. 返回生成的 Excel 文件路径给用户

Excel 输出格式

标准布局（单列）

包含三个区域：

1. 公司信息区（第 1-5 行）：
   - A1:B5：公司 Logo（等比缩放，最大 200px）
   - C1:F5：公司名称、官网、联系人、电话、WhatsApp、邮箱

2. 表头区（第 6 行）：
   - 字段：Image, Product Name, Specifications, Unit Price (USD), MOQ, Remarks
   - 样式：深蓝色背景（#1F4E79）、白色加粗字体

3. 数据区（第 7 行起）：
   - 行高 80pt，容纳产品图片
   - 图片等比缩放，最大 90×90px
   - 奇偶行交替背景色
   - Unit Price 格式化为 $25.00

横向 3 列布局（DG-1688 规则专用）

适用于产品数量多、需要紧凑展示的场景：

第1行（图片行）:  [图片1] [链接1] [空] [图片2] [链接2] [空] [图片3] [链接3] [空]
第2行（数据行）:  [名称] [CNY] [USD] [名称] [CNY] [USD] [名称] [CNY] [USD]

列宽设置：
- 图片列：18
- CNY 价格列：10（缩减）
- USD 价格列：14（加宽，显示绿色加粗 $）
- 空列：2（留白）

产品名称处理：
- 提取原始编号（如 E560-钢色爱心手链 → E560）
- 添加 DG 前缀（如 DG-E560）
- 添加序号避免重名（如 DG-E560-01、DG-E560-02）

USD 价格计算：
- 公式：CNY / 0.65 / 7
- 保留 2 位小数，四舍五入
- 显示美元符号（绿色加粗）

错误处理

文件结构

price-list-generator/
├── main.py              # 主入口
├── csv_manager.py       # CSV 检索
├── excel_builder.py     # Excel 生成
├── image_handler.py     # 图片处理
├── SKILL.md             # 本文件
├── rules/               # 抓取规则包目录
│   └── dg-1688/         # 1688.com 规则
│       ├── SKILL.md
│       ├── extract_sku_selection.js
│       ├── extract_sku_separated.js
│       └── build_quote_from_detail.py
├── config/
│   └── company.json     # 公司信息配置
├── assets/
│   └── logo.png         # 公司 Logo
├── data/
│   └── local_products.csv   # 本地产品库
├── tmp/
│   └── images/          # 临时图片下载目录
└── output/              # 默认报价单输出目录

技术细节

• 图片处理：自动下载网络图片，WebP/AVIF 转 PNG，等比缩放至最大 90px
• 单元格格式：价格使用数字格式（"$"#,##0.00），确保在 Excel 中是真正的数字而非文本
• 图片顶部裁剪：裁掉 100px 编码水印区
• 高清图片处理：自动去掉 _sum 缩略图后缀
• 性能：单张报价单生成（含 12 张网络图片）应在 60 秒内完成

发布前自检（必跑）

python scripts/smoke_test.py

通过标准：
- main.py --help 可执行
- search_csv 返回 JSON 且 status=ok
- generate_excel 成功生成 output/smoke_test_quote.xlsx

变更记录