Xianyu Ops

xianyu-ops — 工具说明

本文是 expert-bd 专家包内的工具说明书，不独立出现在技能列表中。由相关 Workflow 指引调用。

通过 camoufox-cli 持久化 session xianyu（一个且只有一个持久化 session，fail-first 队列：同 session 已有命令在跑时新命令直接 fail）在闲鱼（goofish.com）上完成商品搜索、详情查看、私信管理。

输入：搜索关键词（+ 可选价格区间 / 地区筛选）、商品 item_id、私信会话标识或消息文本。 输出：搜索结果 / 商品详情 / 私信列表与内容（JSON 或 snapshot 提取结果）。

主力后端 = target=camoufox。下方命令 / 示例只针对 target=camoufox。 target=host / target=node：只按本工具的「流程 + 提示事项」走——何时有头 / 何时无头 / 频率限制 / 错误处理约定是后端无关的，照本工具执行。不要照搬 camoufox-cli ... 命令，用你当前后端自带的浏览器工具语义调用即可。

前置条件

1. 持久化 session xianyu 已登录（登录态存 session profile 里）。本工具与 login-manager 完全无关——自管探活 + 登录，不导出 cookie/UA 落中央存储。xianyu 不在 login-manager 支持的 5 平台之列。
2. 首次使用 / 登录态失效时，走自管有头手动登录流：
   • camoufox-cli --session xianyu --persistent --headed --viewport 1920x1080 --json open "https://www.goofish.com"
   • --viewport 1920x1080：camoufox 默认按指纹给移动端窗口比例，二维码看不全；强制桌面 1920×1080
   • 告知用户「闲鱼 浏览器已打开，请在窗口里手动扫码登录，完成后告诉我」
   • 等用户回复后 snapshot 零登录态就位
   • 登录后close session——登录态落磁盘 profile，不留进程占内存；本工具下次 --session xianyu --persistent 重起无头即恢复，用完再 close。

不导出 cookie/UA——登录态只在 session profile 里闭环，不落 ~/.openclaw/logins/。本工具不调用 cookies export / identity export / cookies import。

必做约束

• 每次操作之间保持 3-5 秒间隔，避免风控触发验证码。
• 发送私信时不要连续发送超过 10 条，每条间隔 30 秒以上。
• 出现"请先登录"、"验证码"、"安全验证"、"异常访问"等提示时，立即停止操作并告知用户需要重新登录。
• 用完即 close 持久化 session xianyu——登录态 + 指纹冻结在磁盘 profile，不留进程占内存；下次操作 --session xianyu --persistent 重起无头即恢复。只在 session 卡死时 camoufox-cli --session xianyu --json close teardown。
• 同 session 已有命令在跑时，新命令 fail-first（返回 session xianyu 正忙，请等待当前操作完成后再试）——读到这条文本就等当前操作完成再重试，不要盲试。

登录状态检测

在页面加载后，snapshot 检查页面是否出现以下关键词，命中则说明需要重新登录或被风控：

请先登录 / 登录后     → 需要重新登录
验证码 / 安全验证 / 异常访问 / 访问过于频繁 → 被风控，停止操作

URL 格式

工作流程

搜索商品（mtop API + 服务端筛选）

在已登录 session 的页面里调 goofish 自己的 mtop.taobao.idlemtopsearch.pc.search（页面自带 window.lib.mtop 签名，无需手搓），价格区间 / 地区交给服务端筛 + 分页，而非抓一屏 DOM 本地过滤——更准、更稳、不漏筛。

xianyu-ops search \
  --query "iPhone 15" \
  [--min-price 1000] [--max-price 5000] \
  [--province 广东] [--city 深圳] \
  [--limit 30]

wrapper 转发到包内 scripts/xianyu_search.py。脚本内部：open 搜索页加载 mtop lib → 逐页 camoufox-cli eval 调 window.lib.mtop.request → 解析 data.resultList → 输出 JSON。

服务端筛选编码（脚本内做，agent 不用管）：

• --min-price / --max-price（元）→ propValueStr.searchFilter = "priceRange:<min>,<max>;"，单边用 0 / 99999999 兜底
• --province / --city → extraFilterValue = JSON({divisionList:[{province,city}],...})，city 可单独用
• 任一筛选生效时 fromFilter=true，--limit 最多 60

输出：{ok, query, filters, count, items:[{item_id,title,price,condition,brand,location,want,url}]}

退出码：0 成功 / 1 通用错（mtop 未就绪 / 响应异常 / 参数错）/ 2 登录态失效 / 3 session 正忙。

手动 / 后端非 camoufox：target=host/target=node 时，按上方筛选语义用当前后端的浏览器工具调 goofish 搜索接口或 DOM，筛选条件同样交服务端（拼 URL 参数或调等价 API），不要抓全量本地过滤。

查看商品详情

1. camoufox-cli --session xianyu --persistent --json open "https://www.goofish.com/item?id={item_id}"
2. sleep 2-3 加载，snapshot 检测登录状态
3. 用 eval 调 mtop 接口获取详情：
   camoufox-cli --session xianyu --persistent --json eval "window.lib.mtop.request({api:'mtop.taobao.idle.pc.detail',data:{itemId:'{item_id}'},type:'POST',v:'1.0',dataType:'json',needLogin:false,needLoginPC:false,sessionOption:'AutoLoginOnly',ecode:0}).then(r=>JSON.stringify(r)).catch(e=>JSON.stringify({error:String(e)}))"
4. 从返回的 data 中提取：
   - itemDO.title / itemDO.desc / itemDO.soldPrice / itemDO.originalPrice
   - itemDO.wantCnt / itemDO.collectCnt / itemDO.browseCnt
   - itemDO.itemLabelExtList → 找 propertyText="成色"/"品牌"/"分类" 对应的 text
   - itemDO.imageInfos → 图片 URL 列表
   - sellerDO.nick / sellerDO.sellerId / sellerDO.publishCity
   - sellerDO.xianyuSummary / sellerDO.replyRatio24h
5. 若 mtop 不可用（window.lib.mtop 未就绪），改用 snapshot 从 DOM 提取页面上的可见信息

查看私信列表

1. camoufox-cli --session xianyu --persistent --json open "https://www.goofish.com/im"
2. sleep 4-5 加载，snapshot 检测登录状态
3. snapshot 提取会话列表 ref：每个会话包含
   - 对方昵称、商品标题、价格、最后一条消息
   - 未读标记、未读数量
   - click 会话 ref 后从跳转 URL 中解析 itemId 和 peerUserId
4. 若需获取完整 item_id / peer_user_id，逐个 click 会话 ref，从跳转 URL 中提取

读取私信内容

1. 导航到会话页（两种方式）：
   - 已知 item_id + user_id：open "https://www.goofish.com/im?itemId={item_id}&peerUserId={user_id}"
   - 已在私信列表页：click 目标会话 ref
2. sleep 2-3 加载
3. snapshot 确认聊天输入框存在（can_input 为 true）
4. snapshot 提取可见消息列表

发送私信 / 回复

1. 导航到会话页（同"读取私信内容"步骤 1-3）
2. snapshot 拿到聊天输入框 ref
3. camoufox-cli --session xianyu --persistent --json type <输入框-ref> "消息文本"
4. snapshot 找发送按钮 ref → click
5. sleep 1-2，snapshot 确认消息已出现在聊天区域

错误处理