86 lines
8.3 KiB
Markdown
86 lines
8.3 KiB
Markdown
# SKG AI 素材管线 - TK 二创验证
|
||
|
||
## 启动
|
||
- 后台启动（不弹 Terminal）：`./scripts/start-dev-background.sh`（通过 macOS launchd 后台托管；前端 4290 + 后端 4291，日志写入 `.logs/`）
|
||
- 后台停止：`./scripts/stop-dev-background.sh`
|
||
- 前端 dev：`cd web && npm run dev`（Next.js 16，端口 4290）
|
||
- 后端 dev：`cd api && uvicorn main:app --host 127.0.0.1 --port 4291`（FastAPI，端口 4291，重任务用）
|
||
- 注意：后端不要带 `--reload` 跑长下载 / 抽帧 / 音频任务；reload 会等待后台任务结束，导致 4291 端口占用但新请求卡住。
|
||
|
||
## 立项决策快索引
|
||
- 详见 `CLAUDE.md` 立项决策段 + `.memory/plan.md` 七步管线拆解
|
||
- 风格：`04-Dark-Gallery-Ambient`（路径：`~/Projects/research/20260305-网页风格库/04-Dark-Gallery-Ambient.md`）
|
||
- 第一冲刺：步骤 1-4（下载 / 拆轨 / 关键帧 / ASR+翻译）
|
||
- 当前产品方向（2026-05-17 再确认）：先解决信息流广告快速复刻的第一步，不再沿用“开始后自动抽帧、分镜、元素生成、合成”的默认做法。主界面为“左侧素材输入列 + 右侧音频解析工作表”。用户粘贴 TK 链接或上传视频后点击“开始”，系统自动下载源视频；下载完成后优先提取原音频文案/字幕，并分析讲话人、语速节奏、背景音乐/环境声/音效。抽帧、分镜规划、产品融入、相似主体高清视图包（最多 10 张，含肩颈/后背特写）和视频合成暂作为后续能力保留，不在当前第一步自动触发。
|
||
|
||
## 部署事实
|
||
- 平台：VPS `76.13.31.179`（Ubuntu 24.04 / Docker Compose / Coolify Traefik）
|
||
- 发布状态：已部署并验证（2026-05-15）；`https://marketing.skg.com` 已启用应用内登录页，认证后首页 200，`/api/health` 返回 `ok:true`
|
||
- 主站 / 前端：`https://marketing.skg.com`
|
||
- API / 后端：`https://marketing.skg.com/api`
|
||
- 代码仓库 / Gitea：`https://git.kang-kang.com/kangwan/20260512-skg-tk`
|
||
- 文档 / 解析：`docs/source-analysis.html`（项目内独立文档，不公开挂主应用路由）
|
||
- 管理后台：待定
|
||
- 服务器目录：`/opt/skg-marketing-studio`
|
||
- 生产启动：`docker compose -f docker-compose.prod.yml --env-file deploy/.env.production up -d --build`
|
||
- 生产架构：`web` 容器用 Nginx 承载 Next 静态导出；`/login/`、`/_next/`、`/assets/`、`/skg-logo-black.svg`、`/oasis-source/` 等登录页必需静态资源公开访问；未登录访问工作台跳转 `/login/`，`/api/` 通过 Nginx `auth_request` 校验 FastAPI 会话 Cookie 后反代到 `skg-marketing-api:4291`；Traefik 通过 `coolify` 外部网络接入 80/443
|
||
- 持久化目录：服务器 `./data/jobs` 挂载到后端 `/data/jobs`
|
||
- 登录凭证：用户名写下方快捷登录；密码明文备份只放服务器 `/root/skg-marketing-studio-login.txt`，生产环境变量 `WEB_AUTH_PASSWORD` / `WEB_AUTH_SESSION_SECRET` 只放服务器 `deploy/.env.production`
|
||
|
||
## 快捷登录
|
||
- 登录地址：`https://marketing.skg.com/login/`
|
||
- 用户名：`skg`
|
||
- 密码：见服务器 `/root/skg-marketing-studio-login.txt`（不入库）
|
||
- 说明：当前是生产入口应用内登录页；数据库密码、API Key、服务器 root 密码不要写这里
|
||
|
||
## 元数据回写清单
|
||
- 新增或变更公网地址后，必须同步更新 `.project.json.urls`
|
||
- 如果有网页后台登录：
|
||
- 可直接入库：写 `.project.json.quick_login`
|
||
- 不应入库：写 `.project.json.credentials` 引用
|
||
- 部署完成后，`RULES.md` 和 `.project.json` 必须同一次任务一起更新
|
||
|
||
## Git / 开发收口
|
||
- 工作看板全局规则适用于本项目：`/Users/kangwan/Projects/code/20260317-rules-dashboard/RULES.md`、`SCHEMA.md`、`rules/03-Git约定.md`、`rules/04-版本发布规则.md`
|
||
- 主分支：`main`
|
||
- 主远端：`origin` → `ssh://git@git.kang-kang.com:22222/kangwan/20260512-skg-tk.git`
|
||
- Gitea 网页仓库：`https://git.kang-kang.com/kangwan/20260512-skg-tk`
|
||
- 每次开发结束前必须执行并汇报 `git status -sb` 和变更范围
|
||
- 代码、规则、部署或元数据变更必须形成 `feat:`、`fix:`、`docs:`、`chore:`、`release:` 等人工语义 commit；`auto-save` 只算安全快照
|
||
- 能联网和鉴权时必须 `git push origin main`；如果不能推送，最终回复必须写清楚当前分支、领先/落后数量、最新未推送 commit 和失败原因
|
||
|
||
## 环境变量
|
||
- `LLM_BASE_URL` / `LLM_API_KEY`：OpenAI 兼容网关，用于 ASR、翻译、文案改写、音频分析等文本/音频理解模型调用
|
||
- `ASR_MODEL`：OpenAI Audio Transcriptions 音频转写模型，默认 `whisper-1`
|
||
- `ASR_FALLBACK_MODEL`：远端 ASR 和本机 ASR 都不可用时才尝试的多模态兜底，默认 `gemini-2.5-flash`；如果模型不能真实听到音频或返回疑似逐秒假字幕，后端必须拒绝写入时间轴
|
||
- `ASR_TIMEOUT_SECONDS`：远端 ASR / 音频分析单次请求超时，默认 45 秒，避免第一步长时间停在转录中
|
||
- `LOCAL_ASR_BIN` / `LOCAL_ASR_MODEL` / `LOCAL_ASR_TIMEOUT_SECONDS`：本机 ASR 兜底，默认使用 `/opt/homebrew/bin/mlx_whisper` + `mlx-community/whisper-tiny`，用于当前 SKG 网关 `/audio/transcriptions` 不可用时生成真实逐句时间轴
|
||
- `TRANSLATE_MODEL`：字幕翻译模型，默认 `gemini-2.5-flash`
|
||
- `REWRITE_MODEL`：通用改写/分镜描述模型，默认 `gemini-2.5-pro`
|
||
- `AUDIO_REWRITE_MODEL`：后续音频口播改写模型，默认跟随 `REWRITE_MODEL`；当前第一步不默认调用口播改写，只保留原文案和声音分析
|
||
- `AUDIO_PRODUCT_BRIEF`：音频口播改写时注入的 SKG 产品卖点
|
||
- `PRODUCT_VIEW_MODEL`：同一产品素材池的视角标注/自动识别模型；当前按项目要求强制使用 `gpt-image-2`
|
||
- `IMAGE_BASE_URL` / `IMAGE_API_KEY` / `IMAGE_MODEL`：OpenAI 兼容生图网关；当前所有生图入口一律强制使用 `gpt-image-2`，不做其他图片模型 fallback
|
||
- `GPT_IMAGE_MODEL` / `SUBJECT_ASSET_IMAGE_MODEL` / `SUBJECT_ASSET_IMAGE_MODELS`：保留兼容旧环境变量名，但服务端会强制主体 6 视图和所有其他生图入口都只使用 `gpt-image-2`
|
||
- `VOICE_PROVIDER`：配音通道，当前固定使用 `azure_openai`
|
||
- `AZURE_OPENAI_BASE_URL` / `AZURE_OPENAI_API_KEY`：微软 Azure OpenAI 协议配音网关；本地未单独配置 Key 时回退复用 `LLM_API_KEY`
|
||
- `AZURE_TTS_MODEL` / `AZURE_TTS_VOICE_ID` / `AZURE_TTS_VOICE_POOL` / `AZURE_TTS_PATH`：Azure OpenAI TTS 模型、默认音色、音色池和 OpenAI 协议语音路径
|
||
- `MINIMAX_API_KEY`：MiniMax T2A 配音 Key，只能放本地 `api/.env`，不能入库；当前第一步暂不默认调用
|
||
- `MINIMAX_TTS_BASE_URL` / `MINIMAX_TTS_MODEL` / `MINIMAX_TTS_VOICE_ID`：MiniMax 旧配音端点、模型和兜底音色配置，仅作为保留兼容；当前不作为默认语音通道
|
||
- `MINIMAX_TTS_VOICE_POOL`：MiniMax 英文随机音色池；当前默认男声 `English_magnetic_voiced_man`、女声 `English_Upbeat_Woman`、成熟声 `English_MaturePartner`，供后续新配音阶段使用
|
||
- `POE_API_KEY` / `VIDEO_API_KEY`：视频生成通道 Key，只能放本地环境变量
|
||
- `WEB_AUTH_USERNAME` / `WEB_AUTH_PASSWORD` / `WEB_AUTH_SESSION_SECRET`：生产网页登录和会话签名配置；密码和 session secret 只放服务器环境变量，不入库
|
||
- `FFMPEG_BIN` / `FFPROBE_BIN`：可选本地媒体二进制路径；本机 Homebrew ffmpeg 动态库损坏时，后端会自动跳过不可用的 PATH 版本并尝试本机静态 ffmpeg 备选，生产仍建议使用系统 ffmpeg/ffprobe
|
||
- 生产环境变量：服务器只使用 `deploy/.env.production`，模板为 `deploy/.env.production.example`；真实 Key 不入库
|
||
|
||
## 规则
|
||
- 不允许编造不存在的部署域名、账号、密码
|
||
- 没有公网地址时，`.project.json.urls` 保持空数组
|
||
- 任何部署或域名变化，都要先改元数据，再视为任务完成
|
||
- 用户给到源码 / 下载包 / 参考实现时，默认优先按源码实现和复刻，不先自创“类似效果”；如果因安全、依赖、性能或部署限制必须改写，必须先说明差异和原因。
|
||
|
||
## 注意事项
|
||
- 项目内源码解析页：`docs/source-analysis.html`
|
||
- 源码解析页是给产品协作和需求描述用的独立 HTML，不接入 Next 应用路由
|
||
- 后续任何功能、节点职责、接口、数据模型或用户操作路径变更，都要同步更新 `docs/source-analysis.html` 的对应章节和变更记录
|