{"id":"b23777f9-aeec-48fd-b19f-ac74f1b31653","entityType":"agent","slug":"clawhub-linkfox-ai-linkfox-1688-procurement","name":"1688采购全流程","canonicalUrl":"https://www.xpersona.co/agent/clawhub-linkfox-ai-linkfox-1688-procurement","canonicalPath":"/agent/clawhub-linkfox-ai-linkfox-1688-procurement","generatedAt":"2026-10-11T14:15:04.809Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T11:29:40.039Z","emptyReason":null},"description":"1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 Skill: 1688采购全流程 Owner: linkfox-ai Summary: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 Tags: latest:1.0.5 Version history: v1.0.5 | 2026-09-14T04:52:09.546Z | user Update from 1.0.4 to 1.0.5 v1.0.4 | 2026-08-21T10:1","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-1688-procurement","sourceUrl":"https://clawhub.ai/linkfox-ai/linkfox-1688-procurement","homepage":"https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/linkfox-ai/linkfox-1688-procurement","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:29:40.039Z","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-11T11:29:40.039Z","emptyReason":null},"stars":null,"forks":null,"downloads":1076,"packageName":null,"latestVersion":"1.0.5","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T11:29:40.024Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T11:29:40.039Z","lastCrawledAt":"2026-10-11T11:29:40.024Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T11:29:40.024Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.5","createdAt":"2026-09-14T04:52:09.546Z","changelog":"Update from 1.0.4 to 1.0.5","fileCount":22,"zipByteSize":36540},{"version":"1.0.4","createdAt":"2026-08-21T10:11:10.245Z","changelog":"Update from 1.0.3 to 1.0.4","fileCount":22,"zipByteSize":36503},{"version":"1.0.3","createdAt":"2026-08-14T14:38:46.924Z","changelog":"Update from 1.0.2 to 1.0.3","fileCount":22,"zipByteSize":36261},{"version":"1.0.2","createdAt":"2026-08-07T10:34:20.919Z","changelog":"Update from 1.0.1 to 1.0.2","fileCount":22,"zipByteSize":36342},{"version":"1.0.1","createdAt":"2026-07-13T12:00:37.953Z","changelog":"Update from 1.0.0 to 1.0.1","fileCount":18,"zipByteSize":20372},{"version":"1.0.0","createdAt":"2026-07-10T05:39:40.335Z","changelog":"Initial release","fileCount":18,"zipByteSize":19285}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s171g8b6m2khwdy9ye8bxj0wx183vd4z:linkfox-1688-procurement","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"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-linkfox-ai-linkfox-1688-procurement/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/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-11T14:15:04.803Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-linkfox-ai-linkfox-1688-procurement/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":"high","updatedAt":"2026-10-11T11:29:40.039Z","emptyReason":null},"readme":"Skill: 1688采购全流程\n\nOwner: linkfox-ai\n\nSummary: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n\nTags: latest:1.0.5\n\nVersion history:\n\nv1.0.5 | 2026-09-14T04:52:09.546Z | user\n\nUpdate from 1.0.4 to 1.0.5\n\nv1.0.4 | 2026-08-21T10:11:10.245Z | user\n\nUpdate from 1.0.3 to 1.0.4\n\nv1.0.3 | 2026-08-14T14:38:46.924Z | user\n\nUpdate from 1.0.2 to 1.0.3\n\nv1.0.2 | 2026-08-07T10:34:20.919Z | user\n\nUpdate from 1.0.1 to 1.0.2\n\nv1.0.1 | 2026-07-13T12:00:37.953Z | user\n\nUpdate from 1.0.0 to 1.0.1\n\nv1.0.0 | 2026-07-10T05:39:40.335Z | user\n\nInitial release\n\nArchive index:\n\nArchive v1.0.5: 22 files, 36540 bytes\n\nFiles: references/api.md (17994b), references/onboarding.md (1999b), references/workflow.md (9584b), scripts/_alibaba1688_common.py (15106b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/invoice_amount.py (125b), scripts/invoice_apply.py (124b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24027b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (3012b), SKILL.md (13820b), _meta.json (143b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in `linkfox-1688-search-by-image`.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like \"continue\".\n- Use exact internal request field names from `references/api.md` when calling scripts. Do not show these field names in normal user-facing text.\n- Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per `references/api.md`; do not mention procurement type or ask users to choose one.\n- `cancel_order.py` only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and address |\n| `create_order.py` | High | Yes | Create a 1688 order |\n| `payment_url.py` | High | Yes | Get payment URL |\n| `order_status.py` | Low | Yes | Query order status |\n| `logistics.py` | Low | Yes | Query logistics summary |\n| `logistics_trace.py` | Low | Yes | Query logistics trace |\n| `confirm_receive.py` | High | Yes | Confirm receipt |\n| `cancel_order.py` | High | Yes | Cancel order |\n| `invoice_amount.py` | Low | Yes | Query invoiceable amount before applying for an invoice |\n| `invoice_apply.py` | High | Yes | Apply for an invoice after order completion |\n\n## 调用方式\n\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}`（完整参数、响应和错误处理见 `references/api.md`）\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`\n- **成本约束**：本工具会消耗算力。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。\n- **缓存约束**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。\n- **授权约束**：除 `authorize_url.py` 和 `authorized_stores.py` 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。\n- **授权刷新**：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用 `authorizedStores` 或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（`authorizedStores` 返回 `expired=true`）时才需要重新走 `authorize_url.py` 授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。\n- **高风险约束**：`create_order.py`、`payment_url.py`、`confirm_receive.py`、`cancel_order.py`、`invoice_apply.py` 必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n**脚本入参方式**：\n\n- 直接传 JSON 字符串：`python scripts/sku.py '{\"offerId\":\"...\"}'`\n- 从环境变量读取：`python scripts/sku.py --payload-env PAYLOAD`\n- 从文件读取：`python scripts/sku.py --payload-file payload.json`\n- 加 `--inline` 强制全量打印到 stdout\n- 加 `--save` 强制保存对 token 类敏感字段脱敏\n- 加 `--no-save` 禁止保存响应文件\n\n**输出策略（脚本默认行为）**：\n\n- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。\n- 响应体 > 8 KB：默认将完整脱敏响应写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。\n- `<writable-root>` 优先取 `ACPX_WORKSPACES` 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；`<session>` 取自环境变量 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。\n- 加 `--save` 或设置 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；加 `--no-save` 或设置 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存；`--inline` 不隐含保存。\n\n**读数据建议**：先看 stdout 摘要判断是否足够；需要保存完整响应再加 `--save`，之后优先用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和算力问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示算力或余额不足**：消息含\"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## High-Risk Confirmation\n\nAsk the user for a separate Chinese natural-language confirmation immediately before each high-risk call, restating the exact order/action summary in business terms only. If the immediately preceding assistant message clearly asks for confirmation of one specific high-risk action, a reply of \"确认\" is valid. Earlier phrases such as \"继续\", \"可以\", or \"按上面来\" are not valid for later high-risk actions. Do not ask the user to type English parameter names.\n\nAfter the user confirms in Chinese, the Agent must add the internal safety field required by `references/api.md` when calling the script. Never mention internal fields, request field names, or backend defaults in user-facing confirmation text unless debugging a tool error.\n\n## Common Workflow\n\n1. Run `authorized_stores.py`; continue only when the current user has an ACTIVE, unexpired 1688 authorization.\n2. If not authorized, run `authorize_url.py`, let the user complete OAuth, then re-check `authorized_stores.py`.\n3. If starting from an image, use `linkfox-1688-search-by-image` to get an `offerId`.\n4. Run `sku.py`, then `receive_address_list.py`, then `order_preview.py`.\n5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.\n6. Only after separate Chinese confirmation, run `create_order.py`; add required safety fields internally without showing them to the user.\n7. Only after separate Chinese confirmation, run `payment_url.py`; pass the created order ID internally without showing request field names to the user.\n8. Use `order_status.py`, `logistics.py`, and `logistics_trace.py` for tracking.\n9. Use `cancel_order.py` and `confirm_receive.py` only after separate confirmations for the exact order and action; pass the selected 1688 order ID internally. Do not describe cancellation as refund handling for paid orders.\n10. After receipt confirmation, run `invoice_amount.py` to query the invoiceable amount and whether each order can be invoiced; pass the returned `amount` as-is (do not recompute). Only after separate Chinese confirmation of the invoice type, title, and amount, run `invoice_apply.py`; pass `confirmApplyInvoice=true` and the amount internally. Walk `successList`/`failedList` per order; treat `INVOICE_ALREADY_APPLIED` as already-invoiced, not an error.\n\n## Display Rules\n\n1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.\n2. `authorizedStores` output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.\n3. For authorization, only tell the user whether it is available or whether re-authorization is required. Do not display token expiry times, token validity periods, refresh windows, or internal fields such as `tokenExpiresAt`.\n4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.\n5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.\n6. Before high-risk calls, summarize the exact operation, key IDs, amount/status when available, then ask the user to confirm in Chinese. Do not show internal boolean fields, request field names, or implementation details.\n7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.\n8. Report `costToken` or equivalent cost fields only when returned.\n\n## Important Limitations\n\n- Do not create or call image-search scripts here; image search belongs to `linkfox-1688-search-by-image`.\n- Do not expose `/alibaba1688/proxy/callback`, `/alibaba1688/authorizeCallback`, or browser OAuth callback URLs as Skill capabilities.\n- Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.\n- Do not query backend databases to discover authorization state. Use `authorizedStores`.\n- Do not automatically retry write operations or run the full purchase loop.\n- Do not use `_dataQuery_executeDynamicQuery` for live procurement responses.\n\n## User Expression & Scenario Quick Reference\n\n**Applicable** -- 1688 procurement scenarios:\n\n| User Says | Scenario |\n|-----------|----------|\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | Authorization check |\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | New OAuth authorization |\n| \"查这个 offerId 的 SKU\" | SKU lookup |\n| \"查1688收货地址\" | Receive address lookup |\n| \"帮我预览1688订单\" | Order preview |\n| \"确认下单\" | High-risk create order gate |\n| \"获取支付链接\" | High-risk payment URL gate |\n| \"查1688订单状态/物流\" | Order tracking |\n| \"取消这个1688订单\" | High-risk cancel gate |\n| \"确认收货\" | High-risk confirm receive gate |\n| \"查1688可开票金额\" / \"这个订单能开发票吗\" | Invoiceable amount query |\n| \"给这个1688订单开发票\" / \"确认开票\" | High-risk invoice apply gate |\n\n**Not applicable** -- use another skill or backend system:\n\n- Image-based 1688 product discovery -> `linkfox-1688-search-by-image`\n- Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available\n- MyERP OAuth callback/proxy callback handling -> backend service, not a Skill\n- Direct token repair or manual 1688 token input -> backend authorization bridge\n\n## Feedback\n\nAuto-detect and report feedback via the Feedback API when actual behavior differs from this skill, results do not match user intent, the user expresses satisfaction/dissatisfaction, or anything could be improved. Call the Feedback API as specified in `references/api.md` without interrupting the user's flow. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback content.\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.5:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-procurement\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1789361529546\n}\n\nFile v1.0.5:references/api.md\n\n# 1688采购流程 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/<endpoint>`，默认网关为 `https://tool-gateway.linkfox.com`\n- **请求方式**：POST，Content-Type: `application/json; charset=utf-8`\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置，按 SKILL.md 的 **## 解决认证和算力问题** 处理）\n- **User-Agent**：`LinkFox-Skill/2.0`\n- **超时**：150s\n- **缓存**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\n\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n## API 与脚本\n\n| 能力 | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\n|---|---|---|---|---|---|\n| 生成授权链接 | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\n| 查询已授权账号 | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\n| 查询收货地址 | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\n| 查询 SKU | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\n| 下单预览 | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\n| 创建订单 | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\n| 获取支付链接 | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\n| 查询订单状态 | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\n| 查询物流 | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\n| 查询物流轨迹 | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\n| 确认收货 | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\n| 取消订单 | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\n| 查询可开票金额 | `/alibaba1688/invoiceAmount` | `invoice_amount.py` | 低 | 是 | - |\n| 申请开票 | `/alibaba1688/invoiceApply` | `invoice_apply.py` | 高 | 是 | `confirmApplyInvoice=true` |\n\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。不要把 `/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、`/alibaba1688/oauth/callback` 暴露为 Skill 能力。\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 能力 | 参数 | 必填 | 说明 |\n|---|---|---:|---|\n| `authorizeUrl` | `accountName` | 是 | 授权账号展示名，用于标识本次 1688 OAuth 授权。 |\n| `authorizedStores` | - | 否 | 通常传 `{}`。返回当前 LinkFox 用户的 1688 授权状态，不是全库账号列表。 |\n| `receiveAddressList` | - | 否 | 通常传 `{}`。返回当前用户可用收货地址。 |\n| `sku` | `offerId` | 是 | 1688 商品 ID，必须用字符串，避免 JS 大数精度丢失。 |\n| `orderPreview` | `addressId` 或 `addressParam` | 条件必填 | 二选一。优先使用 `receiveAddressList` 返回的 `addressId`；`addressParam` 至少含 `fullName`、`mobile`、`address`。 |\n| `orderPreview` | `cargoParamList` | 是 | 货品列表，每项含 `offerId`、可选 `specId`、`quantity`；`quantity >= 1`。 |\n| `orderPreview` | `flow` | 是 | 下单流程类型。当前主流程为普通采购，默认 `general`；脚本缺省时会补 `general`，直接调 API 时必须显式传。仅当用户明确要求分销/精选货源分销时，才可透传 `fenxiao`/`boutiquefenxiao`；本 Skill 不提供分销专属校验或保障。 |\n| `orderPreview` | `isvBizType` | 否 | 默认 `cross`；仅支持 `cross`、`cross_daigou`、`cross_distribution`。 |\n| `createOrder` | `confirmCreateOrder` | 是 | 必须是 JSON boolean `true`。未传或 false 时不会调用 1688 下单。 |\n| `createOrder` | 下单参数 | 是 | 与 `orderPreview` 保持一致，必须显式包含相同 `flow`；可额外传 `message`、`tradeType`、`shopPromotionId`、`useRedEnvelope`、`anonymousBuyer`、`outOrderId` 等。 |\n| `createOrder` | `useRedEnvelope` | 否 | 是否使用红包，仅支持 `y`/`n`；默认 `n`。 |\n| `paymentUrl` | `confirmGetPaymentUrl` | 是 | 必须是 JSON boolean `true`。只获取支付链接，不自动打开、不自动支付。 |\n| `paymentUrl` | `orderIdList` | 是 | 1688 订单 ID 字符串数组。使用 `createOrder` 返回的 `orderId`。 |\n| `orderStatus` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logistics` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `logisticsId` | 否 | 物流订单 ID；多个物流单时建议从 `logistics` 返回中选择。 |\n| `confirmReceive` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `confirmReceive` | `confirmReceive` | 是 | 必须是 JSON boolean `true`。确认收货不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `cancelOrder` | `confirmCancel` | 是 | 必须是 JSON boolean `true`。取消订单不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `cancelReason`、`remark` | 否 | 取消原因和备注，非空时透传。 |\n| `invoiceAmount` | `orderIds` | 是 | 1688 订单 ID 字符串数组，至少 1 项，每项必须为数字字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `invoiceApply` | `confirmApplyInvoice` | 是 | 必须是 JSON boolean `true`。申请开票高风险且不可逆，需用户单独中文确认。 |\n| `invoiceApply` | `invoiceApplyModelList` | 是 | 开票申请列表，至少 1 项，每项见下「开票申请逐单模型」。 |\n| `invoiceApply` | 逐单 `amount` | 是 | 必须通过 `invoiceAmount` 查到的可开票金额**原样传入**，不得自行计算；单位为分（1元=100分）。 |\n| `invoiceApply` | 逐单 `invoiceType` | 是 | `VATAX_COMM`（增值税普通发票）/ `VATAX_SPEC`（增值税专用发票）。 |\n| `invoiceApply` | 逐单 `purchaserInvoiceTitleModel` | 是 | 买家发票抬头，见下「开票抬头」。企业抬头建议经 1688 `trade.invoiceTitle.getPageList` 查到既有抬头后原样传入，避免手填不一致。 |\n\n### 开票相关对象\n\n`invoiceApplyModelList` 每项结构：\n\n```json\n{\n  \"orderId\": \"3309156590237728779\",\n  \"amount\": 30500,\n  \"invoiceType\": \"VATAX_COMM\",\n  \"purchaserInvoiceTitleModel\": {\n    \"titleType\": \"COMPANY\",\n    \"title\": \"深圳某某科技有限公司\",\n    \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n  }\n}\n```\n\n`purchaserInvoiceTitleModel`（开票抬头）：\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `titleType` | 是 | `PERSONAL`（个人和社会组织）/ `COMPANY`（企业） |\n| `title` | 是 | 发票抬头 |\n| `taxpayerIdentify` | 条件必填 | 纳税人识别号，**企业开票必填** |\n| `bankName` | 条件必填 | 开户行，**企业开专票必填** |\n| `bankAccountId` | 条件必填 | 银行账号，**企业开专票必填** |\n| `registerAddress` | 条件必填 | 企业注册地址，**企业开专票必填** |\n| `registerPhone` | 条件必填 | 企业电话，**企业开专票必填** |\n\n> 条件必填规则：`titleType=COMPANY`（不论普票/专票）须填 `taxpayerIdentify`；`titleType=COMPANY` 且 `invoiceType=VATAX_SPEC`（企业开专票）须再填 `bankName`/`bankAccountId`/`registerAddress`/`registerPhone` 四项；`titleType=PERSONAL` 以上条件字段可不填。违反返回错误码 `1002` 且不调用 1688。\n\n### 常用对象\n\n`cargoParamList` 示例：\n\n```json\n[\n  {\n    \"offerId\": \"1234567890123456789\",\n    \"specId\": \"456789012345678901\",\n    \"quantity\": 2\n  }\n]\n```\n\n`addressParam` 示例：\n\n```json\n{\n  \"fullName\": \"张三\",\n  \"mobile\": \"13800000000\",\n  \"provinceText\": \"广东省\",\n  \"cityText\": \"深圳市\",\n  \"areaText\": \"南山区\",\n  \"address\": \"科技园示例路 1 号\"\n}\n```\n\n## 响应结构\n\n| 能力 | 关键响应字段 | 说明 |\n|---|---|---|\n| `authorizeUrl` | `authorizeUrl` | 1688 授权链接。给用户手动打开，不自动打开，不返回 token。 |\n| `authorizedStores` | `stores[].accountName/status/expired` | 继续采购必须满足 `status=ACTIVE` 且 `expired=false`。`expired=true` 表示当前授权不可用，通常是 refreshToken 为空、失效或刷新失败；accessToken 普通过期会由后端在调用 `authorizedStores` 或业务接口时自动刷新，不需要重新授权。即使后端响应包含 token 过期时间，也只作内部判断，不要展示给用户。 |\n| `receiveAddressList` | `items[].addressId/fullName/mobile/provinceText/cityText/areaText/address/isDefault` | 多地址时让用户明确选择；展示手机号和详细地址时注意脱敏。 |\n| `sku` | `offerId`、`skuList[].specId/skuId/price/amountOnSale/attributes/skuImageUrl` | 多 SKU 商品下单时使用 `specId`。SKU 价格和库存仅作规格选择参考，真实可购性、最终价格、运费和优惠以 `orderPreview` 为准。 |\n| `orderPreview` | `status`、`message`、`sumPayment`、`sumCarriage`、`discountFee`、`cargoList`、`tradeModelList`、`payChannelInfos`、`shopPromotionList` | `sumPayment/sumCarriage/discountFee` 单位为分；`cargoList.finalUnitPrice/amount` 单位为元，展示时不要混算。支付渠道有可读名称时展示可读名称；只有编码时原样展示，不要猜测含义。 |\n| `orderPreview` 业务失败 | `errcode=200` 但 `status=false`、`message`、金额为 0、交易/支付/优惠列表为空 | 收到预览返回不代表可以下单。停止创建订单，展示上游 `message`，并复核 SKU/规格、起批量、售卖单位、`quantity` 和收货地址。 |\n| `createOrder` | `success`、`orderId`、`message`、`code` | `orderId` 是 1688 订单号；后续 `paymentUrl` 用它组成订单号数组，状态/物流/取消/确认收货可将它作为 `aliOrderId` 使用。 |\n| `paymentUrl` | `success`、`payUrl`、`errorMessage`、`errorCode` | 支付链接只展示给用户手动打开；不要自动打开、自动支付或无必要重复展示。 |\n| `orderStatus` | `aliOrderId`、`aliStatus`、`normalizedStatus` | 用于判断订单当前履约阶段。 |\n| `logistics` | `aliOrderId`、`logisticsOrders[].logisticsId/logisticsBillNo/logisticsCompanyName/status` | `logisticsId` 可用于查询轨迹。 |\n| `logisticsTrace` | `aliOrderId`、`logisticsId`、`traceList[].traceTime/location/traceDescription/traceStatus` | 轨迹时间按 Asia/Shanghai 展示。 |\n| `confirmReceive` | `success`、`aliOrderId` | 确认收货结果。 |\n| `cancelOrder` | `success`、`aliOrderId`、`orderId`、`message` | 仅表示尝试取消 1688 订单的结果；不是退款或售后申请，不保证退款。是否允许取消由 1688 根据订单状态判断。`orderId` 是兼容出参；后续请求仍按各接口要求使用 `aliOrderId` 或 `orderIdList`。 |\n| `invoiceAmount` | `success`、`code`、`message`、`subCode`/`subMessage`、`retCodes[]`、`orderInvoiceAmountModelList[].{orderId, amount}` | `amount` 单位为**分**，须原样传入 `invoiceApply`，不得换算或自行计算；逐单返回码 `retCodes` 与列表逐项对应。`success=false`（如订单不存在/已取消/不可开票）时 HTTP 仍 200，属业务结果，非错误；下游据 `retCodes`/列表判断各订单是否可取到金额。 |\n| `invoiceApply` | `success`、`code`、`message`、`subCode`/`subMessage`、`successList[]`、`failedList[]` | 批量逐单成败独立，须遍历 `successList`/`failedList` 处理，不要只看顶层 `success`。逐单结果含 `orderId`、`outBizId`、`result`、`tradeOrderCompleted`、`errorCode`、`errorDesc`。`INVOICE_ALREADY_APPLIED`（落在 `failedList`）表示该订单历史已开过票，按「已开票」语义处理，不必报错。业务失败 HTTP 仍 200，仅 `code=1003` 或 4xx/5xx 才视为传输异常。开票成功不可在系统侧回滚，红冲需联系商家。 |\n\n## 高风险校验\n\n用户侧只需要用中文自然语言做单独明确确认，例如“确认”“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。只有当上一条消息已明确复述一个具体高风险动作和对象时，单独回复“确认”才算有效；不要要求用户输入英文参数名或 `=true`，也不要向普通用户展示内部确认字段、请求字段名或实现细节。\n\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。这些字段只用于脚本调用和排错，不属于用户可见流程文案。\n\n| 脚本 | 本地拒绝条件 |\n|---|---|\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\n| `invoice_apply.py` | 缺少 JSON boolean `confirmApplyInvoice=true` |\n\n## 错误码\n\n| errcode / error | 含义 | 处理建议 |\n|---|---|---|\n| 200 | 请求已有返回 | 是否可继续下单以具体预览结果、订单结果或提示信息为准 |\n| 401 / authorized error | 认证失败 | 按 SKILL.md 的 **## 解决认证和算力问题** 处理 |\n| 402 | 算力或余额不足 | 按 SKILL.md 的 **## 解决认证和算力问题** 处理 |\n| `authorization_required` | 当前用户没有 ACTIVE 且未过期的 1688 授权 | 先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证 |\n| `confirmation_required` | 高风险确认字段缺失或不是 JSON boolean `true` | 停止并让用户单独中文确认；不要自动补字符串 `\"true\"` |\n| 1002 | 参数缺失或不合法 | 检查字段名、必填项、枚举值、订单号是否为数字字符串 |\n| 1003 | 上游调用或业务失败 | 不要自动重试高风险写操作；向用户说明失败原因 |\n| 1005 | 1688 授权缺失或失效 | 重新走授权检查/授权流程 |\n\n错误响应示例：\n\n```json\n{\n  \"error\": \"authorization_required\",\n  \"message\": \"1688 OAuth authorization is required before this procurement operation.\"\n}\n```\n\n## curl 示例\n\n### 查询授权状态\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/authorizedStores \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{}'\n```\n\n### 查询 SKU\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/sku \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"offerId\":\"1234567890123456789\"}'\n```\n\n### 下单预览\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/orderPreview \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"flow\": \"general\",\n    \"addressId\": \"987654321012345678\",\n    \"cargoParamList\": [\n      {\n        \"offerId\": \"1234567890123456789\",\n        \"specId\": \"456789012345678901\",\n        \"quantity\": 2\n      }\n    ]\n  }'\n```\n\n### 获取支付链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/paymentUrl \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmGetPaymentUrl\": true,\n    \"orderIdList\": [\"1234567890123456789\"]\n  }'\n```\n\n### 查询可开票金额\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceAmount \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"orderIds\": [\"1234567890123456789\"]}'\n```\n\n### 申请开票\n\n高风险、不可逆，必须显式传 `confirmApplyInvoice=true`。`amount` 取自上一步 `invoiceAmount` 返回值，原样传入。\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceApply \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmApplyInvoice\": true,\n    \"invoiceApplyModelList\": [\n      {\n        \"orderId\": \"1234567890123456789\",\n        \"amount\": 30500,\n        \"invoiceType\": \"VATAX_COMM\",\n        \"purchaserInvoiceTitleModel\": {\n          \"titleType\": \"COMPANY\",\n          \"title\": \"深圳某某科技有限公司\",\n          \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n        }\n      }\n    ]\n  }'\n```\n\n## Feedback API\n\n> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-1688-procurement\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"Results were accurate, user was satisfied.\"\n}\n```\n\n**Field rules:**\n- `skillName`: Use this skill's `name` from the YAML frontmatter (`linkfox-1688-procurement`)\n- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)\n- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`\n- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs.\n\nFile v1.0.5:references/onboarding.md\n\n# 解决认证和算力问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `算力/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.5:references/workflow.md\n\n# 1688采购流程地图\n\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\n\n## 总原则\n\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\n4. 下单、支付链接、取消订单、确认收货、申请开票都是独立高风险动作，各自需要单独确认。\n5. Agent 刚刚复述清楚一个具体高风险动作和对象后，用户紧接着回复“确认”也算有效确认；用户更早说过“继续”“可以”“按上面来”，不能作为后续高风险动作的确认。\n6. 授权有效后，除以图搜图外，本 Skill 的查询、预览、下单、支付链接、状态、物流等能力都可按用户需求单独使用；不要强迫用户从第 1 步重新跑完整流程。\n\n## 1. 授权检查\n\n运行：\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- 授权有效且未过期：可以继续采购流程。\n- 没有可用授权：进入授权步骤。\n- 若授权检查返回不可用，提示用户重新授权；不要向用户展示 token 失效、有效期或过期时间等内部细节。\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\n\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\n\n## 2. 发起授权\n\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\n\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\n\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\n\n## 3. 找货与 SKU\n\n如果用户按图片找货：\n\n1. 切换到 `linkfox-1688-search-by-image`。\n2. 从图搜结果中选择目标 `offerId`。\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\n\n如果用户已提供 1688 商品 ID：\n\n1. 直接运行 `sku.py`。\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\n3. 让用户选择明确的 SKU 和数量。SKU 阶段的价格和库存只作规格选择参考，真实可购性、最终价格、运费和优惠以订单预览为准。\n\n## 4. 收货地址\n\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\n\n展示地址时应包含：\n\n- 收货人\n- 手机/电话（如返回）\n- 省市区与详细地址\n- 地址标识\n\n不要猜测默认地址。多地址时让用户明确选择。\n\n## 5. 下单预览\n\n运行 `order_preview.py` 前确认已具备：\n\n- 商品\n- SKU/规格\n- 数量：必须结合 SKU 返回的售卖单位、起批量/最小采购量理解；按瓦、米、件等非“件”单位计价的商品，不要默认买 1 个单位\n- 收货地址\n- Agent 调脚本时按 `references/api.md` 组装内部请求字段，不要把字段名展示给用户\n\n预览结果必须先展示给用户：\n\n- 商品\n- SKU/规格\n- 数量\n- 单价与商品总价\n- 运费\n- 收货地址\n- 订单总额\n- 任何异常、库存或价格变化提示\n\n预览失败时停止，不要进入创建订单。收到预览返回不代表可以下单；必须确认预览结果明确通过、金额和商品行有效。失败时展示上游提示和关键异常，并优先复核 SKU/规格、起批量、售卖单位、数量和收货地址。\n\n## 6. 创建订单\n\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如“确认”或“确认创建这个订单”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n只有用户针对本次订单明确确认后，Agent 才在脚本调用中自动加入内部安全字段。\n\n`create_order.py` 会拒绝缺少内部安全字段的请求；这是脚本保护机制，不要展示给普通用户。\n\n创建成功后，`createOrder` 返回的 `orderId` 就是后续获取支付链接、查询状态、物流、取消和确认收货使用的 1688 订单号；对用户可称为“订单号”。\n\n## 7. 获取支付链接\n\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如“确认”或“确认获取支付链接”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n用户单独确认后，Agent 在脚本调用中自动加入内部安全字段和订单号。\n\n## 8. 订单状态与物流\n\n查询类动作可在用户请求时执行：\n\n- `order_status.py`\n- `logistics.py`\n- `logistics_trace.py`\n\n不要在没有用户要求的情况下连续轮询。只有响应明确返回 `costToken`、402 或余额不足信息时，才提示计费/余额影响。\n\n## 9. 取消订单\n\n取消订单是高风险动作，但它不是退款或售后申请。`cancel_order.py` 只会尝试取消 1688 订单；是否允许取消由 1688 根据订单状态判断，本 Skill 当前没有申请退款能力。\n\n执行前优先查询或确认订单状态，并按状态分流：\n\n- 未付款/待付款：可进入取消订单确认流程。\n- 已付款待发货：不要调用取消订单，也不要把取消订单作为退款方案。直接提示用户到 1688 订单页发起退款/售后。\n- 已发货/已完成：不要调用取消订单，应提示用户到 1688 处理退货退款或售后。\n- 已取消：无需重复取消。\n\n进入取消确认前展示：\n\n- 订单号\n- 当前订单状态\n- 取消原因\n- 取消不等于退款，是否成功以 1688 返回为准\n\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述取消对象，用户回复“确认”即可。\n\n## 10. 确认收货\n\n确认收货是高风险动作。用户查询物流、看到已签收、或问“状态怎么样”，都不等于确认收货。\n\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述确认收货对象，用户回复“确认”即可。\n\n## 11. 开发票\n\n1688 下单接口不支持发票信息，发票须在订单完成（建议确认收货后）通过独立接口申请。开票分两步：先查可开票金额，再申请开票。两步可按用户需求单独触发，不要把整个开票闭环当自动化脚本一次跑完。\n\n### 11.1 查询可开票金额（只读，低风险）\n\n开票前先运行 `invoice_amount.py`，入参 `orderIds`（1688 订单 ID 字符串数组，可使用 `createOrder` 返回的 `orderId`）。\n\n```powershell\n$env:PAYLOAD = '{\"orderIds\": [\"3309156590237728779\"]}'\npython scripts/invoice_amount.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- `success=true`：从 `orderInvoiceAmountModelList[].amount` 取各订单可开票金额，**原样**传给下一步 `invoiceApply`，单位为分（1元=100分），不得自行计算或换算。\n- `success=false`（订单不存在/已取消/不可开票等）：HTTP 仍 200，属业务结果。结合 `retCodes` 与列表逐单判断该订单是否可开票；不可开的订单跳过，不进入申请开票。\n- 逐单返回码 `retCodes` 与 `orderInvoiceAmountModelList` 逐项对应。\n\n### 11.2 申请开票（高风险，不可逆）\n\n申请开票会真实向 1688 申请开票，开票成功后不可在系统侧回滚，红冲需联系商家。用户查询可开票金额、问“能不能开发票”，都不等于确认开票。\n\n只有用户针对该订单明确确认开票后，Agent 才运行 `invoice_apply.py`，并在脚本调用中自动加入内部安全字段 `confirmApplyInvoice=true`、订单号、上一步取到的 `amount`、发票类型与抬头。若上一条消息已明确复述开票对象与发票信息，用户回复“确认”即可。\n\n开票前向用户复述（业务语言，不展示内部字段名）：\n\n- 订单号\n- 发票类型：增值税普通发票（`VATAX_COMM`）/ 增值税专用发票（`VATAX_SPEC`）\n- 抬头：个人（`PERSONAL`，仅抬头文本）/ 企业（`COMPANY`，含抬头、税号；企业开专票另需开户行、银行账号、注册地址、企业电话）\n- 可开票金额（分）\n\n申请后遍历 `successList` / `failedList` 逐单回报，不要只看顶层 `success`：\n\n- 成功：提示该订单已申请开票；`tradeOrderCompleted=true` 表示交易已完结。\n- 失败：展示 `errorCode` / `errorDesc`。`INVOICE_ALREADY_APPLIED` 表示历史已开过票，按“已开票”语义处理，不必报错。\n- 业务失败 HTTP 仍 200，属正常结果；仅当 `code=1003` 或 4xx/5xx 才视为传输异常，可提示稍后重试，不要自动重放高风险写操作。\n\n不要自动联动多订单批量开票；不要申请红冲，红冲需用户联系商家在 1688 处理。\n\n## MCP 与 Skill 分离\n\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\n\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.0.5:skill-card.md\n\n## Description:\n\nHelps LinkFox users run authorized 1688 procurement workflows, including OAuth checks, SKU and address lookup, order preview, guarded order creation, payment link retrieval, order tracking, logistics, cancellation, receipt confirmation, and invoicing.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal LinkFox users and procurement operators use this skill to manage authorized 1688 purchasing and fulfillment tasks from authorization through invoicing. It supports guided, user-confirmed procurement actions rather than unattended end-to-end purchasing.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill handles LinkFox API keys and may process procurement, address, order, invoice, and payment-link data.\n\nMitigation: Use it only in trusted workspaces, keep credentials out of shared logs and shell history, prefer secret-store or temporary credential handling, and use --no-save for sensitive responses.\n\nRisk: Several actions can create orders, retrieve payment links, cancel orders, confirm receipt, or apply for invoices.\n\nMitigation: Require a separate Chinese natural-language confirmation for each high-risk action and review order, payment, cancellation, receipt, or invoice details before calling the script.\n\nRisk: Custom LinkFox service URL environment variables can redirect calls away from the default LinkFox endpoints.\n\nMitigation: Avoid setting custom LinkFox service URL environment variables unless the deployment owner has explicitly approved the endpoint.\n\nRisk: Feedback may be sent automatically and responses may be saved locally depending on size or flags.\n\nMitigation: Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback, and disable response saving for sensitive sessions.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement)\n- [1688 procurement API reference](references/api.md)\n- [1688 procurement workflow map](references/workflow.md)\n- [Authentication and billing onboarding](references/onboarding.md)\n- [LinkFox Skills](https://skill.linkfox.com/)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, text, markdown]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON request or response summaries]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Small sanitized JSON responses are printed inline; larger responses may be saved as redacted JSON files unless disabled with --no-save.]\n\n## Skill Version(s):\n\n1.0.5 (source: server-resolved 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\nArchive v1.0.4: 22 files, 36503 bytes\n\nFiles: references/api.md (17994b), references/onboarding.md (2046b), references/workflow.md (9584b), scripts/_alibaba1688_common.py (15050b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/invoice_amount.py (125b), scripts/invoice_apply.py (124b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (2776b), SKILL.md (13820b), _meta.json (143b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in `linkfox-1688-search-by-image`.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like \"continue\".\n- Use exact internal request field names from `references/api.md` when calling scripts. Do not show these field names in normal user-facing text.\n- Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per `references/api.md`; do not mention procurement type or ask users to choose one.\n- `cancel_order.py` only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and address |\n| `create_order.py` | High | Yes | Create a 1688 order |\n| `payment_url.py` | High | Yes | Get payment URL |\n| `order_status.py` | Low | Yes | Query order status |\n| `logistics.py` | Low | Yes | Query logistics summary |\n| `logistics_trace.py` | Low | Yes | Query logistics trace |\n| `confirm_receive.py` | High | Yes | Confirm receipt |\n| `cancel_order.py` | High | Yes | Cancel order |\n| `invoice_amount.py` | Low | Yes | Query invoiceable amount before applying for an invoice |\n| `invoice_apply.py` | High | Yes | Apply for an invoice after order completion |\n\n## 调用方式\n\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}`（完整参数、响应和错误处理见 `references/api.md`）\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`\n- **成本约束**：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。\n- **缓存约束**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。\n- **授权约束**：除 `authorize_url.py` 和 `authorized_stores.py` 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。\n- **授权刷新**：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用 `authorizedStores` 或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（`authorizedStores` 返回 `expired=true`）时才需要重新走 `authorize_url.py` 授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。\n- **高风险约束**：`create_order.py`、`payment_url.py`、`confirm_receive.py`、`cancel_order.py`、`invoice_apply.py` 必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n**脚本入参方式**：\n\n- 直接传 JSON 字符串：`python scripts/sku.py '{\"offerId\":\"...\"}'`\n- 从环境变量读取：`python scripts/sku.py --payload-env PAYLOAD`\n- 从文件读取：`python scripts/sku.py --payload-file payload.json`\n- 加 `--inline` 强制全量打印到 stdout\n- 加 `--save` 强制保存对 token 类敏感字段脱敏\n- 加 `--no-save` 禁止保存响应文件\n\n**输出策略（脚本默认行为）**：\n\n- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。\n- 响应体 > 8 KB：默认将完整脱敏响应写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。\n- `<writable-root>` 优先取 `ACPX_WORKSPACES` 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；`<session>` 取自环境变量 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。\n- 加 `--save` 或设置 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；加 `--no-save` 或设置 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存；`--inline` 不隐含保存。\n\n**读数据建议**：先看 stdout 摘要判断是否足够；需要保存完整响应再加 `--save`，之后优先用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## High-Risk Confirmation\n\nAsk the user for a separate Chinese natural-language confirmation immediately before each high-risk call, restating the exact order/action summary in business terms only. If the immediately preceding assistant message clearly asks for confirmation of one specific high-risk action, a reply of \"确认\" is valid. Earlier phrases such as \"继续\", \"可以\", or \"按上面来\" are not valid for later high-risk actions. Do not ask the user to type English parameter names.\n\nAfter the user confirms in Chinese, the Agent must add the internal safety field required by `references/api.md` when calling the script. Never mention internal fields, request field names, or backend defaults in user-facing confirmation text unless debugging a tool error.\n\n## Common Workflow\n\n1. Run `authorized_stores.py`; continue only when the current user has an ACTIVE, unexpired 1688 authorization.\n2. If not authorized, run `authorize_url.py`, let the user complete OAuth, then re-check `authorized_stores.py`.\n3. If starting from an image, use `linkfox-1688-search-by-image` to get an `offerId`.\n4. Run `sku.py`, then `receive_address_list.py`, then `order_preview.py`.\n5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.\n6. Only after separate Chinese confirmation, run `create_order.py`; add required safety fields internally without showing them to the user.\n7. Only after separate Chinese confirmation, run `payment_url.py`; pass the created order ID internally without showing request field names to the user.\n8. Use `order_status.py`, `logistics.py`, and `logistics_trace.py` for tracking.\n9. Use `cancel_order.py` and `confirm_receive.py` only after separate confirmations for the exact order and action; pass the selected 1688 order ID internally. Do not describe cancellation as refund handling for paid orders.\n10. After receipt confirmation, run `invoice_amount.py` to query the invoiceable amount and whether each order can be invoiced; pass the returned `amount` as-is (do not recompute). Only after separate Chinese confirmation of the invoice type, title, and amount, run `invoice_apply.py`; pass `confirmApplyInvoice=true` and the amount internally. Walk `successList`/`failedList` per order; treat `INVOICE_ALREADY_APPLIED` as already-invoiced, not an error.\n\n## Display Rules\n\n1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.\n2. `authorizedStores` output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.\n3. For authorization, only tell the user whether it is available or whether re-authorization is required. Do not display token expiry times, token validity periods, refresh windows, or internal fields such as `tokenExpiresAt`.\n4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.\n5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.\n6. Before high-risk calls, summarize the exact operation, key IDs, amount/status when available, then ask the user to confirm in Chinese. Do not show internal boolean fields, request field names, or implementation details.\n7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.\n8. Report `costToken` or equivalent cost fields only when returned.\n\n## Important Limitations\n\n- Do not create or call image-search scripts here; image search belongs to `linkfox-1688-search-by-image`.\n- Do not expose `/alibaba1688/proxy/callback`, `/alibaba1688/authorizeCallback`, or browser OAuth callback URLs as Skill capabilities.\n- Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.\n- Do not query backend databases to discover authorization state. Use `authorizedStores`.\n- Do not automatically retry write operations or run the full purchase loop.\n- Do not use `_dataQuery_executeDynamicQuery` for live procurement responses.\n\n## User Expression & Scenario Quick Reference\n\n**Applicable** -- 1688 procurement scenarios:\n\n| User Says | Scenario |\n|-----------|----------|\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | Authorization check |\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | New OAuth authorization |\n| \"查这个 offerId 的 SKU\" | SKU lookup |\n| \"查1688收货地址\" | Receive address lookup |\n| \"帮我预览1688订单\" | Order preview |\n| \"确认下单\" | High-risk create order gate |\n| \"获取支付链接\" | High-risk payment URL gate |\n| \"查1688订单状态/物流\" | Order tracking |\n| \"取消这个1688订单\" | High-risk cancel gate |\n| \"确认收货\" | High-risk confirm receive gate |\n| \"查1688可开票金额\" / \"这个订单能开发票吗\" | Invoiceable amount query |\n| \"给这个1688订单开发票\" / \"确认开票\" | High-risk invoice apply gate |\n\n**Not applicable** -- use another skill or backend system:\n\n- Image-based 1688 product discovery -> `linkfox-1688-search-by-image`\n- Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available\n- MyERP OAuth callback/proxy callback handling -> backend service, not a Skill\n- Direct token repair or manual 1688 token input -> backend authorization bridge\n\n## Feedback\n\nAuto-detect and report feedback via the Feedback API when actual behavior differs from this skill, results do not match user intent, the user expresses satisfaction/dissatisfaction, or anything could be improved. Call the Feedback API as specified in `references/api.md` without interrupting the user's flow. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback content.\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.4:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-procurement\",\n  \"version\": \"1.0.4\",\n  \"publishedAt\": 1787307070245\n}\n\nFile v1.0.4:references/api.md\n\n# 1688采购流程 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/<endpoint>`，默认网关为 `https://tool-gateway.linkfox.com`\n- **请求方式**：POST，Content-Type: `application/json; charset=utf-8`\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置，按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- **User-Agent**：`LinkFox-Skill/2.0`\n- **超时**：150s\n- **缓存**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\n\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n## API 与脚本\n\n| 能力 | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\n|---|---|---|---|---|---|\n| 生成授权链接 | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\n| 查询已授权账号 | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\n| 查询收货地址 | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\n| 查询 SKU | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\n| 下单预览 | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\n| 创建订单 | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\n| 获取支付链接 | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\n| 查询订单状态 | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\n| 查询物流 | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\n| 查询物流轨迹 | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\n| 确认收货 | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\n| 取消订单 | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\n| 查询可开票金额 | `/alibaba1688/invoiceAmount` | `invoice_amount.py` | 低 | 是 | - |\n| 申请开票 | `/alibaba1688/invoiceApply` | `invoice_apply.py` | 高 | 是 | `confirmApplyInvoice=true` |\n\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。不要把 `/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、`/alibaba1688/oauth/callback` 暴露为 Skill 能力。\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 能力 | 参数 | 必填 | 说明 |\n|---|---|---:|---|\n| `authorizeUrl` | `accountName` | 是 | 授权账号展示名，用于标识本次 1688 OAuth 授权。 |\n| `authorizedStores` | - | 否 | 通常传 `{}`。返回当前 LinkFox 用户的 1688 授权状态，不是全库账号列表。 |\n| `receiveAddressList` | - | 否 | 通常传 `{}`。返回当前用户可用收货地址。 |\n| `sku` | `offerId` | 是 | 1688 商品 ID，必须用字符串，避免 JS 大数精度丢失。 |\n| `orderPreview` | `addressId` 或 `addressParam` | 条件必填 | 二选一。优先使用 `receiveAddressList` 返回的 `addressId`；`addressParam` 至少含 `fullName`、`mobile`、`address`。 |\n| `orderPreview` | `cargoParamList` | 是 | 货品列表，每项含 `offerId`、可选 `specId`、`quantity`；`quantity >= 1`。 |\n| `orderPreview` | `flow` | 是 | 下单流程类型。当前主流程为普通采购，默认 `general`；脚本缺省时会补 `general`，直接调 API 时必须显式传。仅当用户明确要求分销/精选货源分销时，才可透传 `fenxiao`/`boutiquefenxiao`；本 Skill 不提供分销专属校验或保障。 |\n| `orderPreview` | `isvBizType` | 否 | 默认 `cross`；仅支持 `cross`、`cross_daigou`、`cross_distribution`。 |\n| `createOrder` | `confirmCreateOrder` | 是 | 必须是 JSON boolean `true`。未传或 false 时不会调用 1688 下单。 |\n| `createOrder` | 下单参数 | 是 | 与 `orderPreview` 保持一致，必须显式包含相同 `flow`；可额外传 `message`、`tradeType`、`shopPromotionId`、`useRedEnvelope`、`anonymousBuyer`、`outOrderId` 等。 |\n| `createOrder` | `useRedEnvelope` | 否 | 是否使用红包，仅支持 `y`/`n`；默认 `n`。 |\n| `paymentUrl` | `confirmGetPaymentUrl` | 是 | 必须是 JSON boolean `true`。只获取支付链接，不自动打开、不自动支付。 |\n| `paymentUrl` | `orderIdList` | 是 | 1688 订单 ID 字符串数组。使用 `createOrder` 返回的 `orderId`。 |\n| `orderStatus` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logistics` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `logisticsId` | 否 | 物流订单 ID；多个物流单时建议从 `logistics` 返回中选择。 |\n| `confirmReceive` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `confirmReceive` | `confirmReceive` | 是 | 必须是 JSON boolean `true`。确认收货不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `cancelOrder` | `confirmCancel` | 是 | 必须是 JSON boolean `true`。取消订单不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `cancelReason`、`remark` | 否 | 取消原因和备注，非空时透传。 |\n| `invoiceAmount` | `orderIds` | 是 | 1688 订单 ID 字符串数组，至少 1 项，每项必须为数字字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `invoiceApply` | `confirmApplyInvoice` | 是 | 必须是 JSON boolean `true`。申请开票高风险且不可逆，需用户单独中文确认。 |\n| `invoiceApply` | `invoiceApplyModelList` | 是 | 开票申请列表，至少 1 项，每项见下「开票申请逐单模型」。 |\n| `invoiceApply` | 逐单 `amount` | 是 | 必须通过 `invoiceAmount` 查到的可开票金额**原样传入**，不得自行计算；单位为分（1元=100分）。 |\n| `invoiceApply` | 逐单 `invoiceType` | 是 | `VATAX_COMM`（增值税普通发票）/ `VATAX_SPEC`（增值税专用发票）。 |\n| `invoiceApply` | 逐单 `purchaserInvoiceTitleModel` | 是 | 买家发票抬头，见下「开票抬头」。企业抬头建议经 1688 `trade.invoiceTitle.getPageList` 查到既有抬头后原样传入，避免手填不一致。 |\n\n### 开票相关对象\n\n`invoiceApplyModelList` 每项结构：\n\n```json\n{\n  \"orderId\": \"3309156590237728779\",\n  \"amount\": 30500,\n  \"invoiceType\": \"VATAX_COMM\",\n  \"purchaserInvoiceTitleModel\": {\n    \"titleType\": \"COMPANY\",\n    \"title\": \"深圳某某科技有限公司\",\n    \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n  }\n}\n```\n\n`purchaserInvoiceTitleModel`（开票抬头）：\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `titleType` | 是 | `PERSONAL`（个人和社会组织）/ `COMPANY`（企业） |\n| `title` | 是 | 发票抬头 |\n| `taxpayerIdentify` | 条件必填 | 纳税人识别号，**企业开票必填** |\n| `bankName` | 条件必填 | 开户行，**企业开专票必填** |\n| `bankAccountId` | 条件必填 | 银行账号，**企业开专票必填** |\n| `registerAddress` | 条件必填 | 企业注册地址，**企业开专票必填** |\n| `registerPhone` | 条件必填 | 企业电话，**企业开专票必填** |\n\n> 条件必填规则：`titleType=COMPANY`（不论普票/专票）须填 `taxpayerIdentify`；`titleType=COMPANY` 且 `invoiceType=VATAX_SPEC`（企业开专票）须再填 `bankName`/`bankAccountId`/`registerAddress`/`registerPhone` 四项；`titleType=PERSONAL` 以上条件字段可不填。违反返回错误码 `1002` 且不调用 1688。\n\n### 常用对象\n\n`cargoParamList` 示例：\n\n```json\n[\n  {\n    \"offerId\": \"1234567890123456789\",\n    \"specId\": \"456789012345678901\",\n    \"quantity\": 2\n  }\n]\n```\n\n`addressParam` 示例：\n\n```json\n{\n  \"fullName\": \"张三\",\n  \"mobile\": \"13800000000\",\n  \"provinceText\": \"广东省\",\n  \"cityText\": \"深圳市\",\n  \"areaText\": \"南山区\",\n  \"address\": \"科技园示例路 1 号\"\n}\n```\n\n## 响应结构\n\n| 能力 | 关键响应字段 | 说明 |\n|---|---|---|\n| `authorizeUrl` | `authorizeUrl` | 1688 授权链接。给用户手动打开，不自动打开，不返回 token。 |\n| `authorizedStores` | `stores[].accountName/status/expired` | 继续采购必须满足 `status=ACTIVE` 且 `expired=false`。`expired=true` 表示当前授权不可用，通常是 refreshToken 为空、失效或刷新失败；accessToken 普通过期会由后端在调用 `authorizedStores` 或业务接口时自动刷新，不需要重新授权。即使后端响应包含 token 过期时间，也只作内部判断，不要展示给用户。 |\n| `receiveAddressList` | `items[].addressId/fullName/mobile/provinceText/cityText/areaText/address/isDefault` | 多地址时让用户明确选择；展示手机号和详细地址时注意脱敏。 |\n| `sku` | `offerId`、`skuList[].specId/skuId/price/amountOnSale/attributes/skuImageUrl` | 多 SKU 商品下单时使用 `specId`。SKU 价格和库存仅作规格选择参考，真实可购性、最终价格、运费和优惠以 `orderPreview` 为准。 |\n| `orderPreview` | `status`、`message`、`sumPayment`、`sumCarriage`、`discountFee`、`cargoList`、`tradeModelList`、`payChannelInfos`、`shopPromotionList` | `sumPayment/sumCarriage/discountFee` 单位为分；`cargoList.finalUnitPrice/amount` 单位为元，展示时不要混算。支付渠道有可读名称时展示可读名称；只有编码时原样展示，不要猜测含义。 |\n| `orderPreview` 业务失败 | `errcode=200` 但 `status=false`、`message`、金额为 0、交易/支付/优惠列表为空 | 收到预览返回不代表可以下单。停止创建订单，展示上游 `message`，并复核 SKU/规格、起批量、售卖单位、`quantity` 和收货地址。 |\n| `createOrder` | `success`、`orderId`、`message`、`code` | `orderId` 是 1688 订单号；后续 `paymentUrl` 用它组成订单号数组，状态/物流/取消/确认收货可将它作为 `aliOrderId` 使用。 |\n| `paymentUrl` | `success`、`payUrl`、`errorMessage`、`errorCode` | 支付链接只展示给用户手动打开；不要自动打开、自动支付或无必要重复展示。 |\n| `orderStatus` | `aliOrderId`、`aliStatus`、`normalizedStatus` | 用于判断订单当前履约阶段。 |\n| `logistics` | `aliOrderId`、`logisticsOrders[].logisticsId/logisticsBillNo/logisticsCompanyName/status` | `logisticsId` 可用于查询轨迹。 |\n| `logisticsTrace` | `aliOrderId`、`logisticsId`、`traceList[].traceTime/location/traceDescription/traceStatus` | 轨迹时间按 Asia/Shanghai 展示。 |\n| `confirmReceive` | `success`、`aliOrderId` | 确认收货结果。 |\n| `cancelOrder` | `success`、`aliOrderId`、`orderId`、`message` | 仅表示尝试取消 1688 订单的结果；不是退款或售后申请，不保证退款。是否允许取消由 1688 根据订单状态判断。`orderId` 是兼容出参；后续请求仍按各接口要求使用 `aliOrderId` 或 `orderIdList`。 |\n| `invoiceAmount` | `success`、`code`、`message`、`subCode`/`subMessage`、`retCodes[]`、`orderInvoiceAmountModelList[].{orderId, amount}` | `amount` 单位为**分**，须原样传入 `invoiceApply`，不得换算或自行计算；逐单返回码 `retCodes` 与列表逐项对应。`success=false`（如订单不存在/已取消/不可开票）时 HTTP 仍 200，属业务结果，非错误；下游据 `retCodes`/列表判断各订单是否可取到金额。 |\n| `invoiceApply` | `success`、`code`、`message`、`subCode`/`subMessage`、`successList[]`、`failedList[]` | 批量逐单成败独立，须遍历 `successList`/`failedList` 处理，不要只看顶层 `success`。逐单结果含 `orderId`、`outBizId`、`result`、`tradeOrderCompleted`、`errorCode`、`errorDesc`。`INVOICE_ALREADY_APPLIED`（落在 `failedList`）表示该订单历史已开过票，按「已开票」语义处理，不必报错。业务失败 HTTP 仍 200，仅 `code=1003` 或 4xx/5xx 才视为传输异常。开票成功不可在系统侧回滚，红冲需联系商家。 |\n\n## 高风险校验\n\n用户侧只需要用中文自然语言做单独明确确认，例如“确认”“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。只有当上一条消息已明确复述一个具体高风险动作和对象时，单独回复“确认”才算有效；不要要求用户输入英文参数名或 `=true`，也不要向普通用户展示内部确认字段、请求字段名或实现细节。\n\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。这些字段只用于脚本调用和排错，不属于用户可见流程文案。\n\n| 脚本 | 本地拒绝条件 |\n|---|---|\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\n| `invoice_apply.py` | 缺少 JSON boolean `confirmApplyInvoice=true` |\n\n## 错误码\n\n| errcode / error | 含义 | 处理建议 |\n|---|---|---|\n| 200 | 请求已有返回 | 是否可继续下单以具体预览结果、订单结果或提示信息为准 |\n| 401 / authorized error | 认证失败 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| 402 | 积分或余额不足 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| `authorization_required` | 当前用户没有 ACTIVE 且未过期的 1688 授权 | 先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证 |\n| `confirmation_required` | 高风险确认字段缺失或不是 JSON boolean `true` | 停止并让用户单独中文确认；不要自动补字符串 `\"true\"` |\n| 1002 | 参数缺失或不合法 | 检查字段名、必填项、枚举值、订单号是否为数字字符串 |\n| 1003 | 上游调用或业务失败 | 不要自动重试高风险写操作；向用户说明失败原因 |\n| 1005 | 1688 授权缺失或失效 | 重新走授权检查/授权流程 |\n\n错误响应示例：\n\n```json\n{\n  \"error\": \"authorization_required\",\n  \"message\": \"1688 OAuth authorization is required before this procurement operation.\"\n}\n```\n\n## curl 示例\n\n### 查询授权状态\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/authorizedStores \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{}'\n```\n\n### 查询 SKU\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/sku \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"offerId\":\"1234567890123456789\"}'\n```\n\n### 下单预览\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/orderPreview \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"flow\": \"general\",\n    \"addressId\": \"987654321012345678\",\n    \"cargoParamList\": [\n      {\n        \"offerId\": \"1234567890123456789\",\n        \"specId\": \"456789012345678901\",\n        \"quantity\": 2\n      }\n    ]\n  }'\n```\n\n### 获取支付链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/paymentUrl \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmGetPaymentUrl\": true,\n    \"orderIdList\": [\"1234567890123456789\"]\n  }'\n```\n\n### 查询可开票金额\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceAmount \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"orderIds\": [\"1234567890123456789\"]}'\n```\n\n### 申请开票\n\n高风险、不可逆，必须显式传 `confirmApplyInvoice=true`。`amount` 取自上一步 `invoiceAmount` 返回值，原样传入。\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceApply \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmApplyInvoice\": true,\n    \"invoiceApplyModelList\": [\n      {\n        \"orderId\": \"1234567890123456789\",\n        \"amount\": 30500,\n        \"invoiceType\": \"VATAX_COMM\",\n        \"purchaserInvoiceTitleModel\": {\n          \"titleType\": \"COMPANY\",\n          \"title\": \"深圳某某科技有限公司\",\n          \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n        }\n      }\n    ]\n  }'\n```\n\n## Feedback API\n\n> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-1688-procurement\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"Results were accurate, user was satisfied.\"\n}\n```\n\n**Field rules:**\n- `skillName`: Use this skill's `name` from the YAML frontmatter (`linkfox-1688-procurement`)\n- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)\n- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`\n- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs.\n\nFile v1.0.4:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.4:references/workflow.md\n\n# 1688采购流程地图\n\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\n\n## 总原则\n\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\n4. 下单、支付链接、取消订单、确认收货、申请开票都是独立高风险动作，各自需要单独确认。\n5. Agent 刚刚复述清楚一个具体高风险动作和对象后，用户紧接着回复“确认”也算有效确认；用户更早说过“继续”“可以”“按上面来”，不能作为后续高风险动作的确认。\n6. 授权有效后，除以图搜图外，本 Skill 的查询、预览、下单、支付链接、状态、物流等能力都可按用户需求单独使用；不要强迫用户从第 1 步重新跑完整流程。\n\n## 1. 授权检查\n\n运行：\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- 授权有效且未过期：可以继续采购流程。\n- 没有可用授权：进入授权步骤。\n- 若授权检查返回不可用，提示用户重新授权；不要向用户展示 token 失效、有效期或过期时间等内部细节。\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\n\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\n\n## 2. 发起授权\n\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\n\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\n\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\n\n## 3. 找货与 SKU\n\n如果用户按图片找货：\n\n1. 切换到 `linkfox-1688-search-by-image`。\n2. 从图搜结果中选择目标 `offerId`。\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\n\n如果用户已提供 1688 商品 ID：\n\n1. 直接运行 `sku.py`。\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\n3. 让用户选择明确的 SKU 和数量。SKU 阶段的价格和库存只作规格选择参考，真实可购性、最终价格、运费和优惠以订单预览为准。\n\n## 4. 收货地址\n\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\n\n展示地址时应包含：\n\n- 收货人\n- 手机/电话（如返回）\n- 省市区与详细地址\n- 地址标识\n\n不要猜测默认地址。多地址时让用户明确选择。\n\n## 5. 下单预览\n\n运行 `order_preview.py` 前确认已具备：\n\n- 商品\n- SKU/规格\n- 数量：必须结合 SKU 返回的售卖单位、起批量/最小采购量理解；按瓦、米、件等非“件”单位计价的商品，不要默认买 1 个单位\n- 收货地址\n- Agent 调脚本时按 `references/api.md` 组装内部请求字段，不要把字段名展示给用户\n\n预览结果必须先展示给用户：\n\n- 商品\n- SKU/规格\n- 数量\n- 单价与商品总价\n- 运费\n- 收货地址\n- 订单总额\n- 任何异常、库存或价格变化提示\n\n预览失败时停止，不要进入创建订单。收到预览返回不代表可以下单；必须确认预览结果明确通过、金额和商品行有效。失败时展示上游提示和关键异常，并优先复核 SKU/规格、起批量、售卖单位、数量和收货地址。\n\n## 6. 创建订单\n\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如“确认”或“确认创建这个订单”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n只有用户针对本次订单明确确认后，Agent 才在脚本调用中自动加入内部安全字段。\n\n`create_order.py` 会拒绝缺少内部安全字段的请求；这是脚本保护机制，不要展示给普通用户。\n\n创建成功后，`createOrder` 返回的 `orderId` 就是后续获取支付链接、查询状态、物流、取消和确认收货使用的 1688 订单号；对用户可称为“订单号”。\n\n## 7. 获取支付链接\n\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如“确认”或“确认获取支付链接”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n用户单独确认后，Agent 在脚本调用中自动加入内部安全字段和订单号。\n\n## 8. 订单状态与物流\n\n查询类动作可在用户请求时执行：\n\n- `order_status.py`\n- `logistics.py`\n- `logistics_trace.py`\n\n不要在没有用户要求的情况下连续轮询。只有响应明确返回 `costToken`、402 或余额不足信息时，才提示计费/余额影响。\n\n## 9. 取消订单\n\n取消订单是高风险动作，但它不是退款或售后申请。`cancel_order.py` 只会尝试取消 1688 订单；是否允许取消由 1688 根据订单状态判断，本 Skill 当前没有申请退款能力。\n\n执行前优先查询或确认订单状态，并按状态分流：\n\n- 未付款/待付款：可进入取消订单确认流程。\n- 已付款待发货：不要调用取消订单，也不要把取消订单作为退款方案。直接提示用户到 1688 订单页发起退款/售后。\n- 已发货/已完成：不要调用取消订单，应提示用户到 1688 处理退货退款或售后。\n- 已取消：无需重复取消。\n\n进入取消确认前展示：\n\n- 订单号\n- 当前订单状态\n- 取消原因\n- 取消不等于退款，是否成功以 1688 返回为准\n\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述取消对象，用户回复“确认”即可。\n\n## 10. 确认收货\n\n确认收货是高风险动作。用户查询物流、看到已签收、或问“状态怎么样”，都不等于确认收货。\n\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述确认收货对象，用户回复“确认”即可。\n\n## 11. 开发票\n\n1688 下单接口不支持发票信息，发票须在订单完成（建议确认收货后）通过独立接口申请。开票分两步：先查可开票金额，再申请开票。两步可按用户需求单独触发，不要把整个开票闭环当自动化脚本一次跑完。\n\n### 11.1 查询可开票金额（只读，低风险）\n\n开票前先运行 `invoice_amount.py`，入参 `orderIds`（1688 订单 ID 字符串数组，可使用 `createOrder` 返回的 `orderId`）。\n\n```powershell\n$env:PAYLOAD = '{\"orderIds\": [\"3309156590237728779\"]}'\npython scripts/invoice_amount.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- `success=true`：从 `orderInvoiceAmountModelList[].amount` 取各订单可开票金额，**原样**传给下一步 `invoiceApply`，单位为分（1元=100分），不得自行计算或换算。\n- `success=false`（订单不存在/已取消/不可开票等）：HTTP 仍 200，属业务结果。结合 `retCodes` 与列表逐单判断该订单是否可开票；不可开的订单跳过，不进入申请开票。\n- 逐单返回码 `retCodes` 与 `orderInvoiceAmountModelList` 逐项对应。\n\n### 11.2 申请开票（高风险，不可逆）\n\n申请开票会真实向 1688 申请开票，开票成功后不可在系统侧回滚，红冲需联系商家。用户查询可开票金额、问“能不能开发票”，都不等于确认开票。\n\n只有用户针对该订单明确确认开票后，Agent 才运行 `invoice_apply.py`，并在脚本调用中自动加入内部安全字段 `confirmApplyInvoice=true`、订单号、上一步取到的 `amount`、发票类型与抬头。若上一条消息已明确复述开票对象与发票信息，用户回复“确认”即可。\n\n开票前向用户复述（业务语言，不展示内部字段名）：\n\n- 订单号\n- 发票类型：增值税普通发票（`VATAX_COMM`）/ 增值税专用发票（`VATAX_SPEC`）\n- 抬头：个人（`PERSONAL`，仅抬头文本）/ 企业（`COMPANY`，含抬头、税号；企业开专票另需开户行、银行账号、注册地址、企业电话）\n- 可开票金额（分）\n\n申请后遍历 `successList` / `failedList` 逐单回报，不要只看顶层 `success`：\n\n- 成功：提示该订单已申请开票；`tradeOrderCompleted=true` 表示交易已完结。\n- 失败：展示 `errorCode` / `errorDesc`。`INVOICE_ALREADY_APPLIED` 表示历史已开过票，按“已开票”语义处理，不必报错。\n- 业务失败 HTTP 仍 200，属正常结果；仅当 `code=1003` 或 4xx/5xx 才视为传输异常，可提示稍后重试，不要自动重放高风险写操作。\n\n不要自动联动多订单批量开票；不要申请红冲，红冲需用户联系商家在 1688 处理。\n\n## MCP 与 Skill 分离\n\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\n\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.0.4:skill-card.md\n\n## Description:\n\nAssists LinkFox users with authorized 1688 procurement, including OAuth checks, SKU and address lookup, order preview, guarded order creation, payment link retrieval, order tracking, logistics, cancellation, receipt confirmation, and invoicing.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal LinkFox users and agents use this skill to complete authorized 1688 procurement steps while preserving required authorization checks and explicit confirmations for payment, order, receipt, cancellation, and invoicing actions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can touch procurement, account, billing, and feedback data through LinkFox services.\n\nMitigation: Install only when LinkFox is trusted for those workflows, and review payment or feedback actions before allowing the agent to proceed.\n\nRisk: Generated API keys may be long-lived secrets.\n\nMitigation: Prefer the self-service API-key path when possible, keep API keys out of chat and logs, and rely on the skill's redaction behavior for outputs.\n\nRisk: Endpoint environment variable overrides can redirect requests away from the expected LinkFox services.\n\nMitigation: Avoid overriding LinkFox endpoint environment variables unless the endpoint is controlled and trusted.\n\nRisk: Order creation, payment-link retrieval, cancellation, receipt confirmation, and invoice application can affect real procurement state.\n\nMitigation: Require a separate explicit user confirmation for each high-risk action, stop on failed previews or authorization checks, and avoid automatic retries of write operations.\n\n## Reference(s):\n\n- [1688采购流程 API 参考](references/api.md)\n- [1688采购流程地图](references/workflow.md)\n- [解决认证和积分问题](references/onboarding.md)\n- [ClawHub skill page](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement)\n- [LinkFox Skills](https://skill.linkfox.com/)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands and redacted JSON responses]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Large responses may be saved as redacted JSON files; high-risk actions require separate explicit user confirmation.]\n\n## Skill Version(s):\n\n1.0.4 (source: 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\nArchive v1.0.3: 22 files, 36261 bytes\n\nFiles: references/api.md (17875b), references/onboarding.md (2046b), references/workflow.md (9584b), scripts/_alibaba1688_common.py (14087b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/invoice_amount.py (125b), scripts/invoice_apply.py (124b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (2839b), SKILL.md (13820b), _meta.json (143b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in `linkfox-1688-search-by-image`.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like \"continue\".\n- Use exact internal request field names from `references/api.md` when calling scripts. Do not show these field names in normal user-facing text.\n- Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per `references/api.md`; do not mention procurement type or ask users to choose one.\n- `cancel_order.py` only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and address |\n| `create_order.py` | High | Yes | Create a 1688 order |\n| `payment_url.py` | High | Yes | Get payment URL |\n| `order_status.py` | Low | Yes | Query order status |\n| `logistics.py` | Low | Yes | Query logistics summary |\n| `logistics_trace.py` | Low | Yes | Query logistics trace |\n| `confirm_receive.py` | High | Yes | Confirm receipt |\n| `cancel_order.py` | High | Yes | Cancel order |\n| `invoice_amount.py` | Low | Yes | Query invoiceable amount before applying for an invoice |\n| `invoice_apply.py` | High | Yes | Apply for an invoice after order completion |\n\n## 调用方式\n\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}`（完整参数、响应和错误处理见 `references/api.md`）\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`\n- **成本约束**：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。\n- **缓存约束**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。\n- **授权约束**：除 `authorize_url.py` 和 `authorized_stores.py` 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。\n- **授权刷新**：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用 `authorizedStores` 或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（`authorizedStores` 返回 `expired=true`）时才需要重新走 `authorize_url.py` 授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。\n- **高风险约束**：`create_order.py`、`payment_url.py`、`confirm_receive.py`、`cancel_order.py`、`invoice_apply.py` 必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n**脚本入参方式**：\n\n- 直接传 JSON 字符串：`python scripts/sku.py '{\"offerId\":\"...\"}'`\n- 从环境变量读取：`python scripts/sku.py --payload-env PAYLOAD`\n- 从文件读取：`python scripts/sku.py --payload-file payload.json`\n- 加 `--inline` 强制全量打印到 stdout\n- 加 `--save` 强制保存对 token 类敏感字段脱敏\n- 加 `--no-save` 禁止保存响应文件\n\n**输出策略（脚本默认行为）**：\n\n- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。\n- 响应体 > 8 KB：默认将完整脱敏响应写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。\n- `<writable-root>` 优先取 `ACPX_WORKSPACES` 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；`<session>` 取自环境变量 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。\n- 加 `--save` 或设置 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；加 `--no-save` 或设置 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存；`--inline` 不隐含保存。\n\n**读数据建议**：先看 stdout 摘要判断是否足够；需要保存完整响应再加 `--save`，之后优先用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## High-Risk Confirmation\n\nAsk the user for a separate Chinese natural-language confirmation immediately before each high-risk call, restating the exact order/action summary in business terms only. If the immediately preceding assistant message clearly asks for confirmation of one specific high-risk action, a reply of \"确认\" is valid. Earlier phrases such as \"继续\", \"可以\", or \"按上面来\" are not valid for later high-risk actions. Do not ask the user to type English parameter names.\n\nAfter the user confirms in Chinese, the Agent must add the internal safety field required by `references/api.md` when calling the script. Never mention internal fields, request field names, or backend defaults in user-facing confirmation text unless debugging a tool error.\n\n## Common Workflow\n\n1. Run `authorized_stores.py`; continue only when the current user has an ACTIVE, unexpired 1688 authorization.\n2. If not authorized, run `authorize_url.py`, let the user complete OAuth, then re-check `authorized_stores.py`.\n3. If starting from an image, use `linkfox-1688-search-by-image` to get an `offerId`.\n4. Run `sku.py`, then `receive_address_list.py`, then `order_preview.py`.\n5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.\n6. Only after separate Chinese confirmation, run `create_order.py`; add required safety fields internally without showing them to the user.\n7. Only after separate Chinese confirmation, run `payment_url.py`; pass the created order ID internally without showing request field names to the user.\n8. Use `order_status.py`, `logistics.py`, and `logistics_trace.py` for tracking.\n9. Use `cancel_order.py` and `confirm_receive.py` only after separate confirmations for the exact order and action; pass the selected 1688 order ID internally. Do not describe cancellation as refund handling for paid orders.\n10. After receipt confirmation, run `invoice_amount.py` to query the invoiceable amount and whether each order can be invoiced; pass the returned `amount` as-is (do not recompute). Only after separate Chinese confirmation of the invoice type, title, and amount, run `invoice_apply.py`; pass `confirmApplyInvoice=true` and the amount internally. Walk `successList`/`failedList` per order; treat `INVOICE_ALREADY_APPLIED` as already-invoiced, not an error.\n\n## Display Rules\n\n1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.\n2. `authorizedStores` output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.\n3. For authorization, only tell the user whether it is available or whether re-authorization is required. Do not display token expiry times, token validity periods, refresh windows, or internal fields such as `tokenExpiresAt`.\n4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.\n5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.\n6. Before high-risk calls, summarize the exact operation, key IDs, amount/status when available, then ask the user to confirm in Chinese. Do not show internal boolean fields, request field names, or implementation details.\n7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.\n8. Report `costToken` or equivalent cost fields only when returned.\n\n## Important Limitations\n\n- Do not create or call image-search scripts here; image search belongs to `linkfox-1688-search-by-image`.\n- Do not expose `/alibaba1688/proxy/callback`, `/alibaba1688/authorizeCallback`, or browser OAuth callback URLs as Skill capabilities.\n- Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.\n- Do not query backend databases to discover authorization state. Use `authorizedStores`.\n- Do not automatically retry write operations or run the full purchase loop.\n- Do not use `_dataQuery_executeDynamicQuery` for live procurement responses.\n\n## User Expression & Scenario Quick Reference\n\n**Applicable** -- 1688 procurement scenarios:\n\n| User Says | Scenario |\n|-----------|----------|\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | Authorization check |\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | New OAuth authorization |\n| \"查这个 offerId 的 SKU\" | SKU lookup |\n| \"查1688收货地址\" | Receive address lookup |\n| \"帮我预览1688订单\" | Order preview |\n| \"确认下单\" | High-risk create order gate |\n| \"获取支付链接\" | High-risk payment URL gate |\n| \"查1688订单状态/物流\" | Order tracking |\n| \"取消这个1688订单\" | High-risk cancel gate |\n| \"确认收货\" | High-risk confirm receive gate |\n| \"查1688可开票金额\" / \"这个订单能开发票吗\" | Invoiceable amount query |\n| \"给这个1688订单开发票\" / \"确认开票\" | High-risk invoice apply gate |\n\n**Not applicable** -- use another skill or backend system:\n\n- Image-based 1688 product discovery -> `linkfox-1688-search-by-image`\n- Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available\n- MyERP OAuth callback/proxy callback handling -> backend service, not a Skill\n- Direct token repair or manual 1688 token input -> backend authorization bridge\n\n## Feedback\n\nAuto-detect and report feedback via the Feedback API when actual behavior differs from this skill, results do not match user intent, the user expresses satisfaction/dissatisfaction, or anything could be improved. Call the Feedback API as specified in `references/api.md` without interrupting the user's flow. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback content.\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-procurement\",\n  \"version\": \"1.0.3\",\n  \"publishedAt\": 1786718326924\n}\n\nFile v1.0.3:references/api.md\n\n# 1688采购流程 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/<endpoint>`，默认网关为 `https://tool-gateway.linkfox.com`\n- **请求方式**：POST，Content-Type: `application/json; charset=utf-8`\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置，按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- **User-Agent**：`LinkFox-Skill/2.0`\n- **超时**：150s\n- **缓存**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\n\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n## API 与脚本\n\n| 能力 | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\n|---|---|---|---|---|---|\n| 生成授权链接 | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\n| 查询已授权账号 | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\n| 查询收货地址 | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\n| 查询 SKU | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\n| 下单预览 | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\n| 创建订单 | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\n| 获取支付链接 | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\n| 查询订单状态 | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\n| 查询物流 | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\n| 查询物流轨迹 | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\n| 确认收货 | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\n| 取消订单 | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\n| 查询可开票金额 | `/alibaba1688/invoiceAmount` | `invoice_amount.py` | 低 | 是 | - |\n| 申请开票 | `/alibaba1688/invoiceApply` | `invoice_apply.py` | 高 | 是 | `confirmApplyInvoice=true` |\n\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。不要把 `/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、`/alibaba1688/oauth/callback` 暴露为 Skill 能力。\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 能力 | 参数 | 必填 | 说明 |\n|---|---|---:|---|\n| `authorizeUrl` | `accountName` | 是 | 授权账号展示名，用于标识本次 1688 OAuth 授权。 |\n| `authorizedStores` | - | 否 | 通常传 `{}`。返回当前 LinkFox 用户的 1688 授权状态，不是全库账号列表。 |\n| `receiveAddressList` | - | 否 | 通常传 `{}`。返回当前用户可用收货地址。 |\n| `sku` | `offerId` | 是 | 1688 商品 ID，必须用字符串，避免 JS 大数精度丢失。 |\n| `orderPreview` | `addressId` 或 `addressParam` | 条件必填 | 二选一。优先使用 `receiveAddressList` 返回的 `addressId`；`addressParam` 至少含 `fullName`、`mobile`、`address`。 |\n| `orderPreview` | `cargoParamList` | 是 | 货品列表，每项含 `offerId`、可选 `specId`、`quantity`；`quantity >= 1`。 |\n| `orderPreview` | `flow` | 是 | 下单流程类型。当前主流程为普通采购，默认 `general`；脚本缺省时会补 `general`，直接调 API 时必须显式传。仅当用户明确要求分销/精选货源分销时，才可透传 `fenxiao`/`boutiquefenxiao`；本 Skill 不提供分销专属校验或保障。 |\n| `orderPreview` | `isvBizType` | 否 | 默认 `cross`；仅支持 `cross`、`cross_daigou`、`cross_distribution`。 |\n| `createOrder` | `confirmCreateOrder` | 是 | 必须是 JSON boolean `true`。未传或 false 时不会调用 1688 下单。 |\n| `createOrder` | 下单参数 | 是 | 与 `orderPreview` 保持一致，必须显式包含相同 `flow`；可额外传 `message`、`tradeType`、`shopPromotionId`、`anonymousBuyer`、`outOrderId` 等。 |\n| `paymentUrl` | `confirmGetPaymentUrl` | 是 | 必须是 JSON boolean `true`。只获取支付链接，不自动打开、不自动支付。 |\n| `paymentUrl` | `orderIdList` | 是 | 1688 订单 ID 字符串数组。使用 `createOrder` 返回的 `orderId`。 |\n| `orderStatus` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logistics` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `logisticsId` | 否 | 物流订单 ID；多个物流单时建议从 `logistics` 返回中选择。 |\n| `confirmReceive` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `confirmReceive` | `confirmReceive` | 是 | 必须是 JSON boolean `true`。确认收货不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `cancelOrder` | `confirmCancel` | 是 | 必须是 JSON boolean `true`。取消订单不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `cancelReason`、`remark` | 否 | 取消原因和备注，非空时透传。 |\n| `invoiceAmount` | `orderIds` | 是 | 1688 订单 ID 字符串数组，至少 1 项，每项必须为数字字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `invoiceApply` | `confirmApplyInvoice` | 是 | 必须是 JSON boolean `true`。申请开票高风险且不可逆，需用户单独中文确认。 |\n| `invoiceApply` | `invoiceApplyModelList` | 是 | 开票申请列表，至少 1 项，每项见下「开票申请逐单模型」。 |\n| `invoiceApply` | 逐单 `amount` | 是 | 必须通过 `invoiceAmount` 查到的可开票金额**原样传入**，不得自行计算；单位为分（1元=100分）。 |\n| `invoiceApply` | 逐单 `invoiceType` | 是 | `VATAX_COMM`（增值税普通发票）/ `VATAX_SPEC`（增值税专用发票）。 |\n| `invoiceApply` | 逐单 `purchaserInvoiceTitleModel` | 是 | 买家发票抬头，见下「开票抬头」。企业抬头建议经 1688 `trade.invoiceTitle.getPageList` 查到既有抬头后原样传入，避免手填不一致。 |\n\n### 开票相关对象\n\n`invoiceApplyModelList` 每项结构：\n\n```json\n{\n  \"orderId\": \"3309156590237728779\",\n  \"amount\": 30500,\n  \"invoiceType\": \"VATAX_COMM\",\n  \"purchaserInvoiceTitleModel\": {\n    \"titleType\": \"COMPANY\",\n    \"title\": \"深圳某某科技有限公司\",\n    \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n  }\n}\n```\n\n`purchaserInvoiceTitleModel`（开票抬头）：\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `titleType` | 是 | `PERSONAL`（个人和社会组织）/ `COMPANY`（企业） |\n| `title` | 是 | 发票抬头 |\n| `taxpayerIdentify` | 条件必填 | 纳税人识别号，**企业开票必填** |\n| `bankName` | 条件必填 | 开户行，**企业开专票必填** |\n| `bankAccountId` | 条件必填 | 银行账号，**企业开专票必填** |\n| `registerAddress` | 条件必填 | 企业注册地址，**企业开专票必填** |\n| `registerPhone` | 条件必填 | 企业电话，**企业开专票必填** |\n\n> 条件必填规则：`titleType=COMPANY`（不论普票/专票）须填 `taxpayerIdentify`；`titleType=COMPANY` 且 `invoiceType=VATAX_SPEC`（企业开专票）须再填 `bankName`/`bankAccountId`/`registerAddress`/`registerPhone` 四项；`titleType=PERSONAL` 以上条件字段可不填。违反返回错误码 `1002` 且不调用 1688。\n\n### 常用对象\n\n`cargoParamList` 示例：\n\n```json\n[\n  {\n    \"offerId\": \"1234567890123456789\",\n    \"specId\": \"456789012345678901\",\n    \"quantity\": 2\n  }\n]\n```\n\n`addressParam` 示例：\n\n```json\n{\n  \"fullName\": \"张三\",\n  \"mobile\": \"13800000000\",\n  \"provinceText\": \"广东省\",\n  \"cityText\": \"深圳市\",\n  \"areaText\": \"南山区\",\n  \"address\": \"科技园示例路 1 号\"\n}\n```\n\n## 响应结构\n\n| 能力 | 关键响应字段 | 说明 |\n|---|---|---|\n| `authorizeUrl` | `authorizeUrl` | 1688 授权链接。给用户手动打开，不自动打开，不返回 token。 |\n| `authorizedStores` | `stores[].accountName/status/expired` | 继续采购必须满足 `status=ACTIVE` 且 `expired=false`。`expired=true` 表示当前授权不可用，通常是 refreshToken 为空、失效或刷新失败；accessToken 普通过期会由后端在调用 `authorizedStores` 或业务接口时自动刷新，不需要重新授权。即使后端响应包含 token 过期时间，也只作内部判断，不要展示给用户。 |\n| `receiveAddressList` | `items[].addressId/fullName/mobile/provinceText/cityText/areaText/address/isDefault` | 多地址时让用户明确选择；展示手机号和详细地址时注意脱敏。 |\n| `sku` | `offerId`、`skuList[].specId/skuId/price/amountOnSale/attributes/skuImageUrl` | 多 SKU 商品下单时使用 `specId`。SKU 价格和库存仅作规格选择参考，真实可购性、最终价格、运费和优惠以 `orderPreview` 为准。 |\n| `orderPreview` | `status`、`message`、`sumPayment`、`sumCarriage`、`discountFee`、`cargoList`、`tradeModelList`、`payChannelInfos`、`shopPromotionList` | `sumPayment/sumCarriage/discountFee` 单位为分；`cargoList.finalUnitPrice/amount` 单位为元，展示时不要混算。支付渠道有可读名称时展示可读名称；只有编码时原样展示，不要猜测含义。 |\n| `orderPreview` 业务失败 | `errcode=200` 但 `status=false`、`message`、金额为 0、交易/支付/优惠列表为空 | 收到预览返回不代表可以下单。停止创建订单，展示上游 `message`，并复核 SKU/规格、起批量、售卖单位、`quantity` 和收货地址。 |\n| `createOrder` | `success`、`orderId`、`message`、`code` | `orderId` 是 1688 订单号；后续 `paymentUrl` 用它组成订单号数组，状态/物流/取消/确认收货可将它作为 `aliOrderId` 使用。 |\n| `paymentUrl` | `success`、`payUrl`、`errorMessage`、`errorCode` | 支付链接只展示给用户手动打开；不要自动打开、自动支付或无必要重复展示。 |\n| `orderStatus` | `aliOrderId`、`aliStatus`、`normalizedStatus` | 用于判断订单当前履约阶段。 |\n| `logistics` | `aliOrderId`、`logisticsOrders[].logisticsId/logisticsBillNo/logisticsCompanyName/status` | `logisticsId` 可用于查询轨迹。 |\n| `logisticsTrace` | `aliOrderId`、`logisticsId`、`traceList[].traceTime/location/traceDescription/traceStatus` | 轨迹时间按 Asia/Shanghai 展示。 |\n| `confirmReceive` | `success`、`aliOrderId` | 确认收货结果。 |\n| `cancelOrder` | `success`、`aliOrderId`、`orderId`、`message` | 仅表示尝试取消 1688 订单的结果；不是退款或售后申请，不保证退款。是否允许取消由 1688 根据订单状态判断。`orderId` 是兼容出参；后续请求仍按各接口要求使用 `aliOrderId` 或 `orderIdList`。 |\n| `invoiceAmount` | `success`、`code`、`message`、`subCode`/`subMessage`、`retCodes[]`、`orderInvoiceAmountModelList[].{orderId, amount}` | `amount` 单位为**分**，须原样传入 `invoiceApply`，不得换算或自行计算；逐单返回码 `retCodes` 与列表逐项对应。`success=false`（如订单不存在/已取消/不可开票）时 HTTP 仍 200，属业务结果，非错误；下游据 `retCodes`/列表判断各订单是否可取到金额。 |\n| `invoiceApply` | `success`、`code`、`message`、`subCode`/`subMessage`、`successList[]`、`failedList[]` | 批量逐单成败独立，须遍历 `successList`/`failedList` 处理，不要只看顶层 `success`。逐单结果含 `orderId`、`outBizId`、`result`、`tradeOrderCompleted`、`errorCode`、`errorDesc`。`INVOICE_ALREADY_APPLIED`（落在 `failedList`）表示该订单历史已开过票，按「已开票」语义处理，不必报错。业务失败 HTTP 仍 200，仅 `code=1003` 或 4xx/5xx 才视为传输异常。开票成功不可在系统侧回滚，红冲需联系商家。 |\n\n## 高风险校验\n\n用户侧只需要用中文自然语言做单独明确确认，例如“确认”“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。只有当上一条消息已明确复述一个具体高风险动作和对象时，单独回复“确认”才算有效；不要要求用户输入英文参数名或 `=true`，也不要向普通用户展示内部确认字段、请求字段名或实现细节。\n\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。这些字段只用于脚本调用和排错，不属于用户可见流程文案。\n\n| 脚本 | 本地拒绝条件 |\n|---|---|\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\n| `invoice_apply.py` | 缺少 JSON boolean `confirmApplyInvoice=true` |\n\n## 错误码\n\n| errcode / error | 含义 | 处理建议 |\n|---|---|---|\n| 200 | 请求已有返回 | 是否可继续下单以具体预览结果、订单结果或提示信息为准 |\n| 401 / authorized error | 认证失败 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| 402 | 积分或余额不足 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| `authorization_required` | 当前用户没有 ACTIVE 且未过期的 1688 授权 | 先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证 |\n| `confirmation_required` | 高风险确认字段缺失或不是 JSON boolean `true` | 停止并让用户单独中文确认；不要自动补字符串 `\"true\"` |\n| 1002 | 参数缺失或不合法 | 检查字段名、必填项、枚举值、订单号是否为数字字符串 |\n| 1003 | 上游调用或业务失败 | 不要自动重试高风险写操作；向用户说明失败原因 |\n| 1005 | 1688 授权缺失或失效 | 重新走授权检查/授权流程 |\n\n错误响应示例：\n\n```json\n{\n  \"error\": \"authorization_required\",\n  \"message\": \"1688 OAuth authorization is required before this procurement operation.\"\n}\n```\n\n## curl 示例\n\n### 查询授权状态\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/authorizedStores \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{}'\n```\n\n### 查询 SKU\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/sku \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"offerId\":\"1234567890123456789\"}'\n```\n\n### 下单预览\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/orderPreview \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"flow\": \"general\",\n    \"addressId\": \"987654321012345678\",\n    \"cargoParamList\": [\n      {\n        \"offerId\": \"1234567890123456789\",\n        \"specId\": \"456789012345678901\",\n        \"quantity\": 2\n      }\n    ]\n  }'\n```\n\n### 获取支付链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/paymentUrl \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmGetPaymentUrl\": true,\n    \"orderIdList\": [\"1234567890123456789\"]\n  }'\n```\n\n### 查询可开票金额\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceAmount \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"orderIds\": [\"1234567890123456789\"]}'\n```\n\n### 申请开票\n\n高风险、不可逆，必须显式传 `confirmApplyInvoice=true`。`amount` 取自上一步 `invoiceAmount` 返回值，原样传入。\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceApply \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmApplyInvoice\": true,\n    \"invoiceApplyModelList\": [\n      {\n        \"orderId\": \"1234567890123456789\",\n        \"amount\": 30500,\n        \"invoiceType\": \"VATAX_COMM\",\n        \"purchaserInvoiceTitleModel\": {\n          \"titleType\": \"COMPANY\",\n          \"title\": \"深圳某某科技有限公司\",\n          \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n        }\n      }\n    ]\n  }'\n```\n\n## Feedback API\n\n> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-1688-procurement\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"Results were accurate, user was satisfied.\"\n}\n```\n\n**Field rules:**\n- `skillName`: Use this skill's `name` from the YAML frontmatter (`linkfox-1688-procurement`)\n- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)\n- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`\n- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs.\n\nFile v1.0.3:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.3:references/workflow.md\n\n# 1688采购流程地图\n\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\n\n## 总原则\n\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\n4. 下单、支付链接、取消订单、确认收货、申请开票都是独立高风险动作，各自需要单独确认。\n5. Agent 刚刚复述清楚一个具体高风险动作和对象后，用户紧接着回复“确认”也算有效确认；用户更早说过“继续”“可以”“按上面来”，不能作为后续高风险动作的确认。\n6. 授权有效后，除以图搜图外，本 Skill 的查询、预览、下单、支付链接、状态、物流等能力都可按用户需求单独使用；不要强迫用户从第 1 步重新跑完整流程。\n\n## 1. 授权检查\n\n运行：\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- 授权有效且未过期：可以继续采购流程。\n- 没有可用授权：进入授权步骤。\n- 若授权检查返回不可用，提示用户重新授权；不要向用户展示 token 失效、有效期或过期时间等内部细节。\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\n\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\n\n## 2. 发起授权\n\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\n\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\n\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\n\n## 3. 找货与 SKU\n\n如果用户按图片找货：\n\n1. 切换到 `linkfox-1688-search-by-image`。\n2. 从图搜结果中选择目标 `offerId`。\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\n\n如果用户已提供 1688 商品 ID：\n\n1. 直接运行 `sku.py`。\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\n3. 让用户选择明确的 SKU 和数量。SKU 阶段的价格和库存只作规格选择参考，真实可购性、最终价格、运费和优惠以订单预览为准。\n\n## 4. 收货地址\n\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\n\n展示地址时应包含：\n\n- 收货人\n- 手机/电话（如返回）\n- 省市区与详细地址\n- 地址标识\n\n不要猜测默认地址。多地址时让用户明确选择。\n\n## 5. 下单预览\n\n运行 `order_preview.py` 前确认已具备：\n\n- 商品\n- SKU/规格\n- 数量：必须结合 SKU 返回的售卖单位、起批量/最小采购量理解；按瓦、米、件等非“件”单位计价的商品，不要默认买 1 个单位\n- 收货地址\n- Agent 调脚本时按 `references/api.md` 组装内部请求字段，不要把字段名展示给用户\n\n预览结果必须先展示给用户：\n\n- 商品\n- SKU/规格\n- 数量\n- 单价与商品总价\n- 运费\n- 收货地址\n- 订单总额\n- 任何异常、库存或价格变化提示\n\n预览失败时停止，不要进入创建订单。收到预览返回不代表可以下单；必须确认预览结果明确通过、金额和商品行有效。失败时展示上游提示和关键异常，并优先复核 SKU/规格、起批量、售卖单位、数量和收货地址。\n\n## 6. 创建订单\n\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如“确认”或“确认创建这个订单”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n只有用户针对本次订单明确确认后，Agent 才在脚本调用中自动加入内部安全字段。\n\n`create_order.py` 会拒绝缺少内部安全字段的请求；这是脚本保护机制，不要展示给普通用户。\n\n创建成功后，`createOrder` 返回的 `orderId` 就是后续获取支付链接、查询状态、物流、取消和确认收货使用的 1688 订单号；对用户可称为“订单号”。\n\n## 7. 获取支付链接\n\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如“确认”或“确认获取支付链接”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n用户单独确认后，Agent 在脚本调用中自动加入内部安全字段和订单号。\n\n## 8. 订单状态与物流\n\n查询类动作可在用户请求时执行：\n\n- `order_status.py`\n- `logistics.py`\n- `logistics_trace.py`\n\n不要在没有用户要求的情况下连续轮询。只有响应明确返回 `costToken`、402 或余额不足信息时，才提示计费/余额影响。\n\n## 9. 取消订单\n\n取消订单是高风险动作，但它不是退款或售后申请。`cancel_order.py` 只会尝试取消 1688 订单；是否允许取消由 1688 根据订单状态判断，本 Skill 当前没有申请退款能力。\n\n执行前优先查询或确认订单状态，并按状态分流：\n\n- 未付款/待付款：可进入取消订单确认流程。\n- 已付款待发货：不要调用取消订单，也不要把取消订单作为退款方案。直接提示用户到 1688 订单页发起退款/售后。\n- 已发货/已完成：不要调用取消订单，应提示用户到 1688 处理退货退款或售后。\n- 已取消：无需重复取消。\n\n进入取消确认前展示：\n\n- 订单号\n- 当前订单状态\n- 取消原因\n- 取消不等于退款，是否成功以 1688 返回为准\n\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述取消对象，用户回复“确认”即可。\n\n## 10. 确认收货\n\n确认收货是高风险动作。用户查询物流、看到已签收、或问“状态怎么样”，都不等于确认收货。\n\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述确认收货对象，用户回复“确认”即可。\n\n## 11. 开发票\n\n1688 下单接口不支持发票信息，发票须在订单完成（建议确认收货后）通过独立接口申请。开票分两步：先查可开票金额，再申请开票。两步可按用户需求单独触发，不要把整个开票闭环当自动化脚本一次跑完。\n\n### 11.1 查询可开票金额（只读，低风险）\n\n开票前先运行 `invoice_amount.py`，入参 `orderIds`（1688 订单 ID 字符串数组，可使用 `createOrder` 返回的 `orderId`）。\n\n```powershell\n$env:PAYLOAD = '{\"orderIds\": [\"3309156590237728779\"]}'\npython scripts/invoice_amount.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- `success=true`：从 `orderInvoiceAmountModelList[].amount` 取各订单可开票金额，**原样**传给下一步 `invoiceApply`，单位为分（1元=100分），不得自行计算或换算。\n- `success=false`（订单不存在/已取消/不可开票等）：HTTP 仍 200，属业务结果。结合 `retCodes` 与列表逐单判断该订单是否可开票；不可开的订单跳过，不进入申请开票。\n- 逐单返回码 `retCodes` 与 `orderInvoiceAmountModelList` 逐项对应。\n\n### 11.2 申请开票（高风险，不可逆）\n\n申请开票会真实向 1688 申请开票，开票成功后不可在系统侧回滚，红冲需联系商家。用户查询可开票金额、问“能不能开发票”，都不等于确认开票。\n\n只有用户针对该订单明确确认开票后，Agent 才运行 `invoice_apply.py`，并在脚本调用中自动加入内部安全字段 `confirmApplyInvoice=true`、订单号、上一步取到的 `amount`、发票类型与抬头。若上一条消息已明确复述开票对象与发票信息，用户回复“确认”即可。\n\n开票前向用户复述（业务语言，不展示内部字段名）：\n\n- 订单号\n- 发票类型：增值税普通发票（`VATAX_COMM`）/ 增值税专用发票（`VATAX_SPEC`）\n- 抬头：个人（`PERSONAL`，仅抬头文本）/ 企业（`COMPANY`，含抬头、税号；企业开专票另需开户行、银行账号、注册地址、企业电话）\n- 可开票金额（分）\n\n申请后遍历 `successList` / `failedList` 逐单回报，不要只看顶层 `success`：\n\n- 成功：提示该订单已申请开票；`tradeOrderCompleted=true` 表示交易已完结。\n- 失败：展示 `errorCode` / `errorDesc`。`INVOICE_ALREADY_APPLIED` 表示历史已开过票，按“已开票”语义处理，不必报错。\n- 业务失败 HTTP 仍 200，属正常结果；仅当 `code=1003` 或 4xx/5xx 才视为传输异常，可提示稍后重试，不要自动重放高风险写操作。\n\n不要自动联动多订单批量开票；不要申请红冲，红冲需用户联系商家在 1688 处理。\n\n## MCP 与 Skill 分离\n\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\n\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.0.3:skill-card.md\n\n## Description:\n\n1688采购全流程 helps LinkFox users run authorized 1688 procurement, including OAuth checks, SKU and address lookup, order preview, order creation, payment-link retrieval, order tracking, logistics, cancellation, receipt confirmation, and invoicing.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal LinkFox users and procurement operators use this skill to manage authorized 1688 purchasing flows from account authorization through order fulfillment and invoicing. The skill is intended for supervised procurement workflows where high-risk purchase, payment, cancellation, receipt, and invoice actions are reviewed before execution.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Account onboarding and credential handling may expose procurement access if configured in shared or synced shell profiles.\n\nMitigation: Install only when LinkFox is trusted for the procurement workflow, keep LINKFOX_* endpoint variables on official LinkFox HTTPS hosts, and avoid storing API keys in shared or synced shell profile files.\n\nRisk: High-risk actions can create orders, retrieve payment links, cancel orders, confirm receipt, or apply for invoices.\n\nMitigation: Review each high-risk action in business terms and require a separate Chinese natural-language confirmation immediately before execution.\n\nRisk: Unauthorized or expired 1688 account authorization can make procurement operations fail or target the wrong account state.\n\nMitigation: Check the current LinkFox user's authorized 1688 stores before procurement operations and re-authorize through the provided authorization flow when no active, unexpired store is available.\n\n## Reference(s):\n\n- [1688 procurement API reference](references/api.md)\n- [Authentication and billing onboarding](references/onboarding.md)\n- [1688 procurement workflow map](references/workflow.md)\n- [ClawHub skill listing](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, JSON, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance and shell command invocations with JSON script outputs]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [High-risk procurement actions require separate Chinese natural-language confirmation; large script responses may be saved as redacted JSON.]\n\n## Skill Version(s):\n\n1.0.3 (source: 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\nArchive v1.0.2: 22 files, 36342 bytes\n\nFiles: references/api.md (17875b), references/onboarding.md (2046b), references/workflow.md (9584b), scripts/_alibaba1688_common.py (14087b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/invoice_amount.py (125b), scripts/invoice_apply.py (124b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/onboarding.py (24089b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (3033b), SKILL.md (13820b), _meta.json (143b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in `linkfox-1688-search-by-image`.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like \"continue\".\n- Use exact internal request field names from `references/api.md` when calling scripts. Do not show these field names in normal user-facing text.\n- Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per `references/api.md`; do not mention procurement type or ask users to choose one.\n- `cancel_order.py` only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and address |\n| `create_order.py` | High | Yes | Create a 1688 order |\n| `payment_url.py` | High | Yes | Get payment URL |\n| `order_status.py` | Low | Yes | Query order status |\n| `logistics.py` | Low | Yes | Query logistics summary |\n| `logistics_trace.py` | Low | Yes | Query logistics trace |\n| `confirm_receive.py` | High | Yes | Confirm receipt |\n| `cancel_order.py` | High | Yes | Cancel order |\n| `invoice_amount.py` | Low | Yes | Query invoiceable amount before applying for an invoice |\n| `invoice_apply.py` | High | Yes | Apply for an invoice after order completion |\n\n## 调用方式\n\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}`（完整参数、响应和错误处理见 `references/api.md`）\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`\n- **成本约束**：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。\n- **缓存约束**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。\n- **授权约束**：除 `authorize_url.py` 和 `authorized_stores.py` 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。\n- **授权刷新**：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用 `authorizedStores` 或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（`authorizedStores` 返回 `expired=true`）时才需要重新走 `authorize_url.py` 授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。\n- **高风险约束**：`create_order.py`、`payment_url.py`、`confirm_receive.py`、`cancel_order.py`、`invoice_apply.py` 必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n**脚本入参方式**：\n\n- 直接传 JSON 字符串：`python scripts/sku.py '{\"offerId\":\"...\"}'`\n- 从环境变量读取：`python scripts/sku.py --payload-env PAYLOAD`\n- 从文件读取：`python scripts/sku.py --payload-file payload.json`\n- 加 `--inline` 强制全量打印到 stdout\n- 加 `--save` 强制保存对 token 类敏感字段脱敏\n- 加 `--no-save` 禁止保存响应文件\n\n**输出策略（脚本默认行为）**：\n\n- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。\n- 响应体 > 8 KB：默认将完整脱敏响应写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。\n- `<writable-root>` 优先取 `ACPX_WORKSPACES` 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；`<session>` 取自环境变量 `SESSION_ID`，未提供时自动生成；禁止写入 `/tmp`。\n- 加 `--save` 或设置 `LINKFOX_SKILL_SAVE_RESPONSE=1` 强制保存；加 `--no-save` 或设置 `LINKFOX_SKILL_NO_SAVE=1` 禁止保存；`--inline` 不隐含保存。\n\n**读数据建议**：先看 stdout 摘要判断是否足够；需要保存完整响应再加 `--save`，之后优先用 `jq` 或 `ConvertFrom-Json` 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。\n\n## 解决认证和积分问题\n发生以下异常情况时，采用 references/onboarding.md 引导解决问题：\n\n### 异常情况\n- **未配置API Key**：环境变量未配置 `LINKFOX_AGENT_API_KEY`，也未配置 `LINKFOXAGENT_API_KEY`。\n- **响应401或402状态码**\n- **响应提示积分或余额不足**：消息含\"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值\"，或类似含义的内容。\n\n## High-Risk Confirmation\n\nAsk the user for a separate Chinese natural-language confirmation immediately before each high-risk call, restating the exact order/action summary in business terms only. If the immediately preceding assistant message clearly asks for confirmation of one specific high-risk action, a reply of \"确认\" is valid. Earlier phrases such as \"继续\", \"可以\", or \"按上面来\" are not valid for later high-risk actions. Do not ask the user to type English parameter names.\n\nAfter the user confirms in Chinese, the Agent must add the internal safety field required by `references/api.md` when calling the script. Never mention internal fields, request field names, or backend defaults in user-facing confirmation text unless debugging a tool error.\n\n## Common Workflow\n\n1. Run `authorized_stores.py`; continue only when the current user has an ACTIVE, unexpired 1688 authorization.\n2. If not authorized, run `authorize_url.py`, let the user complete OAuth, then re-check `authorized_stores.py`.\n3. If starting from an image, use `linkfox-1688-search-by-image` to get an `offerId`.\n4. Run `sku.py`, then `receive_address_list.py`, then `order_preview.py`.\n5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.\n6. Only after separate Chinese confirmation, run `create_order.py`; add required safety fields internally without showing them to the user.\n7. Only after separate Chinese confirmation, run `payment_url.py`; pass the created order ID internally without showing request field names to the user.\n8. Use `order_status.py`, `logistics.py`, and `logistics_trace.py` for tracking.\n9. Use `cancel_order.py` and `confirm_receive.py` only after separate confirmations for the exact order and action; pass the selected 1688 order ID internally. Do not describe cancellation as refund handling for paid orders.\n10. After receipt confirmation, run `invoice_amount.py` to query the invoiceable amount and whether each order can be invoiced; pass the returned `amount` as-is (do not recompute). Only after separate Chinese confirmation of the invoice type, title, and amount, run `invoice_apply.py`; pass `confirmApplyInvoice=true` and the amount internally. Walk `successList`/`failedList` per order; treat `INVOICE_ALREADY_APPLIED` as already-invoiced, not an error.\n\n## Display Rules\n\n1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.\n2. `authorizedStores` output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.\n3. For authorization, only tell the user whether it is available or whether re-authorization is required. Do not display token expiry times, token validity periods, refresh windows, or internal fields such as `tokenExpiresAt`.\n4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.\n5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.\n6. Before high-risk calls, summarize the exact operation, key IDs, amount/status when available, then ask the user to confirm in Chinese. Do not show internal boolean fields, request field names, or implementation details.\n7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.\n8. Report `costToken` or equivalent cost fields only when returned.\n\n## Important Limitations\n\n- Do not create or call image-search scripts here; image search belongs to `linkfox-1688-search-by-image`.\n- Do not expose `/alibaba1688/proxy/callback`, `/alibaba1688/authorizeCallback`, or browser OAuth callback URLs as Skill capabilities.\n- Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.\n- Do not query backend databases to discover authorization state. Use `authorizedStores`.\n- Do not automatically retry write operations or run the full purchase loop.\n- Do not use `_dataQuery_executeDynamicQuery` for live procurement responses.\n\n## User Expression & Scenario Quick Reference\n\n**Applicable** -- 1688 procurement scenarios:\n\n| User Says | Scenario |\n|-----------|----------|\n| \"查询我的1688授权店铺\" / \"show my authorized 1688 stores\" | Authorization check |\n| \"生成1688授权链接\" / \"authorize my 1688 account\" | New OAuth authorization |\n| \"查这个 offerId 的 SKU\" | SKU lookup |\n| \"查1688收货地址\" | Receive address lookup |\n| \"帮我预览1688订单\" | Order preview |\n| \"确认下单\" | High-risk create order gate |\n| \"获取支付链接\" | High-risk payment URL gate |\n| \"查1688订单状态/物流\" | Order tracking |\n| \"取消这个1688订单\" | High-risk cancel gate |\n| \"确认收货\" | High-risk confirm receive gate |\n| \"查1688可开票金额\" / \"这个订单能开发票吗\" | Invoiceable amount query |\n| \"给这个1688订单开发票\" / \"确认开票\" | High-risk invoice apply gate |\n\n**Not applicable** -- use another skill or backend system:\n\n- Image-based 1688 product discovery -> `linkfox-1688-search-by-image`\n- Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available\n- MyERP OAuth callback/proxy callback handling -> backend service, not a Skill\n- Direct token repair or manual 1688 token input -> backend authorization bridge\n\n## Feedback\n\nAuto-detect and report feedback via the Feedback API when actual behavior differs from this skill, results do not match user intent, the user expresses satisfaction/dissatisfaction, or anything could be improved. Call the Feedback API as specified in `references/api.md` without interrupting the user's flow. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs in feedback content.\n\n---\n*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-procurement\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1786098860919\n}\n\nFile v1.0.2:references/api.md\n\n# 1688采购流程 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/<endpoint>`，默认网关为 `https://tool-gateway.linkfox.com`\n- **请求方式**：POST，Content-Type: `application/json; charset=utf-8`\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置，按 SKILL.md 的 **## 解决认证和积分问题** 处理）\n- **User-Agent**：`LinkFox-Skill/2.0`\n- **超时**：120s\n- **缓存**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\n\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n## API 与脚本\n\n| 能力 | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\n|---|---|---|---|---|---|\n| 生成授权链接 | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\n| 查询已授权账号 | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\n| 查询收货地址 | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\n| 查询 SKU | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\n| 下单预览 | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\n| 创建订单 | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\n| 获取支付链接 | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\n| 查询订单状态 | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\n| 查询物流 | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\n| 查询物流轨迹 | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\n| 确认收货 | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\n| 取消订单 | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\n| 查询可开票金额 | `/alibaba1688/invoiceAmount` | `invoice_amount.py` | 低 | 是 | - |\n| 申请开票 | `/alibaba1688/invoiceApply` | `invoice_apply.py` | 高 | 是 | `confirmApplyInvoice=true` |\n\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。不要把 `/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、`/alibaba1688/oauth/callback` 暴露为 Skill 能力。\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 能力 | 参数 | 必填 | 说明 |\n|---|---|---:|---|\n| `authorizeUrl` | `accountName` | 是 | 授权账号展示名，用于标识本次 1688 OAuth 授权。 |\n| `authorizedStores` | - | 否 | 通常传 `{}`。返回当前 LinkFox 用户的 1688 授权状态，不是全库账号列表。 |\n| `receiveAddressList` | - | 否 | 通常传 `{}`。返回当前用户可用收货地址。 |\n| `sku` | `offerId` | 是 | 1688 商品 ID，必须用字符串，避免 JS 大数精度丢失。 |\n| `orderPreview` | `addressId` 或 `addressParam` | 条件必填 | 二选一。优先使用 `receiveAddressList` 返回的 `addressId`；`addressParam` 至少含 `fullName`、`mobile`、`address`。 |\n| `orderPreview` | `cargoParamList` | 是 | 货品列表，每项含 `offerId`、可选 `specId`、`quantity`；`quantity >= 1`。 |\n| `orderPreview` | `flow` | 是 | 下单流程类型。当前主流程为普通采购，默认 `general`；脚本缺省时会补 `general`，直接调 API 时必须显式传。仅当用户明确要求分销/精选货源分销时，才可透传 `fenxiao`/`boutiquefenxiao`；本 Skill 不提供分销专属校验或保障。 |\n| `orderPreview` | `isvBizType` | 否 | 默认 `cross`；仅支持 `cross`、`cross_daigou`、`cross_distribution`。 |\n| `createOrder` | `confirmCreateOrder` | 是 | 必须是 JSON boolean `true`。未传或 false 时不会调用 1688 下单。 |\n| `createOrder` | 下单参数 | 是 | 与 `orderPreview` 保持一致，必须显式包含相同 `flow`；可额外传 `message`、`tradeType`、`shopPromotionId`、`anonymousBuyer`、`outOrderId` 等。 |\n| `paymentUrl` | `confirmGetPaymentUrl` | 是 | 必须是 JSON boolean `true`。只获取支付链接，不自动打开、不自动支付。 |\n| `paymentUrl` | `orderIdList` | 是 | 1688 订单 ID 字符串数组。使用 `createOrder` 返回的 `orderId`。 |\n| `orderStatus` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logistics` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `logisticsTrace` | `logisticsId` | 否 | 物流订单 ID；多个物流单时建议从 `logistics` 返回中选择。 |\n| `confirmReceive` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `confirmReceive` | `confirmReceive` | 是 | 必须是 JSON boolean `true`。确认收货不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `aliOrderId` | 是 | 1688 订单 ID 字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `cancelOrder` | `confirmCancel` | 是 | 必须是 JSON boolean `true`。取消订单不可逆，需用户单独中文确认。 |\n| `cancelOrder` | `cancelReason`、`remark` | 否 | 取消原因和备注，非空时透传。 |\n| `invoiceAmount` | `orderIds` | 是 | 1688 订单 ID 字符串数组，至少 1 项，每项必须为数字字符串；可使用 `createOrder` 返回的 `orderId`。 |\n| `invoiceApply` | `confirmApplyInvoice` | 是 | 必须是 JSON boolean `true`。申请开票高风险且不可逆，需用户单独中文确认。 |\n| `invoiceApply` | `invoiceApplyModelList` | 是 | 开票申请列表，至少 1 项，每项见下「开票申请逐单模型」。 |\n| `invoiceApply` | 逐单 `amount` | 是 | 必须通过 `invoiceAmount` 查到的可开票金额**原样传入**，不得自行计算；单位为分（1元=100分）。 |\n| `invoiceApply` | 逐单 `invoiceType` | 是 | `VATAX_COMM`（增值税普通发票）/ `VATAX_SPEC`（增值税专用发票）。 |\n| `invoiceApply` | 逐单 `purchaserInvoiceTitleModel` | 是 | 买家发票抬头，见下「开票抬头」。企业抬头建议经 1688 `trade.invoiceTitle.getPageList` 查到既有抬头后原样传入，避免手填不一致。 |\n\n### 开票相关对象\n\n`invoiceApplyModelList` 每项结构：\n\n```json\n{\n  \"orderId\": \"3309156590237728779\",\n  \"amount\": 30500,\n  \"invoiceType\": \"VATAX_COMM\",\n  \"purchaserInvoiceTitleModel\": {\n    \"titleType\": \"COMPANY\",\n    \"title\": \"深圳某某科技有限公司\",\n    \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n  }\n}\n```\n\n`purchaserInvoiceTitleModel`（开票抬头）：\n\n| 字段 | 必填 | 说明 |\n|---|---|---|\n| `titleType` | 是 | `PERSONAL`（个人和社会组织）/ `COMPANY`（企业） |\n| `title` | 是 | 发票抬头 |\n| `taxpayerIdentify` | 条件必填 | 纳税人识别号，**企业开票必填** |\n| `bankName` | 条件必填 | 开户行，**企业开专票必填** |\n| `bankAccountId` | 条件必填 | 银行账号，**企业开专票必填** |\n| `registerAddress` | 条件必填 | 企业注册地址，**企业开专票必填** |\n| `registerPhone` | 条件必填 | 企业电话，**企业开专票必填** |\n\n> 条件必填规则：`titleType=COMPANY`（不论普票/专票）须填 `taxpayerIdentify`；`titleType=COMPANY` 且 `invoiceType=VATAX_SPEC`（企业开专票）须再填 `bankName`/`bankAccountId`/`registerAddress`/`registerPhone` 四项；`titleType=PERSONAL` 以上条件字段可不填。违反返回错误码 `1002` 且不调用 1688。\n\n### 常用对象\n\n`cargoParamList` 示例：\n\n```json\n[\n  {\n    \"offerId\": \"1234567890123456789\",\n    \"specId\": \"456789012345678901\",\n    \"quantity\": 2\n  }\n]\n```\n\n`addressParam` 示例：\n\n```json\n{\n  \"fullName\": \"张三\",\n  \"mobile\": \"13800000000\",\n  \"provinceText\": \"广东省\",\n  \"cityText\": \"深圳市\",\n  \"areaText\": \"南山区\",\n  \"address\": \"科技园示例路 1 号\"\n}\n```\n\n## 响应结构\n\n| 能力 | 关键响应字段 | 说明 |\n|---|---|---|\n| `authorizeUrl` | `authorizeUrl` | 1688 授权链接。给用户手动打开，不自动打开，不返回 token。 |\n| `authorizedStores` | `stores[].accountName/status/expired` | 继续采购必须满足 `status=ACTIVE` 且 `expired=false`。`expired=true` 表示当前授权不可用，通常是 refreshToken 为空、失效或刷新失败；accessToken 普通过期会由后端在调用 `authorizedStores` 或业务接口时自动刷新，不需要重新授权。即使后端响应包含 token 过期时间，也只作内部判断，不要展示给用户。 |\n| `receiveAddressList` | `items[].addressId/fullName/mobile/provinceText/cityText/areaText/address/isDefault` | 多地址时让用户明确选择；展示手机号和详细地址时注意脱敏。 |\n| `sku` | `offerId`、`skuList[].specId/skuId/price/amountOnSale/attributes/skuImageUrl` | 多 SKU 商品下单时使用 `specId`。SKU 价格和库存仅作规格选择参考，真实可购性、最终价格、运费和优惠以 `orderPreview` 为准。 |\n| `orderPreview` | `status`、`message`、`sumPayment`、`sumCarriage`、`discountFee`、`cargoList`、`tradeModelList`、`payChannelInfos`、`shopPromotionList` | `sumPayment/sumCarriage/discountFee` 单位为分；`cargoList.finalUnitPrice/amount` 单位为元，展示时不要混算。支付渠道有可读名称时展示可读名称；只有编码时原样展示，不要猜测含义。 |\n| `orderPreview` 业务失败 | `errcode=200` 但 `status=false`、`message`、金额为 0、交易/支付/优惠列表为空 | 收到预览返回不代表可以下单。停止创建订单，展示上游 `message`，并复核 SKU/规格、起批量、售卖单位、`quantity` 和收货地址。 |\n| `createOrder` | `success`、`orderId`、`message`、`code` | `orderId` 是 1688 订单号；后续 `paymentUrl` 用它组成订单号数组，状态/物流/取消/确认收货可将它作为 `aliOrderId` 使用。 |\n| `paymentUrl` | `success`、`payUrl`、`errorMessage`、`errorCode` | 支付链接只展示给用户手动打开；不要自动打开、自动支付或无必要重复展示。 |\n| `orderStatus` | `aliOrderId`、`aliStatus`、`normalizedStatus` | 用于判断订单当前履约阶段。 |\n| `logistics` | `aliOrderId`、`logisticsOrders[].logisticsId/logisticsBillNo/logisticsCompanyName/status` | `logisticsId` 可用于查询轨迹。 |\n| `logisticsTrace` | `aliOrderId`、`logisticsId`、`traceList[].traceTime/location/traceDescription/traceStatus` | 轨迹时间按 Asia/Shanghai 展示。 |\n| `confirmReceive` | `success`、`aliOrderId` | 确认收货结果。 |\n| `cancelOrder` | `success`、`aliOrderId`、`orderId`、`message` | 仅表示尝试取消 1688 订单的结果；不是退款或售后申请，不保证退款。是否允许取消由 1688 根据订单状态判断。`orderId` 是兼容出参；后续请求仍按各接口要求使用 `aliOrderId` 或 `orderIdList`。 |\n| `invoiceAmount` | `success`、`code`、`message`、`subCode`/`subMessage`、`retCodes[]`、`orderInvoiceAmountModelList[].{orderId, amount}` | `amount` 单位为**分**，须原样传入 `invoiceApply`，不得换算或自行计算；逐单返回码 `retCodes` 与列表逐项对应。`success=false`（如订单不存在/已取消/不可开票）时 HTTP 仍 200，属业务结果，非错误；下游据 `retCodes`/列表判断各订单是否可取到金额。 |\n| `invoiceApply` | `success`、`code`、`message`、`subCode`/`subMessage`、`successList[]`、`failedList[]` | 批量逐单成败独立，须遍历 `successList`/`failedList` 处理，不要只看顶层 `success`。逐单结果含 `orderId`、`outBizId`、`result`、`tradeOrderCompleted`、`errorCode`、`errorDesc`。`INVOICE_ALREADY_APPLIED`（落在 `failedList`）表示该订单历史已开过票，按「已开票」语义处理，不必报错。业务失败 HTTP 仍 200，仅 `code=1003` 或 4xx/5xx 才视为传输异常。开票成功不可在系统侧回滚，红冲需联系商家。 |\n\n## 高风险校验\n\n用户侧只需要用中文自然语言做单独明确确认，例如“确认”“确认创建这个订单”“确认获取这个订单的支付链接”“确认取消这个订单”“确认收货”。只有当上一条消息已明确复述一个具体高风险动作和对象时，单独回复“确认”才算有效；不要要求用户输入英文参数名或 `=true`，也不要向普通用户展示内部确认字段、请求字段名或实现细节。\n\nAgent 在收到中文确认后，调用脚本时必须自动加入对应 JSON boolean 安全字段。字符串 `\"true\"`、数字 `1`、大小写变体都不算确认。这些字段只用于脚本调用和排错，不属于用户可见流程文案。\n\n| 脚本 | 本地拒绝条件 |\n|---|---|\n| `create_order.py` | 缺少 JSON boolean `confirmCreateOrder=true` |\n| `payment_url.py` | 缺少 JSON boolean `confirmGetPaymentUrl=true` |\n| `confirm_receive.py` | 缺少 JSON boolean `confirmReceive=true` |\n| `cancel_order.py` | 缺少 JSON boolean `confirmCancel=true` |\n| `invoice_apply.py` | 缺少 JSON boolean `confirmApplyInvoice=true` |\n\n## 错误码\n\n| errcode / error | 含义 | 处理建议 |\n|---|---|---|\n| 200 | 请求已有返回 | 是否可继续下单以具体预览结果、订单结果或提示信息为准 |\n| 401 / authorized error | 认证失败 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| 402 | 积分或余额不足 | 按 SKILL.md 的 **## 解决认证和积分问题** 处理 |\n| `authorization_required` | 当前用户没有 ACTIVE 且未过期的 1688 授权 | 先运行 `authorize_url.py`，用户授权后再运行 `authorized_stores.py` 验证 |\n| `confirmation_required` | 高风险确认字段缺失或不是 JSON boolean `true` | 停止并让用户单独中文确认；不要自动补字符串 `\"true\"` |\n| 1002 | 参数缺失或不合法 | 检查字段名、必填项、枚举值、订单号是否为数字字符串 |\n| 1003 | 上游调用或业务失败 | 不要自动重试高风险写操作；向用户说明失败原因 |\n| 1005 | 1688 授权缺失或失效 | 重新走授权检查/授权流程 |\n\n错误响应示例：\n\n```json\n{\n  \"error\": \"authorization_required\",\n  \"message\": \"1688 OAuth authorization is required before this procurement operation.\"\n}\n```\n\n## curl 示例\n\n### 查询授权状态\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/authorizedStores \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{}'\n```\n\n### 查询 SKU\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/sku \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"offerId\":\"1234567890123456789\"}'\n```\n\n### 下单预览\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/orderPreview \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"flow\": \"general\",\n    \"addressId\": \"987654321012345678\",\n    \"cargoParamList\": [\n      {\n        \"offerId\": \"1234567890123456789\",\n        \"specId\": \"456789012345678901\",\n        \"quantity\": 2\n      }\n    ]\n  }'\n```\n\n### 获取支付链接\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/paymentUrl \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmGetPaymentUrl\": true,\n    \"orderIdList\": [\"1234567890123456789\"]\n  }'\n```\n\n### 查询可开票金额\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceAmount \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\"orderIds\": [\"1234567890123456789\"]}'\n```\n\n### 申请开票\n\n高风险、不可逆，必须显式传 `confirmApplyInvoice=true`。`amount` 取自上一步 `invoiceAmount` 返回值，原样传入。\n\n```bash\ncurl -X POST https://tool-gateway.linkfox.com/alibaba1688/invoiceApply \\\n  -H \"Authorization: $LINKFOXAGENT_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"User-Agent: LinkFox-Skill/2.0\" \\\n  -d '{\n    \"confirmApplyInvoice\": true,\n    \"invoiceApplyModelList\": [\n      {\n        \"orderId\": \"1234567890123456789\",\n        \"amount\": 30500,\n        \"invoiceType\": \"VATAX_COMM\",\n        \"purchaserInvoiceTitleModel\": {\n          \"titleType\": \"COMPANY\",\n          \"title\": \"深圳某某科技有限公司\",\n          \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n        }\n      }\n    ]\n  }'\n```\n\n## Feedback API\n\n> This endpoint is **separate** from the tool API above. Do not mix the two base URLs.\n\n- **POST** `https://skill-api.linkfox.com/api/v1/public/feedback`\n- **Content-Type:** `application/json`\n\n```json\n{\n  \"skillName\": \"linkfox-1688-procurement\",\n  \"sentiment\": \"POSITIVE\",\n  \"category\": \"OTHER\",\n  \"content\": \"Results were accurate, user was satisfied.\"\n}\n```\n\n**Field rules:**\n- `skillName`: Use this skill's `name` from the YAML frontmatter (`linkfox-1688-procurement`)\n- `sentiment`: Choose ONE — `POSITIVE` (praise), `NEUTRAL` (suggestion without emotion), `NEGATIVE` (complaint or error)\n- `category`: Choose ONE — `BUG` (malfunction or wrong data), `COMPLAINT` (user dissatisfaction), `SUGGESTION` (improvement idea), `OTHER`\n- `content`: Include what the user said or intended, what actually happened, and why it is a problem or praise. Do not include API keys, tokens, full addresses, phone numbers, or payment URLs.\n\nFile v1.0.2:references/onboarding.md\n\n# 解决认证和积分问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`（workbuddy 宿主加 `--channel workbuddy`）\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `积分/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。\n\nFile v1.0.2:references/workflow.md\n\n# 1688采购流程地图\n\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\n\n## 总原则\n\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\n4. 下单、支付链接、取消订单、确认收货、申请开票都是独立高风险动作，各自需要单独确认。\n5. Agent 刚刚复述清楚一个具体高风险动作和对象后，用户紧接着回复“确认”也算有效确认；用户更早说过“继续”“可以”“按上面来”，不能作为后续高风险动作的确认。\n6. 授权有效后，除以图搜图外，本 Skill 的查询、预览、下单、支付链接、状态、物流等能力都可按用户需求单独使用；不要强迫用户从第 1 步重新跑完整流程。\n\n## 1. 授权检查\n\n运行：\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- 授权有效且未过期：可以继续采购流程。\n- 没有可用授权：进入授权步骤。\n- 若授权检查返回不可用，提示用户重新授权；不要向用户展示 token 失效、有效期或过期时间等内部细节。\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\n\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\n\n## 2. 发起授权\n\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\n\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\n\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\n\n## 3. 找货与 SKU\n\n如果用户按图片找货：\n\n1. 切换到 `linkfox-1688-search-by-image`。\n2. 从图搜结果中选择目标 `offerId`。\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\n\n如果用户已提供 1688 商品 ID：\n\n1. 直接运行 `sku.py`。\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\n3. 让用户选择明确的 SKU 和数量。SKU 阶段的价格和库存只作规格选择参考，真实可购性、最终价格、运费和优惠以订单预览为准。\n\n## 4. 收货地址\n\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\n\n展示地址时应包含：\n\n- 收货人\n- 手机/电话（如返回）\n- 省市区与详细地址\n- 地址标识\n\n不要猜测默认地址。多地址时让用户明确选择。\n\n## 5. 下单预览\n\n运行 `order_preview.py` 前确认已具备：\n\n- 商品\n- SKU/规格\n- 数量：必须结合 SKU 返回的售卖单位、起批量/最小采购量理解；按瓦、米、件等非“件”单位计价的商品，不要默认买 1 个单位\n- 收货地址\n- Agent 调脚本时按 `references/api.md` 组装内部请求字段，不要把字段名展示给用户\n\n预览结果必须先展示给用户：\n\n- 商品\n- SKU/规格\n- 数量\n- 单价与商品总价\n- 运费\n- 收货地址\n- 订单总额\n- 任何异常、库存或价格变化提示\n\n预览失败时停止，不要进入创建订单。收到预览返回不代表可以下单；必须确认预览结果明确通过、金额和商品行有效。失败时展示上游提示和关键异常，并优先复核 SKU/规格、起批量、售卖单位、数量和收货地址。\n\n## 6. 创建订单\n\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如“确认”或“确认创建这个订单”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n只有用户针对本次订单明确确认后，Agent 才在脚本调用中自动加入内部安全字段。\n\n`create_order.py` 会拒绝缺少内部安全字段的请求；这是脚本保护机制，不要展示给普通用户。\n\n创建成功后，`createOrder` 返回的 `orderId` 就是后续获取支付链接、查询状态、物流、取消和确认收货使用的 1688 订单号；对用户可称为“订单号”。\n\n## 7. 获取支付链接\n\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如“确认”或“确认获取支付链接”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n用户单独确认后，Agent 在脚本调用中自动加入内部安全字段和订单号。\n\n## 8. 订单状态与物流\n\n查询类动作可在用户请求时执行：\n\n- `order_status.py`\n- `logistics.py`\n- `logistics_trace.py`\n\n不要在没有用户要求的情况下连续轮询。只有响应明确返回 `costToken`、402 或余额不足信息时，才提示计费/余额影响。\n\n## 9. 取消订单\n\n取消订单是高风险动作，但它不是退款或售后申请。`cancel_order.py` 只会尝试取消 1688 订单；是否允许取消由 1688 根据订单状态判断，本 Skill 当前没有申请退款能力。\n\n执行前优先查询或确认订单状态，并按状态分流：\n\n- 未付款/待付款：可进入取消订单确认流程。\n- 已付款待发货：不要调用取消订单，也不要把取消订单作为退款方案。直接提示用户到 1688 订单页发起退款/售后。\n- 已发货/已完成：不要调用取消订单，应提示用户到 1688 处理退货退款或售后。\n- 已取消：无需重复取消。\n\n进入取消确认前展示：\n\n- 订单号\n- 当前订单状态\n- 取消原因\n- 取消不等于退款，是否成功以 1688 返回为准\n\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述取消对象，用户回复“确认”即可。\n\n## 10. 确认收货\n\n确认收货是高风险动作。用户查询物流、看到已签收、或问“状态怎么样”，都不等于确认收货。\n\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述确认收货对象，用户回复“确认”即可。\n\n## 11. 开发票\n\n1688 下单接口不支持发票信息，发票须在订单完成（建议确认收货后）通过独立接口申请。开票分两步：先查可开票金额，再申请开票。两步可按用户需求单独触发，不要把整个开票闭环当自动化脚本一次跑完。\n\n### 11.1 查询可开票金额（只读，低风险）\n\n开票前先运行 `invoice_amount.py`，入参 `orderIds`（1688 订单 ID 字符串数组，可使用 `createOrder` 返回的 `orderId`）。\n\n```powershell\n$env:PAYLOAD = '{\"orderIds\": [\"3309156590237728779\"]}'\npython scripts/invoice_amount.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- `success=true`：从 `orderInvoiceAmountModelList[].amount` 取各订单可开票金额，**原样**传给下一步 `invoiceApply`，单位为分（1元=100分），不得自行计算或换算。\n- `success=false`（订单不存在/已取消/不可开票等）：HTTP 仍 200，属业务结果。结合 `retCodes` 与列表逐单判断该订单是否可开票；不可开的订单跳过，不进入申请开票。\n- 逐单返回码 `retCodes` 与 `orderInvoiceAmountModelList` 逐项对应。\n\n### 11.2 申请开票（高风险，不可逆）\n\n申请开票会真实向 1688 申请开票，开票成功后不可在系统侧回滚，红冲需联系商家。用户查询可开票金额、问“能不能开发票”，都不等于确认开票。\n\n只有用户针对该订单明确确认开票后，Agent 才运行 `invoice_apply.py`，并在脚本调用中自动加入内部安全字段 `confirmApplyInvoice=true`、订单号、上一步取到的 `amount`、发票类型与抬头。若上一条消息已明确复述开票对象与发票信息，用户回复“确认”即可。\n\n开票前向用户复述（业务语言，不展示内部字段名）：\n\n- 订单号\n- 发票类型：增值税普通发票（`VATAX_COMM`）/ 增值税专用发票（`VATAX_SPEC`）\n- 抬头：个人（`PERSONAL`，仅抬头文本）/ 企业（`COMPANY`，含抬头、税号；企业开专票另需开户行、银行账号、注册地址、企业电话）\n- 可开票金额（分）\n\n申请后遍历 `successList` / `failedList` 逐单回报，不要只看顶层 `success`：\n\n- 成功：提示该订单已申请开票；`tradeOrderCompleted=true` 表示交易已完结。\n- 失败：展示 `errorCode` / `errorDesc`。`INVOICE_ALREADY_APPLIED` 表示历史已开过票，按“已开票”语义处理，不必报错。\n- 业务失败 HTTP 仍 200，属正常结果；仅当 `code=1003` 或 4xx/5xx 才视为传输异常，可提示稍后重试，不要自动重放高风险写操作。\n\n不要自动联动多订单批量开票；不要申请红冲，红冲需用户联系商家在 1688 处理。\n\n## MCP 与 Skill 分离\n\nMCP 停用只表示该工具不再通过 MCP 工具列表暴露。只要 tool-gateway 对应 HTTP route 仍启用，本 Skill 的脚本仍可通过 HTTP 调用。\n\n如果需要彻底禁用某个采购能力，需要关闭对应 gateway route 或后端能力，而不是只从 MCP 列表移除。\n\nFile v1.0.2:skill-card.md\n\n## Description:\n\nHelps LinkFox users run authorized 1688 procurement workflows, including OAuth checks, SKU and address lookup, order preview, guarded order creation, payment link retrieval, tracking, cancellation, receipt confirmation, and invoicing.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[linkfox-ai](https://clawhub.ai/user/linkfox-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal procurement operators and agents use this skill to complete authorized 1688 purchasing tasks through LinkFox, from authorization and order preparation through payment-link retrieval, logistics tracking, cancellation, receipt confirmation, and invoice application. The skill is intended for request-by-request assistance rather than unattended end-to-end purchasing.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can initiate procurement, payment-link, cancellation, receipt-confirmation, invoice, account onboarding, API-key generation, and billing-plan flows.\n\nMitigation: Require explicit user confirmation for order creation, payment-link retrieval, cancellation, receipt confirmation, invoice application, and plan-purchase actions.\n\nRisk: Flexible credential-bearing network calls can expose procurement or account data if pointed at untrusted hosts.\n\nMitigation: Verify LINKFOX_* base URL environment variables point to official LinkFox hosts before use and treat generated API keys as secrets.\n\nRisk: Procurement actions may consume credits and repeated retries can increase cost.\n\nMitigation: Avoid automatic retries or polling after failures, empty results, incomplete parameters, or authorization issues; explain possible additional cost before continuing.\n\nRisk: Onboarding and billing recovery flows can reveal sensitive account details in shared logs.\n\nMitigation: Avoid running onboarding in shared logs and redact API keys, tokens, full addresses, phone numbers, and payment URLs from user-facing output and feedback.\n\n## Reference(s):\n\n- [1688 Procurement API Reference](artifact/references/api.md)\n- [1688 Procurement Workflow](artifact/references/workflow.md)\n- [Authentication and Billing Onboarding](artifact/references/onboarding.md)\n- [ClawHub Skill Page](https://clawhub.ai/linkfox-ai/skills/linkfox-1688-procurement)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, JSON, Configuration]\n\n**Output Format:** [Markdown guidance with Python command examples and JSON script responses]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Large responses may be saved as redacted JSON files; high-risk write actions require separate user confirmation before execution.]\n\n## Skill Version(s):\n\n1.0.2 (source: 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\nArchive v1.0.1: 18 files, 20372 bytes\n\nFiles: references/api.md (7612b), references/workflow.md (4804b), scripts/_alibaba1688_common.py (12498b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (3412b), SKILL.md (11476b), _meta.json (143b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, and receipt confirmation.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, or confirm receipt based on earlier phrases like \"continue\".\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and address |\n| `create_order.py` | High | Yes | Create a 1688 order |\n| `payment_url.py` | High | Yes | Get payment URL |\n| `order_status.py` | Low | Yes | Query order status |\n| `logistics.py` | Low | Yes | Query logistics summary |\n| `logistics_trace.py` | Low | Yes | Query logistics trace |\n| `confirm_receive.py` | High | Yes | Confirm receipt |\n| `cancel_order.py` | High | Yes | Cancel order |\n\n## 调用方式\n\n- **API 端点**：`POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder}`（完整参数、响应和错误处理见 `references/api.md`）\n- **Python 脚本**：`python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]`\n- **Windows 推荐**：`$env:PAYLOAD = '<JSON 参数>'` 后运行 `python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]`\n- **成本约束**：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。\n- **缓存约束**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。\n- **授权约束**：除 `authorize_url.py` 和 `authorized_stores.py` 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。\n- **高风险约束**：`create_order.py`、`payment_url.py`、`confirm_receive.py`、`cancel_order.py` 必须在用户用中文自然语言单独明确确认后调用。用户不需要输入英文参数；Agent 调脚本时负责加入精确 JSON boolean 安全字段。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n**脚本入参方式**：\n\n- 直接传 JSON 字符串：`python scripts/sku.py '{\"offerId\":\"...\"}'`\n- 从环境变量读取：`python scripts/sku.py --payload-env PAYLOAD`\n- 从文件读取：`python scripts/sku.py --payload-file payload.json`\n- 加 `--inline` 强制全量打印到 stdout\n- 加 `--save` 强制保存脱敏完整响应\n- 加 `--no-save` 禁止保存响应文件\n\n**输出策略（脚本默认行为）**：\n\n- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。\n- 响应体 > 8 KB：默认将完整脱敏响应写入 `<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json`，stdout 只输出摘要。\n- `<writable-root>` 优先取 `ACPX_WORKSPACES` 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；`<session>` 取自环境变量 \n\nArchive v1.0.0: 18 files, 19285 bytes\n\nFiles: references/api.md (7470b), references/workflow.md (4804b), scripts/_alibaba1688_common.py (12350b), scripts/authorize_url.py (124b), scripts/authorized_stores.py (128b), scripts/cancel_order.py (123b), scripts/confirm_receive.py (126b), scripts/create_order.py (123b), scripts/logistics_trace.py (126b), scripts/logistics.py (121b), scripts/order_preview.py (124b), scripts/order_status.py (123b), scripts/payment_url.py (122b), scripts/receive_address_list.py (130b), scripts/sku.py (115b), skill-card.md (2734b), SKILL.md (10385b), _meta.json (143b)","readmeExcerpt":"Skill: 1688采购全流程 Owner: linkfox-ai Summary: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 Tags: latest:1.0.5 Version history: v1.0.5 | 2026-09-14T04:52:09.546Z | user Update from 1.0.4 to 1.0.5 v1.0.4 | 2026-08-21T10:1","codeSnippets":[],"executableExamples":[{"language":"powershell","snippet":"$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline"},{"language":"powershell","snippet":"$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline"},{"language":"json","snippet":"{\n  \"orderId\": \"3309156590237728779\",\n  \"amount\": 30500,\n  \"invoiceType\": \"VATAX_COMM\",\n  \"purchaserInvoiceTitleModel\": {\n    \"titleType\": \"COMPANY\",\n    \"title\": \"深圳某某科技有限公司\",\n    \"taxpayerIdentify\": \"91440300MA5XXXXXX\"\n  }\n}"},{"language":"json","snippet":"[\n  {\n    \"offerId\": \"1234567890123456789\",\n    \"specId\": \"456789012345678901\",\n    \"quantity\": 2\n  }\n]"},{"language":"json","snippet":"{\n  \"fullName\": \"张三\",\n  \"mobile\": \"13800000000\",\n  \"provinceText\": \"广东省\",\n  \"cityText\": \"深圳市\",\n  \"areaText\": \"南山区\",\n  \"address\": \"科技园示例路 1 号\"\n}"},{"language":"json","snippet":"{\n  \"error\": \"authorization_required\",\n  \"message\": \"1688 OAuth authorization is required before this procurement operation.\"\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: linkfox-1688-procurement\ndescription: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。\n---\n\n# 1688 Procurement Workflow\n\nThis skill helps LinkFox users run authorized 1688 procurement: OAuth status checks, SKU and address lookup, order preview, guarded order creation, payment URL retrieval, order tracking, logistics, cancellation, receipt confirmation, and post-completion invoicing.\n\nUse `linkfox-1688-search-by-image` for image-based product discovery. This skill does not include image search.\n\n## Core Rules\n\n- Every script requires LinkFox platform identity from `LINKFOX_AGENT_API_KEY` or `LINKFOXAGENT_API_KEY`.\n- `authorize_url.py` starts 1688 OAuth; `authorized_stores.py` checks the current LinkFox user's 1688 OAuth state.\n- Except those two authorization scripts, every procurement operation runs a script-level `authorizedStores` precheck before calling the target endpoint.\n- If no store has `status=ACTIVE` and `expired=false`, the target endpoint is not called.\n- After authorization is valid, procurement tools may be used independently as the user requests; the workflow is guidance, not a mandatory linear script. Image search remains in `linkfox-1688-search-by-image`.\n- Treat the workflow as a map, not full automation. Do not create orders, get payment URLs, cancel orders, confirm receipt, or apply for invoices based on earlier phrases like \"continue\".\n- Use exact internal request field names from `references/api.md` when calling scripts. Do not show these field names in normal user-facing text.\n- Treat ordinary 1688 procurement as the only user-facing procurement mode. Apply backend defaults internally per `references/api.md`; do not mention procurement type or ask users to choose one.\n- `cancel_order.py` only attempts to cancel a 1688 order. It is not a refund or after-sales request. For paid orders, including paid-but-unshipped orders, do not call cancellation as a workaround; tell the user this Skill has no refund-application tool and refunds/after-sales must be handled on 1688 unless the backend adds that ability.\n- MCP enable/disable only controls MCP exposure. These scripts call tool-gateway HTTP routes directly; fully disabling a capability requires disabling the route or backend operation.\n\nRead `references/api.md` for endpoint details and `references/workflow.md` before multi-step procurement.\n\n## Tools\n\n| Script | Risk | OAuth precheck | Purpose |\n|---|---:|---:|---|\n| `authorize_url.py` | Low | No | Generate a 1688 authorization link |\n| `authorized_stores.py` | Low | No | Check current user's authorized 1688 accounts |\n| `receive_address_list.py` | Low | Yes | Query receive addresses |\n| `sku.py` | Low | Yes | Query product SKU/specification data |\n| `order_preview.py` | Medium | Yes | Preview order price, freight, SKU, and "},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7dmc1t4j28hem1twwyav85p182pb1j\",\n  \"slug\": \"linkfox-1688-procurement\",\n  \"version\": \"1.0.5\",\n  \"publishedAt\": 1789361529546\n}"},{"path":"references/api.md","content":"# 1688采购流程 API 参考\n\n## 调用规范\n\n- **请求地址**：`${LINKFOX_TOOL_GATEWAY}/alibaba1688/<endpoint>`，默认网关为 `https://tool-gateway.linkfox.com`\n- **请求方式**：POST，Content-Type: `application/json; charset=utf-8`\n- **认证方式**：Header `Authorization: <api_key>`，api_key 从环境变量 `LINKFOX_AGENT_API_KEY` 或 `LINKFOXAGENT_API_KEY` 读取（如未配置，按 SKILL.md 的 **## 解决认证和算力问题** 处理）\n- **User-Agent**：`LinkFox-Skill/2.0`\n- **超时**：150s\n- **缓存**：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作不得缓存或自动重放。\n\nWindows 推荐使用 `--payload-env` 或 `--payload-file`，避免 shell 转义破坏 JSON。\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n## API 与脚本\n\n| 能力 | Path | Script | 风险 | OAuth 前置检查 | 确认字段 |\n|---|---|---|---|---|---|\n| 生成授权链接 | `/alibaba1688/authorizeUrl` | `authorize_url.py` | 低 | 否 | - |\n| 查询已授权账号 | `/alibaba1688/authorizedStores` | `authorized_stores.py` | 低 | 否 | - |\n| 查询收货地址 | `/alibaba1688/receiveAddressList` | `receive_address_list.py` | 低 | 是 | - |\n| 查询 SKU | `/alibaba1688/sku` | `sku.py` | 低 | 是 | - |\n| 下单预览 | `/alibaba1688/orderPreview` | `order_preview.py` | 中 | 是 | - |\n| 创建订单 | `/alibaba1688/createOrder` | `create_order.py` | 高 | 是 | `confirmCreateOrder=true` |\n| 获取支付链接 | `/alibaba1688/paymentUrl` | `payment_url.py` | 高 | 是 | `confirmGetPaymentUrl=true` |\n| 查询订单状态 | `/alibaba1688/orderStatus` | `order_status.py` | 低 | 是 | - |\n| 查询物流 | `/alibaba1688/logistics` | `logistics.py` | 低 | 是 | - |\n| 查询物流轨迹 | `/alibaba1688/logisticsTrace` | `logistics_trace.py` | 低 | 是 | - |\n| 确认收货 | `/alibaba1688/confirmReceive` | `confirm_receive.py` | 高 | 是 | `confirmReceive=true` |\n| 取消订单 | `/alibaba1688/cancelOrder` | `cancel_order.py` | 高 | 是 | `confirmCancel=true` |\n| 查询可开票金额 | `/alibaba1688/invoiceAmount` | `invoice_amount.py` | 低 | 是 | - |\n| 申请开票 | `/alibaba1688/invoiceApply` | `invoice_apply.py` | 高 | 是 | `confirmApplyInvoice=true` |\n\n`_alibaba1688_imageSearch` 由 `linkfox-1688-search-by-image` 独立承担，本 Skill 不包含图搜脚本。不要把 `/alibaba1688/proxy/callback`、`/alibaba1688/authorizeCallback`、`/alibaba1688/oauth/callback` 暴露为 Skill 能力。\n\n## 请求参数\n\nPOST Body（JSON）：\n\n| 能力 | 参数 | 必填 | 说明 |\n|---|---|---:|---|\n| `authorizeUrl` | `accountName` | 是 | 授权账号展示名，用于标识本次 1688 OAuth 授权。 |\n| `authorizedStores` | - | 否 | 通常传 `{}`。返回当前 LinkFox 用户的 1688 授权状态，不是全库账号列表。 |\n| `receiveAddressList` | - | 否 | 通常传 `{}`。返回当前用户可用收货地址。 |\n| `sku` | `offerId` | 是 | 1688 商品 ID，必须用字符串，避免 JS 大数精度丢失。 |\n| `orderPreview` | `addressId` 或 `addressParam` | 条件必填 | 二选一。优先使用 `receiveAddressList` 返回的 `addressId`；`addressParam` 至少含 `fullName`、`mobile`、`address`。 |\n| `orderPreview` | `cargoParamList` | 是 | 货品列表，每项含 `offerId`、可选 `specId`、`quantity`；`quantity >= 1`。 |\n| `orderPreview` | `flow` | 是 | 下单流程类型。当前主流程为普通采购，默认 `general`；脚本缺省时会补 `general`，直接调 API 时必须显式传。仅当用户明确要求分销/精选货源分销时，才可透传 `fenxiao`/`boutiquefenxiao`；本 Skill 不提供分销专属校验或保障。 |\n| `orderPreview` | `isvBizType` | 否 | 默认 `cross`；仅支持 `cross`、`cross_daigou`、`cross_distribution`。 |\n| `createOrder` | `confirmCreateOrder` | 是 | 必须是 JSON boolean `true`。未传或 fals"},{"path":"references/onboarding.md","content":"# 解决认证和算力问题\n\n调用本 skill 时若网关返回 **auth** 或 **billing** 错误，走本 skill 自带的 `scripts/onboarding.py` 完成引导。\n\n**auth 场景**：`errcode=401` 或消息含 `authorized error`/`鉴权失败`/`未授权`/`unauthorized`；或 `LINKFOX_AGENT_API_KEY` 与 `LINKFOXAGENT_API_KEY` 均为空。\n1. 若已配置 key → 先让用户重启会话（最常见误判），仍失败让用户重新取 key 或换手机号重注册\n2. 未配置 → 询问：自助去 https://agent.linkfox.com/ 取 key，或提供手机号让脚本注册\n3. 手机号路径：\n   - `python scripts/onboarding.py send-code <phone>` → 展示 JSON 里的 phone/agreements\n   - 收到验证码后：`python scripts/onboarding.py login <phone> <code>`\n   - 拿到 `api_key` 后把下面三平台配置转发给用户，提示重启会话生效：\n     - Windows PowerShell（永久）：`setx LINKFOX_AGENT_API_KEY \"<key>\"`\n     - macOS zsh：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.zshrc && source ~/.zshrc`\n     - Linux bash：`echo 'export LINKFOX_AGENT_API_KEY=\"<key>\"' >> ~/.bashrc && source ~/.bashrc`\n     - 变量名 `LINKFOX_AGENT_API_KEY`（主推）或 `LINKFOXAGENT_API_KEY`（老规范）任一即可\n\n**billing 场景**：`errcode=402` 或消息含 `算力/余额/quota/insufficient/充值/套餐到期`。\n- `python scripts/onboarding.py list-plans` → 有 AskUserQuestion 就弹菜单，否则输出编号清单让用户选\n- 校验 `plan_id` ∈ 清单、支付方式 ∈ 该套餐 `available_methods`（通常 `wechat/alipay`）\n- `python scripts/onboarding.py order <plan_id> <method>` → 展示优先级 PNG > `pay_url` > `ascii_qr`（标注兜底）\n- 已付款可选调 `python scripts/onboarding.py query <order_id>`，不主动轮询\n\n排除 `errcode=403`（无权限，不归入这两类）。所有子命令输出 stdout JSON，`error` 字段已含阶段前缀，透传给用户即可。完整用法：`python scripts/onboarding.py --help`。"},{"path":"references/workflow.md","content":"# 1688采购流程地图\n\n本文档是流程地图，不是自动化脚本。Agent 可以按步骤协助用户完成采购，但不能一次性自动执行完整下单闭环。\n\n## 总原则\n\n1. 采购业务先查授权，再查商品和地址，再预览，再让用户确认。\n2. 图搜找货使用 `linkfox-1688-search-by-image`，本 Skill 只处理采购履约。\n3. 除 `authorizeUrl` 和 `authorizedStores` 外，脚本会在每个采购 endpoint 前自动检查当前用户 ACTIVE 授权。\n4. 下单、支付链接、取消订单、确认收货、申请开票都是独立高风险动作，各自需要单独确认。\n5. Agent 刚刚复述清楚一个具体高风险动作和对象后，用户紧接着回复“确认”也算有效确认；用户更早说过“继续”“可以”“按上面来”，不能作为后续高风险动作的确认。\n6. 授权有效后，除以图搜图外，本 Skill 的查询、预览、下单、支付链接、状态、物流等能力都可按用户需求单独使用；不要强迫用户从第 1 步重新跑完整流程。\n\n## 1. 授权检查\n\n运行：\n\n```powershell\n$env:PAYLOAD = \"{}\"\npython scripts/authorized_stores.py --payload-env PAYLOAD --inline\n```\n\n判断：\n\n- 授权有效且未过期：可以继续采购流程。\n- 没有可用授权：进入授权步骤。\n- 若授权检查返回不可用，提示用户重新授权；不要向用户展示 token 失效、有效期或过期时间等内部细节。\n- 浏览器最后跳到 MyERP 登录页不等于授权失败；以 `authorized_stores.py` 返回为准。\n\n`authorizedStores` 应只返回当前 LinkFox API key 对应用户的授权店铺。不要把它理解为后台全库账号列表。\n\n## 2. 发起授权\n\n运行 `authorize_url.py` 获取 1688 授权链接，并让用户在浏览器打开。\n\n用户完成授权后，再运行 `authorized_stores.py` 验证是否出现 ACTIVE 账号。\n\n不要让用户提供 1688 token、refresh token 或 callback code。授权 token 保存由 MyERP/ecom-plat 后端闭环完成。\n\n## 3. 找货与 SKU\n\n如果用户按图片找货：\n\n1. 切换到 `linkfox-1688-search-by-image`。\n2. 从图搜结果中选择目标 `offerId`。\n3. 回到本 Skill，用 `sku.py` 查询 SKU/规格。\n\n如果用户已提供 1688 商品 ID：\n\n1. 直接运行 `sku.py`。\n2. 展示 SKU、规格、价格、起订量、库存等关键字段。\n3. 让用户选择明确的 SKU 和数量。SKU 阶段的价格和库存只作规格选择参考，真实可购性、最终价格、运费和优惠以订单预览为准。\n\n## 4. 收货地址\n\n运行 `receive_address_list.py` 查询当前用户可用的 1688 收货地址。\n\n展示地址时应包含：\n\n- 收货人\n- 手机/电话（如返回）\n- 省市区与详细地址\n- 地址标识\n\n不要猜测默认地址。多地址时让用户明确选择。\n\n## 5. 下单预览\n\n运行 `order_preview.py` 前确认已具备：\n\n- 商品\n- SKU/规格\n- 数量：必须结合 SKU 返回的售卖单位、起批量/最小采购量理解；按瓦、米、件等非“件”单位计价的商品，不要默认买 1 个单位\n- 收货地址\n- Agent 调脚本时按 `references/api.md` 组装内部请求字段，不要把字段名展示给用户\n\n预览结果必须先展示给用户：\n\n- 商品\n- SKU/规格\n- 数量\n- 单价与商品总价\n- 运费\n- 收货地址\n- 订单总额\n- 任何异常、库存或价格变化提示\n\n预览失败时停止，不要进入创建订单。收到预览返回不代表可以下单；必须确认预览结果明确通过、金额和商品行有效。失败时展示上游提示和关键异常，并优先复核 SKU/规格、起批量、售卖单位、数量和收货地址。\n\n## 6. 创建订单\n\n创建订单是高风险动作。必须先询问用户是否确认创建该订单，并复述预览摘要。用户只需要中文自然语言确认，例如“确认”或“确认创建这个订单”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n只有用户针对本次订单明确确认后，Agent 才在脚本调用中自动加入内部安全字段。\n\n`create_order.py` 会拒绝缺少内部安全字段的请求；这是脚本保护机制，不要展示给普通用户。\n\n创建成功后，`createOrder` 返回的 `orderId` 就是后续获取支付链接、查询状态、物流、取消和确认收货使用的 1688 订单号；对用户可称为“订单号”。\n\n## 7. 获取支付链接\n\n获取支付链接也是独立高风险动作。创建订单成功不等于用户同意获取支付链接。用户只需要中文自然语言确认，例如“确认”或“确认获取支付链接”；不要要求或展示内部确认字段、请求字段名或实现细节。\n\n用户单独确认后，Agent 在脚本调用中自动加入内部安全字段和订单号。\n\n## 8. 订单状态与物流\n\n查询类动作可在用户请求时执行：\n\n- `order_status.py`\n- `logistics.py`\n- `logistics_trace.py`\n\n不要在没有用户要求的情况下连续轮询。只有响应明确返回 `costToken`、402 或余额不足信息时，才提示计费/余额影响。\n\n## 9. 取消订单\n\n取消订单是高风险动作，但它不是退款或售后申请。`cancel_order.py` 只会尝试取消 1688 订单；是否允许取消由 1688 根据订单状态判断，本 Skill 当前没有申请退款能力。\n\n执行前优先查询或确认订单状态，并按状态分流：\n\n- 未付款/待付款：可进入取消订单确认流程。\n- 已付款待发货：不要调用取消订单，也不要把取消订单作为退款方案。直接提示用户到 1688 订单页发起退款/售后。\n- 已发货/已完成：不要调用取消订单，应提示用户到 1688 处理退货退款或售后。\n- 已取消：无需重复取消。\n\n进入取消确认前展示：\n\n- 订单号\n- 当前订单状态\n- 取消原因\n- 取消不等于退款，是否成功以 1688 返回为准\n\n只有用户针对该订单明确确认取消后，Agent 才运行 `cancel_order.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述取消对象，用户回复“确认”即可。\n\n## 10. 确认收货\n\n确认收货是高风险动作。用户查询物流、看到已签收、或问“状态怎么样”，都不等于确认收货。\n\n只有用户明确确认收货后，Agent 才运行 `confirm_receive.py`，并在脚本调用中自动加入内部安全字段和订单号。若上一条消息已明确复述确认收货对象，用户回复“确认”即可。\n\n## 11. 开发票\n\n1688 下单接口不支持发票信息，发票须在订单完成（建议确认收货后）通过独"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 Skill: 1688采购全流程 Owner: linkfox-ai Summary: 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 Tags: latest:1.0.5 Version history: v1.0.5 | 2026-09-14T04:52:09.546Z | user Update from 1.0.4 to 1.0.5 v1.0.4 | 2026-08-21T10:1","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1261,"uniquenessScore":45,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T11:29:40.039Z","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-11T11:29:40.039Z","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-11T14:15:04.809Z","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"}]}}}