goofish-cli

闲鱼 CLI · 原生支持 MCP · 为 AI Agent 而生

Goofish (Xianyu) automation CLI · MCP-ready · Built for AI Agents

https://github.com/user-attachments/assets/ae20ae2f-ccdf-4d3e-a947-69182d4c4eff

goofish-cli 把闲鱼（Xianyu/Goofish）的核心运营能力抽成一套结构化命令， 同一份定义同时输出给四种消费者：

• 👨‍💻 人类：goofish item get 12345 --format table

• 🤖 AI Agent（Claude Code / Cursor / Codex）：uvx goofish-cli → 自动注册成 MCP tool

• 🧩 Claude Skills（v0.3）：5 个内置 skill，goofish skills install 一行装到 ~/.claude/skills/

• OpenClaw：ClawHub bundle 一次安装 MCP server + 5 个 skills

架构思想来自 opencli 的 single-registry 设计。

特别鸣谢

Related MCP server: goofish-z-mcp

✨ 核心特性

• 🔐 17 个命令覆盖核心链路：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装

• 📡 真·实时 IM：WebSocket 长连 + 自动重连 + 三类事件分类输出

  • event=message（收到消息）· event=read（已读回执）· event=new_msg（轻量通知）

• 🛡 内置风控护栏：账号与业务桶限流（经营 1 次/分钟、媒体 9 次/分钟）+ RGV587 自动熔断

• 🧠 AI-first I/O：--format json/yaml/table/md/csv，给 LLM 喂 JSON、给人看表格

• ⚡ 一次定义，三种入口：CLI / MCP / Skill 共享同一 registry

• ✅ 真实端到端验证：每个命令都跑过真实账号

🚀 60 秒上手

# 1. 安装
pip install goofish-cli    # 或 uv pip install goofish-cli

# 2. 导入 cookie（从浏览器 DevTools → Application → Cookies 导出）
goofish auth login ~/Downloads/goofish-cookies.json

# 3. 验证登录态
goofish auth status
# → {"unb":"<masked-unb>","tracknick":"<masked-tracknick>","nick":"...","valid":true}

# 4. 干活
goofish item get 1045171414271
goofish message watch                               # 实时接收消息
goofish message send <cid> <toid> --text "在的"    # 发消息

不占用桌面的沙箱模式

需要运行中的本机 Docker Desktop / Docker Engine。安装支持沙箱的版本后，先在终端执行：

goofish sandbox --help
goofish sandbox start
# 手动打开输出的观察链接，默认 http://127.0.0.1:16080/vnc.html?autoconnect=1&resize=scale
goofish sandbox login  # 在虚拟桌面里扫码并确认

goofish sandbox run auth status --format json
goofish sandbox run search items '机械键盘' --limit 3

让 AI 客户端也使用沙箱时，将原有 goofish MCP 配置替换为：

{
  "mcpServers": {
    "goofish": {
      "command": "goofish",
      "args": ["sandbox", "mcp"]
    }
  }
}

客户端必须能找到 goofish 和 docker；桌面客户端找不到命令时，将 command 改为 command -v goofish 输出的绝对路径，并检查客户端 PATH 中是否有 Docker。Codex 使用 TOML，见 MCP 客户端配置。不要同时保留原来的本机 Goofish server；直接运行 uvx goofish-cli 仍使用本机模式。

首次启动会下载并构建镜像。Chromium 在容器虚拟桌面里常驻，登录态保存在独立卷；命令不会自动打开宿主机浏览器。平台要求验证时，执行 goofish sandbox browse --item-id <商品ID>，在观察页面人工完成。升级后用 stop、start --rebuild 更新镜像，状态卷保留。

如果 sandbox --help 不识别命令，当前安装的发行版尚未包含沙箱功能。源码安装、完整的登录/恢复步骤和限制见沙箱指南。

🧩 Claude Skills（v0.3 新增）

v0.3 起内置 5 个 Claude Skill，装完之后 Claude Code / Cursor 里的 Agent 在识别到 闲鱼任务就会自动加载对应 skill 的知识库，不再靠 zero-shot 试错。

# 装到 ~/.claude/skills/（默认）
goofish skills install

# 或者只看有哪些 skill，不拷贝
goofish skills install --list

# 或者装到自定义目录 + 覆盖已有的
goofish skills install --dest ./skills --force

5 个 skill 分工

skill 的源文件在仓库的 skills/ 目录下（每个 skill 一个子目录，含 SKILL.md

• references/*.md 知识库）。也可以走 Claude Code Plugin Marketplace 安装：

claude /plugin marketplace add fancyboi999/goofish-cli

OpenClaw / ClawHub

OpenClaw 2026.6.1 及以上可把本仓库作为 compatible bundle 加载。已发布到 ClawHub，安装：

openclaw plugins install clawhub:openclaw-goofish

# 登录态由用户在终端初始化，不交给 Agent 覆盖
uvx --from goofish-cli==0.6.3 goofish auth login --qr

openclaw plugins inspect goofish --json
openclaw gateway restart

本地开发无需发布：

openclaw plugins install -l .
openclaw plugins inspect goofish --json

重启后新会话会获得 5 个 skills，以及 goofish__auth_status、 goofish__item_get 等 MCP tools。bundle 默认不暴露需要操作者执行或会长期阻塞的 auth_login、auth_reset_guard、message_watch、skills_install。

运行 MCP server 需要 PATH 中有 uv。完整说明见 MCP 接入指南。

📟 命令详略与真实输出

$ goofish list-commands --format table

会话读取使用真实消息时间，而非会话创建时间：

goofish message list-chats --format json
goofish message history <cid> --limit 20 --timeout 30 --format json

list-chats 默认 --watch-secs 5，在一个已就绪的连接中补齐真人会话的最近消息页； --watch-secs 0 关闭 WS 会话发现，结果可能遗漏 HTTP 未返回的会话。 --timeout 限制摘要读取阶段。历史输出保留 cid、message_id 和毫秒时间 created_at， --limit 0 保留完整翻页行为，其他正数只读最近 N 条。

metadata_status 标明摘要是当前、为空、不完整或读取失败；无法确定的时间为 null。 has_more 只代表 HTTP 分页，enumeration_complete=false 表明短时同步不能证明全部历史会话已覆盖。 接口契约与异常边界见 会话同步。

{
  "unb": "<masked-unb>",
  "tracknick": "<masked-tracknick>",
  "nick": "闲鱼用户昵称",
  "valid": true,
  "h5_token_exp": "2026-04-21T20:30:00+08:00"
}

$ goofish message watch

实时输出（小号给主号发 3 条 + 主号读了所有消息）：

{"event":"message","cid":"<masked-cid>","send_user_id":"<masked-user-id>","send_user_name":"小号昵称","send_message":"测试消息1"}
{"event":"message","cid":"<masked-cid>","send_user_id":"<masked-user-id>","send_user_name":"小号昵称","send_message":"测试消息2"}
{"event":"message","cid":"<masked-cid>","send_user_id":"<masked-user-id>","send_user_name":"小号昵称","send_message":"测试消息3"}
{"event":"read","cid":"<masked-cid>","msg_ids":["<masked-msg-id-1>","<masked-msg-id-2>","<masked-msg-id-3>"],"status":1,"ts":"<masked-timestamp>"}

自动跳过噪音：/s/para（对方正在输入）、contentType=8（会话激活心跳）。

$ goofish message send <masked-cid> <masked-user-id> \
    --text "在的 claude 测试成功 ✅" --item-id 1045171414271

{"ok": true, "mid": "<masked-message-id>", "cid": "<masked-cid>"}

goofish item publish "男士毛呢大衣 驼色长款" \
    "全新未拆封 原价 2999 现 999" ./a.png ./b.png 999 --format json

流程：上传图片 → 推荐类目 → 默认地址 → 提交。已有上传收据可通过 --images-json '[{"url":"https://example.alicdn.com/image.png","width":1024,"height":1024}]' 复用，省略本地图片参数；已确认类目和地址分别通过 --category-json、--location-json 传入对应工具返回的完整 DTO。

返回 item_id、status="accepted" 和 requires_readback=true；使用 goofish item get <item_id> 和自己的商品列表确认保存。失败也保留已上传图片和准备信息； submission_unknown 必须先核对商品列表，不自动重复发布。

发布与下架共用账号的 item.write 预算，默认 1 次/分钟；媒体上传独立计数，默认 9 次/分钟。一个多图商品只消耗一次商品预算。

🔌 接入 Claude Code（MCP）

以下为本机模式；需要隔离桌面时，使用上面的沙箱 MCP 配置，客户端位置见 MCP 接入指南。

在项目根目录 .mcp.json 配置：

{
  "mcpServers": {
    "goofish": {
      "command": "uvx",
      "args": ["goofish-cli"]
    }
  }
}

Claude 会自动把全部命令看成 tool：mcp__goofish__item_get / mcp__goofish__item_publish / mcp__goofish__message_watch... 你在对话里直接说"帮我看下 itemId=xxx 的详情"，Claude 就会调用。

🎯 项目亮点

🗺 Roadmap

• v0.1：12 个命令 + MCP + IM 三类事件

• v0.2：goofish message list-chats（会话列表 + sessionType 分类：1 真人 / 3 系统 / 6 互动 / 23 通知；--watch-secs 支持合并 WS ackDiff(pts=0) 历史推送补齐 h5 接口漏掉的会话）

• v0.2：浏览器自动化链路（吸纳 OpenCLI 精华）—— Playwright + 系统 Chrome 驱动 goofish search items / goofish item view，抗风控 & 完整字段

• v0.2.3 / v0.2.4：session 自动续命（passport 快速进入）+ auth login --qr 扫码兜底

• v0.3：Claude Skills 包装（5 个 skill：overview / risk-guard / publish-item / reply-buyer / shop-diagnosis）+ goofish skills install

• v0.4：goofish message create-chat（主动与陌生用户建会话）

• v0.4：goofish order（订单状态查询 / 发货）

• v0.4：历史数据落盘（SQLite / JSONL），给 shop-diagnosis 做时序归因

• v0.5：支持发视频消息

🛠 开发

git clone https://github.com/fancyboi999/goofish-cli
cd goofish-cli
uv venv --python 3.11
uv pip install -e ".[dev]"

uv run pytest                # 33 测全绿
uv run ruff check src tests  # 零告警

详细请看 CONTRIBUTING.md 和 docs/architecture.md。

⚠️ 合规声明

本工具仅用于用户自有账号的自动化运营。严禁：

• 欺诈 / 刷单 / 虚假交易

• 针对闲鱼平台的 SaaS 化转售

• 违反闲鱼、淘宝、阿里巴巴用户协议的行为

工具不提供：绕过滑块验证、批量设备 ID 伪造、自动化规避封号。遇到风控请人工处理（见 docs/compliance.md）。

📜 License

Apache-2.0 © 2026 fancy。详见 LICENSE 和 NOTICE。