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

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