linkfox-walmart-wmtwin

沃师傅(WMTwin) 自動ログインと競合製品検索

このスキルは、WMTwin（沃师傅）向けに、自動ログイン、API 呼び出し、競合製品検索の機能を提供します。認証フローと、データの自動デコードを伴う競合製品検索を処理します。

コアコンセプト

沃师傅(WMTwin) は、Walmart の販売者向けツールプラットフォームです。このスキルは、自動ログイン、API 呼び出し、競合製品検索の機能を提供します。以下の機能が含まれます。

ログインと認証

• 自動ログイン管理: ログイン状態を確認し、ログインフローを自動的に実行します
• 画像認証: 人による確認が必要です。システムが画像をユーザーに表示します
• SMS 認証コード: 自動送信されます。ユーザーが認証コードを入力してログインを完了します
• セッションの永続化: ログイン成功後にセッションを保存し、再ログインを回避します
• 複数アカウントのサポート: 電話番号ごとに個別にセッションを管理します

競合製品検索

• キーワード検索: キーワードで Walmart プラットフォーム上の競合製品を検索します
• WFS フィルター: Walmart Fulfillment Services の商品だけを検索します
• 販売数の範囲: 最小／最大販売数で商品を絞り込みます
• ページネーション検索: 大量のデータをページ単位で取得できます
• 自動デコード: すべてのエンコード文字を自動的に元のデータに変換します
• 自動ログイン: ログイン状態を確認し、未ログインの場合はユーザーをログインへ誘導します
• セッション管理: ログイン状態を自動的に保存・読み込みし、複数アカウントに対応します

認証フロー

1. 尝试密码登录
   ├─ 成功 → 保存session，完成
   └─ 失败 (code: 1101) → 需要验证码登录

2. 获取图形验证码
   └─ 展示图片给用户，等待人工识别

3. 发送短信验证码
   └─ 使用图形验证码答案调用发送API

4. 短信验证码登录
   └─ 用户提供短信验证码，完成登录

5. 保存Session
   └─ Session保存在 /tmp/linkfox_wmtwin_sessions/{phone}.json

API の重要なルール

レスポンス形式

沃师傅 の API レスポンスには特殊な形式があるため、注意が必要です。

成功レスポンス:

{
  "code": 1,           // 注意：1表示成功，不是0！
  "msg": "成功",
  "data": {...}
}

失敗レスポンス:

{
  "code": 1101,        // 其他code表示失败
  "msg": "错误信息",
  "data": null
}

成功と判定する条件:

def is_success(result):
    return result.get('code') in [0, 1] and result.get('msg') in ['成功', '操作成功']

よくあるエラーコード

コード	意味	対処方法
1	成功	通常どおり処理します
1101	環境異常。認証コードによるログインが必要です	SMS ログインフローを実行します
1008	認証コードが正しくありません	認証コードを再取得します
1020	SMS 認証コードが正しくありません	認証コードを確認するか、再送信します

API エンドポイント

認証 API

エンドポイント	メソッド	説明
/api/v1/auth/login	POST	パスワードログイン
/api/v1/auth/captcha	GET	画像認証を取得
/api/v1/auth/sms-code	POST	SMS 認証コードを送信
/api/v1/auth/sms-login	POST	SMS 認証コードでログイン

詳しい API ドキュメントについては、references/api.md を参照してください。

使用方法

ログイン手順

# 步骤1: 开始登录，获取验证码
python3 scripts/wmtwin_login.py login 13699998888 111111

# 系统会保存验证码图片: /tmp/linkfox_wmtwin_captcha.png
# 用户查看图片并提供答案（例如：24）

# 步骤2: 提供验证码，发送短信
python3 scripts/wmtwin_login.py continue 24

# 系统发送短信到用户手机
# 用户提供短信验证码（例如：123456）

# 步骤3: 完成登录
python3 scripts/wmtwin_login.py continue sms 123456

# 登录成功，session保存在:
# /tmp/linkfox_wmtwin_sessions/13699998888.json

ログイン状態の確認

python3 scripts/wmtwin_login.py check 13699998888

API の呼び出し

# GET请求
python3 scripts/wmtwin_login.py api 13699998888 /user/info

# POST请求
python3 scripts/wmtwin_login.py api 13699998888 /order/create POST '{"item":"test"}'

セッションの操作

セッションの保存先

• 場所: /tmp/linkfox_wmtwin_sessions/{phone}.json
• 形式: Cookie、ヘッダー、タイムスタンプを含む JSON
• 自動読み込み: API 呼び出し時に自動的に読み込まれます

セッションの構造

{
  "cookies": {
    "wal": "encoded_session_token"
  },
  "headers": {
    "User-Agent": "...",
    "Content-Type": "application/json"
  },
  "saved_at": "2024-04-28T16:28:08.987745"
}

Cookie の処理

重要: 沃师傅 は同じ名前の Cookie を重複して返すため、特別な処理が必要です。

# 正确方式：避免重复cookie错误
cookies_dict = {}
for cookie in session.cookies:
    cookies_dict[cookie.name] = cookie.value  # 自动覆盖重复项

パスワードの暗号化

パスワードは RSA で暗号化して送信します。

• アルゴリズム: RSA 1024-bit + PKCS1 v1.5 padding
• エンコード: Base64
• 通信: HTTPS

from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_v1_5
import base64

PUBLIC_KEY = """-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDEICVdtxqOCBwHN9a/+YxeXz/B
ZGfduADPfV9dUTW+hGVpIcXU6kBkUdlhVPPdO6n7irK7dxD56m1xG1EmV2RICsvy
W2Y7JVyRRVhun92urbw7TtBcMCCB5SzLI+x1LBUr98SMkMNRQxcnYPkrPj0qGI4v
MC52dJ7z3n6aMf3XoQIDAQAB
-----END PUBLIC KEY-----"""

def encrypt_password(password):
    public_key = RSA.import_key(PUBLIC_KEY)
    cipher = PKCS1_v1_5.new(public_key)
    encrypted_bytes = cipher.encrypt(password.encode('utf-8'))
    return base64.b64encode(encrypted_bytes).decode('utf-8')

データのデコード

沃师傅 API が返す文字列では、Unicode U+0100–U+024F の範囲のエンコード文字がよく使われます（環境によっては文字化けのように見えます）。このスキルは scripts/wmtwin_complete_decoder.py を使って自動的にデコードします。ドキュメント内の例では、元のエンコード文字を直接表示せず、すべて U+XXXX コードポイントで表記します。

エンコード範囲

沃师傅 は4つのエンコード範囲を使用しており、2種類のエンコード方式に対応しています。

エンコード範囲	Unicode	マッピング	用途	方式
323	1文字	小数点 .	価格の小数点	共通
324-333	10文字	数字 0-9	単純な数値（レビュー数など）	API 方式
334-385	52文字	A-Z, a-z	販売者名、会社名	API 方式
528	1文字	小数点 .	価格の小数点	ドキュメント方式
529-538	10文字	数字 0-9	数字	ドキュメント方式
539-564	26文字	大文字 A-Z	大文字	ドキュメント方式
565-590	26文字	小文字 a-z	小文字	ドキュメント方式

デコード例

# 编码示例
'U+0146' (326) → '2'                    # 评论数 (324-333)
'U+0152U+015FU+0156U+0150-U+0152U+0165U+015DU+015FU+0152U+0160U+0160' → 'ERIC-EXPRESS'      # 卖家名 (334-385)
'$U+0146U+0145U+0145U+0144U+0143U+0148U+0172+' → '$2110.4k+'           # 销售额 (323+324-333)
'U+0213' (531) → '2'                    # 数字 (529-538)
'U+021FU+022CU+0223U+021D-U+021FU+0232U+022AU+022CU+021FU+022DU+022D' → 'ERIC-EXPRESS'    # 卖家名 (539-564)
'$U+0213U+0212U+0212U+0211U+0210U+0215U+023F+' → '$2110.4k+'          # 销售额 (528-590)

デコーダーの使用方法

完全デコーダー: scripts/wmtwin_complete_decoder.py

# 解码JSON文件
python3 scripts/wmtwin_complete_decoder.py input.json -o output.json

# 从标准输入解码
cat input.json | python3 scripts/wmtwin_complete_decoder.py - -o output.json

コード内での使用:

from scripts.wmtwin_complete_decoder import decode_json, decode_json_file

# 方法1: 解码JSON对象
import json
with open('input.json') as f:
    data = json.load(f)
decoded_data = decode_json(data)

# 方法2: 直接解码文件
decoded_data = decode_json_file('input.json', 'output.json')

デコード対象フィールド

デコーダーは、JSON 内のすべての文字列フィールドを再帰的にデコードします。対象には以下が含まれます。

基本フィールド:

• number_of_reviews: レビュー数
• additional_offer_count: 販売者数
• sales_volume: 販売数
• sales_amount: 売上額

販売者フィールド (sellers):

• display_name: 販売者の表示名
• name: 会社名
• seller_reviews: 販売者のレビュー数
• seller_rating: 販売者の評価

販売傾向 (sales_trends):

• sales_amount.label: 売上額のラベル（例: $2110.4k+）
• sales_volume.label: 販売数のラベル（例: 197.0k+）
• month_sales_growth: 月間成長率
• gross_profit: 粗利益
• gross_profit_margin: 粗利益率

データソース

データソースによって、使用されるエンコード方式が異なる場合があります。

• API のリアルタイムデータ: 323-385 の範囲を使用（方式A）
• 参照ファイル: 528-590 の範囲を使用（方式B）
• デコーダーの対応: どちらの方式にも対応

検証

デコードが完全に行われたことを確認します。

# 检查是否还有编码字符
encoded_ranges = [(323, 323), (324, 333), (334, 385), (528, 590)]

def has_encoded_chars(text):
    if not isinstance(text, str):
        return False
    for char in text:
        code = ord(char)
        for start, end in encoded_ranges:
            if start <= code <= end:
                return True
    return False

# 检查解码后的数据
import json
with open('decoded.json') as f:
    data = json.load(f)

# 递归检查所有字符串字段
def check_decoded(obj):
    if isinstance(obj, dict):
        return all(check_decoded(v) for v in obj.values())
    elif isinstance(obj, list):
        return all(check_decoded(item) for item in obj)
    elif isinstance(obj, str):
        return not has_encoded_chars(obj)
    return True

is_fully_decoded = check_decoded(data)
print(f"完全解码: {is_fully_decoded}")

会話中の使用方法

ユーザーが沃师傅または関連キーワードに言及すると、このスキルが自動的に起動します。次の手順に従ってください。

1. ログイン状態を確認:

   from scripts.wmtwin_login import load_session
   session = load_session(phone)
   

2. 未ログインの場合は、ユーザーを案内:

   • ログインを開始します
   • CAPTCHA 画像をユーザーに表示します
   • CAPTCHA の回答をユーザーに尋ねます
   • SMS 認証コードを送信します
   • SMS 認証コードをユーザーに尋ねます
   • ログインを完了します

3. セッションを使って API を呼び出す:

   from scripts.wmtwin_login import call_api
   result = call_api(phone, endpoint, method, data)
   

ベストプラクティス

1. API 呼び出しの前に必ずログイン状態を確認する - 401/403 エラーを回避します
2. CAPTCHA 画像をユーザーに表示する - 画像 CAPTCHA には人間による入力が必要です
3. わかりやすいエラーメッセージ - 各ステップでユーザーを案内します
4. セッションの再利用 - セッションが存在する場合は、繰り返しログインしないでください
5. 複数アカウントのサポート - 電話番号ごとに独立したセッションを使用します

デバッグ

CAPTCHA の表示

# macOS
open /tmp/linkfox_wmtwin_captcha.png

# Or in conversation
"帮我查看验证码图片"

セッションの表示

cat /tmp/linkfox_wmtwin_sessions/13699998888.json | python3 -m json.tool

セッションのクリア

rm /tmp/linkfox_wmtwin_sessions/13699998888.json

セキュリティ

• ✅ 送信前にパスワードを RSA で暗号化
• ✅ HTTPS 通信のみ
• ✅ 平文のパスワードを保存しない
• ✅ ローカルでセッションを保存
• ✅ セッションのクリーンアップに対応

パフォーマンス

操作	時間
パスワードログインの試行	< 2s
CAPTCHA の取得	< 1s
SMS コードの送信	< 2s
SMS ログイン	< 2s
API 呼び出し（ログイン済み）	< 2s

制限事項

• CAPTCHA の認識：人間による入力が必要です（自動認識にはまだ対応していません）
• SMS 認証：ユーザーが SMS コードを手動で入力する必要があります
• セッションの有効期限：セッションが期限切れになると、再ログインが必要です

競合商品の検索

使用方法

Walmart の競合商品を検索します。複数の絞り込み条件に対応しています。自動ログイン機能を統合しているため、ログイン状態を手動で管理する必要はありません。

✨ 自動ページネーション機能

新機能：リクエストするデータ件数が API の1ページあたりの上限（50件）を超える場合、スクリプトが自動的に複数ページを取得し、結果を結合します。

# 自动获取100条数据（自动查询2页）
python3 scripts/wmtwin_search_competitors.py \
    --keyword "iphone case" \
    --phone 15625238480 \
    --page-size 100 \
    -o results.json

機能：

• ✅ リクエスト件数が1ページあたりの上限（50件）を超えているか自動で検出
• ✅ 目標件数に達するまで複数ページを自動で取得
• ✅ 複数ページの結果を1つの JSON ファイルに自動で結合
• ✅ 取得状況（取得済み件数／目標総数）をリアルタイムで表示
• ✅ すべての絞り込み条件に対応

自動ログインの流れ

検索 API を呼び出すと、次の処理が自動的に行われます。

1. 有効なログインセッションがあるか確認します
2. セッションがない場合は、ログインするようユーザーに案内します
3. ログインに成功すると、セッションを自動的に保存します
4. 次回は、保存済みのセッションを自動的に読み込みます
5. セッションの期限が切れている場合は、自動的に再ログインします

Python コード

from scripts.wmtwin_search_competitors import WMTwinCompetitorSearch

# 创建搜索客户端（提供手机号会自动加载已有登录）
client = WMTwinCompetitorSearch(phone="13699998888")

# 方法1: 使用参数字典（自动检查登录）
params = {
    "keyword": "iphone case",
    "is_wfs": True,
    "min_sales_volume": 200,
    "max_sales_volume": 800,
    "min_sales_amount": 200,
    "max_sales_amount": 800,
    "min_number_of_reviews": 50,
    "max_number_of_reviews": 100,
    "min_average_rating": 1.0,
    "max_average_rating": 5.0,
    "min_price": 1.0,
    "max_price": 10.0,
    "seller_name": "ERIC-EXPRESS",
    "brand": "Simyoung",
    "page": 1,
    "pageSize": 10
}
results = client.search_from_params(params)

# 方法2: 直接调用（自动检查登录）
results = client.search_competitors(
    keyword="iphone case",
    is_wfs=True,
    min_sales_volume=200,
    max_sales_volume=800,
    min_sales_amount=200,
    max_sales_amount=800,
    min_number_of_reviews=50,
    max_number_of_reviews=100,
    min_average_rating=1.0,
    max_average_rating=5.0,
    min_price=1.0,
    max_price=10.0,
    seller_name="ERIC-EXPRESS",
    brand="Simyoung",
    page=1,
    page_size=10
)

# 方法3: 提供登录信息（首次登录）
results = client.search_competitors(
    keyword="iphone",
    phone="13699998888",
    password="your_password",  # 可选，不提供会提示输入
    is_wfs=True
)

# 方法4: 自动分页获取大量数据（推荐）
results = client.search_multiple_pages(
    total_count=100,  # 自动查询多页直到获取100条
    keyword="iphone case",
    phone="15625238480",
    is_wfs=True,
    min_sales_volume=200
)
print(f"共获取 {len(results['data']['list'])} 条数据")

# 使用解码后的数据
for product in results['data']['list']:
    print(f"产品: {product['title']}")
    print(f"价格: {product['price']}")
    print(f"卖家: {product['sellers'][0]['display_name']}")
    print(f"销量: {product['sales_trends'][0]['sales_volume']['label']}")

コマンドライン

# 基本搜索（会自动检查登录，需要时提示登录）
python3 scripts/wmtwin_search_competitors.py --keyword "iphone"

# 提供手机号（自动加载已有登录）
python3 scripts/wmtwin_search_competitors.py --keyword "iphone" --phone 13699998888

# 完整参数（自动管理登录）
python3 scripts/wmtwin_search_competitors.py \
    --keyword "iphone case" \
    --phone 13699998888 \
    --seller-name "ERIC-EXPRESS" \
    --brand "Simyoung" \
    --is-wfs \
    --min-sales 200 \
    --max-sales 800 \
    --min-sales-amount 200 \
    --max-sales-amount 800 \
    --min-reviews 50 \
    --max-reviews 100 \
    --min-rating 1.0 \
    --max-rating 5.0 \
    --min-price 1.0 \
    --max-price 10.0 \
    --page 1 \
    --page-size 10

# 模拟模式（无需登录，用于测试）
python3 scripts/wmtwin_search_competitors.py --keyword "iphone" --mock

# 从 JSON 文件读取参数
python3 scripts/wmtwin_search_competitors.py --from-json params.json --phone 13699998888

# 保存结果（自动保存原始和解码两个文件）
python3 scripts/wmtwin_search_competitors.py --keyword "iphone" --phone 13699998888 -o results.json
# 这将保存：
#   - results_raw.json (原始编码数据)
#   - results.json (解码后的数据)

重要な注意事項：

• -o パラメーターを使ってファイルを保存すると、2つのファイルが自動的に保存されます。
  • <filename>_raw.json - 元のエンコードデータ（API から直接返されたデータ）
  • <filename>.json - デコード済みデータ（すべての文字をデコード済み）
• 以降の操作では、常にデコード済みのファイルを使用します
• デコードは自動で行われるため、手動操作は不要です

検索パラメーター

パラメーター名	型	必須	説明	例
keyword	string	はい	検索キーワード	"iphone"
is_wfs	boolean	いいえ	WFS 商品のみを検索	true
min_sales_volume	integer	いいえ	最小販売数	4000
max_sales_volume	integer	いいえ	最大販売数	90000
min_sales_amount	integer	いいえ	最小売上額	200
max_sales_amount	integer	いいえ	最大売上額	800
min_number_of_reviews	integer	いいえ	最小レビュー数	50
max_number_of_reviews	integer	いいえ	最大レビュー数	100
min_average_rating	float	いいえ	最低評価（1-5）	1.0
max_average_rating	float	いいえ	最高評価（1-5）	5.0
min_price	float	いいえ	最低価格	1.0
max_price	float	いいえ	最高価格	10.0
seller_name	string	いいえ	販売者名	"ERIC-EXPRESS"
brand	string	いいえ	ブランド	"Simyoung"
page	integer	いいえ	ページ番号（1から開始）	1
pageSize	integer	いいえ	1ページあたりの件数	10

返却データの構造

返却データの構造は、ログイン後にほかの API を呼び出した場合と同じで、商品リスト、販売者情報、販売データなどが含まれます。エンコードされた文字はすべて自動的にデコードされます。

詳細なデータ構造とフィールドの説明については、references/competitor_search.md を参照してください。

自動デコード

ウォーシーフーでは Unicode 文字エンコードを使ってデータをエンコードしています。このツールはデータを自動的にデコードします。

エンコード例（コードポイント）	デコード結果	種類
U+021F…（販売者名）	ERIC-EXPRESS	販売者名
U+0212 U+0213…	$12.37	価格
U+0213 U+0211 U+0211 +	200+	数量
U+0213 U+0212…	$2110.4k+	売上額

よくある使用例

# 1. 搜索高销量产品
results = client.search_competitors(
    keyword="phone case",
    min_sales_volume=10000,
    page_size=50
)

# 2. 只搜索 WFS 商品
results = client.search_competitors(
    keyword="iphone",
    is_wfs=True
)

# 3. 特定销量区间
results = client.search_competitors(
    keyword="charger",
    min_sales_volume=5000,
    max_sales_volume=50000
)

# 4. 按评论数和评分筛选
results = client.search_competitors(
    keyword="iphone case",
    min_number_of_reviews=50,
    max_number_of_reviews=100,
    min_average_rating=4.0,
    max_average_rating=5.0
)

# 5. 按价格范围筛选
results = client.search_competitors(
    keyword="phone charger",
    min_price=5.0,
    max_price=20.0
)

# 6. 按卖家和品牌筛选
results = client.search_competitors(
    keyword="iphone case",
    seller_name="ERIC-EXPRESS",
    brand="Simyoung"
)

# 7. 综合筛选（多条件组合）
results = client.search_competitors(
    keyword="iphone case",
    is_wfs=True,
    min_sales_volume=200,
    max_sales_volume=800,
    min_price=1.0,
    max_price=10.0,
    min_number_of_reviews=50,
    max_number_of_reviews=100,
    min_average_rating=1.0,
    max_average_rating=5.0,
    seller_name="ERIC-EXPRESS",
    brand="Simyoung",
    page=1,
    page_size=10
)

# 8. 分页获取所有数据
all_products = []
page = 1
while True:
    results = client.search_competitors(
        keyword="iphone",
        page=page,
        page_size=50
    )
    products = results['data']['list']
    if not products:
        break
    all_products.extend(products)
    page += 1

コマンドラインの使用例

# 基本搜索
python3 scripts/wmtwin_search_competitors.py --keyword "iphone case" --phone 15625238480

# 多条件筛选
python3 scripts/wmtwin_search_competitors.py \
    --keyword "iphone case" \
    --phone 15625238480 \
    --seller-name "ERIC-EXPRESS" \
    --brand "Simyoung" \
    --is-wfs \
    --min-sales 200 \
    --max-sales 800 \
    --min-sales-amount 200 \
    --max-sales-amount 800 \
    --min-reviews 50 \
    --max-reviews 100 \
    --min-rating 1.0 \
    --max-rating 5.0 \
    --min-price 1.0 \
    --max-price 10.0 \
    --page 1 \
    --page-size 10 \
    -o results.json

参考資料

• API ドキュメント：references/api.md を参照
• 競合商品検索 API：references/competitor_search.md を参照
• 自動ログインガイド：AUTO_LOGIN.md を参照
• 競合商品検索クイックスタート：COMPETITOR_SEARCH.md を参照
• ログインスクリプト：scripts/wmtwin_login.py を参照
• 検索スクリプト（自動ログイン機能付き）：scripts/wmtwin_search_competitors.py を参照
• デコーダー：scripts/wmtwin_complete_decoder.py を参照
• デコードガイド：DECODING.md を参照
• 自動ページネーション：AUTO_PAGING.md を参照

大きなレスポンスの処理

エージェントのコンテキストがあふれないように、レスポンスをディスクに保存し、必要なフィールドだけを抽出します。

python scripts/response_io.py run --script scripts/wmtwin_complete_decoder.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

--out-dir は、Git の作業ツリーの外（Unix では /tmp/...、Windows では %TEMP%/... など）に指定してください。保存されたレスポンスには、個人を特定できる情報、料金情報、認証に関する機密データが含まれる場合があります。コミットしないでください。ファイルは自動削除されないため、作業が終わったら削除してください。

このスキルには複数のエントリースクリプトがあります：wmtwin_complete_decoder.py、wmtwin_login.py、wmtwin_search_competitors.py。必要なスクリプトを選ぶには、--script scripts/<name>.py を渡してください。

run はレスポンス全体をファイルに書き込み、スキーマのプレビューとファイルパスのみを出力します。read は指定したフィールドを抽出します。スライスには --limit/--offset、出力形式の指定には --format json|jsonl|csv|table を使用します。

この方法を選ぶ場面 — たとえば、次のようなレスポンスの特徴をもとに判断してください。

• レコードあたりのフィールド数が多い、または不要なフィールドが含まれる
• バッチ／ページネーションされた結果（1 回の呼び出しで複数の項目が返される）
• 長文フィールド（説明、レビュー、HTML、時系列データ）
• すぐに消費するのではなく、後続のステップで出力を再利用する

小規模で一度だけ使用するレスポンスの場合は、メインスクリプトを直接呼び出しても問題ありません。

⚠️ プレビューは、スキーマとサンプルを切り詰めたものであり、データ全体ではありません。フィールド単位の判断が必要な場合は、保存されたファイルを read で読み取ってください。