linkfox-1688-procurement

1688 購買ワークフロー

このスキルを使うと、LinkFox のユーザーは、認可済みの 1688 購買業務を実行できます。OAuth 状態の確認、SKU と住所の検索、注文のプレビュー、ガード付きの注文作成、支払い URL の取得、注文追跡、物流、キャンセル、受領確認、完了後の請求書申請に対応しています。

画像を使った商品検索には、linkfox-1688-search-by-image を使用してください。このスキルには画像検索は含まれていません。

基本ルール

• すべてのスクリプトで、LINKFOX_AGENT_API_KEY または LINKFOXAGENT_API_KEY から LinkFox プラットフォームの ID 情報を取得する必要があります。
• authorize_url.py は 1688 OAuth を開始し、authorized_stores.py は現在の LinkFox ユーザーの 1688 OAuth 状態を確認します。
• この 2 つの認可スクリプトを除き、すべての購買操作では、対象エンドポイントを呼び出す前にスクリプトレベルの authorizedStores 事前チェックを実行します。
• status=ACTIVE かつ expired=false のストアがない場合、対象エンドポイントは呼び出されません。
• 認可が有効であれば、ユーザーのリクエストに応じて購買ツールを個別に使用できます。ワークフローはガイドであり、必須の直線的なスクリプトではありません。画像検索は引き続き linkfox-1688-search-by-image で行います。
• ワークフローは自動化の全体ではなく、手引きとして扱ってください。「続けて」などの以前の発言を根拠に、注文を作成したり、支払い URL を取得したり、注文をキャンセルしたり、受領を確認したり、請求書を申請したりしないでください。
• スクリプトを呼び出す際は、references/api.md に記載された正確な内部リクエストフィールド名を使用してください。通常のユーザー向けの文章では、これらのフィールド名を表示しないでください。
• ユーザー向けの購買方法は、通常の 1688 購買のみとしてください。references/api.md に従ってバックエンドのデフォルトを内部で適用し、購買タイプについて言及したり、ユーザーに選択を求めたりしないでください。
• cancel_order.py は 1688 の注文のキャンセルを試みるだけです。返金やアフターサービスの申請ではありません。支払い済みの注文（支払い済み・未発送の注文を含む）については、回避策としてキャンセルを呼び出さないでください。このスキルには返金申請ツールがなく、バックエンドにその機能が追加されない限り、返金やアフターサービスは 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 は 24 時間のレスポンスキャッシュを行いません。認証、価格、在庫、注文状況、物流情報はリアルタイムの応答を正とし、リスクの高い書き込み操作はキャッシュしてはいけません。
• 認証制約：authorize_url.py と authorized_stores.py を除き、スクリプトは対象インターフェースを呼び出す前に、現在のユーザーに有効な ACTIVE 1688 認証があるかを自動で確認します。ACTIVE かつ有効期限内の認証がない場合、対象 endpoint は呼び出されません。
• 認証の更新：accessToken の有効期限が近い、または期限切れの場合、バックエンドがそのユーザー自身の refreshToken を使って自動更新します。authorizedStores または仕入れインターフェースの呼び出し時に更新が行われるため、Skill とユーザーが介入する必要はありません。refreshToken が空、無効、または更新に失敗した場合（authorizedStores が expired=true を返す場合）に限り、authorize_url.py で再認証が必要です。トークンの有効期間、期限切れ日時、更新期間など、内部の認証情報をユーザーに表示したり伝えたりしてはいけません。
• 高リスク操作の制約：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 を追加すると、全量を標準出力に強制的に出力します
• --save を追加すると、トークンなどの機密フィールドをマスキングして強制的に保存します
• --no-save を追加すると、レスポンスファイルの保存を禁止します

出力方針（スクリプトのデフォルト動作）：

• レスポンス本文が 8 KB 以下の場合：デフォルトではディスクに保存せず、マスキング済みの JSON 全体を標準出力に直接出力します。照会のたびに Skill ディレクトリへデータファイルが生成されるのを防ぎます。
• レスポンス本文が 8 KB を超える場合：デフォルトではマスキング済みのレスポンス全体を <writable-root>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-1688-procurement-<operation>-<timestamp>.json に書き込み、標準出力には概要のみを出力します。
• <writable-root> は、まず ACPX_WORKSPACES の最初のワークスペースを使用し、次にスクリプト実行時のカレントディレクトリを使用し、最後にユーザーディレクトリへフォールバックします。<session> には環境変数 SESSION_ID の値を使用し、設定されていない場合は自動生成します。/tmp への書き込みは禁止されています。
• --save を追加するか、LINKFOX_SKILL_SAVE_RESPONSE=1 を設定すると、保存を強制します。--no-save を追加するか、LINKFOX_SKILL_NO_SAVE=1 を設定すると、保存を禁止します。--inline に保存の意味は含まれません。

データ読み取りの推奨事項：まず標準出力の概要を確認し、それだけで十分か判断してください。レスポンス全体を保存する必要がある場合は、--save を追加してください。その後は、保存された JSON ファイルから必要なデータを jq または ConvertFrom-Json で抽出することを優先し、JSON 全体がコンテキストに入らないようにしてください。

認証と計算リソースの問題の解決

次の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常

• API Key 未設定：環境変数 LINKFOX_AGENT_API_KEY と LINKFOXAGENT_API_KEY のどちらも設定されていません。
• 401 または 402 のステータスコードが返された
• 計算リソースまたは残高不足を示すレスポンス：メッセージに「算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值」、または同様の意味の内容が含まれています。

高リスク操作の確認

高リスク操作を呼び出す直前に、毎回ユーザーへ個別に中国語の自然言語で確認を求め、注文や操作の内容を業務上の表現だけで正確に伝えてください。直前のアシスタントメッセージで特定の高リスク操作について明確に確認を求めている場合は、「确认」という返信を有効な確認として扱えます。それ以前の「继续」「可以」「按上面来」などの表現は、後続の高リスク操作に対する確認として認められません。ユーザーに英語のパラメーター名を入力させてはいけません。

ユーザーが中国語で確認した後、Agent はスクリプトの呼び出し時に references/api.md で指定されている内部の安全フィールドを追加する必要があります。ツールのエラーをデバッグする場合を除き、ユーザー向けの確認文で内部フィールド、リクエストフィールド名、バックエンドのデフォルト値に言及してはいけません。

一般的なワークフロー

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 はエラーではなく、発行済みとして扱います。

表示ルール

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授权店铺" / "認証済みの1688店舗を表示して"	認証の確認
"生成1688授权链接" / "1688アカウントを認証して"	新規 OAuth 認証
"查这个 offerId 的 SKU"	SKU の検索
"查1688收货地址"	受取先住所の検索
"帮我预览1688订单"	注文のプレビュー
"确认下单"	高リスクの注文作成ゲート
"获取支付链接"	高リスクの支払い URL ゲート
"查1688订单状态/物流"	注文の追跡
"取消这个1688订单"	高リスクのキャンセルゲート
"确认收货"	高リスクの受取確認ゲート
"查1688可开票金额" / "この注文は請求書を発行できますか"	請求書発行可能額の照会
"给这个1688订单开发票" / "請求書の発行を確認して"	高リスクの請求書発行申請ゲート

適用対象外 -- 別のスキルまたはバックエンドシステムを使用してください：

• 画像を使った1688商品の検索 -> linkfox-1688-search-by-image
• キーワードを使った1688商品の調達／ランキング -> 利用可能な既存の1688検索／ランキングスキルを使用
• MyERP OAuth コールバック／プロキシコールバックの処理 -> バックエンドサービスであり、スキルではありません
• トークンの直接修復、または1688トークンの手動入力 -> バックエンド認証ブリッジ

フィードバック

実際の動作がこのスキルと異なる場合、結果がユーザーの意図と一致しない場合、ユーザーが満足／不満足を表明した場合、または改善できる点がある場合は、フィードバックを自動検出し、Feedback API を通じて報告してください。ユーザーの操作を中断せず、references/api.md の指定に従って Feedback API を呼び出してください。フィードバック内容には API キー、トークン、住所全体、電話番号、支払い URL を含めないでください。

---

高品質でプロフェッショナルな越境 EC スキルをさらにご覧になるには、LinkFox Skills にアクセスしてください。