技术架构说明 · 两个选品技能

读者：技术同事、客户 IT 验收人基线：2026-10-13 实测代码。所有文件清单与调用关系均从源码提取。 不用于培训课件 —— 课件面向运营，只讲方法论。

一、两个技能的分工

text

                    用户说「帮我分析 DE 站的瑜伽垫」
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
    market-trend-judge              amazon-product-selection
    ─────────────────               ──────────────────────
    「这个方向是涨还是跌？」         「该选哪个品？」
              │                               │
    三腿数据 + 判定卡                六步漏斗 + 选品报告

边界：前者回答方向（方法论），后者回答选品（工程漏斗）。两者数据源共享，都走 LinkFox 网关。

二、market-trend-judge 2.1 目录结构

text

market-trend-judge/
├── SKILL.md                      方法层：四步流程 + 红线 + 输出契约
├── 新手上手指南.md / .html        用户手册（面向运营）
├── scripts/                12 个文件
├── references/
│   ├── data-sources.md          数据源口径
│   └── troubleshooting.md       排障手册
├── assets/判定卡.xlsx
├── examples/                    demo_report.tsv / demo_series.json
└── docs/                        方案与设计文档

2.2 脚本职责

脚本	职责
`orchestrate.py`	编排入口：一次调用跑完翻译 → 三腿数据 → 判定卡
`keyword_translator.py`	中文关键词 → 站点语言主词（LLM 翻译 + ABA 仲裁）
`fetch_market.py`	市场侧：Google Trends 序列
`fetch_own.py`	自有侧：店铺报表 → ASIN 月度真实销量
`fetch_third.py`	第三方：Sorftime / Keepa（含 parentAsin 去重）
`judge.py`	计算层：方向标签 + 置信度（红线执行者）
`card.py`	输出层：判定卡 md + xlsx
`mtj_common.py`	公共层：阈值常量 / 落盘 / 周降采样
`check_env.py`	自检：授权 / 依赖 / 网关连通
`md2html_guide.py`	手册渲染
`test_keyword_translation.py`	翻译层回归测试（44 项）
`verify_guide.py`	手册一致性校验（33 项）

2.3 编排流程

text

入口屏（摊开成本：0 + 6 算力 + 0 积分）
   │
   ├─ [0/3] resolve_keyword()      翻译中文 → 站点语言；失败则停下问用户
   │
   ├─ [1/3] leg_own_sales()       店铺真实销量（0 算力，SP-API 报表，约 45s）
   │        └─ 受限速约束，串行等待
   │
   ├─ [2/3] leg_market_trend()    Google Trends（6 算力）
   │        └─ 判定方向：末端 3 点均值 vs 全序列均值
   │
   ├─ 决策闸                结论清晰 → 结束（默认不花钱）
   │        └─ 否则付费精修（2 积分/ASIN）或扩候选（≤3 搜索积分）
   │
   └─ 判定卡                        merge_evidence() 合并多路

成本闸设计：第 1 轮固定 6 算力；第 2、3 轮必须经「决策闸」显式确认才花钱。

2.4 判定口径（judge.py:8-17）

python

1) 有效点 < 6                          → 未采集（样本不足）
2) 全序列均值 ≤ 0（全 0/全缺）          → 未采集（无数据）
3) 序列极差 = 0（常量，含恒 5 默认填充） → 未采集（无变化）
4) 末端 3 点均值 > 全序列均值 × 1.10   → 升
5) 末端 3 点均值 < 全序列均值 × 0.90   → 降
6) 其余                                → 平
日粒度（≥20 点）先按 7 点窗口周降采样再判定。
置信度：高 = 点数≥8 且 CV≤0.25；中 = 点数≥5 且 CV≤0.50；其余低。

对应常量（mtj_common.py:13-16）：

python

MIN_POINTS = 6      # 有效点少于 6 → 未采集
THRESHOLD_UP = 1.10
THRESHOLD_DOWN = 0.90

红线 3 的由来：第三方 API（Sorftime）在低销量产品上会统一填充常量 5。若不识别，会把「没数据」误判为「平稳」——这是最危险的一类错误。

2.5 关键词翻译的仲裁机制

text

中文输入
  ↓ LLM 翻译（Agent API，约 20s）
得到多个候选译词
  ↓ ABA 搜索频率仲裁（Amazon 真实搜索量排名）
  │
  ├─ 候选差距 ≥ 3.0x  → 自动选 rank 最优者，标注 rank_gap
  ├─ 候选差距 < 3.0x   → 不裁定，列出候选交用户选（too_close）
  ├─ ABA 不支持该站点（UK/IN）→ 标「未校验」，不阻断
  └─ ABA 无记录        → 标「前台无搜索记录」，提示可能臆造词

降级链：翻译失败 → 落 i18n_pending.json + 停下问用户，绝不拿中文硬查。

2.6 环境变量（两处拼写差异）

脚本	读取
`linkfox_client.py:25`（翻译链路上游）	只读 `LINKFOXAGENT_API_KEY`（无 AGENT 前置下划线）
`check_env.py` / `fetch_third.py` / `amazon_search.py`	`LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY`，带下划线的优先

⚠ 只配带下划线的版本会导致：其他腿正常、翻译单独失败。 test_keyword_translation.py 有断言锁定这条。

三、amazon-product-selection 3.1 脚本分层（21 个）

分层	脚本
编排	`orchestrator.py`（六步合并成报告）、`run_live.py`、`run_live_multi.py`
Step1 硬约束筛选	`step1_screening.py`、`merge_and_screen.py`
Step2 市场评估	`step2_market.py`（多站点红黄绿灯）、`step2_manual_eval.py`（极目数据）
Step3 需求/趋势	`step3_demand.py`、`step3_seasonality_v2.py`
Step4 利润	`step4_profit_engine.py`（多站点本币售价→毛利）
Step5 专利风险	`step5_patent.py`（多层级评估）
Step6 报告	`step6_report_gen.py`（MD + JSON + HTML）
数据接入	`linkfox_mapper.py`（响应 → 扁平结构）、`io_utils.py`、`keyword_expander.py`、`image_fusion.py`
辅助	`catalog.py`（十站点类目树）、`category_select.py`、`find_category.py`（卖家精灵查节点）、`fba_calculator.py`、`export_excel.py`

3.2 调用链

text

orchestrator.py
   ├─ step1_screening     → 硬约束筛选
   ├─ step2_market        → 市场分层与红黄绿灯
   ├─ step3_demand        → 需求/趋势/流量可行性 + 季节性
   ├─ step4_profit_engine → 毛利测算
   ├─ step5_patent        → 专利风险
   ├─ step6_report_gen    → 最终报告（MD/JSON/HTML）
   └─ io_utils            → 统一 I/O

六步顺序依赖：Step4 需要 Step2 的售价档位，Step6 汇总全部前序结果。

3.3 站点配置

references/site_configs.json + 10 套 FBA 费率表（fba_fee_{de,fr,es,it,jp,mx,uk,us,ca,in}.json，

低客单价另有 *_lowprice 变体）+ vat_config.json 税率表。

工程含义：定价与毛利必须按站点取表，不能用美区费率套其他站点。

四、两技能共享的工程约定

约定	说明
数据接入统一	一切外部数据经 `linkfox_mapper.py` 转成扁平 dict，step 脚本不直接解析原始响应
多站点显式	凡涉及金额/税率/费率的计算，站点代码是必填参数
产出双格式	报告同时出 MD（人读）与 JSON/HTML（机读），供后续环节消费
离线可跑	所有脚本支持 `--demo`，用内置示例数据走完整链路，供断网/教学/回归

五、质量保障

闸	覆盖	规模
`test_keyword_translation.py`	代码正确性	44 项
`verify_guide.py`	文档与实现一致	33 项

两个闸都经过变异测试验证有效性——把已修复的缺陷重新注入源码，确认测试会失败。

这是「测试全绿」不等于「测试有用」的必要检查。

六、给 IT 验收的三条命令

bash

cd ~/.workbuddy/skills/market-trend-judge

# 1. 环境自检（凭据 / 依赖 / 网关连通）
python3 scripts/check_env.py

# 2. 代码回归（44 项，零付费）
python3 scripts/test_keyword_translation.py

# 3. 手册一致性（33 项）
python3 scripts/verify_guide.py

预期：三项分别输出「全部通过」。

七、文档维护规则

规则	原因
代码变更后必须跑两个闸	「有数据却报未采集」这类缺陷只能靠回归测试拦
手册改动后必须 `verify_guide.py --fix`	自动重生成 HTML 并校验 33 项
架构文档以源码为准	不引用历史方案稿（文件清单会随实现漂移）
面向运营的内容不进本文件	本文件含文件名与版本号，运营不需要

相关文档：用户手册见 新手上手指南.md（面向运营），培训方案见 docs/培训/WorkBuddy实操方案-选品与市场趋势预测.md。