# 操作步骤手册(怎么跑起来)

> 上一篇:[[01 完整流程解读]] · 下一篇:[[03 GitHub最新版与本地版差异]]

## 0. 前置条件

- Node.js v18+
- Shopify 店铺 Admin API 权限(Client ID/Secret 或 Admin Token)
- 至少一个 LLM key(OpenAI / Anthropic / DeepSeek / Gemini;最新版主力走 codex)
- 可选:Pexels key(免费图库,200 请求/月)、火山方舟 Seedream(按量计费需余额)、NanoBanana

## 1. 首次安装(15 分钟)

```bash
cd SEO博客自动化/
npm install
cp .env.example .env     # 然后编辑 .env
npm test                 # 期望 Passed: 30  Failed: 0
npm run run:dry          # 干跑 5 篇样例,不调真实 API,查 output/summary.md
```

### .env 关键变量
```ini
# Shopify(推荐 Client Credentials)
SHOPIFY_STORE_DOMAIN=xxx.myshopify.com
SHOPIFY_CLIENT_ID=...
SHOPIFY_CLIENT_SECRET=shpss_...
SHOPIFY_BLOG_HANDLE=cooling-hub        # 博客 handle

# LLM
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-proj-...
OPENAI_MODEL=gpt-4.1                   # (最新版实际主力是 codex,openai 兜底)

# 图片
PEXELS_API_KEY=...
VOLC_ACCESS_KEY=... / VOLC_SECRET_KEY=...
SEEDREAM_ARK_MODEL=doubao-seedream-5-0
NANOBANANA_MODEL=gemini-2.5-flash-image
```

## 2. 准备数据文件(`data/`)

| 文件 | 用途 |
|---|---|
| `jobs.csv` | 本批要生成的文章清单(从内容日历 Excel 导出) |
| `products.json` | 产品规格(**不含价格**) |
| `anchor-dictionary.json` | 内链锚文本库 |
| `brand-guidelines.md` | 品牌规范、禁用词 |
| `seo-rules.md` | 关键词密度、标题长度等 SEO 规则 |
| `citation-library.json` | 权威引用源清单 |
| `author-bio.html` / `cta.html` | 作者卡、CTA 区块 |
| `research/{job_id}.json` | 每篇的调研证据(RAG 产出) |

jobs.csv 列:`job_id, topic, target_keyword, product_ids, priority, llm_provider, status`

## 3. 日常跑批

```bash
# 生成一批(草稿模式,自动跳过已存在文章)
npm start -- --jobs data/jobs.csv

# 强制重跑(忽略去重阀)
npm start -- --jobs data/jobs.csv --force

# 调试单篇(不写 Shopify)
DRY_RUN=true node src/queue/runner.js --job-id C10-017

# 跑完后手动补一次 Sheet 同步(runner 一般会自动做)
python -X utf8 scripts/sync-sheets-full.py
```

跑完检查 `output/`:
- `{job_id}.html / .json` — 成品与元数据
- `summary.md` — 本轮运行摘要
- `pending-review.json` / `review-suggestions.json` — 待审清单与 AI 审核建议
- `_duplicate-blocked.json` — 被去重阀拦下的(人工确认)

## 4. 人工审核

1. 打开 Google Sheet(Status/Review tab)看每篇打分与建议
2. 进 Shopify Admin 看 Hidden 草稿:排版、图片、内外链、事实性
3. 低分文章按分类补内容:购买指南加个人推荐、对比测评加实测数据

## 5. 发布

```bash
npm run approve:all                              # 发布全部草稿
npm run approve -- --job-id C10-017              # 发布单篇
node scripts/scheduled-publish.js --per-run 3    # 每次批量放出 N 篇(控节奏)
```

发布后**必须**用 desktop + mobile 两个 UA curl 线上 URL 验证渲染(Shopify 边缘缓存按 UA 分桶,API 200 不代表用户看到新版)。

## 6. 存量维护常用脚本

```bash
node scripts/humanize-live-articles.js --dry-run          # 批量去 AI 味(--limit N / --ids)
node scripts/skeletonAudit.js                             # 骨架相似度审计(文章是否长得太像)
node scripts/monitor-placeholder-headers.js               # 扫灰色占位 header 图
node scripts/force-cache-bust-suffix-swap.js              # 破 page_cache
python 博客流量跟踪/blog_ctr_tracker.py                    # 周度 CTR 跟踪
```

## 7. 红线(AGENTS.md 原文,绝对规则)

1. 生产店铺:主题文件(*.liquid / assets)未经确认不碰
2. 任何 Shopify 写操作后必须线上验证(双 UA curl + grep 标记)
3. 永不提交 .env / 含密钥文件
4. 永不 force push / 改写 main 历史
5. 文章 body 不嵌 BreadcrumbList JSON-LD(统一走主题层 snippet)
6. AI 套话规则只改 SoT 两文件:`src/data/aiPatterns.js`、`src/utils/stripBoilerplate.js`,消费方 import,不复制粘贴