硕软·跨境电商利润测算

概述

硕软·跨境利润与定价测算（v1.1.3）

环境依赖（首次使用 30 秒：先跑环境自检）

导出脚本依赖 Python 包 openpyxl（Excel）与 python-docx（Word 报告），两者缺一不可。首次使用先跑：

python scripts/check_env.py

• 输出「环境就绪」→ 直接开工，以后不用再跑
• 报缺依赖 → 按提示装（国内镜像，装进 venv 别装系统全局）：

   pip install openpyxl python-docx -i https://pypi.tuna.tsinghua.edu.cn/simple

• 没有 venv 时先建（禁止装到系统全局）：

   python -m venv <python目录>/envs/default
   <python目录>/envs/default/Scripts/pip install openpyxl python-docx -i https://pypi.tuna.tsinghua.edu.cn/simple

• 自检退出码 1 时不抛 traceback，照着给出来的命令补齐即可

自测（环境就绪后 30 秒验证全链路）

python scripts/export_excel.py --input examples/sample.json --output test.xlsx
python scripts/export_report.py --input examples/sample.json --output test.docx

两个都 exit 0 即环境就绪；examples/sample-output.md 是对照样例（Excel 结论：净利 ¥84.00 / 净利率 58.4% 🟢）。

Overview

跨境电商利润与定价测算工具：输入售价、采购成本、头程物流、平台费率、VAT、退货率、广告占比等参数，产出双件套交付物——公式联动的 Excel 盈亏模型（改参数即自动重算）+ 一页 Word 决策报告（拿结论/转发用）。支持单品深度模型与多品对比排名两种模式。

架构决策（设计即确定，不再询问用户）：

• 纯计算型零依赖：所有成本参数由用户提供或按内置参考表取默认值，不联网检索、不用任何付费工具、不需要 API key。用户给的数据永远优先于参考表。
• 公式联动是核心价值：Excel 里不是死数字，而是 =售价-成本-... 的活公式。用户改任意输入，毛利/净利/保本价全部自动重算。
• 货币与汇率：成本端人民币（¥）、售价端目的地货币（$/€/£ 等），汇率作为输入参数由用户给定或取默认值，所有换算过程在表中可见。

盈亏模型（skill 的核心资产，公式固定）

计算链（从售价到净利，逐行瀑布）

以下序号即 Excel 计算区的行序。佣金模式（Amazon/TikTok Shop/独立站）：

全托管/半托管模式（Temu/Shein 核销制）：平台给核价，卖家的账简化为——净利 = 核价供货价(¥人民币直填，不乘汇率) − 采购成本 − 头程 − 其他；无佣金/VAT/广告/退货项（由平台承担），但需加「售后罚款扣款」经验项（默认 1%–3% 供货价）。核价按平台核价页面的人民币金额直填（Temu/Shein 核价口径本来就是人民币），模型不做汇率换算。模型自动切换口径，并在表中注明模式。

保本与定价反推

• 保本售价 = 使净利 = 0 的售价：保本售价 = (固定成本部分) ÷ (1 − 佣金率 − VAT率 − 广告占比 − 退货损耗系数)
• 目标净利率反推定价：目标售价 = (采购+头程+履约+其他) ÷ (1 − 佣金率 − VAT率 − 广告占比 − 退货损耗系数 − 目标净利率)
• 保本 ACOS（广告占比上限）= 净利率(不含广告) ÷ 1，即当前定价下不亏损能承受的最大广告占比。
• 可降价空间（安全边际）= 1 − 保本售价 ÷ 当前售价，即售价还能降多少仍不亏——比保本价更直观的定价安全垫指标，进 Excel 结论区与 Word 报告定价锚。

评分口径（结论灯）

（全托管模式阈值下调 5 个百分点：≥20% 绿 / 12%–20% 黄 / 6%–12% 橙 / <6% 红——核销制无广告退货敞口，合理利润带下移。）

工作流程

第 0 步：首次调用引导（开场必做）

skill 被触发后的第一次交互，判定规则：用户消息中已含「售价 + 采购成本」两项 → 跳过引导直接进第 1 步建模；缺任何一项 → 先输出引导卡（下方模板，按用户已给信息裁剪，已提供的项不再问）：

【跨境利润测算 · 使用引导】
帮你算清楚一件商品卖到海外到底赚多少。产出两件东西：
▸ Excel 盈亏模型——公式联动，改参数自动重算，可以自己反复调
▸ 一页决策报告（Word）——结论、保本线、风险敏感点、行动建议

需要你提供（缺的我会用行业默认值并明确标注，之后随时可改）：
✅ 必需（缺了算不了）：
  1. 售价（外币）——计划卖多少钱
  2. 采购成本（¥/件）——1688/工厂拿货价
📋 常用（不给就用默认，报告中标注为估算）：
  3. 平台与市场——默认 Amazon 美国站
  4. 头程物流 ¥/件——不给就按体积重估算（需包装尺寸重量）
  5. 佣金率 / 履约费——默认按平台费率参考表
  6. 退货率 / 广告占比——默认按类目经验值
  7. 汇率——默认 7.2，请核实
💡 最省事：一句话甩过来，如「保温杯，美国 Amazon 卖 $19.99，采购 ¥12.5」——其余全用默认值直接跑。
📦 批量对比：一次给多个商品也行（每个品至少有售价+采购成本），出多品对比表按净利率排序。
🔧 首次使用先跑一次环境自检：python scripts/check_env.py（30 秒，报缺什么按提示装什么）。
❓ 遇到报错先看下方「常见问题 FAQ」，多数报错在里面能直接对上。

语气规则：引导卡只发一次；用户第二轮还没给全必需项，只提醒缺的具体项，不重发整卡。

第 1 步：参数收集（一次问全，不挤牙膏）

从用户消息推断，只把缺失项一次性列出提问。用户给的数据永远优先于参考表默认值：

全托管模式跳过 7–11，只问核价供货价（人民币）与售后扣款率；汇率参数不参与托管模式计算。

参数齐全判定：售价、采购成本两项缺失任何一项都无法建模——只问这两项，其余全部走默认并标注「默认值，可在表中修改」。

缺参降级路径（每项都有兜底，绝不卡死）：

降级纪律：① 每个走默认值的参数，在对话摘要与报告中列「估算参数清单」；② 低置信度估算叠加 ≥3 项时，结论灯降一档显示（绿→黄）并注明「多参数估算叠加，建议补真实数据复核」；③ 报告行动建议里必须有一条「把估算参数换成真实数据的获取路径」（如去后台拉 FBA 费用预览、用官方收入计算器核一次）。

第 2 步：计算与结论（先在对话中给核心结论）

按盈亏模型公式手工计算一遍（脚本负责 Excel，结论由 AI 算），在对话中给出 3–5 行摘要：单件净利、净利率、结论灯、1–2 个最敏感因素（如「退货率每 +5pct，净利率 −3.2pct」）。不贴长表，细节全在 Excel。

第 3 步：Excel 导出

参数由我整理成内部 JSON（你不需要写、也不会看到它），然后运行：

python scripts/export_excel.py --input result.json --output 利润测算_<平台>_<商品>_<日期>.xlsx

JSON schema（脚本唯一入口）：

{
  "meta": {
    "platform": "Amazon", "market": "美国", "mode": "commission",
    "currency_sell": "USD", "currency_cost": "CNY", "exchange_rate": 7.2,
    "product": "保温杯 500ml", "calc_date": "2026-10-20"
  },
  "params": {
    "price": 19.99, "purchase": 12.5, "first_leg": 3.8, "fulfillment": 4.2,
    "commission_rate": 0.15, "vat_rate": 0.0, "ad_rate": 0.10,
    "return_rate": 0.08, "resalable_rate": 0.80, "other": 0.5
  },
  "scenarios": [
    { "label": "低价档", "price": 16.99 },
    { "label": "中档", "price": 19.99 },
    { "label": "高价档", "price": 22.99 }
  ],
  "platforms": [
    { "platform": "Amazon", "price": 19.99, "commission_rate": 0.15, "fulfillment": 4.2, "ad_rate": 0.10, "return_rate": 0.08, "vat_rate": 0.0 },
    { "platform": "TikTok Shop", "price": 19.99, "commission_rate": 0.06, "fulfillment": 3.5, "ad_rate": 0.12, "return_rate": 0.12, "vat_rate": 0.0 },
    { "platform": "Temu全托管", "mode": "hosting", "hosting_price": 28.0, "return_penalty_rate": 0.02 }
  ],
  "sensitivity": { "ad_rate": [0.05, 0.10, 0.15], "return_rate": [0.05, 0.08, 0.12] },
  "assumptions": [
    { "key": "first_leg", "source": "default", "note": "体积重估算" },
    { "key": "return_rate", "source": "user", "note": "" }
  ],
  "verdict": "健康，可推进",
  "advice": ["控广告占比 ≤10%", "退货率压到 8% 以内", "批量拿货谈采购价"]
}

（sensitivity 为 JSON 键；模式 commission 佣金制 / hosting 全托管。多平台条目缺的参数继承主 params。assumptions 标注关键参数来源 user/default；verdict 为 AI 一句话判定；advice 为行动建议数组——三者供报告脚本使用，缺省时报告相应栏位省略。）

多品对比模式（用户一次给多个商品时触发）

路由规则：JSON 有 products 数组 → 双脚本自动切多品模式；无 → 单品模式（前述四 sheet）。用户消息含 ≥2 个商品（各自有售价/成本）即应走多品。

多品 JSON schema（字段与单品 params 同名，每品独立，可混合模式）：

{
  "meta": { "market": "美国", "mode": "multi", "currency_sell": "USD", "exchange_rate": 7.2, "calc_date": "2026-10-20" },
  "products": [
    { "name": "保温杯 500ml", "platform": "Amazon", "mode": "commission",
      "price": 19.99, "fx": 7.2, "purchase": 12.5, "first_leg": 3.8, "fulfillment": 4.2,
      "commission_rate": 0.15, "vat_rate": 0.0, "ad_rate": 0.10,
      "return_rate": 0.08, "resalable_rate": 0.8, "other": 0.5, "verdict": "成本结构健康，主推" },
    { "name": "收纳盒三件套", "platform": "Temu", "mode": "hosting",
      "price": 26.0, "purchase": 18.5, "first_leg": 2.8,
      "penalty": 0.02, "other": 0.4, "verdict": "核价偏紧，需重谈" }
  ],
  "verdict": "整体一句话结论",
  "advice": ["优先推进 XX", "YY 重谈采购价"]
}

多品交付物：

• Excel「多品对比」单 sheet：每行一品（22 列），行内参数黄格可改，净利/净利率/保本售价公式联动（模式列「佣金/托管」驱动 IF 公式，混合平台同表可比）；净利率列四档灯。
• Word 多品报告：汇总对比表（按净利率降序，灯色着色）→ 排序结论（最优/最弱/红绿灯统计）→ 逐品速览卡（净利率+净利+一句话判定）→ 行动建议 → 口径声明。

多品纪律：① 每品至少有售价+采购成本，缺的项按单品降级路径走默认并在 verdict 里注明；② 排序只按净利率，但结论必须同时提绝对净利（高利率低单价的陷阱）；③ 品数 ≤20（Excel 一屏内），更多建议分批；④ 托管品 price 填核价人民币（无 fx 字段），佣金品 price 填外币 + fx。

Excel 结构（四个 sheet）：

• Sheet1「参数与结论」：左侧参数区（黄色底输入单元格，用户可改）、右侧结论区（净利/净利率/保本价/目标价反推，公式引用参数区——用户改参数，结论即时重算）。
• Sheet2「盈亏瀑布」：从售价到净利的逐行瀑布（公式联动），每行标注「输入项/公式项」与口径说明，末行结论灯着色。
• Sheet3「价位与平台对比」：上半 3 档价位对比（每档净利与净利率，公式联动），下半多平台对比（同商品不同平台的费率与净利）。
• Sheet4「敏感性分析」：广告占比 × 退货率 双因子矩阵，每格净利率并按四档灯色着色；矩阵下方一句话结论（如「广告 >12% 且退货 >10% 时净利率跌破 8%」）。

第 4 步：报告生成（计算完成后默认顺带做，单独询问成本高）

Excel 落盘后无需再问用户，直接运行报告脚本（读同一个 JSON，数字由脚本按同一套公式计算，保证与 Excel 一致）：

python scripts/export_report.py --input result.json --output 利润报告_<平台>_<商品>_<日期>.docx

报告结构（一页决策报告，Word）：

1. 报告头：商品/平台/市场/测算日期/模式
2. 结论卡：结论灯（🟢🟡🟠🔴）+ 一句话判定（verdict）+ 核心四数（到手售价/总成本/单件净利/净利率）
3. 盈亏明细表：瀑布各行金额与占比（脚本计算，与 Excel 公式同源）
4. 保本与定价锚：保本售价、保本 ACOS、目标净利率反推价（基准 15% 目标）、毛利率（不含广告）、可降价空间（安全边际）
5. 估算参数清单（assumptions 中 source=default 的项）：每项列「参数名 → 用的默认值 → 怎么拿到真实值」，没有则整节省略
6. 行动建议（advice 数组逐条 + 兜底一条「把估算参数换成真实数据的获取路径」）
7. 口径声明（一字不差，同第 5 步）

双脚本出双交付物的成本约等于单出 Excel，报告是顺带的，不要把它做成可选项——用户拿到报告才拿得到结论，Excel 是给自己调参用的。

第 5 步：交付与口径声明

交付物两件套：

• 单品：利润测算_<平台>_<商品>_<日期>.xlsx（四 sheet 模型）+ 利润报告_<平台>_<商品>_<日期>.docx（一页决策报告）
• 多品：多品对比_<市场>_<日期>.xlsx（对比总表）+ 多品报告_<市场>_<日期>.docx（汇总报告）

对话中只给 3–5 行结论摘要（净利/净利率/结论灯/最敏感因素）+ 两件交付物路径，不重复表内数字。

口径声明（写入报告表尾，对话摘要中提醒，一字不差）：

本模型为测算工具，费率与经验参数（退货率/广告占比/汇率）以输入与标注默认值为准，非平台实时数据。FBA 费档、佣金率以平台最新官方口径为准，重大决策前请以平台后台实际扣费复核。

references/fba-fee-reference.md 使用规范

Amazon FBA 履约费按【尺寸分档 × 重量档】查表（美国站）。规则：

1. 用户给了商品包装尺寸与重量 → 直接查表取档。
2. 未给 → 先问；给不出时用「标准件小号档」估算并标注「低置信度」。
3. 表为 2026 年初公开口径，FBA 费用估算均标注「以官方收入计算器为准」；这里用的是公开费率表，跟你后台实际扣费可能有几块钱差异，差得多就以后台为准改黄格。
4. 单个商品超过 20kg，或者最长边超过 1.2 米，这里不估算运费——找货代报个价，填进头程那一格更准。

常见问题 FAQ（报错先查这里）

每条按「现象 → 原因 → 怎么办」读。

1. Excel 里公式显示 0 / #DIV/0! / 空白→ 原因：v1.1 起脚本会拦下会算出 #DIV/0! 的输入，自己打开后出现说明是手动改了黄格——比如把售价改成 0，或把费率改到合计 100%。→ 怎么办：把对应黄格改回正常值即恢复；#DIV/0! 出现在「保本售价」一行就是费率合计扣满了，把佣金/VAT/广告至少一项降下来。

2. 报告里少了「保本与定价锚」或「估算参数清单」一节→ 原因：按条件省略，不是漏做——「估算参数清单」只在 assumptions 里存在 default 来源参数时出现（你给的参数全就整节省略）；「保本与定价锚」只在全托管模式没有——托管没有「保本售价」这个概念，核价是平台给的，改看「核价反推」那一块。→ 怎么办：想让清单出现，把走了默认值的参数在 assumptions 里标 source=default；不需要就不用管。

3. 大件商品算不准→ 原因：单个商品超过 20kg 或最长边超过 1.2 米，模型不硬估运费（大件费档跳档太陡，估了反而误导）。→ 怎么办：找货代要个实价，按公斤或整箱折成单件成本填进头程那一格。→ 怎么办：去平台官方收入计算器查真实履约费，填进「尾程履约费」格，模型按你填的数算；头程同理，给货代报价单的实数，别用体积重估。

4. 汇率该填多少、哪里查→ 原因：模型不联网，汇率是输入参数不是预测。→ 怎么办：用你的收款工具（连连/万里汇/Payoneer）后台看当日结算价，那是你真正能拿到的数；没有就先填 7.2 跑一版，结论只看趋势别拍板。

5. 多品对比里某一行判不了/没颜色→ 原因：该品缺售价或采购成本之外的关键参数，或参数组合解不出保本价。→ 怎么办：看该行黄格哪项异常（0/空/费率合计超限），补齐后净利率列自动出灯色。

6. 平台费率与实际扣费对不上→ 原因：模型用的是公开口径费率表，平台随时调整且类目子类有例外，跟你后台实际扣费差几块钱是正常的。→ 怎么办：差得多就以后台实际扣费为准，改 Excel 对应黄格（佣金率/履约费），全表自动重算。

7. 想改口径（广告占比按 ACOS 还是按销售额）→ 原因：模型默认广告占比 = ACOS 口径（广告花费÷销售额）。→ 怎么办：如果你按「广告费÷回款」口径记账，把广告占比黄格按你的口径直接改数即可，公式结构不变。

8. 托管模式的核价为什么填人民币→ 原因：Temu/Shein 全托管的核价本来就是平台按人民币给的供货价，不是外币售价，乘汇率反而错。→ 怎么办：从平台核价页面把人民币金额原样填进「售价/核价」格，模型自动按托管口径算，不碰汇率。

9. 三个平台之外想加平台→ 原因：模型不绑定具体平台，平台名只是标注；算什么平台取决于你填什么费率。→ 怎么办：改参数表即可，不需要改脚本——新平台的佣金率/履约费按该平台后台实际口径填黄格。

10. 报告能不能直接发给老板 / 能不能改 Excel 后重算→ 原因：Word 报告数字与 Excel 公式同源（同一 JSON 同一套公式），一页决策报告就是给转发用的。→ 怎么办：报告可以直接发；要调参就在 Excel 里改黄格，净利/净利率/保本价即时重算——改完想同步报告，改 JSON 重跑一次 export_report.py。

11. 金额/净利率和别的工具算出来不一样→ 原因：口径差异——本模型退货损耗按「售价不可售损失+物流沉没」上限口径估，比按成本口径的工具偏保守。→ 怎么办：以自己后台真实退货损耗为准改退货率/可售率黄格，模型口径可在参数区调。

12. 我需要懂 JSON 才能用吗？→ 不需要。一句话说出商品、售价和采购价即可，参数由我整理；JSON 是脚本间的中间格式，出问题我替你改。

报错关键词对照表

边界与注意事项

• 不承诺收益：测算是决策支持，不构成投资建议；避免「稳赚」「必爆」表述。
• 不做税务建议：VAT/销售税口径复杂（欧洲低税率、美国各州差异），模型只按用户给定税率计算，声明「税务口径请咨询专业税务师」。
• 汇率风险：汇率是输入参数不是预测，提醒用户结算汇率与购汇成本有差。
• 平台规则时效：费率随时调整，表内费率标注口径日期；skill 不联网，不主动获取「实时费率」。
• 退货模型是简化口径：实际退货涉及平台退货处理费、二次销售折价，模型按「不可售损失+物流沉没」简化，参数区可调。