| name | linkfox-1688-procurement |
| description | 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货、开发票等已授权采购履约场景。用户提到1688采购、1688下单、1688授权、1688订单、1688支付、1688物流、1688开发票、1688开票、1688发票、1688 sourcing procurement或1688 order processing时触发。以图搜图使用linkfox-1688-search-by-image。 |
1688 Procurement Workflow
This 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.
Use linkfox-1688-search-by-image for image-based product discovery. This skill does not include image search.
Core Rules
- Every script requires LinkFox platform identity from
LINKFOX_AGENT_API_KEY or LINKFOXAGENT_API_KEY.
authorize_url.py starts 1688 OAuth; authorized_stores.py checks the current LinkFox user's 1688 OAuth state.- Except those two authorization scripts, every procurement operation runs a script-level
authorizedStores precheck before calling the target endpoint.
- If no store has
status=ACTIVE and expired=false, the target endpoint is not called.
- 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.
- 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".
- Use exact internal request field names from
references/api.md when calling scripts. Do not show these field names in normal user-facing text.
- 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.
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.- 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.
Read references/api.md for endpoint details and references/workflow.md before multi-step procurement.
Tools
| Script | Risk | OAuth precheck | Purpose |
|---|
authorize_url.py | Low | No | Generate a 1688 authorization link |
authorized_stores.py | Low | No | Check current user's authorized 1688 accounts |
receive_address_list.py | Low | Yes | Query receive addresses |
sku.py | Low | Yes | Query product SKU/specification data |
order_preview.py | Medium | Yes | Preview order price, freight, SKU, and address |
create_order.py | High | Yes | Create a 1688 order |
payment_url.py | High | Yes | Get payment URL |
order_status.py | Low | Yes | Query order status |
logistics.py | Low | Yes | Query logistics summary |
logistics_trace.py | Low | Yes | Query logistics trace |
confirm_receive.py | High | Yes | Confirm receipt |
cancel_order.py | High | Yes | Cancel order |
invoice_amount.py | Low | Yes | Query invoiceable amount before applying for an invoice |
invoice_apply.py | High | Yes | Apply for an invoice after order completion |
调用方式
- API 端点：
POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder|invoiceAmount|invoiceApply}（完整参数、响应和错误处理见 references/api.md）
- Python 脚本：
python scripts/<script_name>.py '<JSON 参数>' [--inline] [--save] [--no-save]
- Windows 推荐：
$env:PAYLOAD = '<JSON 参数>' 后运行 python scripts/<script_name>.py --payload-env PAYLOAD [--inline] [--save]
- 成本约束：本工具会消耗积分。失败、空结果、参数不完整或授权不足时，不得自动连续试探、换参数重试或轮询；需要继续查询时先向用户说明会产生额外消耗。
- 缓存约束：本采购 Skill 不做 24h 响应缓存；授权、价格、库存、订单状态和物流以实时返回为准，高风险写操作更不能缓存。
- 授权约束：除
authorize_url.py 和 authorized_stores.py 外，脚本会在调用目标接口前自动检查当前用户的 ACTIVE 1688 授权；没有 ACTIVE 且未过期授权时不会调用目标 endpoint。
- 授权刷新：accessToken 临期或已过期时后端会用该用户自己的 refreshToken 自动刷新，调用
authorizedStores 或采购接口时都会触发，Skill 与用户无需介入。只有 refreshToken 为空、失效或刷新失败（authorizedStores 返回 expired=true）时才需要重新走 authorize_url.py 授权；不要向用户展示或播报 token 有效期、过期时间、刷新窗口等内部授权细节。
- 高风险约束：
create_order.py、payment_url.py、confirm_receive.py、cancel_order.py、invoice_apply.py 必须在用户用中文自然语言单独明确确认后调用。内部确认字段和请求细节只供 Agent 调脚本使用，不要展示给用户。
$env:PAYLOAD = "{}"
python scripts/authorized_stores.py --payload-env PAYLOAD --inline
脚本入参方式：
- 直接传 JSON 字符串：
python scripts/sku.py '{"offerId":"..."}'
- 从环境变量读取：
python scripts/sku.py --payload-env PAYLOAD
- 从文件读取：
python scripts/sku.py --payload-file payload.json
- 加
--inline 强制全量打印到 stdout
- 加
--save 强制保存对 token 类敏感字段脱敏
- 加
--no-save 禁止保存响应文件
输出策略（脚本默认行为）：
- 响应体 ≤ 8 KB：默认不落盘，直接把完整脱敏 JSON 打印到 stdout，避免每次查询都在 Skill 目录生成数据文件。
- 响应体 > 8 KB：默认将完整脱敏响应写入
<writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json，stdout 只输出摘要。
<writable-root> 优先取 ACPX_WORKSPACES 的第一个工作区，其次为脚本执行时的当前目录，最后回退到用户目录；<session> 取自环境变量 SESSION_ID，未提供时自动生成；禁止写入 /tmp。- 加
--save 或设置 LINKFOX_SKILL_SAVE_RESPONSE=1 强制保存；加 --no-save 或设置 LINKFOX_SKILL_NO_SAVE=1 禁止保存；--inline 不隐含保存。
读数据建议：先看 stdout 摘要判断是否足够；需要保存完整响应再加 --save，之后优先用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
异常情况
- 未配置API Key：环境变量未配置
LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
High-Risk Confirmation
Ask 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.
After 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.
Common Workflow
- Run
authorized_stores.py; continue only when the current user has an ACTIVE, unexpired 1688 authorization.
- If not authorized, run
authorize_url.py, let the user complete OAuth, then re-check authorized_stores.py.
- If starting from an image, use
linkfox-1688-search-by-image to get an offerId.
- Run
sku.py, then receive_address_list.py, then order_preview.py.
- Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.
- Only after separate Chinese confirmation, run
create_order.py; add required safety fields internally without showing them to the user.
- Only after separate Chinese confirmation, run
payment_url.py; pass the created order ID internally without showing request field names to the user.
- Use
order_status.py, logistics.py, and logistics_trace.py for tracking.
- 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.
- 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.
Display Rules
- Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.
authorizedStores output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.- 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.
- Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.
- Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.
- 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.
- For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.
- Report
costToken or equivalent cost fields only when returned.
Important Limitations
- Do not create or call image-search scripts here; image search belongs to
linkfox-1688-search-by-image.
- Do not expose
/alibaba1688/proxy/callback, /alibaba1688/authorizeCallback, or browser OAuth callback URLs as Skill capabilities.
- Do not ask users to provide 1688 tokens, refresh tokens, callback codes, or secrets. OAuth token exchange is handled by MyERP and ecom-plat.
- Do not query backend databases to discover authorization state. Use
authorizedStores.
- Do not automatically retry write operations or run the full purchase loop.
- Do not use
_dataQuery_executeDynamicQuery for live procurement responses.
User Expression & Scenario Quick Reference
Applicable -- 1688 procurement scenarios:
| User Says | Scenario |
|---|
| "查询我的1688授权店铺" / "show my authorized 1688 stores" | Authorization check |
| "生成1688授权链接" / "authorize my 1688 account" | New OAuth authorization |
| "查这个 offerId 的 SKU" | SKU lookup |
| "查1688收货地址" | Receive address lookup |
| "帮我预览1688订单" | Order preview |
| "确认下单" | High-risk create order gate |
| "获取支付链接" | High-risk payment URL gate |
| "查1688订单状态/物流" | Order tracking |
| "取消这个1688订单" | High-risk cancel gate |
| "确认收货" | High-risk confirm receive gate |
| "查1688可开票金额" / "这个订单能开发票吗" | Invoiceable amount query |
| "给这个1688订单开发票" / "确认开票" | High-risk invoice apply gate |
Not applicable -- use another skill or backend system:
- Image-based 1688 product discovery ->
linkfox-1688-search-by-image
- Keyword-based 1688 sourcing/ranking -> use existing 1688 search/ranking skills when available
- MyERP OAuth callback/proxy callback handling -> backend service, not a Skill
- Direct token repair or manual 1688 token input -> backend authorization bridge
Feedback
Auto-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.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.
