goofish-cli 0.1.0__tar.gz → 0.2.1__tar.gz

goofish_cli-0.2.1/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-04-22
+
+### Changed
+- MCP script entry 新增 `goofish-cli`（与 package 名一致），`uvx goofish-cli` 即可直接拉起
+  MCP server。Claude Code 等 AI Agent 的 MCP 配置应使用这个入口。`goofish-mcp` 作为
+  次级入口保留，但只在本包已装到某 env 时可用（`pip install goofish-cli` /
+  `uv tool install goofish-cli` / `uvx --from goofish-cli goofish-mcp`）——单写
+  `uvx goofish-mcp` 仍会因 PyPI 无同名包解析失败。
+- `goofish_cli.__version__` 改为从 `importlib.metadata` 动态读取 package 版本，避免和
+  `pyproject.toml` 的 `version` 字段 drift（之前硬编码在 `__init__.py` 里，0.2.0 忘了同步）。
+
+## [0.2.0] - 2026-04-22
+
+### Added
+- **浏览器自动化子系统**（`core/browser.py`）：基于 Playwright + 系统 Chrome（`channel="chrome"`）
+  每次调用独立 tmp profile（`~/.goofish-cli/profiles/chrome-<tmp>/`），退出清理——
+  避开 Chrome `SingletonLock` 并发冲突。自动从 `Session.load()` 注入登录态。
+  默认 **headful**（headless 会被闲鱼识别为"非法访问"），CI 可 `GOOFISH_HEADLESS=1` 切回。
+- `goofish search items <query>` [`--limit N`]：浏览器路径搜索商品。对标 OpenCLI
+  `xianyu/search.js`，打开搜索页 → 自动滚动触发懒加载 → 从 DOM 提卡片。返回
+  `rank / item_id / title / price / condition / brand / location / badge / url`。
+- `goofish item view <item_id>`：浏览器视角看商品详情。在商品页上下文里调
+  `window.lib.mtop.request('mtop.taobao.idle.pc.detail')`，从 `itemDO/sellerDO/itemLabelExtList`
+  抽 20+ 字段（description / want_count / browse_count / 成色 / 品牌 / seller_score /
+  reply_ratio_24h / image_urls 等）。和现有 `item get`（CLI 直签，字段浅）并存。
+- `goofish message list-chats`：拉取会话列表（对应网页左栏），返回 `session_id`、对方昵称、
+  未读数、最后一条消息摘要、`sessionType`（1=真人 / 3=系统 / 6=互动 / 23=官方通知）。
+  AI Agent 可基于 `sessionType=1 and unread>0` 一键过滤"待回复真人会话"。
+- 接口：`mtop.taobao.idlemessage.pc.session.sync` v3.0，入参 `fetchNum`。
+- `list-chats --watch-secs N`：在 baseline 之上连 WS 收 N 秒 `ackDiff(pts=0)` 的历史推送，
+  补 h5 `session.sync` 漏掉的 cid（网页左栏 50 条也靠 ACCS 累积，单次 HTTP 拿不到）。每条
+  record 带 `source` 字段（`baseline` / `watch`）。watch 记录只有 cid / session_type /
+  item_id / ts，要正文要自己调 `message history <cid>`。
+
+### Changed
+- MCP handler 用 `asyncio.to_thread` 包装同步命令调用，避免 `asyncio.run()` 在已有事件
+  循环里抛 `RuntimeError` —— `search items` / `item view` / `list-chats --watch-secs` 现在
+  可以通过 MCP 正常调用。
+
+## [0.1.0] - 2026-04-21
+
+### Added
+- 初始发布。12 个命令覆盖闲鱼核心运营链路：
+  - `auth`：login / status / reset-guard
+  - `item`：get / publish / delete
+  - `media upload`、`category recommend`、`location default`
+  - `message`：watch / history / send（WebSocket IM）
+- `message watch` 三类事件分类输出（JSONL）：
+  - `event=message`：收到消息正文
+  - `event=read`：对方已读回执（带 msg_ids）
+  - `event=new_msg`：轻量新消息通知（无正文，需 history 拉取）
+- WebSocket 自动重连 + 指数退避
+- 全局速率限制（令牌桶 1 写/分钟）+ RGV587 熔断器
+- MCP server：`goofish-mcp` 同一命令集自动暴露给 Claude Code / Cursor / Codex
+- 统一输出契约 `--format json/yaml/table/md/csv`
+- 29 个单测
+
+### Notes
+- 本版本需要用户手动从浏览器导入 cookie（含 `unb` / `_m_h5_tk` / `x5sec`）
+- 遇到 `RGV587_ERROR` 风控时，需在浏览器完成滑块验证并**重新导出**带 `x5sec` 的 cookie
+
+[Unreleased]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/fancyboi999/goofish-cli/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/fancyboi999/goofish-cli/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/fancyboi999/goofish-cli/releases/tag/v0.1.0

{goofish_cli-0.1.0 → goofish_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: goofish-cli
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -18,8 +18,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Internet :: WWW/HTTP
 Requires-Python: >=3.11
+Requires-Dist: browser-cookie3>=0.20
 Requires-Dist: loguru>=0.7
 Requires-Dist: mcp>=1.2
+Requires-Dist: playwright>=1.58.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyexecjs>=1.5
 Requires-Dist: pyyaml>=6.0
@@ -56,7 +58,7 @@ Description-Content-Type: text/markdown
 **同一份定义**同时输出给三种消费者：
 
 - 👨‍💻 **人类**：`goofish item get 12345 --format table`
-- 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-mcp` → 自动注册成 MCP tool
+- 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-cli` → 自动注册成 MCP tool
 - 🧩 **Claude Skills**（规划中）：`skills/` 目录直接放进 Agent
 
 > 架构思想来自 [opencli](https://github.com/jackwener/opencli) 的 single-registry 设计。
@@ -65,7 +67,7 @@ Description-Content-Type: text/markdown
 
 ## ✨ 核心特性
 
-- 🔐 **12 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发
+- 🔐 **13 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
 - 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
@@ -116,6 +118,9 @@ $ goofish list-commands --format table
 | `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 输出） | ❌ |
@@ -210,7 +215,7 @@ $ goofish item publish \
   "mcpServers": {
     "goofish": {
       "command": "uvx",
-      "args": ["goofish-mcp"]
+      "args": ["goofish-cli"]
     }
   }
 }
@@ -226,19 +231,21 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 |---|---|
 | 11 个核心 mtop 接口 | 发布/下架/查询/图片/类目/地址/IM 全覆盖 |
 | CLI + `--format` 多格式输出 | `json` / `yaml` / `table` / `md` / `csv`，人机两用 |
-| MCP Server | `uvx goofish-mcp` 一行接入 Claude Code / Cursor |
+| MCP Server | `uvx goofish-cli` 一行接入 Claude Code / Cursor |
 | WebSocket 批量 push 全量解码 | 一帧多条消息全部还原，不丢单 |
 | WebSocket 自动重连 | 断线自退避重连，长跑无感知 |
 | 已读回执 / typing / 新消息通知分类 | `/s/sync` 元事件结构化为三类 JSONL |
 | 全局限流 + 风控熔断 | 令牌桶 1 写/分钟 + RGV587 自动熔断 |
-| 单元测试 | 29 个，ruff 零告警 |
-| 包分发 | `pip install goofish-cli` / `uvx goofish-mcp` |
+| 单元测试 | 33 个，ruff 零告警 |
+| 包分发 | `pip install goofish-cli` / `uvx goofish-cli` |
 
 ---
 
 ## 🗺 Roadmap
 
 - [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`（订单状态查询 / 发货）
@@ -254,7 +261,7 @@ cd goofish-cli
 uv venv --python 3.11
 uv pip install -e ".[dev]"
 
-uv run pytest                # 29 测全绿
+uv run pytest                # 33 测全绿
 uv run ruff check src tests  # 零告警
 ```
 

{goofish_cli-0.1.0 → goofish_cli-0.2.1}/README.md

@@ -19,7 +19,7 @@
 **同一份定义**同时输出给三种消费者：
 
 - 👨‍💻 **人类**：`goofish item get 12345 --format table`
-- 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-mcp` → 自动注册成 MCP tool
+- 🤖 **AI Agent（Claude Code / Cursor / Codex）**：`uvx goofish-cli` → 自动注册成 MCP tool
 - 🧩 **Claude Skills**（规划中）：`skills/` 目录直接放进 Agent
 
 > 架构思想来自 [opencli](https://github.com/jackwener/opencli) 的 single-registry 设计。
@@ -28,7 +28,7 @@
 
 ## ✨ 核心特性
 
-- 🔐 **12 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发
+- 🔐 **13 个命令覆盖核心链路**：发布、下架、查询、图片上传、AI 类目识别、默认地址、IM 收发 + 会话列表
 - 📡 **真·实时 IM**：WebSocket 长连 + 自动重连 + **三类事件分类输出**
   - `event=message`（收到消息）· `event=read`（已读回执）· `event=new_msg`（轻量通知）
 - 🛡 **内置风控护栏**：令牌桶限流（1 写/分钟）+ RGV587 自动熔断
@@ -79,6 +79,9 @@ $ goofish list-commands --format table
 | `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 输出） | ❌ |
@@ -173,7 +176,7 @@ $ goofish item publish \
   "mcpServers": {
     "goofish": {
       "command": "uvx",
-      "args": ["goofish-mcp"]
+      "args": ["goofish-cli"]
     }
   }
 }
@@ -189,19 +192,21 @@ Claude 会自动把全部命令看成 tool：`goofish_item_get` / `goofish_item_
 |---|---|
 | 11 个核心 mtop 接口 | 发布/下架/查询/图片/类目/地址/IM 全覆盖 |
 | CLI + `--format` 多格式输出 | `json` / `yaml` / `table` / `md` / `csv`，人机两用 |
-| MCP Server | `uvx goofish-mcp` 一行接入 Claude Code / Cursor |
+| MCP Server | `uvx goofish-cli` 一行接入 Claude Code / Cursor |
 | WebSocket 批量 push 全量解码 | 一帧多条消息全部还原，不丢单 |
 | WebSocket 自动重连 | 断线自退避重连，长跑无感知 |
 | 已读回执 / typing / 新消息通知分类 | `/s/sync` 元事件结构化为三类 JSONL |
 | 全局限流 + 风控熔断 | 令牌桶 1 写/分钟 + RGV587 自动熔断 |
-| 单元测试 | 29 个，ruff 零告警 |
-| 包分发 | `pip install goofish-cli` / `uvx goofish-mcp` |
+| 单元测试 | 33 个，ruff 零告警 |
+| 包分发 | `pip install goofish-cli` / `uvx goofish-cli` |
 
 ---
 
 ## 🗺 Roadmap
 
 - [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`（订单状态查询 / 发货）
@@ -217,7 +222,7 @@ cd goofish-cli
 uv venv --python 3.11
 uv pip install -e ".[dev]"
 
-uv run pytest                # 29 测全绿
+uv run pytest                # 33 测全绿
 uv run ruff check src tests  # 零告警
 ```
 

{goofish_cli-0.1.0 → goofish_cli-0.2.1}/docs/mcp-setup.md

@@ -9,7 +9,7 @@
   "mcpServers": {
     "goofish": {
       "command": "uvx",
-      "args": ["goofish-mcp"]
+      "args": ["goofish-cli"]
     }
   }
 }
@@ -21,7 +21,7 @@
 {
   "mcpServers": {
     "goofish": {
-      "command": "/Users/you/Desktop/goofish-cli/.venv/bin/goofish-mcp"
+      "command": "/Users/you/Desktop/goofish-cli/.venv/bin/goofish-cli"
     }
   }
 }

{goofish_cli-0.1.0 → goofish_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "goofish-cli"
-version = "0.1.0"
+version = "0.2.1"
 description = "闲鱼 CLI — 支持 MCP，未来支持 Claude Skills。为 AI Agent 提供闲鱼自动化基础能力。"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -30,6 +30,8 @@ dependencies = [
   "tenacity>=8.2",
   "mcp>=1.2",
   "websockets>=13",
+  "browser-cookie3>=0.20",
+  "playwright>=1.58.0",
 ]
 
 [project.optional-dependencies]
@@ -42,6 +44,14 @@ dev = [
 
 [project.scripts]
 goofish = "goofish_cli.cli:app"
+# MCP server 入口。名字与 package 名一致，`uvx goofish-cli` 可直接拉起（uvx 默认按
+# command 名查包，和 scripts 名对齐就不用 --from 绕弯）。这是 Claude Code 等 AI Agent
+# 配 MCP 时的推荐写法。
+goofish-cli = "goofish_cli.mcp_server:main"
+# 保留 `goofish-mcp` 别名只在 **本包已装** 时可用（`pip install goofish-cli` /
+# `uv tool install goofish-cli` / `uvx --from goofish-cli goofish-mcp`）。单独的
+# `uvx goofish-mcp` 仍会因 PyPI 无同名包解析失败 —— 这不是别名能救的，Claude Code
+# MCP 配置必须用上面的 `uvx goofish-cli`。
 goofish-mcp = "goofish_cli.mcp_server:main"
 
 [project.urls]

goofish_cli-0.2.1/src/goofish_cli/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("goofish-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

goofish_cli-0.2.1/src/goofish_cli/commands/auth/login.py

@@ -0,0 +1,116 @@
+"""auth login — 导入闲鱼登录态到 ~/.goofish-cli/cookies.json。
+
+默认行为（零参数）：从本机所有已装浏览器中自动探测 → 最低认知负荷。
+支持的浏览器：Chrome / Edge / Brave / Chromium / Opera / OperaGX / Vivaldi
+            / Arc / Firefox / LibreWolf / Safari（由 browser_cookie3 提供）。
+
+降级路径：
+
+- `auth login`                     自动 auto-detect（推荐）
+- `auth login --browser edge`      指定单个浏览器
+- `auth login <path>`              从 JSON 文件导入
+- `auth login <cookie_str> --raw`  粘贴 "k=v; k=v" 字符串
+
+触发条件：
+1. 所有浏览器都没拿到 → 报错里列出手动兜底方案
+2. 环境变量 GOOFISH_NO_CHROME_BOOTSTRAP=1 只影响其它命令启动时的
+   Session.load 自动 bootstrap，不影响本命令。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from goofish_cli.core import Strategy, command
+from goofish_cli.core.errors import AuthRequiredError
+from goofish_cli.core.session import DEFAULT_COOKIE_PATH, write_cookies_json
+
+
+@command(
+    namespace="auth",
+    name="login",
+    description="导入登录态（默认从本机浏览器 auto-detect；支持 Chrome/Edge/Brave/Safari/Firefox 等）",
+    strategy=Strategy.PUBLIC,
+    columns=["source", "path", "unb", "tracknick", "cookies_count"],
+)
+def login(
+    source: str | None = None,
+    *,
+    raw: bool = False,
+    browser: str = "auto",
+) -> dict[str, object]:
+    target = DEFAULT_COOKIE_PATH
+
+    if source is None:
+        if raw:
+            # --raw 要求紧跟 cookie 字符串；如果没传 source，说明用户漏了参数——
+            # 不能静默走浏览器 auto-detect，否则 --raw 被吞，用户会困惑。
+            raise ValueError(
+                "--raw 需要配合 cookie 字符串使用，如："
+                "goofish auth login 'unb=...; _m_h5_tk=...' --raw"
+            )
+        cookies, source_label = _pull_from_browser(browser)
+    elif raw:
+        cookies = _parse_raw(source)
+        source_label = "raw"
+    else:
+        p = Path(source).expanduser()
+        cookies = _parse_json(p.read_text())
+        source_label = f"file:{p}"
+
+    if "unb" not in cookies or "_m_h5_tk" not in cookies:
+        raise AuthRequiredError(
+            "cookie 缺失关键字段 unb / _m_h5_tk。"
+            "请先在浏览器里登录 https://www.goofish.com 再试。"
+        )
+
+    write_cookies_json(target, cookies)
+
+    return {
+        "source": source_label,
+        "path": str(target),
+        "unb": cookies.get("unb", ""),
+        "tracknick": cookies.get("tracknick", ""),
+        "cookies_count": len(cookies),
+    }
+
+
+def _pull_from_browser(browser: str) -> tuple[dict[str, str], str]:
+    from goofish_cli.core.browser_cookie import (
+        BrowserCookieError,
+        available_browsers,
+        extract_goofish_cookies,
+    )
+    try:
+        used, cookies = extract_goofish_cookies(browser=browser)
+        return cookies, f"browser:{used}"
+    except BrowserCookieError as e:
+        supported = ", ".join(available_browsers())
+        raise AuthRequiredError(
+            f"浏览器登录态导入失败：{e}\n"
+            f"兜底方案：\n"
+            f"  1. 确认已在任一浏览器里登录 https://www.goofish.com 后重试\n"
+            f"  2. 指定具体浏览器：`goofish auth login --browser edge`（支持：{supported}）\n"
+            f"  3. 手动导出 JSON：`goofish auth login ~/Downloads/cookies.json`\n"
+            f"  4. 粘 cookie 字符串：`goofish auth login 'unb=...; _m_h5_tk=...' --raw`"
+        ) from e
+
+
+def _parse_raw(raw: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for part in raw.split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        k, _, v = part.partition("=")
+        out[k.strip()] = v.strip()
+    return out
+
+
+def _parse_json(text: str) -> dict[str, str]:
+    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}
+    if isinstance(data, dict):
+        return {str(k): str(v) for k, v in data.items()}
+    raise AuthRequiredError("cookie JSON 格式不识别（需 list 或 dict）")

goofish_cli-0.2.1/src/goofish_cli/commands/item/view.py

@@ -0,0 +1,182 @@
+"""item view — 浏览器视角的商品详情。对标 OpenCLI `xianyu/item.js`。
+
+`item get` 已经在 CLI 里直签调 `mtop.taobao.idle.pc.detail` v1.0，字段浅抽（5 项）。
+`item view` 在真实 Chrome 的商品页上下文里调同一 API（走 `window.lib.mtop.request`），
+好处：
+
+1. **字段完整**：直接按 OpenCLI 的提取器从 `data.itemDO / data.sellerDO / itemLabelExtList`
+   抽 20+ 字段（description / want_count / browse_count / 成色 / 品牌 / image_urls /
+   seller_score / reply_ratio_24h 等）。
+2. **抗风控兜底**：CLI 直签偶尔遇到 x5sec / h5_token 失效，浏览器路径作为备份链路。
+
+保留 `item get`（快且不需要 Chrome），两条路并存。用户根据场景选。
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from typing import Any
+
+from goofish_cli.core import Strategy, command
+from goofish_cli.core.browser import goofish_page
+from goofish_cli.core.errors import AuthRequiredError, GoofishError
+
+
+def _normalize_item_id(value: Any) -> str:
+    s = str(value or "").strip()
+    if not re.fullmatch(r"\d+", s):
+        raise GoofishError(f"item_id 必须是数字，收到：{value!r}")
+    return s
+
+
+def _build_item_url(item_id: str) -> str:
+    return f"https://www.goofish.com/item?id={item_id}"
+
+
+# 页面上下文里运行的抽取脚本。直接复用 OpenCLI 的提取逻辑（DOM 文案检查 + mtop 调用）。
+_FETCH_JS = r"""
+(itemId) => (async () => {
+  const clean = (v) => String(v ?? '').replace(/\s+/g, ' ').trim();
+  const extractRetCode = (ret) => {
+    const first = Array.isArray(ret) ? ret[0] : '';
+    return clean(first).split('::')[0] || '';
+  };
+  const waitFor = async (predicate, timeoutMs = 5000) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      if (predicate()) return true;
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    return false;
+  };
+
+  const bodyText = document.body?.innerText || '';
+  // 注意：「登录后」在页脚也会出现，不能作为 auth 判定；真正的未登录靠 mtop 返回的
+  // FAIL_SYS_SESSION_EXPIRED 来判，这里只拦显式验证码/风控页。
+  if (/验证码|安全验证|异常访问/.test(bodyText)) return { error: 'blocked' };
+
+  await waitFor(() => window.lib?.mtop?.request);
+  if (!window.lib || !window.lib.mtop || typeof window.lib.mtop.request !== 'function') {
+    return { error: 'mtop-not-ready' };
+  }
+
+  let response;
+  try {
+    response = await window.lib.mtop.request({
+      api: 'mtop.taobao.idle.pc.detail',
+      data: { itemId: String(itemId) },
+      type: 'POST',
+      v: '1.0',
+      dataType: 'json',
+      needLogin: false,
+      needLoginPC: false,
+      sessionOption: 'AutoLoginOnly',
+      ecode: 0,
+    });
+  } catch (error) {
+    const ret = error?.ret || [];
+    return {
+      error: 'mtop-request-failed',
+      error_code: extractRetCode(ret),
+      error_message: clean(Array.isArray(ret) ? ret.join(' | ') : error?.message || String(error)),
+    };
+  }
+
+  const retCode = extractRetCode(response?.ret || []);
+  if (retCode && retCode !== 'SUCCESS') {
+    return {
+      error: 'mtop-response-error',
+      error_code: retCode,
+      error_message: clean((response?.ret || []).join(' | ')),
+    };
+  }
+
+  const data = response?.data || {};
+  const item = data.itemDO || {};
+  const seller = data.sellerDO || {};
+  const labels = Array.isArray(item.itemLabelExtList) ? item.itemLabelExtList : [];
+  const findLabel = (name) => labels.find((l) => clean(l.propertyText) === name)?.text || '';
+  const images = Array.isArray(item.imageInfos)
+    ? item.imageInfos.map((e) => e?.url).filter(Boolean)
+    : [];
+
+  return {
+    item_id: clean(item.itemId || itemId),
+    title: clean(item.title || ''),
+    description: clean(item.desc || ''),
+    price: clean('¥' + (item.soldPrice || item.defaultPrice || '')).replace(/^¥\s*$/, ''),
+    original_price: clean(item.originalPrice || ''),
+    want_count: String(item.wantCnt ?? ''),
+    collect_count: String(item.collectCnt ?? ''),
+    browse_count: String(item.browseCnt ?? ''),
+    status: clean(item.itemStatusStr || ''),
+    condition: clean(findLabel('成色')),
+    brand: clean(findLabel('品牌')),
+    category: clean(findLabel('分类')),
+    location: clean(seller.publishCity || seller.city || ''),
+    seller_name: clean(seller.nick || seller.uniqueName || ''),
+    seller_id: String(seller.sellerId || ''),
+    seller_score: clean(seller.xianyuSummary || ''),
+    reply_ratio_24h: clean(seller.replyRatio24h || ''),
+    reply_interval: clean(seller.replyInterval || ''),
+    seller_url: seller.sellerId ? 'https://www.goofish.com/personal?userId=' + seller.sellerId : '',
+    image_count: String(images.length),
+    image_urls: images,
+  };
+})()
+"""
+
+
+async def _run(item_id: str) -> dict[str, Any]:
+    url = _build_item_url(item_id)
+    async with goofish_page() as page:
+        await page.goto(url, wait_until="domcontentloaded")
+        await page.wait_for_timeout(2000)
+        result = await page.evaluate(_FETCH_JS, item_id)
+
+    if not isinstance(result, dict):
+        raise GoofishError("商品详情页返回结构非预期")
+
+    err = result.get("error")
+    if err == "blocked":
+        raise GoofishError("商品详情页被验证码/安全验证拦截，触发风控")
+    if err == "mtop-not-ready":
+        raise GoofishError("页面 window.lib.mtop 未就绪（等待超时），页面加载异常")
+
+    # auth 判定统一走 mtop 返回的 error_code/error_message 里的 SESSION_EXPIRED，
+    # 不再依赖 body 文案正则（"登录后" 在页脚也会出现，误报多）。
+    err_code = str(result.get("error_code") or "")
+    err_msg = str(result.get("error_message") or "")
+    if re.search(r"FAIL_SYS_SESSION_EXPIRED|SESSION_EXPIRED", err_code + " " + err_msg):
+        raise AuthRequiredError("mtop 返回 session 过期：" + (err_msg or err_code))
+    if err:
+        raise GoofishError(f"mtop 调用失败 [{err_code or err}]: {err_msg or '无详情'}")
+    if not result.get("title"):
+        raise GoofishError(f"未拿到商品 {item_id} 的标题，接口返回为空")
+
+    return result
+
+
+@command(
+    namespace="item",
+    name="view",
+    description="浏览器视角查看商品详情（字段比 item get 更全，抗风控）",
+    strategy=Strategy.COOKIE,
+    columns=[
+        "item_id", "title", "price", "condition", "brand", "location",
+        "seller_name", "want_count", "browse_count",
+    ],
+)
+def view(item_id: str) -> dict[str, Any]:
+    normalized = _normalize_item_id(item_id)
+    # MCP / table 渲染依赖 dict；image_urls 是列表（JSON 里保留，table 里压成长度）
+    result = asyncio.run(_run(normalized))
+    result["_image_urls_json"] = json.dumps(result.get("image_urls", []), ensure_ascii=False)
+    return result
+
+
+__test__ = {
+    "_normalize_item_id": _normalize_item_id,
+    "_build_item_url": _build_item_url,
+}