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

{goofish_cli-0.4.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.4.0",
+  "version": "0.5.0",
   "author": {
     "name": "fancy",
     "url": "https://github.com/fancyboi999"

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

@@ -6,6 +6,26 @@ 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
@@ -196,7 +216,8 @@ 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.4.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goofish-cli
-Version: 0.4.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
 - ✅ **真实端到端验证**：每个命令都跑过真实账号
@@ -160,7 +179,7 @@ OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。
 openclaw plugins install clawhub:openclaw-goofish
 
 # 登录态由用户在终端初始化，不交给 Agent 覆盖
-uvx --from goofish-cli==0.4.0 goofish auth login --qr
+uvx --from goofish-cli==0.5.0 goofish auth login --qr
 
 openclaw plugins inspect goofish --json
 openclaw gateway restart
@@ -202,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` | 拉取会话历史消息 | ❌ |
@@ -211,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>
 
@@ -267,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>
 
 ---
@@ -319,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.4.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
 - ✅ **真实端到端验证**：每个命令都跑过真实账号
@@ -120,7 +138,7 @@ OpenClaw `2026.6.1` 及以上可把本仓库作为 compatible bundle 加载。
 openclaw plugins install clawhub:openclaw-goofish
 
 # 登录态由用户在终端初始化，不交给 Agent 覆盖
-uvx --from goofish-cli==0.4.0 goofish auth login --qr
+uvx --from goofish-cli==0.5.0 goofish auth login --qr
 
 openclaw plugins inspect goofish --json
 openclaw gateway restart
@@ -162,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` | 拉取会话历史消息 | ❌ |
@@ -171,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>
 
@@ -227,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>
 
 ---
@@ -279,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.4.0 → goofish_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "goofish-cli"
-version = "0.4.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.4.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.4.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.4.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.4.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.4.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.4.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.5.0/src/goofish_cli/commands/category/recommend.py

@@ -0,0 +1,101 @@
+"""category recommend — AI 识别商品类目（发布前置）。
+
+接口：mtop.taobao.idle.kgraph.property.recommend v2.0
+"""
+
+import json
+import math
+import time
+from typing import Any
+
+from goofish_cli.commands.media.upload import validate_image_receipt
+from goofish_cli.core import Session, Strategy, command
+from goofish_cli.core.errors import GoofishError
+from goofish_cli.core.mtop import call
+
+
+def _selected_score(data: dict, predict: dict) -> tuple[float | None, str | None]:
+    explicit = predict.get("confidence")
+    if isinstance(explicit, (float, int)) and not isinstance(explicit, bool) and math.isfinite(explicit):
+        return float(explicit), "categoryPredictResult.confidence"
+    values = []
+    for card in data.get("cardList") or []:
+        body = card.get("cardData") or {}
+        if str(body.get("propertyId")) != "-10000":
+            continue
+        for candidate in body.get("valuesList") or []:
+            keys = ("channelCatId", "tbCatId", "catId")
+            if all(str(candidate.get(key)) == str(predict[key]) for key in keys if predict.get(key) is not None):
+                score = candidate.get("score")
+                if isinstance(score, (float, int)) and not isinstance(score, bool) and math.isfinite(score):
+                    values.append(float(score))
+    return (values[0], "classification_card.score") if len(values) == 1 else (None, None)
+
+
+@command(
+    namespace="category",
+    name="recommend",
+    description="AI 识别商品类目，输入标题+图片返回 catId/catName",
+    strategy=Strategy.COOKIE,
+    columns=["cat_id", "cat_name", "channel_cat_id", "tb_cat_id", "confidence"],
+)
+def recommend(
+    title: str,
+    images_json: str = "[]",
+) -> dict[str, Any]:
+    """images_json 是 JSON 字符串：[{"url":"...","width":1024,"height":1024}, ...]"""
+    if not title.strip():
+        raise GoofishError("类目推荐标题不能为空")
+    try:
+        images = json.loads(images_json) if images_json else []
+    except ValueError:
+        raise GoofishError("images-json 必须是有效 JSON 图片收据数组") from None
+    if not isinstance(images, list) or len(images) > 9:
+        raise GoofishError("images-json 必须是至多 9 张图片收据的数组")
+    images = [validate_image_receipt(value) for value in images]
+    session = Session.load()
+    unique_code = str(time.time_ns() // 1000)
+    image_infos: list[dict[str, Any]] = []
+    for img in images:
+        image_infos.append({
+            "extraInfo": {"isH": "false", "isT": "false", "raw": "false"},
+            "isQrCode": False,
+            "url": img["url"],
+            "heightSize": img["height"],
+            "widthSize": img["width"],
+            "major": True,
+            "type": 0,
+            "status": "done",
+        })
+
+    raw = call(
+        session,
+        api="mtop.taobao.idle.kgraph.property.recommend",
+        data={
+            "title": title,
+            "lockCpv": False,
+            "multiSKU": False,
+            "publishScene": "mainPublish",
+            "scene": "newPublishChoice",
+            "description": title,
+            "imageInfos": image_infos,
+            "uniqueCode": unique_code,
+        },
+        version="2.0",
+        spm_cnt="a21ybx.publish.0.0",
+    )
+    predict = (raw.get("data", {}) or {}).get("categoryPredictResult", {}) or {}
+    if not predict.get("catId") or not predict.get("channelCatId") or not predict.get("tbCatId"):
+        raise GoofishError("类目推荐响应缺少选中分类身份，不能继续自动发布", raw=raw)
+    score, source = _selected_score(raw.get("data") or {}, predict)
+    return {
+        "cat_id": str(predict.get("catId", "")),
+        "cat_name": predict.get("catName", ""),
+        "channel_cat_id": str(predict.get("channelCatId", "")),
+        "tb_cat_id": str(predict.get("tbCatId", "")),
+        "confidence": score,
+        "confidence_source": source,
+        "confidence_kind": "model_score_not_calibrated_probability",
+        "unique_code": unique_code,
+        "raw": raw,
+    }

{goofish_cli-0.4.0 → goofish_cli-0.5.0}/src/goofish_cli/commands/item/delete.py

@@ -1,9 +1,8 @@
 """item delete — 下架商品。接口 com.taobao.idle.item.delete v1.1（写操作）"""
 
 from goofish_cli.core import Session, Strategy, command
-from goofish_cli.core.guard import watch
-from goofish_cli.core.limiter import acquire
 from goofish_cli.core.mtop import call
+from goofish_cli.core.write_operation import write_operation
 
 
 @command(
@@ -16,7 +15,7 @@ from goofish_cli.core.mtop import call
 )
 def delete(item_id: str) -> dict[str, object]:
     session = Session.load()
-    with acquire("item.write"), watch():
+    with write_operation(session, "item.write"):
         raw = call(
             session,
             api="com.taobao.idle.item.delete",

{goofish_cli-0.4.0 → goofish_cli-0.5.0}/src/goofish_cli/commands/item/get.py

@@ -3,6 +3,7 @@
 from typing import Any
 
 from goofish_cli.core import Session, Strategy, command
+from goofish_cli.core.item_data import normalize_item
 from goofish_cli.core.mtop import call
 
 
@@ -22,13 +23,4 @@ def get(item_id: str) -> dict[str, Any]:
         version="1.0",
         spm_cnt="a21ybx.item.0.0",
     )
-    data = raw.get("data", {}) or {}
-    track = data.get("trackParams", {}) or {}
-    return {
-        "item_id": track.get("id", item_id),
-        "title": track.get("title", ""),
-        "price": track.get("soldPrice") or track.get("price", ""),
-        "seller_nick": track.get("seller_nick", ""),
-        "status": track.get("itemStatus", ""),
-        "raw": raw,
-    }
+    return normalize_item(raw, str(item_id))