القائمة
1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找供应商。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | 1688-product-find |
| version | 1.7.0 |
| description | 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找供应商。 |
| metadata | {"openclaw":{"emoji":"🔍","requires":{"bins":["python3"]},"primaryEnv":"ALI_1688_AK"}} |
统一入口：python3 {baseDir}/cli.py <command> [options]
productId、规格或供货信息，所有商品内容必须来自工具返回用户输入
├─ 纯文本描述商品 → text_search
├─ 上传图片/链接
│ ├─ 包含"比价/比较/对比/哪家便宜"等关键词 → compare（一步到位）
│ └─ 仅"找同款/找相似/搜这个" → image_search 或 link_search
└─ 已展示搜索结果，用户选中某款后说"比价" → compare（从结果取 image_url）
| Tool 名称 | 用途 | 调用语法 |
|---|---|---|
text_search | 文本搜索商品 | python3 cli.py text_search --query "黑色连帽卫衣" |
image_search | 图片以图搜图 | python3 cli.py image_search --image "/path/to/image.jpg" |
link_search | 链接找同款 | python3 cli.py link_search --url "https://detail.1688.com/offer/xxx.html" |
compare | 商品比价 | python3 cli.py compare --image "商品图片URL" [--query "规格关键词"] 或 python3 cli.py compare --url "商品链接" |
configure | AK 管理 | cli.py configure YOUR_AK（设置）/ --status（查看）/ --clear（清除）/ --reset NEW_AK（重置） |
get_ak | 自动获取 AK | cli.py get_ak |
所有命令输出 JSON：{"success": bool, "markdown": str, "data": {...}}
首次执行任何命令前，必须先完整阅读对应的 reference 文件，按文件中的使用示例调用。禁止跳过此步骤直接执行命令。
| 命令 | 执行前必读 |
|---|---|
configure | references/capabilities/configure.md |
text_search | references/capabilities/text_search.md |
image_search | references/capabilities/image_search.md |
link_search | references/capabilities/link_search.md |
compare | references/capabilities/compare.md |
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），不拆分两步compare展示时直接输出 markdown 字段，Agent 分析追加在后面，不得混入其中。
markdown 字段中包含完整的 Markdown 表格，Agent 展示时必须完整输出，禁止以下行为：
detail_url（商品详情页链接）是核心字段，必须在表格中完整展示，不得省略或替换为其他内容markdown 字段内容markdown 字段输出之后，不得将其混入表格或替代表格markdown 末尾包含 「后续操作」 小节，引导用户生成钉钉表格：
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 时：
markdown 字段（已包含用户可读的错误描述）references/common/error-handling.md）：| markdown 关键词 | Agent 额外动作 |
|---|---|
| "AK 未配置" 或 "AK 未就绪" | 停止一切搜索尝试，优先执行 python3 cli.py get_ak 自动获取 AK；如自动获取失败，引导用户前往 https://clawhub.1688.com/ 获取后执行 python3 cli.py configure YOUR_AK。禁止浏览器替代 |
| "签名无效" 或 "401" | 提示用户检查 AK 是否正确或已过期，引导重新 configure |
| "图片路径无效" | 提示用户检查图片路径是否存在 |
| "无法自动获取商品主图" | 引导用户手动提供商品图片 URL，使用 --image 参数 |
| "限流" 或 "429" | 建议用户等待 1-2 分钟后重试 |
| "格式异常" 或 "HTTP 错误 500" | 提示用户稍后重试，可能是 API 返回异常 |
| "沙箱" 或 "权限" 或 "Permission denied" | 提示用户授予目录访问权限，或在 IDE 设置中允许 Skill 访问所需目录 |
| 其他 | 仅输出 markdown，不得自行发起浏览器搜索 |
文本搜索：请描述您想要的商品，例如："帮我找一件黑色连帽卫衣，宽松款的"
图片搜索：请上传商品图片，我会帮您找到同款或相似商品。
链接搜索：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。
项目根目录的 .env 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。
| 变量 | 默认值 | 说明 |
|---|---|---|
SKILL_NAME | 1688-product-find | skill 名称 |
SKILL_VERSION | 1.7.0 | skill 版本号 |
SKILL_CHANNEL | clawhub | 发布渠道 |
已存在的系统环境变量优先级高于
.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 | 发布渠道 |
失败处理：上报失败静默忽略，不影响主流程
| 路径 | 类型 | 用途 |
|---|---|---|
SKILL.md | 主文件 | 技能入口、意图判断、工作流、错误处理 |
cli.py | CLI 入口 | 统一命令行接口，自动发现 capabilities |
scripts/ | 脚本目录 | 核心实现（认证、HTTP、输出格式化等） |
references/capabilities/configure.md | 参考文档 | AK 配置能力详细说明 |
references/capabilities/text_search.md | 参考文档 | 文本搜索能力详细说明 |
references/capabilities/image_search.md | 参考文档 | 图片搜索能力详细说明 |
references/capabilities/link_search.md | 参考文档 | 链接搜索能力详细说明 |
references/capabilities/compare.md | 参考文档 | 商品比价能力详细说明 |
references/common/error-handling.md | 参考文档 | 通用错误处理策略 |
tests/testcases.json | 测试用例 | 典型输入输出样例 |
tags（TC标/品池标签，默认 4306497）和 icTags（IC标/品池标签）两个入参，贯穿 CLI → service → API 全链路；搜索结果展示统一为表格输出；同步更新全部 reference 文档（注：可视化商品墙 + 后续操作引导已暂时禁用）--url 参数，支持直接传入商品链接比价，内部自动解析链接并提取主图cli.py 统一 CLI 入口，简化命令调用方式