为聊天品牌化 — 颜色与标志

原则——只给一种颜色，不要给一套配色。 前景色会在保存时从中派生，从而确保所有组合都清晰可读。自行选择文本颜色是导致按钮文字无法阅读的原因。

品牌标识（Branding）存在于 share（分享链接） 中，而非 agent（智能体）本身：同一个 agent 在一个网站上可以是白标小部件，在另一个地方则只是一个普通链接。因此，请先获取 token。

list_shares(agent_name="mortgage-advisor")
# → [{ token: "RuqY…", label: "Website widget", config: { theme_color: "#F7B331", … } }]
 
configure_share(
  agent_name="mortgage-advisor",
  token="RuqY…",
  theme_color="#F7B331",
  logo_url="https://cdn.example.com/brand/mark-512.png",
)

仅更改你传递的字段——其余配置保持不变。

重命名 share

label 是聊天页面顶部和浏览器标签页标题中显示的名称。它是 configure_share 上的一个字段，与其他字段无异：

configure_share(agent_name="mortgage-advisor", token="RuqY…", label="Pip — reading buddy")

你无需创建新的 share 并删除旧的 share 来重命名它。 新的 share 意味着新的 token，因此已嵌入客户网站中的链接将失效——可见的名称与地址并非同一事物，且只有名称是在发布后可以安全更改的。

第二种颜色，仅当品牌拥有时

大多数品牌只有一种颜色，无需在此处进行任何操作。有些品牌拥有主色和高亮色——将第二种颜色作为 highlight_color 传递，它将被用于需要可见但不能与主要操作竞争的场景：

configure_share(
  agent_name="pip",
  token="ENhs…",
  theme_color="#0B4230",      # primary: buttons, the current storyline step, user bubbles
  highlight_color="#D9A922",  # highlight: second chart series, citation markers
)

其前景色会在保存时像主色一样派生，因此相同的可读性保证依然有效。将其省略则任何地方都不会发生变化——--acc-2 回退到主色，这是每个单色品牌所需且无需配置的内容。

不要手动将其扩散。 你 可以 从 custom_css 覆盖我们的组件类，但你会后悔的：这些类名是我们的内部实现，它们会发生变化，一旦变化，你的品牌标识就会无声地失效。设置这两种颜色，让组件决定每个颜色的归属。

颜色：传递一个，获得四个

theme_color 是品牌的主色，格式为 #RGB 或 #RRGGBB。在保存时，平台通过 WCAG 对比度派生前景色并存储它们：

浅色品牌颜色因此获得深色文本，而不是白色。#F7B331 配白色文本的对比度为 1.83:1——甚至低于 UI 组件 3:1 的底线，这意味着标签实际上不可读；派生的深色前景对比度为 10.21:1。

不要自行计算配色方案，也不要尝试设置文本颜色——它们由服务器派生，你的值会被覆盖。传递一种颜色就是全部工作。

清除它（theme_color=""）也会删除派生值，并将小部件恢复为默认蓝色。不设置它也会产生相同的效果——内置 token 已经是匹配的一对。

Logo：纵横比决定其使用位置

传递绝对 URL。Logo 出现在两个具有不同约束的位置：

• 标题栏——高度对齐，宽度自由。任何纵横比都适用，包括宽幅字标。
• 折叠气泡——正方形，因为 logo 就是 气泡的形状。仅使用 0.74 到 1.35 之间的纵横比；宽幅字标会回退到平台图标，而不是被挤压成无法阅读的窄条。

因此，对于宽幅字标，实际的答案是两个文件：标题栏的字标，气泡的方形标记。如果客户只有字标，标题栏仍会显示他们的品牌，而气泡显示中性图标——这比不可读的窄条要好。

不要将字标裁剪为正方形。裁剪会留下半个单词，这不再是他们的商标。

当品牌指南覆盖一切时

某些客户拥有严格的配色方案，不会遵循我们的任何主题。custom_css 在品牌变量之后注入，因此纯声明已经获胜——无需 !important。（以前是必需的，因为颜色是作为内联样式设置的。现在不是了。）

⚠️ 在编写任何 CSS 之前阅读此内容

你必须编写两个块：:root 用于浅色，html[data-theme="dark"] 用于深色。

:root 在两种主题中匹配，并胜过平台的深色规则（特异性相同，且你的规则在后面）。因此，仅在 :root 下编写的配色方案意味着访问者的浅色/深色切换根本不会改变任何东西——data-theme 翻转，但没有变量跟随它。

这已经在生产中发生过：一个 agent 在 :root 下放置了完整的深色配色方案，页面看起来很棒，主题按钮变成了一个无人注意的无效控件长达数周。页面看起来是正确的，这正是它未被报告的原因。

如果客户确实只想要一种主题，请将 share 的 theme 字段设置为 light 或 dark。这会隐藏切换按钮，而不是破坏它。

正确的形状——复制此内容并替换值：

/* LIGHT — the light values go here, not the dark ones */
:root{
  --acc: #6b21a8;        /* brand primary — backgrounds, focus rings */
  --acc-fg: #ffffff;     /* text on --acc: YOU own the contrast here */
  --acc-text-l: #581c87; /* brand colour used as text, light theme */
  --bg: #fdfbff;
  --surface: #ffffff;
  --text: #1e1b2e;
  --border: #e6e0f0;
}
/* DARK — required whenever you touched --bg / --surface / --text above */
html[data-theme="dark"]{
  --acc: #a855f7;
  --acc-fg: #1a0b2e;
  --acc-text-d: #c084fc; /* note: -d, the dark-theme variant */
  --bg: #120c1d;
  --surface: #1c142b;
  --text: #f0e9ff;
  --border: #32254a;
}

这是值得覆盖的完整集合——小部件故意使用很少的颜色。

哪些变量需要深色块？描述表面的变量，因为它们会在主题之间反转：--bg、--surface、--text、--border。--acc 是品牌颜色，通常在两种主题中保持不变，尽管示例中为了深色主题将其调亮，因为深紫色在接近黑色的背景上很难看清。

另外两件事要记住：

• custom_css 不提供可读性保证。 theme_color 提供。仅针对派生无法表达的内容使用 CSS，并保持 theme_color 设置为基线。
• 将 --acc-text-l 和 --acc-text-d 设置为相同的值会使其目的失效。 它们的存在正是为了让品牌颜色在相反的背景上作为文本可读。

configure_share 在检测到单个 :root 错误时会返回 warnings 数组——阅读它。控制台在 CSS 编辑器旁边显示相同的警告。

css_url 加载外部样式表，供保留自己主题文件的客户使用。

你的颜色驱动的交互控件

聊天中的每个强调色控件都读取相同的一对——背景 --acc，文本 --acc-fg：

选中行自带样式——品牌色边框、行后 10% 品牌色调，以及使用 accent-color 绘制的原生控件——全部由 --acc 驱动，因此设置 theme_color 再次成为全部工作。语音按钮的录制发光同样派生自 --acc（通过 color-mix 在 22%/55% alpha），因此它会自动以品牌色脉冲；仅在 custom_css 中覆盖它以进行不同的处理：

/* softer, wider recording glow — both themes if you also touch surfaces */
:root .ca-talk.rec{
  box-shadow: 0 0 0 3px color-mix(in srgb, var(--acc) 15%, transparent),
              0 0 40px color-mix(in srgb, var(--acc) 40%, transparent);
}

仅当品牌指南要求不同的处理时才使用 CSS：

/* stronger selected state, both themes (remember the two-block rule above) */
:root .ca-form label:has(input:checked){
  border-color: var(--acc);
  background: color-mix(in srgb, var(--acc) 18%, transparent);
  font-weight: 600;
}
html[data-theme="dark"] .ca-form label:has(input:checked){
  background: color-mix(in srgb, var(--acc) 24%, transparent);
}

保持所有可读性的规则：任何你用 --acc 绘制的东西都从 --acc-fg 获取其文本——而不是字面颜色。 经典的失败是在深色块中将 --acc 覆盖为浅色品牌黄色，并保留白色文本：ask-form 按钮变为黄色背景上的白色文本，对比度为 1.8:1，客户报告“深色模式下表单按钮不可读”。如果你在 custom_css 中覆盖 --acc，你必须在同一块、两种主题中拥有 --acc-fg——或者更好，不要为此使用 CSS：设置 theme_color，平台会为你派生一个合规的 --acc-fg。

使聊天可安装 (PWA)

独立聊天页面（/s/… 链接、二维码和下面的别名 URL）是可安装的应用：访问者可以将它们添加到主屏幕，使用你自己的图标和名称。两个旋钮，配置每个 agent——安装到主屏幕的是该 agent 的入口页面，因此每个 agent 都是具有自己图标的应用（支持智能体和售前智能体安装为两个不同的应用）：

set_pwa_branding(
  agent="support",                                                # which agent's install branding
  icon_source_url="https://cdn.example.com/brand/mark-1024.png",  # ONE square master image ≥192×192
  install_prompt="banner",                                        # banner (default) | card | off
)

• 主图像仅获取一次，平台生成整个集合——浏览器标签 favicon、192/512 安装图标和 Android 可屏蔽变体。非正方形主图像居中裁剪，因此使用正方形标记，而不是宽幅字标。
• install_prompt 控制访问者在聊天页面上看到的内容：banner 是一个可关闭的窄条（Android/Chrome 触发系统安装对话框；iOS 获得“分享 → 添加到主屏幕”引导，因为 Apple 不提供 API），card 是更可见的首次访问卡片，off 禁用邀请。关闭状态按访问者记住。
• 图标是可选的——没有它们则使用平台图标。仅使用 agent 名称调用以读取该 agent 的当前配置。

你交给人的链接

当租户别名和 agent 别名都设置时，create_share / list_shares 返回一个 pretty_url——https://chat.agent4.io/t/<tenant-alias>/<agent-alias>。这是给人看的链接并印在材料上： 易读、易记，并且它幸存于 token 轮换（平台在其后懒惰地维护一个 share）。/s/<token> 形式仍用于嵌入和机器。

响应中没有 pretty_url？别名未设置——修复它而不是发送 token 链接：通过 create_agent(alias=…) 或 PUT /agents/{name}/alias 设置 agent 别名；租户别名位于控制台 → 设置。设置 agent 的别名本身就是一个发布操作：别名页面在首次访问时自动创建匿名 share。

客户自己的域名

托管聊天页面可以在客户的域名上提供服务——https://chat.client.com/ 显示他们的品牌页面，证书自动颁发。

set_custom_domain(domain="chat.client.com", agent_alias="menu")
# → { status: "pending", cname_target: "endpoint.agent4.io", last_error: "…" }

顺序很重要，并且它是异步的：

1. 告诉客户在响应中的 cname_target (endpoint.agent4.io) 从他们的子域添加 CNAME。仅限子域—— apex 域 (client.com) 不能采用 CNAME；让他们使用 chat.client.com，或使用具有 CNAME 展平的 DNS 提供商。
2. 在 Cloudflare 上，记录必须是 DNS 仅（灰云）。 智能体记录解析为 Cloudflare 的 IP 并导致验证失败——last_error 明确说明，带有观察到的地址。这是最常见的失败；在猜测之前阅读 last_error。
3. 验证每 10 分钟自动重新运行；再次调用 set_custom_domain（相同参数）或检查 tenant_info() 以查看当前状态。active 表示在线——首次访问颁发证书。

每个工作区一个域。agent_alias 为空落在租户的品牌页面上；设置它直接落在一个 agent 的聊天上。现有的 chat.agent4.io 链接继续工作——这是额外的入口，而不是替换——聊天身份是按域的：访问者在 chat.agent4.io 上的历史不会跟随他们到自定义域。

需要包含自定义域的计划（403 = 租户需要升级）。

对话搜索模态框 (Spotlight)

独立页面和网络客户端都有 ⌘K 对话搜索。它自动遵循品牌——模态框读取与其他所有内容相同的变量（--surface、--border、--text、--muted、--overlay、--surface-hover、--accent-soft，以及用于高亮匹配的 --acc-text 对）——因此设置 theme_color 在这里也是全部工作。

对于需要更多的品牌指南，类名是稳定的，custom_css 胜过组件自己的样式：

/* rounder panel, brand-tinted selected row — remember the two-block rule above */
:root{ }
.ca-ss{ border-radius: 20px; }
.ca-ss-item.sel{ background: color-mix(in srgb, var(--acc) 10%, transparent); }
html[data-theme="dark"] .ca-ss-item.sel{ background: color-mix(in srgb, var(--acc) 16%, transparent); }

与 everywhere 一样：两主题规则在你触及表面颜色时适用，纯声明获胜——无需 !important。

表单控件和本地日期选择器

Ask-form 输入 (.ca-form input.cain) 和对话框输入 (.ca-in) 是 token 样式的——表面、文本、边框和强调焦点环都遵循主题和你的 theme_color。系统对话框（重命名/确认）共享 Spotlight 处理：磨砂背景、呼吸式提升、深色中的品牌发光。

日历是混合的。 在桌面（鼠标）上，平台绘制自己的日历——完全 token 样式化，品牌色选中的日期，本地化的月/星期名称——稳定选择器 .ca-dp、.ca-dp-d、.ca-dp-d.sel、.ca-dp-d.today 如果品牌指南需要更多。在触摸设备上，原生 OS 选择器被故意保留：移动轮子胜过网页中绘制的任何东西，并且其面板是 OS 私有 UI，CSS 无法触及——在那里，平台控制可触及的内容（主题固定的 color-scheme、token 样式的输入字段、反转的日历图标）和 nothing more exists to control。

限制你的元素选择器。 裸 input[type="text"] { … } 为 composer 编写也会捕获平台的对话框和表单字段——白色 composer 样式渗入深色重命名对话框是经典症状，CSS lint 现在标记它 (broad_element_selector)。改为编写 .composer textarea 或 #input。系统对话框具有更高的特异性，因此事故不再发生——但 lint 在你依赖事故之前告诉你。

share 上还有

• input_mode —— text（默认）或 voice，直接打开按住说话。需要在平台上启用语音转文本后端。
• launcher —— 气泡的悬停工具提示。
• theme —— 强制 light / dark，或留空以跟随访问者的系统设置。首选空：小部件位于客户页面内，应与之匹配。

验证

打开 list_shares 中的 chat_url 并查看发送按钮。如果标签难以阅读，theme_color 未设置，并且某些内容正在覆盖它——检查 custom_css 中的硬编码 color。