goofish-cli 0.2.4__tar.gz → 0.4.0__tar.gz

goofish_cli-0.4.0/.claude-plugin/marketplace.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://claude.ai/schemas/plugin-marketplace.json",
+  "name": "goofish-cli-skills",
+  "displayName": "goofish-cli Skills",
+  "description": "闲鱼（goofish.com）自动化运营的 Claude Skills 套件。配合 goofish-cli MCP server 使用，让 Agent 在发布商品 / 回复买家 / 风控预检 / 店铺诊断这些场景里上手即会。",
+  "version": "0.4.0",
+  "author": {
+    "name": "fancy",
+    "url": "https://github.com/fancyboi999"
+  },
+  "homepage": "https://github.com/fancyboi999/goofish-cli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fancyboi999/goofish-cli.git"
+  },
+  "license": "Apache-2.0",
+  "requires": {
+    "mcp": ["goofish"]
+  },
+  "plugins": [
+    {
+      "name": "goofish-overview",
+      "source": "./skills/goofish-overview",
+      "description": "闲鱼自动化总入口：介绍工具定位、账号模型、15 个 MCP 工具速查、风控底线，并指向其它专项 skill。"
+    },
+    {
+      "name": "goofish-risk-guard",
+      "source": "./skills/goofish-risk-guard",
+      "description": "发布 / 发消息 / 风控恢复三道闸门。内置违禁词表、外联词表、x5sec 恢复指引。被其它 skill 频繁引用。"
+    },
+    {
+      "name": "goofish-publish-item",
+      "source": "./skills/goofish-publish-item",
+      "description": "从描述 / 图片到商品发布的闭环：类目识别 → 标题 5 段式生成 → 风控扫描 → 批量传图 → 用户确认 → 调 item_publish。"
+    },
+    {
+      "name": "goofish-reply-buyer",
+      "source": "./skills/goofish-reply-buyer",
+      "description": "买家消息闭环：拉未读 → 意图分类 → 议价阶梯策略 → 风控扫描 → 用户确认发送。不托管发送权。"
+    },
+    {
+      "name": "goofish-shop-diagnosis",
+      "source": "./skills/goofish-shop-diagnosis",
+      "description": "限流 / 降权 / 曝光掉的归因诊断。search_items 买家视角搜 + item_view 历史对比 → 给嫌疑排序和修复清单。"
+    }
+  ],
+  "install": {
+    "preferredMethod": "cli",
+    "cli": {
+      "command": "uvx",
+      "args": ["--from", "goofish-cli", "goofish", "skills", "install"],
+      "description": "运行 `uvx --from goofish-cli goofish skills install` 把所有 skill 复制到 ~/.claude/skills/。"
+    },
+    "manual": {
+      "description": "也可以直接 clone 仓库并把 skills/ 下的任一目录拷到 ~/.claude/skills/。"
+    }
+  },
+  "tags": ["xianyu", "goofish", "ecommerce", "automation", "mcp", "chinese"]
+}

{goofish_cli-0.2.4 → goofish_cli-0.4.0}/.gitignore

@@ -47,3 +47,7 @@ Thumbs.db
 *.tmp.json
 /frames.jsonl
 /ws_diag*.jsonl
+.video-build/
+
+# npm / ClawHub package artifacts
+*.tgz

{goofish_cli-0.2.4 → goofish_cli-0.4.0}/CHANGELOG.md

@@ -6,6 +6,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-07
+
+### Added
+- 搜索支持 `goofish search items --pages N`，跨页按商品 ID 去重；默认仍读取一页，
+  `--limit` 控制所有页面的结果总数。返回 `pages_fetched`、`pages_total` 和
+  `stopped_reason`，说明实际翻页数量与停止原因。翻页过程中发生错误或遇到登录阻拦时，
+  保留已经取得的结果。
+
+### Fixed
+- 浏览器导入、JSON 导入、扫码登录和 Cookie 刷新保留 Cookie 的 domain/path，
+  防止同名 Cookie 覆盖或注入到错误域名、路径；兼容旧版扁平 Cookie 数据。
+- 修复 Cookie 刷新在 `persist=False` 时的异常，并保持内存与持久化记录一致。
+- 恢复搜索成功时的结构化返回；仅在首屏没有结果且明确要求登录时重试一次。
+
+## [0.3.0] - 2026-08-19
+
+### Added
+- **Claude Skills 套件**（5 个 skill，打包进 wheel）：把 goofish-cli 从"给 Agent 用的
+  工具"升级成"给 Agent 的完整经验体"。Agent 在 Claude Code / Cursor 里识别到闲鱼任务
+  即加载对应 skill 走 reference 知识库，不再 zero-shot 试错。
+  - `goofish-overview`：总入口。介绍定位、账号模型、15 个 MCP 工具速查、风控硬红线，
+    dispatch 到其他 4 个专项 skill。
+  - `goofish-risk-guard`：知识库型 skill。内置违禁词表、外联词正则、发布红线清单、
+    RGV587/x5sec 恢复指引。被 publish-item / reply-buyer 频繁引用。
+  - `goofish-publish-item`：发布闭环。类目识别 → 标题 5 段式生成 → 风控扫描 →
+    批量传图 → 用户确认 → `item_publish`。强约束"不跳过用户确认"。
+  - `goofish-reply-buyer`：消息闭环。`message_watch/list_chats/history/send` 四件套
+    + 议价小刀/大刀/屠龙刀三档策略 + 意图 5 分类。不托管发送权。
+  - `goofish-shop-diagnosis`：限流诊断。`search_items` 买家视角搜 + `item_view`
+    历史对比 → 归因清单给嫌疑排序 + 修复建议。纯读不写。
+- **`goofish skills install` 命令**（`commands/skills/install.py`）：把内置 skill
+  复制到 `~/.claude/skills/`（或 `--dest` 指定路径）。`--list` 仅列举，`--force`
+  覆盖已存在。支持 `uvx --from goofish-cli goofish skills install` 一行装机。
+- **`.claude-plugin/marketplace.json`**：Claude Code Plugin Marketplace 分发清单，
+  5 个 skill 均登记在 `plugins` 数组，`install.cli` 指向 `goofish skills install`。
+- **wheel 打包 skills**：hatch `force-include` 把项目根 `skills/` 装进
+  `goofish_cli/_bundled_skills/`，运行时用 `goofish_cli.__file__` 拿包路径定位
+  （不依赖 namespace package 的 importlib.resources 行为，避免 py 版本差异坑）。
+- **OpenClaw / ClawHub compatible bundle**：用 `.codex-plugin/plugin.json`、`.mcp.json`
+  和 5 个内置 skills 组成 Codex-compatible bundle；OpenClaw 2026.6.1+ 可一次安装 MCP
+  server 与 skills。默认公开 13 个业务 tools，并排除登录、重置风控、长时间 watch 和
+  skills 安装等 4 个需要操作者控制的 tools。
+- **`goofish item list`**：通过 `mtop.idle.web.xyh.item.list` 分页列出当前账号的在售和
+  已下架商品，提取价格、状态、图片和文本标签；后续修复了图片图标 key 泄漏、重复商品、
+  空页继续翻页和异常 `nextPage` 导致的无限循环风险。
+- **OpenClaw 包验证**：检查四处版本对齐、MCP tool filter、archive 文件白名单、敏感内容，
+  并通过 embedded-agent trajectory 验证实际 bundle 工具目录。
+
+### Changed
+- `pyproject.toml` 新增 `[tool.hatch.build.targets.wheel.force-include]` 和
+  `[tool.hatch.build.targets.sdist]` 段。wheel 只 force-include `skills/`（运行时
+  `goofish skills install` 唯一需要的资源）；sdist 额外带 `.claude-plugin/` 和
+  `README / CHANGELOG / LICENSE`，便于从源码分发时拿到完整元数据。
+- skills 同时记录 OpenClaw (`goofish__*`) 和 Claude (`mcp__goofish__*`) 的 MCP tool 名。
+- MCP Python SDK 约束为 `mcp>=1.2,<2`；2.0 已移除当前 server 使用的
+  `mcp.server.fastmcp`，未迁移前禁止 clean install 静默跨主版本。
+- `goofish-cli` 在交互终端启动时明确提示它是 MCP stdio server；Typer positional metadata
+  只进入 CLI wrapper，pyexecjs 的编码 workaround 也不再全局替换 `subprocess.Popen`。
+
+### Fixed
+- 修复闲鱼登录页改版后 `auth login --qr` 必然超时：入口改为 `/login`，按 passport frame
+  URL 重新定位跨文档导航后的 iframe，并兼容 QR 从 `<canvas>` 改为 `<img>` 的 DOM。
+
+### Security
+- Cookie 文件改为 Fernet 加密存储，使用机器与用户信息派生本地密钥；旧版明文 cookie
+  首次读取时自动迁移为密文。
+- 新增全仓库敏感标识扫描，阻止真实格式的账号、会话、发送者和消息标识进入提交与
+  OpenClaw/ClawHub 发布产物。
+
 ## [0.2.4] - 2026-04-22
 
 ### Added
@@ -127,7 +196,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - 本版本需要用户手动从浏览器导入 cookie（含 `unb` / `_m_h5_tk` / `x5sec`）
 - 遇到 `RGV587_ERROR` 风控时，需在浏览器完成滑块验证并**重新导出**带 `x5sec` 的 cookie
 
-[Unreleased]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/fancyboi999/goofish-cli/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/fancyboi999/goofish-cli/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.4...v0.3.0
 [0.2.4]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.1...v0.2.2

{goofish_cli-0.2.4 → goofish_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: goofish-cli
-Version: 0.2.4
+Version: 0.4.0
 Summary: 闲鱼 CLI — 支持 MCP，未来支持 Claude Skills。为 AI Agent 提供闲鱼自动化基础能力。
 Project-URL: Homepage, https://github.com/fancyboi999/goofish-cli
 Project-URL: Repository, https://github.com/fancyboi999/goofish-cli
@@ -19,8 +19,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
 Requires-Dist: browser-cookie3>=0.20
+Requires-Dist: cryptography>=41.0
 Requires-Dist: loguru>=0.7
-Requires-Dist: mcp>=1.2
+Requires-Dist: mcp<2,>=1.2
 Requires-Dist: playwright>=1.58.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyexecjs>=1.5
@@ -54,12 +55,29 @@ Description-Content-Type: text/markdown
 
 </div>
 
+<p align="center">
+  <a href="media/goofish-cli-promo.mp4">
+    <img src="media/goofish-cli-promo.gif" alt="goofish-cli 演示" width="760">
+  </a>
+  <br>
+  <em>▶️ 点击查看带终端音效 + 配乐的高清 MP4（46s）</em>
+</p>
+
+<!--
+  想在 README 里内嵌「带声音的播放器」？GitHub 上唯一的办法：
+  1. 打开本仓库任意 issue / PR 评论框（或 Releases 编辑页）
+  2. 把 media/goofish-cli-promo.mp4 拖进去，等它生成 https://github.com/user-attachments/assets/xxxx 链接
+  3. 把那串链接单独一行粘进这里，GitHub 会自动渲染成带声音的播放器
+  （提交进仓库的 mp4 用 <video> 标签会被 GitHub 过滤，不渲染）
+-->
+
 `goofish-cli` 把闲鱼（Xianyu/Goofish）的核心运营能力抽成一套结构化命令，
-**同一份定义**同时输出给三种消费者：
+**同一份定义**同时输出给四种消费者：
 
 - 👨‍💻 **人类**：`goofish item get 12345 --format table`
 - 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-cli` → 自动注册成 MCP tool
-- 🧩 **Claude Skills**（规划中）：`skills/` 目录直接放进 Agent
+- 🧩 **Claude Skills**（v0.3）：5 个内置 skill，`goofish skills install` 一行装到 `~/.claude/skills/`
+- **OpenClaw**：ClawHub bundle 一次安装 MCP server + 5 个 skills
 
 > 架构思想来自 [opencli](https://github.com/jackwener/opencli) 的 single-registry 设计。
 
@@ -67,7 +85,7 @@ Description-Content-Type: text/markdown
 
 ## ✨ 核心特性
 
-- 🔐 **13 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表
+- 🔐 **17 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
 - 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
@@ -88,7 +106,7 @@ goofish auth login ~/Downloads/goofish-cookies.json
 
 # 3. 验证登录态
 goofish auth status
-# → {"unb":"2214350705775","tracknick":"xy575986224572","nick":"...","valid":true}
+# → {"unb":"<masked-unb>","tracknick":"<masked-tracknick>","nick":"...","valid":true}
 
 # 4. 干活
 goofish item get 1045171414271
@@ -98,6 +116,72 @@ goofish message send <cid> <toid> --text "在的"    # 发消息
 
 ---
 
+## 🧩 Claude Skills（v0.3 新增）
+
+v0.3 起内置 5 个 Claude Skill，装完之后 Claude Code / Cursor 里的 Agent 在识别到
+闲鱼任务就会自动加载对应 skill 的知识库，**不再靠 zero-shot 试错**。
+
+```bash
+# 装到 ~/.claude/skills/（默认）
+goofish skills install
+
+# 或者只看有哪些 skill，不拷贝
+goofish skills install --list
+
+# 或者装到自定义目录 + 覆盖已有的
+goofish skills install --dest ./skills --force
+```
+
+### 5 个 skill 分工
+
+| 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 安装：
+
+```bash
+claude /plugin marketplace add fancyboi999/goofish-cli
+```
+
+---
+
+## OpenClaw / ClawHub
+
+OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。已发布到
+[ClawHub](https://clawhub.ai/plugins/openclaw-goofish)，安装：
+
+```bash
+openclaw plugins install clawhub:openclaw-goofish
+
+# 登录态由用户在终端初始化，不交给 Agent 覆盖
+uvx --from goofish-cli==0.4.0 goofish auth login --qr
+
+openclaw plugins inspect goofish --json
+openclaw gateway restart
+```
+
+本地开发无需发布：
+
+```bash
+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`](https://docs.astral.sh/uv/)。完整说明见
+[MCP 接入指南](./docs/mcp-setup.md)。
+
+---
+
 ## 📟 命令详略与真实输出
 
 <details open>
@@ -132,8 +216,8 @@ $ goofish list-commands --format table
 
 ```json
 {
-  "unb": "2214350705775",
-  "tracknick": "xy575986224572",
+  "unb": "<masked-unb>",
+  "tracknick": "<masked-tracknick>",
   "nick": "闲鱼用户昵称",
   "valid": true,
   "h5_token_exp": "2026-04-21T20:30:00+08:00"
@@ -151,10 +235,10 @@ $ goofish message watch
 实时输出（小号给主号发 3 条 + 主号读了所有消息）：
 
 ```jsonl
-{"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"}
+{"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>"}
 ```
 
 | 事件 | 字段 |
@@ -170,12 +254,12 @@ $ goofish message watch
 <summary><b><code>goofish message send</code></b> — 主动发消息</summary>
 
 ```bash
-$ goofish message send 60585751957 2215266653893 \
+$ goofish message send <masked-cid> <masked-user-id> \
     --text "在的 claude 测试成功 ✅" --item-id 1045171414271
 ```
 
 ```json
-{"ok": true, "mid": "1061776769407570", "cid": "60585751957"}
+{"ok": true, "mid": "<masked-message-id>", "cid": "<masked-cid>"}
 ```
 </details>
 
@@ -246,10 +330,12 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 - [x] v0.1：12 个命令 + MCP + IM 三类事件
 - [x] v0.2：`goofish message list-chats`（会话列表 + sessionType 分类：1 真人 / 3 系统 / 6 互动 / 23 通知；`--watch-secs` 支持合并 WS `ackDiff(pts=0)` 历史推送补齐 h5 接口漏掉的会话）
 - [x] v0.2：浏览器自动化链路（吸纳 [OpenCLI](https://github.com/jackwener/opencli) 精华）—— Playwright + 系统 Chrome 驱动 `goofish search items` / `goofish item view`，抗风控 & 完整字段
-- [ ] v0.2：`goofish message create-chat`（主动与陌生用户建会话）
-- [ ] v0.2：Claude Skills 包装（`skills/` 目录）
-- [ ] v0.3：`goofish order`（订单状态查询 / 发货）
-- [ ] v0.3：支持发视频消息
+- [x] v0.2.3 / v0.2.4：session 自动续命（passport 快速进入）+ `auth login --qr` 扫码兜底
+- [x] 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：支持发视频消息
 
 ---
 

{goofish_cli-0.2.4 → goofish_cli-0.4.0}/README.md

@@ -15,12 +15,29 @@
 
 </div>
 
+<p align="center">
+  <a href="media/goofish-cli-promo.mp4">
+    <img src="media/goofish-cli-promo.gif" alt="goofish-cli 演示" width="760">
+  </a>
+  <br>
+  <em>▶️ 点击查看带终端音效 + 配乐的高清 MP4（46s）</em>
+</p>
+
+<!--
+  想在 README 里内嵌「带声音的播放器」？GitHub 上唯一的办法：
+  1. 打开本仓库任意 issue / PR 评论框（或 Releases 编辑页）
+  2. 把 media/goofish-cli-promo.mp4 拖进去，等它生成 https://github.com/user-attachments/assets/xxxx 链接
+  3. 把那串链接单独一行粘进这里，GitHub 会自动渲染成带声音的播放器
+  （提交进仓库的 mp4 用 <video> 标签会被 GitHub 过滤，不渲染）
+-->
+
 `goofish-cli` 把闲鱼（Xianyu/Goofish）的核心运营能力抽成一套结构化命令，
-**同一份定义**同时输出给三种消费者：
+**同一份定义**同时输出给四种消费者：
 
 - 👨‍💻 **人类**：`goofish item get 12345 --format table`
 - 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-cli` → 自动注册成 MCP tool
-- 🧩 **Claude Skills**（规划中）：`skills/` 目录直接放进 Agent
+- 🧩 **Claude Skills**（v0.3）：5 个内置 skill，`goofish skills install` 一行装到 `~/.claude/skills/`
+- **OpenClaw**：ClawHub bundle 一次安装 MCP server + 5 个 skills
 
 > 架构思想来自 [opencli](https://github.com/jackwener/opencli) 的 single-registry 设计。
 
@@ -28,7 +45,7 @@
 
 ## ✨ 核心特性
 
-- 🔐 **13 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表
+- 🔐 **17 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
 - 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
@@ -49,7 +66,7 @@ goofish auth login ~/Downloads/goofish-cookies.json
 
 # 3. 验证登录态
 goofish auth status
-# → {"unb":"2214350705775","tracknick":"xy575986224572","nick":"...","valid":true}
+# → {"unb":"<masked-unb>","tracknick":"<masked-tracknick>","nick":"...","valid":true}
 
 # 4. 干活
 goofish item get 1045171414271
@@ -59,6 +76,72 @@ goofish message send <cid> <toid> --text "在的"    # 发消息
 
 ---
 
+## 🧩 Claude Skills（v0.3 新增）
+
+v0.3 起内置 5 个 Claude Skill，装完之后 Claude Code / Cursor 里的 Agent 在识别到
+闲鱼任务就会自动加载对应 skill 的知识库，**不再靠 zero-shot 试错**。
+
+```bash
+# 装到 ~/.claude/skills/（默认）
+goofish skills install
+
+# 或者只看有哪些 skill，不拷贝
+goofish skills install --list
+
+# 或者装到自定义目录 + 覆盖已有的
+goofish skills install --dest ./skills --force
+```
+
+### 5 个 skill 分工
+
+| 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 安装：
+
+```bash
+claude /plugin marketplace add fancyboi999/goofish-cli
+```
+
+---
+
+## OpenClaw / ClawHub
+
+OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。已发布到
+[ClawHub](https://clawhub.ai/plugins/openclaw-goofish)，安装：
+
+```bash
+openclaw plugins install clawhub:openclaw-goofish
+
+# 登录态由用户在终端初始化，不交给 Agent 覆盖
+uvx --from goofish-cli==0.4.0 goofish auth login --qr
+
+openclaw plugins inspect goofish --json
+openclaw gateway restart
+```
+
+本地开发无需发布：
+
+```bash
+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`](https://docs.astral.sh/uv/)。完整说明见
+[MCP 接入指南](./docs/mcp-setup.md)。
+
+---
+
 ## 📟 命令详略与真实输出
 
 <details open>
@@ -93,8 +176,8 @@ $ goofish list-commands --format table
 
 ```json
 {
-  "unb": "2214350705775",
-  "tracknick": "xy575986224572",
+  "unb": "<masked-unb>",
+  "tracknick": "<masked-tracknick>",
   "nick": "闲鱼用户昵称",
   "valid": true,
   "h5_token_exp": "2026-04-21T20:30:00+08:00"
@@ -112,10 +195,10 @@ $ goofish message watch
 实时输出（小号给主号发 3 条 + 主号读了所有消息）：
 
 ```jsonl
-{"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"}
+{"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>"}
 ```
 
 | 事件 | 字段 |
@@ -131,12 +214,12 @@ $ goofish message watch
 <summary><b><code>goofish message send</code></b> — 主动发消息</summary>
 
 ```bash
-$ goofish message send 60585751957 2215266653893 \
+$ goofish message send <masked-cid> <masked-user-id> \
     --text "在的 claude 测试成功 ✅" --item-id 1045171414271
 ```
 
 ```json
-{"ok": true, "mid": "1061776769407570", "cid": "60585751957"}
+{"ok": true, "mid": "<masked-message-id>", "cid": "<masked-cid>"}
 ```
 </details>
 
@@ -207,10 +290,12 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 - [x] v0.1：12 个命令 + MCP + IM 三类事件
 - [x] v0.2：`goofish message list-chats`（会话列表 + sessionType 分类：1 真人 / 3 系统 / 6 互动 / 23 通知；`--watch-secs` 支持合并 WS `ackDiff(pts=0)` 历史推送补齐 h5 接口漏掉的会话）
 - [x] v0.2：浏览器自动化链路（吸纳 [OpenCLI](https://github.com/jackwener/opencli) 精华）—— Playwright + 系统 Chrome 驱动 `goofish search items` / `goofish item view`，抗风控 & 完整字段
-- [ ] v0.2：`goofish message create-chat`（主动与陌生用户建会话）
-- [ ] v0.2：Claude Skills 包装（`skills/` 目录）
-- [ ] v0.3：`goofish order`（订单状态查询 / 发货）
-- [ ] v0.3：支持发视频消息
+- [x] v0.2.3 / v0.2.4：session 自动续命（passport 快速进入）+ `auth login --qr` 扫码兜底
+- [x] 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：支持发视频消息
 
 ---
 

{goofish_cli-0.2.4 → goofish_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "goofish-cli"
-version = "0.2.4"
+version = "0.4.0"
 description = "闲鱼 CLI — 支持 MCP，未来支持 Claude Skills。为 AI Agent 提供闲鱼自动化基础能力。"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -28,10 +28,13 @@ dependencies = [
   "rich>=13.7",
   "pyyaml>=6.0",
   "tenacity>=8.2",
-  "mcp>=1.2",
+  # v2 renames FastMCP to MCPServer and requires a server migration.
+  # Keep the existing FastMCP implementation on the maintained v1 line for now.
+  "mcp>=1.2,<2",
   "websockets>=13",
   "browser-cookie3>=0.20",
   "playwright>=1.58.0",
+  "cryptography>=41.0",
 ]
 
 [project.optional-dependencies]
@@ -63,6 +66,23 @@ Changelog = "https://github.com/fancyboi999/goofish-cli/blob/main/CHANGELOG.md"
 [tool.hatch.build.targets.wheel]
 packages = ["src/goofish_cli"]
 
+# 内置 Claude Skills：把项目根 `skills/` 收进 wheel 的 `goofish_cli/_bundled_skills/`，
+# 让 `goofish skills install` 能按包内路径定位到它（当前实现用 `goofish_cli.__file__`
+# 拼子路径，不依赖 importlib.resources，避免 namespace package 在不同 py 版本上的行为差异）。
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "src/goofish_cli/_bundled_skills"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/",
+  "skills/",
+  ".claude-plugin/",
+  "README.md",
+  "CHANGELOG.md",
+  "LICENSE",
+  "pyproject.toml",
+]
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"