{"id":"cb060185-b332-47ef-95b7-344d71651850","entityType":"agent","slug":"clawhub-1688aiinfra-1688-product-find","name":"1688 Product Find","canonicalUrl":"https://www.xpersona.co/agent/clawhub-1688aiinfra-1688-product-find","canonicalPath":"/agent/clawhub-1688aiinfra-1688-product-find","generatedAt":"2026-10-10T09:09:37.508Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":null},"description":"1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s177df9srv6z2y0gd1kw90rern83hzxb:1688-product-find","sourceUrl":"https://clawhub.ai/1688aiinfra/1688-product-find","homepage":"https://clawhub.ai/1688aiinfra/skills/1688-product-find","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/1688aiinfra/1688-product-find","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/1688aiinfra/skills/1688-product-find","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"1688 Product Find technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":null},"stars":null,"forks":null,"downloads":3028,"packageName":null,"latestVersion":"0.27.0","tractionLabel":"3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:10:58.537Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T10:10:58.538Z","lastCrawledAt":"2026-10-09T10:10:58.537Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T10:10:58.537Z","lastVerifiedAt":null,"highlights":[{"version":"0.27.0","createdAt":"2026-09-03T14:57:26.948Z","changelog":"- 埋点上报接口和渠道字段更新：上报接口改为 /api/alibaba.1688.report.skills.usage/1.0.0，`SKILL_CHANNEL` 默认值改为 `clawhubai` - 错误处理策略调整：错误关键字和处理话术与新版接口返回保持同步，如“AK 无效或已过期”“请求被限流”等 - 参考文档和核心工作流同步优化，与新版能力和字段命名保持一致 - 移除废弃文档 skill-card.md，目录结构更清晰","fileCount":47,"zipByteSize":109932},{"version":"1.7.0","createdAt":"2026-05-11T07:25:40.022Z","changelog":"v1.7.0 (2026-04-15): 全面升级，所有搜索命令支持品池标签，接口与文档大幅增强。 - 所有搜索能力（text_search/image_search/link_search/compare）新增 `tags`（TC标/品池标签，默认 4306497）与 `icTags` 入参，支持全链路标签筛选。 - 输出格式统一为完整表格，所有商品信息均在 markdown 字段中详细呈现。 - error-handling（异常处理）、执行前置、参数补齐引导等策略更细化，严格禁止浏览器或网页搜索降级。 - compare（商品比价）功能增强：支持直接对图片或链接比价，并支持选品后比价。 - 同步完善全部 reference 文档和使用示例，增加多场景意图判断与错误提示策略。 - 新增自动上报每次 CLI 调用的埋点，上报参数可配置，统计 skill 使用情况。 - 附加","fileCount":47,"zipByteSize":109685},{"version":"0.2.0","createdAt":"2026-04-09T02:38:32.650Z","changelog":"- 修复了 scripts/_http.py 相关问题，提升了稳定性。 - 其他功能保持不变，依旧支持文本、图片、链接三种商品搜索能力。","fileCount":27,"zipByteSize":45911},{"version":"0.1.0","createdAt":"2026-04-08T12:42:03.449Z","changelog":"1688-product-find v0.1.0 - Initial release with core product search abilities for 1688. - Supports searching by text (text_search), image (image_search), or link (link_search). - Clear usage instructions and strict rules for input construction. - Provides consistent JSON results with user-focused markdown summaries. - Includes detailed error handling and response guidance.","fileCount":27,"zipByteSize":45922}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177df9srv6z2y0gd1kw90rern83hzxb:1688-product-find","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s177df9srv6z2y0gd1kw90rern83hzxb:1688-product-find` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/1688aiinfra/1688-product-find before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T09:09:37.505Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-1688aiinfra-1688-product-find/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":null},"readme":"Skill: 1688 Product Find\n\nOwner: 1688aiinfra\n\nSummary: 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找...\n\nTags: latest:1.7.0\n\nVersion history:\n\nv0.27.0 | 2026-09-03T14:57:26.948Z | auto\n\n- 埋点上报接口和渠道字段更新：上报接口改为 /api/alibaba.1688.report.skills.usage/1.0.0，`SKILL_CHANNEL` 默认值改为 `clawhubai`\n- 错误处理策略调整：错误关键字和处理话术与新版接口返回保持同步，如“AK 无效或已过期”“请求被限流”等\n- 参考文档和核心工作流同步优化，与新版能力和字段命名保持一致\n- 移除废弃文档 skill-card.md，目录结构更清晰\n\nv1.7.0 | 2026-05-11T07:25:40.022Z | auto\n\nv1.7.0 (2026-04-15): \n全面升级，所有搜索命令支持品池标签，接口与文档大幅增强。\n\n- 所有搜索能力（text_search/image_search/link_search/compare）新增 `tags`（TC标/品池标签，默认 4306497）与 `icTags` 入参，支持全链路标签筛选。\n- 输出格式统一为完整表格，所有商品信息均在 markdown 字段中详细呈现。\n- error-handling（异常处理）、执行前置、参数补齐引导等策略更细化，严格禁止浏览器或网页搜索降级。\n- compare（商品比价）功能增强：支持直接对图片或链接比价，并支持选品后比价。\n- 同步完善全部 reference 文档和使用示例，增加多场景意图判断与错误提示策略。\n- 新增自动上报每次 CLI 调用的埋点，上报参数可配置，统计 skill 使用情况。\n- 附加\n\nv0.2.0 | 2026-04-09T02:38:32.650Z | auto\n\n- 修复了 scripts/_http.py 相关问题，提升了稳定性。\n- 其他功能保持不变，依旧支持文本、图片、链接三种商品搜索能力。\n\nv0.1.0 | 2026-04-08T12:42:03.449Z | auto\n\n1688-product-find v0.1.0\n\n- Initial release with core product search abilities for 1688.\n- Supports searching by text (text_search), image (image_search), or link (link_search).\n- Clear usage instructions and strict rules for input construction.\n- Provides consistent JSON results with user-focused markdown summaries.\n- Includes detailed error handling and response guidance.\n\nArchive index:\n\nArchive v0.27.0: 47 files, 109932 bytes\n\nFiles: cli.py (16289b), references/capabilities/compare.md (13227b), references/capabilities/configure.md (5135b), references/capabilities/image_search.md (8540b), references/capabilities/link_search.md (10549b), references/capabilities/text_search.md (8076b), references/common/error-handling.md (1438b), references/skill埋点说明.md (4411b), requirements.txt (45b), scripts/_auth.py (13078b), scripts/_const.py (584b), scripts/_errors.py (1726b), scripts/_http.py (8406b), scripts/_image.py (5315b), scripts/_output.py (17933b), scripts/_tracker.py (2497b), scripts/authorize.py (8285b), scripts/callback_server.py (18307b), scripts/capabilities/compare/__init__.py (0b), scripts/capabilities/compare/cmd.py (3819b), scripts/capabilities/compare/service.py (9962b), scripts/capabilities/configure/__init__.py (0b), scripts/capabilities/configure/cmd.py (4228b), scripts/capabilities/configure/service.py (3772b), scripts/capabilities/image_search/__init__.py (55b), scripts/capabilities/image_search/cmd.py (4558b), scripts/capabilities/image_search/service.py (5564b), scripts/capabilities/link_search/__init__.py (55b), scripts/capabilities/link_search/cmd.py (5205b), scripts/capabilities/link_search/service.py (20336b), scripts/capabilities/text_search/__init__.py (55b), scripts/capabilities/text_search/cmd.py (3791b), scripts/capabilities/text_search/service.py (3615b), scripts/encrypted_store.py (2038b), scripts/env_writer.py (2294b), scripts/main.py (6850b), scripts/pkce.py (836b), scripts/scope_manager.py (5043b), scripts/secure_store.py (4653b), scripts/settings.py (686b), scripts/templates/callback.html (8108b), scripts/templates/product_list.html (15688b), scripts/token_manager.py (10663b), skill-card.md (2622b), SKILL.md (14224b), tests/testcases.json (2807b), _meta.json (137b)\n\nFile v0.27.0:SKILL.md\n\n---\nname: 1688-product-find\nversion: \"1.7.0\"\ndescription: |\n 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。\n 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找供应商。\nmetadata: {\"openclaw\": {\"emoji\": \"🔍\", \"requires\": {\"bins\": [\"python3\"]}, \"primaryEnv\": \"ALI_1688_AK\"}}\n---\n\n# 1688-product-find (1688找商品Skill)\n统一入口：`python3 {baseDir}/cli.py [options]`\n\n## 严格禁止 (NEVER DO)\n- 不要编造商品价格、链接、`productId`、规格或供货信息，所有商品内容必须来自工具返回\n- 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力\n- 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接\n- **禁止在 AK 未配置或命令执行失败时，自行通过浏览器访问 1688 网站搜索商品**。所有搜索必须通过 CLI 命令 + API 完成，不存在\"浏览器降级\"方案。遇到 AK 缺失或 API 错误时，只能按「错误处理」提示用户，不得尝试绕过\n- **禁止在命令报错后使用网页搜索引擎替代本 Skill 的搜索能力**。如果 CLI 命令失败，应引导用户解决问题（配置 AK、检查路径等），而非切换到其他搜索方式\n- **禁止不读 reference 文档直接执行命令**。首次执行任何命令前，必须先阅读对应的 reference 文件（见「执行前置」）\n\n## 意图判断\n\n### 触发本技能（满足任一即触发）\n- 用户用自然语言描述想要的商品（如\"帮我找一件黑色卫衣\"、\"我要买打印纸\"）\n- 用户上传商品图片并表达找同款/找相似意图（如\"帮我找同款\"、\"有类似的吗\"）\n- 用户提供商品链接并要求找同款（如\"帮我找这个商品的同款\"）\n- 用户使用触发关键词：找商品、找同款、搜商品、想要XX、帮我找、图片找货、链接找货、以图搜图\n- 用户在搜索结果中选定商品后要求\"比价\"、\"对比\"、\"找更便宜的\"\n- 用户上传图片/链接并提到\"比价\"、\"同款低价\"、\"哪家便宜\"、\"进行比较\"\n\n### 不触发本技能（明确不处理）\n- 用户要下单、支付、结算（如\"我现在就要下单付款\"）\n- 用户查物流、查订单状态（如\"我的订单物流到哪了\"）\n- 用户要管理库存、修改商品信息\n- 用户仅闲聊，未表达任何找商品意图\n\n### 命令选择决策树\n\n```\n用户输入\n├─ 纯文本描述商品 → text_search\n├─ 上传图片/链接\n│ ├─ 包含\"比价/比较/对比/哪家便宜\"等关键词 → compare（一步到位）\n│ └─ 仅\"找同款/找相似/搜这个\" → image_search 或 link_search\n└─ 已展示搜索结果，用户选中某款后说\"比价\" → compare（从结果取 image_url）\n```\n\n## Tool 总览\n\n| Tool 名称 | 用途 | 调用语法 |\n|-----------|------|---------|\n| `text_search` | 文本搜索商品 | `python3 cli.py text_search --query \"黑色连帽卫衣\"` |\n| `image_search` | 图片以图搜图 | `python3 cli.py image_search --image \"/path/to/image.jpg\"` |\n| `link_search` | 链接找同款 | `python3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"` |\n| `compare` | 商品比价 | `python3 cli.py compare --image \"商品图片URL\" [--query \"规格关键词\"]` 或 `python3 cli.py compare --url \"商品链接\"` |\n| `configure` | AK 管理 | `cli.py configure YOUR_AK`（设置）/ `--status`（查看）/ `--clear`（清除）/ `--reset NEW_AK`（重置） |\n| `get_ak` | 自动获取 AK | `cli.py get_ak` |\n\n所有命令输出 JSON：`{\"success\": bool, \"markdown\": str, \"data\": {...}}`\n\n## ⚠️ 执行前置（首次命中能力时必须）\n\n**首次执行任何命令前，必须先完整阅读对应的 reference 文件，按文件中的使用示例调用。禁止跳过此步骤直接执行命令。**\n\n| 命令 | 执行前必读 |\n|------|-----------|\n| `configure` | `references/capabilities/configure.md` |\n| `text_search` | `references/capabilities/text_search.md` |\n| `image_search` | `references/capabilities/image_search.md` |\n| `link_search` | `references/capabilities/link_search.md` |\n| `compare` | `references/capabilities/compare.md` |\n\n> reference 文件中包含完整的参数说明、使用示例、输出格式和注意事项。Agent 必须按 reference 中的示例格式构造命令，不得凭猜测拼接参数。\n\n## 核心工作流\n\nAgent 根据用户意图，**先读 reference → 再按示例执行命令**（命令速查见上方「Tool 总览」）。\n各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「错误处理」应对即可。\n\n### 比价流程（特殊工作流）\n\n**核心原则：图片/链接默认为找同款，仅用户明确要求比价时才用 compare**\n\n**场景1：直接比价**（一步到位）\n- 用户上传图片并要求比价 → 直接执行 `compare --image <图片> --query <关键词>`\n- 用户给链接并要求比价 → 直接执行 `compare --url <链接> [--query <关键词>]`\n- **禁止**先执行 `image_search` 或 `link_search`，`compare` 内部已包含图片搜索和链接解析逻辑\n\n**场景2：选品后比价**\n- 用户从搜索结果选中某款 → 提取 `data.similar_products[N].image_url` → 执行 `compare --image `\n\n**⚠️ 关键约束**：\n- **一次到位**：\"找同款并比价\" → 直接 `compare`（图片用 `--image`，链接用 `--url`），不拆分两步\n- **limit 默认值**：保持 TOP 3，除非用户明确要求\n- **意图判断**：上传图片/链接时，仅含\"比价/比较\"关键词才用 `compare`\n\n## 输出完整性要求\n\n**展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。**\n\n`markdown` 字段中包含完整的 Markdown 表格，Agent 展示时**必须完整输出**，禁止以下行为：\n- **禁止省略或截断表格行**：返回了多少条商品就展示多少条，不得用\"等\"、\"...\"或\"仅展示前 N 条\"代替\n- **禁止丢弃表格列**：每行必须包含完整的 序号、商品名称、价格、供应商、服务与卖点、链接（详情链接）等全部列\n- **禁止丢失商品链接**：`detail_url`（商品详情页链接）是核心字段，必须在表格中完整展示，不得省略或替换为其他内容\n- **禁止重新格式化**：不得将表格改写为列表、卡片或其他格式，直接原样输出 `markdown` 字段内容\n- **禁止合并或二次加工**：Agent 的分析、总结等内容必须追加在 `markdown` 字段输出**之后**，不得将其混入表格或替代表格\n\n- **后续操作支持**：`markdown` 末尾包含 **「后续操作」** 小节，引导用户生成钉钉表格：\n - 当用户回复「生成钉钉表格」时，Agent 应使用钉钉表格 MCP 工具，将 `data.similar_products` 中的商品信息写入钉钉表格。**导出字段必须严格包含如下字段**：\n | 表头 | 字段 | 说明 |\n |:--|:--|:--|\n | 商品ID | `product_id` | 商品唯一标识 |\n | 商品名称 | `title` | 商品标题 |\n | 主图URL | `image_url` | 商品主图链接 |\n | 详情链接 | `detail_url` | 商品详情页URL |\n | 价格 | `price` | 单价（元） |\n | 规格ID | `sku_id` | SKU 标识 |\n | 规格 | `sku_title` | SKU 规格描述 |\n | 严选指数 | `yx_index` | 严选推荐指数 |\n | 起批量 | `quantity_begin` | 最低起订量 |\n | 单位 | `unit` | 计量单位 |\n | 供应商 | `supplier` | 供应商名称 |\n | 销量 | `sold_count` | 累计销量 |\n | 库存 | `stock_amount` | 当前库存 |\n | 促销标签 | `promotion_tags` | 促销活动标签（多值用、分隔） |\n | 服务保障 | `service_infos` | 服务保障信息（取 value 字段，多值用、分隔） |\n | 卖点 | `selling_points` | 商品卖点（取 value 字段，多值用、分隔） |\n\n\n## 错误处理\n\n任何命令输出 `success: false` 时：\n\n1. **先输出 `markdown` 字段**（已包含用户可读的错误描述）\n2. **再根据关键词追加引导**（详细错误码见 `references/common/error-handling.md`）：\n\n| markdown 关键词 | Agent 额外动作 |\n|----------------|--------------|\n| \"AK 未配置\" 或 \"AK 未就绪\" | **停止一切搜索尝试**，优先执行 `python3 cli.py get_ak` 自动获取 AK；如自动获取失败，引导用户前往 https://clawhub.1688.com/ 获取后执行 `python3 cli.py configure YOUR_AK`。**禁止浏览器替代** |\n| \"AK 无效或已过期\" | 提示用户检查 AK 是否正确或已过期，引导重新 configure |\n| \"图片路径无效\" | 提示用户检查图片路径是否存在 |\n| \"无法自动获取商品主图\" | 引导用户手动提供商品图片 URL，使用 `--image` 参数 |\n| \"请求被限流\" | 建议用户等待 1-2 分钟后重试 |\n| \"格式异常\" 或 \"HTTP 错误 500\" | 提示用户稍后重试，可能是 API 返回异常 |\n| \"沙箱\" 或 \"权限\" 或 \"Permission denied\" | 提示用户授予目录访问权限，或在 IDE 设置中允许 Skill 访问所需目录 |\n| 其他 | 仅输出 markdown，**不得自行发起浏览器搜索** |\n\n## 参数补齐引导话术\n\n> **文本搜索**：请描述您想要的商品，例如：\"帮我找一件黑色连帽卫衣，宽松款的\"\n\n> **图片搜索**：请上传商品图片，我会帮您找到同款或相似商品。\n\n> **链接搜索**：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。\n\n---\n\n## 附录\n\n### 环境变量（.env）\n\n项目根目录的 `.env` 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `SKILL_NAME` | `1688-product-find` | skill 名称 |\n| `SKILL_VERSION` | `1.7.0` | skill 版本号 |\n| `SKILL_CHANNEL` | `clawhubai` | 发布渠道 |\n\n> 已存在的系统环境变量优先级高于 `.env`，CI/CD 注入的变量不会被覆盖。\n\n### 埋点上报\n\n每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。\n\n- **实现位置**：`scripts/_tracker.py` → `report_skill_usage()`，在 `cli.py` 的 `main()` 中每次命令执行后自动调用\n- **上报接口**：`POST /api/alibaba.1688.report.skills.usage/1.0.0`\n- **上报参数**：\n\n | 参数 | 值来源 | 说明 |\n |------|--------|------|\n | `apiName` | 固定 `null` | 固定传 null |\n | `skillsName` | `.env` `SKILL_NAME` | skill 名称 |\n | `version` | `.env` `SKILL_VERSION` | skill 版本号 |\n | `scene` | 固定 `CLI` | 固定值 |\n | `channel` | `.env` `SKILL_CHANNEL` | 发布渠道 |\n\n- **失败处理**：上报失败静默忽略，不影响主流程\n\n### 文件清单\n\n| 路径 | 类型 | 用途 |\n|------|------|------|\n| `SKILL.md` | 主文件 | 技能入口、意图判断、工作流、错误处理 |\n| `cli.py` | CLI 入口 | 统一命令行接口，自动发现 capabilities |\n| `scripts/` | 脚本目录 | 核心实现（认证、HTTP、输出格式化等） |\n| `references/capabilities/configure.md` | 参考文档 | AK 配置能力详细说明 |\n| `references/capabilities/text_search.md` | 参考文档 | 文本搜索能力详细说明 |\n| `references/capabilities/image_search.md` | 参考文档 | 图片搜索能力详细说明 |\n| `references/capabilities/link_search.md` | 参考文档 | 链接搜索能力详细说明 |\n| `references/capabilities/compare.md` | 参考文档 | 商品比价能力详细说明 |\n| `references/common/error-handling.md` | 参考文档 | 通用错误处理策略 |\n| `tests/testcases.json` | 测试用例 | 典型输入输出样例 |\n\n### 技术说明\n\n- **无状态设计**：每次请求独立执行，不依赖历史上下文。多轮 refinement（如\"再找便宜一点的\"）需 Agent 将上下文重新拼接到 query 参数中\n\n### 更新日志\n\n- v1.7.0 (2026-04-15): 所有搜索 API 新增 `tags`（TC标/品池标签，默认 4306497）和 `icTags`（IC标/品池标签）两个入参，贯穿 CLI → service → API 全链路；搜索结果展示统一为表格输出；同步更新全部 reference 文档（注：可视化商品墙 + 后续操作引导已暂时禁用）\n- v1.6.0 (2026-04-19): 「打开详情」改为页面内抽屉展示（不再跳转新窗口）；底部「复制选中链接」改为「我要下单」；精简搜索结果后的操作引导文案\n- v1.5.0 (2026-04-15): compare 命令新增 `--url` 参数，支持直接传入商品链接比价，内部自动解析链接并提取主图\n- v1.4.0 (2026-04-14): 新增商品比价能力（compare），支持搜索后选品比价、纵向对比表输出、销量/价格/服务三维度自动选品\n- v1.3.0 (2026-04-14): 代码精简和重构\n- v1.2.0 (2026-04-09): 文档结构标准化（章节重命名），新增意图判断章节，新增 API 空数据过滤，新增测试用例\n- v1.1.0 (2026-03-27): 新增 `cli.py` 统一 CLI 入口，简化命令调用方式\n- v1.0.0 (2026-03-27): 初始版本，包含三大核心搜索能力（text_search、image_search、link_search）\n\nFile v0.27.0:_meta.json\n\n{\n \"ownerId\": \"kn76msg8cwkep3b08z7zffx9fx82p5wj\",\n \"slug\": \"1688-product-find\",\n \"version\": \"0.27.0\",\n \"publishedAt\": 1788447446948\n}\n\nFile v0.27.0:references/capabilities/compare.md\n\n# Capability: compare (商品比价)\n\n## 功能说明\n基于用户选中商品的图片或商品链接，通过以图搜图找到同款商品，自动按销量、价格、服务三个维度各选出 1 款代表性商品，生成纵向对比表。\n\n## 触发方式\n**Skill 级触发词**: 比价、对比、哪家便宜、找更便宜的、同款低价、进行比较\n\n**Capability 识别特征**:\n- 用户上传图片/链接并**明确要求比价**（如“找同款并比价”、“找到同款进行比较”）\n- 用户在搜索结果中选定某款商品后要求比价/对比\n- 用户使用“比一比”、“哪家便宜”、“低价同款”等关键词\n\n**❗ 商品链接直接比价**：\n- 用户给到商品链接且意图包含比价 → 直接使用 `compare --url`，一步到位\n- **禁止**先执行 `link_search` 再执行 `compare`，`compare --url` 内部已包含链接解析+主图提取+比价逻辑\n\n**⚠️ 意图判断核心原则**:\n- **上传图片/链接时，默认是找同款，使用 `image_search` 或 `link_search`**\n- **仅在用户明确提到“比价/比较/对比”时，才使用 `compare`**\n- `compare` 命令内部已包含以图搜图/链接解析逻辑，一步到位完成搜索+比价\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。\n- 需要商品图片或商品链接（支持以下四种输入方式，二选一）：\n - **URL 图片**：在线图片链接，如 `https://img.alicdn.com/xxx.jpg`\n - **本地图片**：本地文件路径，如 `/path/to/image.jpg`（自动预处理：缩放 + 格式转换）\n - **搜索结果中的图片**：从前序搜索结果的 `image_url` 字段提取\n - **商品链接/ID**：1688/淘宝/天猫商品链接或纯商品 ID（自动解析链接并提取主图）\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py compare [--image \"商品图片URL\"] [--url \"商品链接\"] [--query \"附加关键词\"] [--limit 3] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n> `--image` 和 `--url` 二选一，必须提供其中一个。两者都提供时优先使用 `--image`。\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 商品图片 URL 或本地路径（与 `--url` 二选一） | 可选 |\n| `--url` | `-u` | 商品链接或商品 ID（自动提取主图，与 `--image` 二选一） | 可选 |\n| `--query` | `-q` | 附加关键词（规格、品类等） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 对比商品数量 | 3 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n**支持的图片输入格式**：\n- URL：`https://xxx.jpg`、`https://xxx.png` 等\n- 本地路径：`/path/to/image.jpg`、`C:\\Users\\image.png` 等（支持 JPG、PNG、GIF、BMP、WEBP 等格式）\n- 本地图片会自动预处理：超尺寸自动缩放、非 JPEG 格式自动转换\n\n### 使用示例\n```bash\n# 场景1：基本比价（一步到位，无需先执行 image_search）\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒙奇奇 15CM 毛绒\"\n\n# 场景2：通过商品链接直接比价（一步到位，无需先执行 link_search）\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 场景3：通过纯商品 ID 比价\npython3 {baseDir}/cli.py compare -u \"895657286458\" -q \"不锈钢漏勺\"\n\n# 场景4：按价格从低到高排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc\n\n# 场景5：按销量从高到低排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s sold_desc\n\n# 场景6：降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" --score-level medium\n\n# 场景7：组合使用 - 按价格排序 + 中等相关性\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc --score-level medium\n\n# 场景8：使用默认 TOP 3 对比（推荐，不要随意修改 limit）\npython3 {baseDir}/cli.py compare -i \"https://img.alicdn.com/imgextra/xxx.jpg\"\n\n# 场景9：指定采购件数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" --purchase-amount 200\n\n# 场景10：完整参数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" -l 3 -s yx_desc --score-level high --purchase-amount 100 --tags \"4306497\"\n\n# 场景11：链接比价 + 关键词\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\" -q \"不锈钢漏勺\"\n```\n\n## 处理流程\n\n### 1. 获取商品图片\n- **图片输入**（`--image`）：直接使用图片 URL 或本地路径\n- **链接输入**（`--url`）：自动解析商品链接，提取商品主图（复用 link_search 的 LinkParser + ProductImageExtractor）\n - 支持 1688/淘宝/天猫链接及纯商品 ID\n - 提取失败时返回错误提示，建议用户改用 `--image` 参数\n\n### 2. 以图搜图获取同款候选\n- 使用商品图片 URL 调用 `/api/alibaba.1688.find.product/1.0.0` 接口\n- 固定搜索 20 条候选商品，确保三维度选品有足够样本\n- 若用户提供了 `--query` 关键词，同时传入 API 请求体提升相关性\n- 支持通过 `--sort` 参数控制排序方式\n- 支持通过 `--score-level` 参数控制相关性档位\n\n### 2. 三维度自动选品\n独立评估每个维度的最佳商品（不互斥），同一商品赢得多个维度时合并标签：\n\n| 维度 | 选品策略 | 标签 |\n|------|---------|------|\n| 销量最高 | 按 `sold_count` 降序取第 1 | \"销量最高\" |\n| 价格最低 | 按 `price` 升序取第 1（排除无价格） | \"价格最低\" |\n| 综合最优 | 按 `yx_index` 倒序取第 1 | \"综合最优\" |\n\n> **标签合并规则**：当同一商品同时满足多个维度最优时，合并标签展示（如 \"销量最高 且 价格最低 且 综合最优\"），最终输出的商品数量由去重结果决定（1~3 款），不会用额外商品填充。\n\n### 3. 自适应输出格式\n- **3 款不同商品**：标准纵向对比表格（3 列）\n- **2 款不同商品**：精简对比表格（2 列），合并标签展示\n- **1 款商品**（三维度均为同一商品）：卡片式展示，标签合并为 \"销量最高 且 价格最低 且 综合最优\"\n\n## 输出格式\n\n### 场景 A：多款商品对比表（2~3 列）\n```markdown\n| 维度 | 推荐 1 (销量最高) | 推荐 2 (价格最低) | 推荐 3 (综合最优) |\n|:-----|:----------------|:----------------|:----------------|\n| 商品 | 铂佳无磁不锈钢漏勺... | 加大不锈钢花椒漏勺... | 新款不锈钢汤勺饭店... |\n| 💰 单价 | ￥1.19 | ￥3.80 | ￥3.89 |\n| 📦 规格 | 20cm 细网 | 25cm 粗网 | 30cm 加密 |\n| ⭐ 严选指数 | 85.23 | 72.50 | 90.16 |\n| 📊 起批量 | 100件 | 50件 | 200件 |\n| 销量 | 1.2万 | 856 | 2340 |\n| 库存 | 有货 | 有货 | 有货 |\n| 服务 | 7天无理由、48h发货 | 包邮、7天无理由 | 7天无理由 |\n| 卖点 | 爆款热销 | 工厂直供 | 品质保障 |\n| 供应商 | 义乌XX日用.. | 揭阳XX不锈钢.. | 潮安XX厨具.. |\n| 链接 | [查看](url1) | [查看](url2) | [查看](url3) |\n```\n\n### 场景 B：标签合并对比表（2 列）\n当两个维度指向同一商品时，合并标签展示：\n```markdown\n| 维度 | 推荐 1 (销量最高 且 综合最优) | 推荐 2 (价格最低) |\n|:-----|:---------------------------|:-----------------|\n| 商品 | XX商品... | YY商品... |\n| ... | ... | ... |\n```\n\n### 场景 C：单款商品卡片（1 列）\n当三个维度均指向同一商品时，使用卡片式展示：\n```markdown\n**🏆 销量最高 且 价格最低 且 综合最优**\n\n| 维度 | 详情 |\n|:-----|:-----|\n| 商品 | XX不锈钢漏勺... |\n| 💰 单价 | ￥1.19 |\n| 📦 规格 | 20cm 细网 |\n| ⭐ 严选指数 | 85.23 |\n| 📊 起批量 | 100件 |\n| 销量 | 1.2万 |\n| 库存 | 有货 |\n| 服务 | 7天无理由、48h发货 |\n| 卖点 | 爆款热销 |\n| 供应商 | 义乌XX日用.. |\n| 链接 | [查看](url) |\n```\n\n### JSON 输出结构\n```json\n{\n \"success\": true,\n \"markdown\": \"纵向比价表 Markdown\",\n \"data\": {\n \"data\": {\n \"success\": true,\n \"source_image\": \"图片URL\",\n \"compare_products\": [...],\n \"search_type\": \"compare\",\n \"total_candidates\": 9,\n \"total_compared\": 3\n }\n }\n}\n```\n\n## 输出字段说明\n\n### 展示的字段\n\n| 字段名 | API 字段 | 说明 | 示例 |\n|--------|---------|------|------|\n| 商品 | `title` | 商品标题 | \"铂佳无磁不锈钢漏勺...\" |\n| 💰 单价 | `price` | 商品单价（元） | ￥1.19 |\n| 📦 规格 | `sku_title` | 规格详情/SKU 信息 | \"20cm 细网\" |\n| ⭐ 严选指数 | `yx_index` | 严选指数评分（两位小数，截断） | 85.23 |\n| 📊 起批量 | `quantity_begin` + `unit` | 起批量（拼接展示） | 100件 |\n| 销量 | `sold_count` | 销量数据 | 1.2万 |\n| 库存 | `stock_amount` | 库存状态 | 有货/无货 |\n| 服务 | `service_infos` | 服务标签列表 | 7天无理由、48h发货 |\n| 卖点 | `selling_points` | 卖点标签列表 | 爆款热销 |\n| 供应商 | `supplier` | 供应商名称 | 义乌XX日用.. |\n| 链接 | `detail_url` | 商品详情页链接 | [查看](url) |\n\n## 代码结构\n```\nscripts/capabilities/compare/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心比价逻辑\n ├── ImagePreprocessor # 图片预处理器（复用 image_search）\n ├── _count_service_tags() # 服务标签计数\n ├── _select_top() # 三维度选品策略\n ├── CompareExecutor # 比价执行器\n └── compare_products() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **链接无法提取主图**: 提示用户改用 `--image` 参数直接提供图片 URL\n- **链接格式无效**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **两个参数都未提供**: 抛出 `ValueError(\"必须提供 --image 或 --url 参数\")`\n- **图片路径无效**: 提示用户检查图片路径是否存在\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无匹配商品**: 返回 `success: true`，markdown 显示\"未找到可比价的同款商品\"\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_compare_table`: 输出格式化\n- `ImagePreprocessor`: 图片预处理（复用 image_search 逻辑）\n- `LinkParser` / `ProductImageExtractor`: 链接解析和主图提取（复用 link_search 逻辑）\n\n## 注意事项\n1. **意图判断**：\n - ✅ 用户上传图片 + “找同款” → 使用 `image_search`\n - ✅ 用户上传图片 + “找同款并比价” → 使用 `compare --image`\n - ✅ 用户给链接 + “找同款并比价” → 使用 `compare --url`\n - ✅ 搜索结果展示后，用户选中某款说“比价” → 使用 `compare --image`（从结果提取 image_url）\n2. `--image` 参数来源：\n - 用户直接上传的本地图片路径（用户说“找这款并比价”）\n - 前序搜索结果的 `image_url` 字段（用户已选中某款商品后要求比价）\n - 商家指定的图片 URL\n3. `--url` 参数来源：\n - 用户提供的商品链接（如 `https://detail.1688.com/offer/xxx.html`）\n - 纯商品 ID（如 `895657286458`）\n4. `--query` 参数用于传入用户提到的规格、品类等附加条件，提升搜索相关性\n5. **默认返回 TOP 3**，Agent 不应擅自修改 `--limit`，除非用户明确要求\n6. **排序参数**：`--sort` 可选，不传则使用 API 默认排序（相关性）\n7. **相关性档位**：`--score-level` 默认 `high`，如果高相关性结果不足，可提示用户是否降低为 `medium` 或 `low`\n8. **不存在浏览器降级方案**，AK 缺失或 API 失败时只能返回错误提示\n9. **🚫 常见错误**：\n - ❌ 错误：用户上传图片说“找同款” → 执行 `compare`（应该用 `image_search`）\n - ✅ 正确：用户上传图片说“找同款” → 执行 `image_search`\n - ❌ 错误：用户上传图片说“找同款并比价” → 先 `image_search` 再 `compare`\n - ✅ 正确：用户上传图片说“找同款并比价” → 直接 `compare --image `\n - ❌ 错误：用户给链接说“比价” → 先 `link_search` 再 `compare`\n - ✅ 正确：用户给链接说“比价” → 直接 `compare --url `\n\nFile v0.27.0:references/capabilities/configure.md\n\n# Capability: configure (AK配置和管理)\n\n## 使用示例\n\n```bash\n# 自动获取 AK（启动浏览器授权流程）\npython3 {baseDir}/cli.py get_ak\n\n# 配置 AK\npython3 {baseDir}/cli.py configure YOUR_AK_HERE\n\n# 查看 AK 配置状态（无参数等同于 --status）\npython3 {baseDir}/cli.py configure\npython3 {baseDir}/cli.py configure --status\n\n# 重置 AK（清除旧 Token + 配置新 AK）\npython3 {baseDir}/cli.py configure --reset NEW_AK_HERE\n\n# 清除 AK（同时清除关联的 OAuth Token）\npython3 {baseDir}/cli.py configure --clear\n\n```\n\n## 命令参数\n\n| 参数形式 | 说明 |\n|---------|------|\n| `` | 直接配置新 AK。若已有旧 AK 且不同，自动清除旧 Token |\n| `--status` | 查看当前 AK 配置状态（无参数调用时默认行为） |\n| `--clear` | 清除 AK 并同步清除关联的 OAuth Token |\n| `--reset ` | 重置 AK：清除旧 Token → 写入新 AK |\n| （无参数） | 等同于 `--status` |\n\n## ⚠️ AK 检查机制（Agent 必读）\n\n**判断 AK 是否已配置，不应仅依据用户消息或对话历史。** 正确做法：\n\n1. **直接执行用户请求的搜索命令**（text_search / image_search / link_search / compare）\n2. 如果 AK 未配置，CLI 会返回 `success: false` + \"AK 未配置\" 提示\n3. 此时按下方「AK 缺失时的处理流程」应对\n\n也可主动查询状态：`python3 {baseDir}/cli.py configure`（无参数）\n\n**禁止以下行为**：\n- ❌ 仅因对话中没出现过 AK 就认为未配置（AK 可能已持久化在配置文件中）\n- ❌ 仅因之前配置过就认为仍有效（AK 可能已过期或被清除）\n- ❌ 跳过 CLI 检查直接要求用户提供 AK\n- ❌ 在搜索前主动调用 configure 检查（应直接执行搜索，让 CLI 自动判断）\n\n## AK 缺失时的处理流程\n\n当 CLI 返回 \"AK 未配置\" 错误时，Agent **按顺序**执行：\n\n**第一步：自动获取（优先）**\n\n```bash\npython3 {baseDir}/cli.py get_ak\n```\n\n- 启动本地回调服务器 + 打开浏览器授权页面\n- 用户在浏览器完成登录后，AK 自动保存\n- `success: true` → 配置成功，**立即继续执行用户的原始请求**\n- `success: false` → 进入第二步\n\n**第二步：引导手动配置（回退）**\n\n输出以下话术：\n\n> 自动获取 AK 失败。请手动提供您的 AK（Access Key），用于接口调用的鉴权。\n> 如果还没有 API_KEY，请前往 https://clawhub.1688.com/ 获取。\n\n用户提供 AK 后执行：\n\n```bash\npython3 {baseDir}/cli.py configure <用户提供的AK>\n```\n\n配置成功后，**继续执行用户的原始请求**（如搜索商品）。\n\n## 输出格式\n\n所有输出为标准 JSON：\n\n```json\n{\"success\": bool, \"markdown\": \"...\", \"data\": {\"configured\": bool, \"ak\": \"...\"}}\n```\n\n| 场景 | success | markdown |\n|------|---------|----------|\n| 配置成功 | `true` | `✅ AK 设置成功` |\n| 配置成功（替换旧 AK） | `true` | `✅ AK 设置成功\\n\\n旧的 1688 OAuth Token 已同步清除` |\n| 重置成功 | `true` | `✅ AK 已重置\\n\\n旧的 1688 OAuth Token 已同步清除。` |\n| 清除成功 | `true` | `AK 已清除，关联的 1688 OAuth Token 也已同步清除。` |\n| 无需清除 | `true` | `当前未配置 AK，无需清除。` |\n| 状态：已配置 | `true` | `AK 已配置。\\n\\n**AK**: \\`xxx\\`` |\n| 状态：未配置 | `true` | `AK 未配置。` |\n| AK 格式错误 | `false` | `❌ AK 长度不足（当前 N，需要至少 32 位）` |\n| 写入失败 | `false` | `❌ AK 写入失败，请检查文件权限` |\n| 缺少参数 | `false` | `缺少参数：\\`--reset\\` 后需要提供新的 AK` |\n\n## 异常处理\n\n| 场景 | Agent 应对 |\n|------|-----------|\n| configure 输出 success=false | 原样输出 markdown 错误信息 |\n| 配置成功但后续命令仍报 AK 未配置 | 提示用户新开会话或执行 `openclaw secrets reload`，必要时再重试 configure |\n| 用户问\"我的 AK 在哪\" | 输出获取 AK 引导话术，引导前往 https://clawhub.1688.com/ 获取 |\n\n通用 HTTP 异常（400/401/429/500）处理见 `references/common/error-handling.md`。\n\n---\n\n## 附录：内部机制（Agent 无需主动操作）\n\n以下为系统内部实现细节，Agent 了解即可，**不需要手动执行这些逻辑**。\n\n### AK 校验规则\n\nconfigure 内部会自动校验 AK 格式：\n- 不能为空\n- 长度至少 32 位\n- 仅允许字母、数字及 `_-=` 字符\n\n校验失败时 CLI 会返回明确的 `success: false` 错误信息。\n\n### AK 读取优先级\n\n系统内部按以下优先级自动读取 AK（Agent 无需关心路径细节）：\n\n1. 环境变量 `ALI_1688_AK`（OpenClaw 平台注入，最高优先级）\n2. 配置文件 `{workspace}/.1688-AK/.ak_store.json`（多个候选路径自动遍历）\n\n配置文件格式：`{\"ak\": \"...\"}`\n\n### Token 联动清除\n\n以下操作会自动清除关联的 OAuth Token（Agent 无需手动清 Token）：\n\n| 操作 | Token 清除条件 |\n|------|--------------|\n| `configure ` | 仅当新旧 AK 不同时 |\n| `--reset ` | 始终清除 |\n| `--clear` | 始终清除 |\n\nToken 清除失败时静默忽略，不影响主流程。\n\nFile v0.27.0:references/capabilities/image_search.md\n\n# Capability: image_search (图片找同款)\n\n## 功能说明\n基于用户上传的商品图片，通过图像识别和特征匹配，在 1688 平台搜索同款或相似商品。支持本地图片路径和图片 URL。\n\n## 触发方式\n**Skill 级触发词**: 图片找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含图片附件\n- 或消息中包含图片 URL\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"搜这个\"\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py image_search --image \"图片路径或URL\" [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 图片本地路径或 URL | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg\n\n# 指定返回数量\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -p 1688 -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"image_path\": \"string (required) - 本地图片路径或 URL\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n### 1. 图片预处理 (ImagePreprocessor)\n```python\n步骤：\n1. 判断输入类型（本地路径 / URL）\n2. 本地图片：检查文件存在性和大小\n3. 返回处理后的图片信息\n```\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 将图片通过 base64 编码转换成字符串\n2. 拼装请求并调用 `/api/alibaba.1688.find.product/1.0.0` 接口\n3. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"imgBase64\": \"base64编码的图片字符串\",\n \"imageUrl\": \"图片URL（可选）\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n> `sortType` 和 `scoreLevel` 为可选字段，不传则使用默认值。\n\n**API 响应格式**:\n```json\n{\n \"data\": {\n \"data\": [\n {\n \"itemId\": 987622522091,\n \"title\": \"商品标题\",\n \"imageUrl\": \"商品主图URL\",\n \"detailUrl\": \"商品详情页URL\",\n \"score\": 0.99786893,\n \"currentPrice\": 12.8,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"五彩公鸡\",\n \"yxIndex\": 4.5,\n \"quantityBegin\": 1,\n \"unit\": \"\",\n \"company\": \"义乌某工艺品有限公司\",\n \"soldOut\": 20000,\n \"storeAmount\": 5000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 201382421,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [],\n \"serviceInfos\": [{\"type\": \"赊账服务\", \"value\": \"先采后付\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"亚克力\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"count\": 3\n }\n}\n```\n\n### 3. 错误处理（无浏览器降级）\n**本能力不存在浏览器降级方案。** 当 API 不可用或 AK 未配置时，直接返回错误信息，由 Agent 引导用户解决（配置 AK、检查路径等），禁止尝试通过浏览器访问 1688 网站。\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"source_image\": \"/path/to/uploaded.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"跨境创意五彩公鸡动物摆件2D平面亚克力家居办公桌面装饰摆件\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"price\": 12.8,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"五彩公鸡\",\n \"yx_index\": 4.5,\n \"quantity_begin\": 1,\n \"unit\": \"\",\n \"supplier\": \"义乌某工艺品有限公司\",\n \"sold_count\": 20000,\n \"stock_amount\": 5000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [],\n \"service_infos\": [{\"type\": \"赊账服务\", \"value\": \"先采后付\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"亚克力\"}]\n }\n ],\n \"search_type\": \"image_similarity\",\n \"total_results\": 3\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/image_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── ImagePreprocessor # 图片预处理器\n ├── ImageSearchExecutor # 搜索执行器\n └── image_search() # 主入口函数\n```\n\n## 错误处理\n- **图片路径无效**: 抛出 `ServiceError(\"图片路径无效\")`\n- **图片不存在**: 抛出 `FileNotFoundError`\n- **图片太大**: 抛出 `ValueError`（超过 5MB）\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n\n## 测试用例\n```python\n# 本地图片路径\nimage_search(image_path=\"/workspace/product.jpg\")\n\n# 图片 URL\nimage_search(image_path=\"https://example.com/product.png\")\n\n# 指定返回数量\nimage_search(image_path=\"xxx.jpg\", limit=10)\n\n# 指定采购件数\nimage_search(image_path=\"xxx.jpg\", purchase_amount=100)\n\n# 指定排序和相关性\nimage_search(image_path=\"xxx.jpg\", sort_type=\"price_asc\", score_level=\"medium\")\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n\n## 注意事项\n1. 图片上传需考虑隐私和安全，临时文件会自动清理\n2. API 调用需要有效的 AK 配置\n3. **不存在浏览器降级方案**，AK 缺失或 API 失败时只能返回错误提示，不得尝试浏览器搜索\n4. Windows 环境下临时文件可能受沙箱限制，代码已内置 fallback 到工作目录\n5. **本地图片必须使用绝对路径**（如 `/home/user/image.png` 或 `C:\\Users\\user\\image.png`），禁止使用相对路径（如 `./image.png`），否则在不同操作系统下可能因工作目录不一致导致找不到文件\n6. **图片预处理限制**：本地图片最大支持 5MB；超过 800×800 像素的图片会自动等比缩放；非 JPEG 格式会自动转换为 JPEG（透明通道处理为白色底）\n\nFile v0.27.0:references/capabilities/link_search.md\n\n# Capability: link_search (链接找同款)\n\n## 功能说明\n解析用户提供的商品链接或商品 ID，自动识别平台，尝试静默获取商品主图，然后基于主图搜索同款或相似商品。与 image_search 和 text_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 链接找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含完整 URL (1688/淘宝/天猫)\n- 或纯商品 ID (6-12 位数字/字母组合)\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"这个的平价替代\"\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py link_search --url \"商品链接\" [--image \"图片URL\"] [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--url` | `-u` | 商品链接或商品 ID | 必需 |\n| `--image` | `-i` | 商品图片 URL（自动获取失败时使用） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法（自动获取主图）\npython3 {baseDir}/cli.py link_search -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 纯商品 ID\npython3 {baseDir}/cli.py link_search -u \"895657286458\"\n\n# 手动指定商品图片（当自动获取失败时）\npython3 {baseDir}/cli.py link_search -u \"https://detail.1688.com/offer/895657286458.html\" -i \"https://img.alicdn.com/xxx.jpg\"\n\n# 指定返回数量\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"url\": \"string (required) - 商品链接或商品 ID\",\n \"image_url\": \"string (optional) - 商品图片 URL（自动获取失败时使用）\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n\n### 1. 链接解析 (LinkParser)\n```python\n输入示例：\n- \"https://detail.1688.com/offer/895657286458.html\"\n- \"https://item.taobao.com/item.htm?id=1033765771797\"\n- \"895657286458\" (纯 ID)\n\n输出：\n{\n \"platform\": \"1688\",\n \"product_id\": \"895657286458\",\n \"canonical_url\": \"https://detail.1688.com/offer/895657286458.html\"\n}\n```\n\n**识别规则**:\n- **1688**: URL 包含 `1688.com` 且路径含 `offer`，ID 格式：6-12 位纯数字\n- **淘宝**: URL 包含 `taobao.com` 或 `tb.cn`，ID 格式：8-12 位字母数字\n- **天猫**: URL 包含 `tmall.com`，ID 格式同淘宝\n\n### 2. 商品主图提取 (ProductImageExtractor)\n**尝试静默获取商品主图**:\n1. 发起 HTTP 请求获取商品页面 HTML\n2. 根据以下特征判断商品主图：\n - 图片 URL 符合阿里图片服务模式（alicdn.com）\n - 包含 `ibank` 或 `imgextra` 标识\n - 过滤掉缩略图（如 `_50x50`、`_100x100`）\n3. 返回第一个符合条件的图片 URL\n\n**如果无法获取主图**:\n- 返回 `action: \"need_image_url\"` 信号\n- 提示用户手动输入商品图片 URL\n- 转到 image_search 流程完成功能\n\n### 3. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/alibaba.1688.find.product/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"imageUrl\": \"商品主图URL\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"itemId\": 984731164094,\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捨腰部按摩器\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"score\": \"0.97332934\",\n \"currentPrice\": 45.5,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"黑色 XL\",\n \"yxIndex\": 4.9,\n \"quantityBegin\": 2,\n \"unit\": \"件\",\n \"company\": \"广州某服饰有限公司\",\n \"soldOut\": 50000,\n \"storeAmount\": 12000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 122698013,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [\"满99减5\"],\n \"serviceInfos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n\n### 成功获取主图时\n```json\n{\n \"success\": true,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"source_image\": \"https://img.alicdn.com/xxx.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"同款商品标题\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"price\": 25.0,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"黑色 M\",\n \"yx_index\": 4.8,\n \"quantity_begin\": 1,\n \"unit\": \"\",\n \"supplier\": \"某服饰有限公司\",\n \"sold_count\": 30000,\n \"stock_amount\": 8000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [],\n \"service_infos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"棉\"}]\n }\n ],\n \"search_type\": \"link_search\",\n \"total_results\": 6\n}\n```\n\n### 无法获取主图时\n```json\n{\n \"success\": false,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"action\": \"need_image_url\",\n \"message\": \"无法自动获取商品主图，请手动输入商品图片 URL\",\n \"similar_products\": [],\n \"search_type\": \"link_search\",\n \"total_results\": 0\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/link_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── LinkParser # 链接解析器\n ├── ProductImageExtractor # 商品主图提取器\n ├── LinkSearchExecutor # 搜索执行器\n ├── link_search() # 主入口函数\n └── link_search_with_image() # 使用指定图片搜索\n```\n\n## 错误处理\n- **链接格式错误**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **不支持的平台**: 抛出 `ValueError(\"不支持的电商平台\")`\n- **无法获取主图**: 返回 `action: \"need_image_url\"` 信号\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n\n## 测试用例\n```python\n# 1688 链接\nlink_search(url=\"https://detail.1688.com/offer/895657286458.html\")\n\n# 淘宝链接\nlink_search(url=\"https://item.taobao.com/item.htm?id=1033765771797\")\n\n# 纯商品 ID\nlink_search(url=\"895657286458\")\n\n# 手动指定图片 URL\nlink_search_with_image(image_url=\"https://img.alicdn.com/xxx.jpg\", limit=10)\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n- `urllib.request`: 用于获取商品页面 HTML\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`text_search` 使用同一 API path (`/api/alibaba.1688.find.product/1.0.0`)\n- **降级策略**: 当无法获取主图时，提示用户手动输入图片 URL，转到 `image_search` 流程\n\n## 注意事项\n1. 静默获取主图依赖于页面的 HTML 结构，可能因页面变化而失效\n2. 部分商品页面可能需要登录才能访问，此时无法获取主图\n3. 建议用户直接提供商品图片 URL 以获得更稳定的搜索结果\n4. 返回的商品数据结构与 image_search 一致\n\n### 平台自动提取主图支持\n\n| 平台 | 自动提取主图 | 说明 |\n|------|-------------|------|\n| **1688** | ✅ 支持 | 自动从商品页面提取主图 |\n| **淘宝** | ❌ 不支持 | 需要用户手动提供图片 URL |\n| **天猫** | ❌ 不支持 | 需要用户手动提供图片 URL |\n\nFile v0.27.0:references/capabilities/text_search.md\n\n# Capability: text_search (文本搜索)\n\n## 功能说明\n通过用户输入的关键词或自然语言描述，在 1688 平台搜索匹配的商品列表。与 image_search 和 link_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 找商品、搜商品、想要 XX、帮我找 XX\n\n**Capability 识别特征**:\n- 用户输入包含商品描述性语言\n- 不包含图片附件\n- 不包含完整 URL 链接\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py text_search --query \"搜索关键词\" [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--query` | `-q` | 搜索关键词 | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 {baseDir}/cli.py text_search -q \"黑色连帽卫衣\"\n\n# 指定返回数量\npython3 {baseDir}/cli.py text_search -q \"手机壳\" -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py text_search -q \"男士牛仔裤\" -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py text_search -q \"冲锋衣\" -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py text_search -q \"卫衣\" --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py text_search -q \"手机壳\" --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py text_search -q \"手机壳\" --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py text_search -q \"男士牛仔裤 修身\" -p 1688 -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"query\": \"string (required) - 搜索关键词\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n### 1. 查询处理\n直接使用用户输入的关键词作为搜索条件。\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/alibaba.1688.find.product/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"query\": \"搜索关键词\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"itemId\": 984731164094,\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捨腰部按摩器\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"score\": \"0.97332934\",\n \"currentPrice\": 45.5,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"黑色 XL\",\n \"yxIndex\": 4.9,\n \"quantityBegin\": 2,\n \"unit\": \"件\",\n \"company\": \"广州某服饰有限公司\",\n \"soldOut\": 50000,\n \"storeAmount\": 12000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 122698013,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [\"满99减5\"],\n \"serviceInfos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"query\": \"黑色连帽卫衣\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"2024新款黑色连帽卫衣男宽松加绒加厚秋冬季外套\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.95,\n \"price\": 45.5,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"黑色 XL\",\n \"yx_index\": 4.9,\n \"quantity_begin\": 2,\n \"unit\": \"件\",\n \"supplier\": \"广州某服饰有限公司\",\n \"sold_count\": 50000,\n \"stock_amount\": 12000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [\"满99减5\"],\n \"service_infos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}]\n }\n ],\n \"search_type\": \"text_search\",\n \"total_results\": 6\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/text_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── TextSearchExecutor # 搜索执行器\n └── text_search() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无搜索结果**: 返回空数组\n\n## 测试用例\n```python\n# 基础搜索\ntext_search(query=\"黑色连帽卫衣\")\n\n# 多关键词搜索\ntext_search(query=\"黑色连帽卫衣 宽松 加绒\")\n\n# 限定数量\ntext_search(query=\"手机壳\", limit=10)\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`link_search` 使用同一 API path (`/api/alibaba.1688.find.product/1.0.0`)\n- **区别**: text_search 通过 `query` 参数传递搜索词，而非图片\n\n# 注意事项\n1. 搜索关键词应尽量准确，避免过于宽泛\n2. 返回的商品数据结构与 image_search 一致\n3. **--query 必须完整保留用户意图**：禁止丢弃用户提及的排序要求（如\"按销量倒排\"）、价格筛选（如\"100元以下\"）、品牌限定等信息，这些要素必须一并携带到 query 参数中\n\n### --query 构造示例\n\n| 用户输入 | ✅ 正确的 --query | ❌ 错误的 --query |\n|---------|------------------|------------------|\n| 帮我找一件深绿色的始祖鸟同款冲锋衣，按销量倒排 | \"深绿色 始祖鸟同款 冲锋衣 销量排序\" | \"深绿色冲锋衣 始祖鸟同款\"|\n| 找价格100元以下的男士牛仔裤 | \"男士牛仔裤 价格100元以下\" | \"男士牛仔裤\" |\n\nFile v0.27.0:references/common/error-handling.md\n\n# 通用错误处理\n\n所有命令在遇到以下 HTTP / 业务错误时，遵循统一处理策略。\n\n## 错误码与 Agent 应对\n\n| 错误码 | 含义 | Agent 应对 |\n|--------|------|-----------|\n| — | AK 未配置（命令入口预检查） | 输出 AK 引导话术（见 SKILL.md） |\n| 400 | 参数不合法 | 检查用户输入（关键词、渠道、商品ID等）是否正确 |\n| 401 | 鉴权无效（AK 错误或已过期） | 输出 AK 引导话术（见 SKILL.md），引导用户重新配置 |\n| 429 | 请求被限流 | 建议用户稍后重试（通常等待 1-2 分钟） |\n| 500 | 服务端异常 | 建议用户稍后重试，如持续出现建议联系客服 |\n\n## 网络异常\n\nCLI 已内置 3 次重试（指数退避），重试耗尽后返回 `success: false`。\n\nAgent 应对：告知用户\"网络异常，请检查网络连接后重试\"。\n\n## 识别方式\n\n当 CLI 输出 `success: false` 时：\n\n1. 输出 `markdown` 字段（用户可读的错误描述）\n2. 检查 `markdown` 中的关键词（如 \"AK 未配置\"、\"401\"、\"授权过期\"、\"限流\"），按 SKILL.md 异常处理表追加对应引导\n\n## 各能力特有异常\n\n通用错误外的业务异常，见各能力文档的\"业务异常处理\"段。\n\n## 沙箱/权限异常\n\n当 `markdown` 包含 \"沙箱\"、\"权限\"、\"Permission denied\" 关键词时：\n- 提示用户授予目录访问权限\n- 或在 IDE 设置中允许 Skill 访问所需目录\n\nFile v0.27.0:references/skill埋点说明.md\n\n# Skill 埋点说明\n\n本文描述 **1688-open-skill-template** 中 Skill 调用埋点的上报时机、请求内容与失败策略，便于对接网关统计与二次开发对齐行为。\n\n## 1. 作用概述\n\n埋点用于在 **Skill 网关**侧统计 Skill 被调用的次数与基础元信息（名称、版本、渠道、场景）。实现集中在 `scripts/_tracker.py` 的 `report_skill_usage()`，由统一 CLI 入口 `cli.py` 在命令生命周期末尾触发。\n\n## 2. 上报时机\n\n| 场景 | 是否上报 | 说明 |\n|------|----------|------|\n| 已识别子命令（如 `ali_dingtalk`、`configure`），且子命令 `main()` **正常执行完毕**（无未捕获异常、未中途 `sys.exit`） | **是** | 无论业务 JSON 中 `success` 为 `true` 或 `false`（例如 AK 未配置、参数校验失败等只要进程未崩），均在子命令返回后上报一次。 |\n| 未传入子命令、子命令名不在注册表、或展示用法后 `sys.exit(1)` | **否** | `cli.py` 在调用子模块前即退出，不会执行埋点逻辑。 |\n| 子命令内 `argparse` 报错并 `sys.exit`（如必填参数缺失） | **否** | 进程在 `module.main()` 内退出，**不会**回到 `cli.py` 的埋点代码。 |\n| 子命令 `main()` 抛出**未捕获**异常 | **否** | 异常向上传播，埋点代码未执行。 |\n\n**小结**：埋点表示「一次 CLI 子命令入口已跑完主流程」，偏 **会话级 / 调用次数** 统计，**不**区分具体子命令名（请求体中无命令字段），也**不**保证业务一定成功。\n\n## 3. 上报接口与传输\n\n| 项 | 值 |\n|----|-----|\n| 方法 | `POST` |\n| 路径 | `/api/alibaba.1688.report.skills.usage/1.0.0` |\n| 完整 URL | 与业务 API 相同网关：`https://gateway.1688.com` + 路径（见 `scripts/_http.py` 中 `BASE_URL`） |\n| 请求体 | JSON，`Content-Type: application/json; charset=utf-8` |\n| 鉴权 | 与能力调用一致：通过 `get_auth_headers()` 注入签名；**未配置 AK 时** `api_post` 会抛鉴权类异常，由埋点模块捕获（见下文），**不会**向网关发出 HTTP 请求。 |\n\n网络层对 **连接错误 / 超时** 有有限次重试（与 `_http.api_post` 一致）；HTTP 4xx/5xx 或业务 `success: false` 会转为异常并由埋点侧吞掉。\n\n## 4. 请求体字段\n\n上报 JSON 字段与含义如下（与代码一一对应）。\n\n| 字段 | 类型 | 取值说明 |\n|------|------|----------|\n| `apiName` | `null` | 固定为 JSON `null`，占位或网关约定字段。 |\n| `skillsName` | string | Skill 名称，来自环境变量 `SKILL_NAME`，缺省为 `1688-open-skill-template`。 |\n| `version` | string | Skill 版本，来自 `SKILL_VERSION`，缺省为 `1.0.0`。 |\n| `scene` | string | 固定为 `\"CLI\"`，表示当前模板通过命令行入口触发。 |\n| `channel` | string | 发布渠道，来自 `SKILL_CHANNEL`，缺省为 `clawhubai`。 |\n\n**环境变量来源**：模块加载时会读取项目根目录 `.env` 并写入 `os.environ`（**不覆盖**已存在的环境变量，便于 CI/CD 注入覆盖本地文件）。\n\n## 5. 失败与日志策略\n\n- `report_skill_usage()` 整体包裹在 `try/except` 中：**任意异常均不向外抛出**，主命令的退出码与输出不受影响。\n- 失败时通过 logger `1688_tracker` 输出 **DEBUG** 级别日志：`埋点上报失败（已忽略）: ...`。\n- `cli.py` 在调用 `report_skill_usage()` 外层还有一次 `try/except`，避免导入埋点模块等极端情况影响进程。\n\n若需在本地排查埋点，可将日志级别调到 DEBUG 并关注 `1688_tracker` / `1688_http`。\n\n## 6. 与模板扩展的关系\n\n新增 `capabilities//cmd.py` 并注册命令后，只要仍由根目录 `cli.py` 统一调度且在子命令 `main()` 正常返回后回到 `cli.py`，**会自动沿用同一套埋点**，无需在子命令内重复调用。\n\n若希望按子命令或按业务结果细分统计，需要在网关契约允许的前提下扩展请求体或增加独立埋点逻辑（当前模板未实现）。\n\n## 7. 相关文件索引\n\n| 文件 | 职责 |\n|------|------|\n| `scripts/_tracker.py` | 读取 `.env`、组装请求体、调用 `api_post` 上报。 |\n| `cli.py` | 命令分发结束后调用 `report_skill_usage()`。 |\n| `scripts/_http.py` | `api_post`：网关地址、签名、重试与错误映射。 |\n| `SKILL.md` | 面向使用方的环境变量与埋点摘要。 |\n\nFile v0.27.0:skill-card.md\n\n## Description:\n\nFinds and compares 1688 products from text, image, or product-link inputs, returning sourced options for wholesale, cross-border, hot-selling, and criteria-filtered shopping workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[1688aiinfra](https://clawhub.ai/user/1688aiinfra)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and sourcing agents use this skill to search 1688 for product candidates, find same or similar items from images or links, and compare options for wholesale purchasing decisions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Configuration status may reveal the full 1688 AK in normal output.\n\nMitigation: Avoid running status checks in shared or logged sessions, redact any displayed key, and rotate the AK if it is exposed.\n\nRisk: Link-based search disables HTTPS verification when scraping product links.\n\nMitigation: Use link search only on trusted networks until normal TLS verification is restored.\n\nRisk: The skill depends on a 1688 AK and gateway flow for product results.\n\nMitigation: Install and use it only when the publisher and gateway flow are trusted, and stop rather than falling back to unsourced web searches if the CLI or API fails.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/1688aiinfra/skills/1688-product-find)\n- [Text search capability](references/capabilities/text_search.md)\n- [Image search capability](references/capabilities/image_search.md)\n- [Link search capability](references/capabilities/link_search.md)\n- [Compare capability](references/capabilities/compare.md)\n- [AK configuration capability](references/capabilities/configure.md)\n- [Common error handling](references/common/error-handling.md)\n- [1688 AK portal](https://clawhub.1688.com/)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [JSON containing a success flag, Markdown for user-facing results, and structured product data]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Product outputs are expected to be sourced from CLI/API results and commonly include tables with product names, prices, suppliers, service details, and detail links.]\n\n## Skill Version(s):\n\n0.27.0 (source: server release metadata; artifact frontmatter: 1.7.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.27.0:tests/testcases.json\n\n[\n {\n \"id\": \"TC001\",\n \"name\": \"基础文本搜索\",\n \"input\": \"我要买打印纸\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"打印纸\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 包含核心关键词'打印纸'\",\n \"返回商品数 ≤ limit\",\n \"每个商品含标题/价格/链接\",\n \"数据来自 API 真实返回，不编造\"\n ]\n }\n },\n {\n \"id\": \"TC002\",\n \"name\": \"排序意图保留\",\n \"input\": \"卖得最好的蓝牙耳机有哪些\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"蓝牙耳机\", \"销量\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 保留排序意图：'卖得最好' → 包含'销量排序'或'销量'\",\n \"返回商品数 = 10（默认 limit）\",\n \"每个商品含标题/价格/链接\",\n \"不编造数据，所有展示数据可在 tool_response 中找到来源\"\n ]\n }\n },\n {\n \"id\": \"TC003\",\n \"name\": \"多条件搜索（价格+排序+数量）\",\n \"input\": \"找10款夏季连衣裙，价格50-100元，按销量排序\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"夏季连衣裙\", \"价格50-100元\", \"销量排序\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留：商品描述 + 价格筛选 + 排序条件\",\n \"--limit 正确设为 10\",\n \"返回商品数 ≤ 10\",\n \"数据真实，所有价格来自 API 返回\"\n ]\n }\n },\n {\n \"id\": \"TC004\",\n \"name\": \"数量与价格约束（非默认 limit）\",\n \"input\": \"找15个10块钱以下的发圈，从便宜到贵排\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"发圈\", \"价格10元以下\", \"价格从低到高\"],\n \"limit\": 15,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留：商品描述 + 价格约束 + 排序方向\",\n \"--limit 正确设为 15（用户说'找15个'）\",\n \"返回商品数 ≤ 15\",\n \"全部价格 < 10元\"\n ]\n }\n },\n {\n \"id\": \"TC005\",\n \"name\": \"大数量请求（超出 API 上限）\",\n \"input\": \"找100个20-80元的夏季女装连衣裙，按销量从高到低排\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"夏季女装连衣裙\", \"价格20-80元\", \"销量从高到低\"],\n \"limit\": 100,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留全部意图\",\n \"--limit 正确设为 100\",\n \"返回商品数 ≤ 100（API 单次上限约30-40条，实际返回数小于请求数属正常）\",\n \"数据真实，不编造\"\n ]\n }\n }\n]\n\nFile v0.27.0:requirements.txt\n\nrequests>=2.28.0\nkeyring>=25.0\nPillow>=10.0.0\n\nArchive v1.7.0: 47 files, 109685 bytes\n\nFiles: cli.py (16289b), references/capabilities/compare.md (13214b), references/capabilities/configure.md (5135b), references/capabilities/image_search.md (8527b), references/capabilities/link_search.md (10523b), references/capabilities/text_search.md (8050b), references/common/error-handling.md (1438b), references/skill埋点说明.md (4401b), requirements.txt (45b), scripts/_auth.py (13053b), scripts/_const.py (535b), scripts/_errors.py (1726b), scripts/_http.py (8594b), scripts/_image.py (5315b), scripts/_output.py (17933b), scripts/_tracker.py (2478b), scripts/authorize.py (8285b), scripts/callback_server.py (18088b), scripts/capabilities/compare/__init__.py (0b), scripts/capabilities/compare/cmd.py (3819b), scripts/capabilities/compare/service.py (9962b), scripts/capabilities/configure/__init__.py (0b), scripts/capabilities/configure/cmd.py (4228b), scripts/capabilities/configure/service.py (3772b), scripts/capabilities/image_search/__init__.py (55b), scripts/capabilities/image_search/cmd.py (4558b), scripts/capabilities/image_search/service.py (5564b), scripts/capabilities/link_search/__init__.py (55b), scripts/capabilities/link_search/cmd.py (5205b), scripts/capabilities/link_search/service.py (20336b), scripts/capabilities/text_search/__init__.py (55b), scripts/capabilities/text_search/cmd.py (3791b), scripts/capabilities/text_search/service.py (3615b), scripts/encrypted_store.py (2038b), scripts/env_writer.py (2294b), scripts/main.py (6850b), scripts/pkce.py (836b), scripts/scope_manager.py (4836b), scripts/secure_store.py (4653b), scripts/settings.py (686b), scripts/templates/callback.html (8108b), scripts/templates/product_list.html (15688b), scripts/token_manager.py (10306b), skill-card.md (3014b), SKILL.md (14209b), tests/testcases.json (2807b), _meta.json (136b)\n\nFile v1.7.0:SKILL.md\n\n---\nname: 1688-product-find\nversion: \"1.7.0\"\ndescription: |\n 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。\n 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找供应商。\nmetadata: {\"openclaw\": {\"emoji\": \"🔍\", \"requires\": {\"bins\": [\"python3\"]}, \"primaryEnv\": \"ALI_1688_AK\"}}\n---\n\n# 1688-product-find (1688找商品Skill)\n统一入口：`python3 {baseDir}/cli.py [options]`\n\n## 严格禁止 (NEVER DO)\n- 不要编造商品价格、链接、`productId`、规格或供货信息，所有商品内容必须来自工具返回\n- 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力\n- 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接\n- **禁止在 AK 未配置或命令执行失败时，自行通过浏览器访问 1688 网站搜索商品**。所有搜索必须通过 CLI 命令 + API 完成，不存在\"浏览器降级\"方案。遇到 AK 缺失或 API 错误时，只能按「错误处理」提示用户，不得尝试绕过\n- **禁止在命令报错后使用网页搜索引擎替代本 Skill 的搜索能力**。如果 CLI 命令失败，应引导用户解决问题（配置 AK、检查路径等），而非切换到其他搜索方式\n- **禁止不读 reference 文档直接执行命令**。首次执行任何命令前，必须先阅读对应的 reference 文件（见「执行前置」）\n\n## 意图判断\n\n### 触发本技能（满足任一即触发）\n- 用户用自然语言描述想要的商品（如\"帮我找一件黑色卫衣\"、\"我要买打印纸\"）\n- 用户上传商品图片并表达找同款/找相似意图（如\"帮我找同款\"、\"有类似的吗\"）\n- 用户提供商品链接并要求找同款（如\"帮我找这个商品的同款\"）\n- 用户使用触发关键词：找商品、找同款、搜商品、想要XX、帮我找、图片找货、链接找货、以图搜图\n- 用户在搜索结果中选定商品后要求\"比价\"、\"对比\"、\"找更便宜的\"\n- 用户上传图片/链接并提到\"比价\"、\"同款低价\"、\"哪家便宜\"、\"进行比较\"\n\n### 不触发本技能（明确不处理）\n- 用户要下单、支付、结算（如\"我现在就要下单付款\"）\n- 用户查物流、查订单状态（如\"我的订单物流到哪了\"）\n- 用户要管理库存、修改商品信息\n- 用户仅闲聊，未表达任何找商品意图\n\n### 命令选择决策树\n\n```\n用户输入\n├─ 纯文本描述商品 → text_search\n├─ 上传图片/链接\n│ ├─ 包含\"比价/比较/对比/哪家便宜\"等关键词 → compare（一步到位）\n│ └─ 仅\"找同款/找相似/搜这个\" → image_search 或 link_search\n└─ 已展示搜索结果，用户选中某款后说\"比价\" → compare（从结果取 image_url）\n```\n\n## Tool 总览\n\n| Tool 名称 | 用途 | 调用语法 |\n|-----------|------|---------|\n| `text_search` | 文本搜索商品 | `python3 cli.py text_search --query \"黑色连帽卫衣\"` |\n| `image_search` | 图片以图搜图 | `python3 cli.py image_search --image \"/path/to/image.jpg\"` |\n| `link_search` | 链接找同款 | `python3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"` |\n| `compare` | 商品比价 | `python3 cli.py compare --image \"商品图片URL\" [--query \"规格关键词\"]` 或 `python3 cli.py compare --url \"商品链接\"` |\n| `configure` | AK 管理 | `cli.py configure YOUR_AK`（设置）/ `--status`（查看）/ `--clear`（清除）/ `--reset NEW_AK`（重置） |\n| `get_ak` | 自动获取 AK | `cli.py get_ak` |\n\n所有命令输出 JSON：`{\"success\": bool, \"markdown\": str, \"data\": {...}}`\n\n## ⚠️ 执行前置（首次命中能力时必须）\n\n**首次执行任何命令前，必须先完整阅读对应的 reference 文件，按文件中的使用示例调用。禁止跳过此步骤直接执行命令。**\n\n| 命令 | 执行前必读 |\n|------|-----------|\n| `configure` | `references/capabilities/configure.md` |\n| `text_search` | `references/capabilities/text_search.md` |\n| `image_search` | `references/capabilities/image_search.md` |\n| `link_search` | `references/capabilities/link_search.md` |\n| `compare` | `references/capabilities/compare.md` |\n\n> reference 文件中包含完整的参数说明、使用示例、输出格式和注意事项。Agent 必须按 reference 中的示例格式构造命令，不得凭猜测拼接参数。\n\n## 核心工作流\n\nAgent 根据用户意图，**先读 reference → 再按示例执行命令**（命令速查见上方「Tool 总览」）。\n各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「错误处理」应对即可。\n\n### 比价流程（特殊工作流）\n\n**核心原则：图片/链接默认为找同款，仅用户明确要求比价时才用 compare**\n\n**场景1：直接比价**（一步到位）\n- 用户上传图片并要求比价 → 直接执行 `compare --image <图片> --query <关键词>`\n- 用户给链接并要求比价 → 直接执行 `compare --url <链接> [--query <关键词>]`\n- **禁止**先执行 `image_search` 或 `link_search`，`compare` 内部已包含图片搜索和链接解析逻辑\n\n**场景2：选品后比价**\n- 用户从搜索结果选中某款 → 提取 `data.similar_products[N].image_url` → 执行 `compare --image `\n\n**⚠️ 关键约束**：\n- **一次到位**：\"找同款并比价\" → 直接 `compare`（图片用 `--image`，链接用 `--url`），不拆分两步\n- **limit 默认值**：保持 TOP 3，除非用户明确要求\n- **意图判断**：上传图片/链接时，仅含\"比价/比较\"关键词才用 `compare`\n\n## 输出完整性要求\n\n**展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。**\n\n`markdown` 字段中包含完整的 Markdown 表格，Agent 展示时**必须完整输出**，禁止以下行为：\n- **禁止省略或截断表格行**：返回了多少条商品就展示多少条，不得用\"等\"、\"...\"或\"仅展示前 N 条\"代替\n- **禁止丢弃表格列**：每行必须包含完整的 序号、商品名称、价格、供应商、服务与卖点、链接（详情链接）等全部列\n- **禁止丢失商品链接**：`detail_url`（商品详情页链接）是核心字段，必须在表格中完整展示，不得省略或替换为其他内容\n- **禁止重新格式化**：不得将表格改写为列表、卡片或其他格式，直接原样输出 `markdown` 字段内容\n- **禁止合并或二次加工**：Agent 的分析、总结等内容必须追加在 `markdown` 字段输出**之后**，不得将其混入表格或替代表格\n\n- **后续操作支持**：`markdown` 末尾包含 **「后续操作」** 小节，引导用户生成钉钉表格：\n - 当用户回复「生成钉钉表格」时，Agent 应使用钉钉表格 MCP 工具，将 `data.similar_products` 中的商品信息写入钉钉表格。**导出字段必须严格包含如下字段**：\n | 表头 | 字段 | 说明 |\n |:--|:--|:--|\n | 商品ID | `product_id` | 商品唯一标识 |\n | 商品名称 | `title` | 商品标题 |\n | 主图URL | `image_url` | 商品主图链接 |\n | 详情链接 | `detail_url` | 商品详情页URL |\n | 价格 | `price` | 单价（元） |\n | 规格ID | `sku_id` | SKU 标识 |\n | 规格 | `sku_title` | SKU 规格描述 |\n | 严选指数 | `yx_index` | 严选推荐指数 |\n | 起批量 | `quantity_begin` | 最低起订量 |\n | 单位 | `unit` | 计量单位 |\n | 供应商 | `supplier` | 供应商名称 |\n | 销量 | `sold_count` | 累计销量 |\n | 库存 | `stock_amount` | 当前库存 |\n | 促销标签 | `promotion_tags` | 促销活动标签（多值用、分隔） |\n | 服务保障 | `service_infos` | 服务保障信息（取 value 字段，多值用、分隔） |\n | 卖点 | `selling_points` | 商品卖点（取 value 字段，多值用、分隔） |\n\n\n## 错误处理\n\n任何命令输出 `success: false` 时：\n\n1. **先输出 `markdown` 字段**（已包含用户可读的错误描述）\n2. **再根据关键词追加引导**（详细错误码见 `references/common/error-handling.md`）：\n\n| markdown 关键词 | Agent 额外动作 |\n|----------------|--------------|\n| \"AK 未配置\" 或 \"AK 未就绪\" | **停止一切搜索尝试**，优先执行 `python3 cli.py get_ak` 自动获取 AK；如自动获取失败，引导用户前往 https://clawhub.1688.com/ 获取后执行 `python3 cli.py configure YOUR_AK`。**禁止浏览器替代** |\n| \"签名无效\" 或 \"401\" | 提示用户检查 AK 是否正确或已过期，引导重新 configure |\n| \"图片路径无效\" | 提示用户检查图片路径是否存在 |\n| \"无法自动获取商品主图\" | 引导用户手动提供商品图片 URL，使用 `--image` 参数 |\n| \"限流\" 或 \"429\" | 建议用户等待 1-2 分钟后重试 |\n| \"格式异常\" 或 \"HTTP 错误 500\" | 提示用户稍后重试，可能是 API 返回异常 |\n| \"沙箱\" 或 \"权限\" 或 \"Permission denied\" | 提示用户授予目录访问权限，或在 IDE 设置中允许 Skill 访问所需目录 |\n| 其他 | 仅输出 markdown，**不得自行发起浏览器搜索** |\n\n## 参数补齐引导话术\n\n> **文本搜索**：请描述您想要的商品，例如：\"帮我找一件黑色连帽卫衣，宽松款的\"\n\n> **图片搜索**：请上传商品图片，我会帮您找到同款或相似商品。\n\n> **链接搜索**：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。\n\n---\n\n## 附录\n\n### 环境变量（.env）\n\n项目根目录的 `.env` 文件存储 skill 基础信息，供埋点上报等模块读取。发布到不同环境时可直接替换该文件中的变量值。\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `SKILL_NAME` | `1688-product-find` | skill 名称 |\n| `SKILL_VERSION` | `1.7.0` | skill 版本号 |\n| `SKILL_CHANNEL` | `clawhub` | 发布渠道 |\n\n> 已存在的系统环境变量优先级高于 `.env`，CI/CD 注入的变量不会被覆盖。\n\n### 埋点上报\n\n每次 CLI 命令执行时，自动向 skill 网关上报一次调用记录，用于统计 skill 调用次数。\n\n- **实现位置**：`scripts/_tracker.py` → `report_skill_usage()`，在 `cli.py` 的 `main()` 中每次命令执行后自动调用\n- **上报接口**：`POST /api/reportSkillsUsage/1.0.0`\n- **上报参数**：\n\n | 参数 | 值来源 | 说明 |\n |------|--------|------|\n | `apiName` | 固定 `null` | 固定传 null |\n | `skillsName` | `.env` `SKILL_NAME` | skill 名称 |\n | `version` | `.env` `SKILL_VERSION` | skill 版本号 |\n | `scene` | 固定 `CLI` | 固定值 |\n | `channel` | `.env` `SKILL_CHANNEL` | 发布渠道 |\n\n- **失败处理**：上报失败静默忽略，不影响主流程\n\n### 文件清单\n\n| 路径 | 类型 | 用途 |\n|------|------|------|\n| `SKILL.md` | 主文件 | 技能入口、意图判断、工作流、错误处理 |\n| `cli.py` | CLI 入口 | 统一命令行接口，自动发现 capabilities |\n| `scripts/` | 脚本目录 | 核心实现（认证、HTTP、输出格式化等） |\n| `references/capabilities/configure.md` | 参考文档 | AK 配置能力详细说明 |\n| `references/capabilities/text_search.md` | 参考文档 | 文本搜索能力详细说明 |\n| `references/capabilities/image_search.md` | 参考文档 | 图片搜索能力详细说明 |\n| `references/capabilities/link_search.md` | 参考文档 | 链接搜索能力详细说明 |\n| `references/capabilities/compare.md` | 参考文档 | 商品比价能力详细说明 |\n| `references/common/error-handling.md` | 参考文档 | 通用错误处理策略 |\n| `tests/testcases.json` | 测试用例 | 典型输入输出样例 |\n\n### 技术说明\n\n- **无状态设计**：每次请求独立执行，不依赖历史上下文。多轮 refinement（如\"再找便宜一点的\"）需 Agent 将上下文重新拼接到 query 参数中\n\n### 更新日志\n\n- v1.7.0 (2026-04-15): 所有搜索 API 新增 `tags`（TC标/品池标签，默认 4306497）和 `icTags`（IC标/品池标签）两个入参，贯穿 CLI → service → API 全链路；搜索结果展示统一为表格输出；同步更新全部 reference 文档（注：可视化商品墙 + 后续操作引导已暂时禁用）\n- v1.6.0 (2026-04-19): 「打开详情」改为页面内抽屉展示（不再跳转新窗口）；底部「复制选中链接」改为「我要下单」；精简搜索结果后的操作引导文案\n- v1.5.0 (2026-04-15): compare 命令新增 `--url` 参数，支持直接传入商品链接比价，内部自动解析链接并提取主图\n- v1.4.0 (2026-04-14): 新增商品比价能力（compare），支持搜索后选品比价、纵向对比表输出、销量/价格/服务三维度自动选品\n- v1.3.0 (2026-04-14): 代码精简和重构\n- v1.2.0 (2026-04-09): 文档结构标准化（章节重命名），新增意图判断章节，新增 API 空数据过滤，新增测试用例\n- v1.1.0 (2026-03-27): 新增 `cli.py` 统一 CLI 入口，简化命令调用方式\n- v1.0.0 (2026-03-27): 初始版本，包含三大核心搜索能力（text_search、image_search、link_search）\n\nFile v1.7.0:_meta.json\n\n{\n \"ownerId\": \"kn76msg8cwkep3b08z7zffx9fx82p5wj\",\n \"slug\": \"1688-product-find\",\n \"version\": \"1.7.0\",\n \"publishedAt\": 1778484340022\n}\n\nFile v1.7.0:references/capabilities/compare.md\n\n# Capability: compare (商品比价)\n\n## 功能说明\n基于用户选中商品的图片或商品链接，通过以图搜图找到同款商品，自动按销量、价格、服务三个维度各选出 1 款代表性商品，生成纵向对比表。\n\n## 触发方式\n**Skill 级触发词**: 比价、对比、哪家便宜、找更便宜的、同款低价、进行比较\n\n**Capability 识别特征**:\n- 用户上传图片/链接并**明确要求比价**（如“找同款并比价”、“找到同款进行比较”）\n- 用户在搜索结果中选定某款商品后要求比价/对比\n- 用户使用“比一比”、“哪家便宜”、“低价同款”等关键词\n\n**❗ 商品链接直接比价**：\n- 用户给到商品链接且意图包含比价 → 直接使用 `compare --url`，一步到位\n- **禁止**先执行 `link_search` 再执行 `compare`，`compare --url` 内部已包含链接解析+主图提取+比价逻辑\n\n**⚠️ 意图判断核心原则**:\n- **上传图片/链接时，默认是找同款，使用 `image_search` 或 `link_search`**\n- **仅在用户明确提到“比价/比较/对比”时，才使用 `compare`**\n- `compare` 命令内部已包含以图搜图/链接解析逻辑，一步到位完成搜索+比价\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。\n- 需要商品图片或商品链接（支持以下四种输入方式，二选一）：\n - **URL 图片**：在线图片链接，如 `https://img.alicdn.com/xxx.jpg`\n - **本地图片**：本地文件路径，如 `/path/to/image.jpg`（自动预处理：缩放 + 格式转换）\n - **搜索结果中的图片**：从前序搜索结果的 `image_url` 字段提取\n - **商品链接/ID**：1688/淘宝/天猫商品链接或纯商品 ID（自动解析链接并提取主图）\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py compare [--image \"商品图片URL\"] [--url \"商品链接\"] [--query \"附加关键词\"] [--limit 3] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n> `--image` 和 `--url` 二选一，必须提供其中一个。两者都提供时优先使用 `--image`。\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 商品图片 URL 或本地路径（与 `--url` 二选一） | 可选 |\n| `--url` | `-u` | 商品链接或商品 ID（自动提取主图，与 `--image` 二选一） | 可选 |\n| `--query` | `-q` | 附加关键词（规格、品类等） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 对比商品数量 | 3 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n**支持的图片输入格式**：\n- URL：`https://xxx.jpg`、`https://xxx.png` 等\n- 本地路径：`/path/to/image.jpg`、`C:\\Users\\image.png` 等（支持 JPG、PNG、GIF、BMP、WEBP 等格式）\n- 本地图片会自动预处理：超尺寸自动缩放、非 JPEG 格式自动转换\n\n### 使用示例\n```bash\n# 场景1：基本比价（一步到位，无需先执行 image_search）\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒙奇奇 15CM 毛绒\"\n\n# 场景2：通过商品链接直接比价（一步到位，无需先执行 link_search）\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 场景3：通过纯商品 ID 比价\npython3 {baseDir}/cli.py compare -u \"895657286458\" -q \"不锈钢漏勺\"\n\n# 场景4：按价格从低到高排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc\n\n# 场景5：按销量从高到低排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s sold_desc\n\n# 场景6：降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" --score-level medium\n\n# 场景7：组合使用 - 按价格排序 + 中等相关性\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc --score-level medium\n\n# 场景8：使用默认 TOP 3 对比（推荐，不要随意修改 limit）\npython3 {baseDir}/cli.py compare -i \"https://img.alicdn.com/imgextra/xxx.jpg\"\n\n# 场景9：指定采购件数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" --purchase-amount 200\n\n# 场景10：完整参数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" -l 3 -s yx_desc --score-level high --purchase-amount 100 --tags \"4306497\"\n\n# 场景11：链接比价 + 关键词\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\" -q \"不锈钢漏勺\"\n```\n\n## 处理流程\n\n### 1. 获取商品图片\n- **图片输入**（`--image`）：直接使用图片 URL 或本地路径\n- **链接输入**（`--url`）：自动解析商品链接，提取商品主图（复用 link_search 的 LinkParser + ProductImageExtractor）\n - 支持 1688/淘宝/天猫链接及纯商品 ID\n - 提取失败时返回错误提示，建议用户改用 `--image` 参数\n\n### 2. 以图搜图获取同款候选\n- 使用商品图片 URL 调用 `/api/find_product/1.0.0` 接口\n- 固定搜索 20 条候选商品，确保三维度选品有足够样本\n- 若用户提供了 `--query` 关键词，同时传入 API 请求体提升相关性\n- 支持通过 `--sort` 参数控制排序方式\n- 支持通过 `--score-level` 参数控制相关性档位\n\n### 2. 三维度自动选品\n独立评估每个维度的最佳商品（不互斥），同一商品赢得多个维度时合并标签：\n\n| 维度 | 选品策略 | 标签 |\n|------|---------|------|\n| 销量最高 | 按 `sold_count` 降序取第 1 | \"销量最高\" |\n| 价格最低 | 按 `price` 升序取第 1（排除无价格） | \"价格最低\" |\n| 综合最优 | 按 `yx_index` 倒序取第 1 | \"综合最优\" |\n\n> **标签合并规则**：当同一商品同时满足多个维度最优时，合并标签展示（如 \"销量最高 且 价格最低 且 综合最优\"），最终输出的商品数量由去重结果决定（1~3 款），不会用额外商品填充。\n\n### 3. 自适应输出格式\n- **3 款不同商品**：标准纵向对比表格（3 列）\n- **2 款不同商品**：精简对比表格（2 列），合并标签展示\n- **1 款商品**（三维度均为同一商品）：卡片式展示，标签合并为 \"销量最高 且 价格最低 且 综合最优\"\n\n## 输出格式\n\n### 场景 A：多款商品对比表（2~3 列）\n```markdown\n| 维度 | 推荐 1 (销量最高) | 推荐 2 (价格最低) | 推荐 3 (综合最优) |\n|:-----|:----------------|:----------------|:----------------|\n| 商品 | 铂佳无磁不锈钢漏勺... | 加大不锈钢花椒漏勺... | 新款不锈钢汤勺饭店... |\n| 💰 单价 | ￥1.19 | ￥3.80 | ￥3.89 |\n| 📦 规格 | 20cm 细网 | 25cm 粗网 | 30cm 加密 |\n| ⭐ 严选指数 | 85.23 | 72.50 | 90.16 |\n| 📊 起批量 | 100件 | 50件 | 200件 |\n| 销量 | 1.2万 | 856 | 2340 |\n| 库存 | 有货 | 有货 | 有货 |\n| 服务 | 7天无理由、48h发货 | 包邮、7天无理由 | 7天无理由 |\n| 卖点 | 爆款热销 | 工厂直供 | 品质保障 |\n| 供应商 | 义乌XX日用.. | 揭阳XX不锈钢.. | 潮安XX厨具.. |\n| 链接 | [查看](url1) | [查看](url2) | [查看](url3) |\n```\n\n### 场景 B：标签合并对比表（2 列）\n当两个维度指向同一商品时，合并标签展示：\n```markdown\n| 维度 | 推荐 1 (销量最高 且 综合最优) | 推荐 2 (价格最低) |\n|:-----|:---------------------------|:-----------------|\n| 商品 | XX商品... | YY商品... |\n| ... | ... | ... |\n```\n\n### 场景 C：单款商品卡片（1 列）\n当三个维度均指向同一商品时，使用卡片式展示：\n```markdown\n**🏆 销量最高 且 价格最低 且 综合最优**\n\n| 维度 | 详情 |\n|:-----|:-----|\n| 商品 | XX不锈钢漏勺... |\n| 💰 单价 | ￥1.19 |\n| 📦 规格 | 20cm 细网 |\n| ⭐ 严选指数 | 85.23 |\n| 📊 起批量 | 100件 |\n| 销量 | 1.2万 |\n| 库存 | 有货 |\n| 服务 | 7天无理由、48h发货 |\n| 卖点 | 爆款热销 |\n| 供应商 | 义乌XX日用.. |\n| 链接 | [查看](url) |\n```\n\n### JSON 输出结构\n```json\n{\n \"success\": true,\n \"markdown\": \"纵向比价表 Markdown\",\n \"data\": {\n \"data\": {\n \"success\": true,\n \"source_image\": \"图片URL\",\n \"compare_products\": [...],\n \"search_type\": \"compare\",\n \"total_candidates\": 9,\n \"total_compared\": 3\n }\n }\n}\n```\n\n## 输出字段说明\n\n### 展示的字段\n\n| 字段名 | API 字段 | 说明 | 示例 |\n|--------|---------|------|------|\n| 商品 | `title` | 商品标题 | \"铂佳无磁不锈钢漏勺...\" |\n| 💰 单价 | `price` | 商品单价（元） | ￥1.19 |\n| 📦 规格 | `sku_title` | 规格详情/SKU 信息 | \"20cm 细网\" |\n| ⭐ 严选指数 | `yx_index` | 严选指数评分（两位小数，截断） | 85.23 |\n| 📊 起批量 | `quantity_begin` + `unit` | 起批量（拼接展示） | 100件 |\n| 销量 | `sold_count` | 销量数据 | 1.2万 |\n| 库存 | `stock_amount` | 库存状态 | 有货/无货 |\n| 服务 | `service_infos` | 服务标签列表 | 7天无理由、48h发货 |\n| 卖点 | `selling_points` | 卖点标签列表 | 爆款热销 |\n| 供应商 | `supplier` | 供应商名称 | 义乌XX日用.. |\n| 链接 | `detail_url` | 商品详情页链接 | [查看](url) |\n\n## 代码结构\n```\nscripts/capabilities/compare/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心比价逻辑\n ├── ImagePreprocessor # 图片预处理器（复用 image_search）\n ├── _count_service_tags() # 服务标签计数\n ├── _select_top() # 三维度选品策略\n ├── CompareExecutor # 比价执行器\n └── compare_products() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **链接无法提取主图**: 提示用户改用 `--image` 参数直接提供图片 URL\n- **链接格式无效**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **两个参数都未提供**: 抛出 `ValueError(\"必须提供 --image 或 --url 参数\")`\n- **图片路径无效**: 提示用户检查图片路径是否存在\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无匹配商品**: 返回 `success: true`，markdown 显示\"未找到可比价的同款商品\"\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_compare_table`: 输出格式化\n- `ImagePreprocessor`: 图片预处理（复用 image_search 逻辑）\n- `LinkParser` / `ProductImageExtractor`: 链接解析和主图提取（复用 link_search 逻辑）\n\n## 注意事项\n1. **意图判断**：\n - ✅ 用户上传图片 + “找同款” → 使用 `image_search`\n - ✅ 用户上传图片 + “找同款并比价” → 使用 `compare --image`\n - ✅ 用户给链接 + “找同款并比价” → 使用 `compare --url`\n - ✅ 搜索结果展示后，用户选中某款说“比价” → 使用 `compare --image`（从结果提取 image_url）\n2. `--image` 参数来源：\n - 用户直接上传的本地图片路径（用户说“找这款并比价”）\n - 前序搜索结果的 `image_url` 字段（用户已选中某款商品后要求比价）\n - 商家指定的图片 URL\n3. `--url` 参数来源：\n - 用户提供的商品链接（如 `https://detail.1688.com/offer/xxx.html`）\n - 纯商品 ID（如 `895657286458`）\n4. `--query` 参数用于传入用户提到的规格、品类等附加条件，提升搜索相关性\n5. **默认返回 TOP 3**，Agent 不应擅自修改 `--limit`，除非用户明确要求\n6. **排序参数**：`--sort` 可选，不传则使用 API 默认排序（相关性）\n7. **相关性档位**：`--score-level` 默认 `high`，如果高相关性结果不足，可提示用户是否降低为 `medium` 或 `low`\n8. **不存在浏览器降级方案**，AK 缺失或 API 失败时只能返回错误提示\n9. **🚫 常见错误**：\n - ❌ 错误：用户上传图片说“找同款” → 执行 `compare`（应该用 `image_search`）\n - ✅ 正确：用户上传图片说“找同款” → 执行 `image_search`\n - ❌ 错误：用户上传图片说“找同款并比价” → 先 `image_search` 再 `compare`\n - ✅ 正确：用户上传图片说“找同款并比价” → 直接 `compare --image `\n - ❌ 错误：用户给链接说“比价” → 先 `link_search` 再 `compare`\n - ✅ 正确：用户给链接说“比价” → 直接 `compare --url `\n\nFile v1.7.0:references/capabilities/configure.md\n\n# Capability: configure (AK配置和管理)\n\n## 使用示例\n\n```bash\n# 自动获取 AK（启动浏览器授权流程）\npython3 {baseDir}/cli.py get_ak\n\n# 配置 AK\npython3 {baseDir}/cli.py configure YOUR_AK_HERE\n\n# 查看 AK 配置状态（无参数等同于 --status）\npython3 {baseDir}/cli.py configure\npython3 {baseDir}/cli.py configure --status\n\n# 重置 AK（清除旧 Token + 配置新 AK）\npython3 {baseDir}/cli.py configure --reset NEW_AK_HERE\n\n# 清除 AK（同时清除关联的 OAuth Token）\npython3 {baseDir}/cli.py configure --clear\n\n```\n\n## 命令参数\n\n| 参数形式 | 说明 |\n|---------|------|\n| `` | 直接配置新 AK。若已有旧 AK 且不同，自动清除旧 Token |\n| `--status` | 查看当前 AK 配置状态（无参数调用时默认行为） |\n| `--clear` | 清除 AK 并同步清除关联的 OAuth Token |\n| `--reset ` | 重置 AK：清除旧 Token → 写入新 AK |\n| （无参数） | 等同于 `--status` |\n\n## ⚠️ AK 检查机制（Agent 必读）\n\n**判断 AK 是否已配置，不应仅依据用户消息或对话历史。** 正确做法：\n\n1. **直接执行用户请求的搜索命令**（text_search / image_search / link_search / compare）\n2. 如果 AK 未配置，CLI 会返回 `success: false` + \"AK 未配置\" 提示\n3. 此时按下方「AK 缺失时的处理流程」应对\n\n也可主动查询状态：`python3 {baseDir}/cli.py configure`（无参数）\n\n**禁止以下行为**：\n- ❌ 仅因对话中没出现过 AK 就认为未配置（AK 可能已持久化在配置文件中）\n- ❌ 仅因之前配置过就认为仍有效（AK 可能已过期或被清除）\n- ❌ 跳过 CLI 检查直接要求用户提供 AK\n- ❌ 在搜索前主动调用 configure 检查（应直接执行搜索，让 CLI 自动判断）\n\n## AK 缺失时的处理流程\n\n当 CLI 返回 \"AK 未配置\" 错误时，Agent **按顺序**执行：\n\n**第一步：自动获取（优先）**\n\n```bash\npython3 {baseDir}/cli.py get_ak\n```\n\n- 启动本地回调服务器 + 打开浏览器授权页面\n- 用户在浏览器完成登录后，AK 自动保存\n- `success: true` → 配置成功，**立即继续执行用户的原始请求**\n- `success: false` → 进入第二步\n\n**第二步：引导手动配置（回退）**\n\n输出以下话术：\n\n> 自动获取 AK 失败。请手动提供您的 AK（Access Key），用于接口调用的鉴权。\n> 如果还没有 API_KEY，请前往 https://clawhub.1688.com/ 获取。\n\n用户提供 AK 后执行：\n\n```bash\npython3 {baseDir}/cli.py configure <用户提供的AK>\n```\n\n配置成功后，**继续执行用户的原始请求**（如搜索商品）。\n\n## 输出格式\n\n所有输出为标准 JSON：\n\n```json\n{\"success\": bool, \"markdown\": \"...\", \"data\": {\"configured\": bool, \"ak\": \"...\"}}\n```\n\n| 场景 | success | markdown |\n|------|---------|----------|\n| 配置成功 | `true` | `✅ AK 设置成功` |\n| 配置成功（替换旧 AK） | `true` | `✅ AK 设置成功\\n\\n旧的 1688 OAuth Token 已同步清除` |\n| 重置成功 | `true` | `✅ AK 已重置\\n\\n旧的 1688 OAuth Token 已同步清除。` |\n| 清除成功 | `true` | `AK 已清除，关联的 1688 OAuth Token 也已同步清除。` |\n| 无需清除 | `true` | `当前未配置 AK，无需清除。` |\n| 状态：已配置 | `true` | `AK 已配置。\\n\\n**AK**: \\`xxx\\`` |\n| 状态：未配置 | `true` | `AK 未配置。` |\n| AK 格式错误 | `false` | `❌ AK 长度不足（当前 N，需要至少 32 位）` |\n| 写入失败 | `false` | `❌ AK 写入失败，请检查文件权限` |\n| 缺少参数 | `false` | `缺少参数：\\`--reset\\` 后需要提供新的 AK` |\n\n## 异常处理\n\n| 场景 | Agent 应对 |\n|------|-----------|\n| configure 输出 success=false | 原样输出 markdown 错误信息 |\n| 配置成功但后续命令仍报 AK 未配置 | 提示用户新开会话或执行 `openclaw secrets reload`，必要时再重试 configure |\n| 用户问\"我的 AK 在哪\" | 输出获取 AK 引导话术，引导前往 https://clawhub.1688.com/ 获取 |\n\n通用 HTTP 异常（400/401/429/500）处理见 `references/common/error-handling.md`。\n\n---\n\n## 附录：内部机制（Agent 无需主动操作）\n\n以下为系统内部实现细节，Agent 了解即可，**不需要手动执行这些逻辑**。\n\n### AK 校验规则\n\nconfigure 内部会自动校验 AK 格式：\n- 不能为空\n- 长度至少 32 位\n- 仅允许字母、数字及 `_-=` 字符\n\n校验失败时 CLI 会返回明确的 `success: false` 错误信息。\n\n### AK 读取优先级\n\n系统内部按以下优先级自动读取 AK（Agent 无需关心路径细节）：\n\n1. 环境变量 `ALI_1688_AK`（OpenClaw 平台注入，最高优先级）\n2. 配置文件 `{workspace}/.1688-AK/.ak_store.json`（多个候选路径自动遍历）\n\n配置文件格式：`{\"ak\": \"...\"}`\n\n### Token 联动清除\n\n以下操作会自动清除关联的 OAuth Token（Agent 无需手动清 Token）：\n\n| 操作 | Token 清除条件 |\n|------|--------------|\n| `configure ` | 仅当新旧 AK 不同时 |\n| `--reset ` | 始终清除 |\n| `--clear` | 始终清除 |\n\nToken 清除失败时静默忽略，不影响主流程。\n\nFile v1.7.0:references/capabilities/image_search.md\n\n# Capability: image_search (图片找同款)\n\n## 功能说明\n基于用户上传的商品图片，通过图像识别和特征匹配，在 1688 平台搜索同款或相似商品。支持本地图片路径和图片 URL。\n\n## 触发方式\n**Skill 级触发词**: 图片找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含图片附件\n- 或消息中包含图片 URL\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"搜这个\"\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py image_search --image \"图片路径或URL\" [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 图片本地路径或 URL | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg\n\n# 指定返回数量\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -p 1688 -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"image_path\": \"string (required) - 本地图片路径或 URL\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n### 1. 图片预处理 (ImagePreprocessor)\n```python\n步骤：\n1. 判断输入类型（本地路径 / URL）\n2. 本地图片：检查文件存在性和大小\n3. 返回处理后的图片信息\n```\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 将图片通过 base64 编码转换成字符串\n2. 拼装请求并调用 `/api/find_product/1.0.0` 接口\n3. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"imgBase64\": \"base64编码的图片字符串\",\n \"imageUrl\": \"图片URL（可选）\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n> `sortType` 和 `scoreLevel` 为可选字段，不传则使用默认值。\n\n**API 响应格式**:\n```json\n{\n \"data\": {\n \"data\": [\n {\n \"itemId\": 987622522091,\n \"title\": \"商品标题\",\n \"imageUrl\": \"商品主图URL\",\n \"detailUrl\": \"商品详情页URL\",\n \"score\": 0.99786893,\n \"currentPrice\": 12.8,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"五彩公鸡\",\n \"yxIndex\": 4.5,\n \"quantityBegin\": 1,\n \"unit\": \"\",\n \"company\": \"义乌某工艺品有限公司\",\n \"soldOut\": 20000,\n \"storeAmount\": 5000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 201382421,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [],\n \"serviceInfos\": [{\"type\": \"赊账服务\", \"value\": \"先采后付\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"亚克力\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"count\": 3\n }\n}\n```\n\n### 3. 错误处理（无浏览器降级）\n**本能力不存在浏览器降级方案。** 当 API 不可用或 AK 未配置时，直接返回错误信息，由 Agent 引导用户解决（配置 AK、检查路径等），禁止尝试通过浏览器访问 1688 网站。\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"source_image\": \"/path/to/uploaded.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"跨境创意五彩公鸡动物摆件2D平面亚克力家居办公桌面装饰摆件\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"price\": 12.8,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"五彩公鸡\",\n \"yx_index\": 4.5,\n \"quantity_begin\": 1,\n \"unit\": \"\",\n \"supplier\": \"义乌某工艺品有限公司\",\n \"sold_count\": 20000,\n \"stock_amount\": 5000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [],\n \"service_infos\": [{\"type\": \"赊账服务\", \"value\": \"先采后付\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"亚克力\"}]\n }\n ],\n \"search_type\": \"image_similarity\",\n \"total_results\": 3\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/image_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── ImagePreprocessor # 图片预处理器\n ├── ImageSearchExecutor # 搜索执行器\n └── image_search() # 主入口函数\n```\n\n## 错误处理\n- **图片路径无效**: 抛出 `ServiceError(\"图片路径无效\")`\n- **图片不存在**: 抛出 `FileNotFoundError`\n- **图片太大**: 抛出 `ValueError`（超过 5MB）\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n\n## 测试用例\n```python\n# 本地图片路径\nimage_search(image_path=\"/workspace/product.jpg\")\n\n# 图片 URL\nimage_search(image_path=\"https://example.com/product.png\")\n\n# 指定返回数量\nimage_search(image_path=\"xxx.jpg\", limit=10)\n\n# 指定采购件数\nimage_search(image_path=\"xxx.jpg\", purchase_amount=100)\n\n# 指定排序和相关性\nimage_search(image_path=\"xxx.jpg\", sort_type=\"price_asc\", score_level=\"medium\")\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n\n## 注意事项\n1. 图片上传需考虑隐私和安全，临时文件会自动清理\n2. API 调用需要有效的 AK 配置\n3. **不存在浏览器降级方案**，AK 缺失或 API 失败时只能返回错误提示，不得尝试浏览器搜索\n4. Windows 环境下临时文件可能受沙箱限制，代码已内置 fallback 到工作目录\n5. **本地图片必须使用绝对路径**（如 `/home/user/image.png` 或 `C:\\Users\\user\\image.png`），禁止使用相对路径（如 `./image.png`），否则在不同操作系统下可能因工作目录不一致导致找不到文件\n6. **图片预处理限制**：本地图片最大支持 5MB；超过 800×800 像素的图片会自动等比缩放；非 JPEG 格式会自动转换为 JPEG（透明通道处理为白色底）\n\nFile v1.7.0:references/capabilities/link_search.md\n\n# Capability: link_search (链接找同款)\n\n## 功能说明\n解析用户提供的商品链接或商品 ID，自动识别平台，尝试静默获取商品主图，然后基于主图搜索同款或相似商品。与 image_search 和 text_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 链接找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含完整 URL (1688/淘宝/天猫)\n- 或纯商品 ID (6-12 位数字/字母组合)\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"这个的平价替代\"\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py link_search --url \"商品链接\" [--image \"图片URL\"] [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--url` | `-u` | 商品链接或商品 ID | 必需 |\n| `--image` | `-i` | 商品图片 URL（自动获取失败时使用） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法（自动获取主图）\npython3 {baseDir}/cli.py link_search -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 纯商品 ID\npython3 {baseDir}/cli.py link_search -u \"895657286458\"\n\n# 手动指定商品图片（当自动获取失败时）\npython3 {baseDir}/cli.py link_search -u \"https://detail.1688.com/offer/895657286458.html\" -i \"https://img.alicdn.com/xxx.jpg\"\n\n# 指定返回数量\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py link_search -u \"895657286458\" --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py link_search -u \"895657286458\" -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"url\": \"string (required) - 商品链接或商品 ID\",\n \"image_url\": \"string (optional) - 商品图片 URL（自动获取失败时使用）\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n\n### 1. 链接解析 (LinkParser)\n```python\n输入示例：\n- \"https://detail.1688.com/offer/895657286458.html\"\n- \"https://item.taobao.com/item.htm?id=1033765771797\"\n- \"895657286458\" (纯 ID)\n\n输出：\n{\n \"platform\": \"1688\",\n \"product_id\": \"895657286458\",\n \"canonical_url\": \"https://detail.1688.com/offer/895657286458.html\"\n}\n```\n\n**识别规则**:\n- **1688**: URL 包含 `1688.com` 且路径含 `offer`，ID 格式：6-12 位纯数字\n- **淘宝**: URL 包含 `taobao.com` 或 `tb.cn`，ID 格式：8-12 位字母数字\n- **天猫**: URL 包含 `tmall.com`，ID 格式同淘宝\n\n### 2. 商品主图提取 (ProductImageExtractor)\n**尝试静默获取商品主图**:\n1. 发起 HTTP 请求获取商品页面 HTML\n2. 根据以下特征判断商品主图：\n - 图片 URL 符合阿里图片服务模式（alicdn.com）\n - 包含 `ibank` 或 `imgextra` 标识\n - 过滤掉缩略图（如 `_50x50`、`_100x100`）\n3. 返回第一个符合条件的图片 URL\n\n**如果无法获取主图**:\n- 返回 `action: \"need_image_url\"` 信号\n- 提示用户手动输入商品图片 URL\n- 转到 image_search 流程完成功能\n\n### 3. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/find_product/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"imageUrl\": \"商品主图URL\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"itemId\": 984731164094,\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捨腰部按摩器\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"score\": \"0.97332934\",\n \"currentPrice\": 45.5,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"黑色 XL\",\n \"yxIndex\": 4.9,\n \"quantityBegin\": 2,\n \"unit\": \"件\",\n \"company\": \"广州某服饰有限公司\",\n \"soldOut\": 50000,\n \"storeAmount\": 12000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 122698013,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [\"满99减5\"],\n \"serviceInfos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n\n### 成功获取主图时\n```json\n{\n \"success\": true,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"source_image\": \"https://img.alicdn.com/xxx.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"同款商品标题\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"price\": 25.0,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"黑色 M\",\n \"yx_index\": 4.8,\n \"quantity_begin\": 1,\n \"unit\": \"\",\n \"supplier\": \"某服饰有限公司\",\n \"sold_count\": 30000,\n \"stock_amount\": 8000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [],\n \"service_infos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"棉\"}]\n }\n ],\n \"search_type\": \"link_search\",\n \"total_results\": 6\n}\n```\n\n### 无法获取主图时\n```json\n{\n \"success\": false,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"action\": \"need_image_url\",\n \"message\": \"无法自动获取商品主图，请手动输入商品图片 URL\",\n \"similar_products\": [],\n \"search_type\": \"link_search\",\n \"total_results\": 0\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/link_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── LinkParser # 链接解析器\n ├── ProductImageExtractor # 商品主图提取器\n ├── LinkSearchExecutor # 搜索执行器\n ├── link_search() # 主入口函数\n └── link_search_with_image() # 使用指定图片搜索\n```\n\n## 错误处理\n- **链接格式错误**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **不支持的平台**: 抛出 `ValueError(\"不支持的电商平台\")`\n- **无法获取主图**: 返回 `action: \"need_image_url\"` 信号\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n\n## 测试用例\n```python\n# 1688 链接\nlink_search(url=\"https://detail.1688.com/offer/895657286458.html\")\n\n# 淘宝链接\nlink_search(url=\"https://item.taobao.com/item.htm?id=1033765771797\")\n\n# 纯商品 ID\nlink_search(url=\"895657286458\")\n\n# 手动指定图片 URL\nlink_search_with_image(image_url=\"https://img.alicdn.com/xxx.jpg\", limit=10)\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n- `urllib.request`: 用于获取商品页面 HTML\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`text_search` 使用同一 API path (`/api/find_product/1.0.0`)\n- **降级策略**: 当无法获取主图时，提示用户手动输入图片 URL，转到 `image_search` 流程\n\n## 注意事项\n1. 静默获取主图依赖于页面的 HTML 结构，可能因页面变化而失效\n2. 部分商品页面可能需要登录才能访问，此时无法获取主图\n3. 建议用户直接提供商品图片 URL 以获得更稳定的搜索结果\n4. 返回的商品数据结构与 image_search 一致\n\n### 平台自动提取主图支持\n\n| 平台 | 自动提取主图 | 说明 |\n|------|-------------|------|\n| **1688** | ✅ 支持 | 自动从商品页面提取主图 |\n| **淘宝** | ❌ 不支持 | 需要用户手动提供图片 URL |\n| **天猫** | ❌ 不支持 | 需要用户手动提供图片 URL |\n\nFile v1.7.0:references/capabilities/text_search.md\n\n# Capability: text_search (文本搜索)\n\n## 功能说明\n通过用户输入的关键词或自然语言描述，在 1688 平台搜索匹配的商品列表。与 image_search 和 link_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 找商品、搜商品、想要 XX、帮我找 XX\n\n**Capability 识别特征**:\n- 用户输入包含商品描述性语言\n- 不包含图片附件\n- 不包含完整 URL 链接\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py text_search --query \"搜索关键词\" [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--query` | `-q` | 搜索关键词 | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 {baseDir}/cli.py text_search -q \"黑色连帽卫衣\"\n\n# 指定返回数量\npython3 {baseDir}/cli.py text_search -q \"手机壳\" -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py text_search -q \"男士牛仔裤\" -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py text_search -q \"冲锋衣\" -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py text_search -q \"卫衣\" --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py text_search -q \"手机壳\" --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py text_search -q \"手机壳\" --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py text_search -q \"男士牛仔裤 修身\" -p 1688 -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"query\": \"string (required) - 搜索关键词\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n### 1. 查询处理\n直接使用用户输入的关键词作为搜索条件。\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/find_product/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"query\": \"搜索关键词\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"itemId\": 984731164094,\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捨腰部按摩器\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"score\": \"0.97332934\",\n \"currentPrice\": 45.5,\n \"skuId\": 6052056270674,\n \"skuTitle\": \"黑色 XL\",\n \"yxIndex\": 4.9,\n \"quantityBegin\": 2,\n \"unit\": \"件\",\n \"company\": \"广州某服饰有限公司\",\n \"soldOut\": 50000,\n \"storeAmount\": 12000,\n \"userId\": \"\",\n \"memberId\": \"\",\n \"cateId\": 122698013,\n \"industryName\": \"消费品\",\n \"source\": \"1688\",\n \"recallSource\": \"same_product_recall\",\n \"promotionTags\": [\"满99减5\"],\n \"serviceInfos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"sellingPoints\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}],\n \"offerTags\": \"180739;3056835;...\",\n \"offerICTagInfo\": {},\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"query\": \"黑色连帽卫衣\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"2024新款黑色连帽卫衣男宽松加绒加厚秋冬季外套\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.95,\n \"price\": 45.5,\n \"sku_id\": \"6052056270674\",\n \"sku_title\": \"黑色 XL\",\n \"yx_index\": 4.9,\n \"quantity_begin\": 2,\n \"unit\": \"件\",\n \"supplier\": \"广州某服饰有限公司\",\n \"sold_count\": 50000,\n \"stock_amount\": 12000,\n \"user_id\": \"\",\n \"member_id\": \"\",\n \"category_id\": 201382421,\n \"promotion_tags\": [\"满99减5\"],\n \"service_infos\": [{\"type\": \"发货保障\", \"value\": \"48小时发货\"}],\n \"selling_points\": [{\"type\": \"industryCPV\", \"value\": \"加绒\"}]\n }\n ],\n \"search_type\": \"text_search\",\n \"total_results\": 6\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/text_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── TextSearchExecutor # 搜索执行器\n └── text_search() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无搜索结果**: 返回空数组\n\n## 测试用例\n```python\n# 基础搜索\ntext_search(query=\"黑色连帽卫衣\")\n\n# 多关键词搜索\ntext_search(query=\"黑色连帽卫衣 宽松 加绒\")\n\n# 限定数量\ntext_search(query=\"手机壳\", limit=10)\n```\n\n## 依赖关系\n- `_http.search_products`: 商品搜索公共接口\n- `_auth.get_ak_from_env`: AK 认证（cmd.py 层调用）\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error/format_products_table`: 输出格式化\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`link_search` 使用同一 API path (`/api/find_product/1.0.0`)\n- **区别**: text_search 通过 `query` 参数传递搜索词，而非图片\n\n# 注意事项\n1. 搜索关键词应尽量准确，避免过于宽泛\n2. 返回的商品数据结构与 image_search 一致\n3. **--query 必须完整保留用户意图**：禁止丢弃用户提及的排序要求（如\"按销量倒排\"）、价格筛选（如\"100元以下\"）、品牌限定等信息，这些要素必须一并携带到 query 参数中\n\n### --query 构造示例\n\n| 用户输入 | ✅ 正确的 --query | ❌ 错误的 --query |\n|---------|------------------|------------------|\n| 帮我找一件深绿色的始祖鸟同款冲锋衣，按销量倒排 | \"深绿色 始祖鸟同款 冲锋衣 销量排序\" | \"深绿色冲锋衣 始祖鸟同款\"|\n| 找价格100元以下的男士牛仔裤 | \"男士牛仔裤 价格100元以下\" | \"男士牛仔裤\" |\n\nFile v1.7.0:references/common/error-handling.md\n\n# 通用错误处理\n\n所有命令在遇到以下 HTTP / 业务错误时，遵循统一处理策略。\n\n## 错误码与 Agent 应对\n\n| 错误码 | 含义 | Agent 应对 |\n|--------|------|-----------|\n| — | AK 未配置（命令入口预检查） | 输出 AK 引导话术（见 SKILL.md） |\n| 400 | 参数不合法 | 检查用户输入（关键词、渠道、商品ID等）是否正确 |\n| 401 | 鉴权无效（AK 错误或已过期） | 输出 AK 引导话术（见 SKILL.md），引导用户重新配置 |\n| 429 | 请求被限流 | 建议用户稍后重试（通常等待 1-2 分钟） |\n| 500 | 服务端异常 | 建议用户稍后重试，如持续出现建议联系客服 |\n\n## 网络异常\n\nCLI 已内置 3 次重试（指数退避），重试耗尽后返回 `success: false`。\n\nAgent 应对：告知用户\"网络异常，请检查网络连接后重试\"。\n\n## 识别方式\n\n当 CLI 输出 `success: false` 时：\n\n1. 输出 `markdown` 字段（用户可读的错误描述）\n2. 检查 `markdown` 中的关键词（如 \"AK 未配置\"、\"401\"、\"授权过期\"、\"限流\"），按 SKILL.md 异常处理表追加对应引导\n\n## 各能力特有异常\n\n通用错误外的业务异常，见各能力文档的\"业务异常处理\"段。\n\n## 沙箱/权限异常\n\n当 `markdown` 包含 \"沙箱\"、\"权限\"、\"Permission denied\" 关键词时：\n- 提示用户授予目录访问权限\n- 或在 IDE 设置中允许 Skill 访问所需目录\n\nFile v1.7.0:references/skill埋点说明.md\n\n# Skill 埋点说明\n\n本文描述 **1688-open-skill-template** 中 Skill 调用埋点的上报时机、请求内容与失败策略，便于对接网关统计与二次开发对齐行为。\n\n## 1. 作用概述\n\n埋点用于在 **Skill 网关**侧统计 Skill 被调用的次数与基础元信息（名称、版本、渠道、场景）。实现集中在 `scripts/_tracker.py` 的 `report_skill_usage()`，由统一 CLI 入口 `cli.py` 在命令生命周期末尾触发。\n\n## 2. 上报时机\n\n| 场景 | 是否上报 | 说明 |\n|------|----------|------|\n| 已识别子命令（如 `ali_dingtalk`、`configure`），且子命令 `main()` **正常执行完毕**（无未捕获异常、未中途 `sys.exit`） | **是** | 无论业务 JSON 中 `success` 为 `true` 或 `false`（例如 AK 未配置、参数校验失败等只要进程未崩），均在子命令返回后上报一次。 |\n| 未传入子命令、子命令名不在注册表、或展示用法后 `sys.exit(1)` | **否** | `cli.py` 在调用子模块前即退出，不会执行埋点逻辑。 |\n| 子命令内 `argparse` 报错并 `sys.exit`（如必填参数缺失） | **否** | 进程在 `module.main()` 内退出，**不会**回到 `cli.py` 的埋点代码。 |\n| 子命令 `main()` 抛出**未捕获**异常 | **否** | 异常向上传播，埋点代码未执行。 |\n\n**小结**：埋点表示「一次 CLI 子命令入口已跑完主流程」，偏 **会话级 / 调用次数** 统计，**不**区分具体子命令名（请求体中无命令字段），也**不**保证业务一定成功。\n\n## 3. 上报接口与传输\n\n| 项 | 值 |\n|----|-----|\n| 方法 | `POST` |\n| 路径 | `/api/reportSkillsUsage/1.0.0` |\n| 完整 URL | 与业务 API 相同网关：`https://skills-gateway.1688.com` + 路径（见 `scripts/_http.py` 中 `BASE_URL`） |\n| 请求体 | JSON，`Content-Type: application/json; charset=utf-8` |\n| 鉴权 | 与能力调用一致：通过 `get_auth_headers()` 注入签名；**未配置 AK 时** `api_post` 会抛鉴权类异常，由埋点模块捕获（见下文），**不会**向网关发出 HTTP 请求。 |\n\n网络层对 **连接错误 / 超时** 有有限次重试（与 `_http.api_post` 一致）；HTTP 4xx/5xx 或业务 `success: false` 会转为异常并由埋点侧吞掉。\n\n## 4. 请求体字段\n\n上报 JSON 字段与含义如下（与代码一一对应）。\n\n| 字段 | 类型 | 取值说明 |\n|------|------|----------|\n| `apiName` | `null` | 固定为 JSON `null`，占位或网关约定字段。 |\n| `skillsName` | string | Skill 名称，来自环境变量 `SKILL_NAME`，缺省为 `1688-open-skill-template`。 |\n| `version` | string | Skill 版本，来自 `SKILL_VERSION`，缺省为 `1.0.0`。 |\n| `scene` | string | 固定为 `\"CLI\"`，表示当前模板通过命令行入口触发。 |\n| `channel` | string | 发布渠道，来自 `SKILL_CHANNEL`，缺省为 `clawhub`。 |\n\n**环境变量来源**：模块加载时会读取项目根目录 `.env` 并写入 `os.environ`（**不覆盖**已存在的环境变量，便于 CI/CD 注入覆盖本地文件）。\n\n## 5. 失败与日志策略\n\n- `report_skill_usage()` 整体包裹在 `try/except` 中：**任意异常均不向外抛出**，主命令的退出码与输出不受影响。\n- 失败时通过 logger `1688_tracker` 输出 **DEBUG** 级别日志：`埋点上报失败（已忽略）: ...`。\n- `cli.py` 在调用 `report_skill_usage()` 外层还有一次 `try/except`，避免导入埋点模块等极端情况影响进程。\n\n若需在本地排查埋点，可将日志级别调到 DEBUG 并关注 `1688_tracker` / `1688_http`。\n\n## 6. 与模板扩展的关系\n\n新增 `capabilities//cmd.py` 并注册命令后，只要仍由根目录 `cli.py` 统一调度且在子命令 `main()` 正常返回后回到 `cli.py`，**会自动沿用同一套埋点**，无需在子命令内重复调用。\n\n若希望按子命令或按业务结果细分统计，需要在网关契约允许的前提下扩展请求体或增加独立埋点逻辑（当前模板未实现）。\n\n## 7. 相关文件索引\n\n| 文件 | 职责 |\n|------|------|\n| `scripts/_tracker.py` | 读取 `.env`、组装请求体、调用 `api_post` 上报。 |\n| `cli.py` | 命令分发结束后调用 `report_skill_usage()`。 |\n| `scripts/_http.py` | `api_post`：网关地址、签名、重试与错误映射。 |\n| `SKILL.md` | 面向使用方的环境变量与埋点摘要。 |\n\nFile v1.7.0:skill-card.md\n\n## Description:\n\nSearches 1688 products by text, image, or product link, finds same or similar items, and supports purchase comparison with price, sales, supplier, and product attribute filters.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[1688aiinfra](https://clawhub.ai/user/1688aiinfra)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and purchasing-focused agents use this skill to search 1688 for products, same-item matches, similar products, and lower-cost or higher-volume supplier options. It is intended for product discovery and comparison, not order placement, payment, logistics tracking, or inventory management.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Reusable 1688 AK or OAuth credentials may be exposed in chat, command output, or local files.\n\nMitigation: Use an isolated environment, avoid pasting real AK values into chat, avoid status commands that reveal live credentials until redaction is fixed, and rotate any AK that appears in transcripts or logs.\n\nRisk: The skill requires access to a 1688 AK for product search and comparison.\n\nMitigation: Install only when granting this credential access is acceptable, and clear or rotate credentials when the skill is no longer needed.\n\nRisk: Product recommendations, prices, links, and supplier details are only as reliable as the API response returned at execution time.\n\nMitigation: Do not invent missing product details, present returned links and fields as evidence, and ask the user to retry or reconfigure credentials when the CLI reports API or authentication errors.\n\n## Reference(s):\n\n- [1688 Product Find on ClawHub](https://clawhub.ai/1688aiinfra/skills/1688-product-find)\n- [Publisher profile: 1688aiinfra](https://clawhub.ai/user/1688aiinfra)\n- [Text search capability](references/capabilities/text_search.md)\n- [Image search capability](references/capabilities/image_search.md)\n- [Link search capability](references/capabilities/link_search.md)\n- [Compare capability](references/capabilities/compare.md)\n- [Configure capability](references/capabilities/configure.md)\n- [Error handling](references/common/error-handling.md)\n\n## Skill Output:\n\n**Output Type(s):** [Markdown, JSON, Shell commands, Configuration, Guidance]\n\n**Output Format:** [JSON containing a success flag, markdown product tables or errors, and structured product data]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Product results include item identifiers, titles, image URLs, detail URLs, price, SKU, supplier, sales, stock, promotion tags, service tags, and selling points when returned by the 1688 API.]\n\n## Skill Version(s):\n\n1.7.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.7.0:tests/testcases.json\n\n[\n {\n \"id\": \"TC001\",\n \"name\": \"基础文本搜索\",\n \"input\": \"我要买打印纸\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"打印纸\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 包含核心关键词'打印纸'\",\n \"返回商品数 ≤ limit\",\n \"每个商品含标题/价格/链接\",\n \"数据来自 API 真实返回，不编造\"\n ]\n }\n },\n {\n \"id\": \"TC002\",\n \"name\": \"排序意图保留\",\n \"input\": \"卖得最好的蓝牙耳机有哪些\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"蓝牙耳机\", \"销量\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 保留排序意图：'卖得最好' → 包含'销量排序'或'销量'\",\n \"返回商品数 = 10（默认 limit）\",\n \"每个商品含标题/价格/链接\",\n \"不编造数据，所有展示数据可在 tool_response 中找到来源\"\n ]\n }\n },\n {\n \"id\": \"TC003\",\n \"name\": \"多条件搜索（价格+排序+数量）\",\n \"input\": \"找10款夏季连衣裙，价格50-100元，按销量排序\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"夏季连衣裙\", \"价格50-100元\", \"销量排序\"],\n \"limit\": 10,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留：商品描述 + 价格筛选 + 排序条件\",\n \"--limit 正确设为 10\",\n \"返回商品数 ≤ 10\",\n \"数据真实，所有价格来自 API 返回\"\n ]\n }\n },\n {\n \"id\": \"TC004\",\n \"name\": \"数量与价格约束（非默认 limit）\",\n \"input\": \"找15个10块钱以下的发圈，从便宜到贵排\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"发圈\", \"价格10元以下\", \"价格从低到高\"],\n \"limit\": 15,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留：商品描述 + 价格约束 + 排序方向\",\n \"--limit 正确设为 15（用户说'找15个'）\",\n \"返回商品数 ≤ 15\",\n \"全部价格 < 10元\"\n ]\n }\n },\n {\n \"id\": \"TC005\",\n \"name\": \"大数量请求（超出 API 上限）\",\n \"input\": \"找100个20-80元的夏季女装连衣裙，按销量从高到低排\",\n \"expected\": {\n \"tool\": \"text_search\",\n \"query_contains\": [\"夏季女装连衣裙\", \"价格20-80元\", \"销量从高到低\"],\n \"limit\": 100,\n \"assertions\": [\n \"正确触发 text_search\",\n \"query 完整保留全部意图\",\n \"--limit 正确设为 100\",\n \"返回商品数 ≤ 100（API 单次上限约30-40条，实际返回数小于请求数属正常）\",\n \"数据真实，不编造\"\n ]\n }\n }\n]\n\nFile v1.7.0:requirements.txt\n\nrequests>=2.28.0\nkeyring>=25.0\nPillow>=10.0.0\n\nArchive v0.2.0: 27 files, 45911 bytes\n\nFiles: cli.py (3020b), references/capabilities/configure.md (1512b), references/capabilities/image_search.md (4805b), references/capabilities/link_search.md (6210b), references/capabilities/text_search.md (4723b), references/common/error-handling.md (1240b), scripts/_auth.py (6422b), scripts/_const.py (530b), scripts/_errors.py (1217b), scripts/_http.py (4877b), scripts/_output.py (5637b), scripts/capabilities/configure/__init__.py (0b), scripts/capabilities/configure/cmd.py (2259b), scripts/capabilities/configure/service.py (3850b), scripts/capabilities/image_search/__init__.py (55b), scripts/capabilities/image_search/cmd.py (2428b), scripts/capabilities/image_search/service.py (9729b), scripts/capabilities/link_search/__init__.py (55b), scripts/capabilities/link_search/cmd.py (2747b), scripts/capabilities/link_search/service.py (19144b), scripts/capabilities/text_search/__init__.py (55b), scripts/capabilities/text_search/cmd.py (1840b), scripts/capabilities/text_search/service.py (4001b), scripts/main.py (6846b), scripts/settings.py (2674b), SKILL.md (7569b), _meta.json (136b)\n\nFile v0.2.0:SKILL.md\n\n---\nname: 1688-product-find\ndescription: |\n 1688智能找商品能力。理解用户找商品、找同款等需求，通过文本、图片或链接搜索匹配商品。\n 触发词：找商品、找同款、搜商品、想要 XX、帮我找、图片找货、链接找货、以图搜图。\nmetadata: {\"openclaw\": {\"emoji\": \"🔍\", \"requires\": {\"bins\": [\"python3\"]}, \"primaryEnv\": \"ALI_1688_AK\"}}\n---\n\n# 1688-product-find (1688找商品Skill)\n统一入口：`python3 {baseDir}/cli.py [options]`\n\n## 严格禁止 (NEVER DO)\n- 不要编造商品价格、链接、`productId`、规格或供货信息，所有商品内容必须来自工具返回\n- 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力\n- 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接\n\n## 命令速查\n\n| 命令 | 说明 | 示例 |\n|------|------|------|\n| `text_search` | 文本搜索商品 | `python3 cli.py text_search --query \"黑色连帽卫衣\"` |\n| `image_search` | 图片以图搜图 | `python3 cli.py image_search --image \"/path/to/image.jpg\"` |\n| `link_search` | 链接找同款 | `python3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"` |\n| `configure` | 配置 AK | `python3 cli.py configure YOUR_AK` |\n\n所有命令输出 JSON：`{\"success\": bool, \"markdown\": str, \"data\": {...}}`\n\n**展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。**\n\n## 使用流程\n\nAgent 根据用户意图**直接执行对应命令**。\n各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「异常处理」应对即可。\n\n### text_search（文本搜索）\n\n当用户通过自然语言描述想要的商品时使用。\n\n```bash\npython3 cli.py text_search --query \"黑色连帽卫衣宽松款\" --limit 10\n```\n\n**参数说明**：\n- `--query, -q`（必填）：搜索关键词\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n\n**❗ --query 构造规则（必须遵守）**：\n\n`--query` 的值应完整保留用户意图中的所有要素，包括但不限于：商品描述、排序要求、筛选条件。禁止丢弃用户提及的排序/筛选信息。\n\n| 用户输入 | ✅ 正确的 --query | ❌ 错误的 --query |\n|---------|------------------|------------------|\n| 帮我找一件深绿色的始祖鸟同款冲锋衣，按销量倒排 | \"深绿色 始祖鸟同款 冲锋衣 销量排序\" | \"深绿色冲锋衣 始祖鸟同款\"|\n| 找价格100元以下的男士牛仔裤 | \"男士牛仔裤 价格100元以下\" | \"男士牛仔裤\" |\n\n### image_search（图片搜索）\n\n当用户上传图片找同款时使用。\n\n```bash\npython3 cli.py image_search --image \"/path/to/product.jpg\" --limit 10\n```\n\n**参数说明**：\n- `--image, -i`（必填）：图片本地路径或 URL。**本地图片必须使用绝对路径**（如 `/home/user/image.png` 或 `C:\\Users\\user\\image.png`），禁止使用相对路径（如 `./image.png`），否则在不同操作系统下可能因工作目录不一致导致找不到文件。\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n- `--threshold, -t`（可选）：相似度阈值，默认 `0.7`\n\n### link_search（链接搜索）\n\n当用户提供商品链接找同款时使用。\n\n```bash\n# 自动提取主图（仅 1688 支持）\npython3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"\n\n# 手动指定图片 URL（淘宝/天猫需要）\npython3 cli.py link_search --url \"https://item.taobao.com/item.htm?id=xxx\" --image \"图片URL\"\n```\n\n**参数说明**：\n- `--url, -u`（必填）：商品链接或商品 ID\n- `--image, -i`（可选）：商品图片 URL（当自动获取失败时使用）\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n\n**平台支持**：\n| 平台 | 自动提取主图 | 说明 |\n|------|-------------|------|\n| **1688** | ✅ 支持 | 自动从商品页面提取主图 |\n| **淘宝** | ❌ 不支持 | 需要用户手动提供图片 URL |\n| **天猫** | ❌ 不支持 | 需要用户手动提供图片 URL |\n\n**降级流程**：当 `link_search` 返回 `action: \"need_image_url\"` 时：\n1. 提示用户无法自动获取商品主图\n2. 引导用户手动复制商品图片 URL\n3. 使用 `--image` 参数重新执行搜索\n\n## 统一返回结构\n\n所有搜索能力返回相同的商品数据结构：\n\n```json\n{\n \"success\": true,\n \"query\": \"搜索词（仅 text_search）\",\n \"source_image\": \"图片 URL（image_search/link_search）\",\n \"source_url\": \"原始链接（仅 link_search）\",\n \"similar_products\": [\n {\n \"product_id\": \"商品 ID\",\n \"title\": \"商品标题\",\n \"image_url\": \"商品主图\",\n \"detail_url\": \"商品详情页链接\",\n \"similarity_score\": 0.95,\n \"source\": \"1688\",\n \"category_id\": \"类目 ID\",\n \"industry_name\": \"行业名称\"\n }\n ],\n \"search_type\": \"text_search|image_similarity|link_search\",\n \"total_results\": 6\n}\n```\n\n## 安全声明\n\n| 风险级别 | 命令 | Agent 行为 |\n|---------|------|-----------|\n| **只读** | text_search | 参数明确时直接执行 |\n| **只读** | image_search | 图片路径有效时直接执行 |\n| **只读** | link_search | URL 有效时直接执行；提取失败时引导用户提供图片 URL |\n\n## 执行前置（首次命中能力时必须）\n\n- 首次执行 `configure` 前：先完整阅读 `references/capabilities/configure.md`\n- 首次执行 `text_search` 前：先完整阅读 `references/capabilities/text_search.md`\n- 首次执行 `image_search` 前：先完整阅读 `references/capabilities/image_search.md`\n- 首次执行 `link_search` 前：先完整阅读 `references/capabilities/link_search.md`\n\n## 异常处理\n\n任何命令输出 `success: false` 时：\n\n1. **先输出 `markdown` 字段**（已包含用户可读的错误描述）\n2. **再根据关键词追加引导**：\n\n| markdown 关键词 | Agent 额外动作 |\n|----------------|--------------|\n| “AK 未配置” | 提示用户运行 `python3 cli.py configure YOUR_AK` 配置认证信息，如果用户还没有 API_KEY，引导前往 https://clawhub.1688.com/ 获取 |\n| \"签名无效\" 或 \"401\" | 提示用户检查 AK 是否正确或已过期 |\n| \"图片路径无效\" | 提示用户检查图片路径是否存在 |\n| \"无法自动获取商品主图\" | 引导用户手动提供商品图片 URL，使用 `--image` 参数 |\n| \"限流\" 或 \"429\" | 建议用户等待 1-2 分钟后重试 |\n| \"格式异常\" | 提示用户稍后重试，可能是 API 返回异常 |\n| 其他 | 仅输出 markdown 即可 |\n\n## 参数补齐引导话术\n\n> **文本搜索**：请描述您想要的商品，例如：\"帮我找一件黑色连帽卫衣，宽松款的\"\n\n> **图片搜索**：请上传商品图片，我会帮您找到同款或相似商品。\n\n> **链接搜索**：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。\n\n## 技术说明\n\n- **统一 API**：三个搜索能力共用 `/api/findProduct/1.0.0` 接口\n- **认证方式**：通过环境变量 `ALI_1688_AK` 配置\n- **依赖项**：Python 3.9+、requests、Pillow\n\n## 更新日志\n\n- v1.1.0 (2026-03-27): 新增 `cli.py` 统一 CLI 入口，简化命令调用方式\n- v1.0.0 (2026-03-27): 初始版本，包含三大核心搜索能力（text_search、image_search、link_search）\n\nFile v0.2.0:_meta.json\n\n{\n \"ownerId\": \"kn76msg8cwkep3b08z7zffx9fx82p5wj\",\n \"slug\": \"1688-product-find\",\n \"version\": \"0.2.0\",\n \"publishedAt\": 1775702312650\n}\n\nFile v0.2.0:references/capabilities/configure.md\n\n# AK 配置指南\n\n## 获取 AK（引导用户）\n\n当用户没有 AK 时，Agent 输出以下引导：\n\n> 请提供您的 AK（Access Key），用于接口调用的鉴权。\n> 如果还没有 API_KEY，请前往 https://clawhub.1688.com/ 获取。\n\n## Agent 配置流程（核心）\n\n用户告知 AK 后，Agent 按以下步骤执行：\n\n```\n1. 从用户消息中提取 AK 字符串\n2. 执行 cli.py configure \n3. 检查输出：success=true → 继续；success=false → 原样输出 markdown 错误信息\n4. 配置成功后由 OpenClaw 配置注入生效（不依赖本地会话缓存）；如当前会话仍未生效，提示用户新开会话或执行 `openclaw secrets reload`\n5. 继续用户的原始请求（如发送钉钉消息）；若用户仅提供了 AK 没有其他请求，告知\"配置成功，您可以发送钉钉消息了\"\n```\n\n## CLI 调用\n\n```bash\npython3 {baseDir}/cli.py configure YOUR_AK_HERE\n```\n\n无参数调用可查看当前配置状态：`python3 {baseDir}/cli.py configure`\n\n## 异常处理\n\n| 场景 | Agent 应对 |\n|------|-----------|\n| configure 输出 success=false | 原样输出 markdown 错误信息 |\n| 配置成功但后续命令仍报 AK 未配置 | 提示用户新开会话或执行 `openclaw secrets reload`，必要时再重试 configure |\n| 用户问“我的 AK 在哪” | 输出上方获取 AK 引导话术，并引导用户前往 https://clawhub.1688.com/ 获取 |\n\n通用 HTTP 异常（400/401/429/500）处理见 `references/common/error-handling.md`。\n\nFile v0.2.0:references/capabilities/image_search.md\n\n# Capability: image_search (图片找同款)\n\n## 功能说明\n基于用户上传的商品图片，通过图像识别和特征匹配，在 1688 平台搜索同款或相似商品。支持本地图片路径和图片 URL。\n\n## 触发方式\n**Skill 级触发词**: 图片找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含图片附件\n- 或消息中包含图片 URL\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"搜这个\"\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/image_search/cmd.py --image \"图片路径或URL\" [--platform 1688] [--limit 6] [--threshold 0.7]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 图片本地路径或 URL | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n| `--threshold` | `-t` | 相似度阈值 | 0.7 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 cmd.py -i /path/to/image.jpg\n\n# 指定返回数量\npython3 cmd.py -i /path/to/image.jpg -l 10\n\n# 完整参数\npython3 cmd.py -i /path/to/image.jpg -p 1688 -l 5 -t 0.8\n```\n\n## 输入参数\n```json\n{\n \"image_path\": \"string (required) - 本地图片路径或 URL\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\",\n \"similarity_threshold\": \"float (optional) - 相似度阈值，默认 0.7\"\n}\n```\n\n## 处理流程\n### 1. 图片预处理 (ImagePreprocessor)\n```python\n步骤：\n1. 判断输入类型（本地路径 / URL）\n2. 本地图片：检查文件存在性和大小\n3. 返回处理后的图片信息\n```\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 将图片通过 base64 编码转换成字符串\n2. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n3. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"imgBase64\": \"base64编码的图片字符串\",\n \"imageUrl\": \"图片URL（可选）\",\n \"pageSize\": 10\n }\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": {\n \"data\": [\n {\n \"itemId\": 987622522091,\n \"title\": \"商品标题\",\n \"imageUrl\": \"商品主图URL\",\n \"detailUrl\": \"商品详情页URL\",\n \"score\": 0.99786893,\n \"source\": \"1688\",\n \"cateId\": 201382421,\n \"industryName\": \"消费品\"\n }\n ],\n \"count\": 3\n }\n}\n```\n\n### 3. 浏览器降级方案 (_search_via_browser)\n当 API 不可用时，返回结构化信号，由 Agent 接管：\n```python\nreturn [{\n \"action\": \"browser_render\",\n \"url\": \"https://s.1688.com/selloffer/offer_search.htm\",\n \"upload_image\": image_path,\n \"message\": \"正在上传图片并搜索同款...\"\n}]\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"source_image\": \"/path/to/uploaded.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"跨境创意五彩公鸡动物摆件2D平面亚克力家居办公桌面装饰摆件\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"未定义产业名称\"\n }\n ],\n \"search_type\": \"image_similarity\",\n \"total_results\": 3\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/image_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── ImagePreprocessor # 图片预处理器\n ├── ImageSearchExecutor # 搜索执行器\n ├── format_similar_product() # 格式化输出\n └── image_search() # 主入口函数\n```\n\n## 错误处理\n- **图片路径无效**: 抛出 `ServiceError(\"图片路径无效\")`\n- **图片不存在**: 抛出 `FileNotFoundError`\n- **图片太大**: 抛出 `ValueError`（超过 5MB）\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n\n## 测试用例\n```python\n# 本地图片路径\nimage_search(image_path=\"/workspace/product.jpg\")\n\n# 图片 URL\nimage_search(image_path=\"https://example.com/product.png\")\n\n# 指定返回数量\nimage_search(image_path=\"xxx.jpg\", limit=10)\n\n# 调整相似度阈值\nimage_search(image_path=\"xxx.jpg\", similarity_threshold=0.8)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n\n## 注意事项\n1. 图片上传需考虑隐私和安全，临时文件会自动清理\n2. API 调用需要有效的 AK 配置\n3. 浏览器降级方案需要 Agent 接管处理\n\nFile v0.2.0:references/capabilities/link_search.md\n\n# Capability: link_search (链接找同款)\n\n## 功能说明\n解析用户提供的商品链接或商品 ID，自动识别平台，尝试静默获取商品主图，然后基于主图搜索同款或相似商品。与 image_search 和 text_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 链接找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含完整 URL (1688/淘宝/天猫)\n- 或纯商品 ID (6-12 位数字/字母组合)\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"这个的平价替代\"\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/link_search/cmd.py --url \"商品链接\" [--image \"图片URL\"] [--platform 1688] [--limit 6]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--url` | `-u` | 商品链接或商品 ID | 必需 |\n| `--image` | `-i` | 商品图片 URL（自动获取失败时使用） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n\n### 使用示例\n```bash\n# 基本用法（自动获取主图）\npython3 cmd.py -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 纯商品 ID\npython3 cmd.py -u \"895657286458\"\n\n# 手动指定商品图片（当自动获取失败时）\npython3 cmd.py -u \"https://detail.1688.com/offer/895657286458.html\" -i \"https://img.alicdn.com/xxx.jpg\"\n\n# 指定返回数量\npython3 cmd.py -u \"895657286458\" -l 10\n```\n\n## 输入参数\n```json\n{\n \"url\": \"string (required) - 商品链接或商品 ID\",\n \"image_url\": \"string (optional) - 商品图片 URL（自动获取失败时使用）\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\"\n}\n```\n\n## 处理流程\n\n### 1. 链接解析 (LinkParser)\n```python\n输入示例：\n- \"https://detail.1688.com/offer/895657286458.html\"\n- \"https://item.taobao.com/item.htm?id=1033765771797\"\n- \"895657286458\" (纯 ID)\n\n输出：\n{\n \"platform\": \"1688\",\n \"product_id\": \"895657286458\",\n \"canonical_url\": \"https://detail.1688.com/offer/895657286458.html\"\n}\n```\n\n**识别规则**:\n- **1688**: URL 包含 `1688.com` 且路径含 `offer`，ID 格式：6-12 位纯数字\n- **淘宝**: URL 包含 `taobao.com` 或 `tb.cn`，ID 格式：8-12 位字母数字\n- **天猫**: URL 包含 `tmall.com`，ID 格式同淘宝\n\n### 2. 商品主图提取 (ProductImageExtractor)\n**尝试静默获取商品主图**:\n1. 发起 HTTP 请求获取商品页面 HTML\n2. 根据以下特征判断商品主图：\n - 图片 URL 符合阿里图片服务模式（alicdn.com）\n - 包含 `ibank` 或 `imgextra` 标识\n - 过滤掉缩略图（如 `_50x50`、`_100x100`）\n3. 返回第一个符合条件的图片 URL\n\n**如果无法获取主图**:\n- 返回 `action: \"need_image_url\"` 信号\n- 提示用户手动输入商品图片 URL\n- 转到 image_search 流程完成功能\n\n### 3. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"imageUrl\": \"商品主图URL\",\n \"pageSize\": 10\n }\n}\n```\n\n## 输出格式\n\n### 成功获取主图时\n```json\n{\n \"success\": true,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"source_image\": \"https://img.alicdn.com/xxx.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"同款商品标题\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"消费品\"\n }\n ],\n \"search_type\": \"link_search\",\n \"total_results\": 6\n}\n```\n\n### 无法获取主图时\n```json\n{\n \"success\": false,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"action\": \"need_image_url\",\n \"message\": \"无法自动获取商品主图，请手动输入商品图片 URL\",\n \"similar_products\": [],\n \"search_type\": \"link_search\",\n \"total_results\": 0\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/link_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── LinkParser # 链接解析器\n ├── ProductImageExtractor # 商品主图提取器\n ├── LinkSearchExecutor # 搜索执行器\n ├── format_link_search_result() # 格式化输出\n ├── link_search() # 主入口函数\n └── link_search_with_image() # 使用指定图片搜索\n```\n\n## 错误处理\n- **链接格式错误**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **不支持的平台**: 抛出 `ValueError(\"不支持的电商平台\")`\n- **无法获取主图**: 返回 `action: \"need_image_url\"` 信号\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n\n## 测试用例\n```python\n# 1688 链接\nlink_search(url=\"https://detail.1688.com/offer/895657286458.html\")\n\n# 淘宝链接\nlink_search(url=\"https://item.taobao.com/item.htm?id=1033765771797\")\n\n# 纯商品 ID\nlink_search(url=\"895657286458\")\n\n# 手动指定图片 URL\nlink_search_with_image(image_url=\"https://img.alicdn.com/xxx.jpg\", limit=10)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n- `requests` (可选): 用于获取商品页面 HTML\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`text_search` 使用同一 API path (`/api/findProduct/1.0.0`)\n- **降级策略**: 当无法获取主图时，提示用户手动输入图片 URL，转到 `image_search` 流程\n\n## 注意事项\n1. 静默获取主图依赖于页面的 HTML 结构，可能因页面变化而失效\n2. 部分商品页面可能需要登录才能访问，此时无法获取主图\n3. 建议用户直接提供商品图片 URL 以获得更稳定的搜索结果\n4. 返回的商品数据结构与 image_search 一致\n\nFile v0.2.0:references/capabilities/text_search.md\n\n# Capability: text_search (文本搜索)\n\n## 功能说明\n通过用户输入的关键词或自然语言描述，在 1688 平台搜索匹配的商品列表。与 image_search 和 link_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 找商品、搜商品、想要 XX、帮我找 XX\n\n**Capability 识别特征**:\n- 用户输入包含商品描述性语言\n- 不包含图片附件\n- 不包含完整 URL 链接\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/text_search/cmd.py --query \"搜索关键词\" [--platform 1688] [--limit 6]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--query` | `-q` | 搜索关键词 | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 cmd.py -q \"黑色连帽卫衣\"\n\n# 指定返回数量\npython3 cmd.py -q \"手机壳\" -l 10\n\n# 完整参数\npython3 cmd.py -q \"男士牛仔裤 修身\" -p 1688 -l 5\n```\n\n## 输入参数\n```json\n{\n \"query\": \"string (required) - 搜索关键词\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\"\n}\n```\n\n## 处理流程\n### 1. 查询处理\n直接使用用户输入的关键词作为搜索条件。\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"query\": \"搜索关键词\",\n \"pageSize\": 10\n }\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"industryName\": \"消费品\",\n \"score\": \"0.97332934\",\n \"itemId\": 984731164094,\n \"cateId\": 122698013,\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"source\": \"1688\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"recallSource\": \"same_product_recall\",\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捏腰部按摩器\",\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"query\": \"黑色连帽卫衣\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"2024新款黑色连帽卫衣男宽松加绒加厚秋冬季外套\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.95,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"消费品\"\n }\n ],\n \"search_type\": \"text_search\",\n \"total_results\": 6\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/text_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── TextSearchExecutor # 搜索执行器\n ├── format_product_card() # 格式化输出\n └── text_search() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无搜索结果**: 返回空数组\n\n## 测试用例\n```python\n# 基础搜索\ntext_search(query=\"黑色连帽卫衣\")\n\n# 多关键词搜索\ntext_search(query=\"黑色连帽卫衣 宽松 加绒\")\n\n# 限定数量\ntext_search(query=\"手机壳\", limit=10)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`link_search` 使用同一 API path (`/api/findProduct/1.0.0`)\n- **区别**: text_search 通过 `query` 参数传递搜索词，而非图片\n\n## 注意事项\n1. 搜索关键词应尽量准确，避免过于宽泛\n2. API 调用需要有效的 AK 配置\n3. 返回的商品数据结构与 image_search 一致\n4. **--query 必须完整保留用户意图**：禁止丢弃用户提及的排序要求（如“按销量倒排”）、价格筛选（如“100元以下”）、品牌限定等信息，这些要素必须一并携带到 query 参数中\n\nFile v0.2.0:references/common/error-handling.md\n\n# 通用错误处理\n\n所有命令在遇到以下 HTTP / 业务错误时，遵循统一处理策略。\n\n## 错误码与 Agent 应对\n\n| 错误码 | 含义 | Agent 应对 |\n|--------|------|-----------|\n| — | AK 未配置（命令入口预检查） | 输出 AK 引导话术（见 SKILL.md） |\n| 400 | 参数不合法 | 检查用户输入（关键词、渠道、商品ID等）是否正确 |\n| 401 | 鉴权无效（AK 错误或已过期） | 输出 AK 引导话术（见 SKILL.md），引导用户重新配置 |\n| 429 | 请求被限流 | 建议用户稍后重试（通常等待 1-2 分钟） |\n| 500 | 服务端异常 | 建议用户稍后重试，如持续出现建议联系客服 |\n\n## 网络异常\n\nCLI 已内置 3 次重试（指数退避），重试耗尽后返回 `success: false`。\n\nAgent 应对：告知用户\"网络异常，请检查网络连接后重试\"。\n\n## 识别方式\n\n当 CLI 输出 `success: false` 时：\n\n1. 输出 `markdown` 字段（用户可读的错误描述）\n2. 检查 `markdown` 中的关键词（如 \"AK 未配置\"、\"401\"、\"授权过期\"、\"限流\"），按 SKILL.md 异常处理表追加对应引导\n\n## 各能力特有异常\n\n通用错误外的业务异常，见各能力文档的\"业务异常处理\"段。\n\nArchive v0.1.0: 27 files, 45922 bytes\n\nFiles: cli.py (3020b), references/capabilities/configure.md (1512b), references/capabilities/image_search.md (4805b), references/capabilities/link_search.md (6210b), references/capabilities/text_search.md (4723b), references/common/error-handling.md (1240b), scripts/_auth.py (6422b), scripts/_const.py (530b), scripts/_errors.py (1217b), scripts/_http.py (4888b), scripts/_output.py (5637b), scripts/capabilities/configure/__init__.py (0b), scripts/capabilities/configure/cmd.py (2259b), scripts/capabilities/configure/service.py (3850b), scripts/capabilities/image_search/__init__.py (55b), scripts/capabilities/image_search/cmd.py (2428b), scripts/capabilities/image_search/service.py (9729b), scripts/capabilities/link_search/__init__.py (55b), scripts/capabilities/link_search/cmd.py (2747b), scripts/capabilities/link_search/service.py (19144b), scripts/capabilities/text_search/__init__.py (55b), scripts/capabilities/text_search/cmd.py (1840b), scripts/capabilities/text_search/service.py (4001b), scripts/main.py (6846b), scripts/settings.py (2674b), SKILL.md (7569b), _meta.json (136b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: 1688-product-find\ndescription: |\n 1688智能找商品能力。理解用户找商品、找同款等需求，通过文本、图片或链接搜索匹配商品。\n 触发词：找商品、找同款、搜商品、想要 XX、帮我找、图片找货、链接找货、以图搜图。\nmetadata: {\"openclaw\": {\"emoji\": \"🔍\", \"requires\": {\"bins\": [\"python3\"]}, \"primaryEnv\": \"ALI_1688_AK\"}}\n---\n\n# 1688-product-find (1688找商品Skill)\n统一入口：`python3 {baseDir}/cli.py [options]`\n\n## 严格禁止 (NEVER DO)\n- 不要编造商品价格、链接、`productId`、规格或供货信息，所有商品内容必须来自工具返回\n- 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力\n- 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接\n\n## 命令速查\n\n| 命令 | 说明 | 示例 |\n|------|------|------|\n| `text_search` | 文本搜索商品 | `python3 cli.py text_search --query \"黑色连帽卫衣\"` |\n| `image_search` | 图片以图搜图 | `python3 cli.py image_search --image \"/path/to/image.jpg\"` |\n| `link_search` | 链接找同款 | `python3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"` |\n| `configure` | 配置 AK | `python3 cli.py configure YOUR_AK` |\n\n所有命令输出 JSON：`{\"success\": bool, \"markdown\": str, \"data\": {...}}`\n\n**展示时直接输出 `markdown` 字段，Agent 分析追加在后面，不得混入其中。**\n\n## 使用流程\n\nAgent 根据用户意图**直接执行对应命令**。\n各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「异常处理」应对即可。\n\n### text_search（文本搜索）\n\n当用户通过自然语言描述想要的商品时使用。\n\n```bash\npython3 cli.py text_search --query \"黑色连帽卫衣宽松款\" --limit 10\n```\n\n**参数说明**：\n- `--query, -q`（必填）：搜索关键词\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n\n**❗ --query 构造规则（必须遵守）**：\n\n`--query` 的值应完整保留用户意图中的所有要素，包括但不限于：商品描述、排序要求、筛选条件。禁止丢弃用户提及的排序/筛选信息。\n\n| 用户输入 | ✅ 正确的 --query | ❌ 错误的 --query |\n|---------|------------------|------------------|\n| 帮我找一件深绿色的始祖鸟同款冲锋衣，按销量倒排 | \"深绿色 始祖鸟同款 冲锋衣 销量排序\" | \"深绿色冲锋衣 始祖鸟同款\"|\n| 找价格100元以下的男士牛仔裤 | \"男士牛仔裤 价格100元以下\" | \"男士牛仔裤\" |\n\n### image_search（图片搜索）\n\n当用户上传图片找同款时使用。\n\n```bash\npython3 cli.py image_search --image \"/path/to/product.jpg\" --limit 10\n```\n\n**参数说明**：\n- `--image, -i`（必填）：图片本地路径或 URL。**本地图片必须使用绝对路径**（如 `/home/user/image.png` 或 `C:\\Users\\user\\image.png`），禁止使用相对路径（如 `./image.png`），否则在不同操作系统下可能因工作目录不一致导致找不到文件。\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n- `--threshold, -t`（可选）：相似度阈值，默认 `0.7`\n\n### link_search（链接搜索）\n\n当用户提供商品链接找同款时使用。\n\n```bash\n# 自动提取主图（仅 1688 支持）\npython3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"\n\n# 手动指定图片 URL（淘宝/天猫需要）\npython3 cli.py link_search --url \"https://item.taobao.com/item.htm?id=xxx\" --image \"图片URL\"\n```\n\n**参数说明**：\n- `--url, -u`（必填）：商品链接或商品 ID\n- `--image, -i`（可选）：商品图片 URL（当自动获取失败时使用）\n- `--platform, -p`（可选）：目标平台，默认 `1688`\n- `--limit, -l`（可选）：返回数量，默认 `10`\n\n**平台支持**：\n| 平台 | 自动提取主图 | 说明 |\n|------|-------------|------|\n| **1688** | ✅ 支持 | 自动从商品页面提取主图 |\n| **淘宝** | ❌ 不支持 | 需要用户手动提供图片 URL |\n| **天猫** | ❌ 不支持 | 需要用户手动提供图片 URL |\n\n**降级流程**：当 `link_search` 返回 `action: \"need_image_url\"` 时：\n1. 提示用户无法自动获取商品主图\n2. 引导用户手动复制商品图片 URL\n3. 使用 `--image` 参数重新执行搜索\n\n## 统一返回结构\n\n所有搜索能力返回相同的商品数据结构：\n\n```json\n{\n \"success\": true,\n \"query\": \"搜索词（仅 text_search）\",\n \"source_image\": \"图片 URL（image_search/link_search）\",\n \"source_url\": \"原始链接（仅 link_search）\",\n \"similar_products\": [\n {\n \"product_id\": \"商品 ID\",\n \"title\": \"商品标题\",\n \"image_url\": \"商品主图\",\n \"detail_url\": \"商品详情页链接\",\n \"similarity_score\": 0.95,\n \"source\": \"1688\",\n \"category_id\": \"类目 ID\",\n \"industry_name\": \"行业名称\"\n }\n ],\n \"search_type\": \"text_search|image_similarity|link_search\",\n \"total_results\": 6\n}\n```\n\n## 安全声明\n\n| 风险级别 | 命令 | Agent 行为 |\n|---------|------|-----------|\n| **只读** | text_search | 参数明确时直接执行 |\n| **只读** | image_search | 图片路径有效时直接执行 |\n| **只读** | link_search | URL 有效时直接执行；提取失败时引导用户提供图片 URL |\n\n## 执行前置（首次命中能力时必须）\n\n- 首次执行 `configure` 前：先完整阅读 `references/capabilities/configure.md`\n- 首次执行 `text_search` 前：先完整阅读 `references/capabilities/text_search.md`\n- 首次执行 `image_search` 前：先完整阅读 `references/capabilities/image_search.md`\n- 首次执行 `link_search` 前：先完整阅读 `references/capabilities/link_search.md`\n\n## 异常处理\n\n任何命令输出 `success: false` 时：\n\n1. **先输出 `markdown` 字段**（已包含用户可读的错误描述）\n2. **再根据关键词追加引导**：\n\n| markdown 关键词 | Agent 额外动作 |\n|----------------|--------------|\n| “AK 未配置” | 提示用户运行 `python3 cli.py configure YOUR_AK` 配置认证信息，如果用户还没有 API_KEY，引导前往 https://clawhub.1688.com/ 获取 |\n| \"签名无效\" 或 \"401\" | 提示用户检查 AK 是否正确或已过期 |\n| \"图片路径无效\" | 提示用户检查图片路径是否存在 |\n| \"无法自动获取商品主图\" | 引导用户手动提供商品图片 URL，使用 `--image` 参数 |\n| \"限流\" 或 \"429\" | 建议用户等待 1-2 分钟后重试 |\n| \"格式异常\" | 提示用户稍后重试，可能是 API 返回异常 |\n| 其他 | 仅输出 markdown 即可 |\n\n## 参数补齐引导话术\n\n> **文本搜索**：请描述您想要的商品，例如：\"帮我找一件黑色连帽卫衣，宽松款的\"\n\n> **图片搜索**：请上传商品图片，我会帮您找到同款或相似商品。\n\n> **链接搜索**：请提供商品链接。1688 链接可自动提取主图；淘宝/天猫链接需要您同时提供商品图片 URL。\n\n## 技术说明\n\n- **统一 API**：三个搜索能力共用 `/api/findProduct/1.0.0` 接口\n- **认证方式**：通过环境变量 `ALI_1688_AK` 配置\n- **依赖项**：Python 3.9+、requests、Pillow\n\n## 更新日志\n\n- v1.1.0 (2026-03-27): 新增 `cli.py` 统一 CLI 入口，简化命令调用方式\n- v1.0.0 (2026-03-27): 初始版本，包含三大核心搜索能力（text_search、image_search、link_search）\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn76msg8cwkep3b08z7zffx9fx82p5wj\",\n \"slug\": \"1688-product-find\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1775652123449\n}\n\nFile v0.1.0:references/capabilities/configure.md\n\n# AK 配置指南\n\n## 获取 AK（引导用户）\n\n当用户没有 AK 时，Agent 输出以下引导：\n\n> 请提供您的 AK（Access Key），用于接口调用的鉴权。\n> 如果还没有 API_KEY，请前往 https://clawhub.1688.com/ 获取。\n\n## Agent 配置流程（核心）\n\n用户告知 AK 后，Agent 按以下步骤执行：\n\n```\n1. 从用户消息中提取 AK 字符串\n2. 执行 cli.py configure \n3. 检查输出：success=true → 继续；success=false → 原样输出 markdown 错误信息\n4. 配置成功后由 OpenClaw 配置注入生效（不依赖本地会话缓存）；如当前会话仍未生效，提示用户新开会话或执行 `openclaw secrets reload`\n5. 继续用户的原始请求（如发送钉钉消息）；若用户仅提供了 AK 没有其他请求，告知\"配置成功，您可以发送钉钉消息了\"\n```\n\n## CLI 调用\n\n```bash\npython3 {baseDir}/cli.py configure YOUR_AK_HERE\n```\n\n无参数调用可查看当前配置状态：`python3 {baseDir}/cli.py configure`\n\n## 异常处理\n\n| 场景 | Agent 应对 |\n|------|-----------|\n| configure 输出 success=false | 原样输出 markdown 错误信息 |\n| 配置成功但后续命令仍报 AK 未配置 | 提示用户新开会话或执行 `openclaw secrets reload`，必要时再重试 configure |\n| 用户问“我的 AK 在哪” | 输出上方获取 AK 引导话术，并引导用户前往 https://clawhub.1688.com/ 获取 |\n\n通用 HTTP 异常（400/401/429/500）处理见 `references/common/error-handling.md`。\n\nFile v0.1.0:references/capabilities/image_search.md\n\n# Capability: image_search (图片找同款)\n\n## 功能说明\n基于用户上传的商品图片，通过图像识别和特征匹配，在 1688 平台搜索同款或相似商品。支持本地图片路径和图片 URL。\n\n## 触发方式\n**Skill 级触发词**: 图片找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含图片附件\n- 或消息中包含图片 URL\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"搜这个\"\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/image_search/cmd.py --image \"图片路径或URL\" [--platform 1688] [--limit 6] [--threshold 0.7]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 图片本地路径或 URL | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n| `--threshold` | `-t` | 相似度阈值 | 0.7 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 cmd.py -i /path/to/image.jpg\n\n# 指定返回数量\npython3 cmd.py -i /path/to/image.jpg -l 10\n\n# 完整参数\npython3 cmd.py -i /path/to/image.jpg -p 1688 -l 5 -t 0.8\n```\n\n## 输入参数\n```json\n{\n \"image_path\": \"string (required) - 本地图片路径或 URL\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\",\n \"similarity_threshold\": \"float (optional) - 相似度阈值，默认 0.7\"\n}\n```\n\n## 处理流程\n### 1. 图片预处理 (ImagePreprocessor)\n```python\n步骤：\n1. 判断输入类型（本地路径 / URL）\n2. 本地图片：检查文件存在性和大小\n3. 返回处理后的图片信息\n```\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 将图片通过 base64 编码转换成字符串\n2. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n3. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"imgBase64\": \"base64编码的图片字符串\",\n \"imageUrl\": \"图片URL（可选）\",\n \"pageSize\": 10\n }\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": {\n \"data\": [\n {\n \"itemId\": 987622522091,\n \"title\": \"商品标题\",\n \"imageUrl\": \"商品主图URL\",\n \"detailUrl\": \"商品详情页URL\",\n \"score\": 0.99786893,\n \"source\": \"1688\",\n \"cateId\": 201382421,\n \"industryName\": \"消费品\"\n }\n ],\n \"count\": 3\n }\n}\n```\n\n### 3. 浏览器降级方案 (_search_via_browser)\n当 API 不可用时，返回结构化信号，由 Agent 接管：\n```python\nreturn [{\n \"action\": \"browser_render\",\n \"url\": \"https://s.1688.com/selloffer/offer_search.htm\",\n \"upload_image\": image_path,\n \"message\": \"正在上传图片并搜索同款...\"\n}]\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"source_image\": \"/path/to/uploaded.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"跨境创意五彩公鸡动物摆件2D平面亚克力家居办公桌面装饰摆件\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"未定义产业名称\"\n }\n ],\n \"search_type\": \"image_similarity\",\n \"total_results\": 3\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/image_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── ImagePreprocessor # 图片预处理器\n ├── ImageSearchExecutor # 搜索执行器\n ├── format_similar_product() # 格式化输出\n └── image_search() # 主入口函数\n```\n\n## 错误处理\n- **图片路径无效**: 抛出 `ServiceError(\"图片路径无效\")`\n- **图片不存在**: 抛出 `FileNotFoundError`\n- **图片太大**: 抛出 `ValueError`（超过 5MB）\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n\n## 测试用例\n```python\n# 本地图片路径\nimage_search(image_path=\"/workspace/product.jpg\")\n\n# 图片 URL\nimage_search(image_path=\"https://example.com/product.png\")\n\n# 指定返回数量\nimage_search(image_path=\"xxx.jpg\", limit=10)\n\n# 调整相似度阈值\nimage_search(image_path=\"xxx.jpg\", similarity_threshold=0.8)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n\n## 注意事项\n1. 图片上传需考虑隐私和安全，临时文件会自动清理\n2. API 调用需要有效的 AK 配置\n3. 浏览器降级方案需要 Agent 接管处理\n\nFile v0.1.0:references/capabilities/link_search.md\n\n# Capability: link_search (链接找同款)\n\n## 功能说明\n解析用户提供的商品链接或商品 ID，自动识别平台，尝试静默获取商品主图，然后基于主图搜索同款或相似商品。与 image_search 和 text_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 链接找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含完整 URL (1688/淘宝/天猫)\n- 或纯商品 ID (6-12 位数字/字母组合)\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"这个的平价替代\"\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/link_search/cmd.py --url \"商品链接\" [--image \"图片URL\"] [--platform 1688] [--limit 6]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--url` | `-u` | 商品链接或商品 ID | 必需 |\n| `--image` | `-i` | 商品图片 URL（自动获取失败时使用） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n\n### 使用示例\n```bash\n# 基本用法（自动获取主图）\npython3 cmd.py -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 纯商品 ID\npython3 cmd.py -u \"895657286458\"\n\n# 手动指定商品图片（当自动获取失败时）\npython3 cmd.py -u \"https://detail.1688.com/offer/895657286458.html\" -i \"https://img.alicdn.com/xxx.jpg\"\n\n# 指定返回数量\npython3 cmd.py -u \"895657286458\" -l 10\n```\n\n## 输入参数\n```json\n{\n \"url\": \"string (required) - 商品链接或商品 ID\",\n \"image_url\": \"string (optional) - 商品图片 URL（自动获取失败时使用）\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\"\n}\n```\n\n## 处理流程\n\n### 1. 链接解析 (LinkParser)\n```python\n输入示例：\n- \"https://detail.1688.com/offer/895657286458.html\"\n- \"https://item.taobao.com/item.htm?id=1033765771797\"\n- \"895657286458\" (纯 ID)\n\n输出：\n{\n \"platform\": \"1688\",\n \"product_id\": \"895657286458\",\n \"canonical_url\": \"https://detail.1688.com/offer/895657286458.html\"\n}\n```\n\n**识别规则**:\n- **1688**: URL 包含 `1688.com` 且路径含 `offer`，ID 格式：6-12 位纯数字\n- **淘宝**: URL 包含 `taobao.com` 或 `tb.cn`，ID 格式：8-12 位字母数字\n- **天猫**: URL 包含 `tmall.com`，ID 格式同淘宝\n\n### 2. 商品主图提取 (ProductImageExtractor)\n**尝试静默获取商品主图**:\n1. 发起 HTTP 请求获取商品页面 HTML\n2. 根据以下特征判断商品主图：\n - 图片 URL 符合阿里图片服务模式（alicdn.com）\n - 包含 `ibank` 或 `imgextra` 标识\n - 过滤掉缩略图（如 `_50x50`、`_100x100`）\n3. 返回第一个符合条件的图片 URL\n\n**如果无法获取主图**:\n- 返回 `action: \"need_image_url\"` 信号\n- 提示用户手动输入商品图片 URL\n- 转到 image_search 流程完成功能\n\n### 3. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"imageUrl\": \"商品主图URL\",\n \"pageSize\": 10\n }\n}\n```\n\n## 输出格式\n\n### 成功获取主图时\n```json\n{\n \"success\": true,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"source_image\": \"https://img.alicdn.com/xxx.jpg\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"同款商品标题\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.9979,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"消费品\"\n }\n ],\n \"search_type\": \"link_search\",\n \"total_results\": 6\n}\n```\n\n### 无法获取主图时\n```json\n{\n \"success\": false,\n \"source_url\": \"https://detail.1688.com/offer/895657286458.html\",\n \"action\": \"need_image_url\",\n \"message\": \"无法自动获取商品主图，请手动输入商品图片 URL\",\n \"similar_products\": [],\n \"search_type\": \"link_search\",\n \"total_results\": 0\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/link_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── LinkParser # 链接解析器\n ├── ProductImageExtractor # 商品主图提取器\n ├── LinkSearchExecutor # 搜索执行器\n ├── format_link_search_result() # 格式化输出\n ├── link_search() # 主入口函数\n └── link_search_with_image() # 使用指定图片搜索\n```\n\n## 错误处理\n- **链接格式错误**: 抛出 `ValueError(\"无法识别的商品 ID 格式\")`\n- **不支持的平台**: 抛出 `ValueError(\"不支持的电商平台\")`\n- **无法获取主图**: 返回 `action: \"need_image_url\"` 信号\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n\n## 测试用例\n```python\n# 1688 链接\nlink_search(url=\"https://detail.1688.com/offer/895657286458.html\")\n\n# 淘宝链接\nlink_search(url=\"https://item.taobao.com/item.htm?id=1033765771797\")\n\n# 纯商品 ID\nlink_search(url=\"895657286458\")\n\n# 手动指定图片 URL\nlink_search_with_image(image_url=\"https://img.alicdn.com/xxx.jpg\", limit=10)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n- `requests` (可选): 用于获取商品页面 HTML\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`text_search` 使用同一 API path (`/api/findProduct/1.0.0`)\n- **降级策略**: 当无法获取主图时，提示用户手动输入图片 URL，转到 `image_search` 流程\n\n## 注意事项\n1. 静默获取主图依赖于页面的 HTML 结构，可能因页面变化而失效\n2. 部分商品页面可能需要登录才能访问，此时无法获取主图\n3. 建议用户直接提供商品图片 URL 以获得更稳定的搜索结果\n4. 返回的商品数据结构与 image_search 一致\n\nFile v0.1.0:references/capabilities/text_search.md\n\n# Capability: text_search (文本搜索)\n\n## 功能说明\n通过用户输入的关键词或自然语言描述，在 1688 平台搜索匹配的商品列表。与 image_search 和 link_search 共用同一 API 接口。\n\n## 触发方式\n**Skill 级触发词**: 找商品、搜商品、想要 XX、帮我找 XX\n\n**Capability 识别特征**:\n- 用户输入包含商品描述性语言\n- 不包含图片附件\n- 不包含完整 URL 链接\n\n## 前置条件\n- 已配置 AK（未配置时会提示运行 `cli.py configure YOUR_AK`）\n\n## CLI 调用\n```bash\npython3 {baseDir}/capabilities/text_search/cmd.py --query \"搜索关键词\" [--platform 1688] [--limit 6]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--query` | `-q` | 搜索关键词 | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 6 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 cmd.py -q \"黑色连帽卫衣\"\n\n# 指定返回数量\npython3 cmd.py -q \"手机壳\" -l 10\n\n# 完整参数\npython3 cmd.py -q \"男士牛仔裤 修身\" -p 1688 -l 5\n```\n\n## 输入参数\n```json\n{\n \"query\": \"string (required) - 搜索关键词\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 6\"\n}\n```\n\n## 处理流程\n### 1. 查询处理\n直接使用用户输入的关键词作为搜索条件。\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 拼装请求并调用 `/api/findProduct/1.0.0` 接口\n2. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"request\": {\n \"query\": \"搜索关键词\",\n \"pageSize\": 10\n }\n}\n```\n\n**API 响应格式**:\n```json\n{\n \"data\": [\n {\n \"industryName\": \"消费品\",\n \"score\": \"0.97332934\",\n \"itemId\": 984731164094,\n \"cateId\": 122698013,\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN018RgEjT1KiHAGIt18W_!!2212920081197-0-cib.jpg\",\n \"source\": \"1688\",\n \"detailUrl\": \"https://detail.1688.com/offer/984731164094.html\",\n \"recallSource\": \"same_product_recall\",\n \"title\": \"按摩垫按摩靠垫电动热敷按摩仪长导轨家用按摩仪揉捏腰部按摩器\",\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductItem\"\n }\n ],\n \"__msgCode__\": \"OK\",\n \"__success__\": true,\n \"count\": 1,\n \"intent\": {\n \"intentType\": \"IMAGE_SEARCH\",\n \"imageUrl\": \"https://img.alicdn.com/imgextra/O1CN01Mx7Qyb24jADQmO25X_!!2217083847426-0-cib.jpg\",\n \"findSame\": true,\n \"class\": \"com.alibaba.china.shared.tagspider.client.Model.aifindproduct.AiFindProductIntent\"\n }\n}\n```\n\n## 输出格式\n```json\n{\n \"success\": true,\n \"query\": \"黑色连帽卫衣\",\n \"similar_products\": [\n {\n \"product_id\": \"987622522091\",\n \"title\": \"2024新款黑色连帽卫衣男宽松加绒加厚秋冬季外套\",\n \"image_url\": \"https://img.alicdn.com/...\",\n \"detail_url\": \"https://detail.1688.com/offer/987622522091.html\",\n \"similarity_score\": 0.95,\n \"source\": \"1688\",\n \"category_id\": 201382421,\n \"industry_name\": \"消费品\"\n }\n ],\n \"search_type\": \"text_search\",\n \"total_results\": 6\n}\n```\n\n## 代码结构\n```\nscripts/capabilities/text_search/\n├── __init__.py # 模块初始化\n├── cmd.py # CLI 入口\n└── service.py # 核心服务实现\n ├── TextSearchExecutor # 搜索执行器\n ├── format_product_card() # 格式化输出\n └── text_search() # 主入口函数\n```\n\n## 错误处理\n- **AK 未配置**: 提示用户运行 `cli.py configure YOUR_AK`\n- **API 格式异常**: 抛出 `ServiceError(\"格式异常，请稍后重试\")`\n- **无搜索结果**: 返回空数组\n\n## 测试用例\n```python\n# 基础搜索\ntext_search(query=\"黑色连帽卫衣\")\n\n# 多关键词搜索\ntext_search(query=\"黑色连帽卫衣 宽松 加绒\")\n\n# 限定数量\ntext_search(query=\"手机壳\", limit=10)\n```\n\n## 依赖关系\n- `_http.api_post`: HTTP 请求封装\n- `_auth.get_ak_from_env`: AK 认证\n- `_errors.ServiceError`: 错误处理\n- `_output.print_output/print_error`: 输出格式化\n\n## 与其他能力的关系\n- **共用 API**: 与 `image_search`、`link_search` 使用同一 API path (`/api/findProduct/1.0.0`)\n- **区别**: text_search 通过 `query` 参数传递搜索词，而非图片\n\n## 注意事项\n1. 搜索关键词应尽量准确，避免过于宽泛\n2. API 调用需要有效的 AK 配置\n3. 返回的商品数据结构与 image_search 一致\n4. **--query 必须完整保留用户意图**：禁止丢弃用户提及的排序要求（如“按销量倒排”）、价格筛选（如“100元以下”）、品牌限定等信息，这些要素必须一并携带到 query 参数中\n\nFile v0.1.0:references/common/error-handling.md\n\n# 通用错误处理\n\n所有命令在遇到以下 HTTP / 业务错误时，遵循统一处理策略。\n\n## 错误码与 Agent 应对\n\n| 错误码 | 含义 | Agent 应对 |\n|--------|------|-----------|\n| — | AK 未配置（命令入口预检查） | 输出 AK 引导话术（见 SKILL.md） |\n| 400 | 参数不合法 | 检查用户输入（关键词、渠道、商品ID等）是否正确 |\n| 401 | 鉴权无效（AK 错误或已过期） | 输出 AK 引导话术（见 SKILL.md），引导用户重新配置 |\n| 429 | 请求被限流 | 建议用户稍后重试（通常等待 1-2 分钟） |\n| 500 | 服务端异常 | 建议用户稍后重试，如持续出现建议联系客服 |\n\n## 网络异常\n\nCLI 已内置 3 次重试（指数退避），重试耗尽后返回 `success: false`。\n\nAgent 应对：告知用户\"网络异常，请检查网络连接后重试\"。\n\n## 识别方式\n\n当 CLI 输出 `success: false` 时：\n\n1. 输出 `markdown` 字段（用户可读的错误描述）\n2. 检查 `markdown` 中的关键词（如 \"AK 未配置\"、\"401\"、\"授权过期\"、\"限流\"），按 SKILL.md 异常处理表追加对应引导\n\n## 各能力特有异常\n\n通用错误外的业务异常，见各能力文档的\"业务异常处理\"段。","readmeExcerpt":"Skill: 1688 Product Find Owner: 1688aiinfra Summary: 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找... Tags: latest:1.7.0 Version history: v0.27.0 | 2026-09-03T14:57:26.948Z | auto - 埋点上报接口和渠道字段更新：上报接口改为 /api/alibaba.1688.report.skills.usage/1.0.0，SKILL_CHANNEL 默认值改为 clawhubai - 错误处理策略调整：错误关键字和处理话术与新版接口返回保持同","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"用户输入\n├─ 纯文本描述商品 → text_search\n├─ 上传图片/链接\n│ ├─ 包含\"比价/比较/对比/哪家便宜\"等关键词 → compare（一步到位）\n│ └─ 仅\"找同款/找相似/搜这个\" → image_search 或 link_search\n└─ 已展示搜索结果，用户选中某款后说\"比价\" → compare（从结果取 image_url）"},{"language":"bash","snippet":"python3 {baseDir}/cli.py compare [--image \"商品图片URL\"] [--url \"商品链接\"] [--query \"附加关键词\"] [--limit 3] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]"},{"language":"bash","snippet":"# 场景1：基本比价（一步到位，无需先执行 image_search）\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒙奇奇 15CM 毛绒\"\n\n# 场景2：通过商品链接直接比价（一步到位，无需先执行 link_search）\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 场景3：通过纯商品 ID 比价\npython3 {baseDir}/cli.py compare -u \"895657286458\" -q \"不锈钢漏勺\"\n\n# 场景4：按价格从低到高排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc\n\n# 场景5：按销量从高到低排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s sold_desc\n\n# 场景6：降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" --score-level medium\n\n# 场景7：组合使用 - 按价格排序 + 中等相关性\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc --score-level medium\n\n# 场景8：使用默认 TOP 3 对比（推荐，不要随意修改 limit）\npython3 {baseDir}/cli.py compare -i \"https://img.alicdn.com/imgextra/xxx.jpg\"\n\n# 场景9：指定采购件数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" --purchase-amount 200\n\n# 场景10：完整参数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" -l 3 -s yx_desc --score-level high --purchase-amount 100 --tags \"4306497\"\n\n# 场景11：链接比价 + 关键词\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\" -q \"不锈钢漏勺\""},{"language":"markdown","snippet":"| 维度 | 推荐 1 (销量最高) | 推荐 2 (价格最低) | 推荐 3 (综合最优) |\n|:-----|:----------------|:----------------|:----------------|\n| 商品 | 铂佳无磁不锈钢漏勺... | 加大不锈钢花椒漏勺... | 新款不锈钢汤勺饭店... |\n| 💰 单价 | ￥1.19 | ￥3.80 | ￥3.89 |\n| 📦 规格 | 20cm 细网 | 25cm 粗网 | 30cm 加密 |\n| ⭐ 严选指数 | 85.23 | 72.50 | 90.16 |\n| 📊 起批量 | 100件 | 50件 | 200件 |\n| 销量 | 1.2万 | 856 | 2340 |\n| 库存 | 有货 | 有货 | 有货 |\n| 服务 | 7天无理由、48h发货 | 包邮、7天无理由 | 7天无理由 |\n| 卖点 | 爆款热销 | 工厂直供 | 品质保障 |\n| 供应商 | 义乌XX日用.. | 揭阳XX不锈钢.. | 潮安XX厨具.. |\n| 链接 | [查看](url1) | [查看](url2) | [查看](url3) |"},{"language":"markdown","snippet":"| 维度 | 推荐 1 (销量最高 且 综合最优) | 推荐 2 (价格最低) |\n|:-----|:---------------------------|:-----------------|\n| 商品 | XX商品... | YY商品... |\n| ... | ... | ... |"},{"language":"markdown","snippet":"**🏆 销量最高 且 价格最低 且 综合最优**\n\n| 维度 | 详情 |\n|:-----|:-----|\n| 商品 | XX不锈钢漏勺... |\n| 💰 单价 | ￥1.19 |\n| 📦 规格 | 20cm 细网 |\n| ⭐ 严选指数 | 85.23 |\n| 📊 起批量 | 100件 |\n| 销量 | 1.2万 |\n| 库存 | 有货 |\n| 服务 | 7天无理由、48h发货 |\n| 卖点 | 爆款热销 |\n| 供应商 | 义乌XX日用.. |\n| 链接 | [查看](url) |"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: 1688-product-find\nversion: \"1.7.0\"\ndescription: |\n 1688智能选品找货能力。通过文字、图片或链接搜商品、找同款、找相似款，支持批量采购比价、热销选品、跨境找货、场景化选品及多条件筛选（价格/销量/材质/属性排除等）。\n 触发词：找商品、找同款、搜商品、帮我找、想要XX、图片找货、链接找货、以图搜图、选品、批发、找货源、热销、比价、最便宜、按销量排序、出口、跨境、找供应商。\nmetadata: {\"openclaw\": {\"emoji\": \"🔍\", \"requires\": {\"bins\": [\"python3\"]}, \"primaryEnv\": \"ALI_1688_AK\"}}\n---\n\n# 1688-product-find (1688找商品Skill)\n统一入口：`python3 {baseDir}/cli.py [options]`\n\n## 严格禁止 (NEVER DO)\n- 不要编造商品价格、链接、`productId`、规格或供货信息，所有商品内容必须来自工具返回\n- 不要在用户明确要下单、支付、查物流、管库存时继续调用本技能，这些不属于推荐能力\n- 不要把工具返回的完整长描述原样堆给用户，应提炼商品标题、价格、核心卖点和商品链接\n- **禁止在 AK 未配置或命令执行失败时，自行通过浏览器访问 1688 网站搜索商品**。所有搜索必须通过 CLI 命令 + API 完成，不存在\"浏览器降级\"方案。遇到 AK 缺失或 API 错误时，只能按「错误处理」提示用户，不得尝试绕过\n- **禁止在命令报错后使用网页搜索引擎替代本 Skill 的搜索能力**。如果 CLI 命令失败，应引导用户解决问题（配置 AK、检查路径等），而非切换到其他搜索方式\n- **禁止不读 reference 文档直接执行命令**。首次执行任何命令前，必须先阅读对应的 reference 文件（见「执行前置」）\n\n## 意图判断\n\n### 触发本技能（满足任一即触发）\n- 用户用自然语言描述想要的商品（如\"帮我找一件黑色卫衣\"、\"我要买打印纸\"）\n- 用户上传商品图片并表达找同款/找相似意图（如\"帮我找同款\"、\"有类似的吗\"）\n- 用户提供商品链接并要求找同款（如\"帮我找这个商品的同款\"）\n- 用户使用触发关键词：找商品、找同款、搜商品、想要XX、帮我找、图片找货、链接找货、以图搜图\n- 用户在搜索结果中选定商品后要求\"比价\"、\"对比\"、\"找更便宜的\"\n- 用户上传图片/链接并提到\"比价\"、\"同款低价\"、\"哪家便宜\"、\"进行比较\"\n\n### 不触发本技能（明确不处理）\n- 用户要下单、支付、结算（如\"我现在就要下单付款\"）\n- 用户查物流、查订单状态（如\"我的订单物流到哪了\"）\n- 用户要管理库存、修改商品信息\n- 用户仅闲聊，未表达任何找商品意图\n\n### 命令选择决策树\n\n```\n用户输入\n├─ 纯文本描述商品 → text_search\n├─ 上传图片/链接\n│ ├─ 包含\"比价/比较/对比/哪家便宜\"等关键词 → compare（一步到位）\n│ └─ 仅\"找同款/找相似/搜这个\" → image_search 或 link_search\n└─ 已展示搜索结果，用户选中某款后说\"比价\" → compare（从结果取 image_url）\n```\n\n## Tool 总览\n\n| Tool 名称 | 用途 | 调用语法 |\n|-----------|------|---------|\n| `text_search` | 文本搜索商品 | `python3 cli.py text_search --query \"黑色连帽卫衣\"` |\n| `image_search` | 图片以图搜图 | `python3 cli.py image_search --image \"/path/to/image.jpg\"` |\n| `link_search` | 链接找同款 | `python3 cli.py link_search --url \"https://detail.1688.com/offer/xxx.html\"` |\n| `compare` | 商品比价 | `python3 cli.py compare --image \"商品图片URL\" [--query \"规格关键词\"]` 或 `python3 cli.py compare --url \"商品链接\"` |\n| `configure` | AK 管理 | `cli.py configure YOUR_AK`（设置）/ `--status`（查看）/ `--clear`（清除）/ `--reset NEW_AK`（重置） |\n| `get_ak` | 自动获取 AK | `cli.py get_ak` |\n\n所有命令输出 JSON：`{\"success\": bool, \"markdown\": str, \"data\": {...}}`\n\n## ⚠️ 执行前置（首次命中能力时必须）\n\n**首次执行任何命令前，必须先完整阅读对应的 reference 文件，按文件中的使用示例调用。禁止跳过此步骤直接执行命令。**\n\n| 命令 | 执行前必读 |\n|------|-----------|\n| `configure` | `references/capabilities/configure.md` |\n| `text_search` | `references/capabilities/text_search.md` |\n| `image_search` | `references/capabilities/image_search.md` |\n| `link_search` | `references/capabilities/link_search.md` |\n| `compare` | `references/capabilities/compare.md` |\n\n> reference 文件中包含完整的参数说明、使用示例、输出格式和注意事项。Agent 必须按 reference 中的示例格式构造命令，不得凭猜测拼接参数。\n\n## 核心工作流\n\nAgent 根据用户意图，**先读 reference → 再按示例执行命令**（命令速查见上方「Tool 总览」）。\n各命令在 AK 缺失等情况下会自行返回明确错误，Agent 按下方「错误处理」应对即可。\n\n### 比价流程（特殊工作流）\n\n**核心原则：图片/链接默认为找同款，仅用户明确要求比价时才用 compare**\n\n**场景1：直接比价**（一步到位）\n- 用户上传图片并要求比价 → 直接执行 `compare --image <图片> --query <关键词>`\n- 用户给链接并要求比价 → 直接执行 `compare --url <链接> [--query <关键词>]`\n- **禁止**先执行 `image_search` 或 `link_search`，`compare` 内部已包含图片搜索和链接解析逻辑\n"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn76msg8cwkep3b08z7zffx9fx82p5wj\",\n \"slug\": \"1688-product-find\",\n \"version\": \"0.27.0\",\n \"publishedAt\": 1788447446948\n}"},{"path":"references/capabilities/compare.md","content":"# Capability: compare (商品比价)\n\n## 功能说明\n基于用户选中商品的图片或商品链接，通过以图搜图找到同款商品，自动按销量、价格、服务三个维度各选出 1 款代表性商品，生成纵向对比表。\n\n## 触发方式\n**Skill 级触发词**: 比价、对比、哪家便宜、找更便宜的、同款低价、进行比较\n\n**Capability 识别特征**:\n- 用户上传图片/链接并**明确要求比价**（如“找同款并比价”、“找到同款进行比较”）\n- 用户在搜索结果中选定某款商品后要求比价/对比\n- 用户使用“比一比”、“哪家便宜”、“低价同款”等关键词\n\n**❗ 商品链接直接比价**：\n- 用户给到商品链接且意图包含比价 → 直接使用 `compare --url`，一步到位\n- **禁止**先执行 `link_search` 再执行 `compare`，`compare --url` 内部已包含链接解析+主图提取+比价逻辑\n\n**⚠️ 意图判断核心原则**:\n- **上传图片/链接时，默认是找同款，使用 `image_search` 或 `link_search`**\n- **仅在用户明确提到“比价/比较/对比”时，才使用 `compare`**\n- `compare` 命令内部已包含以图搜图/链接解析逻辑，一步到位完成搜索+比价\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。\n- 需要商品图片或商品链接（支持以下四种输入方式，二选一）：\n - **URL 图片**：在线图片链接，如 `https://img.alicdn.com/xxx.jpg`\n - **本地图片**：本地文件路径，如 `/path/to/image.jpg`（自动预处理：缩放 + 格式转换）\n - **搜索结果中的图片**：从前序搜索结果的 `image_url` 字段提取\n - **商品链接/ID**：1688/淘宝/天猫商品链接或纯商品 ID（自动解析链接并提取主图）\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py compare [--image \"商品图片URL\"] [--url \"商品链接\"] [--query \"附加关键词\"] [--limit 3] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n> `--image` 和 `--url` 二选一，必须提供其中一个。两者都提供时优先使用 `--image`。\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 商品图片 URL 或本地路径（与 `--url` 二选一） | 可选 |\n| `--url` | `-u` | 商品链接或商品 ID（自动提取主图，与 `--image` 二选一） | 可选 |\n| `--query` | `-q` | 附加关键词（规格、品类等） | 可选 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 对比商品数量 | 3 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n**支持的图片输入格式**：\n- URL：`https://xxx.jpg`、`https://xxx.png` 等\n- 本地路径：`/path/to/image.jpg`、`C:\\Users\\image.png` 等（支持 JPG、PNG、GIF、BMP、WEBP 等格式）\n- 本地图片会自动预处理：超尺寸自动缩放、非 JPEG 格式自动转换\n\n### 使用示例\n```bash\n# 场景1：基本比价（一步到位，无需先执行 image_search）\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒙奇奇 15CM 毛绒\"\n\n# 场景2：通过商品链接直接比价（一步到位，无需先执行 link_search）\npython3 {baseDir}/cli.py compare -u \"https://detail.1688.com/offer/895657286458.html\"\n\n# 场景3：通过纯商品 ID 比价\npython3 {baseDir}/cli.py compare -u \"895657286458\" -q \"不锈钢漏勺\"\n\n# 场景4：按价格从低到高排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc\n\n# 场景5：按销量从高到低排序\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s sold_desc\n\n# 场景6：降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" --score-level medium\n\n# 场景7：组合使用 - 按价格排序 + 中等相关性\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -s price_asc --score-level medium\n\n# 场景8：使用默认 TOP 3 对比（推荐，不要随意修改 limit）\npython3 {baseDir}/cli.py compare -i \"https://img.alicdn.com/imgextra/xxx.jpg\"\n\n# 场景9：指定采购件数\npython3 {baseDir}/cli.py compare -i \"/path/to/image.jpg\" -q \"蒸汽拖把\" --purchase-amount 200\n\n# 场景10：完整参数\npython3 {baseDir}/cli.py compare -i \"/p"},{"path":"references/capabilities/configure.md","content":"# Capability: configure (AK配置和管理)\n\n## 使用示例\n\n```bash\n# 自动获取 AK（启动浏览器授权流程）\npython3 {baseDir}/cli.py get_ak\n\n# 配置 AK\npython3 {baseDir}/cli.py configure YOUR_AK_HERE\n\n# 查看 AK 配置状态（无参数等同于 --status）\npython3 {baseDir}/cli.py configure\npython3 {baseDir}/cli.py configure --status\n\n# 重置 AK（清除旧 Token + 配置新 AK）\npython3 {baseDir}/cli.py configure --reset NEW_AK_HERE\n\n# 清除 AK（同时清除关联的 OAuth Token）\npython3 {baseDir}/cli.py configure --clear\n\n```\n\n## 命令参数\n\n| 参数形式 | 说明 |\n|---------|------|\n| `` | 直接配置新 AK。若已有旧 AK 且不同，自动清除旧 Token |\n| `--status` | 查看当前 AK 配置状态（无参数调用时默认行为） |\n| `--clear` | 清除 AK 并同步清除关联的 OAuth Token |\n| `--reset ` | 重置 AK：清除旧 Token → 写入新 AK |\n| （无参数） | 等同于 `--status` |\n\n## ⚠️ AK 检查机制（Agent 必读）\n\n**判断 AK 是否已配置，不应仅依据用户消息或对话历史。** 正确做法：\n\n1. **直接执行用户请求的搜索命令**（text_search / image_search / link_search / compare）\n2. 如果 AK 未配置，CLI 会返回 `success: false` + \"AK 未配置\" 提示\n3. 此时按下方「AK 缺失时的处理流程」应对\n\n也可主动查询状态：`python3 {baseDir}/cli.py configure`（无参数）\n\n**禁止以下行为**：\n- ❌ 仅因对话中没出现过 AK 就认为未配置（AK 可能已持久化在配置文件中）\n- ❌ 仅因之前配置过就认为仍有效（AK 可能已过期或被清除）\n- ❌ 跳过 CLI 检查直接要求用户提供 AK\n- ❌ 在搜索前主动调用 configure 检查（应直接执行搜索，让 CLI 自动判断）\n\n## AK 缺失时的处理流程\n\n当 CLI 返回 \"AK 未配置\" 错误时，Agent **按顺序**执行：\n\n**第一步：自动获取（优先）**\n\n```bash\npython3 {baseDir}/cli.py get_ak\n```\n\n- 启动本地回调服务器 + 打开浏览器授权页面\n- 用户在浏览器完成登录后，AK 自动保存\n- `success: true` → 配置成功，**立即继续执行用户的原始请求**\n- `success: false` → 进入第二步\n\n**第二步：引导手动配置（回退）**\n\n输出以下话术：\n\n> 自动获取 AK 失败。请手动提供您的 AK（Access Key），用于接口调用的鉴权。\n> 如果还没有 API_KEY，请前往 https://clawhub.1688.com/ 获取。\n\n用户提供 AK 后执行：\n\n```bash\npython3 {baseDir}/cli.py configure <用户提供的AK>\n```\n\n配置成功后，**继续执行用户的原始请求**（如搜索商品）。\n\n## 输出格式\n\n所有输出为标准 JSON：\n\n```json\n{\"success\": bool, \"markdown\": \"...\", \"data\": {\"configured\": bool, \"ak\": \"...\"}}\n```\n\n| 场景 | success | markdown |\n|------|---------|----------|\n| 配置成功 | `true` | `✅ AK 设置成功` |\n| 配置成功（替换旧 AK） | `true` | `✅ AK 设置成功\\n\\n旧的 1688 OAuth Token 已同步清除` |\n| 重置成功 | `true` | `✅ AK 已重置\\n\\n旧的 1688 OAuth Token 已同步清除。` |\n| 清除成功 | `true` | `AK 已清除，关联的 1688 OAuth Token 也已同步清除。` |\n| 无需清除 | `true` | `当前未配置 AK，无需清除。` |\n| 状态：已配置 | `true` | `AK 已配置。\\n\\n**AK**: \\`xxx\\`` |\n| 状态：未配置 | `true` | `AK 未配置。` |\n| AK 格式错误 | `false` | `❌ AK 长度不足（当前 N，需要至少 32 位）` |\n| 写入失败 | `false` | `❌ AK 写入失败，请检查文件权限` |\n| 缺少参数 | `false` | `缺少参数：\\`--reset\\` 后需要提供新的 AK` |\n\n## 异常处理\n\n| 场景 | Agent 应对 |\n|------|-----------|\n| configure 输出 success=false | 原样输出 markdown 错误信息 |\n| 配置成功但后续命令仍报 AK 未配置 | 提示用户新开会话或执行 `openclaw secrets reload`，必要时再重试 configure |\n| 用户问\"我的 AK 在哪\" | 输出获取 AK 引导话术，引导前往 https://clawhub.1688.com/ 获取 |\n\n通用 HTTP 异常（400/401/429/500）处理见 `references/common/error-handling.md`。\n\n---\n\n## 附录：内部机制（Agent 无需主动操作）\n\n以下为系统内部实现细节，Agent 了解即可，**不需要手动执行这些逻辑**。\n\n### AK 校验规则\n\nconfigure 内部会自动校验 AK 格式：\n- 不能为空\n- 长度至少 32 位\n- 仅允许字母、数字及 `_-=` 字符\n\n校验失败时 CLI 会返回明确的 `success: false` 错误信息。\n\n### AK 读取优先级\n\n系统内部按以下优先级自动读取 AK（Agent 无需关心路径细节）：\n\n1. 环境变量 `ALI_1688_AK`（OpenClaw 平台注入，最高优先级）\n2. 配置文件 `{workspace}/.1688-AK/.ak_store.json`（多个候选路径自动遍历）\n\n配置文件格式：`{\"ak\": \"...\"}`\n\n### Token 联动清除\n\n以下操作会自动清除关联的 OAuth Token（Agent 无需手动清 Token）：\n\n| 操作 | Token 清除条件 |\n"},{"path":"references/capabilities/image_search.md","content":"# Capability: image_search (图片找同款)\n\n## 功能说明\n基于用户上传的商品图片，通过图像识别和特征匹配，在 1688 平台搜索同款或相似商品。支持本地图片路径和图片 URL。\n\n## 触发方式\n**Skill 级触发词**: 图片找货、找同款、搜相似\n\n**Capability 识别特征**:\n- 用户输入包含图片附件\n- 或消息中包含图片 URL\n- 配合文字：\"找同款\"、\"有类似的吗\"、\"搜这个\"\n\n## 前置条件\n- 已配置 AK。**Agent 判断 AK 是否已配置时，必须通过执行 `cli.py configure`（无参数）确认，禁止仅凭环境变量或对话历史判断**。AK 可能已持久化在本地配置文件中，即使当前对话未提及也可能已配置。\n\n## CLI 调用（Agent 执行时必须使用）\n```bash\npython3 {baseDir}/cli.py image_search --image \"图片路径或URL\" [--limit 10] [--sort price_asc] [--score-level high] [--purchase-amount 1] [--tags 4306497] [--ic-tags \"\"]\n```\n\n### 命令行参数\n| 参数 | 简写 | 说明 | 默认值 |\n|------|------|------|--------|\n| `--image` | `-i` | 图片本地路径或 URL | 必需 |\n| `--platform` | `-p` | 目标平台 | 1688 |\n| `--limit` | `-l` | 返回数量 | 10 |\n| `--sort` | `-s` | 排序方式：`price_asc`(价格低→高)、`price_desc`(价格高→低)、`sold_desc`(销量高→低)、`yx_desc`(严选指数高→低) | 无（默认排序） |\n| `--score-level` | - | 相关性档位：`high`(高)、`medium`(中)、`low`(低) | `high` |\n| `--purchase-amount` | - | 采购件数（正整数，不支持范围） | `1` |\n| `--tags` | - | TC标（品池标签），英文逗号分隔 | `4306497` |\n| `--ic-tags` | - | IC标（品池标签），英文逗号分隔 | 无 |\n\n### 使用示例\n```bash\n# 基本用法\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg\n\n# 指定返回数量\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -l 10\n\n# 按价格从低到高排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s price_asc\n\n# 按销量从高到低排序\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -s sold_desc\n\n# 降低相关性要求，召回更多商品\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --score-level medium\n\n# 指定采购件数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --purchase-amount 100\n\n# 指定品池标签\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg --tags \"4306497\"\n\n# 完整参数\npython3 {baseDir}/cli.py image_search -i /path/to/image.jpg -p 1688 -l 5 -s price_asc --score-level high --purchase-amount 50 --tags \"4306497\"\n```\n\n## 输入参数\n```json\n{\n \"image_path\": \"string (required) - 本地图片路径或 URL\",\n \"platform\": \"string (optional) - 目标平台，默认 1688\",\n \"limit\": \"int (optional) - 返回数量，默认 10\",\n \"sort_type\": \"string (optional) - 排序方式（price_asc/price_desc/sold_desc/yx_desc）\",\n \"score_level\": \"string (optional) - 相关性档位（high/medium/low），默认 high\",\n \"purchase_amount\": \"int (optional) - 采购件数，默认 1\",\n \"tags\": \"string (optional) - TC标（品池标签），英文逗号分隔，默认 4306497\",\n \"ic_tags\": \"string (optional) - IC标（品池标签），英文逗号分隔\"\n}\n```\n\n## 处理流程\n### 1. 图片预处理 (ImagePreprocessor)\n```python\n步骤：\n1. 判断输入类型（本地路径 / URL）\n2. 本地图片：检查文件存在性和大小\n3. 返回处理后的图片信息\n```\n\n### 2. API 搜索 (_search_via_api)\n**主要流程**:\n1. 将图片通过 base64 编码转换成字符串\n2. 拼装请求并调用 `/api/alibaba.1688.find.product/1.0.0` 接口\n3. 解析返回的商品数据\n\n**API 请求格式**:\n```json\n{\n \"imgBase64\": \"base64编码的图片字符串\",\n \"imageUrl\": \"图片URL（可选）\",\n \"pageSize\": 10,\n \"purchaseAmount\": 1,\n \"sortType\": \"price_asc\",\n \"scoreLevel\": \"high\",\n \"tags\": \"4306497\",\n \"icTags\": \"标签值（可选）\"\n}\n```\n> `sortType` 和 `scoreLevel` 为可选字段，不传则使用默认值。\n\n**API 响应格式**:\n```json\n{\n \"data\": {\n \"data\": [\n {\n \"itemId\": 987622522091,\n \"title\": \"商品标题\",\n \"imageUrl\": \"商品主图URL\",\n \"detailUrl\": \"商品详情页URL"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":993,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:10:58.538Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:09:37.508Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}