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