前言¶
外贸业务里，报价单往往要同时带上公司抬头、产品图、规格、MOQ 和美元单价。手工在 Excel 里排版、拉图、改格式，重复劳动多；通用表格工具也不会按「报价单」的版式自动套版。若产品来自本地 CSV，或上游 Agent 已从电商页抓出结构化数据，仍需要一条可复现的生成链路，把内存里的产品列表写成客户能直接打开的 .xlsx。
下面介绍 SkillHub 社区 Skill quotation-builder（坐标 @user_c72f7801/quotation-builder，版本 1.0.0）。它面向 Agent 工作流：检索本地产品库、按约定字段生成带 Logo 与图片的 Excel，并通过 rules/ 下的规则包扩展不同站点或客户的版式逻辑。页面标注 requires_api_key=false，不依赖额外 API Key。
这是什么¶
quotation-builder 是社区来源（community）的办公效率类 Skill，发布者为 user_c72f7801，SkillHub 分类为 office-efficiency。官方简介为：外贸报价单生成器，专业的 Excel 报价单生成工具，支持多规则包扩展，专为外贸行业设计。
Skill 本体基于通用 SKILL.md 约定：当用户提到「生成报价单」「quotation」「price list」等意图时，Agent 按文档调用包内 Python 入口（main.py），输出排版好的报价单文件。网页抓取不由本 Skill 直接完成；文档说明需配合 web-access 等抓取能力，再由本 Skill 负责 Excel 生成。
核心功能¶
以下能力均来自已发布的 SKILL.md 与包内脚本说明，可按需选用。
- search_csv：从本地 CSV 产品库按 SKU 精确或名称模糊检索产品。
- generate_excel：生成含公司信息区、表头与数据行的 Excel 报价单；支持嵌入产品图片；默认单列布局，并支持横向 3 列（每行 3 个产品）模式。
- 规则包扩展：在
rules/{rule-name}/下放置规则包；当前内置 dg-1688（1688.com），含横向 3 列、颜色×尺码组合、产品名称序号等逻辑；新规则包可通过新增目录及SKILL.md被加载。 - run_rule：通过主入口动态调用规则包，例如对 1688 商品详情 URL 生成专用版式报价单。
运行环境要求（Skill 文档 compatibility）：Python 3.10+，依赖 xlsxwriter、Pillow、requests、pandas。默认约定路径包括 ./data/local_products.csv 与 ./config/company.json。
安装与启用¶
通过 SkillHub CLI 安装¶
先确认本机是否已有 skillhub（安装方式见 SkillHub 安装文档）。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能无法被识别。
skillhub install quotation-builder --namespace user_c72f7801 --dir <你的 Agent skills 目录>
常见 Agent 的 skills 路径（同一文档中的说明）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
也可将下面提示交给支持 Skill 的 AI，让其按官方安装说明执行：
请根据 https://skillhub.cn/install/skillhub.md，安装 @user_c72f7801/quotation-builder。
Python 依赖¶
进入 Skill 解压目录后安装依赖，便于本地执行 main.py 或跑自检：
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
requirements.txt 中列为：xlsxwriter、Pillow、requests、pandas。
典型用法¶
1. 发布前自检¶
Skill 文档要求发布或接入前运行冒烟测试：
python scripts/smoke_test.py
通过标准包括：main.py --help 可执行、search_csv 返回 status=ok、generate_excel 在 output/ 下生成 smoke_test_quote.xlsx。
2. 从本地 CSV 生成报价单¶
先在 config/company.json 配置公司信息，在 data/local_products.csv 维护产品库，再分步调用：
python main.py --action search_csv --query "mouse"
python main.py --action generate_excel --output ./output/quote.xlsx
search_csv 可用 --csv 指定非默认 CSV 路径。
3. Agent 一体化 JSON 调用¶
适合在对话中由 Agent 构造产品列表与公司信息，单条命令生成文件：
python main.py --json '{"action":"generate_excel","products":[...],"company_info":{...}}'
产品字段需符合 ProductDict 约定（如 name、price 必填；image_url、specs、moq、remarks 等可选）。公司信息可参考 config/company.json 中的 CompanyInfo 字段（name、logo_path、website、contact_name、phone、whatsapp、email、address 等）。
4. 使用 dg-1688 规则包¶
对 1688 商品详情链接触发规则包（可传汇率等扩展参数）：
python main.py --action run_rule --rule dg-1688 --url "https://detail.1688.com/offer/xxx.html"
python main.py --action run_rule \
--rule dg-1688 \
--url "https://detail.1688.com/offer/xxx.html" \
--rule-params '{"fx":7.2}'
或在 Python 中：
from rules.dg_1688.build_quote_from_detail import build_quote
output = build_quote("https://detail.1688.com/offer/xxx.html", fx=7.2)
规则名支持 dg-1688 与 dg_1688 互通。
5. 与 web-access 协同的完整流程¶
文档给出的推荐链路如下：
- 用户给出抓取目标（例如 1688 链接）及加价、汇率等规则。
- Agent 使用 web-access 打开页面、滚动加载并
eval提取标题、价格、图片 URL。 - Agent 在内存中计算最终报价（含 markup、换汇），组装为 ProductDict 列表。
- 调用本 Skill 的
generate_excel（或--json模式）写出 Excel，将输出路径返回用户。
适用场景与注意¶
适合谁
- 外贸销售、跟单或运营，希望用 Agent 把「产品数据 → 标准报价单 Excel」固定成可重复步骤。
- 已有本地 CSV 产品库，需要按关键词检索后批量出单。
- 需要为特定客户维护独立规则包（如 dg-1688 的 3 列版式），而不改核心生成代码。
使用上需注意
- 本 Skill 不直接承担通用网页抓取；未安装或未调用 web-access 时，应走 CSV 或规则包已实现的入口，避免误以为任意 URL 都能一键出单。
- 公司信息缺失时
generate_excel会报错且不生成文件；图片下载失败会占位「No Image」并继续生成。 - Excel 版式、汇率公式（如 dg-1688 文档中的 CNY/USD 计算方式）以规则包与
SKILL.md为准，出单前建议用真实样品跑一遍smoke_test.py或小额数据试生成。 - SkillHub 页面统计（抓取时）：评分 100000，下载 1025，安装 26；数据随商店更新变化，引用时以页面为准。
结尾¶
quotation-builder 把外贸报价单从「表格手工排版」收敛为 Agent 可调用的 search_csv、generate_excel 与可扩展 rules/ 规则包，并明确与 web-access 的分工。若你要在 Cursor 或 Claude Code 里接入，可从 SkillHub 安装到对应 skills 目录，再按文档准备 company.json 与产品数据。
官方 Skill 页：https://www.skillhub.cn/skills/user_c72f7801/quotation-builder
API 坐标地址：https://api.skillhub.cn/user_c72f7801/quotation-builder
