xianyu-publish

xianyu-publish

When publishing a product, only use this project's CLI:

python scripts/cli.py <command>

Applicable Scenarios

The user asks to publish, list, test-publish, or fill in a publishing draft.
The user provides a product title, description, price, and image materials that need to be uploaded to Xianyu.
The user asks to fill in the form for review first, then confirm publishing.
The user explicitly asks for one-step publishing.

Material Source Strategy

For formal publishing, prioritize using the real product image materials provided by the user.

Local image: pass the absolute path directly to --images。
Image URL: first download it to a local temporary directory, then pass the local path to --images。
Images generated by design tools or other Agents: they must also be saved as local image paths first, then uploaded.
ImageGen is not a required dependency of this Skill; it can only be used when the current Agent explicitly has it available and the user needs to generate materials.
Do not upload images containing QR codes, phone numbers, WeChat IDs, external links, obvious watermarks, off-platform traffic diversion, exaggerated promises, or sensitive text.

The CLI currently uploads images through the browser file upload control, so --images must ultimately be a local file path.

Recommended Publishing Process

Execute check-login。
Prepare the description file and local image paths.
Execute fill-publish, only fill in the form without clicking publish.
Read the returned category_resolution、selected、unsupported_category_marker and the page prompt.
Have the user confirm the images, description, price, category, and platform prompts in Chrome.
After the user confirms, execute click-publish。
After publishing, use get-item-detail or get-item-stats to look up the product.

python scripts/cli.py fill-publish \
  --description-file D:/abs/desc.txt \
  --price 29.9 \
  --images D:/abs/cover.png D:/abs/detail.png \
  --shipping "无需邮寄"

python scripts/cli.py click-publish
python scripts/cli.py get-item-stats --item-id ITEM_ID

One-step Publishing

Use when the user explicitly asks to publish directly:

python scripts/cli.py publish \
  --description-file D:/abs/desc.txt \
  --price 29.9 \
  --images D:/abs/cover.png D:/abs/detail.png \
  --shipping "无需邮寄"

One-step publishing still returns the final URL, title, category result, and publishing status. If the product detail page is not detected, do not claim that publishing succeeded.

Key Parameters

--description: pass in the product description directly.
--description-file: read the description from a local UTF-8 text file, recommended for formal publishing.
--price: product price.
--original-price: original price, optional.
--images: one or more local image paths.
--category: category name, or auto-safe / auto / next-supported; default auto-safe。
--pricing-unit: pricing method, for example 元/次。
--scenario: application scenario, for example PPT。
--shipping: shipping method, commonly used for service products 无需邮寄。

Category Strategy

By default, use --category auto-safe. Do not hard-code in the Skill or script "which category a category that does not support web publishing should be mapped to".

The script handles categories based on page feedback:

First accept the category automatically recognized by Xianyu.
If the user explicitly passes in --category "分类名", select that category first.
Check whether the page shows prompts such as "Publishing this category is not currently supported on the web version" or "Please use the Xianyu APP to scan the QR code and continue publishing".
If a prompt appears, open the category dropdown and try the adjacent candidate categories after the current category one by one.
After each switch, re-check the page prompt; once the prompt disappears, keep that category.
If it is still unsupported after consecutive attempts, return the list of attempts and let the user confirm manually.

In the returned result, category_resolution is used to explain the classification process:

requested: the category requested by the user, or auto-safe。
initial: the page's initial/automatically detected category.
final: the final retained category.
changed: whether a switch occurred.
attempted: the candidate categories that were attempted and whether they are supported.
unsupported_marker_seen: whether a web-side unsupported prompt was detected.
reason: the reason for switching or not switching.

Output interpretation

success: true only indicates that the command executed successfully, not necessarily that the product was published; whether publishing succeeded is determined by click-publish / publish 's final URL and status.
selected.category being true indicates that the final category has been read.
selected.pricing_unit / selected.scenario being false may mean that the category has no corresponding field, and is not necessarily a failure.
unsupported_category_marker: true indicates that the page still has an unsupported prompt, which must be handled before publishing.
page_text_preview , correct them before publishing.

Failure handling

Image recognized as a QR code: replace the image and remove QR-code-like graphics, contact information, and dense code blocks.
Category does not support web-side publishing: use the default auto-safe or reselect a more appropriate category.
After clicking the publish button, the product detail page is not entered: return the page prompt; do not fake success.
The product disappears quickly after publishing: it may have entered review, been taken down, or triggered risk control; check messages and the My Products list.
Image URL cannot be uploaded: first download it to a local path, then pass it to --images。

Confirmation strategy

Stay consistent with xiaohongshu-skills : the documentation layer requires confirmation, while the CLI layer retains full capability. Before publishing, the user should confirm the final description, price, images, and category; when the user explicitly requests direct publishing, you may execute publish。