taiyi/xiaohongshufabu

Fork 0

taiyi 2a3eac2d49 第一次提交

2026-07-21 21:17:20 +08:00

14 KiB

Raw Permalink Blame History

小红书千帆店铺矩阵工具 —— 项目实施计划书

版本：v1.0　　日期：2026-07-18

一、项目背景与目标

1.1 背景

运营方需要同时管理多个小红书千帆店铺，人工逐条撰写商品笔记、上传发布效率低，且难以规模化。本项目旨在打造一套"内容工厂 + 分发工具"，实现：

店铺与商品信息的集中管理
商品笔记（文案+图片）的批量 AI 生成
多浏览器并行、自动化批量发布

1.2 目标产出

本地服务（数据与生成中枢）：Node.js + SQLite，统一管理数据、代理调用 AI 接口
网页版管理端：账号管理、商品管理、笔记审核、模型与提示词配置
浏览器插件（执行端）：可在多个浏览器实例中并行运行，自动在千帆发布页完成选品、上传图片、填写文案并发布

1.3 非目标（本期不做）

不做云端多人协作（如需团队共享，后续可扩展为局域网/云端部署）
不做小红书官方 API 对接（官方未开放笔记发布接口，仍走浏览器自动化路径）
不做多平台（抖音/快手等）适配，本期仅聚焦小红书千帆

二、总体架构

                        ┌───────────────────────┐
                        │      本地服务 (Local Service)   │
                        │  Node.js + Express + SQLite     │
                        │  - 数据存储（店铺/商品/笔记/配置）│
                        │  - AI 接口代理（Deepseek/生图）  │
                        │  - 图片文件管理与去重             │
                        │  - 任务队列与认领锁               │
                        └───────────┬───────────┘
                     HTTP(localhost:3000)
            ┌────────────────┴────────────────┐
            │                                  │
   ┌────────▼────────┐              ┌──────────▼──────────┐
   │   网页版管理端     │              │   浏览器插件（可多开）  │
   │ React + Vite      │              │ Manifest V3          │
   │ - 账号/商品/笔记管理│              │ - Content Script 注入 │
   │ - AI 配置/提示词管理│              │ - 任务轮询/认领         │
   └────────────────────┘              │ - 自动化发布执行        │
                                        └───────────────────────┘

关键设计原则：本地服务是唯一数据源与状态权威，网页版和插件都是无状态客户端，通过 HTTP API 读写数据，天然支持多浏览器并行而不冲突。

三、技术栈选型

层	技术	说明
本地服务	Node.js 18+ / Express	轻量、易打包，开发效率高
数据库	SQLite（better-sqlite3）	单文件数据库，免安装，适合本地化部署
网页版前端	React + Vite + TailwindCSS	组件化开发快，生态成熟
状态管理	Zustand 或 React Query	React Query 处理服务端数据缓存更合适
插件框架	Chrome Extension Manifest V3	Service Worker + Content Script
图片处理	Sharp（服务端）	用于压缩、格式转换、生成缩略图
图片去重	pHash（sharp-phash 或自实现）	感知哈希，判断生成图片相似度
打包分发	Electron（可选，做成桌面壳）	让本地服务"点击即启动"，非技术用户更友好
AI 文案	Deepseek API	用户自行配置 Key/模型
AI 生图	用户配置的生图模型（如 Agens/其他文生图API）	服务端统一代理转发，避免 Key 暴露给插件/前端

四、数据库设计（SQLite）

4.1 shops（店铺表）

字段	类型	说明
id	TEXT PK	UUID
shop_id	TEXT	小红书店铺ID，唯一索引
shop_name	TEXT	店铺名称
remark	TEXT	备注
created_at	DATETIME
updated_at	DATETIME

4.2 products（商品表）

字段	类型	说明
id	TEXT PK	UUID
shop_id	TEXT FK	关联 shops.id
title	TEXT	商品标题
status	TEXT	pending / generating / generated
created_at / updated_at	DATETIME

4.3 notes（笔记表，核心表）

字段	类型	说明
id	TEXT PK	UUID
product_id	TEXT FK	关联 products.id
shop_id	TEXT	冗余字段，便于按店铺过滤任务
title	TEXT	笔记标题
content	TEXT	正文
topics	TEXT(JSON数组)	热搜话题
image_prompt	TEXT	生图提示词
image_paths	TEXT(JSON数组)	生成图片相对路径
status	TEXT	draft(待审核) / approved(已通过) / publishing(发布中) / published(已发布) / rejected / failed
worker_id	TEXT	认领任务的浏览器实例标识（发布中状态使用）
claimed_at	DATETIME	认领时间，用于超时释放
published_at	DATETIME	实际发布时间
created_at / updated_at	DATETIME

4.4 configs（配置表，Key-Value）

key	value(JSON)
deepseek_config	{ apiKey, baseUrl, model, temperature }
image_config	{ provider, apiKey, baseUrl, defaultCount, size }
prompt_templates	{ title: "...", content: "...", image: "..." }

4.5 图片文件目录规范

/data/images/{product_id}/{note_id}_{seq}.png

使用 product_id 而非商品标题命名文件夹，避免特殊字符/重名问题；标题作为元数据存于 notes 表。

五、本地服务 API 设计

方法	路径	说明
GET/POST/PUT/DELETE	`/api/shops`	店铺 CRUD
POST	`/api/shops/import`	批量导入店铺（CSV/Excel）
GET	`/api/shops/export`	导出店铺列表
GET/POST/PUT/DELETE	`/api/products`	商品 CRUD
POST	`/api/products/import`	批量导入商品标题
POST	`/api/notes/generate`	批量触发生成任务（文案+图片）
GET	`/api/notes`	笔记列表，支持按店铺/商品/状态筛选
POST	`/api/notes/:id/rewrite`	重新生成单条笔记
POST	`/api/notes/:id/approve`	审核通过
DELETE	`/api/notes/:id`	删除笔记
GET	`/api/notes/next?shop_id=`	插件拉取该店铺下一条待发布任务（内部执行认领事务）
POST	`/api/notes/:id/complete`	插件回调：发布成功
POST	`/api/notes/:id/fail`	插件回调：发布失败，记录原因
GET	`/api/images/:productId/:filename`	静态图片资源
GET/PUT	`/api/configs/:key`	读写配置（Deepseek/生图/提示词）

任务认领事务（防并发抢单）：

UPDATE notes
SET status = 'publishing', worker_id = ?, claimed_at = CURRENT_TIMESTAMP
WHERE id = (
  SELECT id FROM notes
  WHERE shop_id = ? AND status = 'approved'
  ORDER BY created_at ASC LIMIT 1
)
RETURNING *;

SQLite 单文件写锁天然保证该操作串行执行，多个浏览器同时请求也不会拿到同一条。同时启动一个定时任务：publishing 状态超过 10 分钟未回调，自动释放回 approved，避免浏览器崩溃导致任务卡死。

六、网页版功能详细设计

6.1 账号（店铺）管理页

列表字段：店铺ID、店铺名称、备注、创建时间、更新时间、操作
支持搜索（按店铺名/ID模糊匹配）
新增/编辑：弹窗表单
导入：上传 CSV/Excel，字段映射后批量写入，支持重复店铺ID去重提示
导出：一键导出当前列表为 CSV

6.2 商品管理页

按店铺筛选 + 标题搜索
批量导入商品标题（每行一个，或 CSV 单列）
列表字段：ID、所属店铺、商品标题、状态、更新时间、操作
批量生成笔记：
1. 勾选商品 → 点击"批量生成"
2. 弹窗选择：生成图片张数（默认取全局配置，可覆盖）、使用的提示词模板
3. 前端调用 /api/notes/generate，服务端异步串行处理（避免并发打爆 AI 接口配额），生成完成后笔记进入"待审核"
4. 页面展示生成进度条（轮询任务状态或用 SSE 推送）

6.3 笔记审核页（对应"创建笔记功能"）

筛选：店铺名称、商品标题、状态
列表字段：店铺名称、标题、生图提示词、正文内容（摘要）、热搜话题、操作
操作：
- 预览图片：弹窗展示该笔记生成的所有图片
- 重写：重新调用生成接口，覆盖当前文案/图片（保留历史版本可选）
- 通过：状态 draft → approved
- 删除：软删除或直接物理删除（含清理对应图片文件）

6.4 Deepseek 配置页

表单：API Key、Base URL、模型名、温度等参数
"测试连接"按钮，调用一次简单请求验证配置有效性

6.5 生图模型配置页

表单：服务商、API Key、Base URL、默认生成张数、图片尺寸
全局默认张数会被批量生成时的临时选择覆盖

6.6 提示词管理页

三类模板：标题生成提示词、正文内容提示词、小红书生图提示词
支持变量占位符，如 {商品标题}、{店铺名}，生成时自动替换
可维护多套模板并设置"当前启用"版本

七、浏览器插件详细设计

7.1 插件结构（Manifest V3）

extension/
├── manifest.json
├── background.js       // Service Worker，负责与本地服务通信、任务调度
├── content_scripts/
│   └── qianfan_publish.js   // 注入千帆发布页，执行DOM自动化
├── popup/
│   └── popup.html/js   // 插件面板：配置 shop_id、启动/暂停、查看进度
└── options/
    └── options.html/js // 可选：配置本地服务地址（默认 localhost:3000）

7.2 核心流程

配置绑定：用户在插件 popup 中为当前浏览器/账号绑定 shop_id（对应网页版店铺管理中的店铺）
任务轮询：background.js 定时（如每 15~30 秒，含随机抖动）向本地服务请求 GET /api/notes/next?shop_id=xxx
执行发布：
- 若在千帆发布页，content script 收到任务后： a. 在商品搜索框输入笔记对应商品标题，触发搜索 b. 点击对应商品进入发布 c. 通过 DataTransfer 构造 FileList，模拟文件选择注入图片 d. 填写正文、话题（用 React/Vue 受控组件时需触发原生 input/change 事件，不能只赋值 .value） e. 点击发布按钮
回调状态：
- 成功：POST /api/notes/:id/complete
- 失败（如商品未找到、上传超时）：POST /api/notes/:id/fail，附带错误信息，便于人工在网页版排查
防风控策略：
- 每次发布间隔随机 30~90 秒
- 单账号单日发布上限（可在插件配置中设置，如 20 条/天），达到后自动停止轮询
- 出现连续失败（如 3 次以上）自动暂停并提示用户人工检查

7.3 DOM 自动化技术要点

发布页面结构需要人工先用浏览器开发者工具抓取实际选择器（本文档暂不假设具体 DOM，需在开发阶段第三阶段实测确认）
文件上传优先尝试标准 <input type="file"> + DataTransfer 注入；如遇到自定义上传组件（拖拽区域），需要模拟 dragenter/dragover/drop 事件序列
富文本编辑器（正文框）若为 contenteditable，需要用 document.execCommand 或直接派发 InputEvent 写入内容，并触发对应框架的状态同步

八、开发阶段与里程碑

阶段	内容	产出物	预估周期
阶段一	本地服务骨架 + 数据库表 + 基础CRUD API	可运行的 Express 服务	3-5 天
阶段二	网页版：账号管理 + 商品管理页面	可用的管理界面	5-7 天
阶段三	接入 Deepseek + 生图 API，打通"批量生成笔记"全流程	生成功能可用，含去重逻辑	5-7 天
阶段四	笔记审核页 + 提示词/模型配置页	网页版功能完整	3-4 天
阶段五	插件基础框架 + 单条笔记手动发布验证千帆DOM结构	可发布单条笔记的插件原型	5-7 天（含DOM调试，具体视千帆页面复杂度）
阶段六	插件任务轮询 + 认领机制 + 批量发布 + 防风控策略	完整插件，支持多浏览器并行	5-7 天
阶段七	联调、异常处理（网络失败/DOM变化容错）、日志与监控	稳定可用版本	3-5 天

总计预估：约 30-42 个工作日（单人开发，实际视千帆页面自动化难度浮动较大，建议阶段五留足调试缓冲）。

九、风险与应对

风险	影响	应对措施
千帆页面 DOM 结构变化	插件自动化失效	Content script 中的选择器集中管理，便于快速修改；增加"选择器失效告警"机制
平台风控（频繁发布被限流/封号）	店铺受损	随机延时、单日上限、失败自动暂停；建议先小规模试运行观察风控阈值
AI 生成内容质量不稳定	笔记需要人工反复重写	保留"待审核"环节，人工把关；持续优化提示词模板
图片生成重复/相似度高	内容同质化，可能被平台判定为重复发布	pHash 去重 + 提示词中加入随机风格变量
API Key 泄露	账号安全风险	Key 只存本地服务端，前端和插件不直接持有；本地服务对本机 localhost 开放，不对外暴露端口
本地服务未启动导致插件/网页版报错	影响使用体验	网页版和插件都加入"服务连接状态"检测与友好提示

十、后续可扩展方向（本期不做，仅记录）

支持云端部署 + 多人协作（需要引入用户权限体系，SQLite 换成 Postgres）
支持发布数据回流（笔记浏览量/互动数据抓取分析）
支持多平台适配（抖音、快手等类似发布场景）
Electron 打包成一体化桌面客户端，进一步降低部署门槛

本计划书为项目启动阶段的设计文档，具体接口字段、页面细节可在开发过程中根据实际情况微调。

14 KiB Raw Permalink Blame History Unescape Escape