Primitiv 是一个设计系统基础设施，旨在让团队和 AI 编码代理保持同步。其核心理念是：检索提供数据，而协调（reconciliation）提供真相。设计系统知识通常分散在代码、Figma、Storybook 和文档中，当这些来源发生漂移时，人类依靠经验协调差异，而 AI 编码代理往往退回到通用模式，这些模式虽然可用但不属于产品。Primitiv 通过机器可读的契约和只读 MCP 接口，为每个代理提供相同且最新的设计上下文，帮助代理复用已有内容、遵循既定决策，并在发布前暴露不一致之处。
主要能力包括：将代码库、Figma 和 Storybook 中的设计上下文整合在一起；使现有令牌、组件、规则和理由可供代理使用；暴露冲突、漂移和硬编码令牌误用；为兼容 MCP 的代理和编辑器提供只读访问；在 CI 中验证契约是否保持最新。
使用方式：在项目根目录运行命令。init 为当前项目设置 Primitiv，build 创建其设计契约，serve 使该契约可供兼容 MCP 的代理使用。建议在项目级别配置 Primitiv，因为全局 MCP 配置在切换仓库时可能提供错误项目的契约。
Primitiv 还会根据每个代码库组件的完整有限属性域检查本地 JSX 用法。已知的域外值会产生待处理的源内冲突，即使在自动解决模式下也是如此。对齐 JSX 用法或扩大声明的域即可解决。warn 报告这些冲突而不阻塞；error 和 verify --strict 以代码 2 退出。动态值和不完整的域保持未知。
当组件证据无法比较时，primitiv verify 会报告简短的诊断摘要。使用 primitiv verify --verbose 查看原因，或使用 --json 获取结构化报告。诊断解释不确定性，不计为冲突或直接导致验证失败；但对它们的更改仍可能使保存的契约过期。--fast 报告已保存的诊断而不是重新构建它们。代理可以在 MCP 摘要中读取诊断计数，并通过 get_design_context 使用 category: "diagnostics" 分页获取详细信息。
在 CI 中检测组件漂移：对保存的契约运行 primitiv verify，检查声明的属性事实、有限变体值、观察到的 JSX 值以及组件关系。验证还会比较 Storybook 默认参数、故事参数和控制选项，包括映射值。故事标签和其他展示元数据不计为 API 漂移。观察和示例描述静态源证据，而非运行时频率或破坏性变更严重程度。例如，将 Button 用法从 size="sm" 改为 size="lg" 即使 JSX 站点数量不变也会被检测到。漂移消息标识组件 ID 和字段路径，如 components/Button 和 usage.props.size。
正常验证在内存中扫描当前源，并使用其当前冲突进行报告和治理。引入或修复域外 JSX 值会立即在验证中生效。保存的契约仍是漂移基线，验证永远不会重写它：运行 primitiv build 刷新它，然后再次验证。MCP 继续提供保存的契约，直到它被重建并重新加载。
失败的源以及不完整或截断的证据无法证明不可用的事实已被移除或冲突已解决。验证报告可用的更改和比较不确定性。较旧的契约仍可读；新可用的证据会使它们过期，直到重建。
过期证据以代码 1 退出，在 --strict 下以代码 2 退出。待处理的冲突在 error 治理或 --strict 下以代码 2 退出；仅警告冲突不会独立导致验证失败。--fast 使用保存的发现和文件修改时间，而不是扫描当前 API 证据，因此请在 CI 中使用正常验证。使用 --json 获取验证结果，使用 --verbose 获取比较诊断详情。
Primitiv 在本地运行，代码永远不会离开用户的机器。项目采用 Apache-2.0 许可证。
