出口食品行业外贸智能寻客源系统

一、技能定位

为脱水蔬菜（蒜/洋葱）出口企业提供从线索采集 → 真实性背调 → 匹配推荐 → 开发信 → 跟进闭环的完整流水线。所有产出强制携带溯源信息（原始 URL + 采集时间戳 + 溯源路径），保证任意一条字段都能反查回原始页面。

核心产品线（默认，可在 assets/company_profile.json 中修改）：
- 脱水蒜粒 Dehydrated Garlic Granules
- 蒜粉 Garlic Powder
- 洋葱粒 Dehydrated Onion Granules / Minced Onion
- 灭菌蒜粒 Sterilized Garlic Granules

一之二、我该什么时候用？（触发条件清单）

符合以下任意一条，就应使用本技能：
- [ ] 你是脱水蒜/洋葱制品出口企业，需要按目标市场批量挖掘海外买家
- [ ] 你想对找到的海外买家做公司真实性背调与可靠性评分
- [ ] 你需要把线索写入可溯源的客户知识库、计算产品匹配度并生成开发信
- [ || ] 你需要管理跟进看板或导出 Excel/Word 客户报告
- [ ] 你的需求命中关键词：「找海外客户 / 开发新市场 / 海关数据买家分析 / 客户背调 / 外贸线索」

不适用：非脱水蒜洋葱行业；希望零干预全自动（部分源需联网工具或人工补数据）；想绕过网络管理访问受限源（本技能不提供此类工具）。

> 遇到问题先查 references/faq.md（常见报错通俗解读 + 高频疑问），能省大量排查时间。

二、关键前置约束：无 VPN 环境（必读）

用户处于国内网络、没有 VPN。执行任何采集任务前，必须遵守以下原则，不得尝试搭建或使用任何绕过网络管理的工具。

本技能的合规解法是"三层通路"，详见 references/network_access.md：

执行流程：先跑 scripts/net_probe.py 探测各源连通性，自动生成"当前可用源清单"，采集器只调度可用源，不可用源降级为 L1/L3 替代方案并在报告中标注 source_degraded。

代理配置：scripts/collector.py 支持从 ~/.foodtrade/proxy.json 读取用户自备的合法代理（企业专线/云主机/商业采集 API 代理），并做轮换、限速、UA 池管理。技能不提供任何代理资源，仅提供接入位。若该文件不存在，自动以直连模式运行 L1+L2。

三、标准工作流

Step 0 初始化

python scripts/setup_workspace.py --workspace ./leadhunt
python scripts/net_probe.py --out ./leadhunt/available_sources.json

产出可用源清单。若用户首次使用，读取并确认 assets/company_profile.json 中的产品线、HS 编码、目标市场。

Step 1 主 Agent 任务拆分

调用 scripts/orchestrator.py plan 生成任务矩阵：区域 × 渠道 笛卡尔积，每个单元为一个子任务。

python scripts/orchestrator.py plan --regions NA,EU,SEA,ME,LATAM --channels search,linkedin,customs,b2b,expo,association --out ./leadhunt/plan.json

主 Agent 职责：任务拆分、子 Agent 分配、进度监控、去重合并、异常兜底。详细架构见 references/agent_architecture.md。

Step 2 多子 Agent 并行采集

python scripts/orchestrator.py run --plan ./leadhunt/plan.json --workers 6 --timeout 180 --retries 2

• 每个子 Agent 负责一个「渠道+区域」组合，互相隔离
• 失败重试 2 次（指数退避），连续失败触发熔断（circuit breaker）跳过该源
• 主 Agent 按 域名 + 公司名规范化 + 邮箱域 三重键去重合并；公司名归一化已剥离 Ltd/Inc/GmbH/شركة/مؤسسة 等中外法律后缀与 (Dubai) 类地点修饰，并额外生成"纯公司名模糊键"（不带国别），可跨国家合并同一实体（如 Al Foodex Ltd 与 Al Foodex (Dubai)）

重要：collector.py 内置的是采集框架与解析器，实际取数需要 CodeBuddy 在运行时配合联网工具（web_search / web_fetch）或用户配置的商业 API。对于本地无法直连的源，脚本会输出待抓取的 query_manifest.json，由主 Agent 用联网工具逐条执行后回填 —— 这是无 VPN 环境下的核心取数方式，详见 references/collection_playbook.md。

Step 3 背调与可靠性评分

python scripts/due_diligence.py --input ./leadhunt/raw_leads.json --out ./leadhunt/verified_leads.json

7 大维度加权算出 0-100 分，输出状态标签：已验证 / 待验证 / 高风险 / 已失效。评分规则与维度权重见 references/due_diligence_rubric.md。

> D4 信用维度说明（设计内"需人工补数据"）：免费合规渠道无法获取企业信用，故 D4 默认返回基础分（0.4）并透明标注"需人工补数据"。进入洽谈阶段后，可接入 中信保(SINOSURE)/邓白氏(D&B) 付费 L3 API，将结果回填到线索的 credit 字段：{"rating":..,"score":..,"l3_source":"sinosure|dnb","l3_report_id":..,"source_url":..}，score_d4() 会优先采用 score（0-100）或 rating 文本评级自动映射分值。脚本只提供字段适配与读取接口，不内置任何付费凭证。

Step 4 写入 RAG 向量知识库

python scripts/rag_store.py upsert --input ./leadhunt/verified_leads.json --db ./leadhunt/vector_db
python scripts/rag_store.py query --db ./leadhunt/vector_db --q "德国 有机认证 蒜粉 进口商" --topk 10

强制字段：source_url、collected_at、trace_path、expires_at。超过 staleness_days（默认 180 天）自动打 stale=true。

Step 5 智能匹配与开发信

python scripts/match_engine.py --leads ./leadhunt/verified_leads.json --profile assets/company_profile.json --out ./leadhunt/matched.json
python scripts/outreach_writer.py --input ./leadhunt/matched.json --top 20 --lang en --out ./leadhunt/emails/

支持 --lang auto|en|es|pt|ar：自动按国别/区域选语言，auto 下北美/欧盟用英文、拉美用西语（巴西葡语）、中东用阿拉伯语（ar）。中东买家开发信自动强调 Halal 认证，并采用尊重式问候（用姓）。

匹配度 = 产品重合度 40% + 采购历史契合 25% + 市场准入匹配 15% + 规模匹配 10% + 认证匹配 10%。

### Step 6 跟进看板
```bash
python scripts/pipeline_board.py init --db ./leadhunt/pipeline.db --import ./leadhunt/matched.json
python scripts/pipeline_board.py set --id LEAD-0007 --stage 洽谈中 --note "已发样品" --next 2026-08-15
python scripts/pipeline_board.py due --within 7          # 未来7天待跟进
python scripts/pipeline_board.py render --out ./leadhunt/board.html

状态机：新线索 → 已联系 → 洽谈中 → 已成交 / 已放弃。

Step 7 导出

python scripts/exporter.py excel --input ./leadhunt/matched.json --out ./leadhunt/客户线索.xlsx
python scripts/exporter.py word  --input ./leadhunt/matched.json --top 30 --out ./leadhunt/背调报告.docx

Excel 含冻结首行、自动筛选、按可靠性评分降序、超链接溯源列。

Step 7.5 多源补源（强烈推荐：让每条线索来源更多、更真实）

背调可靠性高度依赖来源数量与交叉验证。采集初轮往往只产出 1 个弱源（D 级），
会触发 single_weak_source(-8) 重扣。补源环节会针对每家已知公司，从官网、
海关提单、B2B/目录、行业协会、LinkedIn、区域黄页等 6 类渠道主动二次检索，
把新来源 merge 进 sources，使背调可触发 cross_source_corroboration 正向加成。

# 1) 生成补源检索清单（基于已采集线索的真实公司名/国家，绝不虚构 URL）
python scripts/collector.py enrich --input ./leadhunt/raw_leads.json --manifest ./leadhunt/enrich_manifest.json

# 2) 主 Agent 按清单用 web_search/web_fetch 真实取数，写回 enrich_results.json：
#    {"results":[{"lead_id":"LEAD-0001","channel":"customs","tier":"A",
#                 "items":[{"url":...,"snippet":...,"collected_at":"ISO时间"}]}]}

# 3) 合并新来源并去重，回填到线索文件
python scripts/enrich.py --input ./leadhunt/raw_leads.json --apply ./leadhunt/enrich_results.json --out ./leadhunt/raw_leads.json

# 4) 重新背调（此时 source_count 上升，交叉验证加成生效）
python scripts/due_diligence.py --input ./leadhunt/raw_leads.json --out ./leadhunt/scored.json

> 真实性纪律：补源检索式全部基于已采集到的真实公司名/国家构造；主 Agent 必须用
> 真实 web 工具取数才能产生真实 source。missing_traceability 护栏（缺 url/时间上限 40）
> 依然生效，确保不会出现无溯源的"幽灵来源"。详见 references/faq.md 的「Q7：如何做到来源多且真实？」。

Step 2.5 网络不可达 → 境内中转源降级（关键）

很多境外源（Google、部分海关站、个别 B2B 站）境内不可达，是"采集少、信息缺"的根因。
先走境内中转源，再真实取数，而不是空跑或退而求其次只取一个弱源：

• enrich.py --manifest 输出的 JSON 自带 relay_hint 字段，列明各渠道的境内替代源。
• 当某渠道超时/被墙，调用 FallbackRelay().fallback(channel, country, query)：
• search → 必应国际版 / 搜狗 / Yandex（检索式不变，仅换工具）
• customs → 国内落地海关数据（外贸邦/贸管家，需自备 Key）→ Volza 公开页
• b2b → TradeKey / Go4WorldBusiness；expo/association → 搜索引擎找公开名录 PDF
• 官方开放 API（UN Comtrade、EU Eurostat，境内直连）用于市场规模排序，不产出企业名。
• 底线：中转只换通道，绝不虚构数据；降级源打 source_fallback=True 透明溯源。详见 references/data_sources.md §8。

Step 2.6 背调字段补全（修复"信息不全"）

补源阶段除"多源交叉"外，还会针对每条线索缺失的背调字段生成专门检索式
（build_dd_enrich_queries 覆盖：联系人邮箱/电话/姓名、注册号、成立年份、员工规模、
社媒主页、官网）。主 Agent 取回后按 target 字段回填：

{"lead_id":"LEAD-0001","items":[
   {"target":"contacts.email","value":"buyer@acme.com","collected_at":"ISO时间"},
   {"target":"registration","value":"REG-12345"},
   {"target":"online_presence","value":"https://linkedin.com/company/acme"},
   {"target":"founded_year","value":2009}
]}

enrich.py --apply 会把上述结果写入 contacts/registration/online_presence/founded_year
等 schema 字段，使 D1/D2/D6/D7 维度不再 not_found，背调从"待验证"升级为"已验证"。

Step 8 定期自动更新

方式 A：生成可被 IDE 真正定时的自动化描述（推荐）

# 直接生成可导入 CodeBuddy automation_update 的 JSON 描述（含 RRULE）
python scripts/scheduler.py automation --root ./leadhunt \
    --cron "FREQ=WEEKLY;BYDAY=MO;BYHOUR=9" --name "外贸寻客源-周更"
# 然后在 IDE 用 automation_update 工具加载该 automation.json 即可真正周期性运行

方式 B：生成系统级定时任务片段（cron / 计划任务）

python scripts/scheduler.py create --root ./leadhunt \
    --cron "FREQ=WEEKLY;BYDAY=MO;BYHOUR=9" --name weekly-refresh
# 把输出的 snippet 注册到 crontab / Windows 任务计划程序，调用 scheduler.py refresh

> ⚠️ 说明：create/automation 生成的都是调度描述，真正的执行靠 refresh 子命令
> （重新探测连通性 → 采集 → 解析 → 背调 → 匹配 → 入库 → 同步看板 → 重新导出，且保留人工跟进状态）。
> --cron 与 --freq/--at 二选一；automation 子命令比手填 automation_update 更快捷。
详见 references/faq.md 的「Q2：定时自动更新怎么真正跑起来？」。

四、资源索引

五、执行纪律

1. 溯源不可省略：任何一条线索若缺 source_url 或 collected_at，due_diligence.py 直接判为「待验证」且评分上限 40。
2. 不编造数据：无法核实的字段填 null 并在 evidence 中写明 not_found，严禁用模型知识虚构公司名、邮箱、贸易量。
3. 合规采集：遵守 robots.txt 与各平台 ToS；仅采集公开可见的企业级商务联系方式，不采集个人隐私数据（符合 GDPR 合法商业利益原则）。LinkedIn 只取公开企业页与公开职位信息。
4. 限速：默认单域名 QPS ≤ 0.5，随机延迟 2-6 秒，并发 ≤ 6。
5. 失败透明：熔断/降级/超时都要写进 run_report.json 并在最终交付中告知用户哪些源没跑通。

```