lunanting/ai-chatbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-chatbot/docs/AI详情生成-AGENT可编程渲染开发文档.md
Your Name 64cb485dfa
Some checks failed
Lint / build (20) (push) Has been cancelled
Details
Playwright Tests / test (push) Has been cancelled
Details
feat: refine agent workflow flow
2026-03-17 18:23:32 +08:00

13 KiB
Raw Blame History

AI详情生成开发文档（当前实现版）

1. 文档定位

本文档不再描述理想中的完整目标架构，而是基于当前仓库代码与前端交互，整理出一份可直接用于开发、联调、排查和运营说明的“当前实现版”文档。

适用范围：

  • 无限画布中的 AI详情生成工作台
  • 前端入口与交互流程
  • 当前已接入的后端 API
  • classic 与 agent_layout 两种模式的真实差异
  • 已上线能力、未上线能力、已知限制

如果后续要继续推进“项目化管理 / Layout QA / 14屏严格状态机 / 项目级 API”，请在本文件基础上新增“规划版”文档，不要再把目标方案和当前实现混写。

2. 状态说明

本文档中的状态标签含义如下：

  • 已实现：仓库中已有入口和主要逻辑，当前系统可走通
  • 部分实现：已有部分链路，但与原设计稿不完全一致
  • 未实现：文档中仅保留为后续规划，不应视为当前能力

3. 当前能力总览

3.1 功能入口 已实现

  • 入口位置：无限画布右侧聊天工作台中的 AI详情生成
  • 前端主文件：components/canvas/CanvasChatPanel.tsx
  • 用户可以选择两种模式：
    • classic：传统生图
    • agent_layout：AGENT排版

3.2 当前真实输入约束 已实现

必填业务字段：

  • targetAudience
  • usageScenario
  • coreNeed

当前前端强制素材要求：

  • 5 张产品图：必填
  • 1 张模特图：当前实现中必填
  • 0-3 张搭配图：可选

说明：

  • 文档层面原本把模特图写成“可用于卖家视角场景”，但当前前端实现里它实际上是必填项。
  • 如果没有模特图，前端会直接拦截，不会进入 AI 详情规划。

3.3 当前真实输出结构 已实现

当前 AI 详情一次生成的输出由两部分组成：

  1. 详情主图分镜

    • 通过 /api/canvas/detail-plan 先规划
    • 再逐屏调用生图接口

  2. 买家评价与晒单

    • 在主图全部完成后由前端追加生成
    • 不属于 detail-plan 主分镜返回本体

4. 当前系统里的真实流程

4.1 主流程概览 已实现

当前系统实际流程如下：

flowchart LR
    A["用户填写brief并上传素材"] --> B["前端校验必填字段和素材"]
    B --> C["POST /api/canvas/detail-plan"]
    C --> D["返回 screens/prompts/globalStyle/preflight"]
    D --> E["前端逐屏调用生图"]
    E --> F{"generation_mode"}
    F -->|classic| G["逐屏 detail-review 质检 + 可选二次修图"]
    F -->|agent_layout| H["前端叠加可编辑文字层"]
    G --> I["主图完成后追加评价晒图"]
    H --> I
    I --> J["写入画布节点 + 更新本地/数据库存档"]

4.2 关键特点

  • 当前没有“项目级任务状态机 API”
  • 当前没有后端统一的 /detail-projects/:projectId/generate
  • 当前没有 SSE 进度接口
  • 进度条、占位图、逐屏生成状态全部在前端本地维护

5. 两种模式的真实差异

5.1 classic 传统生图模式 已实现

特点：

  • 生图模型直接生成整页详情图
  • 提示词中会带标题、副标题、正文、FABE、排版说明
  • 每屏生成后会调用 /api/canvas/detail-review
  • 如果质检不通过，会基于 revisedPrompt 二次修图一次

优点：

  • 成图速度快
  • 页面信息一次成型

限制：

  • 文生图模型对文字和排版控制不稳定
  • 容易出现文字失真、布局漂移、参数被画出来等问题

5.2 agent_layout AGENT排版模式 已实现

特点：

  • 生图模型只生成画面层
  • 明确禁止模型输出可见文字、数字、Logo、水印
  • 画面生成完成后，前端在图片节点上叠加 3 个可编辑文字节点：
    • 标题
    • 副标题
    • 正文

当前文字层位置：

  • 标题：y + 72
  • 副标题：y + 214
  • 正文：y + 304
  • 左边距：约画面宽度的 7%

优点：

  • 文字可编辑
  • 文案层级更统一
  • 避免模型把整页文字烤死

限制：

  • 当前文字层位置是前端固定模板，不是后端程序化版式引擎
  • 当前 agent_layout 不走 /api/canvas/detail-review
  • 当前没有“文字遮挡主体”的自动检测

6. 屏数与完成条件

6.1 当前真实规则 已实现

当前主图分镜数不是固定 14 屏，而是动态值：

  • 前端会从用户输入文本里解析 X张 / X屏 / X页
  • 如果没解析到，默认 14 屏
  • 后端会把数量限制在 5-20
  • 如果上传了搭配图，会额外加 1 屏搭配展示

6.2 当前真实完成条件 已实现

当前“完成”并不是“必须满 14 屏”，而是：

  • 本次 detail-plan 返回了多少条 prompts
  • 前端就按多少屏去生成
  • 当 generatedImages.length === prompts.length 时，主图阶段视为完成

6.3 评价晒图的关系 已实现

买家评价与晒单是主图完成后的追加产物：

  • 默认追加 3 条评价方案
  • 每条评价生成 3 张晒单图
  • 不计入主图 prompts.length

7. 当前接口清单

7.1 已上线接口

1. POST /api/canvas/detail-plan 已实现

作用：

  • 生成 AI 详情规划结果
  • 返回：
    • summary
    • prompts
    • globalStyle
    • skillFlow
    • qualityChecks
    • preflight
    • screens
    • generationMode

输入重点：

  • prompt
  • count
  • generationMode
  • referenceImages
  • referenceImageNotes
  • modelImageUrl
  • bundleImageUrls
  • brief

2. POST /api/canvas/detail-review 已实现

作用：

  • 对已经生成的单屏整页图做双总监质检
  • 仅在 classic 模式下调用

返回重点：

  • pass
  • score
  • designDirectorScore
  • marketingDirectorScore
  • issues
  • layoutFixes
  • revisedPrompt

3. GET|POST|PATCH|DELETE /api/canvas/[id]/detail-archives 已实现

作用：

  • 详情生成历史归档
  • 读取、保存、更新、删除历史详情项目快照

说明：

  • 当前系统使用的是“归档快照”而不是“项目型任务管理”
  • 实际归档里会保存：
    • prompt
    • generationMode
    • brief
    • slots
    • summary
    • coverUrl
    • imageCount

7.2 文档里曾规划但当前未上线的接口

以下接口在旧文档中出现过，但当前仓库未实现，不应视为现有能力：

  • POST /api/canvas/[id]/detail-projects
  • GET /api/canvas/[id]/detail-projects
  • GET /api/canvas/[id]/detail-projects/:projectId
  • POST /api/canvas/[id]/detail-projects/:projectId/generate
  • POST /api/canvas/[id]/detail-projects/:projectId/retry-screen
  • GET /api/canvas/[id]/detail-projects/:projectId/progress
  • POST /api/canvas/[id]/generation-mode

状态：未实现

8. 当前真实数据与存储方式

8.1 当前真实存档模型 已实现

当前 AI 详情不是独立的 detail_projects 体系，而是基于：

  • canvasProject
  • canvasDetailArchive

来做归档和归属校验。

8.2 当前未实现的数据设计

以下是旧文档中规划过、但当前代码未接入的数据表概念：

  • detail_projects
  • detail_project_inputs
  • detail_assets
  • detail_screen_specs
  • detail_screen_renders
  • detail_generation_jobs

状态：未实现

9. 当前规划结果的数据结构

当前 /api/canvas/detail-plan 返回的每屏结构重点如下：

type DetailPlanScreen = {
  index: number;
  screenType: "A" | "B" | "C";
  objective: string;
  title: string;
  subtitle: string;
  copy: string;
  layoutNote: string;
  useModel: boolean;
  modelReason: string;
  bundleShowcase: boolean;
  bundleReason: string;
  visualPrompt: string;
  fabe: {
    b: string;
    f: string;
    a: string;
    e: string;
  };
};

说明：

  • 当前虽然返回 screens，但这不是旧文档中那个完整的可编辑 ScreenSpec 协议
  • 真实落地时，前端主要使用：
    • visualPrompt
    • title
    • subtitle
    • copy
    • layoutNote
    • screenType

10. 当前前端交互与画布落位

10.1 占位与落位 已实现

  • 生成前先在画布中创建纵向占位图节点
  • 每个节点尺寸固定 790x1300
  • 纵向排列
  • 占位图会显示当前状态：
    • 需求解析与分镜规划中
    • 分镜规划完成
    • 双总监预审通过
    • 主图首稿生成中
    • 排版层渲染中
    • 生成失败

10.2 agent_layout 文字叠加 已实现

画面生成完成后，前端会自动叠加文字节点：

  • 标题：大字号、粗体
  • 副标题：中字号、中高权重
  • 正文：较小字号、灰阶色

当前是模板化坐标，不是自适应排版引擎。

10.3 手动编辑 部分实现

当前可编辑能力：

  • 可直接在画布中改文字
  • 图片节点可继续操作

当前未实现或未证实完整上线：

  • 图标层体系
  • 独立排版吸附策略
  • 通过“保留版式仅重生画面”的专门 UI 按钮

11. 当前质检与兜底机制

11.1 分镜预审 已实现

detail-plan 在规划后会做一次“平面设计总监 + 营销总监”预审：

  • 返回 preflight
  • 包含：
    • designDirectorScore
    • marketingDirectorScore
    • issues
    • rewriteApplied

如果预审不理想，会优先尝试重写方案；仍不理想则回退到稳定模板。

11.2 单屏质检 部分实现

仅 classic 模式下：

  • 每屏首稿完成后调用 /api/canvas/detail-review
  • review 不通过时，会用 revisedPrompt 二次修图一次

agent_layout 模式下：

  • 当前不走这套逐屏 review 流程

11.3 当前实际不存在的质检能力

以下内容在旧文档里有描述，但当前代码中未实现：

  • product_mask
  • saliency_map
  • 遮挡率计算
  • 文本对比度计算
  • qa_passed / qa_score / qa_issues / qa_fix_actions
  • 质检报告面板

状态：未实现

12. 当前失败与回退策略

12.1 已实现回退

  1. detail-plan 超时或失败时
  • 带参考图失败，先去掉参考图重试
  • 仍失败，回退到 fallback 分镜模板
  1. detail-review 失败时
  • 保留当前屏结果
  • 不会整套中断
  1. 生图失败时
  • 逐屏抛错
  • 若最终成功屏数不等于计划屏数，则本轮主图任务报错

12.2 当前线上已观察到的问题

  • detail-plan 经常 generateText timed out after 45000ms
  • preflight 偶发 10000ms 超时
  • 火山视觉兜底存在 size 参数不合法问题
  • 火山视觉会因输入图超过 10MB 报错
  • 当前日志对 generationMode 的显式记录不够

13. 当前性能与运维现状

13.1 已实现策略

  • 参考图会先做可达性检查
  • 规划阶段对内联图片数量有限制
  • 规划超时和参考图失败会自动降级

13.2 当前真实瓶颈

  • 规划模型 45 秒超时较常见
  • 智能分析链路和 AI 详情共用资源时，容易放大整体超时概率
  • 服务器高负载时，详情规划失败概率明显上升

14. 当前实现与旧文档差异总结

以下是最容易误导的几个点：

  1. 不是“固定 14 屏严格状态机”
  • 实际是动态屏数，默认 14，可在 5-20 之间浮动
  1. 不是“项目型 API 架构”
  • 实际是 detail-plan + detail-review + detail-archives
  1. 不是“模特图可选”
  • 实际前端要求模特图必填
  1. 不是“Layout QA 已上线”
  • 实际只有 LLM 预审和 classic 单屏 review
  1. 不是“所有模式都逐屏质检”
  • 实际 agent_layout 跳过 /detail-review

15. 推荐的下一步迭代顺序

基于当前系统现状，建议优先做这些“短路径、可落地”的改动：

第一阶段：修稳定性

  • 在日志中显式打印 generationMode
  • 降低 detail-plan 规划超时概率
  • 修复火山视觉 size 参数映射
  • 生图前压缩超大参考图

第二阶段：修文档与能力一致性

  • 让模特图是否必填与产品策略一致
  • 明确“主图屏数”和“评价晒单”之间的边界
  • 把当前档案型接口正式定义清楚

第三阶段：增强 agent_layout

  • 把前端固定文字坐标升级为可配置模板
  • 让 agent_layout 也支持可控的逐屏质量检查
  • 增加更明确的排版冲突规避策略

第四阶段：再考虑项目化

  • 如需真正的 detail-projects / progress / retry-screen / generation-mode API，再单独设计
  • 不建议在当前文档里继续把它们写成“已经存在的系统能力”

16. 代码入口索引

当前 AI 详情的主要代码入口如下：

  • 前端工作台：components/canvas/CanvasChatPanel.tsx
  • 详情规划：app/api/canvas/detail-plan/route.ts
  • 详情质检：app/api/canvas/detail-review/route.ts
  • 详情存档：app/api/canvas/[id]/detail-archives/route.ts

17. 结语

当前 AI 详情功能已经具备“可用”的主链路：

  • 可规划
  • 可逐屏生图
  • 可归档
  • 可区分 classic 与 agent_layout
  • 可追加评价晒单

但它还不是旧文档里描述的完整项目化系统。

后续所有开发、测试、运营说明，建议以本文件为准；如果要继续推进目标架构，请新开“规划版”文档，不再修改本文件的“当前实现事实”定位。