闲鱼 CLI · 原生支持 MCP · 为 AI Agent 而生
Goofish (Xianyu) automation CLI · MCP-ready · Built for AI Agents
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/
架构思想来自 opencli 的 single-registry 设计。
- 🔐 16 个命令覆盖核心链路：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装
- 📡 真·实时 IM：WebSocket 长连 + 自动重连 + 三类事件分类输出
event=message（收到消息）·event=read（已读回执）·event=new_msg（轻量通知）
- 🛡 内置风控护栏：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
- 🧠 AI-first I/O：
--format json/yaml/table/md/csv，给 LLM 喂 JSON、给人看表格 - ⚡ 一次定义，三种入口：CLI / MCP / Skill 共享同一 registry
- ✅ 真实端到端验证：每个命令都跑过真实账号
# 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":"2214350705775","tracknick":"xy575986224572","nick":"...","valid":true}
# 4. 干活
goofish item get 1045171414271
goofish message watch # 实时接收消息
goofish message send <cid> <toid> --text "在的" # 发消息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| Skill | 什么时候激活 | 核心能力 |
|---|---|---|
goofish-overview |
用户首次提闲鱼 / 问这工具能干啥 | 总入口，dispatch 到其他 4 个 skill |
goofish-publish-item |
发商品 / 上架 / 挂闲置 | 类目识别 → 标题 5 段式 → 风控扫描 → 图片检查 → 确认发布 |
goofish-reply-buyer |
回消息 / 看未读 / 议价 | 拉未读 → 意图 5 分类 → 议价三档（小刀/大刀/屠龙刀）→ 用户确认发送 |
goofish-risk-guard |
发布前 / 发送前 / 被限流了 | 违禁词表、外联词正则、发布红线、x5sec 恢复指引（被其他 skill 频繁引用） |
goofish-shop-diagnosis |
店铺没流量 / 曝光掉了 | 买家视角搜索 + 历史对比 → 归因清单 + 修复建议（纯读不写） |
skill 的源文件在仓库的 skills/ 目录下（每个 skill 一个子目录，含 SKILL.md
references/*.md知识库）。也可以走 Claude Code Plugin Marketplace 安装：
claude /plugin marketplace add fancyboi999/goofish-cligoofish list-commands — 注册表全景
$ goofish list-commands --format table| 命令 | 说明 | 写操作 |
|---|---|---|
auth login |
从 JSON 文件或 cookie 字符串导入登录态 | ❌ |
auth status |
检查登录态是否有效 | ❌ |
auth reset-guard |
手动解除风控熔断 | ❌ |
item get |
查询闲鱼商品详情 | ❌ |
item publish |
发布商品（自动识别类目 + 默认地址） | ✅ |
item delete |
下架/删除商品 | ✅ |
media upload |
上传图片到闲鱼 CDN | ✅ |
category recommend |
AI 识别商品类目 | ❌ |
location default |
获取默认发布地址 | ❌ |
message list-chats |
拉取会话列表（左栏；--watch-secs N 叠加 WS 历史推送补漏） |
❌ |
search items |
搜索闲鱼商品（浏览器路径 Playwright + 系统 Chrome） | ❌ |
item view |
浏览器视角看商品详情（字段完整，抗风控；item get 的姊妹版） |
❌ |
message history |
拉取会话历史消息 | ❌ |
message send |
发送文本/图片 | ✅ |
message watch |
常驻 IM 长连（JSONL 输出） | ❌ |
goofish auth status — 登录态健康检查
{
"unb": "2214350705775",
"tracknick": "xy575986224572",
"nick": "闲鱼用户昵称",
"valid": true,
"h5_token_exp": "2026-04-21T20:30:00+08:00"
}goofish message watch — 三类事件 JSONL 流
$ goofish message watch实时输出（小号给主号发 3 条 + 主号读了所有消息）：
{"event":"message","cid":"60585751957","send_user_id":"2215266653893","send_user_name":"小号昵称","send_message":"测试消息1"}
{"event":"message","cid":"60585751957","send_user_id":"2215266653893","send_user_name":"小号昵称","send_message":"测试消息2"}
{"event":"message","cid":"60585751957","send_user_id":"2215266653893","send_user_name":"小号昵称","send_message":"测试消息3"}
{"event":"read","cid":"60585751957","msg_ids":["4077151826249.PNM","4066820235744.PNM","4066826134477.PNM"],"status":1,"ts":"1776770953455"}| 事件 | 字段 |
|---|---|
message |
cid · send_user_id · send_user_name · send_message · content_type |
read |
cid · msg_ids[] · status · ts |
new_msg |
cid · msg_id · ts（服务端只推指针，需 message history 拉正文） |
自动跳过噪音：/s/para（对方正在输入）、contentType=8（会话激活心跳）。
goofish message send — 主动发消息
$ goofish message send 60585751957 2215266653893 \
--text "在的 claude 测试成功 ✅" --item-id 1045171414271{"ok": true, "mid": "1061776769407570", "cid": "60585751957"}goofish item publish — 发布商品（含风控护栏）
$ goofish item publish \
--title "男士毛呢大衣 驼色长款" \
--desc "全新未拆封 原价 2999 现 999" \
--images ./a.png,./b.png \
--price 999流程：
media upload每张图 → CDN URL + 尺寸category recommend拿 AI 识别的 catIdlocation default拿默认地址mtop.idle.pc.idleitem.publish落库
返回：
{"ok": true, "itemId": "1046118265141", "status": "published"}触发令牌桶限流（1 写/分钟）。高频调用会被本地拒绝，避免被闲鱼风控。
在 ~/.config/claude-code/config.json：
{
"mcpServers": {
"goofish": {
"command": "uvx",
"args": ["goofish-cli"]
}
}
}Claude 会自动把全部命令看成 tool：goofish_item_get / goofish_item_publish / goofish_message_watch... 你在对话里直接说"帮我看下 itemId=xxx 的详情"，Claude 就会调用。
| 能力 | 说明 |
|---|---|
| 11 个核心 mtop 接口 | 发布/下架/查询/图片/类目/地址/IM 全覆盖 |
CLI + --format 多格式输出 |
json / yaml / table / md / csv，人机两用 |
| MCP Server | uvx goofish-cli 一行接入 Claude Code / Cursor |
| WebSocket 批量 push 全量解码 | 一帧多条消息全部还原，不丢单 |
| WebSocket 自动重连 | 断线自退避重连，长跑无感知 |
| 已读回执 / typing / 新消息通知分类 | /s/sync 元事件结构化为三类 JSONL |
| 全局限流 + 风控熔断 | 令牌桶 1 写/分钟 + RGV587 自动熔断 |
| 单元测试 | 33 个，ruff 零告警 |
| 包分发 | pip install goofish-cli / uvx goofish-cli |
- v0.1：12 个命令 + MCP + IM 三类事件
- v0.2：
goofish message list-chats（会话列表 + sessionType 分类：1 真人 / 3 系统 / 6 互动 / 23 通知；--watch-secs支持合并 WSackDiff(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）。