yingqing/交接-AI生成Agent化-2026-06-17.md

AirShelf · AI 生成 Agent 化 · 交接文档

日期: 2026-06-17(凌晨) 交接人: Claude(尹希乐 / seaislee 指导)→ 接手人: 张业昌 + 你的 Claude + 前端 UX 分支: dev(本批改动已推送) 一句话: 把脚本生成升级成「多模型可选 + 出稿/改稿一体的流式对话 agent(挂电商 skill)」,并把 商品→脚本→图片→故事板→视频 的 SOP 用可插拔 Provider 打通;参考图分镜(gpt-image-2 @图N)、模特库、Seedance 出音 全部就位。

---

0. TL;DR · 拿到就能跑

# 后端(端口 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 这几趴会卡)
.venv/Scripts/python.exe -m celery -A airshelf worker -l info -P solo

# 前端(端口 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→参考图合成 整链跑通
故事板 @图1@图2@图3 多锚点合成	✅ 代码完成	逻辑接好,建议接 worker 后端到端复跑一次
Seedance 视频出音(generate_audio)	✅ 已打开	默认 True;原来写死 False
多模型 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
火山人像素材库审核(绿/红标)	🟡 设计完成·未接线	见 §6,AirDrama 有现成代码可照搬,AK/SK 已备好
计费(按 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 万)。

现成代码在 AirDrama,直接照搬:

• C:\Airlabs_Project\Airflow Studio\AirDrama\video-shuoshan\backend\utils\assets_client.py — create_asset_group / create_asset / get_asset(volcengine SDK,AK/SK 签名,异步审核状态轮询 active/failed/processing)。
• 对应 AssetGroup(team, remote_group_id) + Asset(group, remote_asset_id, status, url, error_message) 模型 + asset_poll_status_view。

接线步骤(给你的 Claude):

1. requirements.txt 加 volcengine SDK 并安装(当前 AirShelf 没装)。
2. 照搬 assets_client.py 到 apps/assets/,改 import。
3. 加 AssetGroup / 给 Asset 加 remote_asset_id/audit_status/audit_error 字段 + 迁移。
4. 生成人物基础资产后静默自动上传到团队素材组,前端轮询 audit_status 渲染绿/红标。
5. env 已备好:ASSETS_API_ACCESS_KEY / ASSETS_API_SECRET_KEY / ASSETS_API_ENABLED / ASSETS_API_PROJECT_NAME。

---

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

• 流式生成中途客户端断开,可能留下「预扣未结算」额度(边缘情况;stream_script_agent 已尽量 try/except 释放,但 WSGI 断流的 finally 不保证)。
• 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。祝接手顺利。