一套在本机运行、人工审批、失败即停的闲鱼（Xianyu / Goofish）商品内容生成与发布工作流：导入自有或已授权商品资料，生成真实文案和三张带品牌水印的图片，经人工完整复核后，由最小权限 Chrome 扩展填写发布页，并用商品 URL、item ID、标题和价格核验发布回执。
关键词：闲鱼自动化、闲鱼自动发布、Xianyu automation、Goofish listing automation、AI 商品文案、商品图片水印、Chrome extension、SQLite workflow、human-in-the-loop。
本项目不是闲鱼或阿里巴巴官方产品，与其不存在隶属、授权或背书关系。使用者必须遵守平台规则、当地法律以及商品和素材的权利边界。
手工经营闲鱼时，常见的重复劳动和风险包括：
- 商品资料分散，重复复制标题、事实、价格和发货方式；
- 文案和图片批量制作耗时，品牌水印不统一；
- 自动化工具直接保存 Cookie、搬运竞品、绕过验证码或反复点击发布；
- 页面变化后仍继续执行，产生错价、错字段或重复商品；
- “点过发布按钮”被误判为发布成功，没有可核对的商品回执。
本项目把这些步骤收敛成一条可审计流程：
flowchart LR
A["自有或已授权商品源"] --> B["事实校验与修订去重"]
B --> C["生成文案与 3 张水印图"]
C --> D["人工查看完整内容并复核"]
D --> E["审批队列"]
E --> F["Chrome 扩展填写新发布页"]
F --> G["严格核验商品回执"]
F --> H["验证码、风控或页面变化"]
H --> I["全局暂停并等待人工处理"]
| 能力 | 实现 |
|---|---|
| 授权商品导入 | CSV、JSON、本人闲鱼个人页、已登录淘宝“我的商品”；拒绝任意单商品页和其他用户页面 |
| 内容生成 | 默认离线、确定性、基于商品事实；可选显式启用 OpenAI-compatible provider |
| 图片生成 | 自动生成 3 张 1080×1080 方图，包含中文排版、平铺水印和品牌标识 |
| 人工复核 | 完整显示来源事实、文案、价格、发货方式和全部图片；复核哈希绑定内容和图片字节 |
| 发布审批 | 任务审批和全局发布开关双重门槛，未审批任务不能执行 |
| 浏览器执行 | Chrome Manifest V3 扩展，仅在窄路径页面工作，不读取 Cookie、不申请 debugger |
| 页面漂移保护 | 语义字段锚定、24 小时真实页面预检、空白表单检查、上传完成证据和风险词熔断 |
| 状态与恢复 | SQLite 状态机、修订去重、独占租约、提交前恢复、提交后禁止盲目重试 |
| 严格发布回执 | 仅接受匹配的 goofish.com/item HTTPS URL、唯一 item ID、精确标题和数值价格 |
| 本地运维 | 私有权限、日志轮转、校验和备份、恢复演练、可选 macOS 登录启动 |
本项目有意不提供以下能力：
- 不读取、导出或注入 Cookie；
- 不申请 Chrome
cookies、debugger或全站tabs权限； - 不使用 stealth、指纹伪装、验证码绕过、无头反检测或养号逻辑；
- 不搬运竞争对手商品，不去除他人水印，不抓取未授权素材；
- 不在提交结果不确定时自动重试；
- 不承诺平台页面永久不变，也不把本地测试等同于账号侧真实发布成功。
出现验证码、风控提示、页面契约变化、图片上传证据不足或发布回执不确定时，系统会关闭全局发布开关并停止后续任务。
- Python 回归：41 项通过；
- Node.js 回归：20 项通过；
- Python 编译、JavaScript 语法、Chrome 权限、LaunchAgent 和备份/恢复检查通过；
- 已在真实登录发布页完成只读/可逆字段核对；
- 已完成扩展安装、配对和真实页面语义预检，基础契约签名为
5dd2c232； - 尚未把任何真实商品发布声明作为本仓库的验收证据。
当前维护和真实页面预检环境是 macOS、Google Chrome 和 Python 3.11+。Windows/Linux 上的 Python 服务可能运行，但启动脚本、登录服务和真实发布流程尚未作为受支持组合验证。
- macOS 13 或更高版本；
- Google Chrome；
- Python 3.11 或更高版本；
- Node.js 20 或更高版本仅用于运行 JavaScript 测试。
git clone https://github.com/harringtonwalker/xianyu-automation.git
cd xianyu-automation
./scripts/setup.command安装脚本会在项目内创建 .venv/，并安装锁定版本的 Pillow。运行数据、令牌、日志和备份不会进入 Git。
./scripts/start.command浏览器打开：
http://127.0.0.1:8766
默认发布总开关处于关闭状态。
- 打开
chrome://extensions； - 开启“开发者模式”；
- 点击“加载已解压的扩展程序”；
- 选择本仓库的
extension/目录； - 不要删除或移动这个目录；路径变化后需要在 Chrome 中重新加载。
- 在本地控制台的“品牌与扩展配对”区域点击“复制配对令牌”；
- 打开扩展“选项”，粘贴令牌；
- 本地服务地址保持
http://127.0.0.1:8766； - 如需从本人闲鱼个人页导入，填写该个人页 URL 中的
userId； - 点击“保存并测试连接”。
配对令牌相当于本机发布队列钥匙，不要截图、分享或提交到 Git。
- 启动本地服务并保持同一 Chrome 已登录闲鱼；
- 设置品牌名和水印文字；
- 从控制台导入 CSV/JSON，或从绑定的本人库存页面导入；
- 点击“生成全部待处理内容”；
- 打开每条任务，检查事实、完整文案、价格、发货方式和三张图片；
- 输入
确认已核对完整文案与商品事实完成复核； - 勾选任务并按页面要求输入
确认发布N条； - 在空白
https://www.goofish.com/publish页面运行扩展预检； - 确认预检仍在 24 小时有效期内，再输入
启用自动发布； - 观察任务是否取得严格商品回执；完成批次后输入
关闭自动发布。
账号登录、验证码/风控、首次真实发布以及每个新批次的内容审批都属于人工动作门。
模板：
必填字段：
source_type：local、taobao-own、xianyu-own、authorized-url；external_id或sku：长期稳定且唯一的商品标识；title；price；delivery：包邮、按距离计费、一口价、无需邮寄；rights_confirmed=true；facts，或 CSV 中至少一个fact_前缀字段。
location 必须留空，由发布页保持账号默认所在地。source_type=authorized-url 时必须提供 source_url。一口价 必须填写有效的 shipping_fee，其他发货方式不能携带残留固定邮费。
同一个 external_id 的事实、价格、发货方式或来源变化会创建新修订，并把尚未执行的旧任务置为 SUPERSEDED。完全相同的当前资料会跳过。
| 状态 | 含义 |
|---|---|
INGESTED |
已导入，等待生成 |
PENDING_APPROVAL |
内容已生成，等待完整复核和审批 |
APPROVED |
已进入队列；全局开关关闭时不会执行 |
RUNNING |
扩展已取得短租约，尚未开始提交 |
AWAITING_RECEIPT |
已触发提交；禁止自动重试，等待同一页面回执 |
PUBLISHED |
已取得并校验商品 URL、item ID、标题和价格 |
BLOCKED |
风控、页面漂移或回执不确定，系统已全局暂停 |
FAILED |
执行失败，需要核查原因后重新审批 |
SUPERSEDED |
商品已有新修订，旧任务永久失效 |
提交后五分钟仍没有匹配回执时，任务进入 RECEIPT_UNCERTAIN，全局发布开关关闭。此时必须在“我的闲鱼”人工对账：填写严格匹配且未被其他任务使用的商品回执，或明确确认未发布后再重新排队。
默认模式不需要 API Key。只有同时设置以下变量，系统才会调用外部模型：
export XIANYU_AI_ENDPOINT="https://provider.example/v1"
export XIANYU_AI_API_KEY="..."
export XIANYU_AI_MODEL="..."
export XIANYU_ALLOW_PAID_PROVIDER=1API Key 只应存放在环境变量或本机秘密管理器中，不要写入仓库、SQLite、截图或日志。
完整本地验证：
./scripts/verify.command备份：
./scripts/backup.command无写入恢复演练：
./scripts/restore.command /完整路径/backups/YYYYMMDD-HHMMSS --check-only正式恢复会先校验 SHA-256、SQLite、配置和迁移状态，并保留现有 data/ 作为可回滚目录。
可选 macOS 登录启动会写入 ~/Library/LaunchAgents/io.github.harringtonwalker.xianyu-ops.plist：
./scripts/install-login-service.command卸载脚本会停止服务并把 plist 移到废纸篓：
./scripts/uninstall-login-service.commandxianyu_ops/ Python 本地控制台、策略、内容、图片和 SQLite 状态机
extension/ 最小权限 Chrome Manifest V3 扩展
static/ 本地控制台前端
scripts/ 安装、启动、验证、备份、恢复和登录服务
samples/ 脱敏商品导入模板
tests/ Python 与 Node.js 回归测试
docs/ 架构、验证证据和平台契约
llms.txt 面向 AI 工具的项目摘要与权威入口
架构和不变量详见 docs/architecture.md。
请先阅读 CONTRIBUTING.md 和 SECURITY.md。本项目欢迎页面契约修复、测试、恢复能力、文档和合规性改进，但不会接受验证码绕过、Cookie 导出、竞品搬运、反检测或取消人工发布审批的功能。
Xianyu Automation is a local, approval-gated workflow for Xianyu/Goofish listing operations. It imports owned or explicitly authorized product facts, generates truthful copy and three branded 1080×1080 images, requires a human review bound to the exact content, fills a fresh publish page through a least-privilege Chrome MV3 extension, and accepts success only after a strict item receipt check.
The system deliberately does not export cookies, request debugger privileges, bypass CAPTCHA or risk controls, scrape competitors, remove watermarks, or retry an uncertain submission. It is an independent open-source project and is not affiliated with Xianyu or Alibaba.
For machine-readable project context, see llms.txt.
Apache License 2.0. “闲鱼”, “Xianyu”, “Goofish” and related marks belong to their respective owners.