kangwan/20260512-skg-tk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
48d4002cbd6d0ffb53ca0bfaff170643af814a02
20260512-skg-tk/RULES.md

9.3 KiB
Raw Blame History

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-18 再确认）：先解决信息流广告快速复刻的第一步，不再沿用“开始后线性完成抽帧、分镜、元素生成、合成”的旧做法。主界面为“左侧素材输入列 + 右侧信息流复刻工作表”。用户粘贴 TK 链接或上传视频后点击“开始分析”，系统自动下载源视频；下载完成后并行启动两条路：音频文案路提取原音频文案/字幕，并分析讲话人、语速节奏、背景音乐/环境声/音效；视频视觉路自动抽取参考帧，供人工选择可用主体并生成相似主体白底视图。产品图上传后独立形成产品资产包，自动识别视角/结构/比例并补缺角度。分镜工作台按逐句时间轴规划新口播、镜头类型、首帧/尾帧、人物需求和产品出现方式；当前暂停直接调视频模型，先逐条用“相似主体视图 + 产品素材池 + 首尾帧文字规划”生成并审核首帧/尾帧，保存规划后再决定哪些分镜进入单条视频候选。

部署事实

  • 平台：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
  • AI_HTTP_PROXY / IMAGE_HTTP_PROXY：可选的 AI 网关出站代理；本地 launchd 后台进程不一定继承 shell 的 http_proxy/https_proxy，如生图报 DNS / ConnectError，可在本地 api/.env 配置后重启后端。/health 只回传是否配置代理，不回传代理地址。
  • 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 保持空数组
  • 任何部署或域名变化，都要先改元数据，再视为任务完成
  • 用户给到源码 / 下载包 / 参考实现时，默认优先按源码实现和复刻，不先自创“类似效果”；如果因安全、依赖、性能或部署限制必须改写，必须先说明差异和原因。
  • 媒体素材交互为项目基底规则：任何图片、视频、抽帧、产品图、AI 生成图、首尾帧和视频候选缩略图，默认复用 web/components/media-asset-tile.tsx；必须支持鼠标停留顶层放大预览，可删除素材必须有删除按钮，预览不能被面板或滚动容器遮挡。

注意事项

  • 项目内源码解析页：docs/source-analysis.html
  • 源码解析页是给产品协作和需求描述用的独立 HTML，不接入 Next 应用路由
  • 后续任何功能、节点职责、接口、数据模型或用户操作路径变更，都要同步更新 docs/source-analysis.html 的对应章节和变更记录
Reference in New Issue View Git Blame Copy Permalink