goofish-overview

goofish-cli Overview

What Is This

goofish-cli is a Python CLI + MCP server + Agent Skills three-in-one toolkit, letting an AI Agent operate Xianyu like a skilled seller: posting products, replying to messages, checking risk control, diagnosing the shop.

The tools you (the Agent) see through MCP in OpenClaw / Claude Code / Cursor all come from the same goofish server（FastMCP("goofish")）。

Tool Naming

This document uses the logical names from the registry (for example auth_status). When actually calling, add the prefix according to the host:

OpenClaw：goofish__auth_status
Claude Code / Cursor：mcp__goofish__auth_status

Division of Labor Among the Four Specialized Skills

When encountering a specific task,prefer jumping to the corresponding specialized skill, do not hard-infer within this overview:

User says	Activated skill
"Help me publish / list / put up an idle item"	`goofish-publish-item`
"Reply to buyer messages / check unread / bargain"	`goofish-reply-buyer`
"Pre-publish check / can I say this / risk control / what to do if throttled"	`goofish-risk-guard`
"Why does my shop have no traffic / why did exposure drop / diagnose it"	`goofish-shop-diagnosis`

Cross-skill collaboration:Before publishing / replying to messages, you should first let goofish-risk-guard run through it (to avoid absolutist words, outreach words). This is a recommended convention, not a hard requirement.

Account and Login State

Login state is checked by auth_status , returning {valid: bool}。
The auto-refresh chain is built in (v0.2.2 - v0.2.4): token expiry auto-renews, session expiry auto-clicks passport "quick entry", browser passwordless failure requires the user goofish auth login --qr。
The Agent should not actively call auth_login, this is a sensitive command (will overwrite disk cookies). Only when auth_status returns invalid, prompt the user to manually goofish auth login or goofish auth login --qr。
For account identity details, see references/accounts.md。

17 MCP Tools Quick Reference

The detailed list is in references/mcp-tools-index.md. Whether to read it depends on the task:

Post product → only need category_recommend / media_upload / location_default / item_publish
Reply to messages → only need message_watch / message_list_chats / message_history / message_send
Diagnosis → only need search_items / item_view / item_get
Login state diagnosis → auth_status
Delist/delete → item_delete
skills installation → skills_install(auxiliary tool, generally the Agent will not call it directly; run by the user in the terminal)

For example, the CLI's message list-chats corresponds to the logical name message_list_chats, when calling use the host prefix above.

Compliance Hard Red Lines (This Tool Is Prohibited from Assisting)

The following behaviors are written in the compliance statement and the skills refuse to guide：

Brushing orders / fake transactions / forging logistics
Mass device ID forgery / bypassing slider verification / evading bans
SaaS-style resale targeting the Xianyu platform
Malicious reviews / extortion scripts / outreach traffic diversion (WeChat/VX/威信/V 信 etc.)

If the user's request clearly violates any of the above,refuse to execute and explain the reason, do not look for bypass paths.

Risk Control Basic Concepts

See details in references/xianyu-concepts.md, here only give the Agent a thinking anchor:

Xianqi value: Seller credit score, below 80 starts restriction (search exposure -50% starting).
Traffic pool: Each new product has a 24-hour initial recommendation window; miss it and it's gone.
Price cut and title change: Lowering the price first and then changing the title after publishing triggers "fake promotion", and traffic is halved.
External contact words: WeChat / Weixin / Vxin / VX / +me all hit the rule; at best weight is reduced, at worst the account is banned.

Workflow conventions

Agents in goofish tasks please follow:

Before any write operation, first read auth_status, to avoid continuing to write after the token has expired → wasting effort.
item_publish / media_upload / message_send all have rate limits(token bucket 1 write/minute), do not send continuously in a short time. After RGV587 is triggered, the user must manually goofish auth reset-guard。
All external sending (posting products, sending messages) must have the user confirm the copy first, do not submit automatically.
Report status midway through multi-step tasks: what was completed in the previous step, what is planned for the next step. Xianyu tasks are usually 3-6 steps, and users expect a sense of progress.