danielrandolph/compass-payload-plugin

# Compass **一款让网站持续保持品牌一致性的 Payload CMS 插件。** Compass 会监控基于 Payload 驱动的网站，并根据**品牌本体**（brand ontology）和**设计系统 agent**（通过模拟的 Figma MCP 连接）对其进行检查。当某些内容偏离品牌规范时，它会在 Payload 管理后台和线上站点直接将其标记出来，并提供一键修复功能。 它回答了品牌所有者真正关心的两个问题： 1. **营销团队是否保持了品牌一致性？**（内容与本体语调的对比） 2. **工程师是否按规范开发？**（代码中的 token 和资产与 Figma 设计系统的对比） ## 截图 **Compass 仪表板** —— 实时品牌评分（“营销是否符合品牌？”/“工程师是否符合规范？”）、设计系统 agent 连接状态，以及所有带有一键修复功能的未解决发现。  **发现集合** —— 包含严重程度、来源和段落锚点的完整标记历史记录。可以选择解决或忽略以消除标记。  **实时状态** —— （模拟的）Figma agent 连接状态、规范版本和评分，每次扫描都会刷新。  ## 功能介绍 - **持续检查。** 扫描会按间隔运行、按需运行，并且（对于 CMS 内容）在页面保存的瞬间运行。 - **双重界面。** 发现的结果会出现在 **Compass** 管理仪表板中，*并且*在实时页面上显示为**固定在确切元素上的可点击标记**：偏离的 token 色板、不符合品牌规范的照片图块、甚至是不符合品牌规范的词语本身。仅限管理员可见，对公众不可见。 - **提交 PR。** 每个发现都有一个修复操作。Compass 会编辑唯一的真实数据源（CSS token、文案、不符合品牌规范的资产），然后重新扫描，以便您眼前的标记被清除。 - **本体驱动。** 规则是从机器可读的品牌本体（语调、颜色 token、排版、摄影、Logo 组合）中提炼出来的。 - **Figma 设计系统 agent（模拟）。** 一个模拟的 MCP 客户端返回已批准的 token、照片集和组件规范，其格式与真实的 Figma agent 完全一致，因此可以将编写的网站代码与“Figma 的要求”进行差异对比。 ``` flowchart LR A["Figma agent (MCP, simulated)"] -->|approved tokens, photos, specs| S[Compass scan] O[Brand ontology rules] --> S C[CMS content afterChange] --> S P["Coded site: globals.css + page.tsx"] --> S S --> F[(brandFindings)] F --> D[Admin dashboard] F --> V[On-site flags] V -->|Submit PR| X[Edit source + re-scan] X --> S ``` ## 它能捕获（并修复）的内容 | 检查项目 | 发现示例 | 修复操作 | |---|---|---| | **语调/词汇** | 标题中的“cutting-edge”；破折号；夸大的宣传语（“#1”） | 替换为质朴、符合品牌规范的词语/标点符号 | | **颜色 token 偏移** | 代码中的 `--hd-orange` 为 `#ff5a16`，而 Figma 中为 `#ff4b16` | 将 Figma 中的数值写回 CSS | | **超出调色板颜色** | 页面中出现非品牌 token 的原始十六进制颜色值 | 吸附到最近的已批准 token | | **不符合品牌规范的藏青色** | 使用 `#0e1929` 作为深色表面 | 替换为 Ink `#0c0a09` | | **等宽字体** | 在任何地方使用了 `font-mono` | 移除它 | | **不符合品牌规范的照片** | 不在 Figma 批准图库中的摆拍企业库存照片 | 从页面中**移除**它 | | **Logo 组合** | 文字标志和 H-字母组合并排放置 | （手动）仅使用文字标志 | 每个发现都会标记严重程度、来源（营销还是工程）、本体规则 ID、期望值与实际值对比，并且如果它位于页面上，还会带有一个段落锚点，以便站点上的标记可以指向它。 ### 元素级别的标记固定 覆盖层会将每个标记固定在它能找到的最具体的元素上，如果找不到，则回退到段落角落： | 发现 | 固定于 | 定位方式 | |---|---|---| | 不符合品牌规范的照片 | 照片图块本身 | 内联样式或 `img src` 引用了该文件名的元素 | | Token 偏移 | 代表该 token 的色板 | 带有 `data-brand-token="--hd-orange"` 标签的元素（将其添加到您的色板中） | | 不符合品牌规范的词语 | 悬浮在文本行正上方的词语 | 遍历该段落的文本节点，并在完全匹配的内容上构建 DOM Range | | 其他所有情况 | 段落的右上角 | 发现结果的段落锚点 ID | ## 工作原理 Compass 是一个标准的 Payload 插件：一个改变配置的函数 `compass(options) => (config) => config`。它添加了： - 一个 **`brandFindings`** 集合（历史记录、解决/忽略）和一个 **`brand-sync`** global（实时评分 + MCP 状态）； - **endpoints** `POST /api/brand-guard/scan`、`POST /api/brand-guard/fix`、`GET /api/brand-guard/summary`、`GET /api/brand-guard/findings`； - 在内容集合上添加了 **`afterChange`** 钩子（营销路径）； - 通过封装的 `onInit` 实现**间隔扫描**（工程路径）； - 一个 **`beforeDashboard`** 管理面板； - 一个导出的 **`BrandGuardOverlay`** 客户端组件，用于在站点上显示标记。 扫描是幂等的：每次运行都会根据范围核对发现结果，因此重新扫描只会产生新的偏移，保留仍然存在的问题，删除已修复的内容，并且永远不会重新打开您已解决或忽略的问题。 ### 设计上的确定性 每次检查都是确定性的，扫描时不涉及 API 密钥、网络请求或 LLM： - **内容**检查是对提取文案的启发式处理（具有否定感知能力的禁用词汇、破折号、夸大宣传模式、全大写、感叹号滥用）。 - **设计**检查从 `globals.css` 和页面源码中解析真实的代码 token，并将它们与模拟 Figma agent 报告的内容进行差异对比。 - **Figma MCP 是模拟的**（`mock-figma-mcp.ts`）：它模仿 MCP 的 `connect()` + `callTool()` 握手，并返回标准的 token / 批准的照片集。在 UI 中清楚地标有“模拟”字样。 ## 文件映射 ``` src/ index.ts Plugin entry: wires collection, global, hooks, endpoints, dashboard, interval types.ts Finding + option types brand-rules.ts Ontology-derived rules (tokens, banned terms, approved photos, rule ids) mock-figma-mcp.ts Simulated Figma agent MCP client scan-runner.ts Orchestrates checks, reconciles findings, writes the status global fixer.ts The "agent" fix engine (edits the source of truth) util.ts Fingerprints + text extraction checks/ content-check.ts Voice / lexicon heuristics design-check.ts globals.css tokens vs Figma page-source-check.ts Per-section scan (anchored): off-palette hex, photos, logo lockup collections/BrandFindings.ts globals/BrandSync.ts endpoints/index.ts scan / fix / summary / findings admin/BrandDashboard.tsx Admin panel (client component) client.tsx BrandGuardOverlay: the on-site flags (admin-gated) ``` ## 用法 ``` // payload.config.ts import { brandGuardPlugin } from 'compass-payload-plugin' export default buildConfig({ // ... plugins: [ brandGuardPlugin({ contentCollections: ['pages', 'posts'], // afterChange content checks scanIntervalMs: 60_000, // engineering interval scan }), ], }) ``` 注册管理面板（通过您的 import map）并在前端挂载覆盖层： ``` // app/(frontend)/layout.tsx import { BrandGuardOverlay } from 'compass-payload-plugin/client' // ... ``` ### 选项 | 选项 | 默认值 | 描述 | |---|---|---| | `contentCollections` | `['pages','posts']` | 保存时检查的集合 | | `scanIntervalMs` | `60000` | 全局扫描之间的间隔（0 表示禁用） | | `enabled` | `true` | 总开关 | ## 原型说明（实际范围） 这是一个针对特定演示构建的有效原型，而非通用版本： - **Figma MCP 是模拟的**，检查引擎是**确定性启发式算法**（没有实时的 Figma，也没有 LLM）。其接缝是真实的 MCP 结构，因此替换为真实的 Figma agent 或 LLM 评估器只需直接插入即可。 - 设计/照片/Logo 检查会从演示宿主应用（`src/app/(frontend)/globals.css` 和 `page.tsx`）中读取文件。将这些通用化为可配置路径/任意集合是显而易见的下一步。 - `brand-rules.ts` 中的规则是完整的 Handled 品牌本体的提炼子集。 ## 技术 Payload 3、Next.js 16、React 19、TypeScript。自身没有运行时依赖（Payload 和 React 是对等依赖）。 ## 许可证 MIT © Daniel Randolph

标签：CMS插件, MCP, Payload CMS, 品牌管理, 自动化审查, 自动化攻击, 设计系统