linkfox-1688-procurement

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

1688 Procurement Workflow

1688采购工作流

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.
本Skill帮助LinkFox用户执行已授权的1688采购操作:OAuth状态检查、SKU与地址查询、订单预览、受保护的订单创建、支付链接获取、订单追踪、物流查询、订单取消、收货确认以及订单完成后的发票申请。
基于图片的商品搜索请使用
linkfox-1688-search-by-image
,本Skill不包含图片搜索功能。

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.
  • 所有脚本都需要通过
    LINKFOX_AGENT_API_KEY
    LINKFOXAGENT_API_KEY
    获取LinkFox平台身份认证。
  • authorize_url.py
    用于启动1688 OAuth授权;
    authorized_stores.py
    用于检查当前LinkFox用户的1688 OAuth授权状态。
  • 除上述两个授权脚本外,所有采购操作在调用目标端点前都会执行脚本级的
    authorizedStores
    预检查。
  • 若没有状态为
    ACTIVE
    expired=false
    的店铺,则不会调用目标端点。
  • 授权验证通过后,可根据用户需求独立使用采购工具;工作流仅作为指引,并非强制线性脚本。图片搜索功能仍归属于
    linkfox-1688-search-by-image
  • 将工作流视为操作指引,而非完全自动化流程。不得根据“继续”等前期表述创建订单、获取支付链接、取消订单、确认收货或申请发票。
  • 调用脚本时需使用
    references/api.md
    中指定的内部请求字段名,不得在面向用户的常规文本中展示这些字段名。
  • 将普通1688采购作为唯一面向用户的采购模式。内部按照
    references/api.md
    应用后端默认值;不得提及采购类型或要求用户选择采购类型。
  • cancel_order.py
    仅尝试取消1688订单,不处理退款或售后请求。对于已支付订单(包括已支付但未发货的订单),不得将取消订单作为替代方案;需告知用户本Skill无退款申请工具,退款/售后需在1688平台处理,除非后端新增该能力。
  • MCP启用/禁用仅控制MCP的对外展示。这些脚本直接调用tool-gateway HTTP路由;若要完全禁用某项功能,需禁用对应路由或后端操作。
在执行多步骤采购前,请阅读
references/api.md
了解端点详情,以及
references/workflow.md
的内容。

Tools

工具列表

ScriptRiskOAuth precheckPurpose
authorize_url.py
LowNoGenerate a 1688 authorization link
authorized_stores.py
LowNoCheck current user's authorized 1688 accounts
receive_address_list.py
LowYesQuery receive addresses
sku.py
LowYesQuery product SKU/specification data
order_preview.py
MediumYesPreview order price, freight, SKU, and address
create_order.py
HighYesCreate a 1688 order
payment_url.py
HighYesGet payment URL
order_status.py
LowYesQuery order status
logistics.py
LowYesQuery logistics summary
logistics_trace.py
LowYesQuery logistics trace
confirm_receive.py
HighYesConfirm receipt
cancel_order.py
HighYesCancel order
invoice_amount.py
LowYesQuery invoiceable amount before applying for an invoice
invoice_apply.py
HighYesApply for an invoice after order completion
脚本风险等级OAuth预检查用途
authorize_url.py
生成1688授权链接
authorized_stores.py
检查当前用户的已授权1688账户
receive_address_list.py
查询收货地址
sku.py
查询商品SKU/规格数据
order_preview.py
预览订单价格、运费、SKU及地址
create_order.py
创建1688订单
payment_url.py
获取支付链接
order_status.py
查询订单状态
logistics.py
查询物流概要
logistics_trace.py
查询物流轨迹
confirm_receive.py
确认收货
cancel_order.py
取消订单
invoice_amount.py
申请发票前查询可开票金额
invoice_apply.py
订单完成后申请发票

调用方式

调用方式

  • 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 调脚本使用,不要展示给用户。
powershell
$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 进入上下文。
  • 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不做24小时响应缓存;授权、价格、库存、订单状态及物流信息均以实时返回结果为准,高风险写入操作更不得缓存。
  • 授权约束:除
    authorize_url.py
    authorized_stores.py
    外,脚本会在调用目标接口前自动检查当前用户的ACTIVE状态1688授权;若无ACTIVE且未过期的授权,则不会调用目标端点。
  • 授权刷新:当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调用脚本使用,不得展示给用户。
powershell
$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 引导解决问题:
发生以下异常情况时,请按照references/onboarding.md的指引解决问题:

异常情况

异常情况

  • 未配置API Key:环境变量未配置
    LINKFOX_AGENT_API_KEY
    ,也未配置
    LINKFOXAGENT_API_KEY
  • 响应401或402状态码
  • 响应提示积分或余额不足:消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值",或类似含义的内容。
  • 未配置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.
在每次调用高风险操作前,需单独请求用户用中文自然语言确认,仅用业务术语重述具体的订单/操作摘要。若上一条助手消息明确请求确认某一项特定高风险操作,用户回复“确认”即视为有效。“继续”“可以”“按上面来”等前期表述不得作为后续高风险操作的有效确认依据。不得要求用户输入英文参数名称。
用户用中文确认后,Agent调用脚本时必须添加
references/api.md
要求的内部安全字段。除非调试工具错误,否则不得在面向用户的确认文本中提及内部字段、请求字段名或后端默认值。

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.
  1. 运行
    authorized_stores.py
    ;仅当当前用户拥有ACTIVE且未过期的1688授权时,才可继续后续操作。
  2. 若未授权,运行
    authorize_url.py
    ,让用户完成OAuth授权,然后重新检查
    authorized_stores.py
    的结果。
  3. 若从图片开始,使用
    linkfox-1688-search-by-image
    获取
    offerId
  4. 依次运行
    sku.py
    receive_address_list.py
    order_preview.py
  5. 用业务术语展示商品、SKU/规格、数量、价格、运费、地址、总价及注意事项。
  6. 仅在用户单独用中文确认后,运行
    create_order.py
    ;内部添加所需安全字段,不得展示给用户。
  7. 仅在用户单独用中文确认后,运行
    payment_url.py
    ;内部传入已创建的订单ID,不得向用户展示请求字段名。
  8. 使用
    order_status.py
    logistics.py
    logistics_trace.py
    进行订单追踪。
  9. 仅在用户针对具体订单和操作单独确认后,才可使用
    cancel_order.py
    confirm_receive.py
    ;内部传入选定的1688订单ID。对于已支付订单,不得将取消订单描述为退款处理。
  10. 确认收货后,运行
    invoice_amount.py
    查询可开票金额及各订单是否可开票;直接传入返回的
    amount
    值(不得重新计算)。仅在用户单独用中文确认发票类型、抬头及金额后,运行
    invoice_apply.py
    ;内部传入
    confirmApplyInvoice=true
    及金额。按订单处理
    successList
    /
    failedList
    ;将
    INVOICE_ALREADY_APPLIED
    视为已开票,而非错误。

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.
  1. 当采购依赖OAuth授权时,需先展示授权状态。不得仅通过浏览器重定向就默认授权已完成。
  2. authorizedStores
    的输出是当前LinkFox用户的1688授权状态,不得描述为数据库中的所有店铺。
  3. 关于授权,仅告知用户授权是否可用或是否需要重新授权。不得展示token过期时间、有效期、刷新窗口或
    tokenExpiresAt
    等内部字段。
  4. 不得展示完整的API密钥、JWT、access token、refresh token、回调码、应用密钥、会话密钥或Authorization请求头。
  5. 用清晰的业务术语展示订单预览:商品、SKU/规格、数量、单价、商品总价、运费、收货地址、订单总价、买家留言及注意事项。
  6. 调用高风险操作前,需总结具体操作、关键ID、可用的金额/状态,然后请求用户用中文确认。不得展示内部布尔字段、请求字段名或实现细节。
  7. 展示收货地址时,需提供足够信息供用户安全选择,但避免不必要地重复完整手机号或敏感地址细节。
  8. 仅在返回
    costToken
    或等效成本字段时,才向用户报告该信息。

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.
  • 不得在此创建或调用图片搜索脚本;图片搜索功能归属于
    linkfox-1688-search-by-image
  • 不得将
    /alibaba1688/proxy/callback
    /alibaba1688/authorizeCallback
    或浏览器OAuth回调URL作为Skill能力对外暴露。
  • 不得要求用户提供1688 token、refresh token、回调码或密钥。OAuth token交换由MyERP和ecom-plat处理。
  • 不得查询后端数据库以获取授权状态,需使用
    authorizedStores
  • 不得自动重试写入操作或执行完整采购循环。
  • 不得使用
    _dataQuery_executeDynamicQuery
    获取实时采购响应。

User Expression & Scenario Quick Reference

用户表述与场景速查

Applicable -- 1688 procurement scenarios:
User SaysScenario
"查询我的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
适用场景 -- 1688采购相关场景:
用户表述场景
"查询我的1688授权店铺" / "show my authorized 1688 stores"授权状态检查
"生成1688授权链接" / "authorize my 1688 account"新OAuth授权
"查这个 offerId 的 SKU"SKU查询
"查1688收货地址"收货地址查询
"帮我预览1688订单"订单预览
"确认下单"高风险订单创建校验
"获取支付链接"高风险支付链接获取校验
"查1688订单状态/物流"订单追踪
"取消这个1688订单"高风险订单取消校验
"确认收货"高风险收货确认校验
"查1688可开票金额" / "这个订单能开发票吗"可开票金额查询
"给这个1688订单开发票" / "确认开票"高风险发票申请校验
不适用场景 -- 使用其他Skill或后端系统:
  • 基于图片的1688商品搜索 ->
    linkfox-1688-search-by-image
  • 基于关键词的1688货源搜索/排名 -> 使用现有1688搜索/排名Skill(若可用)
  • MyERP OAuth回调/代理回调处理 -> 后端服务,不属于Skill范畴
  • 直接修复token或手动输入1688 token -> 后端授权桥接服务

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.
当实际行为与本Skill不符、结果不符合用户意图、用户表达满意/不满意或存在可改进之处时,需自动检测并通过Feedback API上报反馈。按照
references/api.md
的指定方式调用Feedback API,不得中断用户操作流程。反馈内容不得包含API密钥、token、完整地址、手机号或支付链接。

如需更多高质量、专业的跨境电商Skill,请访问 LinkFox Skills