linkfox-1688-procurement

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

1. Run authorized_stores.py; continue only when the current user has an ACTIVE, unexpired 1688 authorization.
2. If not authorized, run authorize_url.py, let the user complete OAuth, then re-check authorized_stores.py.
3. If starting from an image, use linkfox-1688-search-by-image to get an offerId.
4. Run sku.py, then receive_address_list.py, then order_preview.py.
5. Show product, SKU/specification, quantity, price, freight, address, total, and warnings in business terms.
6. Only after separate Chinese confirmation, run create_order.py; add required safety fields internally without showing them to the user.
7. Only after separate Chinese confirmation, run payment_url.py; pass the created order ID internally without showing request field names to the user.
8. Use order_status.py, logistics.py, and logistics_trace.py for tracking.
9. 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.
10. 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

1. Show authorization status first when procurement depends on OAuth. Do not assume authorization from a browser redirect alone.
2. authorizedStores output is the current LinkFox user's 1688 authorization state. Do not describe it as all stores in the database.
3. 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.
4. Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.
5. Show order preview clearly in business terms: product, SKU/specification, quantity, unit price, product total, freight, receive address, order total, buyer message, and warnings.
6. 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.
7. For receive addresses, show enough to let the user choose safely, but avoid unnecessarily repeating full phone numbers or sensitive address details.
8. 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.