linkfox-1688-procurement

协助用户完成已授权账号的 1688 采购履约,支持账号授权、收货地址与商品规格查询、订单预览、创建订单、支付链接、订单状态、物流、取消订单、确认收货及完成后的开票。适用于 1688 采购、下单、支付、物流与发票处理;不适用于以图找货、关键词选品、退款售后或手工修复令牌。

SKILL.md

GitHub

1688 采购与订单履约

适用范围

适用

用户希望使用自己的 1688 授权账号完成采购准备、订单履约或开票时,使用本技能。授权有效后各能力可按用户需求独立使用,流程是业务地图,不是一次性自动完成采购闭环的脚本。

场景速查

用户表达 查询场景
查我的 1688 授权账号,或生成授权链接 授权检查或发起授权。
查商品规格和我的收货地址 采购准备。
预览这批商品的采购费用 核对规格、数量、运费和订单总额。
确认下单、获取支付链接 针对具体订单分别确认并执行。
查订单状态、物流或物流轨迹 履约跟踪。
取消这个订单、确认收货 针对具体对象独立确认。
这个订单能开票吗、确认开票 先查金额与资格,再确认发票申请。

边界

以图找货交给 linkfox-1688-search-by-image;关键词找货交给已安装的对应搜索或榜单技能。本技能没有退款或售后申请能力,已付款订单的退款、退货或售后应在 1688 处理。OAuth 回调及令牌修复由后端完成。

接口清单

接口 端点 对应脚本 说明
生成授权链接(authorizeUrl) POST /alibaba1688/authorizeUrl scripts/authorize_url.py 授权账号展示名,启动 1688 OAuth。
查询已授权账号(authorizedStores) POST /alibaba1688/authorizedStores scripts/authorized_stores.py 检查当前用户授权状态。
查询收货地址(receiveAddressList) POST /alibaba1688/receiveAddressList scripts/receive_address_list.py 读取当前用户可用地址。
查询商品规格(sku) POST /alibaba1688/sku scripts/sku.py 读取规格、参考价格及库存。
下单预览(orderPreview) POST /alibaba1688/orderPreview scripts/order_preview.py 核验商品、数量、地址和费用。
创建订单(createOrder) POST /alibaba1688/createOrder scripts/create_order.py 独立确认后创建订单。
获取支付链接(paymentUrl) POST /alibaba1688/paymentUrl scripts/payment_url.py 独立确认后获取手动支付链接。
查询订单状态(orderStatus) POST /alibaba1688/orderStatus scripts/order_status.py 读取当前履约阶段。
查询物流(logistics) POST /alibaba1688/logistics scripts/logistics.py 读取物流单与承运信息。
查询物流轨迹(logisticsTrace) POST /alibaba1688/logisticsTrace scripts/logistics_trace.py 读取指定物流单轨迹。
确认收货(confirmReceive) POST /alibaba1688/confirmReceive scripts/confirm_receive.py 独立确认后确认收货。
取消订单(cancelOrder) POST /alibaba1688/cancelOrder scripts/cancel_order.py 独立确认后尝试取消未付款订单。
查询可开票金额(invoiceAmount) POST /alibaba1688/invoiceAmount scripts/invoice_amount.py 逐单查询开票资格和金额。
申请开票(invoiceApply) POST /alibaba1688/invoiceApply scripts/invoice_apply.py 独立确认后申请开票。

前置条件

配置 LinkFox 平台身份;采购前通过本技能检查当前用户的 1688 授权。除生成授权链接和查询授权账号外,脚本会在每次采购操作前检查授权,检查不通过时停止目标操作。具体条件与脚本兼容约定见 references/api.md。

采购流程

  1. 检查当前用户授权;不可用时生成授权链接供用户手动打开,完成后重新检查。浏览器跳转本身不能证明授权成功或失败。
  2. 用户从图片找货时先转交图搜技能,再回到本技能查询目标商品规格;已有商品编号则直接查规格。展示实际返回的规格、参考价格、起订量和库存,结合售卖单位及起批量让用户确定规格和数量;价格与库存仅作选择参考。
  3. 查询收货地址。多地址时请用户明确选择,不猜测默认地址;展示足以辨认的信息并减少敏感信息重复。
  4. 进行订单预览,展示商品、规格、数量、单价、商品总价、运费、地址、订单总额、买家留言及异常提示。核对全部预览分组与全部请求商品,检查预览明确通过且金额和商品行有效;失败或状态缺失时停止下单并展示上游提示。
  5. 复述本次订单摘要,在用户单独明确确认后创建订单;按接口定义核对并保留全部成功子订单号,再报告失败商品。多笔成功订单时兼容单订单号可能为空;部分成功不能整单重试,后续操作使用具体已确认的订单号。
  6. 获取支付链接也须单独确认,并明确本次包含哪些成功订单。创建订单成功不能代替获取支付链接的确认;支付链接仅供用户手动打开,不自动打开或支付。
  7. 按用户请求查询订单状态、物流和物流轨迹,不主动连续轮询。用户查看签收信息或询问状态,不等于确认收货。
  8. 取消前优先查询或确认订单状态:未付款订单可进入取消确认;已付款待发货、已发货或已完成订单转到 1688 退款售后;已取消订单无需重复取消。复述订单号、状态、原因及取消不等于退款,用户独立确认后才尝试取消。
  9. 确认收货前,复述具体订单和动作并取得独立确认。
  10. 订单完成后(建议确认收货后)先查可开票金额与资格;跳过不可开票的订单,可开票金额须原样传入申请,不自行计算或换算。复述订单号、发票类型、抬头和金额,取得独立确认后申请开票。逐单报告申请成功、失败或历史已开票;不自动联动多订单批量开票,也不申请红冲,红冲需联系商家。

执行方式

  • 直接调用接口:接口端点、完整参数、响应和错误码见 references/api.md。
  • 脚本调用(推荐):python <脚本路径> '<JSON 参数>' [--inline] [--save] [--no-save]。也可使用 --payload-env ENV_NAME 或 --payload-file path.json 读取 JSON;Windows 推荐这两种方式,避免 shell 转义破坏参数。
  • 请求约束:本工具每次调用为 0 算力/次 (限时)。避免无目的重复请求;用户要求刷新实时授权、价格、库存、订单状态或物流时,可按需再次查询。失败、空结果、参数不足或授权不足时停止,不自动换参数试探或轮询。需要继续查询时先明确查询目的与范围。
  • 实时数据:采购业务始终禁用响应缓存,授权、价格、库存、订单状态和物流以实时返回为准;写操作不得缓存或自动重放。--no-cache 可传入,但不改变这一行为。
$env:PAYLOAD = '{}'
python scripts/authorized_stores.py --payload-env PAYLOAD --inline

输出策略

  • 输出和保存的响应均递归脱敏密钥与令牌,并删除令牌过期时间字段。脱敏序列化后不超过 8000 字节:默认直接打印完整 JSON,不保存文件。
  • 超过 8000 字节:默认保存完整脱敏响应,标准输出展示摘要,包含顶层字段、状态、消息、实际返回的消耗字段、常见计数及最大列表的长度和前 3 项。
  • 保存路径为 <writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json。根目录依次选择 ACPX_WORKSPACES 的第一个工作区、当前工作目录、用户目录;禁止使用 /tmp 或系统临时目录,均不可写时报错。<session> 优先取 SESSION_ID,未提供时在进程内自动生成。
  • --save 或 LINKFOX_SKILL_SAVE_RESPONSE=1 强制保存;--no-save 或 LINKFOX_SKILL_NO_SAVE=1 禁止保存,且优先于强制保存与自动保存。环境变量也接受 true / yes。
  • --inline 强制打印完整脱敏 JSON,不隐含保存;保存仍由大小阈值和保存选项决定。

先通过标准输出判断数据是否足够。需要保存小响应时使用 --save;需要具体字段时,优先使用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需提取,避免将整份响应载入上下文。多订单处理必须读取完整子订单列表,不能只保留摘要展示的前 3 项。完整 CLI 与输出约定见 references/api.md。

执行规则

算力消耗预估

全部 14 个采购接口每次调用为 0 算力/次 (限时)。除生成授权链接和查询已授权账号外,脚本每次采购操作还会发起一次授权检查;该检查也适用此规则。仅在响应实际返回消耗字段时报告其值。

声明:算力消耗以实际扣除为准;如因需要调整算力消耗标准,恕不另行通知。最终解释权归 LinkFox 官方所有。

解决认证和算力问题

出现以下情况时,按 references/onboarding.md 的指引处理:

  • 未配置接口密钥:LINKFOX_AGENT_API_KEY 和 LINKFOXAGENT_API_KEY 均为空。
  • HTTP 状态码为 401 或 402。
  • 响应提示算力或余额不足、计费不足、配额超限、套餐到期或需要充值。英文错误消息也按其含义判断。

约束与建议

  • 逐次独立确认:创建订单、获取支付链接、取消订单、确认收货、申请开票均须在调用前取得中文自然语言的单独明确确认。刚刚复述了一个具体动作和对象后,用户紧接着回复“确认”有效;更早的“继续”“可以”“按上面来”不能授权后续动作。内部安全字段由 Agent 组装,不让用户输入英文字段名。
  • 使用业务语言:普通采购是面向用户的采购模式,不要求用户选择后台采购类型;确认文案只讲具体订单、动作、金额与状态,不展示内部请求字段或默认值。参数、默认值、确认字段及接口限制见 references/api.md。
  • 授权展示:只说明授权可用或需要重新授权,不展示令牌有效期、过期时间或刷新窗口。授权账号仅属于当前 LinkFox 用户,不是后台全库账号;不查数据库发现授权,也不向用户索取令牌、回调码或密钥。
  • 费用展示:预览是最终可购性、价格、运费与优惠的依据;按接口定义区分元和分,不混算。支付渠道有可读名称时展示名称,只有编码时原样展示,不猜测含义。消耗字段仅在实际返回时报告。
  • 创建结果:先保留完整脱敏响应和全部成功订单号,再报告部分失败;不把整次采购的商品或金额复制到每个子订单。创建成功但未取得订单号、超时或结果不确定时,先核对 1688 买家订单,禁止重复下单;字段和判断规则见接口定义,异常说明见 references/workflow.md。
  • 发票展示:用普通发票、专用发票、个人或企业抬头等业务名称向用户核对资料;企业开票的税号与专票资料要求见接口定义。不可只看批量顶层状态,历史已开票按“已开票”报告;开票成功不可在系统侧回滚。
  • 保护敏感信息:不展示完整 API Key、JWT、访问令牌、刷新令牌、会话密钥、应用密钥、回调码或认证头。地址和手机号仅展示选择所需信息;反馈不得包含上述秘密、完整地址、手机号或支付链接。
  • 异常处理:失败、空结果、参数不足或授权不足时停止自动试探,不自动更换参数、重试写入或完整执行采购闭环。额外查询遵循请求约束;采购结果不用动态数据库查询代替。
  • 运行边界:本技能不提供图搜或 OAuth 回调能力。MCP 停用与 HTTP 能力关闭的差异,以及少见采购异常的诊断见 references/workflow.md。

使用示例

准备采购并预览

用户:帮我看这件商品的规格,并预览采购费用。

检查授权,查询规格与地址,让用户明确数量、售卖单位及地址,展示预览和异常。需要创建订单时另行复述摘要并取得确认。

查看订单与取消未付款订单

用户:查一下这个订单的状态,我想取消。

核对状态并按采购流程分流;符合取消场景时复述对象和影响,取得独立确认后执行,说明实际结果。

查询可开票金额与申请开票

用户:这个已完成订单能开票吗?

先查询资格及金额,说明所需抬头资料;只有用户针对具体发票明确确认后才申请,逐单展示结果。

使用反馈

当技能有BUG,或技能描述有错误/疏漏/歧义/表述模糊,或技能结果与用户预期不符,或用户表达不满/赞扬,或发现其他可改进之处时,按 references/api.md#Feedback 的指引反馈,不要打断用户当前流程。


更多优质、专业的跨境电商技能,请访问 LinkFox Skill。