CTctikki/taobao-tmall-top-merchants-skill

淘宝/天猫top商家清单

模式选择

• 类目发现模式：用户只提供商品类目并要求寻找优质商家时，执行淘宝候选发现、店铺商品结构审计和正式准入门槛。
• 用户指定名单模式：用户直接提供一个或多个店铺名、多个链接、文本、表格、电子表格或混合信息时，由Codex自行提取和去重，不要求固定文件格式或专用解析脚本。若输入同时含类目和明确店铺名单，以名单为准；只有用户明确要求扩充时才继续发现新店。

用户指定名单模式下，名单中的店铺全部进入正式招商商家，不运行 mine_taobao.py、audit_shops.py，也不为补企业字段触发淘宝页面。不得补造目标SPU、店内目标商品占比、付款人数展示下限或Top30结论；工作簿必须明确标注“用户指定名单，不代表Top30或主营准入达标”。若用户同时提供营业执照截图、资质页截图或执照文字，直接提取平台营业执照公司名和信用代码写入 platform_qualifications.json，不再按店铺名猜主体。

Codex应从原始信息中尽量归一化：类目、店铺名、平台、店铺链接、用户已提供的公司与联系方式、负责人和来源。保留原始输入用于追溯；缺少字段不淘汰店铺。平台只依据明确链接或可靠页面信号识别，无有效证据时写“待核验”，不得根据店名猜测。

输入

类目发现模式只要求用户确认一个商品类目。若用户既未指定类目也未提供店铺名单，询问一次；不要继续索要其可以从页面或公开数据推断的参数。

默认准入：目标SPU >=10、店内目标商品占比 >=30%；>=50% 标记“高匹配”。淘宝店/C店和天猫店使用同一门槛，店铺类型不是淘汰条件。

首次使用硬门槛

• 正式任务必须同时提供并验证成功 企查查 Key + 风鸟 Key，缺一不可；风鸟公共额度不能替代用户自己的 Key，爱企查、天眼查或其他企业 MCP 也不能替代指定的 qcc-company。
• 缺少任一 Key 时先停止任务，并同时给出企查查 https://agent.qcc.com/profile/api-key 与风鸟 https://www.riskbird.com/center/apiKey。请用户把两个 Key 一起发给 Codex，不要让用户自行配置环境变量。
• Codex 收到两个 Key 后不得复述。启动 python scripts/configure_enterprise_keys.py，只通过标准输入依次传入企查查 Key 和风鸟 Key，再运行 bootstrap.ps1；Key 禁止进入命令参数、日志、工作簿、文档、Git或最终回复。
• 预检必须实际验证两个服务，不能只看是否安装。任一 Key 无效、额度不足或服务不可用时拒绝继续招商任务。
• webcli 必须同时满足 connectivity.ok=true 且至少一个 profile 的 extensionConnected=true。未连接时运行 webcli extension install 下载扩展，并用小白步骤引导：在 Chrome 打开 chrome://extensions → 开启“开发者模式” → “加载已解压的扩展程序” → 选择 ~/.webcli/extension → 固定 Browser Bridge → 保持 Chrome 开启。不能因顶层 ok=true 就跳过连接检查。

执行顺序

以下第3至第7步仅用于类目发现模式。名单模式跳过第3至第7步，不运行 create_job.py、mine_taobao.py、audit_shops.py、audit_storefronts.py；完成输入归一化后直接执行企业候选核验和名单模式工作簿生成。名单模式没有标准采集任务JSON时，不强行运行 verify_job.py，但仍必须完成字段检查、公式重算、全表视觉检查和密钥扫描。

1. 先判断模式。类目发现模式运行 powershell -ExecutionPolicy Bypass -File scripts/bootstrap.ps1；用户指定名单模式运行同一脚本并加 -SkipTaobaoCheck，只验证工作簿和企业数据源环境，不打开淘宝页面。脚本通过 preflight.py --install-missing 检查并补齐必要依赖、风鸟 Skill、qcc-company 与 webcli 扩展；自动安装失败时停止并给出明确修复提示，不得跳过环境检查。
2. 只有 qcc-company 与风鸟 Skill 均已安装、两个用户私有 Key 均已配置且轻量验证成功，企业环境才算就绪。详见 references/mcp-setup.md。
3. 若淘宝未登录或出现验证码/滑块，打开淘宝并请用户完成登录；保持同一浏览器会话，恢复时复用缓存，禁止从头高频重跑。
4. 运行 scripts/create_job.py <类目>。检查生成的查询词、目标词和排除词；只在明显歧义时向用户确认商品边界。
5. 运行 scripts/mine_taobao.py 发现淘宝与天猫候选店铺。默认每个查询2页、间隔20秒，禁止并发轰炸。原始候选仅作发现证据，不等于后续审计队列。
6. 运行 scripts/audit_shops.py 按精确店铺名反查商品结构并执行30%门槛。默认按目标商品付款人数展示下限、发现目标SPU和查询覆盖排序，过滤低销量与综合渠道店，每类最多审计30家；不足30家不补低质量商家。店名含类目经营信号的低露出淘宝/C店仍可进入分层召回，避免平台排序偏差漏店。若用户明确要求“每类销量Top N”（如Top30），设置 sales_top_n_mode=true、max_candidate_shops=N、minimum_payment_lower_bound=0、minimum_quality_query_coverage=1：每个类目只按目标商品付款人数展示下限审计前N家，不把数百家原始发现候选全部送入后续流程；最终仍只保留满足SPU与占比门槛的优质商家。
7. 运行 scripts/audit_storefronts.py 取得正式店铺链接、shopId、sellerId 和店铺类型。天猫店必须在店铺头部悬停“查看资质”，打开“查看商家公示信息”对应的 liangzhao.htm，把营业执照公司名、统一社会信用代码、法人、地址、成立日期和证据URL写入 platform_qualifications.json；若该资质页触发滑块或 _____tmd__，记录“主体未确认”并等待人工验证，不得用企业搜索第一名代替。
8. 企业查询先运行 scripts/company_source_routing.py 生成动态计划。只有店铺名/品牌名时采用“风鸟模糊发现 → 企查查精确核验 → 风鸟补缺”；已有公司全称或统一社会信用代码时采用“企查查精确核验 → 风鸟补缺”。任一数据源不可用时停止，不允许绕过双源门槛。风鸟命令统一通过 python scripts/run_fengniao.py 执行，使刚写入的用户级 Key 无需重启即可生效；调用顺序为 discover "企业基本信息"、biz_fuzzy_search 获取内部 entid、biz_basic_info 查询详情，entid 不写入交付表。企查查与风鸟冲突时按“平台资质页 > 信用代码一致 > 商标/品牌官网 > 企业名称相似 > 电话邮箱”裁决，不能按先返回的平台强选。需要商标交叉验证时创建 trademark_queries.json，运行 scripts/crosscheck_trademarks.py。结合证据生成 subjects.json，再运行 enrich 补工商与联系方式。
9. 类目发现模式运行 scripts/build_workbook.py 生成六张表：概览、正式招商商家、主体核验、未确认字段、淘汰商家、口径与复用。用户指定名单模式由Codex按输入实际结构直接生成六类信息：概览、正式招商商家、主体核验、未确认字段、原始输入、口径说明，无需强行套用采集任务JSON。正式表必须把企业搜索结果放在“建联候选公司（非店铺主体，待核验）”及候选联系方式列，平台执照主体单独写入正式主体列；候选联系方式不能反向证明店铺主体。
10. 运行 scripts/verify_job.py，并使用电子表格工具完成公式重算和所有工作表视觉检查后交付。

判定纪律

• “精准命中”是商品归属准确，不是字段必须填满。
• 商品标题需命中目标词；带电、配件、耗材、宠物或明显无关商品按任务配置排除。
• 店铺SPU按唯一商品ID计数；目标占比=目标SPU/精确店铺SPU。
• 付款人数使用搜索卡片可见值的展示下限合计，不宣称近30天月销。
• 企业简称/品牌名先走实体识别；完整公司名或统一社会信用代码才能查询工商详情。
• 动态路由按输入精度决定，不固定某个平台永远优先；平台资质页主体已明确时直接进入精确主体路线。
• 企业查询返回多候选时必须保留候选并标记待确认，不得猜测或自动取第一条。
• 联系方式不能单独证明店铺主体；仅有电话/邮箱时，候选必须保持 selected: false。
• 未确认主体不等于隐藏建联信息：已取得的候选公司电话、邮箱和地址必须在正式表以“待核验”列完整展示，方便先联系再核验关系。
• 店铺资质页确认的当前持证运营主体优先级最高。商标权利人或品牌证据只能提升置信度；若尚未确认当前运营主体，角色必须写明“商标权利主体”，并保留待确认项。
• 平台营业执照主体必须与正式表“公司名称”和“统一社会信用代码”一致；一旦存在平台执照，任何不一致的企业搜索候选都必须降级为“非店铺主体、待核验建联线索”，即使旧数据写了 selected: true 也不得采用。
• 平台资质只能来自独立的 platform_qualifications.json 资质记录；company_enrichment.json 中手工写入 evidence_type: platform_qualification 不能证明主体。信用代码闭环必须同时保存企业工商代码、来源侧 matched_credit_code 和证据来源，两个代码逐字一致后才允许 selected: true。
• 商标/品牌官网证据不得单独写入正式主体；没有平台营业执照或信用代码闭环时，正式公司、法人、地址和信用代码全部留空，不得把名称相似企业包装成主体。
• 多源结果冲突时保留每个候选及来源；只有全称/信用代码与平台资质、品牌商标或官网证据能闭环时才设为 selected: true。
• 未披露字段留空；不得编造电话、邮箱、法人、地址或成立日期。
• 工作簿必须保留全部已取得且去重后的电话和邮箱，并按内容自动扩展行高，禁止为了版面截断数据。
• 所有来源URL写入工作簿；每条主体说明其角色和置信度。
• 用户指定名单中的每个店铺都必须可在正式表与原始输入中追溯；企业查询无结果、额度不足或缺少链接只能进入未确认字段，不能成为删除店铺的理由。

风控与恢复

• 访问间隔保持18–22秒；遇风控立即停止，不换账号、不绕过验证。
• 只操作用户已登录的浏览器会话；不要导出Cookie。
• 用户要求无头执行时，企业查询、工作簿生成、重算和导出必须使用 CLI/API 与 --headless；不得打开或接管可见浏览器窗口。已有淘宝采集结果时直接复用，不得为补企业字段重新触发浏览器。
• 启动脚本前把 Skill 根目录和任务目录解析为绝对路径；不要同时叠加仓库前缀与当前工作目录。每一步写入 work/<job>/ 中间JSON。重跑必须跳过已完成查询和店铺。Browser Bridge 的单次 operation aborted、超时或连接重置最多重试1次；页面内 MTop 请求以 MTOP_REQUEST_TIMEOUT 有界退出，单店仍失败时写入 audit_errors.json 并继续其他店。除正文验证码文案外，还要检测指向 _____tmd__ 的隐藏挑战 iframe；两者都属于淘宝风控，必须立即停止，不得当作普通超时自动重试。若某个低价值店持续占用会话，可换新会话并用 --skip-shop 显式跳过，禁止静默丢失。
• FN_API_KEY、其他 API Key、Bearer Token、Cookie、Authorization 头禁止写入命令参数、脚本、日志、Git、工作簿、手册或最终回复；用户可把双 Key 发给 Codex，由配置助手通过标准输入写入 Windows 当前用户安全配置，Codex 不得在任何回复中复述。

详细资料

• 完整流程：references/workflow.md
• 数据结构：references/data-contract.md
• MCP安装：references/mcp-setup.md
• 类目配置：references/category-rules.md