Files

T

seaislee1209andClaude Opus 4.8 b30eaed838 feat(core): 火山人像素材库审核(绿/红盾)接入 + 端到端验证

- assets_client.py:照搬 AirDrama,volcengine SDK + AK/SK 签名(凭证走 settings.ASSETS_API)。
- review.py:真人资产送审/轮询编排。一团队一组(AssetReviewGroup,OneToOne),全 best-effort 不破坏主流程。
- 模型:AssetReviewGroup + Asset.review_status/review_remote_id/review_error(迁移 assets/0003)。
- 集成:真人基础资产生成后 transaction.on_commit 静默送审(services.generate_base_asset kind==person)。
- 端点 poll-reviews + 序列化暴露 review_status;前端基础资产趴每8s轮询、人物卡渲染 审核✓(绿)/审核✗·重生(红)/审核中,审核终态后停轮询。
- e2e 已验:送审→建组→processing→active(真拿到火山绿盾)。

对抗式交叉验证(2审查员,0 critical)修复:
- get_or_create_team_group 并发竞态:DB 唯一约束去重 + select_for_update 串行化远程建组,杜绝重复建组/丢送审。
- create_asset 返回空 Id 不再标 processing(否则卡死黄);processing 超 15 分钟兜底判 failed,未知 Status 记日志,防永久 processing + 无限轮询。

凭证暂借 AirDrama,.env 改 ASSETS_API_* 两行即可换;ASSETS_API_ENABLED=false 可一键关停。回归 18/18 过。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-17 10:51:23 +08:00

8.0 KiB

Raw Blame History

Airshelf · 电商 AI 平台 · Claude Code 工程约定

本文件由 Claude Code 启动时自动加载。所有 AI 协作必须遵循以下规则。

项目简介

Airshelf · AI 短视频带货生成平台 · 5 阶段流水线(商品 → 故事板 → 镜头 → 生成 → 投放)

设计代号: Restraint · V2.1 · Firecrawl-aligned
主要工作目录: 电商AI平台/
Next.js 工程(独立): app/
V1 历史归档: v1/
V2.1 归档(原 v2.1/): v2/

★ 设计规范铁律(每次涉及页面 / CSS / UI 必读)

触发条件

只要任务涉及以下任一种,必须先 Read 电商AI平台/design.md:

修改 .html 文件
修改 assets/restraint.css 或任何 .css
修改 inline <style> 块
添加新页面 / 新组件
调整布局 / 间距 / 颜色 / 字号
用户提到"页面" "样式" "视觉" "组件" "色" "字" "圆角" "间距" 等关键词

必读章节

7 条铁律

任何页面 / CSS 调整前必须 Read 电商AI平台/design.md — 不读不动手
检查电商AI平台/assets/restraint.css 已有组件 — Grep ".btn|.pill|.input" 等
禁止在页面 inline <style> 重写共享类(.btn .pill .input .modal .drawer .toast .field .tabs .chip .stats .list-row 等)— 要变体回 restraint.css 加
禁止创建新色值 — 必须用 design.md §2.1 的 token,不写裸 hex
禁止改动基础 token(--heat --background-base --border-faint 等)— 改了破坏全站
完成后对照 design.md §8 Don't List 逐条自检
不确定就问用户,不要凭感觉发挥 — 用户原话:"我都希望你能遵循我们的设计规范,而不是乱做"

设计核心速记(详见 design.md)

冷灰底 #f9f9f9 · 主橙 #fa5d19 · 主前景 #262626
全场 8 px 圆角(Pill / dot 999 例外)· >12 px 直接判错
inside-border 而非真 border(hover 不抖动)
单橙锚点 · 全场只有一个 accent · hover 用 alpha 不用换 hue
Mono 装饰必有 · [ 200 OK ] // 05.14 [ /v2 ](品牌签名)
主 CTA 唯一允许阴影 · 4 层橙色发光 · 其他场景禁阴影
Inter(英/数字/装饰)+ Alibaba PuHuiTi(中) · 字符级 fallthrough
字重仅 3 档 · 400 / 500 / 600 · 700 仅给 Ctrl K 徽标

Git 工作流

当前开发分支: dev
主分支: main (生产)
严禁直推 master/main — 走 dev 分支 → PR → 合并触发 CI/CD
严禁 --no-verify 跳过 hook
Push 规则: 默认不 push,改完即停 · 用户明确说"push / 推一下"才执行
commit 前不要 amend — 创建新 commit,避免破坏历史

★ AI 生成 Agent 化架构(后端核心 · 改 AI 链路前必读)

2026-06-17 落地:脚本从「散文+正则」升级为结构化流式对话 agent,并把商品→脚本→图片→故事板→视频用可插拔 Provider 打通。全流程已端到端验证(含 Seedance 出片)。详见仓库 交接-AI生成Agent化-2026-06-17.md 与 AI生成-Agent化落地方案.md。

可插拔 Provider(换中转站零改代码)

火山官方直连(豆包/SeeDream/Seedance)→ VolcanoArkProvider;其余(tokenssr 等中转站)→ 通用 OpenAICompatibleProvider(base_url, api_key)。
分流在 services.py build_provider(),按 provider.name ∈ OFFICIAL_DIRECT_PROVIDERS(含 volcengine)。加/换中转站 = DB 加一行 ModelProvider。凭证解析:ModelProvider.api_key(DB)→ settings.PROVIDER_KEYS(.env),密钥默认只在 .env。
默认模型 get_default_model(capability) = 最早创建的 active 模型;图像默认 = tokenssr:gpt-image-2(迁移 0006 停用其余图像模型,别再激活火山 Seedream 否则会顶替默认)。

脚本 Agent(流式 SSE)

端点 POST /api/projects/{id}/script-agent-stream/ → text/event-stream,事件 tool/delta/draft/saved/done/error。DRF 必须挂 ServerSentEventRenderer 否则 406。
核心 script_agent.py:加载 skills/ecommerce-video-script/ 作系统提示词;3 模式(auto/theme/revise)+ 精准改一镜(target_index,后端 _merge_single_segment 强制保留其余镜);多模型(model_config_id)。
结构化 ScriptDraft 契约:narration(口播/旁白,扁平兼容下游)+ dialogue:[{speaker,line}](剧情对白,默认空,用户聊天提要求才补)+ role/speaker/product_exposure/entity_refs。落 ScriptVersion.metadata(hook/tone/entities)+ ScriptSegment 字段,并回填 project.metadata(cast/scenes/script_entities)给下游。
改稿用基准稿时长(effective_duration),别用请求默认 60 否则截掉 90s 稿尾镜。所有 target_index 判断用 is None 不用真值(0 是合法镜号)。

图像 / 故事板 / 视频 / 模特库

故事板 @图1@图2@图3:_storyboard_reference_images() 按 entity_refs 取角色/场景/商品基础资产,provider.image_edit(images=[...]) 多图合成(锁脸锁商品)。走 image_edit 分支必须用 build_storyboard_frame_prompt_refs(refs 版提示词,否则一致性约束失效)。
视频 Seedance:create_video_task(generate_audio=True) 直接出音(原写死 False)。慢:5-10 分钟/段。
模特库:python manage.py seed_demo_models --count N(model_library.py,9:16氛围图→16:9白底三视图)。

测试 / 凭证

跑测试用 DB_ENGINE=sqlite(远程库无建库权限);测试 setUp 会停用 seed 的中转站文本模型保证命中可 mock 的 VolcanoArkProvider。
.env 已含 tokenssr/飞书/火山审核(借 AirDrama AK/SK,待张业昌换)/豆包TTS。
火山人像素材库审核(绿/红盾)已接入并验证:真人(person)基础资产生成后 transaction.on_commit 静默送审(assets/review.py + assets_client.py,一团队一组 AssetReviewGroup);Asset.review_status(processing/active绿/failed红);端点 poll-reviews 前端基础资产趴每 8s 轮询刷新徽章。e2e 已拿到真绿盾。

文件操作

三视图 = 单张 16:9 图 · 不要拆成 3 张缩略 · 用 aspect-ratio: 16/9 单容器
设计稿优先 · 写代码前必须先读电商AI平台/_design_src/ 设计稿(如果有)
.pen 文件加密 · 只能用 pencil MCP 工具,不能 Read/Grep

用户偏好

角色: UI 设计师 · 不读代码报错,只看最终视觉结果
不需要的: 终端报错截图、深奥的代码解释、过度的实施细节
需要的: 简短状态更新、视觉结果对照、清晰的"对/错"反馈

关键路径速查

资产	路径
设计规范(SSoT)	电商AI平台/design.md
共享 CSS	电商AI平台/assets/restraint.css
Shell 注入	电商AI平台/assets/shell.js
视觉样板间(归档)	电商AI平台/_archive/design-system.html
规范理论(归档)	电商AI平台/_archive/DESIGN_SPEC_V2.md
设计稿源	电商AI平台/_design_src/

违反任何规范规则,用户有权要求重做,无需解释。

8.0 KiB Raw Blame History

Airshelf · 电商 AI 平台 · Claude Code 工程约定

项目简介

★ 设计规范铁律(每次涉及页面 / CSS / UI 必读)

触发条件

必读章节

7 条铁律

设计核心速记(详见 design.md)

Git 工作流

★ AI 生成 Agent 化架构(后端核心 · 改 AI 链路前必读)

可插拔 Provider(换中转站零改代码)

脚本 Agent(流式 SSE)

图像 / 故事板 / 视频 / 模特库

测试 / 凭证

文件操作

用户偏好

关键路径速查

8.0 KiB

Raw Blame History