amazon-ad-ai-kanban

KO | EN

gitlite — search

#python #typescript #llm #go #golang #android #machine-learning #docker #java #windows #awesome #cli #awesome-list #vue

amazon-ad-ai-kanban

(★ 19)

亚马逊广告AI看板-把“广告 + 产品经营 + 生命周期”等数据整理成运营能抓重点的结构化输出；AI 只做解释与写报告，不参与算数。

amazon-ad-ai-kanban Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 亚马逊广告AI看板

> 一句话定位：把“广告 + 产品经营 + 生命周期”等数据整理成 **运营能抓重点** 的结构化输出；AI 只做解释与写报告，不参与算数。

## 目标与范围（Build in public v1）
- **当前目标（L0）**：只输出建议与清单，不修改广告
- **核心价值**：把多源报表统一口径，输出可执行的运营入口（Dashboard/Watchlists/Action Board）
- **范围外**：自动投放执行（L2）、广告 API 直连、利润精算（需更完整成本数据）

---

## 快速开始

### 1) 环境准备
- 推荐 Python `3.11~3.12`
- 建议使用虚拟环境

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 2) 数据放置（默认结构）
```
（目前数据来源是赛狐ERP）

data/
  input/
    广告数据/            # 广告-报告下载 SP/SB/SD 报表（按日）
    产品分析/            # 数据-产品分析（按日）
    产品映射/            # 商品-商品列表
  output/
```

### 3) 一键运行
```bash
python main.py
```

### 4) 查看结果
- 入口文件：`data/output/<时间戳>/START_HERE.html`
- 每店铺聚焦版：`data/output/<时间戳>/<shop>/reports/dashboard.html`
- 多店铺 Owner 轻量总览：`data/output/<时间戳>/OWNER_OVERVIEW.csv`
- 多店铺 Owner 排序总览（含统一优先级分）：`data/output/<时间戳>/OWNER_OVERVIEW.md` / `.html`
- 店铺环比（含促销/季节性校正列）：`data/output/<时间戳>/<shop>/dashboard/compare_summary.csv`
- 广告位预算平移建议：`data/output/<时间戳>/<shop>/dashboard/placement_rebalance_plan.csv`
- 已回填执行日志时，会额外输出：`data/output/<时间戳>/<shop>/ops/action_review_summary.csv`

---

## 依赖列表（建议版本）
- `pandas>=2.2,<3`
- `numpy>=2,<3`
- `openpyxl>=3.1,<4`
- `matplotlib>=3.8,<4`
- `seaborn>=0.13,<1`

---

## 版本发布规范（SemVer）

- 从现在开始统一使用 `vMAJOR.MINOR.PATCH`（例如 `v0.3.0`），不再使用 `release-YYYYMMDD`。
- 版本号含义：
  - `MAJOR`：不兼容变更或重大架构升级；
  - `MINOR`：向后兼容的新功能（你说的“有明显功能新增”通常加这里）；
  - `PATCH`：向后兼容的问题修复/小优化。
- 当前阶段采用 `0.x.y`（产品仍在快速迭代）；当能力和接口趋于稳定后再进入 `1.0.0`。
- 版本变更明细统一记录在 `CHANGELOG.md`。

### 已完成迁移（旧标签 → 新标签）

- `release-20260126` → `v0.1.0`
- `release-20260204` → `v0.2.0`
- `release-20260205` → `v0.2.1`
- `release-20260214` → `v0.3.0`

---

## 常用命令示例

- **仅生成必要文件（更快更轻）**
```bash
python main.py --input-dir data/input --out-dir data/output --output-profile minimal
```

- **不生成报告 HTML/Markdown（只要 CSV/JSON）**
```bash
python main.py --input-dir data/input --out-dir data/output --no-report
```

- **只跑指定店铺**
```bash
python main.py --input-dir data/input --out-dir data/output --only-shop US
```

---

## AI 报告（可选）
默认不调用模型，避免误耗 token。需要时：
1) 复制 `.env.example` → `.env` 并填写：
   - `LLM_PROVIDER`
   - `LLM_API_KEY`
   - `LLM_MODEL`
2) 运行：
```bash
python main.py --input-dir data/input --out-dir data/output --ai-report
```

### AI 报告多‑Agent（更全面，可选）
用于 `ai/ai_suggestions.md` 的三角色裁决版（Analyst/Challenger/Judge）：
```bash
python main.py --input-dir data/input --out-dir data/output --ai-report-multiagent
```

### AI Dashboard 双Agent（可选）
用于 dashboard 的“决策建议（Top5）”结构化输出（双Agent审校），不改核心口径。
```bash
python main.py --input-dir data/input --out-dir data/output --ai-dashboard
```

### AI Dashboard 多‑agent（LangGraph+Guardrails+Promptfoo，可选）
用于 dashboard 的多轮思考与可评估输出，会生成：
- `ai/ai_dashboard_suggestions.json`
- `ai/ai_dashboard_eval.json`
- `ai/ai_dashboard_promptfoo.yaml`（Promptfoo 模板）
```bash
python main.py --input-dir data/input --out-dir data/output --ai-dashboard-multiagent
```

只想生成提示词不调用模型：
```bash
python main.py --input-dir data/input --out-dir data/output --ai-prompt-only
```

---

## 配置说明
- 运营策略：`config/ops_policy.json`
- 总选项档位：`config/ops_profile.json`（建议日常只改这里）
- 生命周期参数：`src/lifecycle/lifecycle_config.json`（支持 `category_default/category_overrides` 做类目阈值覆盖）
- 生命周期阶段连续性：`launch_days` 现在按“首单后连续窗口”判定 launch，不再因短期波动出现 `launch→mature→launch` 回跳。
- 生命周期稳定性：`phase_min_segment_days` 控制阶段最短驻留天数（默认 3 天），用于吸收 1-2 天抖动段。

### 生命周期类目阈值覆盖示例（`src/lifecycle/lifecycle_config.json`）
```json
{
  "category_default": {
    "min_mature_orders": 20,
    "low_inventory": 20
  },
  "category_overrides": [
    {
      "name": "fast_moving",
      "match": ["beauty", "grocery"],
      "min_mature_orders": 35,
      "low_inventory": 35
    },
    {
      "name": "slow_moving",
      "match": ["furniture", "home decor"],
      "min_mature_orders": 10,
      "min_peak_sales_roll": 6
    }
  ]
}
```

### 动作闭环与促销校正参数（`config/ops_policy.json`）
- `dashboard.promo_adjustment.*`：控制 compare 的促销/季节性校正（只影响 `*_corrected` 字段）
- `dashboard.action_scoring.weight_action_loop_score`：闭环分权重（越高越偏向历史高分动作）
- `dashboard.action_scoring.action_loop_min_support`：动作闭环最低样本数
- `dashboard.action_scoring.action_loop_recent_window_days`：闭环统计回看天数

### 广告执行优先级（本次增强）
- `dashboard/action_execution_guide.csv` 新增“可执行版动作手册”：每条动作给出 `decision_basis / execution_style / operator_steps / expected_signal / rollback_guard`，方便运营按步骤执行而不是只看规则结论。
- `reports/dashboard.md` 的“决策建议（Top5）/本周行动（Top3）”改为运营可读卡片：每条建议固定展示 `描述 / 证据 / 执行 / 观察 / 回滚 / 责任`，不再使用长串 `|` 拼接文本。
- `reports/dashboard.md` 新增“生命周期阶段线（交互对比）”：按单个 ASIN 展示阶段随时间变化，作为甘特图的并行解释视图（不替代原时间轴）；支持按类目/阶段/关键词筛选后再下钻单品。
- `reports/dashboard.md` 的 `Action Board（运营聚焦版）` 改为中文动作短语 + 执行风格（如“否定低意图词（先止损后保量）”），并清理链接噪音，便于运营一眼读懂。
- `dashboard/action_board.csv` 与 `dashboard/action_execution_guide.csv` 增加 `strategy_context / action_intensity`，按“生命周期阶段 + 利润方向”输出不同话术和动作强度（L1谨慎/L2标准/L3强动作）。
- `dashboard/keyword_topics_action_hints.csv` 新增 `hint_priority_score / owner / risk_level`，并补充 `execution_style / expected_signal / rollback_guard`，建议不再只有“规则判定”，而是“先做什么、观察什么、何时回滚”。
- `dashboard/placement_rebalance_plan.csv` 提供广告位预算 from→to 建议（优先同 Campaign 平移；无承接位时回收到 `RESERVE`），并新增 `execution_style / expected_signal / rollback_guard / next_step`。
- `config/ops_policy.json -> dashboard.placement_rebalance.*` 支持广告位平移阈值配置（平移比例、最小金额、每个 Campaign 的建议条数等）。

---

## Build in public v1 对齐清单
- ✅ 项目定位清晰（L0 输出建议、不改广告）
- ✅ 可运行（依赖 + 命令 + 默认目录）
- ✅ 输出入口明确（START_HERE.html / dashboard.html）
- ✅ 隐私边界清晰（.gitignore 统一管理）

---

## 故障排查
- **依赖安装失败**：优先使用虚拟环境再安装依赖
- **无输出/找不到报表**：确认 `--input-dir` 指向正确目录，且文件命名包含 SP/SB/SD + 报表关键词
- **Excel 读取警告**：`openpyxl` 的样式警告可忽略，不影响读取

---

## 许可与声明
- 本项目为离线分析工具，输出结果仅供运营决策参考
- 如需自动化投放或写回广告，请评估权限、审计与风控后再进入 L1/L2 阶段

## 作者与联系
- 博客：https://amzalysis.com/
- 公众号：跨境Ai视界

## 许可证
本项目采用 MIT License，详见 `LICENSE`。

amazon-ad-ai-kanban

amazon-ad-ai-kanban Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

amazon-ad-ai-kanban

amazon-ad-ai-kanban Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README