分销经营

1688 分销

处理边界

本 Skill 采用 MCP 调用 + Python 后处理 两段式流程：

1. 鉴权与 API 调用全部交给 MCP 连接器 ali1688-buyer。Agent 不处理 AK、本地 Token、browser_use 授权、签名或 HTTP 请求。
2. 业务后处理必须交给 Python 脚本。Agent 不直接解析 MCP 原始返回、不自行生成商品/订单/店铺/铺货结果表格。

MCP 连接器

• 连接器名称：ali1688-buyer
• 本技能使用的 MCP 工具：
  • distribution_select_offer
  • same_img_offer_search
  • distribution_offer_info
  • shop_and_tool_info
  • distribute_offer
  • fx_query_order
  • fx_send_ww
  • fx_ww_reply
  • distribution_knowledge_tool
• __userId__ 等用户身份参数由 MCP 网关自动注入，Agent 不手动传递。

命令入口

统一入口：

python3 {baseDir}/scripts/cli.py <业务域> <动作> [--参数] --mcp-result-file /tmp/mcp.json

也支持 stdin：

cat /tmp/mcp.json | python3 {baseDir}/scripts/cli.py <业务域> <动作> [--参数]

⚠️ 传递 MCP 结果给 Python：运行 Bash(python3 {baseDir}/scripts/extract_mcp_result.py /tmp/mcp.json) 自动从会话日志提取最近的 MCP 工具结果，然后执行下方命令。禁止读 Python 脚本源码、禁止用 Write/heredoc 手写临时文件——模型逐 token 重新生成大 JSON 会超时。

所有命令输出 JSON：

{"success": true, "markdown": "...", "data": {...}}

Agent 展示给用户时必须完整输出 markdown 字段。除非用户明确要求分析，禁止追加“后续建议”“后续操作”“操作指引”等自创内容。

严格禁止

• 禁止配置、读取、提示用户粘贴或管理 AK。
• 禁止调用旧 _http.py、旧鉴权脚本、浏览器或网页搜索引擎请求 1688 分销数据。
• 禁止在 MCP 调用失败后自行通过外部网站补充商品、店铺、订单、供应商或链接信息。
• 禁止由 AI 直接改写 MCP 原始返回为最终结果；必须调用 Python 后处理脚本输出 markdown。
• 禁止编造数据/链接，所有数据必须来自 MCP 返回或 Python 后处理结果。
• 禁止未经确认执行铺货；铺货不可逆，必须用户明确确认商品和目标店铺。
• 禁止品牌未授权商品铺货：isBrandOffer=true 且 isBrandAuth=false 绝对不能铺货。
• 禁止擅自添加筛选条件、改写用户原话、猜测渠道和店铺。

意图判断

判断不清时优先询问用户意图，不要猜测。与 1688 分销无关的话题不触发本技能。

参考文档（按业务域按需加载）

各业务域的字段映射、接口规范、流程细节集中在 scripts/biz/<业务域>/reference.md。命中对应业务域时，Agent 必须先加载并阅读该 reference.md，再构造 MCP 参数与 Python 后处理调用。

加载原则：

• 仅加载当前用户意图命中的业务域 reference.md，不要一次性加载全部。
• 同一会话中跨业务域时按需追加加载对应 reference.md。
• reference.md 与本 SKILL.md 内容冲突时，以本 SKILL.md 的处理边界与禁止项为准；业务字段、参数枚举、错误码映射以 reference.md 为准。

MCP + Python 后处理映射

Python 后处理职责

本目录保留原有复杂后处理逻辑：

• 选品：解析关键词/图搜结果、截断展示数量、为品牌未授权商品注入 brandAuthUrl。
• 分销参谋：提取价格、运费、品牌授权、支持渠道、体验分、履约率、保障服务等决策因子。
• 店铺查询：过滤已过期工具和过期授权店铺，生成店铺列表。
• 铺货：解析 errorCode、成功/失败/未处理商品 ID，生成稳定铺货结果文案。
• 订单查询：翻译订单状态/退款状态，识别风险订单，生成订单统计和风险明细。
• 旺旺：校验消息和订单参数、解析任务 ID、解析商家回复列表。
• 知识库：校验渠道/工具名称，解析 JSON 字符串型文档列表。

Agent 不得复刻或替代以上逻辑。

选品铺货流程

1. 用户提出选品/铺货需求。
2. Agent 构造 MCP 参数并调用 distribution_select_offer 或 same_img_offer_search。
3. 将 MCP 原始返回交给 product_search_helper search 后处理。
4. 对候选商品调用 distribution_offer_info，再用 offer_info query --decision=true 后处理。
5. 若商品 isBrandOffer=true 且 isBrandAuth=false，标记不可铺货，禁止继续铺货。
6. 调用 shop_and_tool_info 并用 shop_info query 后处理可用店铺。
7. 用户确认商品和目标店铺后，调用 distribute_offer。
8. 将铺货 MCP 返回交给 distribute_helper execute 后处理并完整输出 markdown。

订单流程

• 查询订单：调用 fx_query_order，再用 order_helper query 生成订单统计、风险订单和退款明细。
• 催发催揽：从查询结果中的风险订单生成催发消息，用户确认后调用 fx_send_ww，再用 order_helper send 后处理任务 ID。
• 查询回复：调用 fx_ww_reply，再用 order_helper query_reply 后处理回复状态。

知识库流程

1. 识别用户 query、渠道、工具。
2. 用户未明确渠道/工具时传 default，不要猜测。
3. 调用 distribution_knowledge_tool。
4. 用 knowledge_helper query 解析和统计结果。

错误处理

MCP 调用失败

1. 原样展示 MCP 返回的错误信息。
2. 鉴权、401、Forbidden、token 过期等错误：提示用户检查 ali1688-buyer 连接器 OAuth 授权，必要时在连接器设置中重新授权。
3. 限流、超时、服务异常：提示稍后重试。
4. 禁止提示用户配置 AK。
5. 禁止浏览器、网页搜索或旧 HTTP 脚本降级。

Python 后处理失败

• 直接输出脚本返回的 markdown。
• 参数缺失时按脚本错误提示补齐。
• 不要手动重试，不要使用其他工具补充，不要编造数据。

安全声明

• 本技能不涉及任何 AK / Token 的本地存储和管理。
• 所有鉴权流程通过 MCP 连接器 ali1688-buyer 的 OAuth 机制完成。
• Agent 不应接触、存储或传输用户凭证。

免责声明

分销商品、店铺、订单和知识库数据来自 1688 平台。本技能仅作信息展示和操作辅助，不对商品质量、价格准确性、供应商资质、下游平台规则或交易结果做任何保证，用户应自行核实并承担交易风险。