azmat1127/yingqing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3d38c173e6d4ddc7d750aefa90116da2c8044664
yingqing/CLAUDE.md
T
seaislee1209andClaude Opus 4.8 3d38c173e6 feat(core): 角色对白(剧情向按需)+ 聊天精准改一镜 + 模型下拉移位 + 全流程e2e + 交叉验证修复 
新能力(均已端到端验证):
- 角色对白 dialogue:[{speaker,line}](speaker=null 即旁白)。默认口播,用户在聊天提要求才出多角色对白(剧情向);narration 保留扁平拼接兼容下游字幕/配音。skill 同步:默认不强制对白。
- 聊天精准改一镜:聊天说「第N镜改XX」→ agent 读全脚本上下文、只重写那一镜(target_index + 后端 _merge_single_segment 强制保其余镜原样),保衔接。
- 前端:分镜卡渲染对白/镜型/露出;模型下拉从顶部移到输入框下方小按钮(对齐 ChatGPT/Lovart)。

全流程 e2e 真跑通:商品→脚本→基础资产(gpt-image-2)→故事板(@图N 多图合成锁脸锁商品)→视频(Seedance 6.4分钟出片,带音效+人声)。

对抗式交叉验证(3 审查员)修复:
- 改稿用基准稿时长 effective_duration(prompt head + normalize + merge),避免请求默认 60 把 90s/6镜稿尾镜截掉/单镜改空转。
- target_index 越界服务端早返回报错、不计费;模型未产出目标镜时抛错释放额度(不静默空转)。
- 前端「第N镜」正则收窄为 镜|场(去掉会误判「第3个卖点」的 个|段)。
- 回归:测试 setUp 停用 seed 中转站文本模型,保证命中可 mock 的 provider(18/18 过)。

CLAUDE.md 加「AI 生成 Agent 化架构」一节供后续维护。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 05:09:51 +08:00

7.7 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 条铁律

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

设计核心速记(详见 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。🔴 火山人像素材库审核(绿/红盾)= 设计完成未接线,交接文档 §6 有照搬 AirDrama 步骤。

文件操作

  • 三视图 = 单张 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/

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

Reference in New Issue View Git Blame Copy Permalink