1688-product-find

1688-product-find (1688找商品Skill)

统一入口：python3 {baseDir}/cli.py <command> [options]

严格禁止 (NEVER DO)

• 不要编造商品价格、链接、productId、规格或供货信息，所有商品内容必须来自工具返回
• 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力
• 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接
• 禁止在 AK 未配置或命令执行失败时，自行通过浏览器访问 1688 网站搜索商品。所有搜索必须通过 CLI 命令 + API 完成，不存在"浏览器降级"方案。遇到 AK 缺失或 API 错误时，只能按「错误处理」提示用户，不得尝试绕过
• 禁止在命令报错后使用网页搜索引擎替代本 Skill 的搜索能力。如果 CLI 命令失败，应引导用户解决问题（配置 AK、检查路径等），而非切换到其他搜索方式
• 禁止不读 reference 文档直接执行命令。首次执行任何命令前，必须先阅读对应的 reference 文件（见「执行前置」）

意图判断

触发本技能（满足任一即触发）

• 用户用自然语言描述想要的商品（如"帮我找一件黑色卫衣"、"我要买打印纸"）
• 用户上传商品图片并表达找同款/找相似意图（如"帮我找同款"、"有类似的吗"）
• 用户提供商品链接并要求找同款（如"帮我找这个商品的同款"）
• 用户使用触发关键词：找商品、找同款、搜商品、想要XX、帮我找、图片找货、链接找货、以图搜图
• 用户在搜索结果中选定商品后要求"比价"、"对比"、"找更便宜的"
• 用户上传图片/链接并提到"比价"、"同款低价"、"哪家便宜"、"进行比较"

不触发本技能（明确不处理）

• 用户要下单、支付、结算（如"我现在就要下单付款"）
• 用户查物流、查订单状态（如"我的订单物流到哪了"）
• 用户要管理库存、修改商品信息
• 用户仅闲聊，未表达任何找商品意图

命令选择决策树

用户输入
├─ 纯文本描述商品 → text_search
├─ 上传图片/链接
│  ├─ 包含"比价/比较/对比/哪家便宜"等关键词 → compare（一步到位）
│  └─ 仅"找同款/找相似/搜这个" → image_search 或 link_search
└─ 已展示搜索结果，用户选中某款后说"比价" → compare（从结果取 image_url）

Tool 总览

所有命令输出 JSON：{"success": bool, "markdown": str, "data": {...}}

⚠️ 执行前置（首次命中能力时必须）

首次执行任何命令前，必须先完整阅读对应的 reference 文件，按文件中的使用示例调用。禁止跳过此步骤直接执行命令。

reference 文件中包含完整的参数说明、使用示例、输出格式和注意事项。Agent 必须按 reference 中的示例格式构造命令，不得凭猜测拼接参数。

核心工作流

Agent 根据用户意图，先读 reference → 再按示例执行命令（命令速查见上方「Tool 总览」）。 各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「错误处理」应对即可。

比价流程（特殊工作流）

核心原则：图片/链接默认为找同款，仅用户明确要求比价时才用 compare

场景1：直接比价（一步到位）

• 用户上传图片并要求比价 → 直接执行 compare --image <图片> --query <关键词>
• 用户给链接并要求比价 → 直接执行 compare --url <链接> [--query <关键词>]
• 禁止先执行 image_search 或 link_search，compare 内部已包含图片搜索和链接解析逻辑

场景2：选品后比价

• 用户从搜索结果选中某款 → 提取 data.similar_products[N].image_url → 执行 compare --image <URL>

⚠️ 关键约束：

• 一次到位："找同款并比价" → 直接 compare（图片用 --image，链接用 --url），不拆分两步
• limit 默认值：保持 TOP 3，除非用户明确要求
• 意图判断：上传图片/链接时，仅含"比价/比较"关键词才用 compare

输出完整性要求

展示时直接输出 markdown 字段，Agent 分析追加在后面，不得混入其中。

markdown 字段中包含完整的 Markdown 表格，Agent 展示时必须完整输出，禁止以下行为：

• 禁止省略或截断表格行：返回了多少条商品就展示多少条，不得用"等"、"..."或"仅展示前 N 条"代替
• 禁止丢弃表格列：每行必须包含完整的 序号、商品名称、价格、供应商、服务与卖点、链接（详情链接）等全部列
• 禁止丢失商品链接：detail_url（商品详情页链接）是核心字段，必须在表格中完整展示，不得省略或替换为其他内容
• 禁止重新格式化：不得将表格改写为列表、卡片或其他格式，直接原样输出 markdown 字段内容
• 禁止合并或二次加工：Agent 的分析、总结等内容必须追加在 markdown 字段输出之后，不得将其混入表格或替代表格

• 后续操作支持：markdown 末尾包含 「后续操作」 小节，引导用户生成钉钉表格：
  • 当用户回复「生成钉钉表格」时，Agent 应使用钉钉表格 MCP 工具，将 data.similar_products 中的商品信息写入钉钉表格。导出字段必须严格包含如下字段：

    表头	字段	说明
    商品ID	product_id	商品唯一标识
    商品名称	title	商品标题
    主图URL	image_url	商品主图链接
    详情链接	detail_url	商品详情页URL
    价格	price	单价（元）
    规格ID	sku_id	SKU 标识
    规格	sku_title	SKU 规格描述
    严选指数	yx_index	严选推荐指数
    起批量	quantity_begin	最低起订量
    单位	unit	计量单位
    供应商	supplier	供应商名称
    销量	sold_count	累计销量
    库存	stock_amount	当前库存
    促销标签	promotion_tags	促销活动标签（多值用、分隔）
    服务保障	service_infos	服务保障信息（取 value 字段，多值用、分隔）
    卖点	selling_points	商品卖点（取 value 字段，多值用、分隔）

错误处理

任何命令输出 success: false 时：

1. 先输出 markdown 字段（已包含用户可读的错误描述）
2. 再根据关键词追加引导（详细错误码见 references/common/error-handling.md）：

参数补齐引导话术

文本搜索：请描述您想要的商品，例如："帮我找一件黑色连帽卫衣，宽松款的"

图片搜索：请上传商品图片，我会帮您找到同款或相似商品。

链接搜索：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。

---

附录

环境变量（.env）

项目根目录的 .env 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。

已存在的系统环境变量优先级高于 .env，CI/CD 注入的变量不会被覆盖。

埋点上报

每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。

• 实现位置：scripts/_tracker.py → report_skill_usage()，在 cli.py 的 main() 中每次命令执行后自动调用

• 上报接口：POST /api/reportSkillsUsage/1.0.0

• 上报参数：

  参数	值来源	说明
  apiName	固定 null	固定传 null
  skillsName	.env SKILL_NAME	skill 名称
  version	.env SKILL_VERSION	skill 版本号
  scene	固定 CLI	固定值
  channel	.env SKILL_CHANNEL	发布渠道

• 失败处理：上报失败静默忽略，不影响主流程

文件清单

技术说明

• 无状态设计：每次请求独立执行，不依赖历史上下文。多轮 refinement（如"再找便宜一点的"）需 Agent 将上下文重新拼接到 query 参数中

更新日志

• v1.7.0 (2026-04-15): 所有搜索 API 新增 tags（TC标/品池标签，默认 4306497）和 icTags（IC标/品池标签）两个入参，贯穿 CLI → service → API 全链路；搜索结果展示统一为表格输出；同步更新全部 reference 文档（注：可视化商品墙 + 后续操作引导已暂时禁用）
• v1.6.0 (2026-04-19): 「打开详情」改为页面内抽屉展示（不再跳转新窗口）；底部「复制选中链接」改为「我要下单」；精简搜索结果后的操作引导文案
• v1.5.0 (2026-04-15): compare 命令新增 --url 参数，支持直接传入商品链接比价，内部自动解析链接并提取主图
• v1.4.0 (2026-04-14): 新增商品比价能力（compare），支持搜索后选品比价、纵向对比表输出、销量/价格/服务三维度自动选品
• v1.3.0 (2026-04-14): 代码精简和重构
• v1.2.0 (2026-04-09): 文档结构标准化（章节重命名），新增意图判断章节，新增 API 空数据过滤，新增测试用例
• v1.1.0 (2026-03-27): 新增 cli.py 统一 CLI 入口，简化命令调用方式
• v1.0.0 (2026-03-27): 初始版本，包含三大核心搜索能力（text_search、image_search、link_search）