营销智能体（Marketing Agent）

功能概述

营销智能体是系统两大创作模式之一（另一为短剧模式），面向营销内容创作场景。它提供对话式交互能力，集成 LLM 对话、图片生成、视频生成三大核心功能，帮助用户创作带货脚本、广告创意、产品文案等营销内容。

双模式系统

用户首次进入系统时通过模式选择弹窗选择创作模式，选择结果保存在 localStorage 的 creation_mode 字段中（short_drama 或 marketing）。两种模式共享后端基础设施，但前端入口和交互风格不同：

模式切换入口位于 web/index.html 的模式选择弹窗，selectCreationMode(mode) 方法仅保存模式状态，不自动跳转。

页面架构

技术栈

• 框架：Vue 3（CDN 引入 vue.global.prod.js，使用 Composition API）
• HTTP 客户端：axios（axios.min.js）
• Markdown 渲染：marked.js（marked.min.js）
• 代码高亮：highlight.js（github.min.css 主题）
• 任务配置：task_config.js（统一任务类型/模型/算力配置模块）
• 视频压缩：video_compressor.js（Canvas + MediaRecorder 方案，480p 压缩）
• 国际化：i18n-core.js + i18n-vue-plugin.js + i18n-dom.js

三栏布局

页面为 Vue 3 单页应用（SPA），采用三栏布局，整体高度 100vh：

+--------+------------------+--------------------------------+
| 左侧   | 左侧边栏          | 主内容区                        |
| 窄导航  |                  |                                |
| (64px) | (260px)          | (flex: 1)                      |
+--------+------------------+--------------------------------+

响应式：768px 以下侧边栏变为固定定位的抽屉，通过 .sidebar.open 类控制显示。

组件结构

页面内所有 UI 均在单个 Vue 3 createApp() 实例中实现，无外部组件拆分。主要 UI 区块：

1. 顶部栏 (.top-bar)：当前日期、搜索框、算力余额显示
2. 消息流 (.chat-messages)：欢迎卡片、用户/AI 消息气泡、打字指示器、继续按钮
3. 底部输入区 (.input-area)：文件上传按钮、文本输入框、媒体缩略图条、类型选择、模型选择、比例/分辨率选择、发送按钮
4. 弹窗层：联系反馈弹窗、算力日志弹窗（iframe）、算力充值弹窗、图片放大模态框
5. 资产库视图 (.asset-library)：通过左侧导航切换 activeView 为 assets 显示，展示用户历史生成结果（图片/视频），每页 60 条，支持分页。图片资产支持"生成视频"操作（useAssetForVideo），会将图片带入生成页输入区并自动切换到视频模式。图片放大弹窗中的"生成视频"按钮（imageToVideo）同样会自动切换回生成视图。

核心功能详解

三种创作类型

底部输入栏的类型选择器提供三种创作模式：

Agent 模式为默认推荐模式，走 LLM 对话流程，后端 PM Agent 可自主调用图片/视频生成工具。图片/视频模式为直接生成模式，前端直接调用生成 API 并轮询状态。

会话管理

创建会话

• 调用 POST /api/session/create，传入 user_id、world_id、auth_token、session_type: 2（营销模式标识）
• 营销智能体使用固定 world_id = '1'，无需多世界概念
• 创建成功后将新会话加入本地 sessions 列表头部并持久化到 localStorage（marketing_sessions 键）

搜索

侧边栏搜索框通过 v-model 绑定 searchQuery，filteredSessions 计算属性对会话标题进行大小写不敏感的模糊过滤。

重命名

• 悬浮会话项显示 ··· 按钮，点击弹出上下文菜单
• 选择"重命名"后，会话标题变为内联输入框（.history-rename-input）
• 支持 Enter 确认、Escape 取消、失焦自动确认
• 调用 PUT /api/session/{session_id}/title 保存到后端

删除

• 调用 DELETE /api/session/{session_id} 进行软删除
• 至少保留一个会话，删除最后一个时提示 keep_one_session
• 删除当前活跃会话后自动切换到列表中的第一个会话

加载会话列表

页面初始化时调用 GET /api/sessions?user_id=xxx&world_id=1&session_type=2&limit=50 从后端加载，失败时回退到 localStorage 缓存。

消息交互

消息类型

多模态消息

• 用户上传的图片在消息气泡中以 <img> 标签渲染，最大高度 160px，点击可放大
• 视频以 <video> 标签渲染，支持 controls
• 音频以 <audio> 标签渲染
• 历史消息中的多模态内容（JSON 数组格式的 image_url + text）在 parseHistoryMessage 中解析为文本+图片分别渲染

Markdown 渲染

renderMarkdown(text) 函数的处理流程：

1. 保护已有的 Markdown 图片语法 !alt 和链接语法 text（占位符替换）
2. 将裸图片 URL（以 .png/.jpg/.gif/.webp 等结尾）自动转换为 Markdown 图片格式
3. 处理 URL 后紧跟中文等非空白字符的边界问题
4. 恢复占位符
5. 调用 marked.parse() 解析为 HTML
6. 为所有 <img> 标签添加点击放大事件和样式

Verification 交互（ask_user）

当后端 Agent 通过 ask_user 工具向用户提问时，SSE 流会推送 human_verification_required 事件：

1. 前端解析 verification 对象，提取 title、description、options
2. 渲染为特殊消息气泡，包含预设选项按钮和"其他"自由输入按钮
3. 用户选择后调用 POST /api/verification/{verification_id} 提交回答
4. 验证期间（pendingVerificationId 不为 null）禁止正常发送消息

切换会话或刷新页面后，前端会从会话历史中查找最后一个未被验证回答覆盖、且对应验证记录状态仍为 pending 的验证请求，并恢复 pendingVerificationId。只有 verificationId 等于当前 pendingVerificationId 的问题卡片可点击，历史中的旧问题保持禁用，避免误把旧选项提交到当前等待项。主输入框在等待用户回答时仍可提交自定义答案，但不会发送新的普通对话消息。

如果用户切换会话期间 ask_user 已超时，后端会在历史接口中为该验证项返回 verification_status='cancelled'。前端加载到非 pending 状态时不会恢复等待状态，因此输入框和发送按钮会恢复为普通对话模式；超时后的历史问题仍可展示，但不再阻塞用户继续输入。

SSE 流式响应

连接建立

Agent 模式下发送消息的完整流程：

1. POST /api/session/{session_id}/task 创建任务，获取 task_id
2. EventSource 连接到 /api/task/{task_id}/stream
3. 超时设置为 900 秒（15 分钟）

事件类型

去重与续传

• /api/task/{task_id}/stream 会为数据库中的任务消息输出 SSE id，取值为相关数据表的主键。
• 浏览器原生重连时，后端会读取 Last-Event-ID；手动恢复连接时也可通过 last_id 查询参数指定已处理的最后一条消息。
• 前端维护已处理的 SSE 消息 id 集合，重复 id 会被跳过，避免重连重放时把同一条完整 message 再次拼接到 AI 气泡中。
• 当页面或会话切换后恢复活跃 Agent 任务时，前端还会对比当前历史中已展示的 assistant 内容；如果恢复流重放了同样的完整 message，会跳过该消息，避免"历史气泡 + 恢复流气泡"重复显示。
• Agent SSE 文本回复的持久化以任务完成回调中的 session_storage.save_session() 为准；前端收到 done 后不再调用 /session/{session_id}/message 追加同一段 assistant 文本，避免"后端保存 + 前端追加"产生相邻重复历史。
• Agent 模式下用户消息的持久化以后端增强版为准：前端发送时只在当前页面即时展示用户气泡，不再调用 /session/{session_id}/message 保存展示版；任务完成后 PM Agent 保存包含媒体 URL 标签和用户偏好的增强版 user 消息。历史加载时前端会把 [用户图片偏好]、[用户视频偏好] 折叠为"查看发送偏好"，避免同一用户输入以 UI 展示版和 LLM 增强版各保存一次。
• /session/{session_id}/message 也会跳过与最后一条历史记录 role 和 content 都相同的消息，作为其他追加路径的兜底保护。
• call_agent 成功返回的专家结果会在 _handle_agent_call() 阶段作为 SSE message 推送给前端，确保"图片内容分析"等专家输出立即可见；结果仍会进入 PM 上下文和会话历史，若 PM 后续 assistant 回复复述同一段内容，前端会通过内容去重跳过重复气泡。
• handleStream 在建立连接时捕获发起会话 streamSessionId，并在 onmessage 顶部校验：若用户已切换到其他会话，残留的 SSE 事件（message / image_task_submitted / video_task_submitted / verification_timeout 等）会被丢弃并关闭旧连接，避免把上一会话的 AI 回复、任务结果或验证提示串到当前对话。切回原会话时由会话恢复机制重新建立 SSE。

任务状态轮询

Agent 提交图片/视频生成任务后，前端通过 setInterval 轮询 GET /api/get-status/{project_ids}：

• 图片轮询间隔：5 秒（启动后立即查询一次，不必等待第一个周期）
• 视频轮询间隔：10 秒（启动后立即查询一次）
• 任务完成后将结果（图片/视频 URL）渲染到消息气泡中
• 使用 sessionTaskRegistry 注册表跟踪所有活跃任务，支持会话切换后恢复
• 直接图片/视频生成使用 directGenerationTasks 为每次提交创建独立任务实例，实例内绑定 type、project_ids、msgUid、sessionId 和 intervalId。轮询只读取实例内的 projectIds，避免多轮对话中后提交的图片任务覆盖先提交的视频任务。
• 直接生成任务完成后优先调用 replacePendingTask(sessionId, task_type, project_ids, content) 精确替换原 __PENDING_TASK__ 历史行；只有匹配失败时才 fallback 追加 assistant 消息，且追加到任务所属的原 session。
• 生成结果统一通过媒体类型过滤后渲染：图片结果会排除 .mp4/.webm/.mov/.avi/.mkv，视频结果会排除图片扩展名，避免视频 URL 被 <img class="generated-image"> 包裹。
• GET /api/get-status/{project_ids} 对 CDN 结果采用 CDN 优先策略；如果生成任务已完成但 CDN 仍处于 pending，会先返回本地 result_url 作为 file_url，并附带 cdn_status: "pending"，避免聊天框一直显示生成中
• 前端轮询统一识别 SUCCESS/COMPLETED/DONE 等完成状态，并从 task 本身和 results[] 中提取 file_url、result_url、video_url、image_url、output_url、download_url 等字段
• 如果 video_task_submitted SSE 事件缺失，但专家工作总结中包含 project_ids: [...] 且文本语义为视频任务，前端会自动补启动视频轮询；加载历史会话时也会执行同样的兜底恢复
• 如果 image_task_submitted SSE 事件缺失，但专家回复中包含 project_ids: [...] 或"项目ID: 744"这类图片任务标识，前端会自动补启动图片轮询；图片轮询会绑定触发时的会话，避免切换会话后把结果写入当前对话
• 文本兜底恢复会优先识别视频摘要，包含"视频参数""图生视频""文生视频""时长""first_last_frame""multi_reference"等视频信号的工作总结不会再触发图片轮询，避免"图片模式 first_last_frame"被误判为图片生成任务
• Agent 图片/视频轮询启动后均立即查询一次状态，已完成的任务可直接渲染结果，不必等待第一个轮询周期
• 视频兜底恢复按会话绑定轮询结果，异步返回时如果用户已切换到其他会话，不会把结果写入当前对话；历史加载时会过滤空 AI 气泡和重复的视频结果，避免切换会话后重复显示
• 直接发起模式（checkDirectGenerationStatus）的轮询在每次 await 获取状态返回后，会再次校验 currentSessionId 是否仍等于任务实例的 task.sessionId：任务进行中切换会话时，旧轮询回调立即停止并清理，不再向当前（已切换的）messages 或全局 imageResults/videoResults 写入，杜绝"视频生成失败/图片生成失败"提示串到其他对话
• handleImageTaskSubmitted / handleVideoTaskSubmitted 支持显式 explicitSessionId 入参；由 SSE 流派发任务时传入该流的 streamSessionId，使轮询与结果持久化归属发起会话，而非事件被处理时的"当前会话"

任务恢复机制

页面刷新或切换会话时，系统通过以下机制恢复未完成的任务：

1. __PENDING_TASK__ 标记：后端在相关数据表中保存 __PENDING_TASK__:{type}:{project_ids} 标记（message_type='pending_task'）
2. recoverPendingTasks()：加载历史消息后检测标记，轮询任务状态；完成时优先替换 pending 消息（通过 PUT /session/{id}/message/{message_id}），替换失败则 fallback 追加新消息
3. sessionActiveTaskId 注册表：记录每个 session 的活跃 Agent task_id，切换回来时检查任务状态并重连 SSE
4. directGenerationTasks / Agent 轮询注册表：直接生成任务在内存中按任务实例跟踪 project_ids；Agent 图片/视频轮询按 sessionId:type:project_ids 去重，支持会话内恢复和并发任务隔离
5. 并发安全：clean-pending-tasks 支持按 task_type + project_ids 精确清理，并发任务互不影响。轮询和 recoverPendingTasks(sessionId) 的 fallback 追加也必须显式传入原始 sessionId，避免用户切换会话后把上一会话的图片/视频结果写入当前会话。

模型选择

图片模型

通过 TaskConfig.getModelOptionsForCategory('text_to_image') 动态加载，默认优先选择默认生图模型。用户选择保存到 localStorage（marketing_selected_image_model 键），并通过 POST /api/text-to-image-model 同步到后端相关数据表。

视频模型

• 文生视频：TaskConfig.getModelOptionsForCategory('text_to_video')
• 图生视频：TaskConfig.getModelOptionsForCategory('image_to_video')，根据 videoImageMode 过滤支持的模型
• 模型偏好从后端 GET /api/video-model 获取，回退到 localStorage

模型选择状态

页面 UI 仍保持一个可见的模型选择器，但内部状态已拆分为图片模型和视频模型两套。selectedImageModel / selectedImageModelKey 保存生图选择，selectedVideoModelName / selectedVideoModelKey 保存生视频选择，selectedModel / selectedModelKey 仅作为当前模式的可写计算属性供模板和发送逻辑读取。用户在 Agent 模式下切换"生图 / 生视频"时，不会再用视频模型覆盖图片模型；image_preferences.model_name 始终取图片模型，video_preferences.model_name 始终取视频模型。

LLM 模型（Agent 模式）

调用 GET /api/models 加载所有可用 LLM 模型，支持 VL（视觉理解）和 Thinking（深度思考）标签。同名模型可能来自不同供应商，前端使用 model_id + vendor_id 作为唯一选择键，避免同名模型同时高亮。默认大语言模型优先路由到默认第三方大语言模型服务，该服务未配置时回退到 API 聚合服务或其他供应商。用户选择保存到 localStorage（marketing_selected_llm_model_id + marketing_selected_llm_vendor_id 键），发送消息时通过 model、model_id、vendor_id 字段传给后端。

图像比例选择

比例选项通过 TaskConfig.getRatioOptions(modelKey) 动态获取，支持的比例如下（定义在 aspectRatioMap 中）：

用户选择保存到 localStorage（marketing_selected_ratio 键），并通过 POST /api/text-to-image-model 同步到后端。全新用户没有保存偏好时，前端按当前生图模型的 default_ratio 初始化；默认生图模型使用 9:16 竖屏比例。

分辨率选择

图片模式下显示分辨率选项，通过 TaskConfig.getSizeOptions(modelKey) 动态获取。选项前自动添加 auto（自动根据模型选择最佳分辨率）。分辨率映射：1K -> 1K，2K -> 高清 2K，4K -> 超清 4K。

视频时长和生成方式

视频时长

通过 TaskConfig 的 supported_durations 动态获取，默认选项 ['auto', 3, 5, 8, 10, 15]。

生成方式（videoImageMode）

视频模式下有图片时可选择：

文件上传

Agent 对话模式

支持同时上传多种媒体文件：

Agent 视频模式

支持上传参考图（首尾帧/全能参考）、参考视频和参考音频。图片上传到 /api/upload-agent-image，通过 image_urls 字段传给后端。
Agent 视频模式下，主图和后续参考图都会等待上传完成并转换为 HTTP URL；发送给后端时按输入区显示顺序去重收集到 image_urls，避免 blob 预览地址或未上传完成的参考图遗漏。
当前页面即时渲染的用户气泡统一通过 collectCurrentMessageMedia() 收集媒体，再由 buildUserMessageContent() 渲染；图片、视频、音频模式和 Agent 模式不再分别拼接预览 HTML。Agent 发送给后端的 image_urls、video_urls、audio_urls 也复用同一媒体集合，确保即时显示、请求 payload 和后端保存的增强版用户消息尽量一致。
纯视频参考文件上传到 /api/upload-agent-video，只进入 video_urls 流程，不会设置图片上传状态，也不会触发图片 HTTP URL 等待。

会话历史从后端相关数据表恢复时依赖媒体标签重新渲染图片、视频和音频。/api/session/{session_id}/task 写入用户消息时必须把上传接口返回的 URL 拼入 [图片N]（URL: ... thumb: ...）、[视频N]（URL: ...）、[音频N]（URL: ...） 标签后再落库；上传接口已经根据 server.is_local 决定返回本地 URL 还是 CDN URL，历史持久化层只保存返回值，不重新判断或改写 CDN。

生成状态轮询和 Agent SSE 流使用连续失败保护。图片/视频状态轮询、Agent 图片/视频轮询，以及 SSE 连接错误/超时在同一任务上连续失败 3 次后，会停止对应定时器或断开流，并清理活跃任务归属，避免对话区持续追加"请求超时，请稍后重试"之类的错误气泡。

图片/视频模式

图片直接通过 FormData 上传到 /api/text-to-image 或 /api/image-edit。视频上传到 /api/ai-app-run-image（图生视频）或 /api/ai-app-run（文生视频）。

视频压缩

使用 VIDEO_COMPRESSOR 模块（Canvas + MediaRecorder 方案）：

• 目标短边：480px
• 帧率：30fps
• 视频码率：1.5Mbps
• 压缩阈值：文件 > 10MB 或短边 > 480px
• 支持 WebM (VP9/VP8) 和 MP4 格式
• 超过最大时长的视频自动截断

@ 引用系统

输入框支持 @ 触发媒体引用下拉框，列出已上传的媒体文件。选中后插入引用标签到文本中，支持模糊搜索过滤。mentionDropdown 状态管理下拉框的显示、查询和选中索引。

算力显示

余额显示

顶部栏右侧显示算力余额，每 30-45 秒随机间隔自动刷新（startComputingPowerRefresh）。余额根据数值自动变色：

点击余额打开算力日志弹窗（iframe 加载 /computing_power_logs.html）。

消耗预估

输入区右侧根据当前选中模型和参数实时计算本次操作的算力消耗，使用 TaskConfig.getComputingPower() 方法。

算力充值

算力日志弹窗中点击"算力充值"按钮打开充值弹窗：

1. 调用 GET /api/recharge/packages 加载套餐列表
2. 用户选择套餐后调用 POST /api/recharge/wechat-pay 创建支付订单
3. 通过第三方 QR 码服务生成微信支付二维码
4. 支持自动检测到账

i18n 国际化

使用自研 i18n 框架（i18n-core.js），支持：

• Vue 模板中的 $t('key') 翻译
• JS 代码中的 window.t('key') 翻译
• 带参数的翻译：$t('duration_seconds', { dur: 5 }) -> 5秒
• DOM 属性的 data-i18n 自动翻译
• 语言切换器组件（i18n-switcher.js）

翻译文件位于 web/i18n/locales/zh-CN/marketing_agent.json，共约 220 个翻译键，覆盖页面标题、导航、侧边栏、输入区、模型选择、错误提示等所有用户可见文本。

API 接口列表

会话管理

智能体任务

任务创建请求体

{
  "message": "用户输入文本",
  "auth_token": "认证令牌",
  "image_urls": ["http://..."],
  "video_urls": ["http://..."],
  "audio_urls": ["http://..."],
  "model": "LLM模型名称",
  "model_id": 1,
  "vendor_id": 1,
  "image_preferences": {
    "ratio": "9:16",
    "model_name": "第三方图像生成模型",
    "resolution": "2K"
  },
  "video_preferences": {
    "ratio": "16:9",
    "duration": 5,
    "image_mode": "first_last_frame",
    "model_name": "第三方视频生成模型"
  }
}

Agent 模式下，image_preferences.ratio、image_preferences.resolution 会在创建任务时同步写入后端图片偏好，后续专家调用 generate_text_to_image / edit_image 工具时会由工具层强制应用当前偏好。ratio: "auto" 也会被保存，表示本次任务不强制覆盖专家或模型默认比例。

媒体上传

生成任务

模型和配置

用户和算力

认证与登录跳转

登录状态检查

页面初始化时检查 localStorage 中的 user_id 和 auth_token，如果缺失则自动跳转到登录页面。

401 自动跳转

所有带 Authorization 头的 API 请求均通过 checkAuthResponse() 函数统一检查 HTTP 状态码。当后端返回 401（未授权/token 过期）时，自动跳转到登录页面并携带当前页面路径，登录成功后可跳回原页面。

跳转目标格式：/index.html?redirect_url={当前页面路径}

index.html 已内置 redirect_url 参数支持：

1. 解析 redirect_url 参数并保存到 localStorage 的 redirect_after_login
2. 未登录时自动弹出登录窗口
3. 登录成功后检查 redirect_after_login，存在则跳转到指定路径

世界观

前端依赖库

配置项

localStorage 键

服务端配置（/api/system/server-config）

前端常量

样式与主题

主题色变量（CSS 自定义属性）

定义于 web/css/marketing_agent.css 的 :root 中：

--bg-primary: #f5f5f5;         /* 主背景 */
--bg-secondary: #ffffff;       /* 卡片/输入框背景 */
--bg-sidebar: #fafafa;         /* 侧边栏背景 */
--accent-color: #00a8e6;       /* 主题色（亮蓝） */
--accent-hover: #0095cc;       /* 主题色悬停 */
--accent-light: #e6f7ff;       /* 主题色浅底 */
--user-bubble: #e6f7ff;        /* 用户气泡背景 */
--ai-bubble: #ffffff;          /* AI 气泡背景 */
--text-primary: #1a1a1a;       /* 主文本 */
--text-secondary: #666666;     /* 次要文本 */
--text-muted: #999999;         /* 弱化文本 */
--border-color: #e8e8e8;       /* 边框 */
--shadow: 0 2px 8px rgba(0,0,0,0.06);
--radius-sm: 8px;
--radius-md: 12px;
--radius-lg: 16px;
--header-height: 56px;
--sidebar-width: 260px;

下拉菜单和弹窗

所有下拉菜单（类型选择、模型选择、比例选择等）采用统一的向上弹出定位（position: absolute; bottom: 100%），带 fadeInUp 动画。大面板弹窗使用 box-shadow: 0 -8px 32px 阴影。

与其他模块的关系

世界观系统

营销智能体使用固定 world_id = '1'，复用 script_writer 的世界观基础设施。会话通过 session_type: 2 区分营销模式和短剧模式（session_type: 1）。

算力系统

• 模型选择时通过 TaskConfig.getComputingPower() 实时预估消耗
• 发送消息时后端扣减算力，SSE 流结束后前端刷新余额
• 算力不足时后端返回错误，前端提示充值

PM Agent 后端

Agent 模式的消息通过 PM Agent（pm_agent.py）处理：

• PM Agent 根据用户意图委托专家（如 marketing-image 专家生图）
• 专家返回结果后，PM Agent 自动提取图片 URL 并注入对话历史（多模态消息）
• PM Agent 通过 call_agent 委托专家时会透传本次任务的 image_urls、audio_urls、video_urls；专家会以 [图片N]、[音频N]、[视频N] 标签注入上下文，避免数字人等任务只知道"用户已提供音频"但拿不到真实 URL
• Agent 前端发送任务前会等待音频上传完成，并只把真实 HTTP 音频 URL 写入 audio_urls；上传完成后会同步更新 mediaItems.serverUrl 和 mediaItems.fileUrl
• 数字人任务提交音频前会检查音频地址：localhost、内网地址和本地文件路径会先上传到视频生成服务的文件存储，并改用返回的文件标识；已是视频生成服务标准格式的文件名会直接复用，公网 URL 保持原值
• 通过 ask_user 工具实现向用户提问的交互
• 专家通过 script_writer_core/config/agents_config.json 中的 expert_type 声明所属模式；剧本 PM 只允许 script 类型专家，营销 PM 只允许 marketing 类型专家
• 可调用专家列表会按当前 PM 的 allowed_expert_types 动态过滤，后端也会做校验，避免营销模式误调用剧本专家或反向串线
• 营销视频克隆必须走 sop-video-clone 并委托 marketing-video；数字人口播必须走 sop-digital-human 并委托 digital-human-creator，且数字人专家必须实际调用 generate_digital_human 并返回非空 project_ids 才算提交成功
• 数字人口播缺少用户音频时，专家应调用通用 generate_reference_audio 生成参考音频；数字人专家不暴露角色耦合的 generate_character_reference_audio

用户偏好同步

用户在前端选择的图片模型、比例、分辨率等偏好通过 API 同步到后端相关数据表，确保跨设备/会话的一致性。

Agent 对话任务还会在 /api/session/{session_id}/task 入口同步本次请求携带的 image_preferences，避免只把"9:16"等偏好写入提示词、但专家实际调用生图工具时仍读取旧偏好。LLM 调用日志会输出 Agent 与 Agent scope 字段，可在 llm.log 中按 Agent scope: expert 或具体专家 ID 筛选专家智能体；第三方大语言模型接口返回的 reasoning_content（思考内容）会按日志截断规则记录正文，便于排查专家决策过程。

灵感发布页（Inspiration）

灵感页（/marketing-inspiration，由 web/marketing_inspiration.html + web/js/marketing_inspiration.js + web/css/marketing_inspiration.css 实现）展示已审核通过的公开作品（存于相关数据表），支持瀑布流浏览、Lightbox 详情、"做同款/用作参考图"（携带参数跳转到生成页），以及上传参考图直接发起 Agent 创作。

首页（web/index.html）在营销模式下点击"开始创作"横幅（handleStartCreation）即跳转到本页（/marketing-inspiration?user_id=...），灵感页左侧导航再进入生成对话页 /marketing-agent。

发布与资产固化

用户在生成页将生成记录"发布为灵感"时，POST /api/marketing-publications 触发资产固化服务执行 promote_assets：

1. 将生成结果、参考图、参考音视频从临时缓存（/upload/cache/...、/upload/temp/...）复制到长期目录 /upload/marketing_publications/{publication_id}/，避免缓存过期导致链接失效。
2. 为每个固化文件在相关数据表中创建一条记录（按 label 区分生成结果/参考图/参考音频/参考视频，采用永不过期的存储策略）。
3. 发布时写入数据库的仍是本地路径（指向 /upload/marketing_publications/...）。

CDN 透明加速

灵感页图片/视频统一通过 server.py 的 cdn_redirect_middleware 提供 CDN 访问，前端无需感知 URL 变化：

• 浏览器请求任意 /upload/*.{媒体扩展名} 时，中间件按本地路径指纹查相关数据表；若记录已有云存储路径，则 302 重定向到新鲜的对象存储签名 URL（28 小时有效），否则直接返回本地文件。
• promote_assets 在创建映射后，通过守护线程 fire-and-forget 调用 CDNUtil.trigger_cdn_upload 触发异步上传。因发布接口为 async 端点，此处用独立守护线程而非直接调用，避免内部线程池阻塞事件循环（Web 接口不得阻塞）。
• 上传是否触发受 server.auto_upload_to_cdn 配置门控：未启用时只建映射不上传，中间件也直接走本地文件，行为与无 CDN 一致。

设计说明：无需在 API 层（list_public/to_dict）替换 CDN URL。这与生成记录的处理方式一致（保持本地路径，依赖中间件透明重定向）。在 API 层每次生成签名 URL 既冗余又会绕过中间件统一的刷新逻辑。

做同款/参考图跳转

Lightbox 中"做同款"调用 GET /api/marketing-inspirations/{id}/template 获取参数快照与输入媒体（注意：模板返回的是参考图/参考视频，不包含生成的结果本身），再跳转到生成页；"用作参考图"将作品 URL 作为参考图带入 Agent 模式。跳转前对 src 做绝对 URL 判断（/^https?:\/\//），避免已是完整 URL 时重复拼接 window.location.origin。

文件清单