企业官网建设流程全解析

第三方 Harness 品牌标识的合规打包与运行时图标管线：Buzz 桌面端 harness-logos 溯源体系解析

【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz

本篇技术指南围绕 Buzz 桌面端desktop/public/harness-logos/CREDITS.md溯源清单展开，系统讲解它如何为"运行画廊"（runtime gallery）中出现的第三方预设 Harness 品牌标识（Devin、Grok、Kimi、Goose、Cursor 等）建立来源—提交—许可证—修改记录四要素档案，并结合 RuntimeIcon.tsx、HarnessMarks.tsx、presetLogos.test.mjs 与后端 presets.rs 还原完整的"文件型标识 + 内联单色标识 + 兜底字形"三层渲染管线，以及防止跨语言漂移的自动化覆盖测试。读完你将掌握：如何在产品中合规地打包第三方商标、如何用currentColor实现深浅主题自适应的单色标识、以及如何用测试守护资产清单与磁盘文件的一致性。

一、背景与定位：运行时画廊里的"第二梯队"标识从何而来

Buzz 桌面端允许用户接入多种 ACP（Agent Client Protocol）运行时作为 Harness。除了内置（builtin）运行时与用户自定义 Harness 之外，还有一批**预置（tier-2 preset）**Harness——由后端静态注册、前端内置标识。它们出现在设置页"Your runtimes"列表与引导流程的运行时选择界面中。

由于这些标识（logo/mark）是第三方厂商的商标，Buzz 不能像对待自研 UI 素材一样随意打包，必须满足两个前提：

1. 仅在"指名使用（nominative use）"范围内使用——每个标识只用于指代其所属厂商自己的 Harness（例如 Devin 的标识只出现在 Devin 行上），不暗示背书或关联；
2. 只打包上游许可证明确允许再分发（redistribution）的标识——这直接决定了哪些标识能随应用分发、哪些必须放弃。

CREDITS.md正是这一策略的落地档案：它逐行记录每个被打包标识的上游来源、提交版本/获取日期、许可证、源文件路径、本地修改，并明确约定"新增一个预设标识时必须在此加一行"（Add a row here when adding a preset logo）。这份文件与 RuntimeIcon.tsx 中定义的PRESET_LOGOS一一对应，构成资产清单的"单一事实来源"。

二、两条资产管线：文件型标识与内联单色标识

从源码看，运行时图标的渲染并不只有一个数据源，而是分为两个互补的注册表，CREDITS.md也按此分两节记录。

2.1 文件型预设标识（public/harness-logos/下的位图/SVG 文件）

RuntimeIcon.tsx中通过公共路径引用这些文件，键名与后端PRESET_HARNESSES发射的预设id保持一致：

export const PRESET_LOGOS: Record<string, string> = { devin: "/harness-logos/devin.svg", omp: "/harness-logos/omp.svg", pi: "/harness-logos/pi.svg", grok: "/harness-logos/grok.svg", opencode: "/harness-logos/opencode.svg", kimi: "/harness-logos/kimi.png", amp: "/harness-logos/amp.png", hermes: "/harness-logos/hermes.png", openclaw: "/harness-logos/openclaw.svg", };

CREDITS.md第一张表记录了其中 7 个"可溯源"文件的完整档案（amp.png、opencode.svg因早于本文件存在、溯源缺失，单独说明，见后文）：

从该表可以提炼出三个可复用的操作规范：

• 锁定提交而非"最新版"：除商标类素材（Devin、Grok 按官方文档/品牌指南获取并记录日期）外，每个 MIT/Apache 资产都记录到具体 commit 哈希，保证可复现、可审计；
• 修改必须可验证：openclaw.svg移除 SMIL 动画后标注"与上游 t=0 帧逐像素一致"，说明任何修改都不是随意的视觉加工，而是有验证手段的工程决策；
• 特殊配色单独兜底：在渲染端，RuntimeIcon.tsx对omp和grok两个深色标识分别加了bg-[#0d0d0d] p-1与bg-white p-1的背景/内边距处理，让深色 logo 在浅色/深色主题下都有正确的观感——这与devin.svg的"白底方形画布"修改异曲同工。

2.2 内联单色标识（RUNTIME_MARKS）

第二张表记录的是以currentColor路径内联在 HarnessMarks.tsx 中的单色标识，不占用public/目录、不需要请求文件：

currentColor的妙处在于：内联 SVG 的填充色跟随 CSScolor，因此深浅主题切换时无需位图滤镜（brightness/invert）就能自动适配——这正是 HarnessMarks.tsx 顶部注释所强调的设计动机，也解释了为什么 Goose/Cursor 选择内联路径而非 PNG 文件。渲染优先级上，RuntimeIcon先查RUNTIME_MARKS（取到即渲染内联 SVG），再回落到位图映射表。

2.3 Codex 的"刻意缺席"

CREDITS.md特别说明：Codex 有意不打包任何标识。原因是 OpenAI 的花形标识（blossom）已在厂商要求下从 simple-icons v16 中移除，因此 Buzz 不随应用分发该标识，Codex 在画廊中渲染的是RuntimeIcon的中性终端字形兜底（TerminalSquare）。这是一个值得注意的合规姿态：厂商撤回分发的标识，宁可显示通用兜底，也不重新打包。该决策同时被测试固化为硬性断言（见第五节）。

三、三层渲染管线：从后端静态注册到前端兜底字形

要理解CREDITS.md记录的资产如何被真正使用，需要看完整的分发链路：

1. 后端注册：desktop/src-tauri/src/managed_agents/discovery/presets.rs中的PRESET_HARNESSES静态数组定义了 10 个预置 Harness（pi、devin、cursor、omp、grok、opencode、kimi、amp、hermes、openclaw），每个都带有id、label、command、args、安装提示与安装指引 URL，并由preset_catalog_entry结合 PATH 探测生成运行时目录条目（AcpRuntimeCatalogEntry）。值得注意的是，预置条目的avatar_url被显式置空（No remote URL — all preset icons are bundled assets）。
2. 前端查表：RuntimeIcon按runtime.id依次解析——Buzz 自身运行时渲染BuzzMark；命中RUNTIME_MARKS渲染内联单色标识；命中PRESET_LOGOS/RUNTIME_LOGOS（claude走内联 base64）渲染<img>；全部未命中则回落到TerminalSquare通用字形。
3. 安全红线：RuntimeIcon.tsx注释明确写着——only use bundled logo maps — never render user-supplied avatar URLs for custom/preset entries。这意味着图标管线绝不加载用户提供的头像 URL，从根源上杜绝了利用运行时头像做追踪像素或仿冒标识的攻击向量。设置页 HarnessRow.tsx 中的RuntimeLogo也复用同一RuntimeIcon（注释强调RuntimeIcon owns every runtime asset），保证"医生页"与目录页图标永不漂移。

四、自动化守护：presetLogos.test.mjs如何防住跨语言漂移

资产清单的双方分别住在不同语言里——Rust 侧的PRESET_HARNESSES与 TS 侧的PRESET_LOGOS，编译器无法发现二者不同步；而RuntimeIcon的onError回退又会在运行时悄悄掩盖缺失文件。为此 presetLogos.test.mjs 采用"把 Rust 源码当文本读"的技巧（与项目内motion.test.mjs处理 CSS 的思路一致），从presets.rs中正则提取PRESET_HARNESSES的全部id，然后做四类断言：

1. 解析守卫：先断言至少解析出 8 个预置 id，防止正则本身因结构重命名而静默失效、导致后续断言"空洞通过"；
2. 覆盖断言：每个预置 id 必须有RUNTIME_MARKS或PRESET_LOGOS条目——取不到就断言失败，并提示应在desktop/public/harness-logos/下补文件、在RuntimeIcon.tsx中注册映射；
3. 磁盘存在性：PRESET_LOGOS[id]指向的路径必须真实存在于desktop/public下（existsSync），否则onError会静默回退，列表里就会出现"一个真实标识旁边混着通用字形"的观感缺陷；
4. 未知 id 与 Codex 守卫：PRESET_LOGOS不得出现后端未发射的 id；且RUNTIME_MARKS.codex、PRESET_LOGOS.codex都必须为undefined（assert.equal(..., undefined)），把"Codex 不带标识"从口头约定固化为 CI 级硬约束。

五、历史清理与演进原则：不可溯源的资产一律移除

CREDITS.md后半部分记录了一次"合规清仓"，是理解这份文件价值的点睛之笔：

• amp.png与opencode.svg早于本文件存在，溯源未被记录，文件如实标注这一缺口（未作追溯性编造）；
• Cursor 此前因自身品牌页不授予再分发权而一直显示通用终端兜底，后来借助 simple-icons 的 CC0-1.0 路径数据解决，与 Grok 的"指名使用"先例保持一致；
• 此前无证明来源的cursor.png被移除，未获证明的chatgpt.png、goose.png内置运行时位图也被移除，分别由内联标识替代。

由此可以归纳出本项目的资产治理原则："许可证可再分发 + 溯源可记录"缺一不可，历史遗留的未溯源资产宁可删除，也不在档案缺失的状态下继续分发。

六、给贡献者：新增一个预设标识的标准操作

综合CREDITS.md的约定与源码、测试的约束，为 Buzz 新增一个预设 Harness 标识需要走完以下流程：

1. 确认许可：先确认上游许可证允许再分发，仅此一条不满足就应放弃打包（参考 Codex 的处理方式）；
2. 登记档案：在 CREDITS.md 表格中追加一行，完整填写 File、Upstream、Commit（或获取日期）、License、Source path、Modifications 六列——这是文件开头明确写死的流程要求（Add a row here when adding a preset logo）；
3. 落地资产：把处理好的文件放入desktop/public/harness-logos/（单色标识则内联进 HarnessMarks.tsx 并加入RUNTIME_MARKS）；
4. 注册映射：在 RuntimeIcon.tsx 的PRESET_LOGOS中按后端id键登记公共路径；
5. 验证通过：确保 presetLogos.test.mjs 的全部断言通过（覆盖、磁盘存在、无未知 id），且不触碰 Codex 守卫。

结语

CREDITS.md表面上只是一张出处表，实际承载的是一套完整的第三方商标资产治理方法论：指名使用的边界、按提交锁定的可复现性、可验证的修改记录、currentColor驱动的主题自适应、测试固化的防漂移护栏，以及"宁可兜底也不越权分发"的合规底线。对于任何需要在产品中内置第三方品牌标识的团队，这份文件连同 RuntimeIcon.tsx、presetLogos.test.mjs 构成的组合，是一份可直接借鉴的工程范本。

【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz