# auto_adv

**Repository Path**: topxing/auto_adv

## Basic Information

- **Project Name**: auto_adv
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 店小秘 CPC 广告自动监控

这是一个面向宝塔面板部署的店小秘 CPC 广告工具，核心能力是：复用店小秘登录态读取 Amazon 广告数据，按 SOP 规则自动监控 SP 广告，接入 OpenAI 兼容 GPT 中转做策略建议，并把历史数据写入 MySQL。

当前项目已切换为店小秘链路，不直接调用 Amazon Ads API。所有广告读写都通过店小秘接口完成。

## 当前能力

- 店小秘 CPC 看板：查看广告活动、广告组、广告产品、商品投放、搜索词、关键词等数据。
- 每日广告报表：宝塔计划任务定时生成 JSON/CSV 报告到 `reports/`。
- SP 广告利润监控：默认扫描全部已授权且开启的 Amazon 店铺和站点，当前 SP 策略以“多订单 + ACOS 20%-25% 区间”为目标，不追求单纯压低 ACOS。
- 产品日维度智能控制：额外按 ASIN 聚合当天广告表现，默认 `productDailyUseToday=true`、`productDailyFallbackDays=2`、`productDailyAcosTargetMin=20`、`productDailyAcosTargetMax=25`。当天数据为空时自动回退最近有效日；低于 20% 且有订单时积极抢占坑位，20%-25% 稳步扩单，25%-40% 之间由智能体结合订单、转化和预算消耗判断是否继续小步抢位；0 销售高花费或转化不足时回收预算。
- SOP 候选生成：规则层只生成预算增加、预算回收、关键词调价、否词等候选动作，不直接绕过 AI 执行。
- GPT 策略建议：支持 OpenAI 兼容接口，当前可使用 4sapi 中转 `https://4sapi.com`。
- AI 同向审批：预算增加、预算回收、关键词调价、否词都必须由 AI 结合历史数据同向确认后才执行；AI 未确认或反向建议时跳过。默认 `requireSameDirectionForWrites=true`，不再让本地低风险白名单绕过 AI 审批。
- MySQL 历史库：保存每轮运行、活动快照、搜索词快照、动作记录。
- 冷启动 SOP：支持 2026 新品 0-4 周冷启动 SP 结构计划，默认 dry-run。

## 安装

```bash
npm install
npm run build
mkdir -p data reports logs
```

## 统一配置

复制示例配置：

```bash
cp config.example.json config.json
```

编辑 `config.json`，填入 4sapi/OpenAI Key、MySQL 和 SP 监控参数。真实 `config.json` 不要提交到仓库。

关键配置示例：

```json
{
  "openai": {
    "apiKey": "sk-xxxx",
    "apiBaseUrl": "https://4sapi.com",
    "model": "gpt-4o",
    "temperature": 0.2
  },
  "spMonitor": {
    "enabled": true,
    "mode": "execute",
    "targetAcos": 20,
    "breakEvenAcos": 25,
    "minOrdersForScale": 1,
    "minClicksNoOrder": 12,
    "minSpendForCut": 3,
    "budgetUpRatio": 0.15,
    "budgetDownRatio": 0.15,
    "maxBudgetChangeRatio": 0.15,
    "minBudgetActionIntervalHours": 12,
    "maxKeywordBidChangesPerRun": 30,
    "keywordGrowthZeroImpressionProtection": true,
    "maxKeywordGrowthBidChangesPerCampaign": 3,
    "keywordGrowthMinImpressionsForBidUp": 1,
    "exportObservations": false,
    "profitModelEnabled": false,
    "profitModelPath": "data/sku-profit-model.json",
    "productDailyStopLossEnabled": true,
    "productDailyUseToday": true,
    "productDailyReportDays": 1,
    "productDailyFallbackDays": 2,
    "productDailyAcosTargetMin": 20,
    "productDailyAcosTargetMax": 25,
    "productDailyAcosLimit": 25,
    "productDailyGrowthAcosCeiling": 40,
    "productDailyMinSpendForCut": 3,
    "productDailyMinOrdersForScale": 1,
    "productDailyMinConversionForScale": 0.03,
    "productDailyBudgetUpRatio": 0.12,
    "productDailyBudgetDownRatio": 0.15,
    "searchTermPromotionEnabled": true,
    "autoCreateKeywordsFromSearchTerms": false,
    "shops": []
  }
}
```

## SKU 利润模型

SP 监控可以读取本地 `data/sku-profit-model.json`，用于在报表里展示 ASIN/SKU、生命周期、单件毛利、广告后利润等参考信息。由于头程费用不稳定，当前默认 `profitModelEnabled=false`，主决策按产品日 ACOS、订单、转化率、点击/花费样本和历史趋势判断；利润字段只作为参考，不作为预算放量或回收的硬门槛。

推荐在看板 GUI 里维护：

1. 打开看板 `npm run start`。
2. 选择店铺和站点。
3. 点击顶部 `利润模型`。
4. 点击 `自动抓取商品`，系统会从当前店铺/站点的广告商品里抓取 ASIN/SKU。
5. 在表格里为每个 ASIN/SKU 单独填写售价、ASIN 单件成本、佣金率、安全系数，并选择生命周期。ASIN 单件成本可以把采购、头程、FBA、优惠券、退款损耗、其他费用合并后填写。
6. 把需要展示利润参考的商品设为 `启用`，点击 `保存利润模型`。

保存并启用利润模型后，SP 监控下一轮会在 CSV/HTML/JSON 报表中带出对应 ASIN/SKU 的利润字段。当前策略不会用这些利润字段硬拦截动作，AI 同向审批会优先结合 ACOS、订单、转化率和历史数据做最终确认。

生命周期会影响广告动作节奏，不参与库存限制：

- `new` 新品：小步测试流量，预算/关键词提价默认 8%，单活动冷启动提词默认最多 2 个。
- `mature` 成熟品：按 30% ACOS 红线稳定放量和止损。
- `hero` 爆品：低 ACOS 有单时正常保护有效流量，预算上调默认 15%，关键词上调默认 12%。
- `decline` 衰退品：目标 ACOS 更低，默认不做冷启动放量，高点击无单更快否定。

也可以直接编辑 JSON。第一次使用可复制示例：

```bash
cp config/sku-profit-model.example.json data/sku-profit-model.json
```

把示例产品改成真实数据，并把 `enabled` 改为 `true`：

```json
{
  "enabled": true,
  "defaultSafetyFactor": 0.8,
  "defaultReferralFeeRate": 0.15,
  "products": [
    {
      "enabled": true,
      "marketPlaceId": "ATVPDKIKX0DER",
      "asin": "B0真实ASIN",
      "sku": "真实SKU",
      "lifecycle": "mature",
      "price": 20,
      "totalUnitCost": 12,
      "referralFeeRate": 0.15,
      "safetyFactor": 0.8
    }
  ]
}
```

报表参考口径：

```text
单件毛利 = 售价 - ASIN 单件成本 - 平台佣金
盈亏平衡 ACOS = 单件毛利 / 售价
参考目标 ACOS = 盈亏平衡 ACOS × 安全系数
广告后利润 = 单件毛利 × 估算订单件数 - 广告花费
```

报表会新增 `ASIN`、`SKU`、`生命周期`、`单件毛利`、`盈亏 ACOS`、`目标 ACOS`、`广告后利润`、`净利润率`、`利润状态` 字段。CSV/HTML 摘要也会显示利润模型配置数和匹配对象数。

`shops: []` 表示自动扫描全部已授权且开启的 Amazon 店铺和全部站点。只想限制部分店铺/站点时配置：

```json
"shops": [
  {
    "shopId": "店铺ID或店铺名称",
    "marketPlaceId": "ATVPDKIKX0DER"
  }
]
```

## 店小秘登录态

店小秘不开放官方 API，计划任务需要复用已经登录授权后的 Cookie。推荐写入服务器本地文件：

```bash
mkdir -p data
cat > data/dianxiaomi-session.json <<'JSON'
{
  "cookie": "这里填店小秘登录后的 Cookie",
  "userAgent": "这里填同一个浏览器的 User-Agent，可留空"
}
JSON
chmod 600 data/dianxiaomi-session.json
```

也可以在宝塔计划任务中使用环境变量：

```bash
export DXM_COOKIE='这里填 Cookie'
```

Cookie 过期时任务会失败并提示更新登录态。

## 常用命令

启动看板：

```bash
npm run start
```

生成每日报表：

```bash
npm run dxm:daily
```

预演 SP 低 ACOS 监控，不写入店小秘：

```bash
npm run dxm:sp-monitor
```

执行 SP 低 ACOS 监控，真实调整预算、关键词出价和否定词：

```bash
npm run dxm:sp-monitor -- --execute
```

循环执行 SP 低 ACOS 监控：

```bash
npm run dxm:sp-monitor:loop -- --execute
```

冷启动 SOP 预演：

```bash
npm run dxm:sop
```

确认报告无误后再执行冷启动 SOP 写操作：

```bash
npm run dxm:sop -- --execute
```

## SP 自动监控规则

规则层只负责生成候选动作。预算增加、预算回收、关键词调价和否词都需要 AI 结合 `historySummary` 历史数据同向确认后才会真实执行；AI 返回观察、反向建议、未返回匹配动作或接口异常时，动作会标记为 `skipped`。

会生成候选的情况主要有四类。

### 加预算

满足：

```text
orders >= minOrdersForScale
acos > 0
acos <= 30
未处于同类预算动作冷却期
```

默认含义：统计窗口内至少 1 单，并且产品日/活动 ACOS 位于可控区间时，生成放量候选。只有 AI 同向返回 `scale_up`，且 ACOS、订单和转化样本仍满足放量安全条件时，预算才会上调。

如果商品设置了生命周期，系统会先按生命周期修正目标 ACOS 和放量比例。例如新品默认只小幅放量，衰退品默认不做冷启动放量。

### 降预算

满足任一：

```text
acos > 30 && spend >= minSpendForCut
orders == 0 && spend >= minSpendForCut
```

默认含义：ACOS 超过 30% 且消耗至少 3 美元，或花费达到止损线但 0 单，生成预算回收候选。若该活动仍有订单，系统不会机械回收，必须由 AI 结合历史趋势、订单质量、花费与销售变化明确同向返回 `scale_down` 后才执行。

### 关键词调价

满足低 ACOS 有订单时生成关键词提价候选；满足高 ACOS 或 0 单消耗达到止损线时生成关键词降价候选。关键词调价同样需要 AI 同向确认后才会写入店小秘。

### 否定搜索词

满足：

```text
clicks >= minClicksNoOrder
orders == 0
```

默认含义：搜索词 12 次点击 0 单，生成否定精准候选。AI 同向返回 `negate` 后才写入店小秘。

### 搜索词拓词

满足：

```text
orders >= minSearchTermOrdersForPromote
acos > 0
acos <= 30
同广告组下还没有同名精准关键词
```

默认含义：搜索词至少 2 单，ACOS 低于 30% 时，输出 `搜索词转精准` 候选。默认 `autoCreateKeywordsFromSearchTerms=false`，只在报表中生成候选；确认运行稳定后再改为 `true`，系统才会真实写入手动精准关键词。

预算动作有冷却窗口：默认同一个活动 12 小时内不重复做同类预算调整。

如果配置了 MySQL 历史库，AI 输入会带上最近历史摘要，用于判断最近是否在改善、恶化或持续无转化。历史数据不足时，AI 会在理由里说明不确定性，并倾向观察。

## GPT / 4sapi

项目使用 OpenAI 兼容 Chat Completions 接口。4sapi 文档站是 `https://4sapi.apifox.cn/`，实际 API 地址是：

```text
https://4sapi.com/v1/chat/completions
```

配置中只需要写：

```json
"apiBaseUrl": "https://4sapi.com"
```

程序会自动拼接 `/v1/chat/completions`。

GPT 只参与建议，不直接执行动作。系统会把真实 `plannedActions` 放到 AI 输入最前面，并要求 AI 逐字复制完整 `actionId`。最终执行需要“规则候选 + AI 同向确认 + 风控约束”同时成立，并在报告里记录 `AI联动 / AI采纳 / AI方向 / AI理由`：

- `whitelisted`：AI 与规则同向，且满足规则风控，可执行。
- `diverged`：AI 与规则分歧，忽略 AI。
- `same_direction_observe`：AI 与观察动作同向，仅观察。
- `same_direction_not_profitable`：AI 同向但未满足盈利安全，不放大。
- `no_advice`：本动作没有匹配到 AI 建议。
- `ai_required_not_approved`：该动作需要 AI 审批，但 AI 未同向确认，跳过。
- `ai_recovery_not_approved`：高 ACOS 但有订单的回收候选未获 AI 同向确认，跳过。

CSV/HTML 会直接打印 AI 返回的方向、置信度和原始理由；如果没有匹配到当前动作，也会展开 AI 返回的动作建议列表，方便判断是 actionId 不匹配、AI 返回观察、接口错误还是历史数据不足。

## 宝塔部署

服务器目录示例：

```bash
cd /www/wwwroot/tools.zhushou.me
npm install
npm run build
mkdir -p data reports logs
```

### 看板服务

看板/报表页面建议由 PM2 常驻：

```bash
pm2 start ecosystem.config.cjs --only dianxiaomi-ad-cron --update-env
pm2 save
```

如果已经在宝塔计划任务里跑 SP 自动监控，不建议再启动 `dxm-sp-low-acos-monitor` PM2 循环，避免重复执行。

推荐状态：

```text
PM2：保留 dianxiaomi-ad-cron
宝塔计划任务：每日报表 + SP低ACOS自动监控
```

### 每日广告报表计划任务

宝塔面板 -> 计划任务 -> Shell 脚本，每天一次，例如 01:30：

```bash
cd /www/wwwroot/tools.zhushou.me
mkdir -p logs reports data
npm run dxm:daily >> logs/dxm-daily.log 2>&1
```

### SP 低 ACOS 自动监控计划任务

建议每小时一次，例如每小时第 30 分钟执行：

```bash
cd /www/wwwroot/tools.zhushou.me
mkdir -p logs reports data
npm run dxm:sp-monitor -- --execute >> logs/dxm-sp-monitor.log 2>&1
```

每小时执行不会导致频繁改预算，因为系统有 `minBudgetActionIntervalHours` 冷却保护。

## SP 报表判断

执行后重点看 `dxm-sp-monitor-execute_YYYY-MM-DD_HH-mm.csv`：

- `错误` 为空或统计为 `NONE`，说明店小秘写入接口没有失败。
- `低 ACOS 有订单活动放大预算` 表示活动 ACOS 不超过 30% 且有订单，系统正在放量。
- `高 ACOS 或无单消耗活动压预算` 表示活动 ACOS 超过 30% 或有消耗无订单，系统正在止损。
- `AI联动=AI 同向采纳` 且 `AI采纳=已采纳` 表示 AI 与规则同向，动作允许执行。
- `AI方向=观察` 或 `AI 未确认回收` 表示 AI 结合历史后未同意当前动作，系统会跳过执行。
- `近期已调整预算，等待学习窗口` 表示同类预算动作处于冷却期，不是失败。
- `冷启动低流量关键词小幅提价` 表示关键词流量样本不足，系统小幅提价获取曝光和点击样本。

默认执行报表只导出真实动作，不导出普通观察行；摘要里的“观察 N 个”用于说明有多少对象未触发 SOP。冷启动关键词提价也有保护：0 展现关键词不盲目提价，同一活动单轮最多提价 3 个冷启动关键词。AI 只分析真实动作候选，普通观察行不占用 AI 请求上下文。

## 验证运行状态

查看 PM2：

```bash
pm2 list
```

查看计划任务日志：

```bash
tail -n 100 /www/wwwroot/tools.zhushou.me/logs/dxm-daily.log
tail -n 100 /www/wwwroot/tools.zhushou.me/logs/dxm-sp-monitor.log
```

查看最新报告：

```bash
ls -lt /www/wwwroot/tools.zhushou.me/reports | head
```

检查 GPT 建议：

```bash
cd /www/wwwroot/tools.zhushou.me
node -e "const fs=require('fs'); const f=fs.readdirSync('./reports').filter(x=>x.startsWith('dxm-sp-monitor-execute_')&&x.endsWith('.json')).sort().pop(); const r=require('./reports/'+f); console.log('file=',f); console.dir(r.aiAdvice,{depth:10});"
```

检查 AI 联动统计：

```bash
node -e "const fs=require('fs'); const f=fs.readdirSync('./reports').filter(x=>x.startsWith('dxm-sp-monitor-execute_')&&x.endsWith('.json')).sort().pop(); const r=require('./reports/'+f); console.log('file=',f); console.log(r.actions.reduce((m,a)=>{const k=a.detail.aiLink||'none';m[k]=(m[k]||0)+1;return m},{}));"
```

筛选实际非观察动作：

```bash
node -e "const fs=require('fs'); const f=fs.readdirSync('./reports').filter(x=>x.startsWith('dxm-sp-monitor-execute_')&&x.endsWith('.json')).sort().pop(); const r=require('./reports/'+f); console.log(r.actions.filter(a=>a.type!=='observe').map(a=>({type:a.type,status:a.status,name:a.detail.name||a.detail.term,campaignId:a.detail.campaignId,beforeBudget:a.detail.beforeBudget,afterBudget:a.detail.afterBudget,acos:a.detail.acos,orders:a.detail.orders,clicks:a.detail.clicks,aiLink:a.detail.aiLink,reason:a.detail.reason,error:a.error})));"
```

## 输出文件

常见输出：

- `reports/dxm-daily_YYYY-MM-DD_HH-mm.csv`
- `reports/dxm-campaign_YYYY-MM-DD_HH-mm.csv`
- `reports/dxm-sp-monitor-execute_YYYY-MM-DD_HH-mm.json`
- `reports/dxm-sp-monitor-execute_YYYY-MM-DD_HH-mm.csv`
- `reports/dxm-cold-start-sop_YYYY-MM-DD_HH-mm.json`

看板底部“报表下载”会列出 `reports/` 下最近生成的 JSON/CSV。

## 注意事项

- 不要提交 `config.json`、Cookie、API Key、数据库密码。
- 真实广告写操作都通过店小秘接口执行，执行前先确认配置中的 `mode`。
- 如果 GPT 报模型不存在，去 4sapi 模型广场复制精确模型名后更新 `config.json`。
- 如果报告里大部分是 `observe` 或 `skipped`，通常说明当前数据没有触发调整阈值，或活动仍处于预算调整冷却窗口。