---
url: /docs/agentbuff-stack/brand-assets.md
---
# 品牌名称与素材

产品品牌统一配置在 `packages/core/website.ts`。公开页、工作台导航、登录页、安装清单和实际邮件读取同一配置。模板官网 `apps/website` 保持自己的品牌配置；修改产品不会替换官网案例或名称。

## 默认方案

默认显示短字符标记与网站名称，不依赖外部图片。`metadata.name` 控制名称，`brand.mark` 为一到三个无空白的可见字符。复制新站时，工厂根据名称生成首字母标记与独立 SVG 图标；例如 `Paper Studio` 得到 `PS`。

```ts
brand: {
  mark: "PS",
  logo: { light: null, dark: null },
  favicon: "/brand/favicon.svg",
  touchIcon: null,
  emailLogo: null,
},
```

`metadata.language` 控制产品 HTML 的默认语言声明，实际启用语言由 `i18n` 配置。公开页、工作台和账号 / 任务 / 营销邮件的英 / 西语言路径已有本地验收；译文人工审校、真实邮件显示和外部回跳仍待，见[产品语言](./languages)。维护教程保持中文。

## 使用自己的图片

所有品牌素材使用同源 `/brand/` 路径，分别放进 `apps/web/public/brand/` 与 `apps/app/public/brand/`。两套构建独立提供静态文件，必须有相同路径的对应素材。这里是工厂保留目录，不放业务文件或用户上传内容。

| 配置 | 支持格式 | 使用位置 |
| --- | --- | --- |
| `brand.logo.light` | SVG、PNG、JPEG、WebP、ICO | 浅色主题中的标记图片 |
| `brand.logo.dark` | 同上 | 深色主题中的标记图片；必须同时配置浅色图片 |
| `brand.favicon` | 同上 | 浏览器图标与安装清单，必填 |
| `brand.touchIcon` | PNG | 可选 Apple 触屏图标与安装清单 |
| `brand.emailLogo` | PNG、JPEG | 可选邮件图片，以 `APP_ORIGIN` 转成绝对地址 |
| `metadata.ogImage` | PNG、JPEG、WebP | 产品公开页面的分享预览 |

图片标记显示在导航原有的方形区域，旁边保留文本名称；建议使用方形透明标记而非带文字的横向商标。只配置浅色图片时两个主题共用它；浅深图片同时配置时随现有主题切换，不另建主题状态。

邮件图片必须能通过公开 HTTPS 地址读取，不能用私有文件、需要 Cookie 的下载地址或内联 SVG。默认 `null` 时只显示文字品牌，图片被邮箱屏蔽时仍有名称。当前本地捕获仅检查 HTML 和文字内容，不能替代真实邮箱客户端显示验收。

## 修改与检查

1. 将自己的素材放入上述两处目录。
2. 修改配置中的路径，运行 `bun config:check`。
3. 重新 `bun preview:build`，刷新公开页、登录页与工作台。
4. 分别检查浅深主题、手机宽度、浏览器图标、`/site.manifest` 和公开页分享元数据。

配置诊断与实际构建都检查路径、文件存在和格式签名。不接受外部地址、目录跳转、查询参数或片段；错误指出配置字段，不输出文件内容。这是构建预检，不是图像解码或 SVG 内容安全审计，使用自己确认过的素材。

安装清单由当前配置生成，不能再编辑旧 `public/site.manifest`。公开页和工作台均提供 `/site.manifest`；名称、语言与图标不需要重复维护。独立产品的主题配色仍由共享设计变量控制，见[设计系统](./design-system)。

## 新站与升级

工厂在新复制目录中清空 `/brand/`，生成新站图标，并重置 `brand`、`metadata.ogImage`、`metadata.social` 和 `metadata.supportEmail`。源站不被修改。生成后重新填写自己的联系方式与社交链接，提供自己的品牌素材；首页、博客和工具业务文案仍需按真实产品调整。

已有站升级时，先备份自己的品牌配置和素材，按新字段补齐，再重新构建；不对已有站运行清空素材操作。路径限制从可选外部 OG 图片收紧到同源 `/brand/`，原有图片须迁入保留目录。

任务邮件内容版本更新为 `task-mail-v2`。启用了可选任务邮件的站点，旧版或品牌名称、邮件图片已改变的未投递记录会标记 `CONFIG_CHANGED`，避免用同一幂等键重试不同内容；不会重新发送已接受的邮件。未启用任务邮件的站点不读取该投递表。本阶段没有新增数据库迁移。