lunanting/ai-chatbot

Fork 0

Your Name 17dcfcd55d

Lint / build (20) (push) Has been cancelled

Details

Playwright Tests / test (push) Has been cancelled

Details

feat: add PSD template font rendering workflow

2026-03-27 11:01:13 +08:00

14 KiB

Raw Blame History

智能体结果区接入 PSD 模板替换功能开发文档

1. 目标

在智能体专用功能页面中，为生图结果区增加一个新的结果后处理能力：

管理员可以在后台上传 PSD 模板
管理员可以配置 PSD 中哪些图层允许用户替换，哪些图层锁定不可改
用户可以在智能体结果区直接选择某张生成结果图，套用 PSD 模板
用户可继续上传图片替换模板中可编辑图层
系统输出最终合成图，并支持下载

本功能定位为：

管理员预设模板 + 用户替换素材 + 一键合成导出

本功能不定位为：

通用 PSD 编辑器
完整 Photoshop 在线还原器
支持任意复杂 PSD 全特效、全图层类型的无损回写

2. 现状评估

2.1 已有能力

当前项目已经具备以下基础，可以直接复用：

智能体专用工作台和结果区
- components/agents/AgentGenerationWorkspaceDarkV2.tsx
智能体项目结果归档
- types/agent.ts
- lib/agents/generation-project-state.ts
文件上传和对象存储
- lib/storage/service.ts
图片编辑弹层容器
- components/image-annotator.tsx
后台系统设置页与保存链路
- app/(admin)/settings/admin-settings-client.tsx
- app/api/site-settings/route.ts

2.2 当前缺口

项目中目前没有以下能力：

PSD 模板管理
PSD 图层树解析
图层级可编辑槽位定义
根据图层规则进行模板合成
结果区内“套用 PSD 模板”的入口

因此该需求是一个可独立立项的新功能，不属于简单前端补按钮。

3. 用户路径设计

3.1 管理员路径

管理员进入后台 系统设置
打开新的 PSD模板管理 模块
上传 PSD 模板文件
系统解析图层树并生成模板预览
管理员为图层配置：
- 是否可替换
- 显示名称
- 是否必填
- 默认是否使用“当前结果图”
- 填充模式：cover / contain / stretch
- 是否允许用户自行上传覆盖
保存模板并发布启用

3.2 用户路径

用户在智能体结果区看到某张结果图
点击该结果图上的 套用PSD模板
打开模板编辑面板
当前结果图自动填入管理员配置的默认槽位
用户继续为其余可编辑图层上传图片
点击 生成模板图
系统返回合成结果
用户下载 PNG/JPG

3.3 为什么要从结果区直接进入

这样最符合当前工作流：

用户不需要先下载结果图再重新上传
当前结果图可以直接作为模板主图输入
功能属于“结果加工”，放在结果区比放在独立页面更自然

4. MVP 范围

第一版建议仅支持以下范围：

PSD 模板文件上传
解析 PSD 图层树
支持普通位图图层作为可替换槽位
支持图层位置、尺寸、透明度、显示顺序
支持图层分组的层级结构读取
支持生成扁平化结果图 PNG/JPG
支持从智能体结果图直接进入模板编辑
支持用户上传图片替换多个可编辑槽位

第一版不建议承诺：

复杂图层特效完整还原
调整图层完整支持
智能对象完整支持
文字层在线编辑
PSD 文件回写导出
CMYK/16bit/32bit 全兼容
任意 Photoshop 私有特性兼容

5. 开源方案评估

5.1 候选方案

方案 A：`@webtoon/psd`

仓库：https://github.com/webtoon/psd
语言：TypeScript
适用：Node / Browser
优点：
- 前后端都能接
- 对当前 Next.js 项目接入成本低
- 适合做 PSD/PSB 结构解析、图层信息读取
风险：
- 对复杂 Photoshop 元数据支持有限
- 图层特效完整兼容不适合做第一版承诺

方案 B：`ag-psd`

仓库：https://github.com/Agamnentzar/ag-psd
语言：JavaScript / TypeScript
适用：Node / Browser
优点：
- 生态成熟
- 读写 PSD 成本较低
- 适合快速做 Node 侧 PoC
风险：
- 对复杂 PSD 特性支持有限
- 不适合作为“复杂模板 100% 兼容”的基础承诺

方案 C：`psd-tools`

仓库：https://github.com/psd-tools/psd-tools
语言：Python
优点：
- 服务端解析能力更稳
- 适合复杂模板和批处理
风险：
- 需要额外引入 Python 服务
- 当前 Node 项目接入复杂度更高

5.2 推荐结论

推荐分阶段：

第一阶段：
- 优先使用 Node 方案
- 首选 ag-psd 或 @webtoon/psd 做 PoC
- 结合现有 sharp 完成最终合成导出
第二阶段：
- 若第一阶段发现复杂 PSD 兼容性不够
- 再拆出 Python 微服务，基于 psd-tools 做增强版解析

5.3 与本项目最匹配的建议

当前项目是 Next.js + Node + S3 上传链路，第一版建议：

PSD 解析：Node 侧 ag-psd
图片处理与导出：sharp
存储：复用 lib/storage/service.ts

原因：

改动最小
接入速度最快
适合先把产品闭环跑通

6. 产品设计建议

6.1 后台管理入口

建议在系统设置中新增一个分组：

PSD模板管理

建议不要继续把模板配置塞到单个 site_settings 大 JSON 中，而是独立成资源管理。

6.2 智能体结果区入口

在智能体结果图卡片上增加新操作按钮：

套用PSD模板

保留现有动作：

下载
送入画布改字

新增后的结果卡片动作建议：

下载
送入画布改字
套用PSD模板
删除

6.3 模板编辑弹层

建议使用右侧抽屉或大弹窗，不建议跳新页面。

弹层结构建议：

左侧：模板预览图
右侧：可编辑图层槽位列表

每个槽位显示：

槽位名称
图层预览缩略图
当前素材来源
- 当前结果图
- 用户上传
替换按钮
清空按钮

底部操作：

生成模板图
下载结果

7. 数据结构设计

建议新增以下表。

7.1 `PsdTemplate`

用于存模板主信息。

字段建议：

id
name
description
status
- draft
- active
- disabled
psdAssetUrl
previewImageUrl
flattenPreviewUrl
canvasWidth
canvasHeight
layerCount
parserEngine
parserVersion
createdBy
createdAt
updatedAt

7.2 `PsdTemplateLayerSlot`

用于存 PSD 图层配置。

字段建议：

id
templateId
layerKey
layerName
parentPath
sortOrder
isEditable
isRequired
isDefaultResultSource
allowUserUploadOverride
replaceMode
- cover
- contain
- stretch
x
y
width
height
opacity
blendMode
maskAssetUrl
layerPreviewUrl
lockedReason

7.3 `PsdTemplateRenderTask`

用于记录用户模板替换任务。

字段建议：

id
userId
chatId
projectId
sourceResultImageUrl
templateId
status
- queued
- processing
- succeeded
- failed
slotAssignments
resultImageUrl
errorMessage
createdAt
updatedAt

7.4 结果归档扩展

建议在智能体结果模式中新增：

psd_template_replace

对应类型位置：

types/agent.ts
lib/agents/generation-project-state.ts

这样模板替换结果可以进入当前项目的结果归档体系，而不是游离在外。

8. 后台功能设计

8.1 模板上传

管理员上传 PSD 后，服务端执行：

上传原始 PSD 到对象存储
创建解析任务
解析图层树
生成模板预览图
抽取图层预览图
初始化图层槽位配置

8.2 图层配置页面

管理员在后台对每个图层设置：

是否允许替换
是否锁定
是否默认使用当前结果图
是否必填
用户是否可覆盖
填充模式
图层显示名称

8.3 模板发布

只有 active 模板才会在前台结果区中可选。

9. 前台功能设计

9.1 结果图卡片新增按钮

修改文件：

components/agents/AgentGenerationWorkspaceDarkV2.tsx

在以下结果卡片区域增加 套用PSD模板：

detail_generation
detail_replacement
sku_replacement
scene_generation

9.2 打开模板编辑器

点击后执行：

打开模板选择器
若只有一个启用模板，直接进入模板编辑面板
自动把当前结果图填入默认槽位

9.3 替换槽位填充

用户为每个 editable slot 选择素材来源：

使用当前结果图
上传新图片
清空

9.4 结果下载

输出结果建议：

默认导出 PNG
可选导出 JPG

不建议第一版导出 PSD。

10. API 设计

建议新增以下接口。

10.1 后台模板管理

GET /api/admin/psd-templates
POST /api/admin/psd-templates
GET /api/admin/psd-templates/:id
PUT /api/admin/psd-templates/:id
DELETE /api/admin/psd-templates/:id

10.2 图层槽位管理

PUT /api/admin/psd-templates/:id/layers

10.3 用户模板列表

GET /api/psd-templates

返回启用模板的简要信息。

10.4 模板渲染

POST /api/psd-templates/render

请求体建议：

{
  "templateId": "xxx",
  "projectId": "xxx",
  "chatId": "xxx",
  "sourceResultImageUrl": "https://...",
  "slotAssignments": [
    {
      "layerSlotId": "slot-1",
      "sourceType": "result_image",
      "imageUrl": "https://..."
    },
    {
      "layerSlotId": "slot-2",
      "sourceType": "upload",
      "imageUrl": "https://..."
    }
  ]
}

响应建议：

{
  "success": true,
  "taskId": "xxx",
  "resultImageUrl": "https://..."
}

11. 渲染与合成方案

11.1 推荐实现方式

不要尝试在第一版做“完整 PSD 在线编辑”，而是采用：

PSD 解析
图层资产切片
规则化重组

11.2 合成流程

管理员上传模板后：

解析 PSD
读取图层顺序
把每个锁定图层导出为 PNG 资产
把可替换图层记录为 slot
若图层自带蒙版，导出蒙版资产

用户执行模板替换时：

读取模板图层顺序
对每个可替换槽位做图片变换
- 缩放
- 裁剪
- 平移
- 蒙版裁切
按原始 z-index 顺序叠加
用 sharp 输出最终 PNG/JPG

11.3 第一版支持的图层类型

建议仅支持：

普通位图图层
图层组
透明度
基础可见性
基础图层顺序

11.4 第一版不保证的图层能力

图层样式
调整图层
智能对象深度编辑
文字层重新布局
高级混合模式精确保真

12. 模板规范约束

为了让第一版稳定，必须给运营/设计一个模板规范：

模板请使用 RGB / 8bit
可替换图层尽量使用普通像素图层
可替换图层命名必须规范，例如：
- slot_main_product
- slot_model
- slot_logo
不要把关键替换区域做成复杂智能对象
文字层、滤镜、阴影、渐变叠加等复杂效果尽量做成锁定图层
所有用户可替换区域必须在 PSD 中有明确边界

13. 与现有系统的对接点

13.1 智能体结果区

改动文件：

components/agents/AgentGenerationWorkspaceDarkV2.tsx

新增：

结果卡片按钮 套用PSD模板
模板编辑抽屉
模板结果下载按钮

13.2 项目结果归档

改动文件：

types/agent.ts
lib/agents/generation-project-state.ts
app/canvas/[id]/page.tsx

新增：

psd_template_replace 结果分类

13.3 后台系统设置

如果继续沿用系统设置容器，可在：

app/(admin)/settings/admin-settings-client.tsx

中增加模板管理入口。

但更推荐新增独立管理页：

app/(admin)/settings/psd-templates/page.tsx

14. 风险评估

14.1 技术风险

开源 PSD 库兼容性有限
不同 PSD 导出习惯会导致模板可解析性差异很大
智能对象、文字层、图层样式是风险最高区域

14.2 产品风险

如果一开始承诺“任意 PSD 都能改”，后续维护成本会极高
如果管理员模板配置过于复杂，后台操作成本会上升

14.3 控制策略

第一版强约束模板规范
只开放位图层替换
后台明确标注“不支持复杂 PSD 高级效果完整还原”
先做少量模板验证，再扩大使用范围

15. 开发拆分建议

阶段 1：PoC

目标：

上传一个 PSD
解析图层树
指定 1 到 2 个可替换图层
输出合成 PNG

产出：

证明技术链路成立

阶段 2：后台配置

目标：

完成模板管理
完成图层槽位设置
完成启用/禁用

阶段 3：前台结果区接入

目标：

从智能体结果卡片进入模板编辑
自动带入当前结果图
用户补图
输出结果并下载

阶段 4：项目归档与运营化

目标：

模板替换结果进入项目结果区
支持结果二次查看
支持模板权限与状态管理

16. 工期预估

MVP

需求细化与 PoC：2 到 3 天
后台模板管理：3 到 5 天
前台结果区接入：3 到 5 天
服务端渲染导出：3 到 5 天
联调与修正：2 到 4 天

总计：

约 2 周

稳定版

若加入更多模板兼容、任务队列、错误回退、运营配置，建议预留：

3 到 4 周

17. 验收标准

后台

管理员可上传 PSD 模板
系统可展示图层列表
管理员可标记哪些图层允许替换
模板可启用/停用

前台

用户可从智能体结果区直接点击进入 PSD 模板编辑
当前结果图可自动注入默认槽位
用户可上传图片替换其他 editable slot
能生成最终模板图
能下载生成结果

数据

模板替换结果可被记录
模板配置可持久化
出错时能返回明确失败原因

18. 最终建议

建议立项，但必须按以下原则推进：

第一版只做“模板替换器”，不做“通用 PSD 编辑器”
第一版只支持规范模板，不承诺任意 PSD 全兼容
入口放在智能体结果区，直接作用于现有生成结果
模板管理后台独立建设，不建议继续把所有配置堆到单个大 JSON 里

14 KiB Raw Blame History Unescape Escape

智能体结果区接入 PSD 模板替换功能开发文档

1. 目标

2. 现状评估

2.1 已有能力

2.2 当前缺口

3. 用户路径设计

3.1 管理员路径

3.2 用户路径

3.3 为什么要从结果区直接进入

4. MVP 范围

5. 开源方案评估

5.1 候选方案

方案 A：@webtoon/psd

方案 B：ag-psd

方案 C：psd-tools

5.2 推荐结论

5.3 与本项目最匹配的建议

6. 产品设计建议

6.1 后台管理入口

6.2 智能体结果区入口

6.3 模板编辑弹层

7. 数据结构设计

7.1 PsdTemplate

7.2 PsdTemplateLayerSlot

7.3 PsdTemplateRenderTask

7.4 结果归档扩展

8. 后台功能设计

8.1 模板上传

8.2 图层配置页面

8.3 模板发布

9. 前台功能设计

9.1 结果图卡片新增按钮

9.2 打开模板编辑器

9.3 替换槽位填充

9.4 结果下载

10. API 设计

10.1 后台模板管理

10.2 图层槽位管理

10.3 用户模板列表

10.4 模板渲染

11. 渲染与合成方案

11.1 推荐实现方式

11.2 合成流程

11.3 第一版支持的图层类型

11.4 第一版不保证的图层能力

12. 模板规范约束

13. 与现有系统的对接点

13.1 智能体结果区

13.2 项目结果归档

13.3 后台系统设置

14. 风险评估

14.1 技术风险

14.2 产品风险

14.3 控制策略

15. 开发拆分建议

阶段 1：PoC

阶段 2：后台配置

阶段 3：前台结果区接入

阶段 4：项目归档与运营化

16. 工期预估

MVP

稳定版

17. 验收标准

后台

前台

数据

18. 最终建议

14 KiB

Raw Blame History

方案 A：`@webtoon/psd`

方案 B：`ag-psd`

方案 C：`psd-tools`

7.1 `PsdTemplate`

7.2 `PsdTemplateLayerSlot`

7.3 `PsdTemplateRenderTask`