# SKG TK 二创验证 — 当前状态（2026-05-18）

## 一句话
当前产品方向已收窄为“信息流广告快速复刻”：TK 链接 / 上传视频后，先下载源视频，再并行跑音频文案路和视频视觉路；视频视觉路自动抽 6 张人物定向随机参考帧；产品素材独立成池，自动识别视角并补缺角度；分镜工作台按逐句时间轴写新口播、人物/产品需求和首尾帧规划。当前暂停直接提交视频模型，先逐条生成并审核首帧 / 尾帧。

## 路径 / 端口
- 当前工作树：`/Users/kangwan/Projects/business/20260512-20260512-skg-tk-二创验证-backend/`
- 主项目路径：`/Users/kangwan/Projects/business/20260512-20260512-skg-tk-二创验证/`
- 后台启动：`./scripts/start-dev-background.sh`（前端 4290，后端 4291，launchd 托管）
- 后台停止：`./scripts/stop-dev-background.sh`
- web dev：`cd web && npm run dev`
- api dev：`cd api && uvicorn main:app --host 127.0.0.1 --port 4291`
- 注意：后端不要带 `--reload` 跑下载、抽帧、音频和生图等长任务。

## 当前模型分工
`LLM_BASE_URL` 默认走 `https://ai.skg.com/ezlink/v1`，图片同样默认走 `IMAGE_BASE_URL=https://ai.skg.com/ezlink/v1`，语音默认走 `https://ai.skg.com/azure`，生产视频默认走 `https://ai.skg.com/doubao`。

| 任务 | 当前模型 / 通道 | 备注 |
|---|---|---|
| TK 下载 | `yt-dlp` + 可选 cookies | 公开视频裸下载；受限视频可配 `YTDLP_COOKIES_FILE` 或 `YTDLP_COOKIES_FROM_BROWSER`，也可直接上传 MP4。 |
| 远端 ASR | `ASR_MODEL=whisper-1` | 失败后进本机 ASR，再进多模态兜底。 |
| 本机 ASR | `LOCAL_ASR_MODEL=mlx-community/whisper-tiny` | 默认二级兜底，优先产出真实逐句时间轴。 |
| ASR 兜底 / 音频分析 | `ASR_FALLBACK_MODEL=gemini-2.5-flash` | 多模态音频兜底；后端会拒绝假字幕、重复文本和覆盖率过低结果。 |
| 字幕翻译 | `TRANSLATE_MODEL=gemini-2.5-flash` | 保留 Gemini。 |
| 画面理解 | `VISION_MODEL=gpt-4o` | 关键帧 Vision 已切 GPT；旧环境若写 `gemini-*` 会自动归一化到 `GPT_TEXT_MODEL`。 |
| 通用改写 / 分镜描述 | `REWRITE_MODEL=gpt-4o` | 已切 GPT；旧 Gemini 覆盖值会自动归一化。 |
| 新口播改写 | `AUDIO_REWRITE_MODEL=gpt-4o` | 默认跟随 `REWRITE_MODEL`；旧 Gemini 覆盖值会自动归一化。 |
| 产品视角识别 | `PRODUCT_VIEW_MODEL=gpt-image-2` | 产品图批量识别视角、左右 / 上下 / 内外侧、用途和风险。 |
| 所有生图 / 修图 | `gpt-image-2` | 服务端硬锁，无图片模型 fallback；覆盖关键帧生图、水印清理、元素提取、主体资产包、产品补角度、首尾帧。 |
| 配音 | `VOICE_PROVIDER=azure_openai` + `AZURE_TTS_MODEL=gpt-4o-mini-tts` | 语音固定 Azure OpenAI TTS。后端会按 `AZURE_TTS_PATHS` 依次尝试路径，便于区分路径错误和整条语音服务不可用。 |
| 视频 | `VIDEO_MODEL=seedance` | 当前主流程暂停直接提交；生产通道默认 `ai.skg.com/doubao`，Seedance 真实 ID 由 `VIDEO_MODEL_SEEDANCE` 配置。 |

## 当前主流程
| 步 | 模块 | 状态 | 备注 |
|---|---|---|---|
| 1 | 输入 / 下载 | 已通 | TK 链接或上传视频创建 job，下载完成后进入分析队列。 |
| 2 | 音频文案路 | 已通 | 拆 `audio.wav`，ASR、翻译、讲话人 / 节奏 / 背景音分析；结果默认折叠展示。 |
| 3 | 视频视觉路 | 已通 | 自动抽 6 张人物定向随机参考帧；当前工作区按 9:16 原视频播放秒数手动补帧。 |
| 4 | 相似主体资产 | 已通 | 用关键帧和可选内置角色生成同一主体的 10 张白底视图。 |
| 5 | 产品资产池 | 已通 | 上传 / 内置产品图统一入池，自动识别视角、结构点、用途、风险，缺角度可补图。 |
| 6 | 分镜工作台 | 已通 | 按逐句时间轴编辑新口播、镜头类型、人物 / 产品开关、首帧 / 尾帧规划。 |
| 7 | 首尾帧闸门 | 已通 | 每条分镜先用相似主体视图和产品素材生成首帧 / 尾帧，审核后保存。 |
| 8 | 视频候选 | 暂停直提 | 历史候选保留展示；当前不再一键打 Seedance，等首尾帧审核后再开放单条提交。 |

## 关键文件
- `api/main.py` — FastAPI 后端、模型路由、任务状态、ASR/翻译/音频分析、生图、产品识别、首尾帧和视频接口。
- `api/database.py` — 后端数据库层；当前用 SQLite 保存 document / job / media asset 元数据，媒体文件仍在 `jobs/<jobId>/`。
- `api/.env.example` — 本地模型和网关模板；已包含 `GPT_TEXT_MODEL=gpt-4o`。
- `deploy/.env.production.example` — 生产环境模板；视频默认 SKG Doubao / Seedance 网关。
- `RULES.md` — 启动、部署事实、模型环境变量和项目规则。
- `docs/source-analysis.html` — 源码解析页；任何影响产品理解、接口、模型分工或操作路径的改动都要同步这里。
- `web/components/ad-recreation-board.tsx` — 当前信息流复刻主工作台。
- `web/components/media-asset-tile.tsx` — 统一媒体素材缩略图、hover 放大、删除和状态遮罩组件。
- `web/lib/api.ts` — 前端 API client 和运行模型标注类型。

## 主要 API
```
GET  /health
GET  /documents
POST /jobs
POST /jobs/{id}/download/retry
POST /jobs/upload
GET  /jobs
GET  /jobs/{id}
DELETE /jobs/{id}
POST /jobs/{id}/analyze
POST /jobs/{id}/transcribe
POST /jobs/{id}/frames?t=<sec>
DELETE /jobs/{id}/frames/{idx}
POST /jobs/{id}/frames/{idx}/describe
POST /jobs/{id}/frames/{idx}/cleanup
POST /jobs/{id}/frames/{idx}/cleanup/apply
POST /jobs/{id}/frames/{idx}/generate
POST /jobs/{id}/frames/{idx}/scene-asset
POST /jobs/{id}/frames/{idx}/elements
POST /jobs/{id}/frames/{idx}/elements/{element_id}/cutout
POST /jobs/{id}/frames/{idx}/elements/{element_id}/subject-assets
POST /jobs/{id}/assets
PUT  /jobs/{id}/product-refs
POST /jobs/{id}/assets/product-views/analyze
POST /jobs/{id}/assets/product-angle
POST /jobs/{id}/script/rewrite
PUT  /jobs/{id}/frames/{idx}/storyboard
POST /jobs/{id}/frames/{idx}/storyboard/video
```

## 当前约束 / 不要踩
1. 图片 / 视频 / 抽帧 / 产品图 / 生成图 / 首尾帧 / 视频候选缩略图默认复用 `web/components/media-asset-tile.tsx`。
2. 所有生图入口服务端只允许 `gpt-image-2`，不要重新加 Gemini 图片模型或其他 fallback。
3. 画面理解和文案改写默认归 GPT：`VISION_MODEL`、`REWRITE_MODEL`、`AUDIO_REWRITE_MODEL` 会拦截旧 `gemini-*` 覆盖值。
4. Gemini 仍保留在 ASR fallback / 音频分析 / 翻译链路，不要误删。
5. 语音只走 Azure OpenAI TTS；不要新增或依赖其他配音通道配置。
6. 当前主流程不直接批量提交视频；先走“分镜规划 → 首尾帧 → 人工审核”。
7. 产品素材池默认是“同一产品”，不做不同产品身份判断；视角识别必须按佩戴者左 / 右、上 / 下、内 / 外侧描述。
8. 自动抽帧默认是 `frames=6` + `target=random_subject` + `quality=accurate` + `mode=replace`；如果需要特定动作或表情，用“当前点抽帧”手动补。
9. 文档是顶层业务归类：每个 TK 链接或上传视频默认一个 `document`，`job` 归属到 `document_id`；DB 存元数据和文件索引，视频 / 图片 / 音频文件不进 DB。
10. 后端长任务不要用 `--reload`。
11. 关键帧 `index` 是稳定 ID，不等于数组下标；前端取帧用 `frames.find(x => x.index === idx)`。
12. TikTok cookies 属于账号登录态，只能放本机 / 服务器私有环境；不要提交 cookies 文件或账号密码。

## 最近变更
- 2026-05-18：TK 链接下载新增 `YTDLP_COOKIES_FILE` / `YTDLP_COOKIES_FROM_BROWSER` 支持；受限视频失败时前端提示上传 MP4 或配置后端 cookies 登录态。
- 2026-05-18：素材输入端失败任务支持重新下载 / 重新解析；选中失败且无 `video_url` 的 TK 素材时调用后端重试接口，已有视频的失败任务会清掉自动触发标记并重新跑音频/视觉路。
- 2026-05-18：清理个人语音通道残留，`/health`、前端类型、环境模板和文档不再暴露相关字段或配置。
- 2026-05-18：新增后端数据库层，SQLite 默认落在 `APP_DB_URL` / `DATABASE_URL` 或 `JOBS_DIR/app.db`；`/documents` 返回文档归类列表，`/health.database` 返回 DB 状态。
- 2026-05-18：`VISION_MODEL`、`REWRITE_MODEL`、`AUDIO_REWRITE_MODEL` 切到 GPT 默认模型 `gpt-4o`，并加旧 Gemini 环境变量归一化保护。
- 2026-05-18：语音通道固定 Azure OpenAI TTS，并按 `AZURE_TTS_PATHS` 尝试语音路径。
- 2026-05-18：当前主路径暂停直接提交视频，改为逐条首尾帧闸门。
- 2026-05-18：媒体素材交互统一收口到 `MediaAssetTile`。
- 2026-05-18：产品图视角识别和产品缺角度补图收敛到 `gpt-image-2`。
