goofish-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/.claude-plugin/marketplace.json

@@ -3,7 +3,7 @@
   "name": "goofish-cli-skills",
   "displayName": "goofish-cli Skills",
   "description": "闲鱼（goofish.com）自动化运营的 Claude Skills 套件。配合 goofish-cli MCP server 使用，让 Agent 在发布商品 / 回复买家 / 风控预检 / 店铺诊断这些场景里上手即会。",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "author": {
     "name": "fancy",
     "url": "https://github.com/fancyboi999"

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/CHANGELOG.md

@@ -6,6 +6,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-10
+
+### Changed
+- 会话列表默认启用 5 秒 WS 发现，补齐最近消息并按活动时间倒序；
+  缺失时间和未知未读数返回 null，列表完整性与最近消息上下文状态分别说明。
+- 历史消息保留 CID、消息 ID 和创建时间；支持 limit 限定最近条数及 timeout，
+  按服务端消息 ID 去重，缺少 ID 的记录不按正文或时间推断为重复。
+
+### Fixed
+- 多图发布仅最终提交计一次商品预算，媒体上传独立计数；已上传收据、已确认类目和地址可复用，失败保留准备信息与提交状态。
+- 本机限流和熔断按账号持久化，跨进程事务加锁、原子保存，损坏状态拒绝写入；风控保存失败保留原始错误。
+- 搜索从真实页面响应读取语义字段，保留未知标签，区分昵称、地域与原价；无命中时排除推荐卡片，分页响应绑定查询与页码，部分失败在 CLI/MCP 明确报告。
+- 商品详情从 itemDO/sellerDO 提取，保留价格和状态 0；类目分数对应选中分类，发布地址使用 selectedPoi。
+- 单聊结合 userInfo 与 ownerInfo 及当前账号确认对端，避免买卖家角色对换时
+  选到自己；WS 会话的角色信息与消息参加者共同用于身份确认。
+- MCP 输出 schema 与统一的 ok/data 或错误对象一致，避免历史工具返回 list
+  的声明与适配器实际对象冲突。
+- 消息读取在超时、连接失败或分页游标不推进时明确报告失败；列表保留已有
+  结果并标注未完成的摘要，取消时清理连接和心跳。
+
+## [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
@@ -182,7 +216,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.3.0...HEAD
+[Unreleased]: https://github.com/fancyboi999/goofish-cli/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/fancyboi999/goofish-cli/compare/v0.4.0...v0.5.0
+[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

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goofish-cli
-Version: 0.3.0
+Version: 0.5.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
@@ -20,6 +20,7 @@ Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
 Requires-Dist: browser-cookie3>=0.20
 Requires-Dist: cryptography>=41.0
+Requires-Dist: filelock<4,>=3.16
 Requires-Dist: loguru>=0.7
 Requires-Dist: mcp<2,>=1.2
 Requires-Dist: playwright>=1.58.0
@@ -83,12 +84,30 @@ Description-Content-Type: text/markdown
 
 ---
 
+## 特别鸣谢
+
+<p align="center">
+  <a href="https://www.ipwo.net/?ref=githubgoofishcli">
+    <img src="media/ipwo-banner.png" alt="IPWO 住宅代理：稳定连接、全球节点、多协议支持" width="95%">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.ipwo.net/?ref=githubgoofishcli"><ins>IPWO</ins></a> 拥有 9000 万+ 活跃住宅 IP 资源，覆盖 195+ 个国家和地区。<br>
+  提供动态住宅代理、静态住宅代理及不限量住宅代理。<br>
+  适用于网页抓取、数据采集、浏览器自动化、跨境业务等场景。<br>
+  我们订阅使用 Claude / Claude Code 时采用住宅 IP，长期使用稳定。<br>
+  支持<a href="https://www.ipwo.net/?ref=githubgoofishcli"><ins>免费测试</ins></a>，<strong>9 折优惠码：</strong><code>0203</code>
+</p>
+
+---
+
 ## ✨ 核心特性
 
 - 🔐 **17 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
-- 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
+- 🛡 **内置风控护栏**：账号与业务桶限流（经营 1 次/分钟、媒体 9 次/分钟）+ RGV587 自动熔断
 - 🧠 **AI-first I/O**：`--format json/yaml/table/md/csv`，给 LLM 喂 JSON、给人看表格
 - ⚡ **一次定义，三种入口**：CLI / MCP / Skill 共享同一 registry
 - ✅ **真实端到端验证**：每个命令都跑过真实账号
@@ -153,13 +172,14 @@ claude /plugin marketplace add fancyboi999/goofish-cli
 
 ## OpenClaw / ClawHub
 
-OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。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.3.0 goofish auth login --qr
+uvx --from goofish-cli==0.5.0 goofish auth login --qr
 
 openclaw plugins inspect goofish --json
 openclaw gateway restart
@@ -201,7 +221,7 @@ $ goofish list-commands --format table
 | `media upload` | 上传图片到闲鱼 CDN | ✅ |
 | `category recommend` | AI 识别商品类目 | ❌ |
 | `location default` | 获取默认发布地址 | ❌ |
-| `message list-chats` | 拉取会话列表（左栏；`--watch-secs N` 叠加 WS 历史推送补漏） | ❌ |
+| `message list-chats` | 会话列表（默认 HTTP + 短时 WS，补最近消息并按活动时间倒序） | ❌ |
 | `search items` | 搜索闲鱼商品（浏览器路径 Playwright + 系统 Chrome） | ❌ |
 | `item view` | 浏览器视角看商品详情（字段完整，抗风控；`item get` 的姊妹版） | ❌ |
 | `message history` | 拉取会话历史消息 | ❌ |
@@ -210,6 +230,22 @@ $ goofish list-commands --format table
 
 </details>
 
+会话读取使用真实消息时间，而非会话创建时间：
+
+```bash
+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` 表明短时同步不能证明全部历史会话已覆盖。
+接口契约与异常边界见 [会话同步](docs/conversation-sync.md)。
+
 <details>
 <summary><b><code>goofish auth status</code></b> — 登录态健康检查</summary>
 
@@ -266,25 +302,21 @@ $ goofish message send <masked-cid> <masked-user-id> \
 <summary><b><code>goofish item publish</code></b> — 发布商品（含风控护栏）</summary>
 
 ```bash
-$ goofish item publish \
-    --title "男士毛呢大衣 驼色长款" \
-    --desc "全新未拆封 原价 2999 现 999" \
-    --images ./a.png,./b.png \
-    --price 999
+goofish item publish "男士毛呢大衣 驼色长款" \
+    "全新未拆封 原价 2999 现 999" ./a.png ./b.png 999 --format json
 ```
 
-流程：
-1. `media upload` 每张图 → CDN URL + 尺寸
-2. `category recommend` 拿 AI 识别的 catId
-3. `location default` 拿默认地址
-4. `mtop.idle.pc.idleitem.publish` 落库
+流程：上传图片 → 推荐类目 → 默认地址 → 提交。已有上传收据可通过
+`--images-json '[{"url":"https://example.alicdn.com/image.png","width":1024,"height":1024}]'`
+复用，省略本地图片参数；已确认类目和地址分别通过 `--category-json`、`--location-json`
+传入对应工具返回的完整 DTO。
 
-返回：
-```json
-{"ok": true, "itemId": "1046118265141", "status": "published"}
-```
+返回 `item_id`、`status="accepted"` 和 `requires_readback=true`；使用
+`goofish item get <item_id>` 和自己的商品列表确认保存。失败也保留已上传图片和准备信息；
+`submission_unknown` 必须先核对商品列表，不自动重复发布。
 
-**触发令牌桶限流**（1 写/分钟）。高频调用会被本地拒绝，避免被闲鱼风控。
+发布与下架共用账号的 `item.write` 预算，默认 1 次/分钟；媒体上传独立计数，默认
+9 次/分钟。一个多图商品只消耗一次商品预算。
 </details>
 
 ---
@@ -318,7 +350,7 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 | WebSocket 批量 push 全量解码 | 一帧多条消息全部还原，不丢单 |
 | WebSocket 自动重连 | 断线自退避重连，长跑无感知 |
 | 已读回执 / typing / 新消息通知分类 | `/s/sync` 元事件结构化为三类 JSONL |
-| 全局限流 + 风控熔断 | 令牌桶 1 写/分钟 + RGV587 自动熔断 |
+| 全局限流 + 风控熔断 | 账号业务预算 + RGV587 自动熔断 |
 | 单元测试 | 33 个，ruff 零告警 |
 | 包分发 | `pip install goofish-cli` / `uvx goofish-cli` |
 

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/README.md

@@ -43,12 +43,30 @@
 
 ---
 
+## 特别鸣谢
+
+<p align="center">
+  <a href="https://www.ipwo.net/?ref=githubgoofishcli">
+    <img src="media/ipwo-banner.png" alt="IPWO 住宅代理：稳定连接、全球节点、多协议支持" width="95%">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.ipwo.net/?ref=githubgoofishcli"><ins>IPWO</ins></a> 拥有 9000 万+ 活跃住宅 IP 资源，覆盖 195+ 个国家和地区。<br>
+  提供动态住宅代理、静态住宅代理及不限量住宅代理。<br>
+  适用于网页抓取、数据采集、浏览器自动化、跨境业务等场景。<br>
+  我们订阅使用 Claude / Claude Code 时采用住宅 IP，长期使用稳定。<br>
+  支持<a href="https://www.ipwo.net/?ref=githubgoofishcli"><ins>免费测试</ins></a>，<strong>9 折优惠码：</strong><code>0203</code>
+</p>
+
+---
+
 ## ✨ 核心特性
 
 - 🔐 **17 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表、skills 安装
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
-- 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
+- 🛡 **内置风控护栏**：账号与业务桶限流（经营 1 次/分钟、媒体 9 次/分钟）+ RGV587 自动熔断
 - 🧠 **AI-first I/O**：`--format json/yaml/table/md/csv`，给 LLM 喂 JSON、给人看表格
 - ⚡ **一次定义，三种入口**：CLI / MCP / Skill 共享同一 registry
 - ✅ **真实端到端验证**：每个命令都跑过真实账号
@@ -113,13 +131,14 @@ claude /plugin marketplace add fancyboi999/goofish-cli
 
 ## OpenClaw / ClawHub
 
-OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。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.3.0 goofish auth login --qr
+uvx --from goofish-cli==0.5.0 goofish auth login --qr
 
 openclaw plugins inspect goofish --json
 openclaw gateway restart
@@ -161,7 +180,7 @@ $ goofish list-commands --format table
 | `media upload` | 上传图片到闲鱼 CDN | ✅ |
 | `category recommend` | AI 识别商品类目 | ❌ |
 | `location default` | 获取默认发布地址 | ❌ |
-| `message list-chats` | 拉取会话列表（左栏；`--watch-secs N` 叠加 WS 历史推送补漏） | ❌ |
+| `message list-chats` | 会话列表（默认 HTTP + 短时 WS，补最近消息并按活动时间倒序） | ❌ |
 | `search items` | 搜索闲鱼商品（浏览器路径 Playwright + 系统 Chrome） | ❌ |
 | `item view` | 浏览器视角看商品详情（字段完整，抗风控；`item get` 的姊妹版） | ❌ |
 | `message history` | 拉取会话历史消息 | ❌ |
@@ -170,6 +189,22 @@ $ goofish list-commands --format table
 
 </details>
 
+会话读取使用真实消息时间，而非会话创建时间：
+
+```bash
+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` 表明短时同步不能证明全部历史会话已覆盖。
+接口契约与异常边界见 [会话同步](docs/conversation-sync.md)。
+
 <details>
 <summary><b><code>goofish auth status</code></b> — 登录态健康检查</summary>
 
@@ -226,25 +261,21 @@ $ goofish message send <masked-cid> <masked-user-id> \
 <summary><b><code>goofish item publish</code></b> — 发布商品（含风控护栏）</summary>
 
 ```bash
-$ goofish item publish \
-    --title "男士毛呢大衣 驼色长款" \
-    --desc "全新未拆封 原价 2999 现 999" \
-    --images ./a.png,./b.png \
-    --price 999
+goofish item publish "男士毛呢大衣 驼色长款" \
+    "全新未拆封 原价 2999 现 999" ./a.png ./b.png 999 --format json
 ```
 
-流程：
-1. `media upload` 每张图 → CDN URL + 尺寸
-2. `category recommend` 拿 AI 识别的 catId
-3. `location default` 拿默认地址
-4. `mtop.idle.pc.idleitem.publish` 落库
+流程：上传图片 → 推荐类目 → 默认地址 → 提交。已有上传收据可通过
+`--images-json '[{"url":"https://example.alicdn.com/image.png","width":1024,"height":1024}]'`
+复用，省略本地图片参数；已确认类目和地址分别通过 `--category-json`、`--location-json`
+传入对应工具返回的完整 DTO。
 
-返回：
-```json
-{"ok": true, "itemId": "1046118265141", "status": "published"}
-```
+返回 `item_id`、`status="accepted"` 和 `requires_readback=true`；使用
+`goofish item get <item_id>` 和自己的商品列表确认保存。失败也保留已上传图片和准备信息；
+`submission_unknown` 必须先核对商品列表，不自动重复发布。
 
-**触发令牌桶限流**（1 写/分钟）。高频调用会被本地拒绝，避免被闲鱼风控。
+发布与下架共用账号的 `item.write` 预算，默认 1 次/分钟；媒体上传独立计数，默认
+9 次/分钟。一个多图商品只消耗一次商品预算。
 </details>
 
 ---
@@ -278,7 +309,7 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 | WebSocket 批量 push 全量解码 | 一帧多条消息全部还原，不丢单 |
 | WebSocket 自动重连 | 断线自退避重连，长跑无感知 |
 | 已读回执 / typing / 新消息通知分类 | `/s/sync` 元事件结构化为三类 JSONL |
-| 全局限流 + 风控熔断 | 令牌桶 1 写/分钟 + RGV587 自动熔断 |
+| 全局限流 + 风控熔断 | 账号业务预算 + RGV587 自动熔断 |
 | 单元测试 | 33 个，ruff 零告警 |
 | 包分发 | `pip install goofish-cli` / `uvx goofish-cli` |
 

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "goofish-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "闲鱼 CLI — 支持 MCP，未来支持 Claude Skills。为 AI Agent 提供闲鱼自动化基础能力。"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -35,6 +35,7 @@ dependencies = [
   "browser-cookie3>=0.20",
   "playwright>=1.58.0",
   "cryptography>=41.0",
+  "filelock>=3.16,<4",
 ]
 
 [project.optional-dependencies]

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/skills/goofish-overview/SKILL.md

@@ -90,8 +90,7 @@ metadata:
 Agent 在 goofish 任务里请遵守：
 
 1. **任何写操作前先读 `auth_status`**，避免 token 已过期却继续写 → 白忙一场。
-2. **`item_publish / media_upload / message_send` 都有速率限制**（令牌桶
-   1 写/分钟），不要短时间连发。RGV587 触发后需用户手动 `goofish auth reset-guard`。
+2. **`item_publish / media_upload / message_send` 都有速率限制**（账号业务预算），不要短时间连发。RGV587 触发后需用户手动 `goofish auth reset-guard`。
 3. **所有对外发送（发商品、发消息）务必让用户先确认文案**，不要自动提交。
 4. **多步任务中途报状态**：上一步完成了什么、下一步准备做什么。闲鱼任务
    通常是 3-6 步，用户期望有进度感。

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/skills/goofish-overview/references/mcp-tools-index.md

@@ -20,17 +20,17 @@
 | `item_get` | HTTP 视角拉详情（只读） | `item_id` | 无 |
 | `item_list` | 查看当前账号的在售商品 | `limit?` | 无 |
 | `item_view` | 浏览器视角拉详情（字段更全、抗风控） | `item_id` | 触发 Playwright 启动 |
-| `item_publish` | 发布商品（自动类目+默认地址） | `title, desc, price, image_urls, cat_id?, addr?` | **写操作**，令牌桶 1 写/分钟 |
+| `item_publish` | 发布商品（自动类目+默认地址） | `title, desc, price, images?, images_json?, category_json?, location_json?` | **写操作**，item.write 默认 1 次/分钟 |
 | `item_delete` | 下架/删除商品 | `item_id` | **写操作** + 风控护栏 |
 
-**发布前强依赖**：`category_recommend` 拿 catId、`media_upload` 拿 image_urls、`location_default` 兜底 addr。
+**发布前强依赖**：`category_recommend` 拿 catId、`media_upload` 拿图片收据、`location_default` 兜底 location_json。
 
 ## Message（4 个）
 
 | 工具 | 用途 | 典型入参 | 备注 |
 |---|---|---|---|
-| `message_list_chats` | 会话列表（左栏） | `limit?, watch_secs?` | session.sync v3.0 是阉割版，默认会启 WebSocket 增量补齐 cid |
-| `message_history` | 某 cid 的历史消息（翻页到底） | `cid` | 拉上下文做意图分类用 |
+| `message_list_chats` | 按最近活动排序的会话摘要 | `fetch_num?, watch_secs?, timeout?` | 默认 5 秒 WS 发现并读取最近消息；检查 metadata_status，不能把 has_more 当全部会话完整性 |
+| `message_history` | 某 cid 的历史消息 | `cid, limit_per_page?, limit?, timeout?` | limit=0 翻页到底；正数只读最近 N 条，保留 message_id/created_at |
 | `message_watch` | 常驻 IM 长连接，事件以 JSONL 输出 | `secs?` | 阻塞式；Skill 里慎用，短连接更合适 |
 | `message_send` | 发消息（text/image） | `cid, text` 或 `cid, image_url, w, h` | **写操作** + 外联词风控 |
 
@@ -41,7 +41,7 @@
 | `category_recommend` | AI 识别类目（输入标题+图片返回 catId/catName） | 发布前必跑，类目错放会降权 |
 | `media_upload` | 上传图片到闲鱼 CDN | 返回 `{url, width, height}`，给 `item_publish` 直接用 |
 | `search_items` | 搜闲鱼商品（浏览器路径，抗风控） | 诊断限流时用"卖家视角 vs 买家视角"对比 |
-| `location_default` | 账号默认发布地址 | `item_publish` 不传 addr 时的兜底 |
+| `location_default` | 账号默认发布地址 | `item_publish` 不传 location_json 时的兜底 |
 
 ## Skills（1 个，辅助类）
 
@@ -66,12 +66,15 @@ auth_status → message_list_chats → message_history (按 cid) → [LLM 意图
 auth_status → search_items (用自家核心词，买家视角) → item_view (拉自家详情) → item_get (历史元数据对比)
 ```
 
-## 写操作全局节流
+## 写操作预算与错误恢复
 
-`item_publish / item_delete / media_upload / message_send` 共用令牌桶：
-- 容量 1、每分钟补 1
-- 短时连发会返回 `RATE_LIMITED`
-- RGV587（服务端风控）触发后需用户从浏览器重新导 cookie（带 x5sec/mtop_partitioned_detect），`auth_reset_guard` 只解本地熔断
+- 同账号发布和下架使用 `item.write`，消息使用 `message.write`，默认各 1 次/分钟。
+- 上传使用独立 `media.write`，默认 9 次/分钟；上传收据通过 `images_json` 复用。
+- CLI 进程与 MCP 线程共享加锁、原子保存的状态；损坏文件拒绝写入。
+- 本机预算不代表平台额度；平台风控触发账号熔断，`auth_reset_guard` 只改变本机状态。
+- 发布失败保留图片、类目、地址及提交状态；`submission_unknown` 先回读，不能自动重发。
+- 搜索 `complete=false` 是未完成，CLI 非零退出，MCP `ok=false` 仍带部分 `data`。
+- 搜索的品牌、成色未知时是 null；用 labels 查看原始标签，不能按顺序猜属性。空查询命中不含网页推荐。
 
 ## 错误类型映射
 

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/skills/goofish-publish-item/SKILL.md

@@ -67,8 +67,8 @@ Claude Code / Cursor 调 `mcp__goofish__<逻辑名>`。frontmatter 的 `allowed-
 ### Step 3 · 类目识别
 
 ```
-调 category_recommend(title=候选标题, images=[首图])
-  → 拿到 catId / catName
+调 category_recommend(title=候选标题, images_json="[]")
+  → 拿到完整类目 DTO；已有上传收据时用 images_json=JSON.stringify(收据数组)
 ```
 
 **结果校验**：
@@ -96,8 +96,8 @@ Claude Code / Cursor 调 `mcp__goofish__<逻辑名>`。frontmatter 的 `allowed-
 ### Step 6 · 图片处理
 
 ```
-for image in images:
-    调 media_upload(image)
+for image in 本地图片路径:
+    调 media_upload(path=image)
     收集返回的 {url, width, height}
 
 检查:
@@ -130,12 +130,16 @@ for image in images:
     title=..., 
     desc=..., 
     price=..., 
-    image_urls=[...],
-    cat_id=..., 
-    addr=...（没有就省略，让服务端用 location_default）
+    images_json=JSON.stringify([{url, width, height}, ...]),
+    category_json=JSON.stringify(category_recommend 的完整 DTO),
+    location_json=JSON.stringify(location_default 的完整 DTO)
 )
 ```
 
+发布也可用 `images=[本地路径, ...]` 自动上传，不能把 CDN URL 当本地路径。已提前上传时复用 `images_json`，避免重复上传。类目 DTO 必须包含 cat_id/cat_name/channel_cat_id/tb_cat_id，地址采用 selected 字段。缺少身份的类目不能猜补。模型分数不是校准概率，未知值为 null。
+
+成功返回 accepted 与 item_id 后，用 item_get 回读确认。失败返回的 images/category/location 可复用；submission_unknown 必须先核对自己的商品列表，禁止盲目重试。发布和下架共用 item.write 默认 1 次/分钟，上传独立 media.write 默认 9 次/分钟。
+
 ## 反模式（不要做）
 
 ❌ **跳过 category_recommend**，自己猜 catId

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/skills/goofish-publish-item/references/category-selection.md

@@ -13,7 +13,7 @@ category_recommend(
 )
 ```
 
-返回 `{catId, catName, confidence?}`。
+返回 `{cat_id, cat_name, channel_cat_id, tb_cat_id, confidence, confidence_source}`。confidence 为模型分数，不是校准概率；缺失为 null。
 
 ## 结果处理
 
@@ -75,4 +75,4 @@ category_recommend(
 
 ## 本模块不调其它工具
 
-只调 `category_recommend`。不需要 `item_get` 也不需要反查——API 给的 catId 直接传给 `item_publish` 就够。
+只调 `category_recommend`。不需要 `item_get` 也不需要反查——将完整类目 DTO 作为 category_json 传给 item_publish；缺少 cat_id/channel_cat_id/tb_cat_id 时不得猜补。

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/skills/goofish-reply-buyer/SKILL.md

@@ -60,10 +60,13 @@ auth_status → valid=false 直接停，提示用户 auth login
 ### Step 2 · 拉未读会话
 
 ```
-message_list_chats(limit=20)
+message_list_chats(fetch_num=20)
 ```
 
-返回会话列表，每项含 cid / 对方昵称 / 最后一条消息预览 / 未读数。
+返回按活动时间倒序的会话列表，每项含 session_id / 对方昵称 / 最后一条消息预览 / 未读数。
+默认短时 WS 会话发现；先检查 metadata_status 和 metadata_errors。身份缺失或摘要过期的会话先补信息，不猜对方身份。
+HTTP 的 has_more 不代表整份会话列表完整，短时同步也不能保证发现全部历史会话。
+WS 条目的 unread=null 表示未知，不能按零忽略，也不能直接与数字比较。
 
 **筛选策略**：
 - 优先未读数 > 0 的
@@ -74,7 +77,7 @@ message_list_chats(limit=20)
 
 ```
 对每个选中的 cid:
-    message_history(cid=..., limit=20)
+    message_history(cid=session_id, limit=20)
 ```
 
 20 条基本够分类意图了。太长的会话（50+ 条）拉 30 条。

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/src/goofish_cli/cli.py

@@ -9,6 +9,7 @@ import typer
 from loguru import logger
 
 from goofish_cli.core import GoofishError, iter_commands
+from goofish_cli.core.errors import PartialResultError
 from goofish_cli.core.output import Format, render
 from goofish_cli.core.registry import Command, discover
 
@@ -51,6 +52,10 @@ def _wrap(cmd: Command):
         fmt = Format(kwargs.pop("format"))
         try:
             result = cmd.func(**kwargs)
+        except PartialResultError as e:
+            render(e.data, fmt=fmt, columns=cmd.columns or None)
+            typer.secho(f"[{e.error.get('error_type', 'PartialResultError')}] {e}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=e.exit_code) from e
         except GoofishError as e:
             typer.secho(f"[{type(e).__name__}] {e}", fg=typer.colors.RED, err=True)
             raise typer.Exit(code=e.exit_code) from e

{goofish_cli-0.3.0 → goofish_cli-0.5.0}/src/goofish_cli/commands/auth/login.py

@@ -23,8 +23,14 @@ import json
 from pathlib import Path
 
 from goofish_cli.core import Strategy, command
+from goofish_cli.core.cookie_types import CookieRecord
 from goofish_cli.core.errors import AuthRequiredError
-from goofish_cli.core.session import DEFAULT_COOKIE_PATH, write_cookies_json
+from goofish_cli.core.session import (
+    DEFAULT_COOKIE_PATH,
+    _coerce_records,
+    _records_to_flat,
+    write_cookies_json,
+)
 
 
 @command(
@@ -56,16 +62,8 @@ def login(
         # qr_timeout=None 让 core.qr_login 走统一的 env → 默认值 兜底逻辑；
         # 这里若写 int 默认（例如 120）会把 env 覆盖路径挡掉（CLI 总是显式传值）。
         from goofish_cli.core.qr_login import login_via_qr
-        cookies = login_via_qr(timeout=qr_timeout, persist=False)
-        if not cookies:
-            # 空 dict 可能来自两种失败：超时未扫码，或 Playwright 起不来（Chrome
-            # 未装、端口占用等）。文案同时覆盖，让用户知道去翻日志。
-            raise AuthRequiredError(
-                "QR 扫码登录未完成——可能是超时内未扫码 / 手机未确认，"
-                "也可能是 Playwright 浏览器启动失败（Chrome 未装、端口占用等，"
-                "详见前面的 warning 日志）。可重试并延长超时："
-                "goofish auth login --qr --qr-timeout 180"
-            )
+
+        records = login_via_qr(timeout=qr_timeout, persist=False)
         source_label = "qr"
     elif source is None:
         if raw:
@@ -75,33 +73,35 @@ def login(
                 "--raw 需要配合 cookie 字符串使用，如："
                 "goofish auth login 'unb=...; _m_h5_tk=...' --raw"
             )
-        cookies, source_label = _pull_from_browser(browser)
+        records, source_label = _pull_from_browser(browser)
     elif raw:
-        cookies = _parse_raw(source)
+        records = _coerce_records(_parse_raw(source))
         source_label = "raw"
     else:
         p = Path(source).expanduser()
-        cookies = _parse_json(p.read_text())
+        records = _parse_json(p.read_text())
         source_label = f"file:{p}"
 
-    if "unb" not in cookies or "_m_h5_tk" not in cookies:
+    # 校验用 flat 视角
+    flat = _records_to_flat(records)
+    if "unb" not in flat or "_m_h5_tk" not in flat:
         raise AuthRequiredError(
             "cookie 缺失关键字段 unb / _m_h5_tk。"
             "请先在浏览器里登录 https://www.goofish.com 再试。"
         )
 
-    write_cookies_json(target, cookies)
+    write_cookies_json(target, records)
 
     return {
         "source": source_label,
         "path": str(target),
-        "unb": cookies.get("unb", ""),
-        "tracknick": cookies.get("tracknick", ""),
-        "cookies_count": len(cookies),
+        "unb": flat.get("unb", ""),
+        "tracknick": flat.get("tracknick", ""),
+        "cookies_count": len(flat),
     }
 
 
-def _pull_from_browser(browser: str) -> tuple[dict[str, str], str]:
+def _pull_from_browser(browser: str) -> tuple[list[CookieRecord], str]:
     from goofish_cli.core.browser_cookie import (
         BrowserCookieError,
         available_browsers,
@@ -133,10 +133,20 @@ def _parse_raw(raw: str) -> dict[str, str]:
     return out
 
 
-def _parse_json(text: str) -> dict[str, str]:
+def _parse_json(text: str) -> list[CookieRecord]:
+    """解析导入文件。list-form JSON → records（保留 path/domain）；dict → coerce。"""
     data = json.loads(text)
     if isinstance(data, list):
-        return {c["name"]: c["value"] for c in data if "name" in c and "value" in c}
+        return [
+            {
+                "name": c["name"],
+                "value": c["value"],
+                "domain": c.get("domain", ""),
+                "path": c.get("path", ""),
+            }
+            for c in data
+            if "name" in c and "value" in c
+        ]
     if isinstance(data, dict):
-        return {str(k): str(v) for k, v in data.items()}
+        return _coerce_records(data)
     raise AuthRequiredError("cookie JSON 格式不识别（需 list 或 dict）")