linkfox-1688-procurement

1688 采购工作流

此技能可帮助 LinkFox 用户执行经授权的 1688 采购操作：OAuth 状态检查、SKU 和地址查询、订单预览、受控创建订单、获取支付 URL、订单跟踪、物流查询、取消订单、确认收货，以及订单完成后的发票申请。

使用 linkfox-1688-search-by-image 进行基于图片的商品发现。此技能不包含图片搜索。

核心规则

• 每个脚本都需要通过 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 提供。
• 将工作流视为操作指南，而非全自动流程。不要仅根据先前的“继续”等说法创建订单、获取支付 URL、取消订单、确认收货或申请发票。
• 调用脚本时，请使用 references/api.md 中准确的内部请求字段名称。不要在面向用户的常规文本中显示这些字段名称。
• 面向用户时，只将普通 1688 采购作为采购模式。根据 references/api.md 在内部应用后端默认值；不要提及采购类型，也不要让用户选择。
• cancel_order.py 仅尝试取消 1688 订单，不用于退款或售后申请。对于已付款订单（包括已付款但未发货的订单），不要以取消订单作为替代方案；请告知用户，此 Skill 没有退款申请工具，退款和售后必须在 1688 上处理，除非后端新增相应功能。
• MCP 启用/停用只控制 MCP 暴露状态。这些脚本会直接调用工具网关的 HTTP 路由；若要完全停用某项能力，必须停用相应路由或后端操作。

多步骤采购前，请阅读 references/api.md 了解端点详情，并阅读 references/workflow.md。

工具

脚本	风险	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	高	是	获取支付 URL
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 调脚本使用，不要展示给用户。

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

常见工作流

1. 运行 authorized_stores.py；仅当当前用户拥有有效且未过期的 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 视为已开票，而非错误。

显示规则

1. 如果采购依赖 OAuth，首先显示授权状态。不要仅凭浏览器重定向就假定已授权。
2. authorizedStores 输出的是当前 LinkFox 用户的 1688 授权状态。不要将其描述为数据库中的所有店铺。
3. 对于授权，只告知用户当前是否可用，或是否需要重新授权。不要显示令牌过期时间、令牌有效期、刷新窗口或 tokenExpiresAt 等内部字段。
4. 绝不显示完整的 API 密钥、JWT、访问令牌、刷新令牌、回调代码、应用密钥、会话密钥或 Authorization 标头。
5. 使用清晰的业务术语展示订单预览：商品、SKU/规格、数量、单价、商品总额、运费、收货地址、订单总额、买家留言和警告。
6. 执行高风险调用前，概述确切操作、关键 ID，以及可用的金额/状态，然后请用户用中文确认。不要显示内部布尔字段、请求字段名称或实现细节。
7. 对于收货地址，提供足够的信息以便用户安全选择，但避免不必要地重复完整电话号码或敏感地址详情。
8. 仅在返回 costToken 或同类成本字段时才报告。

重要限制

• 不要在此处创建或调用图片搜索脚本；图片搜索应使用 linkfox-1688-search-by-image。
• 不要将 /alibaba1688/proxy/callback、/alibaba1688/authorizeCallback 或浏览器 OAuth 回调 URL 暴露为 Skill 能力。
• 不要要求用户提供 1688 令牌、刷新令牌、回调代码或密钥。OAuth 令牌交换由 MyERP 和 ecom-plat 处理。
• 不要查询后端数据库来查明授权状态。请使用 authorizedStores。
• 不要自动重试写入操作，也不要运行完整采购流程。
• 不要使用 _dataQuery_executeDynamicQuery 获取实时采购响应。

用户表达与场景速查

适用——1688 采购场景：

用户表达	场景
“查询我的1688授权店铺” / “show my authorized 1688 stores”	授权检查
“生成1688授权链接” / “authorize my 1688 account”	新建 OAuth 授权
“查这个 offerId 的 SKU”	SKU 查询
“查1688收货地址”	收货地址查询
“帮我预览1688订单”	订单预览
“确认下单”	高风险创建订单关卡
“获取支付链接”	高风险支付链接关卡
“查1688订单状态/物流”	订单追踪
“取消这个1688订单”	高风险取消关卡
“确认收货”	高风险确认收货关卡
“查1688可开票金额” / “这个订单能开发票吗”	可开票金额查询
“给这个1688订单开发票” / “确认开票”	高风险申请开票关卡

不适用——请使用其他技能或后端系统：

• 基于图片发现1688商品 -> linkfox-1688-search-by-image
• 基于关键词的1688采购/排名 -> 有可用的现有1688搜索/排名技能时使用
• MyERP OAuth 回调/代理回调处理 -> 后端服务，而非 Skill
• 直接修复令牌或手动输入1688令牌 -> 后端授权桥接

反馈

当实际行为与此技能不符、结果不符合用户意图、用户表达满意/不满意，或存在改进空间时，通过 Feedback API 自动检测并报告反馈。按照 references/api.md 中的说明调用 Feedback API，且不要打断用户的流程。反馈内容中不得包含 API 密钥、令牌、完整地址、电话号码或支付链接。

---

如需了解更多高质量、专业的跨境电商技能，请访问 LinkFox Skills。