| name | linkfox-1688-procurement |
| description | 1688采购全流程技能。用于1688授权链接、授权店铺检查、收货地址、商品SKU、下单预览、创建订单、支付链接、订单状态、物流、物流轨迹、取消订单、确认收货等已授权采购履约场景。用户提到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, and receipt confirmation.
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.
- 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".
- 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 |
调用方式
- API 端点：
POST /alibaba1688/{authorizeUrl|authorizedStores|receiveAddressList|sku|orderPreview|createOrder|paymentUrl|orderStatus|logistics|logisticsTrace|confirmReceive|cancelOrder}（完整参数、响应和错误处理见 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。
- 高风险约束：
create_order.py、payment_url.py、confirm_receive.py、cancel_order.py 必须在用户用中文自然语言单独明确确认后调用。用户不需要输入英文参数；Agent 调脚本时负责加入精确 JSON boolean 安全字段。
$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 强制保存脱敏完整响应
- 加
--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 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用以下措施来处理：
异常情况
- 未配置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. Do not ask the user to type English parameter names.
After the user confirms in Chinese, the Agent must add the internal JSON boolean safety field when calling the script. These fields must be exact boolean true; string "true" and number 1 are rejected locally.
| Operation | Required field |
|---|
createOrder | confirmCreateOrder=true |
paymentUrl | confirmGetPaymentUrl=true |
confirmReceive | confirmReceive=true |
cancelOrder | confirmCancel=true |
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, quantity, price, freight, address, total, and warnings.
- Only after separate Chinese confirmation, run
create_order.py; the Agent adds confirmCreateOrder=true internally.
- Only after separate Chinese confirmation, run
payment_url.py; the Agent adds confirmGetPaymentUrl=true internally.
- 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.
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.- Never display full API keys, JWTs, access tokens, refresh tokens, callback codes, app secrets, session keys, or Authorization headers.
- Show order preview clearly: product/offerId, 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 ask the user to type the internal boolean field.
- 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 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 |
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.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.
