xianyu-openclaw

name	xianyu-openclaw
description	闲鱼数字商品客服和自动发货技能，支持拉取会话、查询订单、自动发货、补发、风险升级。 Use when: 需要在闲鱼场景中处理售前咨询、已付款发货、补发、退款投诉升级。 NOT for: 自动议价、绕过付款直接发货、处理高风险纠纷结论判定。

Xianyu OpenClaw Skill

运行环境：Python 3.11+；mock 模式无需额外依赖；真实模式需 pip install playwright 并执行 playwright install chromium。 默认为 mock 模式（XIANYU_MOCK_MODE=true），数据存储在 assets/data/*.json。

When to Run

• 需要查询闲鱼未读会话
• 买家已付款，需要自动发货或补发数字商品
• 买家提到退款、投诉、平台介入，需要升级人工
• 本地联调时模拟买家消息

Workflow

0. 初始化（首次使用）

重置 mock 数据（将 seeds 复制到 data）：

python scripts/reset_data.py

真实模式——保存登录态（仅需运行一次）：

python scripts/browser_login.py

---

1. 拉取未读会话

python scripts/pull_inbox.py --limit 5

返回按 last_message_at 倒序的会话列表。取第一条获得 session_id，进入步骤 2。

---

2. 获取会话上下文

python scripts/get_conversation.py --session-id <session_id> --limit 20

返回 messages 数组和 item_context（商品信息），用于判断买家意图。

---

3. 风险评估

python scripts/evaluate_risk.py --session-id <session_id>

• 返回 need_human: true → 跳到步骤 7（升级人工）
• 返回 need_human: false → 根据买家意图进入步骤 4 / 5 / 6

---

4. 售前咨询 → 搜索 FAQ 并回复

python scripts/search_faq.py --session-id <session_id> --query "<买家问题关键词>" --limit 3
python scripts/send_message.py --session-id <session_id> --message "<FAQ答案>"

---

5. 已付款 → 查询订单并发货

python scripts/find_order.py --session-id <session_id>
python scripts/deliver_order.py --order-id <order_id>
python scripts/send_message.py --session-id <session_id> --message "<发货结果消息>"

发货幂等：相同 order_id 多次调用只发一次，返回首次 payload（idempotent: true）。

---

6. 补发（链接失效 / 兑换码无效）

python scripts/resend_delivery.py --order-id <order_id> --reason link_expired
python scripts/send_message.py --session-id <session_id> --message "<新链接或兑换码>"

--reason 可选值：link_expired | code_invalid | manual_request

---

7. 升级人工工单

python scripts/escalate_ticket.py \
  --session-id <session_id> \
  --reason refund_request \
  --summary "<问题摘要>" \
  [--order-id <order_id>]

--reason 可选值：refund_request | platform_intervention | complaint | other

---

完整决策流程

pull_inbox → get_conversation → evaluate_risk
  ├─ low risk + 售前咨询  → search_faq → LLM generate → send_message
  ├─ low risk + 已付款    → find_order → deliver_order → send_message
  ├─ low risk + 补发请求  → resend_delivery → send_message
  └─ high risk            → escalate_ticket

AI 自动编排（一键触发）

# 对单个会话执行全自动决策 + 回复
python scripts/auto_reply.py --session-id s_001

# 预览决策但不发送（调试用）
python scripts/auto_reply.py --session-id s_001 --dry-run

持续监听新消息

# 每 30 秒轮询一次（默认间隔）
python scripts/watch_inbox.py

# 自定义间隔（秒）
python scripts/watch_inbox.py --interval 10

# 单次执行（--interval 0）
python scripts/watch_inbox.py --interval 0

# 调试模式：只打印决策不发送
python scripts/watch_inbox.py --dry-run

---

Script 速查表

脚本	用途	参数
reset_data.py	重置 mock 数据	—
browser_login.py	保存真实登录态（仅实模式）	—
pull_inbox.py	拉取未读会话	--limit（可选，默认10）
get_conversation.py	获取会话消息上下文	--session-id（必填）--limit（可选）
evaluate_risk.py	风险评估	--session-id（必填）
search_faq.py	搜索商品 FAQ	--session-id（必填）--query（必填）--limit（可选）
send_message.py	发送消息	--session-id（必填）--message（必填）
find_order.py	查询订单	--session-id 或 --buyer-id 或 --item-id（三选一）
deliver_order.py	自动发货（幂等）	--order-id（必填）
resend_delivery.py	补发	--order-id（必填）--reason（必填）
escalate_ticket.py	升级人工工单	--session-id（必填）--reason（必填）--summary（必填）--order-id（可选）
simulate_message.py	模拟买家消息（本地联调）	--session-id（必填）--message（必填）
auto_reply.py	AI 自动回复（全流程编排）	--session-id（必填）--dry-run（可选）
watch_inbox.py	持续监听并自动回复	--interval（可选）--limit（可选）--dry-run（可选）

---

Example Commands

# ① 重置数据
python scripts/reset_data.py

# ② 拉取会话
python scripts/pull_inbox.py --limit 2

# ③ 模拟买家发消息后再查看会话
python scripts/simulate_message.py --session-id s_001 --message "链接失效了"
python scripts/get_conversation.py --session-id s_001

# ④ 风险评估 → 发货
python scripts/evaluate_risk.py --session-id s_001
python scripts/find_order.py --session-id s_001
python scripts/deliver_order.py --order-id o_001
python scripts/send_message.py --session-id s_001 --message "已为你发货，请查收。"

# ⑤ 补发
python scripts/resend_delivery.py --order-id o_001 --reason link_expired
python scripts/send_message.py --session-id s_001 --message "已补发，新链接请查收。"

# ⑥ 升级人工
python scripts/escalate_ticket.py --session-id s_001 --reason refund_request --summary "买家投诉退款"

# ⑦ AI 一键自动回复（决策 + 发送）
python scripts/auto_reply.py --session-id s_001
python scripts/auto_reply.py --session-id s_001 --dry-run  # 只预览不发送

# ⑧ 持续监听（生产运行方式）
python scripts/watch_inbox.py --interval 30

Output Format

所有脚本返回统一 JSON：

{
  "ok": true,       // boolean - 是否成功
  "data": { ... }   // object/array - 业务数据
}
// 失败时：
{
  "ok": false,
  "error": "错误描述..."
}

各脚本的 data 结构

pull_inbox.py

[
  {
    "session_id": "s_001",
    "buyer_id": "b_001",
    "buyer_name": "小王",
    "item_id": "item_123",
    "unread_count": 1,
    "last_message_at": "2026-03-30T10:00:00Z"
  }
]

get_conversation.py

{
  "session_id": "s_001",
  "messages": [
    { "role": "buyer",  "content": "这个适合零基础吗？" },
    { "role": "seller", "content": "适合，从基础讲起。" }
  ],
  "item_context": { "item_id": "item_123", "title": "Python 入门电子书" }
}

evaluate_risk.py

{ "level": "low", "need_human": false, "hits": [] }

search_faq.py

[
  { "question": "适合零基础吗？", "answer": "适合，无需编程经验。", "score": 12 }
]

send_message.py

{ "session_id": "s_001", "message_id": "s_001-5", "sent_at": "2026-03-30T10:10:00Z" }

find_order.py

[
  {
    "order_id": "o_001",
    "sku": "ebook_python_001",
    "amount": 29.9,
    "payment_status": "paid",
    "delivery_status": "pending",
    "order_status": "paid",
    "created_at": "2026-03-30T10:05:00Z"
  }
]

deliver_order.py

{
  "order_id": "o_001",
  "delivery_status": "success",
  "message_to_buyer": "你购买的是《Python 入门电子书》\n下载链接：https://...",
  "idempotent": false
}

resend_delivery.py

{
  "order_id": "o_001",
  "delivery_status": "resent",
  "attempt_no": 2,
  "message_to_buyer": "已为你补发《Python 入门电子书》下载链接：https://..."
}

escalate_ticket.py

{ "ticket_id": "T-A1B2C3D4E5", "status": "open", "created_at": "2026-03-30T10:20:00Z" }