seaislee1209andClaude Opus 4.8
03e7949307
UI:脚本助手模型框从『原生 select + inline style』换成复用设计系统的 chip 下拉(向上展开,新增共享 .align-up 变体),去 inline、合规范。并发:本地 worker 从 -P solo(单任务串行=一次只生成一张)改 -P threads -c 4;生产 k8s worker --concurrency 2→4。基础资产/故事板/视频出图可并行。loading 动画基础设施(卡内+全局 spinner)已验证存在。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
180 lines
13 KiB
Markdown
180 lines
13 KiB
Markdown
# AirShelf · AI 生成 Agent 化 · 交接文档
|
||
|
||
> **日期:** 2026-06-17(凌晨)
|
||
> **交接人:** Claude(尹希乐 / seaislee 指导)→ **接手人:** 张业昌 + 你的 Claude + 前端 UX
|
||
> **分支:** `dev`(本批改动已推送;gitea 凭证已入 git 库,后续 `git push` 自动用 seaislee 账号)
|
||
> **一句话:** 把脚本生成升级成「多模型可选 + 出稿/改稿一体的**流式对话 agent**(挂电商 skill)」,并把 商品→脚本→图片→故事板→视频 的 SOP 用**可插拔 Provider** 打通;参考图分镜(gpt-image-2 @图N)、角色对白(剧情向按需出)、聊天精准改一镜、模特库、Seedance 出音 全部就位。**全流程已端到端真跑通(含 Seedance 出片)。**
|
||
|
||
---
|
||
|
||
## 0. TL;DR · 拿到就能跑
|
||
|
||
```bash
|
||
# 后端(端口 8010)
|
||
cd core/backend
|
||
.venv/Scripts/python.exe manage.py migrate # 跑新迁移(0005/0006 + projects 0002)
|
||
.venv/Scripts/python.exe manage.py runserver 0.0.0.0:8010
|
||
# 另起 celery worker(图片/故事板/视频是异步,靠 worker 执行;没 worker 这几趴会卡)
|
||
# -P threads -c 4 = 线程池 4 并发(Windows 不能用 prefork;-P solo 是单任务串行=一次只生成一张,别再用 solo)
|
||
.venv/Scripts/python.exe -m celery -A airshelf worker -l info -P threads -c 4
|
||
|
||
# 前端(端口 5173,vite 代理 /api → 8010)
|
||
cd core/frontend
|
||
npm install && npm run dev
|
||
```
|
||
|
||
`.env` 里**凭证已就绪**(tokenssr / 飞书 / 火山审核借用 AK/SK / 豆包 TTS),开箱即用。**⚠️ 见 §7 有一处借用密钥要换。**
|
||
|
||
---
|
||
|
||
## 1. 成熟度总表(诚实标注)
|
||
|
||
| 模块 | 状态 | 验证方式 |
|
||
| ---- | ---- | ---- |
|
||
| 可插拔 Provider 层(tokenssr/任意中转站) | ✅ 已完成·已验证 | 真打 tokenssr 流式 chat 通过 |
|
||
| 结构化脚本 agent + 流式 SSE(出稿/改稿/3模式/多模型) | ✅ 已完成·**双验证** | 后端 HTTP 探针 + **无头浏览器视觉自检**(截图见 `_qa_shots/`) |
|
||
| gpt-image-2 参考图出图 + 落 TOS | ✅ 已完成·已验证 | 文生图→TOS→参考图合成 整链跑通 |
|
||
| 角色对白(剧情向)`dialogue` | ✅ 已完成·已验证 | 默认口播,聊天提要求才出多角色对白;`_probe` 验只动目标镜+出对白 |
|
||
| 聊天精准改一镜(`target_index`) | ✅ 已完成·已验证 | 读全脚本上下文、强制保其余镜;90s 改第5镜/越界保护均验过 |
|
||
| 故事板 @图1@图2@图3 多锚点合成 | ✅ 已完成·**端到端验证** | 真跑 4/4 帧,gpt-image-2 多图合成锁脸锁商品(截图 `_qa_shots/e2e_storyboard.png`) |
|
||
| Seedance 视频出音 + 故事板帧参考 | ✅ 已完成·**端到端验证** | 真出片 6.4 分钟,带音效+人声,mp4 落 TOS |
|
||
| 多模型 seed(豆包/GPT-5.5/Gemini + gpt-image-2 + Seedance) | ✅ 已完成 | 数据迁移 0006,`get_default_model` 选取正确 |
|
||
| 模特库生成器(9:16氛围图→16:9白底三视图) | ✅ 已完成·已验证 | 跑通 1 个,三视图角色一致性极好(截图 `_qa_shots/model_threeview.png`) |
|
||
| 前端脚本趴(流式工具卡+思考流+模型下拉+改稿) | ✅ 已完成·**浏览器视觉验证** | 见 `_qa_shots/01..03` |
|
||
| **火山人像素材库审核(绿/红标)** | ✅ 已完成·**端到端验证** | 真人资产送审→建组→轮询拿到绿盾(active);前端绿/红徽章 + 8s 轮询 |
|
||
| 计费(按 token 精确扣) | 🟡 沿用现有(每次调用扣 unit_price) | 真 token 计量是后续优化项 |
|
||
|
||
---
|
||
|
||
## 2. 架构原则(务必延续)
|
||
|
||
**Provider 可插拔 —— 除火山官方直连外,一切走「OpenAI 兼容中转站」,换站零改代码。**
|
||
|
||
- 火山(豆包文本 / SeeDream 生图 / Seedance 视频)= 官方直连,`VolcanoArkProvider`。
|
||
- 其余(tokenssr / yunqi / 任意 New-API 网关)= 通用 `OpenAICompatibleProvider(base_url, api_key)`。
|
||
- 分流在 `services.build_provider()`:`provider.name in OFFICIAL_DIRECT_PROVIDERS` 走火山,否则走通用适配器。
|
||
- **加/换中转站 = DB 加一行 `ModelProvider`(base_url + 可选 api_key)**,代码一行不改。
|
||
- 密钥解析顺序:`ModelProvider.api_key`(DB)→ `settings.PROVIDER_KEYS`(.env)。**密钥默认只在 .env,不进库**(seed 的 tokenssr provider 的 api_key 留空,运行时从 .env 取)。
|
||
|
||
**关键文件:**
|
||
- `core/backend/apps/ai/providers/openai_compatible.py` — 通用适配器(chat / 流式 chat / 生图 / **参考图 image_edit**)
|
||
- `core/backend/apps/ai/providers/volcano.py` — 基类(新增 `chat_completion_stream` 流式 + `generate_audio` 开关)
|
||
- `core/backend/apps/ai/services.py` — `build_provider / resolve_provider_credentials / get_{text,image,video}_provider`
|
||
|
||
---
|
||
|
||
## 3. 脚本 Agent(核心)
|
||
|
||
### 流式 SSE 端点
|
||
`POST /api/projects/{id}/script-agent-stream/` → `text/event-stream`,逐帧 `data: {json}`。
|
||
|
||
事件类型:
|
||
- `tool` `{id,label?,status:running|done|error}` — 工具卡(加载skill / 分析商品 / 生成分镜 / 提取实体 / 自检)
|
||
- `delta` `{text}` — 模型思考前言逐字(JSON 部分后端隐藏不外露)
|
||
- `draft` `{draft}` — 规范化后的 **ScriptDraft**(结构化)
|
||
- `saved` `{script_version_id, version}` — 已落库的 ScriptVersion(含 segments + metadata)
|
||
- `done` / `error`
|
||
|
||
> **DRF 坑(已解决):** SSE 必须给 action 挂 `ServerSentEventRenderer`(media_type=text/event-stream),否则 `Accept: text/event-stream` 直接 406。错误响应用纯 Django `JsonResponse` 绕开 DRF 渲染。见 `projects/views.py`。
|
||
|
||
### 3 种输入模式(前端已接)
|
||
- **auto(全自动)**:仅商品信息 → 自动定档/选 tone/造 entity/填黄金结构。
|
||
- **theme(一句话主题)**:用户给主题 → 以主题为主轴扩写。
|
||
- **revise(改稿)**:已有脚本 → 基于当前脚本增强(前端追问自动走此模式,带 `base_version_id`)。
|
||
|
||
### 多模型
|
||
请求带 `model_config_id`(前端脚本助手右上**模型下拉**:豆包 / GPT-5.5 / Gemini 3 Pro);缺省用默认文本模型。已实测豆包(官方直连)+ GPT-5.5(经 tokenssr)两条路都通。
|
||
|
||
### 结构化契约 ScriptDraft
|
||
脚本不再是「散文 + 正则」,而是结构化 JSON(`script_agent.normalize_draft` 后端兜底校验):三层 = 脚本头(hook/tone/aspect/duration)+ entities(角色/场景/商品,带 visual_prompt/ref_index,**全脚本共享保一致**)+ segments(role 钩子/痛点/卖点/CTA、narration≤55字、speaker、visual、product_exposure、**entity_refs**)。
|
||
|
||
- 落库:`ScriptVersion`(content=JSON,metadata=hook/tone/entities)+ `ScriptSegment`(新增字段 role/speaker/product_exposure/entity_refs)。
|
||
- **entities 回填 `project.metadata`**(cast/scenes/cast_prompts/scene_prompts + script_entities)→ 复用下游已有的基础资产 seed + 故事板 @图N。
|
||
|
||
### 电商 skill
|
||
`skills/ecommerce-video-script/`(SKILL.md + 5 references)。`script_agent.load_ecommerce_skill()` 运行时加载为系统提示词,**模型无关**。运行时输出协议放开了「先 1 句口语前言 + 再 JSON」以驱动流式体感。
|
||
|
||
**关键文件:** `core/backend/apps/ai/script_agent.py`、`apps/projects/views.py`(`script_agent_stream` action)、前端 `api.ts`(`agentScriptStream`)、`routes/pipeline.tsx`(`runScriptGeneration` 改 SSE 驱动)。
|
||
|
||
---
|
||
|
||
## 4. 图片 / 故事板 / 视频
|
||
|
||
- **图片(基础资产 / 模特 / 套图)**:默认图像模型 = `tokenssr:gpt-image-2`(支持参考图)。原 `yunqi:gpt-image-2`(只能纯文生图)已在迁移里停用。
|
||
- **故事板 @图N**:`services._storyboard_reference_images()` 按本镜 `entity_refs` 取角色/场景/商品的已采用基础资产,用 `provider.image_edit(images=[url1,url2,url3])` 多图合成本镜(锁脸锁商品)。provider 不支持 image_edit 时自动回退纯文生图。
|
||
- **视频(Seedance)**:`create_video_task(generate_audio=True)` 已打开,直接出画面+音效+人声(**不走 TTS**)。慢:单段约 5–10 分钟(凌晨可能 3–4 分钟),轮询端点 `poll-video-segment` 已是「秒回不阻塞」式。
|
||
|
||
---
|
||
|
||
## 5. 模特库
|
||
|
||
`python manage.py seed_demo_models --count 2 [--team <id>] [--brief "画像"]`
|
||
|
||
逻辑(`apps/ai/model_library.py`):先 gpt-image-2 出 9:16 氛围正面图,再以它为参考出 16:9 白底三视图(提示词「参考图1角色，生成角色三视图，从左往右依次为：胸像特写，全身正面，全身侧面，全身背面，白色背景」),两张都存为 person 类 Asset(`metadata.kind="model"`)。**已跑通,三视图角色一致性很好**(见 `_qa_shots/model_threeview.png`)。
|
||
|
||
---
|
||
|
||
## 6. ✅ 火山人像素材库审核(绿/红标)—— 已接入并验证
|
||
|
||
**目标(已实现):** 真人素材进火山素材库审核,前端只显示绿盾(active)/红标(failed,提示改提示词重生)。一团队一素材组(单组 500 万)。
|
||
|
||
**已落地:**
|
||
- `apps/assets/assets_client.py` — 照搬 AirDrama,volcengine SDK + AK/SK 签名(`create_asset_group / create_asset / get_asset`),凭证走 `settings.ASSETS_API`。
|
||
- `apps/assets/review.py` — 编排:`submit_asset_for_review`(建组若无→传素材→标 processing)/ `poll_asset_review`(查状态)/ `poll_team_reviews`。全 best-effort,未配/出错不影响主流程。
|
||
- 模型:`AssetReviewGroup(team OneToOne, remote_group_id)`(一团队一组)+ `Asset.review_status/review_remote_id/review_error`(迁移 `assets/0003`)。
|
||
- 集成:真人基础资产生成后 `transaction.on_commit` **静默送审**(`services.generate_base_asset` 里 `kind==person`)。
|
||
- 端点:`POST /api/projects/{id}/poll-reviews/` → `{reviews:{asset_id:status}}`;前端基础资产趴每 8s 轮询,人物卡渲染 **审核✓(绿)/ 审核✗·重生(红)/ 审核中**。
|
||
- **e2e 已验:送审→建组(group-...)→轮询 processing→active,真从火山拿到绿盾。**
|
||
|
||
🔴 **唯一待办:** `.env` 的 `ASSETS_API_ACCESS_KEY/SECRET_KEY` 是**借 AirDrama 已邀测账号**,AirShelf 自有火山账号开通人像素材库后**只换这两行**(独立于 `TOS_*`)。`ASSETS_API_ENABLED=false` 即可整体关停审核(不影响生图)。
|
||
|
||
---
|
||
|
||
## 7. 凭证与 .env(⚠️ 一处待换)
|
||
|
||
`.env` 已含可用凭证(已随 dev 推送,沿用本仓库既有「.env 入库」惯例):
|
||
- `TOKENSSR_API_KEY / TOKENSSR_BASE_URL` — 中转站主力(一把 key 通吃 ~90 模型)。
|
||
- `FEISHU_APP_ID / FEISHU_APP_SECRET` — 小毛球机器人(交接推送)。
|
||
- `VOLC_TTS_*` — 豆包语音合成(可选后期配音)。
|
||
|
||
**🔴 张业昌待办(唯一硬待办):** `ASSETS_API_ACCESS_KEY / ASSETS_API_SECRET_KEY` 现在**暂借 AirDrama 已邀测开通的火山 AK/SK** 跑通。AirShelf 自有火山账号开通「人像素材库」后,**只换这两行**(独立于 `TOS_*`,不要动 TOS)。
|
||
|
||
---
|
||
|
||
## 8. 给前端 UX 的 2 天打磨建议(视觉,非阻塞)
|
||
|
||
当前以「流程跑通 + 真 agent 体感」为先,视觉是够用级,可优化:
|
||
- 脚本助手的**工具卡**现在复用进度流气泡渲染(`ProgressStream` 的 steps),可做成独立「工具卡」样式(图标 + 标题 + 状态点),更像 lovart。
|
||
- 思考前言文字现在是 `opacity:0.85` 的普通段落,可加打字机光标 / 渐显。
|
||
- 分镜卡可加 **role 徽章**(钩子/痛点/卖点/CTA,数据已在 `segment.role`)和商品露出标签(`segment.product_exposure`)。
|
||
- 模型下拉复用了 `.setup-select`,可做成带模型图标的 Pill。
|
||
- **务必遵循** `电商AI平台/design.md`(冷灰底/单橙锚点/8px 圆角/inside-border),别新造色值或重写共享类。
|
||
|
||
---
|
||
|
||
## 9. 已知问题 / TODO
|
||
|
||
> 本批已跑**对抗式交叉验证**(4 个并行审查员:Provider/脚本agent/前端/迁移),发现并**已修复** 4 个 critical:
|
||
> 流式断连额度泄漏(GeneratorExit 逃逸 → try/finally 兜底释放)、默认图像模型没真正切到 gpt-image-2
|
||
> (只停了 yunqi 没停火山 Seedream → 改为停用所有非 tokenssr 图像)、故事板参考图提示词成死代码、
|
||
> 凭证解析两条路不一致 + JSON 抽取易抓示例块 + 前端兜底重复扣费。修复见 commit `fix(core): 对抗式…`。
|
||
|
||
- vite 代理转发 SSE 一般不缓冲;生产 nginx 需确认关掉 `proxy_buffering`(响应已带 `X-Accel-Buffering: no`)。
|
||
- 计费仍是「每次调用扣 `unit_price`」,非真 token 计量。
|
||
- 故事板 @图N、视频出音 建议接 worker 后端到端复跑一轮确认。
|
||
|
||
---
|
||
|
||
## 10. 本批改动文件清单
|
||
|
||
**后端新增:** `providers/openai_compatible.py`、`script_agent.py`、`model_library.py`、`management/commands/seed_demo_models.py`、迁移 `ai/0005`、`ai/0006`、`projects/0002`。
|
||
**后端修改:** `providers/volcano.py`(流式+音频)、`providers/__init__.py`、`ai/models.py`(ModelProvider.api_key)、`ai/services.py`(provider 分流+故事板参考图)、`projects/models.py`(ScriptSegment 字段)、`projects/serializers.py`、`projects/views.py`(SSE 端点+renderer)、`settings/base.py`(TOKENSSR/PROVIDER_KEYS)、`.env`。
|
||
**前端修改:** `api.ts`(agentScriptStream)、`routes/pipeline.tsx`(SSE 驱动+模型下拉+改稿)、`App.tsx`(textModels)、`types.ts`。
|
||
**资源:** `skills/ecommerce-video-script/`(运行时依赖,**必须随仓库**)。
|
||
|
||
设计 SSoT:`AI生成-Agent化落地方案.md`。API 参考:`tokenssr接口文档.md`、`image调用参考.md`。
|
||
|
||
---
|
||
|
||
_有疑问看 `_qa_shots/` 的截图(脚本流式三连 + 模特三视图),或直接复跑 §0。祝接手顺利。_
|