init: 商品图合规检测工具（豆包初筛 + DeepSeek 复检级联）

- src 标准布局：config/providers/pipeline/report + CLI/Tk GUI 双入口 - 级联省钱：豆包全量初筛，仅无违规/违规不明图进 DeepSeek 复检（含两票复核） - 输出：时间戳目录 + 分类文件夹图片归档 + Excel 报表 - 30 个单元测试（tests/，测试图片不入库）
2026-09-02 15:28:51 +08:00
commit 08d26710b4
20 changed files with 2513 additions and 0 deletions
@@ -0,0 +1,105 @@
+# 商品图合规检测工具
+
+同一份 17 类违规检测提示词，两级级联调用视觉模型，在控制成本的同时从严检测：
+
+```
+全部图片 ──▶ 豆包（火山方舟 Ark）初筛 ──┬─ 判为违规 ──▶ 直接定稿（便宜，拦下大头）
+                                        └─ 无违规/违规不明/异常 ──▶ DeepSeek 复检
+                                                                     └─ 仍判无违规 ──▶ 追加两票复核（3票取多数）
+```
+
+## 输出结构
+
+指定输出目录后，自动建立时间戳文件夹，按分类归档图片，Excel 放在一级目录：
+
+```
+<输出目录>/检测结果_20260902_151603/
+├── 违规检测结果_20260902_151604.xlsx      # 检测明细 + 统计汇总
+├── 12. 侵权 - 除人物外的其他侵权/  *.jpg
+├── 13. 侵权 - 人物相关（…）/
+├── 无违规/  ……
+```
+
+## 使用方式
+
+### exe 版（dist/ 目录）
+
+- `商品图合规检测工具.exe`：双击打开图形界面（零配置：选图片文件夹和输出目录即可）。
+- `商品图合规检测工具CLI.exe`：命令行版，用法同下方 CLI。
+- 首次运行会在 exe 同目录生成 `config.ini` 模板；GUI 会弹窗引导填写
+  豆包 API Key / 接入点、DeepSeek API Key / 模型，四项填完保存即可。
+- 内置提示词（打包进 exe）；界面上也可另选 txt 覆盖。
+
+### 源码运行（Python ≥3.10）
+
+```bash
+uv run violation-detector-gui                 # GUI
+uv run violation-detector tests -o output     # CLI
+# 或免安装：
+PYTHONPATH=src python -m violation_detector.gui
+PYTHONPATH=src python -m violation_detector tests -o output
+```
+
+### 重新打包
+
+```bash
+uv run --with pyinstaller --with aiohttp --with openpyxl \
+  pyinstaller --noconfirm --clean --onefile --windowed \
+  --name 商品图合规检测工具 --add-data "prompts.txt;." --paths src app_gui.py
+uv run --with pyinstaller --with aiohttp --with openpyxl \
+  pyinstaller --noconfirm --clean --onefile \
+  --name 商品图合规检测工具CLI --add-data "prompts.txt;." --paths src app_cli.py
+```
+
+## CLI 用法
+
+```
+商品图合规检测工具CLI <图片文件夹> [选项]
+
+  -o, --output DIR     输出目录（默认为图片文件夹）
+  --mode               cascade（默认）/ doubao / deepseek
+  --no-verify          跳过 DeepSeek 无违规两票复核
+  --prompt FILE        自定义提示词（默认内置 prompts.txt）
+  --workers-ark/--workers-ds/--max-tokens   调优项（默认即可）
+```
+
+## 配置（config.ini，自动生成）
+
+缺失必填项时：GUI 弹窗引导填写；CLI 打印缺哪些项后退出。也可用环境变量
+`ARK_API_KEY` / `ARK_MODEL_ID` / `DEEPSEEK_API_KEY` / `DEEPSEEK_MODEL` 覆盖。
+
+```ini
+[ark]
+api_key = ...
+model_id = ep-xxxx
+[deepseek]
+api_key = sk-...
+model = deepseek-v4-flash-vision-exp
+max_tokens = 5000
+```
+
+## 项目结构
+
+```
+├── src/violation_detector/
+│   ├── config.py     # 配置（自动生成 ini、缺项检测、冻结环境路径）
+│   ├── providers.py  # 豆包/DeepSeek 异步客户端，统一结果结构
+│   ├── pipeline.py   # 级联调度、断点缓存(runs/)、两票复核、成本汇总
+│   ├── report.py     # 时间戳输出目录、分类归档、Excel 报表
+│   ├── cli.py / gui.py
+├── app_gui.py / app_cli.py   # 启动器 + PyInstaller 入口
+├── prompts.txt       # 内置提示词
+├── runs/             # 分阶段缓存（断点续跑；删缓存即全量重跑）
+├── dist/             # 打包产物 exe
+└── legacy/           # 早期脚本与实验数据
+```
+
+## 检测规则与已知特性
+
+- 分类按提示词 17 类标准输出唯一分类，自动归一化写法差异。
+- DeepSeek：temperature=0 + JSON 模式、max_tokens=5000（全量梯度实测零失败最小档）。
+- 无违规两票复核：3 票一致才稳；2:1 保留多数但标记“人工复核”；分歧从严取违规类。
+- 边界图存在运行间抖动（同为 temp=0 重测全量一致率约 68%），与 max_tokens 无关；
+  报表“票型/复核”列已标出分歧图，建议人工终审。
+- 级联成本：DeepSeek 只处理豆包放行的少数存疑图（单张约 1-1.6 分钱，
+  空闲时段半价；高峰=工作日 9-12、14-18 点）。