# Pinterest 综合自动化运营项目规划

## 1. 调研结论

Pinterest 的运营对象和 Facebook 不一样。Facebook-auto 以帖子、群组、评论人、Messenger 为核心；Pinterest-auto 应以 Pin、图板、趋势、搜索意图、商品目录、站外点击和广告/分析为核心。

本次实地访问和官方文档确认到的主要站点结构：

- Pinterest 公开站点：首页、探索、搜索、Pin 详情、图板、用户、购物、注册/登录。
- 搜索页：`/search/pins/`、`/search/boards/`、`/search/users/`、`/search/products/` 等路径，公开页可见 Pin 卡片、图板、用户资料和关注按钮，但很多操作需要登录。
- Pin 详情页：核心动作是保存、访问站外链接、分享、更多操作、相关兴趣、评论等。
- 图板页：展示图板标题、协作者、Pin 数、Pin 卡片、分享。
- Business 站点：企业账号、广告、趋势、资源、成功案例、Business Hub、Analytics。
- Create 站点：创作者/商家/媒体公司内容指南、创作工具、内容学院、成功案例。
- Developers 站点：Pinterest REST API v5.28.0，覆盖 Pins、Boards、Media、Ads、Catalogs、Analytics、Trends、Lead Ads 等模块。

官方能力重点：

- 企业账号可解锁 Business Hub、Analytics、Ads、Catalogs。
- Pinterest API 支持内容管理、广告管理、购物目录管理、分析报告。
- 创建 Pin 需要 OAuth，并通常需要 `boards:read`、`boards:write`、`pins:read`、`pins:write`。
- 创建 Board 需要 `boards:read`、`boards:write`。
- Pin Analytics 支持读取自有 Pin 或共享图板 Pin 的指标，常见指标包括 impressions、engagements、saves、pin clicks、outbound clicks 等。
- Catalog 适合商家批量创建 Product Pins，前置条件包括企业账号、认领网站、安装 Pinterest tag、符合 merchant guidelines。
- 官方允许内容营销工具、Pin 定时发布工具、自动化内容创建工具。

合规边界：

- 不应未经用户知情和同意代表用户操作，例如修改资料、创建/收藏/编辑 Pin、关注/取关、发消息、评论。
- 如果支持定时发布 Pin，用户必须选择每一张要发布的 Pin。
- 不应提供让最终用户无需逐项考虑即可自动开始关注、评论、收藏、消息等动作的功能。
- 未经 Pinterest 明确许可，不应使用自动化方式抓取或提取 Pinterest 信息。
- 不应使用 Pinterest 数据做平台基准、竞品研究或站外广告定向。

因此 Pinterest-auto 的核心原则是：API 优先、用户授权、逐项确认、证据留存、浏览器辅助，不做黑盒抓取。

## 2. 从 Facebook-auto 复用的架构

Facebook-auto 中值得迁移的部分：

- Web 后台：Next.js + TypeScript + 本地 `data/db.json` 原型。
- 本地 store：先用 JSON store，后续迁移 SQLite/PostgreSQL。
- 任务队列：`AutomationTask` 的状态机、日志、证据路径、失败记录。
- OpenClaw MCP：把自然语言命令映射成 typed tools，再调用本地 API。
- Operator Plan：把“每天运营”拆成有状态、有时间、有证据的计划项。
- Browser Executor：连接当前 Chrome/CDP，做登录态检查、页面状态诊断、dry-run 和证据截图。
- 商用化工作台：授权、风控额度、人工确认策略、审计日志。
- 线索表思想：用标准表格沉淀每次发现、分析、跟进，不把结果散在日志里。

Pinterest 版需要重做的部分：

- Facebook 评论/群组/Messenger 逻辑不能直接套用。
- 商机开发应从 Pinterest 搜索意图、趋势、用户/商家/图板、站外网站、商品目录、广告线索表单等方向设计。
- 发布能力应优先走 Pinterest API，而不是模拟 UI 点击。
- 数据采集不能做未经许可的公开页批量抓取；公开页只适合页面诊断和人工辅助，不作为主数据源。

## 3. 目标产品模块

### 3.1 账号与权限中心

目标：让系统知道当前账号是否具备运营能力。

能力：

- Pinterest OAuth 连接。
- 企业账号状态检查。
- Scope 检查：`pins:read/write`、`boards:read/write`、`ads:read/write`、`catalogs:read/write`、`user_accounts:read` 等。
- Business Hub、Analytics、Ads、Catalog、Claimed Website 就绪检查。
- Token 刷新、过期提醒、权限缺失提示。

### 3.2 内容运营中心

目标：从产品资料和关键词生成 Pinterest 原生内容计划。

能力：

- 生成 Pin 标题、描述、目标链接、标签/关键词、图板建议。
- 生成多图/视频/产品图 Pin 方案。
- 管理图板与图板区块。
- API 创建 Pin / Board。
- 支持草稿、排期、人工确认、发布证据。
- 支持 RSS 自动发布和 Catalog Product Pins 的导入规划。

### 3.3 趋势与关键词研究

目标：围绕品类发现内容机会和商机方向。

能力：

- Pinterest Trends / API trends 模块优先。
- 搜索建议与相关兴趣人工辅助。
- 关键词聚类：品类词、场景词、风格词、购买词、季节词。
- 输出内容日历、图板结构、Pin 主题。
- 记录每个关键词的机会评分、竞争程度、内容建议。

### 3.4 商机开发与 CRM

目标：把 Pinterest 的“意图信号”转化为可跟进线索。

合规路线：

- 优先使用自有资产数据：自有 Pin 的 outbound clicks、saves、engagements、profile visits、follows。
- 优先接入 Ads Lead Forms / leads_export，如果账号开通该能力。
- 对来自自有网站的访问、表单、商品点击做归因。
- 对公开 Pinterest 用户/图板只做人工可见的研究与审核，不做未经许可的批量抓取。

线索类型：

- `PinLeadSignal`：某个 Pin 带来的点击、保存、关注、站外访问。
- `AdLead`：Pinterest Lead Ads 表单线索。
- `WebsiteLead`：从 claimed website / tag / UTM 归因来的访客或表单。
- `PartnerProspect`：人工审核的潜在达人、商家、图板主、内容合作对象。

CRM 能力：

- 保存线索、来源、关键词、Pin、图板、广告活动、站外页面。
- AI 评分：购买意图、合作价值、品类匹配、紧急度。
- 后续动作：发邮件、站外 CRM 跟进、人工查看 Pinterest 资料。
- 对 Pinterest 内关注/评论/消息动作默认只排队，不自动执行。

### 3.5 广告与商品目录

目标：把 Pinterest 商业能力纳入运营闭环。

能力：

- Catalog 数据源检查：字段、图片尺寸、价格、库存、链接、错误报告。
- Product Pins 状态监控。
- 广告账号、Campaign、Ad Group、Ads、关键词、受众、报表读取。
- 指标分析：impressions、engagements、saves、pin clicks、outbound clicks、CPA/ROAS。
- 预算建议和素材优化建议。
- Lead Ads 导出和 CRM 入库。

### 3.6 知识库与素材库

目标：让 Pin 内容和商业回复基于真实业务资料。

能力：

- 产品介绍、价格、物流、FAQ、品牌语气、竞品差异。
- 图片/视频素材管理。
- 素材和 Pin 表现关联。
- 生成内容时引用知识库，避免虚构卖点。
- 支持多语言标题/描述。

### 3.7 OpenClaw 指令入口

目标：像 Facebook-auto 一样，让 OpenClaw 可以通过 MCP 直接调度 Pinterest 运营。

建议 MCP 工具：

- `pinterest_auto_health`
- `pinterest_auto_summary`
- `pinterest_auto_pending`
- `pinterest_auto_setup_status`
- `pinterest_auto_create_daily_plan`
- `pinterest_auto_run_operator_plan`
- `pinterest_auto_create_pin_draft`
- `pinterest_auto_queue_pin_publish`
- `pinterest_auto_approve_pin_publish`
- `pinterest_auto_create_board`
- `pinterest_auto_research_keywords`
- `pinterest_auto_analyze_pin_performance`
- `pinterest_auto_import_catalog_report`
- `pinterest_auto_export_leads`
- `pinterest_auto_save_crm_lead`
- `pinterest_auto_browser_snapshot`

## 4. 数据模型草案

```ts
type PinterestAccount = {
  id: string;
  accountName: string;
  businessAccount: boolean;
  scopes: string[];
  tokenStatus: "missing" | "valid" | "expired" | "revoked";
  connectedAt?: string;
  expiresAt?: string;
};

type PinterestBoard = {
  id: string;
  name: string;
  privacy: "PUBLIC" | "PROTECTED" | "SECRET";
  description?: string;
  apiBoardId?: string;
  createdAt: string;
  updatedAt: string;
};

type PinterestPinDraft = {
  id: string;
  boardId: string;
  title: string;
  description: string;
  link?: string;
  mediaUrl?: string;
  mediaType: "image" | "video";
  keywords: string[];
  status: "draft" | "pending_review" | "scheduled" | "published" | "failed";
  apiPinId?: string;
  scheduledAt?: string;
  evidence?: string;
  createdAt: string;
  updatedAt: string;
};

type PinterestTrendResearch = {
  id: string;
  seedKeyword: string;
  market: string;
  terms: Array<{
    keyword: string;
    category?: string;
    intent: "idea" | "shopping" | "seasonal" | "brand" | "unknown";
    score: number;
    reason: string;
  }>;
  summary: string;
  createdAt: string;
};

type PinterestLead = {
  id: string;
  sourceType: "pin_analytics" | "lead_ad" | "website" | "manual_research" | "catalog";
  sourceId?: string;
  name?: string;
  profileUrl?: string;
  email?: string;
  website?: string;
  company?: string;
  keyword?: string;
  pinId?: string;
  boardId?: string;
  score: number;
  intent: "buyer" | "partner" | "creator" | "merchant" | "unknown";
  recommendedAction: "crm_follow_up" | "email" | "review_profile" | "ignore";
  status: "new" | "reviewing" | "contacted" | "converted" | "ignored";
  evidence: string;
  createdAt: string;
  updatedAt: string;
};

type PinterestAutomationTask = {
  id: string;
  type:
    | "check_health"
    | "create_board"
    | "publish_pin"
    | "read_pin_analytics"
    | "research_trends"
    | "catalog_check"
    | "ads_report"
    | "browser_snapshot";
  executorMode: "api" | "browser" | "manual";
  status: "pending" | "running" | "completed" | "failed";
  targetUrl?: string;
  payload: Record<string, unknown>;
  result?: string;
  evidence?: Array<{ label: string; path?: string; url?: string; capturedAt: string }>;
  createdAt: string;
  updatedAt: string;
};
```

## 5. 执行器设计

### API 执行器

优先执行：

- OAuth health。
- list/create/update/delete boards。
- create/update/delete pins。
- upload media。
- get pin analytics。
- ads/campaign/ad group/keyword/report。
- catalogs/feed/report。
- trends/search API。

特点：

- 可控、可审计、合规。
- 失败原因清晰：scope 不足、token 过期、参数错误、rate limit。
- 适合自动化排期，但仍保留人工确认。

### 浏览器执行器

仅用于：

- 检查当前 Pinterest 页面是否登录。
- 诊断 Pin Builder、Business Hub、Catalog、Analytics 页面是否可访问。
- 打开目标页面给用户人工确认。
- API 没覆盖的低风险 dry-run。
- 截图和页面状态证据。

不用于：

- 批量抓取公开 Pin/用户/图板数据。
- 自动关注、评论、私信、收藏。
- 绕过 Pinterest 登录、验证码、地区限制、频率限制。

## 6. 页面类型识别

浏览器 snapshot 应识别：

- `home`
- `login`
- `signup`
- `search_pins`
- `search_boards`
- `search_users`
- `search_products`
- `pin_detail`
- `board`
- `profile`
- `business_home`
- `pin_builder`
- `analytics`
- `catalogs`
- `ads_manager`
- `developer_docs`
- `unknown`

每种页面输出：

- URL、标题、登录状态。
- 主要可见动作。
- 是否适合 API 替代。
- 是否需要人工确认。
- 下一步建议。

## 7. 实施阶段

### Phase 1：项目骨架和模型

- 初始化 Next.js + TypeScript。
- 迁移 Facebook-auto 的 store、task、audit、commercial 风控思路。
- 新增 Pinterest 类型、seed 数据、dashboard。
- 写 `pinterest_auto_health`、`summary`、`pending`。

### Phase 2：OAuth 和 API 客户端

- Pinterest app 配置页指引。
- OAuth redirect/callback。
- Token 存储与刷新。
- API client：boards、pins、analytics。
- 创建 Board / Pin 的 API dry-run 与真实执行。

### Phase 3：内容运营工作台

- Pin draft 表。
- 图板管理。
- AI 生成标题、描述、关键词、链接 CTA。
- 素材上传与校验。
- 发布审核流：draft -> pending_review -> scheduled -> published。

### Phase 4：趋势研究和内容日历

- Trends API / 手工输入趋势数据。
- 关键词聚类和主题评分。
- 生成 7/14/30 天内容计划。
- 与 Pin draft 关联。

### Phase 5：Analytics、Catalog、Ads

- Pin analytics 报表。
- Board / Pin 表现排行。
- Catalog feed 校验与错误报告。
- Ads reporting。
- Lead Ads 导出与 CRM 入库。

### Phase 6：OpenClaw Operator

- MCP server。
- Daily plan。
- Run plan。
- 自动日报。
- 审计链路：command -> MCP -> plan -> task -> API/browser -> evidence -> analysis。

### Phase 7：生产化

- SQLite/PostgreSQL。
- 队列与重试。
- API rate limit 管理。
- 多账号/多客户授权。
- 选择器包和回归测试。
- 商用 license gate。

## 8. 推荐第一批代码任务

1. 从 Facebook-auto 复制并改造基础 Next.js 项目结构。
2. 建立 `lib/types.ts`、`lib/store.ts`、`lib/pinterest-api.ts`、`lib/operator-plan.ts`。
3. 建立 `app/api/integrations/openclaw/*`。
4. 建立 `mcp/pinterest-auto-server.mjs`。
5. 建立 `app/components` 中的 Setup、Content、Trends、Analytics、CRM、Tasks 面板。
6. 先实现 `create_board`、`create_pin_draft`、`publish_pin_via_api`、`pin_analytics` 四个最小闭环。

## 9. 产品定位一句话

Pinterest-auto 应定位为：一个 API 优先、人工确认、可审计的 Pinterest 内容增长与商机运营系统，而不是公开网页抓取脚本。
