Linkfox 1688 Procurement

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

调用方式

• 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.