xianyu-skills

闲鱼自动化 Skills。它通过本项目自带的 Xianyu Bridge Chrome 扩展和本地 Python CLI，直接使用你已登录的 Chrome 闲鱼账号完成商品发布、商品搜索、详情读取、消息互动、收藏/想要和商品运营分析。

支持 Codex、Claude Code、OpenCode、OpenClaw 以及其他兼容 SKILL.md 格式的 AI Agent 平台。

使用提醒：本项目会操作你的真实闲鱼账号。发布商品、发送消息、收藏、点击“我想要”等动作会产生外部效果。建议控制频率，避免短时间内大量重复操作，并遵守闲鱼平台规则。

功能概览

支持自然语言复合操作。例如：

搜索闲鱼上 PPT 美化服务的数据较好的商品，参考竞品生成一条商品发布方案，先填表让我确认。

Agent 会组合执行：登录检查 -> 搜索竞品 -> 读取详情 -> 总结价格和卖点 -> 准备描述和图片路径 -> 填写发布表单。

安装

前置条件

• Python >= 3.11
• uv 包管理器
• Google Chrome 浏览器
• 一个已登录或可登录的闲鱼账号

方法一：使用 Skills CLI 安装

推荐使用 Vercel Labs 的 skills CLI 安装。它支持从 GitHub 仓库安装技能，并可指定目标 Agent。

# 安装到当前项目，由 CLI 交互选择目标 Agent
npx skills add donggeai/xianyu-skills

# 安装到 Claude Code 和 Codex
npx skills add donggeai/xianyu-skills -a claude-code -a codex

# 安装到全局目录
npx skills add donggeai/xianyu-skills -g

# 非交互安装
npx skills add donggeai/xianyu-skills -a codex -y

也可以使用完整 GitHub URL：

npx skills add https://github.com/donggeai/xianyu-skills

如果仓库中存在多个 Skill，可使用 --skill xianyu-skills 指定安装；如果这是独立仓库，通常不需要额外指定。

方法二：手动下载或 Git Clone

cd /.agents/skills/
git clone https://github.com/donggeai/xianyu-skills.git

不同 Agent 的项目目录可能不同：

Codex:       .agents/skills/xianyu-skills/
Claude Code: .claude/skills/xianyu-skills/
OpenClaw:    skills/xianyu-skills/
OpenCode:    .agents/skills/xianyu-skills/

安装 Python 依赖

进入 skill 目录后执行：

cd xianyu-skills
uv sync

如果不使用 uv，也可以在已有 Python 环境中安装：

pip install requests websockets

Windows 上建议使用项目虚拟环境执行命令：

.\.venv\Scripts\python.exe scripts\cli.py check-login

安装 Chrome 扩展

Xianyu Bridge 扩展用于把本地 CLI 命令转发到你自己的 Chrome 浏览器中执行。

1. 打开 Chrome，进入 chrome://extensions/
2. 打开右上角“开发者模式”
3. 点击“加载已解压的扩展程序”
4. 选择本项目的 extension/ 目录
5. 确认扩展名为 Xianyu Bridge

扩展加载后，CLI 默认连接地址为：

ws://localhost:9444

使用方式

作为 AI Agent Skill 使用

安装后，直接用自然语言让 Agent 操作闲鱼即可。

认证登录：

检查我的闲鱼是否已登录。

商品搜索：

搜索闲鱼上“桌面收纳盒”的高想要商品，并总结价格带。

商品发布：

根据我提供的图片和描述，帮我在闲鱼发布一个商品，先填表让我确认。

消息互动：

查看闲鱼消息列表，并帮我起草回复。

商品运营：

分析 PPT 美化服务在闲鱼上的竞品，给我一个发布测试方案。

作为 CLI 工具使用

所有命令输出 JSON，适合 Agent 或脚本解析。

# 检查登录
python scripts/cli.py check-login

# 打开登录页
python scripts/cli.py login

# 搜索商品
python scripts/cli.py search-items --keyword "PPT美化" --limit 20

# 获取商品详情
python scripts/cli.py get-item-detail --item-id ITEM_ID

# 查看我的商品
python scripts/cli.py list-my-items

# 分步发布：先填表，再确认发布
python scripts/cli.py fill-publish \
  --description-file D:/abs/desc.txt \
  --price 29.9 \
  --images D:/abs/cover.png D:/abs/detail.png \
  --shipping "无需邮寄"

python scripts/cli.py click-publish

# 一步发布
python scripts/cli.py publish \
  --description-file D:/abs/desc.txt \
  --price 29.9 \
  --images D:/abs/cover.png D:/abs/detail.png

# 商品运营分析
python scripts/cli.py analyze-competitors --keyword "PPT代做" --limit 10

# 商品状态
python scripts/cli.py get-item-stats --item-id ITEM_ID

# 消息与互动
python scripts/cli.py list-messages
python scripts/cli.py open-chat --item-id ITEM_ID --peer-user-id USER_ID
python scripts/cli.py send-message --content-file D:/abs/message.txt
python scripts/cli.py favorite-item --item-id ITEM_ID
python scripts/cli.py want-item --item-id ITEM_ID

# 截图诊断
python scripts/cli.py screenshot --output D:/abs/xianyu.png

发布商品说明

正式发布优先使用用户提供的真实商品图片素材。

• 本地图片：直接传给 --images
• 图片 URL：先下载到本地，再传给 --images
• 设计工具或 ImageGen 生成的图片：先保存为本地图片，再传给 --images

不要上传含二维码、手机号、微信号、外部链接、明显水印、平台外导流、夸张承诺或敏感文字的图片。

分类策略：auto-safe

闲鱼网页端有些自动识别分类不支持发布。默认 --category auto-safe 会按页面反馈处理：

1. 先接受闲鱼自动识别分类
2. 如果页面提示“网页版暂不支持发布此分类”或“请使用闲鱼APP扫码继续发布”
3. 打开分类下拉框
4. 从当前分类后面的相邻候选分类开始依次尝试
5. 直到页面不再显示网页端不支持提示

返回结果中的 category_resolution 会记录：

• 初始分类
• 最终分类
• 是否切换
• 尝试过的分类
• 是否检测到不支持提示
• 切换原因

示例字段：

{
  "category": "AI办公工具/服务",
  "category_resolution": {
    "requested": "auto-safe",
    "initial": "office办公制作",
    "final": "AI办公工具/服务",
    "changed": true,
    "unsupported_marker_seen": true,
    "reason": "原分类网页端不支持，已切换到相邻可发布分类"
  },
  "unsupported_category_marker": false
}

CLI 命令参考

项目结构

xianyu-skills/
├── extension/                    # Chrome Xianyu Bridge 扩展
│   ├── icons/                    # 扩展图标
│   ├── manifest.json
│   ├── background.js
│   ├── content.js
│   ├── popup.html
│   └── popup.js
├── scripts/
│   ├── cli.py                    # 统一 CLI 入口
│   ├── bridge_server.py          # 本地 WebSocket Bridge
│   ├── run_lock.py               # 串行执行锁
│   └── xianyu/
│       ├── bridge.py             # 扩展通信客户端
│       ├── login.py              # 登录状态
│       ├── publish.py            # 商品发布
│       ├── search.py             # 商品搜索
│       ├── item_detail.py        # 商品详情
│       ├── profile.py            # 个人主页 / 我的商品
│       ├── messages.py           # 消息和聊天
│       ├── interact.py           # 收藏 / 想要
│       └── product_ops.py        # 商品运营分析
├── skills/
│   ├── xianyu-auth/SKILL.md
│   ├── xianyu-publish/SKILL.md
│   ├── xianyu-explore/SKILL.md
│   ├── xianyu-interact/SKILL.md
│   └── xianyu-product-ops/SKILL.md
├── SKILL.md                      # Skill 统一入口
├── pyproject.toml
├── uv.lock
└── README.md

常见问题

No module named websockets

使用虚拟环境里的 Python：

.\.venv\Scripts\python.exe scripts\cli.py check-login

或先运行：

uv sync

等待 Xianyu Bridge 扩展连接超时

• 确认 Chrome 已打开
• 确认 extension/ 已作为已解压扩展加载
• 在 chrome://extensions/ 重新加载 Xianyu Bridge
• 确认本地 scripts/bridge_server.py 未被防火墙拦截

上传图片失败

• 使用本地绝对路径
• 确认文件存在
• 确认图片不是二维码、联系方式或平台外导流素材
• 图片 URL 需要先下载成本地文件

发布后商品不在列表里

可能处于平台审核、被下架、延迟刷新或触发风控。请检查：

python scripts/cli.py list-my-items
python scripts/cli.py list-messages
python scripts/cli.py get-item-detail --item-id ITEM_ID

open-chat 缺少 peer-user-id

open-chat 需要 item-id 和 peer-user-id。当前 list-messages 主要返回文本摘要；如果缺少 peer-user-id，可从商品页、聊天页 URL 或页面诊断中获取。

开发

uv sync
python scripts/cli.py --help
python -m py_compile scripts/cli.py scripts/bridge_server.py scripts/run_lock.py scripts/xianyu/*.py
node --check extension/background.js

如果修改 Skill 文档，可使用 Skill Creator 的 quick_validate.py 校验：

python path/to/skill-creator/scripts/quick_validate.py .

免责声明

本项目仅提供自动化工具和 Skill 工作流。用户应自行确认发布内容、互动行为和账号操作符合闲鱼平台规则及相关法律法规。因不当使用造成的账号限制、商品下架、交易纠纷或其他后果，由使用者自行承担。

License

MIT