diff --git a/.memory/worklog.json b/.memory/worklog.json index 2e14246..f1f449e 100644 --- a/.memory/worklog.json +++ b/.memory/worklog.json @@ -1,18 +1,5 @@ { "entries": [ - { - "files_changed": 1, - "message": "Codex 会话活跃 · 最近命令：codex · 分支 main · 1 项未提交变更 · 最近提交：auto-save 2026-05-20 14:01 (+1, ~1)", - "ts": "2026-05-20T06:03:58Z", - "type": "session-heartbeat" - }, - { - "files_changed": 2, - "hash": "2fe54d1", - "message": "auto-save 2026-05-20 14:07 (~2)", - "ts": "2026-05-20T14:07:12+08:00", - "type": "commit" - }, { "files_changed": 5, "hash": "6cd41a2", @@ -3207,6 +3194,19 @@ "type": "session-heartbeat", "message": "Codex 会话活跃 · 最近命令：codex · 分支 main · 1 项未提交变更 · 最近提交：auto-save 2026-05-26 00:19 (~5)", "files_changed": 1 + }, + { + "ts": "2026-05-26T06:53:30+08:00", + "type": "commit", + "message": "auto-save 2026-05-26 06:53 (~2)", + "hash": "c9d8fa7", + "files_changed": 2 + }, + { + "ts": "2026-05-25T22:54:48Z", + "type": "session-heartbeat", + "message": "Codex 会话活跃 · 最近命令：codex · 分支 main · 1 项未提交变更 · 最近提交：auto-save 2026-05-26 06:53 (~2)", + "files_changed": 1 } ] } diff --git a/.project.json b/.project.json index ee3e470..48cfa37 100644 --- a/.project.json +++ b/.project.json @@ -43,9 +43,15 @@ "name" : "FEISHU_OAUTH", "storage" : "api\/.env \/ deploy\/.env.production \/ 飞书开放平台", "type" : "oauth_app" + }, + { + "description" : "Postgres 服务端持久化配置，用于画布项目、用户索引、任务索引、资源索引和审计日志；生产密码只放服务器 deploy\/.env.production 的 POSTGRES_PASSWORD\/DATABASE_URL，不入库", + "name" : "POSTGRES_DATABASE", + "storage" : "deploy\/.env.production \/ docker-compose.prod.yml \/ 服务器 data\/postgres", + "type" : "database" } ], - "description" : "SKG 营销内容生产平台：根域名 https:\/\/marketing.skg.com 登录后直接进入个人生成画布，终端可见品牌位只保留 SKG logo。主路径为文生图、文生视频、图生视频；每个登录用户只看到自己的任务和结果。画布用于整理多次生成结果，图片\/视频资产继续写入当前用户自己的后端 job；旧 TK 复刻\/一键出片能力保留为高级入口。", + "description" : "SKG 营销内容生产平台：根域名 https:\/\/marketing.skg.com 登录后直接进入个人生成画布，终端可见品牌位只保留 SKG logo。主路径为文生图、文生视频、图生视频；每个登录用户只看到自己的任务和结果。画布项目已接入服务端 Postgres 持久化，浏览器 localStorage 只作为缓存和首次导入来源；图片\/视频资产继续写入当前用户自己的后端 job；旧 TK 复刻\/一键出片能力保留为高级入口。", "kind" : "app", "name" : "SKG 营销内容生产平台", "ownership" : "company", @@ -70,7 +76,7 @@ "username" : "飞书免登录；备用账号见 credentials.WEB_LOGIN" }, "stack" : [ - "Next.js + Python(yt-dlp\/ffmpeg) + OpenAI-compatible LLM + GPT Image 2 + Azure OpenAI TTS + Seedance\/Kling\/Veo video gateway" + "Next.js + Vue\/Vite canvas + FastAPI + Postgres + Python(yt-dlp\/ffmpeg) + OpenAI-compatible LLM + GPT Image 2 + Azure OpenAI TTS + Seedance\/Kling\/Veo video gateway" ], "status" : "active", "urls" : [ diff --git a/RULES.md b/RULES.md index 3380da8..51d2e36 100644 --- a/RULES.md +++ b/RULES.md @@ -12,7 +12,7 @@ - 详见 `CLAUDE.md` 立项决策段 + `.memory/plan.md` 七步管线拆解 - 风格：`04-Dark-Gallery-Ambient`（路径：`~/Projects/research/20260305-网页风格库/04-Dark-Gallery-Ambient.md`） - 第一冲刺：步骤 1-4（下载 / 拆轨 / 关键帧 / ASR+翻译） -- 当前产品方向（2026-05-25 上游画布能力恢复版）：默认入口是多人通用的 SKG 营销内容生产平台，`https://marketing.skg.com` 登录后直接进入个人生成画布，`/canvas/` 只作为旧链接兼容跳转到根域名。终端可见品牌位只放 SKG logo，不在主界面展示“生图生视频”“SKG 生成画布”或长系统名。画布本体尽量恢复 `chatfire-AI/huobao-canvas` 的成熟交互，不再削成三模式单输入框：保留首页推荐词、画布底部推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载等上游能力；多角度分镜、故事板、图转视频、绘本等工作流按上游结构创建节点。API 接入是例外：生成调用继续走本项目后端 `/api` 和当前登录 Cookie，不要求员工在浏览器配置个人 API Key；图片/视频模型选择只显示后端已经接通的媒体模型，不能让浏览器本地自定义或旧缓存模型进入生成下拉。API 设置弹窗只保留模型/端点配置外观，不能出现上游注册链接或外部品牌。用户登录后仍只看到自己的任务、结果和详情页，继续沿用后端 owner 隔离；每个浏览器的画布项目先保存在本地 localStorage，图片/视频资产按登录用户写入后端 job。旧 TK 复刻工作台、Agent Cut 一键出片和营销图文方案保留为高级/详情页能力，不再作为默认首页入口或默认理解框架。 +- 当前产品方向（2026-05-26 Postgres 持久化版）：默认入口是多人通用的 SKG 营销内容生产平台，`https://marketing.skg.com` 登录后直接进入个人生成画布，`/canvas/` 只作为旧链接兼容跳转到根域名。终端可见品牌位只放 SKG logo，不在主界面展示“生图生视频”“SKG 生成画布”或长系统名。画布本体尽量恢复 `chatfire-AI/huobao-canvas` 的成熟交互，不再削成三模式单输入框：保留首页推荐词、画布底部推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载等上游能力；多角度分镜、故事板、图转视频、绘本等工作流按上游结构创建节点。API 接入是例外：生成调用继续走本项目后端 `/api` 和当前登录 Cookie，不要求员工在浏览器配置个人 API Key；图片/视频模型选择只显示后端已经接通的媒体模型，不能让浏览器本地自定义或旧缓存模型进入生成下拉。API 设置弹窗只保留模型/端点配置外观，不能出现上游注册链接或外部品牌。用户登录后仍只看到自己的任务、结果和详情页，继续沿用后端 owner 隔离；画布项目以服务端 Postgres 为主持久化，浏览器 `localStorage` 只作为缓存和首次导入来源，图片/视频资产按登录用户写入后端 job。旧 TK 复刻工作台、Agent Cut 一键出片和营销图文方案保留为高级/详情页能力，不再作为默认首页入口或默认理解框架。 ## 部署事实 - 平台：VPS `76.13.31.179`（Ubuntu 24.04 / Docker Compose / Coolify Traefik） @@ -20,6 +20,7 @@ - Agent Cut 独立预览验证（2026-05-21）：已在 `2.24.28.41` 的 `/opt/skg-marketing-studio` 用 `docker-compose.standalone.yml` 启动 `skg-agent-api` / `skg-agent-web`；独立 compose 通过网络别名兼容 Nginx 的 `skg-marketing-api` upstream。该裸 IP HTTP 入口的服务器 `deploy/.env.production` 需要 `WEB_AUTH_COOKIE_SECURE=false`；本次已补齐 `WEB_AUTH_*` 后重启验证通过：未登录 `/agent/` 返回 302 到 `/login/`，登录后 `/agent/` 返回 200，`/api/agent-runs` 返回数组，容器内 `/health` 返回 `ok:true` 且 `auth_configured:true`。 - 最近部署验证（2026-05-25）：`84d9de6` 已通过 `./scripts/deploy-prod-safe.sh` 部署到 `/opt/skg-marketing-studio`，画布图片/视频模型选择收口到当前后端真实可用媒体模型。部署前脚本已备份生产私有环境、任务数据、资源库和 secrets 到 `/opt/skg-marketing-studio-backups/skg-marketing-preserve-20260525105910.tgz`；生产 Docker 重建后脚本内验证通过（web/API 容器 Up、`/` 302、`/login/` 200、缺失 `_next` 资源 404、未登录 `/api/health` 401、容器内 `api:health ok`、`api:ytdlp_cookie_args []`、未发现本地 API/dev URL 泄漏）。补验：外部访问 `https://marketing.skg.com/` 未登录返回 302 到 `/login/?next=/`，`https://marketing.skg.com/p/test` 未登录返回 302 到 `/login/?next=/p/test`；容器内 `/health` 返回 `image_options=auto,gpt-image-2,gemini-3-pro-image-preview`，`video_options=seedance:Seedance 2.0 Fast:doubao-seedance-2-0-fast-260128`，`video_duration_options=5,8,10,12,15`，图片尺寸为 `auto,1024x1536,1024x1024,1536x1024`，视频画幅为 `720x1280,1280x720,1024x1024,960x1280`；生产静态 bundle 命中 `GPT Image 2 / Gemini 图片 / Seedance 2.0 Fast / 1024x1536 / 720x1280`，未命中 `Nano Banana / Seedream / doubao-seedream / doubao-seedance-1 / sora-2 / Kling / Veo 3`。 - 生产配置验证（2026-05-25 23:49 CST）：已在服务器 `/opt/skg-marketing-studio/deploy/.env.production` 补齐飞书 OAuth 应用配置，并仅重建 `skg-marketing-api` 使环境变量生效；敏感 App Secret 不入库。验证结果：`https://marketing.skg.com/api/auth/config` 返回 `feishu_enabled=true`、`password_enabled=true`、`data_isolation_enabled=true`；`GET https://marketing.skg.com/api/auth/feishu/start?next=/` 返回 302 跳转到飞书授权页；容器内 `/health` 返回 `auth_modes.feishu=True`。 +- 最近部署验证（2026-05-26）：`c9d8fa7` 对应 Postgres 持久化代码已通过 `./scripts/deploy-prod-safe.sh` 部署到 `/opt/skg-marketing-studio`。生产新增 `skg-marketing-postgres` 容器，数据库持久化在服务器 `./data/postgres`，`DATABASE_URL` / `POSTGRES_PASSWORD` 只写服务器 `deploy/.env.production`。部署前脚本备份生产私有环境、任务数据、资源库和 secrets 到 `/opt/skg-marketing-studio-backups/skg-marketing-preserve-20260525225145.tgz`；生产 Docker 重建后脚本内验证通过（web/API/Postgres 容器 Up、Postgres healthy、`/` 302、`/login/` 200、缺失 `_next` 资源 404、未登录 `/api/health` 401、容器内 `api:health ok db connected`、`api:ytdlp_cookie_args []`）。补验：容器内 `/health` 返回 `database.enabled=true`、`database.connected=true`，`/api/auth/config` 返回 `feishu_enabled=true`、`password_enabled=true`、`data_isolation_enabled=true`；画布项目 API 可创建、读取、软删除记录；数据库索引计数为 users=1、jobs=26、assets=129、canvas_active=0、canvas_deleted=1、audit=2。 - 最近部署验证（2026-05-25）：`cce9779` 已通过 `./scripts/deploy-prod-safe.sh` 部署到 `/opt/skg-marketing-studio`，恢复 `chatfire-AI/huobao-canvas` 上游画布能力但保留 SKG 后端 `/api` 接入。部署前脚本已备份生产私有环境、任务数据、资源库和 secrets 到 `/opt/skg-marketing-studio-backups/skg-marketing-preserve-20260525102857.tgz`；生产 Docker 重建后脚本内验证通过（web/API 容器 Up、`/` 302、`/login/` 200、缺失 `_next` 资源 404、未登录 `/api/health` 401、容器内 `api:health ok`、`api:ytdlp_cookie_args []`、未发现本地 API/dev URL 泄漏）。补验：外部访问 `https://marketing.skg.com/` 未登录返回 302 到 `/login/?next=/`，`https://marketing.skg.com/canvas/` 返回 308 到 `/`，`https://marketing.skg.com/p/test` 未登录返回 302 到 `/login/?next=/p/test`；容器内静态 bundle 命中 `AI 润色 / 自动执行 / 推荐： / 首帧 / 尾帧 / 多角度分镜 / 儿童绘本 / 工作流模板 / 批量下载素材`，未命中上游注册链接、火宝欢迎文案、GitHub 入口或 `/huobao-canvas`。 - 最近部署验证（2026-05-25）：`e767d2b` 已通过 `./scripts/deploy-prod-safe.sh` 部署到 `/opt/skg-marketing-studio`，生产根域名改为直接进入个人生成画布，`/canvas/` 仅作为旧链接 308 跳转到 `/`。部署前脚本已备份生产私有环境、任务数据、资源库和 secrets 到 `/opt/skg-marketing-studio-backups/skg-marketing-preserve-20260525095839.tgz`；生产 Docker 重建后脚本内验证通过（web/API 容器 Up、`/` 302、`/login/` 200、缺失 `_next` 资源 404、未登录 `/api/health` 401、容器内 `api:health ok`、`api:ytdlp_cookie_args []`、未发现本地 API/dev URL 泄漏）。补验：容器内 `/usr/share/nginx/html/index.html` 为 Vue 画布产物，引用 `/assets/index-CioZwOvT.js` 且 title 为 `SKG`；静态 bundle 命中 `文生图 / 文生视频 / 图生视频`，未命中 `首帧生视频 / 首尾帧生视频 / 上传首帧 / 上传尾帧 / 推荐：`；外部访问 `https://marketing.skg.com/` 未登录返回 302 到 `/login/?next=/`，`https://marketing.skg.com/canvas/` 返回 308 到 `/`，`/p/test` 未登录返回 302 到 `/login/?next=/p/test`。 - 最近部署验证（2026-05-25）：`2a1ceee` 已通过 `./scripts/deploy-prod-safe.sh` 部署到 `/opt/skg-marketing-studio`，可见品牌位从文字命名收敛为 logo-only：首页、登录页和画布首页只显示 SKG logo，网页 title 和画布 title 为 `SKG`，首页入口按钮文案为“画布”。部署前脚本已备份生产私有环境、任务数据、资源库和 secrets 到 `/opt/skg-marketing-studio-backups/skg-marketing-preserve-20260525092749.tgz`；生产 Docker 重建后脚本内验证通过（web/API 容器 Up、`/` 302、`/login/` 200、缺失 `_next` 资源 404、未登录 `/api/health` 401、容器内 `api:health ok`、`api:ytdlp_cookie_args []`、未发现本地 API/dev URL 泄漏）。容器内静态产物复验：`index.html` 包含 `SKG` 和 `/skg-logo-black.svg`，首页入口包含“画布”，登录页只保留 logo；当前 `_next` 与 `/canvas` 产物未再命中 `SKG 生图生视频`、`SKG 生成画布`、`营销内容生产平台` 或 `内容生产画布` 等旧可见文案。 @@ -74,13 +75,13 @@ - 文档 / 解析：`docs/source-analysis.html`（项目内独立文档，不公开挂主应用路由） - 管理后台：待定 - 服务器目录：`/opt/skg-marketing-studio` -- 生产部署唯一入口：`./scripts/deploy-prod-safe.sh`（先在服务器备份 `deploy/.env.production`、`data/jobs`、资源库和 `secrets`，再用受保护 rsync 同步代码，最后 Docker 重建并运行 `verify-prod-docker.sh`） +- 生产部署唯一入口：`./scripts/deploy-prod-safe.sh`（先在服务器备份 `deploy/.env.production`、`data/jobs`、资源库和 `secrets`，如 Postgres 容器存在则额外导出 `pg_dump`，再用受保护 rsync 同步代码，最后 Docker 重建并运行 `verify-prod-docker.sh`） - 生产容器重建命令：`docker compose -f docker-compose.prod.yml --env-file deploy/.env.production up -d --build`；只允许脚本内部或明确只重启容器时使用，不允许再用裸 `rsync --delete` 手动同步。 - 独立预览容器重建命令：服务器 `/opt/skg-marketing-studio` 下执行 `docker compose -f docker-compose.standalone.yml --env-file deploy/.env.production up -d --build`；Web 暴露 `0.0.0.0:4290->80`，后端仅在 compose 内部网络暴露，`/api/` 由 Web 容器 Nginx 反代并复用应用内登录校验。 -- 生产架构：`web` 容器用 Nginx 承载 Next 静态导出与根域名 Vue / Vite 画布静态应用；构建时先生成画布，再 Next 静态导出，最后用画布产物覆盖 `web/out/index.html` 和 `/assets/`，使登录后的 `/` 直接进入画布；`/canvas/` 只做 308 兼容跳转到 `/`。`/login/`、`/_next/`、`/assets/`、`/skg-logo-black.svg`、`/oasis-source/` 等登录页必需静态资源公开访问；未登录访问工作台跳转 `/login/`；`/api/` 通过 Nginx `auth_request` 校验 FastAPI 会话 Cookie 后反代到 `skg-marketing-api:4291`；Traefik 通过 `coolify` 外部网络接入 80/443 +- 生产架构：`web` 容器用 Nginx 承载 Next 静态导出与根域名 Vue / Vite 画布静态应用；构建时先生成画布，再 Next 静态导出，最后用画布产物覆盖 `web/out/index.html` 和 `/assets/`，使登录后的 `/` 直接进入画布；`/canvas/` 只做 308 兼容跳转到 `/`。`/login/`、`/_next/`、`/assets/`、`/skg-logo-black.svg`、`/oasis-source/` 等登录页必需静态资源公开访问；未登录访问工作台跳转 `/login/`；`/api/` 通过 Nginx `auth_request` 校验 FastAPI 会话 Cookie 后反代到 `skg-marketing-api:4291`；FastAPI 通过内网 `DATABASE_URL` 连接 `skg-marketing-postgres:5432`，Postgres 不对公网暴露；Traefik 通过 `coolify` 外部网络接入 80/443 - Web 验收必须以生产 Docker 形态为准：前端是 `next export` 静态产物 + Nginx，不是 `next dev` / `next start`。任何 Web 改动部署后必须运行 `./scripts/verify-prod-docker.sh`，确认 `/login/`、`/_next/`、`/api/health`、本地 API 地址泄漏和 API 镜像 `.env` 污染检查通过；不能只用本地 `npm run build` 作为上线依据。 - 当前音频解析：`https://ai.skg.com/azure/v1` 的 `gpt-4o-transcribe` 当前返回 `DeploymentNotFound`，且官方 Azure OpenAI transcription 路径探测也未返回可用部署；生产临时复制本地成功策略，直接使用容器内多语言 `faster-whisper` 真实转写，默认语种为 `auto`，支持中文、英文和其他多语言原文识别，关闭 Gemini 多模态音频兜底。拿到真实 Azure ASR deployment 名后再恢复 `ASR_REMOTE_ENABLED=true`，并保持 `ASR_LANGUAGE` 为空或 `auto`，除非明确只想强制单一语种。 -- 持久化目录：服务器 `./data/jobs` 挂载到后端 `/data/jobs`；全局资源中心持久化在 `./data/asset_library`、`./data/prompt_library` 和 `./data/_trash` +- 持久化目录：服务器 `./data/jobs` 挂载到后端 `/data/jobs`；全局资源中心持久化在 `./data/asset_library`、`./data/prompt_library` 和 `./data/_trash`；Postgres 数据目录为服务器 `./data/postgres`，部署脚本通过 `pg_dump` 产出 `/opt/skg-marketing-studio-backups/skg-marketing-postgres-*.sql.gz` - TikTok 下载登录态：公开视频默认不带 cookies 直接下载，生产环境变量必须显式保持 `YTDLP_COOKIES_FILE=`、`YTDLP_COOKIES_FROM_BROWSER=` 为空，防止容器读取不存在的浏览器 cookies。只有 TikTok 明确要求登录态时，才使用服务器私有 cookies 文件 `./secrets/tiktok_cookies.txt` 挂载到 API 容器 `/run/secrets/tiktok_cookies.txt` 并配置 `YTDLP_COOKIES_FILE=/run/secrets/tiktok_cookies.txt`；`yt-dlp` 会在任务结束时回写 cookies，因此不要把该挂载设为只读；不要使用云端浏览器读取方案，也不要把 cookies 入库。生产容器严禁使用 `YTDLP_COOKIES_FROM_BROWSER=chrome`。 - 登录凭证：生产入口以飞书免登录为主；飞书 OAuth 的 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 只放服务器 `deploy/.env.production`，回调地址固定为 `https://marketing.skg.com/api/auth/feishu/callback` 并需要在飞书开放平台应用安全设置中登记。登录页读取 `/api/auth/config` 后，如果检测到飞书客户端并且 `feishu_enabled=true`，会自动跳转 `/api/auth/feishu/start`，普通浏览器仍保留“飞书免登录”按钮和备用账号。原账号密码登录保留为备用入口，用户名写下方快捷登录，密码明文备份只放服务器 `/root/skg-marketing-studio-login.txt`，`WEB_AUTH_PASSWORD` / `WEB_AUTH_SESSION_SECRET` 只放服务器 `deploy/.env.production`。开启 `AUTH_DATA_ISOLATION_ENABLED=true` 后，新建任务、素材任务和一键出片记录按登录用户隔离；历史无 owner 的旧任务只对备用账号可见，飞书用户互不可见。 - 禁止手动裸 `rsync --delete` 到服务器；必须使用 `./scripts/deploy-prod-safe.sh`。如遇极端情况必须手动同步，命令必须同时包含 protect/exclude：`.git`、`.memory`、`.logs`、`.pids`、`data`、`jobs`、`secrets`、`api/jobs`、`api/.env`、`api/.env.local`、`api/.env.production`、`deploy/.env.production`、`web/node_modules`、`web/.next`、`web/out`。不要把本地 `api/.env` 或 `deploy/.env.production` 覆盖到 `/opt/skg-marketing-studio`，也不要删除服务器 `data/jobs`，否则会清空案例、登录和模型配置。 diff --git a/docs/source-analysis.html b/docs/source-analysis.html index 203e320..28cadab 100644 --- a/docs/source-analysis.html +++ b/docs/source-analysis.html @@ -541,12 +541,12 @@ 画布构建 cd web && npm run build - 受同一登录保护的 Vue / Vite 画布应用。构建时先执行 pnpm build:canvas 生成 web/canvas-app/dist，再执行 Next 静态导出，最后由 web/scripts/sync-canvas-root.mjs 把画布产物覆盖到 web/out 根目录；Nginx 登录校验后的 / fallback 到画布 index.html，/canvas/ 只做 308 兼容跳转。画布项目当前保存在浏览器 localStorage，生成出来的图片 / 视频资产通过本项目 /api 写入当前登录用户自己的后端 job。 + 受同一登录保护的 Vue / Vite 画布应用。构建时先执行 pnpm build:canvas 生成 web/canvas-app/dist，再执行 Next 静态导出，最后由 web/scripts/sync-canvas-root.mjs 把画布产物覆盖到 web/out 根目录；Nginx 登录校验后的 / fallback 到画布 index.html，/canvas/ 只做 308 兼容跳转。画布项目以服务端 Postgres 为主持久化，浏览器 localStorage 只作为缓存和首次导入来源；生成出来的图片 / 视频资产通过本项目 /api 写入当前登录用户自己的后端 job。 生产部署 ./scripts/deploy-prod-safe.sh - 服务器目录为 /opt/skg-marketing-studio；后端任务文件挂载到 ./data/jobs，全局资源中心挂载到 ./data/asset_library、./data/prompt_library 和 ./data/_trash，真实 Key 只放服务器 deploy/.env.production。生产部署唯一入口是 deploy-prod-safe.sh：先备份服务器 env、案例和资源库，再用 protect/exclude 保护 data/、jobs/、secrets/、deploy/.env.production 后同步代码，最后 Docker 重建并跑 verify-prod-docker.sh。禁止再用裸 rsync --delete 手动同步。 + 服务器目录为 /opt/skg-marketing-studio；后端任务文件挂载到 ./data/jobs，全局资源中心挂载到 ./data/asset_library、./data/prompt_library 和 ./data/_trash，Postgres 数据目录为 ./data/postgres，真实 Key 和数据库密码只放服务器 deploy/.env.production。生产部署唯一入口是 deploy-prod-safe.sh：先备份服务器 env、案例、资源库和 secrets，如 Postgres 容器存在则额外导出 pg_dump，再用 protect/exclude 保护 data/、jobs/、secrets/、deploy/.env.production 后同步代码，最后 Docker 重建并跑 verify-prod-docker.sh。禁止再用裸 rsync --delete 手动同步。 前端开发服务 @@ -581,16 +581,17 @@

2026-05-25 根域名画布版：https://marketing.skg.com 登录后直接进入个人生成画布，不再先进入 React 单对话框首页再点画布；/canvas/ 只保留为旧链接兼容跳转。后续优先少改成熟画布结构，只在必要时改模式文案、生成接入和结果/队列显示。

2026-05-25 上游能力恢复版：用户明确要求“API 没关系，其他恢复，别削弱”。因此根域名画布恢复 chatfire-AI/huobao-canvas 的成熟节点和工作流结构：推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置、多角度分镜、故事板、绘本和批量下载都保留；只继续替换品牌、路由和 API 接入。生成请求仍走 SKG 后端 /api 与登录 Cookie，员工不需要个人 API Key。

2026-05-25 媒体模型接入收口：图片和视频模型选择只暴露当前后端真实可用项：图片为 auto、gpt-image-2、gemini-3-pro-image-preview；视频当前只接通 Seedance 2.0 Fast（真实模型 doubao-seedance-2-0-fast-260128）。旧上游的 Nano Banana、Seedream、Kling、Veo 或浏览器本地自定义媒体模型不能进入生成下拉，避免同事选到实际不可用的模型。

+

2026-05-26 公司沉淀版：画布项目从浏览器本地存储升级为服务端 Postgres 持久化；localStorage 只作为离线缓存和首次导入来源。后端同时建立用户、任务、资源索引和审计表，保留原有 state.json 文件作为任务详情真源，避免一次迁移动到大文件资产结构。

-

当前默认业务管线是“个人隔离任务 → 根域名进入个人画布 → 用提示词、推荐词、AI 润色或工作流模板创建节点 → 画布自动执行或手动连接图片/视频/文本节点 → 生成结果沉淀在当前个人画布 → 需要时进入详情页继续编辑”。画布不再被削成三模式入口；首帧、尾帧、参考图、图生视频、多角度分镜、故事板和绘本等上游概念按节点能力保留。底层生成仍由 web/canvas-app/src/hooks/useApi.js 适配到本项目 /creative/jobs/image、/jobs/{id}/frames/{idx}/generate、/jobs/{id}/frames/{idx}/storyboard/video，并按当前登录用户写入个人 job。图片尺寸只显示 auto、1024x1536、1024x1024、1536x1024；视频画幅只显示 720x1280、1280x720、1024x1024、960x1280；视频时长只显示 5/8/10/12/15 秒。多人互不影响依赖后端 owner_id 和飞书 / 备用登录会话隔离。旧 React 单对话框首页、信息流复刻链路仍保留在源码里作为回滚/高级能力，但不作为生产默认入口。

+

当前默认业务管线是“个人隔离任务 → 根域名进入个人画布 → 画布项目同步到服务端 Postgres → 用提示词、推荐词、AI 润色或工作流模板创建节点 → 画布自动执行或手动连接图片/视频/文本节点 → 生成结果沉淀在当前个人画布 → 需要时进入详情页继续编辑”。画布不再被削成三模式入口；首帧、尾帧、参考图、图生视频、多角度分镜、故事板和绘本等上游概念按节点能力保留。底层生成仍由 web/canvas-app/src/hooks/useApi.js 适配到本项目 /creative/jobs/image、/jobs/{id}/frames/{idx}/generate、/jobs/{id}/frames/{idx}/storyboard/video，并按当前登录用户写入个人 job。图片尺寸只显示 auto、1024x1536、1024x1024、1536x1024；视频画幅只显示 720x1280、1280x720、1024x1024、960x1280；视频时长只显示 5/8/10/12/15 秒。多人互不影响依赖后端 owner_id、画布项目 owner 和飞书 / 备用登录会话隔离。旧 React 单对话框首页、信息流复刻链路仍保留在源码里作为回滚/高级能力，但不作为生产默认入口。

01

个人任务

GET /jobs 按当前登录用户过滤；旧无 owner 任务只对备用账号可见。

-
02

进入画布

用户直接在根域名个人画布里操作，上游项目列表、推荐词、节点菜单、工作流模板和批量下载能力保留。

+
02

进入画布

用户直接在根域名个人画布里操作；项目列表优先读取服务端 /canvas-projects，本地旧项目会首次导入。

03

组织节点

可通过底部 prompt、AI 润色、自动执行、手动添加节点或工作流模板创建文本、图片、视频、LLM、配置和参考图节点。

04

参考素材

首帧、尾帧、参考图和图片节点按上游节点语义保留；提交到后端时由 useApi.js 转成 first_image、last_image 或图片编辑参考。

05

工作流执行

自动执行会根据提示词创建文生图、图转视频、故事板、多角度分镜或绘本等节点组；手动模式下用户可自行连接节点。

06

生成图片 / 视频

generateImage 和 generateStoryboardVideo 继续走 SKG 后端 /api；视频提交后先写入 queued 占位，再由后端队列按并发上限启动。

-
07

结果沉淀

生成图、视频 URL、任务状态和下载入口回填到画布节点；完整任务结果仍可进入 /detail/?job= 查看。

+
07

结果沉淀

生成图、视频 URL、任务状态和下载入口回填到画布节点；画布结构保存到 Postgres，完整任务结果仍可进入 /detail/?job= 查看。

08

详情页

/detail/?job=<id> 展示参考图、全量生成图、视频候选、提示词和营销图文，并支持继续生成。

09

高级复刻

旧 AdRecreationBoard 与 /agent/ 作为高级入口保留，不再是默认路径。

@@ -606,7 +607,8 @@ web/next.config.mjsNext.js 构建配置：静态导出、图片不走优化、禁用开发环境左下角 Next Dev Indicator，并移除 Next 16 已不支持的 eslint 顶层配置，避免本地 dev 出现配置 Issue 提示。 web/app/globals.css全局主题变量、登录页视觉样式、信息流工作台玻璃拟态 token、ReactFlow 样式引用，以及本地开发态 nextjs-portal 遮挡隐藏规则。工作台在 skg-board-theme 内按 Figma 本地 MCP 参考改成黑灰玻璃系统：深灰背景、#383838 胶囊侧栏、rgba(255,255,255,.1) 玻璃面、backdrop-filter: blur(5px)、20px 圆角、10px 10px 10px rgba(0,0,0,.3) 阴影和绿黄状态色；新增 skg-board-shell、skg-board-rail、skg-glass-card、skg-glass-card--flat、skg-status-orb 等样式。侧栏改为跟随视口拉满工作台可用高度的悬停胶囊，桌面最小 600px，展开时在同一侧栏内承载素材输入抽屉。明暗主题已分开维护 shell、panel、glass、stat、action 和音频波形 token；暗色压低灰雾和面板底色，明亮模式改为暖白工作台，避免指标卡、按钮和波形继续残留黑底/白线；顶部指标卡增加紫、黄绿、琥珀、青绿、绿色光斑变量，接近原版多色玻璃卡效果。主/次按钮、指标卡和空状态继续走统一类，避免各板块散写不同玻璃效果。 web/app/page.tsx旧 React 单对话框生成台源码仍保留，便于以后回滚或抽能力；当前生产根域名已经由 web/canvas-app/ 画布产物覆盖，不再把这个 React 首页作为默认首屏。该页面里的模式也已收敛为文生图、文生视频、图生视频；图生视频只显示“上传图片”，不把“首帧/首尾帧”作为用户入口。旧 TK 复刻工作台组件仍保留在 web/components/ad-recreation-board.tsx，但不再作为默认首页渲染。 - web/canvas-app/SKG 内部画布应用：从 chatfire-AI/huobao-canvas 交互逻辑改造而来。当前策略是“保留成熟画布能力，替换品牌/路由/API”：Vue Flow 节点画布、项目列表、推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载都保留；可见品牌收敛为 SKG logo，不展示上游注册链接或外部品牌。生产路径固定为根域名 /，内部路由用 /p/:id?；来源说明保存在 THIRD_PARTY_NOTICES.md，不展示给终端用户。 + web/canvas-app/SKG 内部画布应用：从 chatfire-AI/huobao-canvas 交互逻辑改造而来。当前策略是“保留成熟画布能力，替换品牌/路由/API”：Vue Flow 节点画布、项目列表、推荐词、AI 润色、自动执行、工作流模板、首帧/尾帧/参考图节点、图片/视频/LLM 配置节点、模型配置和批量下载都保留；可见品牌收敛为 SKG logo，不展示上游注册链接或外部品牌。生产路径固定为根域名 /，内部路由用 /p/:id?；项目列表和画布 JSON 优先同步到服务端 Postgres，浏览器本地存储只是缓存/导入来源；来源说明保存在 THIRD_PARTY_NOTICES.md，不展示给终端用户。 + web/canvas-app/src/stores/projects.js画布项目 Pinia store：启动时先读本地 localStorage["ai-canvas-projects"] 作为缓存，再调用 GET /canvas-projects 拉服务端项目；如果发现本地旧项目，会调用 POST /canvas-projects/import 导入到当前登录用户。新建、重命名、画布节点变更、复制和删除会同步到 /canvas-projects，本地缓存只用于快速打开和网络异常兜底。 web/canvas-app/src/views/Canvas.vue画布主交互：恢复上游底部 prompt composer、AI 润色、自动执行、推荐词、节点菜单、工作流面板、API/模型设置入口和批量下载入口。自动执行会调用 useWorkflowOrchestrator 分析提示词，创建文生图、图转视频、故事板、多角度分镜或绘本节点组；手动模式只创建文本节点，用户自行连接节点。 web/canvas-app/src/config/models.js画布媒体模型和规格的前端白名单：图片只内置 auto、gpt-image-2、gemini-3-pro-image-preview，尺寸只内置 auto、1024x1536、1024x1024、1536x1024；视频只内置 seedance / Seedance 2.0 Fast，画幅和时长对齐后端 /health 能力边界。useModelConfig.js 和 Pinia 模型 store 会忽略浏览器本地自定义图片/视频模型，防止旧缓存把不可用模型带回生成下拉。 web/canvas-app/src/hooks/useApi.js画布到本项目后端的适配层：不再读取浏览器 API Key，而是使用当前登录会话 Cookie 调用 /api。文生图 / 图生图先创建轻量 creative job，再调用 /frames/0/generate；文生视频 / 图生视频调用 /storyboard/video 并轮询 /jobs/{id}，完成后把图片或 mp4 URL 写回画布节点。 @@ -640,7 +642,8 @@

后端核心

- + + @@ -664,6 +667,7 @@ -> 生图：generateImage(job.id, 0, { prompt, mode: text, model }) → jobs/<jobId>/gen -> 生视频：generateStoryboardVideo(job.id, 0, { prompt, model, first_image?, duration }) → jobs/<jobId>/storyboard_videos -> 当前结果：图片 / 视频节点自动排列到画布 + -> 画布项目：web/canvas-app/src/stores/projects.js → GET/POST/PUT/DELETE /canvas-projects → Postgres canvas_projects -> 任务详情页：web/app/detail/page.tsx?job=<id> → getJob → 展示参考图、生成图、视频、提示词、图文方案 → 可继续生成 / 删除 / 复制 旧版 TK 复刻链路（最后版本保留）： @@ -681,6 +685,7 @@ web/app/page.tsx 后端主链路： api/main.py -> Auth session / Feishu OAuth / Job owner / AgentRun owner / KeyFrame / KeyElement / StoryboardScene / AudioScript + -> api/db.py / Postgres: app_users / canvas_projects / job_index / generated_assets / prompt_library_index / asset_library_index / agent_run_index / audit_events -> 下载 / 上传 / 音频提取 / ASR / 翻译 / 声音背景音分析 / 抽帧 / Vision brief / GPT 图像生成 / 产品视角识别 / 分镜保存 / 首尾帧生成 / 后续 Azure OpenAI 配音预留 -> jobs/<jobId>/state.json + agent_runs/<runId>/state.json + 图片文件落盘；API 层按登录用户过滤列表和详情 @@ -774,6 +779,32 @@ api/main.py error, created_at, updated_at } + +
+

CanvasProject

+

根域名画布的项目持久化模型。前端仍保留本地缓存，但服务端 canvas_projects 是公司内部沉淀的主存储；默认可见性为 private，只有 owner 可改写，后续可扩展 team/company 可见项目。

+
CanvasProject {
+  id,
+  owner_id, owner_name, owner_email, owner_provider, tenant_key,
+  name,
+  thumbnail,
+  visibility: private | team | company,
+  canvas_data: { nodes, edges, viewport, ... },
+  version,
+  created_at, updated_at, deleted_at
+}
+
+
+

Postgres 索引表

+

Postgres 不替代大文件和完整 job state；它负责跨用户、跨浏览器和后续后台管理需要的结构化索引。任务详情、媒体文件和资源库原始 manifest 仍保留在现有目录里。

+
app_users
+canvas_projects
+job_index
+generated_assets
+prompt_library_index
+asset_library_index
+agent_run_index
+audit_events

KeyFrame

@@ -1048,10 +1079,11 @@ ProductRefStateItem {
- + - + + @@ -1118,9 +1150,9 @@ ProductRefStateItem { - - - + + + @@ -1156,7 +1188,7 @@ ProductRefStateItem {
  • GPT Image 生图；当前 IMAGE_MODEL 和主体 6 视图链路默认使用 gpt-image-2，单次图片网关请求默认 60 秒超时；主模型超时、429、5xx 或网络错误时允许 gemini-3-pro-image-preview 兜底，并有 2 次失败 / 600 秒短时熔断。
  • 三字段分镜候选生成：默认行左侧露文案、场景一句话、人物+产品+动作，右侧直接展示横向视频轨；中文镜像失焦后会自动优化英文主值；支持 AI 改写预览、单条选择数量生成、追加生成、选中候选和整片按行排队提交。
  • 全局资源中心：提示词库和素材库可从顶部“资源库”打开；提示词可复制并计数，素材应用到 job 时会复制成本 job 内普通 asset。
    • -
  • 画布：https://marketing.skg.com 登录后直接进入个人生成画布，支持文生图、文生视频、图生视频三种节点化生成；生成资产继续写入当前登录用户自己的后端 job。
    • +
  • 画布：https://marketing.skg.com 登录后直接进入个人生成画布，支持文生图、文生视频、图生视频三种节点化生成；画布项目服务端保存到 Postgres，生成资产继续写入当前登录用户自己的后端 job。
    • @@ -1209,6 +1241,20 @@ ProductRefStateItem {

    变更记录

    这个记录不是 git log 的替代品。它记录“产品理解发生了什么变化、影响了哪些源码、你以后描述需求时该怎么说”。后续每次改功能都要补一条。

    +
    +
    +

    2026-05-26 · 接入 Postgres 做公司内部沉淀

    + Backend + Deploy + Data +
    +
    +

    问题：画布项目只存在浏览器 localStorage 时，换电脑、清缓存或多人长期使用都难以形成公司内部资产沉淀；任务和资源虽然已有文件持久化，但缺少结构化索引和审计。

    +

    改动：新增 api/db.py 和 Postgres schema：app_users、canvas_projects、job_index、generated_assets、prompt_library_index、asset_library_index、agent_run_index、audit_events。api/main.py 启动时建表并索引已有 job / AgentRun / 提示词 / 素材；新增 /canvas-projects CRUD 和 import 接口；登录、创建任务、资源库操作、画布保存都会写用户索引或审计。web/canvas-app/src/stores/projects.js 改为服务端项目优先，localStorage 只做缓存和旧项目导入。

    +

    部署：docker-compose.prod.yml 和 docker-compose.standalone.yml 增加 postgres:16-alpine；生产环境在 deploy/.env.production 写入 DATABASE_URL 和 Postgres 密码，数据目录为服务器 ./data/postgres。deploy-prod-safe.sh 会在容器存在时导出 pg_dump，verify-prod-docker.sh 要求 database.connected=true。

    +

    影响：画布项目开始具备跨浏览器、跨设备恢复的服务端主存储；默认仍按 owner 私有隔离，后续可在同一表上扩展 team/company 可见性。完整 job state 和媒体文件仍保留在原有文件目录，避免把大文件一次性搬进数据库。

    +
    +

    2026-05-25 · 媒体模型选择对齐真实后端能力

    @@ -1325,7 +1371,7 @@ ProductRefStateItem {

    问题：默认首页适合“一次生成一个结果”，但内部多人使用时，用户还需要把多次生成的图片、视频、提示词和参考图放在一个自由空间里整理，避免结果都挤在同一条对话或详情页里。

    改动：新增 web/canvas-app/，将 huobao-canvas 的 Vue Flow 画布交互改造为 SKG 内部版：可见品牌、GitHub 入口、API Key 设置和外部服务商配置都已移除，保留项目列表、生成画布、节点连接、四模式 prompt composer 和生成结果节点。构建链路新增 pnpm build:canvas 和 web/scripts/sync-canvas-dist.mjs，生产 Nginx 新增受登录保护的 /canvas/ fallback 路由；首页顶部增加“生成画布”入口。

    -

    影响：画布项目目前保存在浏览器 localStorage，不是团队共享，也不做跨设备同步；生成图片和视频仍调用本项目 /api，按当前登录用户写入个人 job。第三方来源说明只保存在 THIRD_PARTY_NOTICES.md，不进入终端用户 UI。

    +

    影响：当时画布项目先保存在浏览器 localStorage，不是团队共享，也不做跨设备同步；2026-05-26 已升级为服务端 Postgres 持久化。生成图片和视频仍调用本项目 /api，按当前登录用户写入个人 job。第三方来源说明只保存在 THIRD_PARTY_NOTICES.md，不进入终端用户 UI。

    api/main.pyFastAPI 单文件后端：登录会话、状态模型、任务恢复、下载、抽帧、Vision、清洗、元素、分镜、原音频转写/翻译、声音与背景音分析、后续口播改写/TTS、文件返回；同时承载全局 prompt_library 和 asset_library 的磁盘索引、CRUD、删除保护和复制到 job API。轻量创作入口 POST /creative/jobs/image 把上传图片或空白底图写成一个只有 0 号关键帧的 Job，让首页直接复用生图/生视频接口；该接口兼容无 body / JSON 空对象 / 正常 multipart 上传，避免无首帧文生图或文生视频时空 multipart 被 FastAPI 在业务前置解析阶段拒绝；/health 返回 image_options、image_size_options、video_options、video_size_options、video_duration_options 和 video_max_duration_seconds；/frames/{idx}/generate 的 model 字段用于图片模型偏好，size 字段用于图片输出尺寸；/storyboard/video 继续使用 model 字段选择视频别名，并先校验画幅与时长能力边界，然后把 GeneratedVideo 写成 queued 占位并进入进程内视频队列。队列默认 VIDEO_QUEUE_MAX_CONCURRENT=2、VIDEO_QUEUE_MAX_CONCURRENT_PER_USER=1，同一用户连续提交不会占满全局并发；排队任务会回写 queue_position、queue_size、queue_message。旧 AgentRun 一键出片状态机、TK 复刻接口和 POST /creative/copy 继续保留。
    api/main.pyFastAPI 单文件后端：登录会话、状态模型、任务恢复、下载、抽帧、Vision、清洗、元素、分镜、原音频转写/翻译、声音与背景音分析、后续口播改写/TTS、文件返回；同时承载全局 prompt_library 和 asset_library 的磁盘索引、CRUD、删除保护和复制到 job API。启动时会初始化 Postgres schema、扫描现有 state.json / 资源库并写入索引；新增 /canvas-projects 系列接口把画布项目按当前登录用户持久化。轻量创作入口 POST /creative/jobs/image 把上传图片或空白底图写成一个只有 0 号关键帧的 Job，让首页直接复用生图/生视频接口；该接口兼容无 body / JSON 空对象 / 正常 multipart 上传，避免无首帧文生图或文生视频时空 multipart 被 FastAPI 在业务前置解析阶段拒绝；/health 返回 database、image_options、image_size_options、video_options、video_size_options、video_duration_options 和 video_max_duration_seconds；/frames/{idx}/generate 的 model 字段用于图片模型偏好，size 字段用于图片输出尺寸；/storyboard/video 继续使用 model 字段选择视频别名，并先校验画幅与时长能力边界，然后把 GeneratedVideo 写成 queued 占位并进入进程内视频队列。队列默认 VIDEO_QUEUE_MAX_CONCURRENT=2、VIDEO_QUEUE_MAX_CONCURRENT_PER_USER=1，同一用户连续提交不会占满全局并发；排队任务会回写 queue_position、queue_size、queue_message。旧 AgentRun 一键出片状态机、TK 复刻接口和 POST /creative/copy 继续保留。
    api/db.pyPostgres 适配层：在 DATABASE_URL 存在且 psycopg 可用时启用；负责建表、健康检查、用户 upsert、审计日志、画布项目 CRUD，以及把 Job、AgentRun、提示词库和素材库写入索引表。数据库不可用时本地开发会降级为 disabled，生产 verify-prod-docker.sh 会要求 database.connected=true。
    video_model_options()视频模型能力出口：如果 seedance、kling、veo3、veo 等业务别名实际都映射到同一个真实模型，会按真实模型去重，只给前端返回一个可用选项；当前生产真实模型为 doubao-seedance-2-0-fast-260128，前端显示为 Seedance 2.0 Fast。后续只有在服务器真的配置了不同可用视频模型时，才应把新的模型重新暴露给画布。
    api/product_library/skg-products内置 SKG 白底产品图库：manifest.json 记录从桌面产品图筛出的 gallery 白底图和桌面 4 张产品角度图，images/ 存 45 张参考图。
    api/character_library/skg-characters内置相似主体形象库：从桌面 5 套策划形象导入，manifest.json 记录运动阳光男、都市型男、优雅白领女、运动辣妹、绅士大叔，每套含 7 张透明骨架参考图和一段 prompt_brief。相似主体生成时优先使用文字 brief 作为创意方向，避免把内置图作为强参考图复制。
    网页登录 / 飞书免登录GET /auth/config、GET /auth/feishu/start、GET /auth/feishu/callback、POST /auth/login、GET /auth/check、GET /auth/me、POST /auth/logoutweb/app/login/page.tsx、Nginx auth_request登录页先读 /api/auth/config 判断是否显示飞书按钮；飞书客户端内且 feishu_enabled=true 时前端自动跳转授权入口，普通浏览器保留手动按钮和备用账号。飞书 OAuth 成功后后端用 open_id / union_id / email 生成多用户会话并设置 HttpOnly Cookie。账号密码登录保留为备用方式。生产 Nginx 对工作台和 /api/ 调 /auth/check 做统一校验，未登录页面跳 /login/?next=$request_uri，API 返回 JSON 401。
    运行配置 / 模型标注GET /healthgetRuntimeHealth、ModelTrace返回 models：ASR、asr_language（默认 auto，表示中文/英文/多语言自动识别）、asr_base_url、asr_remote_enabled、asr_local_fallback_enabled、asr_audio_fallback_enabled、faster_whisper、本机 ASR、ASR fallback、翻译、GPT 改写、GPT 画面理解、产品视角识别 product_view、主图像模型 gpt-image-2、图片故障兜底 image_fallbacks、图片尺寸 image_size_options、短时熔断状态 image_circuit、主体 6 视图模型链路、Azure OpenAI TTS、视频别名、视频画幅 video_size_options、真实可用视频时长 video_duration_options、单条最大秒数 video_max_duration_seconds 和 Seedance 服务商。当前 REWRITE_MODEL、AUDIO_REWRITE_MODEL 和 VISION_MODEL 默认使用 gpt-4o；如果旧环境变量仍写 gemini-*，后端会归一化回 GPT_TEXT_MODEL / REWRITE_MODEL。语音只走 Azure OpenAI TTS，models.voice_tts_paths 会回传当前尝试的语音路径，方便区分路径错误和语音服务不可用。前端所有当前主路径里会调用模型的按钮旁显示模型名，点击弹出小窗口查看模型链路和输入输出逻辑；不返回 API Key 或敏感凭证。
    运行配置 / 模型标注GET /healthgetRuntimeHealth、ModelTrace返回 database 健康状态和 models：ASR、asr_language（默认 auto，表示中文/英文/多语言自动识别）、asr_base_url、asr_remote_enabled、asr_local_fallback_enabled、asr_audio_fallback_enabled、faster_whisper、本机 ASR、ASR fallback、翻译、GPT 改写、GPT 画面理解、产品视角识别 product_view、主图像模型 gpt-image-2、图片故障兜底 image_fallbacks、图片尺寸 image_size_options、短时熔断状态 image_circuit、主体 6 视图模型链路、Azure OpenAI TTS、视频别名、视频画幅 video_size_options、真实可用视频时长 video_duration_options、单条最大秒数 video_max_duration_seconds 和 Seedance 服务商。当前 REWRITE_MODEL、AUDIO_REWRITE_MODEL 和 VISION_MODEL 默认使用 gpt-4o；如果旧环境变量仍写 gemini-*，后端会归一化回 GPT_TEXT_MODEL / REWRITE_MODEL。语音只走 Azure OpenAI TTS，models.voice_tts_paths 会回传当前尝试的语音路径，方便区分路径错误和语音服务不可用。前端所有当前主路径里会调用模型的按钮旁显示模型名，点击弹出小窗口查看模型链路和输入输出逻辑；不返回 API Key、数据库密码或敏感凭证。
    历史列表GET /jobslistJobs当前登录用户可见 job 精简列表（id/url/status/thumbnail/mtime/owner…），按 state.json mtime 倒序。前端 URL 无 ?job= 时拉它回填本人历史；带 limit 可截断。开启数据隔离时，飞书用户只看到自己的任务，历史无 owner 的旧任务只对备用账号可见。
    创建任务POST /jobscreateJob提交 TK 链接，后台开始下载；后端会把当前登录用户写入 Job.owner_*，后续详情、素材文件、删除和生成接口都通过统一中间件校验归属。下载阶段默认不带 cookies；生产环境必须显式保持 YTDLP_COOKIES_FILE= 和 YTDLP_COOKIES_FROM_BROWSER= 为空，避免容器内误读被打进镜像的开发 api/.env。
    画布生成POST /creative/jobs/image
    POST /jobs/{id}/frames/upload
    POST /jobs/{id}/frames/{idx}/generate
    POST /jobs/{id}/frames/{idx}/storyboard/video
    GET /jobs/{id}    		web/canvas-app/src/hooks/useApi.js根域名画布不单独保存后端画布表，画布项目当前在浏览器 localStorage；一旦生成图片或视频，就通过同一套 creative job / frame / storyboard video 接口写入当前登录用户自己的 job 目录。文生图会创建空白 creative job 后生成图片；图生视频会把上传图转成 frame 并作为视频参考图提交，提交视频后用 skg:{jobId}:{videoId} 作为画布侧任务 id 轮询 /jobs/{id}，直到视频状态完成或失败。
    画布项目GET /canvas-projects
    POST /canvas-projects
    PUT /canvas-projects/{id}
    GET /canvas-projects/{id}
    DELETE /canvas-projects/{id}
    POST /canvas-projects/import    		web/canvas-app/src/stores/projects.js根域名画布项目的服务端持久化接口。列表和详情按当前登录用户过滤；写入时保存画布 JSON、缩略图、可见性、版本和更新时间；删除为软删除。首次上线后本地 localStorage 旧项目会通过 import 导入到当前用户，之后服务端 Postgres 是主存储。
    画布生成POST /creative/jobs/image
    POST /jobs/{id}/frames/upload
    POST /jobs/{id}/frames/{idx}/generate
    POST /jobs/{id}/frames/{idx}/storyboard/video
    GET /jobs/{id}    		web/canvas-app/src/hooks/useApi.js画布项目结构保存在 /canvas-projects；一旦生成图片或视频，就通过同一套 creative job / frame / storyboard video 接口写入当前登录用户自己的 job 目录。文生图会创建空白 creative job 后生成图片；图生视频会把上传图转成 frame 并作为视频参考图提交，提交视频后用 skg:{jobId}:{videoId} 作为画布侧任务 id 轮询 /jobs/{id}，直到视频状态完成或失败。
    一键出片终端POST /agent-runs
    GET /agent-runs
    GET /agent-runs/{id}
    GET /agent-runs/{id}/final.mp4
    GET /agent-runs/{id}/contact.jpg    		web/app/agent/page.tsx快速出片页的唯一主接口。前端提交 TikTok 链接和最多 6 张产品图；后端创建同 owner 的 Job 与 AgentRun，后台执行下载、产品图归一化、透明骨架主体参考复制、12 段镜头计划、视频生成、失败镜头自动重跑一次、审片接触表和 ffmpeg 最终合成。列表、详情、最终 mp4 和接触表同样按 owner 隔离。
    重试下载POST /jobs/{id}/download/retryretryJobDownload用于 TK 链接下载失败且没有 video_url 的素材；清空错误、重新进入下载状态，并在后台再次执行 pipeline_download。上传视频不能重下载，需要重新上传文件。
    上传视频POST /jobs/uploaduploadJob保存 source.mp4，然后同样进入下载完成状态；当前上传后也加入第一步队列，下载完成后自动解析音频。
    内容生产画布承载个人自由排列的创作空间：用户在画布上通过提示词、推荐词、AI 润色、自动执行、工作流模板或手动节点连接生成文本、图片和视频节点，结果按节点位置沉淀。画布项目先保存在浏览器本地，生成资产进入后端个人 job。当前不做团队共享画布、管理员总览、多人协同编辑或跨浏览器同步；API 设置不能接回上游外部注册链接，生成调用必须继续走本项目后端 /api 和登录会话。web/canvas-app/、deploy/nginx.conf、web/scripts/sync-canvas-root.mjs承载个人自由排列的创作空间：用户在画布上通过提示词、推荐词、AI 润色、自动执行、工作流模板或手动节点连接生成文本、图片和视频节点，结果按节点位置沉淀。画布项目服务端保存到 Postgres，浏览器本地只缓存，生成资产进入后端个人 job。当前不做实时多人协同编辑或管理员总览；默认项目仍是个人私有，可见性字段先预留 team/company。API 设置不能接回上游外部注册链接，生成调用必须继续走本项目后端 /api 和登录会话。web/canvas-app/、web/canvas-app/src/stores/projects.js、api/main.py、api/db.py
    音频条