0 Fork 0

Files

T

Stev_Wang 00ae12435e docs(specs): add AGENTS.md and engineering guidelines

项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立
总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈
基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、
格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。

影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。
回滚方式：git revert 本提交。

2026-11-02 15:09:51 +08:00

7.4 KiB

Raw Permalink Blame History

10 · 资产命名与 PSD 图层规范

项	内容
文档版本	V1.0（2026-11-02）
依据	PRD §5.3（资产）、§5.2（素材线）、R-01 / R-19 / R-25 / R-29 / R-30；技术架构 §7.3 / §7.5 / §8.11
适用范围	资产上传、模板制作、批次命名、成片导出、对象存储
强制级别	强制（`PSD-*` 为图片线硬前提，不满足即不可入库）

1　归属与层级

AST-01 全部资产必须挂在「行业 → 客户」两级目录下；行业是客户的业务属性，客户不可跨行业移动（PRD R-20）。
AST-02 资产三级：行业级（公共）→ 客户级（私有）→ 批次级（一次性）；同名时客户级覆盖行业级。
AST-03 跨客户复用必须显式授权并留痕，禁止默认共享（PRD 5.3.2）。
AST-04 15 类资产固定为：行业包、脚本模板、视频方向、已入库脚本、图片模板、Logo、产品位置、警示语、人物池、场景池、光影/色调预设、BGM/音效、提示词模板、要素卡模板/卖点库、成片。新增类型须先改 PRD 与架构。
AST-05 资产状态：草稿 → 启用 → 停用；被引用的资产只能停用不能删除（R-02）；模板与提示词修改产生新版本并记录被引用的版本号（R-03）。

2　命名通用规则

项	规则
允许字符	中文、字母、数字、下划线 `_`、短横线 `-`
禁止字符	空格、`\ / : * ? " < >
长度	≤ 100 字符（含扩展名）
占位符	`{行业}` `{客户}` `{视频方向}` `{日期}` `{序号}`（PRD R-01）
默认格式	`{行业}-{客户}-{视频方向}-{序号}`
重名	自动追加序号（`-02`、`-03`），禁止覆盖
大小写	语义名大小写敏感；扩展名统一小写

AST-06 占位符由服务端在批次创建时快照，之后修改命名规则不影响历史批次。
AST-07 文件名中的客户名使用客户简称（必填字段），不使用全称，避免超长与敏感信息。

3　各类编号与成片命名

对象	规则	示例
脚本编号	`{客户编码}-YYMMDD + 当日序号`，过审入库时原子取号；草稿不占号；一经分配不重用、不可改（R-21）	`LX001-261102-007`
素材批次号	`{YYMMDD}{3 位当日序号}`	`261102003`
图片成片	`{行业}-{客户}-{脚本方向}-{日期}-{序号}-{规格}`	`电商-某服饰-通勤穿搭-261102-01-9x16`
视频成片	`{行业}-{客户}-{视频方向}-{序号}`	`电商-某服饰-达人到店-03`
导出目录	`客户 / 交付日期 / 类型 / 批次`	`某服饰/2026-11-02/图片/261102003`

AST-08 规格后缀用 宽x高 或平台别名（9x16、1x1），由字典统一，禁止自由书写。
AST-09 成片命名与脚本编号必须可对账（交付清单同 key，PRD 5.5）。
AST-10 对象存储 key 与展示名分离：storage_key = assets/{industry_id}/{customer_id}/{asset_id}/v{version}/{filename}；展示名可改，key 不可改。

4　PSD 模板与图层约定（图片线核心）

4.1 图层前缀（唯一合法语义声明方式）

前缀	语义	数量要求
`image_replacement_`	商品图替换位（主体）	≥ 1
`clipping_mask_`	剪贴容器 / 裁切区域	0..n
`text_replacement_`	文字替换位（可配置字号 / 对齐 / 颜色）	0..n

PSD-01 命名结构：<前缀><语义名>，如 image_replacement_main、text_replacement_price；前缀全小写且大小写敏感。
PSD-02 同一模板内语义名唯一；重复命名视为非法。
PSD-03 无命名图层 / 解析失败 / 缺少 image_replacement_ → 模板不得入库，返回明确错误并提示设计师修正。
PSD-04 禁止用图层组名冒充命名图层；前缀必须落在实际图层上。
PSD-05 剪贴蒙版必须挂在 clipping_mask_ 容器下，商品图替换后仍保持裁切关系。
PSD-06 新增图层前缀类型须先更新技术架构 §7.3 与本文，禁止在代码里私自识别新前缀。
PSD-07 模板入库时校验：图层语义完整性、画布尺寸与目标规格比例、字体是否在白名单、是否存在隐藏图层（隐藏图层默认忽略并记录）。
PSD-08 字体：镜像内置中文字体，启动自检；模板引用的字体不在白名单 → 拒绝入库（避免豆腐块，风险 R-T-18）。

4.2 抠图与合成

PSD-09 抠图失败必须降级为原图并标 low_quality（原因码 matting_fallback），默认不勾选（R-30）。
PSD-10 合成结果必须过质量校验：安全区、Logo 完整性、主体不变形、警示语四项；未过则标 low_quality 并记录原因码。
PSD-11 视觉回归：packages/render 改动需跑像素级比对，阈值与基线图入库管理。

5　规格矩阵（字典化，禁止硬编码）

平台	比例	分辨率
抖音	9:16	1080×1920
小红书	3:4	1080×1440
朋友圈	1:1 / 4:5	1080×1080 / 1080×1350
横版	16:9	1920×1080
电商主图	1:1	800×800 / 1200×1200

AST-11 规格来自字典表，前后端与任务判定读同一来源（R-26）；新增规格改字典不发版。
AST-12 素材为主对象、规格为属性：同源多规格不各建素材，用 material_specs 承载（R-25）；素材与脚本多对多用关联表，禁止 JSON 列存 ID。

6　输出编码与存储

类型	参数
视频	MP4 / H.264 / AAC / 1080×1920 / 30fps / `+faststart`
图片	JPG（质量 92）或 PNG；导出质量 ≥ 90
兜底	超限降质必须标 `low_quality`（原因码 `downscaled`），不得静默

桶	内容	保留
`assets`	长期资产	永久（版本化）
`renders`	生成产物	按客户策略
`temp`	任务中间文件	30 天
`archive`	归档	≥ 12 个月
`uploads`	原始上传	按资产生命周期
`exports`	打包导出	3 天

AST-13 下载一律短时效签名 URL（5–15 分钟），禁止公开读权限、禁止把签名 URL 存库。
AST-14 临时目录按任务隔离：/tmp/task/{taskItemId}，任务结束清理；失败任务保留 1 天便于排查后清理。

7　低质量原因码（统一枚举）

matting_fallback（抠图降级）· missing_font（缺字体）· downscaled（超限降质）· logo_incomplete（Logo 不完整）· warning_missing（警示语缺失）· safe_area_violated（安全区越界）· subject_distorted（主体变形）

AST-15 原因码只增不改语义；前端与看板按码聚合，禁止在文案里写自由文本。
AST-16 低质量条目计入质量看板与指标（PRD 8.1），可被人工复核转为正常，但必须留痕。

8　检查清单（模板入库前）

PSD 至少 1 个 image_replacement_，剪贴关系正确
所有可替换位均有合法前缀，语义名唯一
画布比例与目标规格匹配
字体在白名单内，无隐藏图层未说明
模板归属「行业 → 客户」正确，版本号已生成
命名符合 §2，无非法字符，长度 ≤ 100
低质量降级路径可触发，原因码已定义
产物编码参数符合 §6，签名 URL 生效

7.4 KiB Raw Permalink Blame History Unescape Escape

10 · 资产命名与 PSD 图层规范

1 归属与层级

2 命名通用规则

3 各类编号与成片命名

4 PSD 模板与图层约定（图片线核心）