在很多团队里，多端协作的主要问题是“同一个需求被翻译了多少次”。最典型的场景是：Web 一套实现，Flutter 一套实现，H5 和小程序又各有一套适配逻辑。产品提一个需求，设计讲一遍，前端理解一遍，Flutter 再理解一遍，最后各端虽然都“做出来了”，但视觉、交互、状态处理、权限逻辑、埋点口径往往并不一致。沟通成本高、返工频繁、质量不稳定。
如果团队还希望进一步引入 AI 辅助开发，那么问题会更明显。因为 AI 并不能天然理解团队的设计语言、组件规范、页面模式和业务边界。如果没有一套结构化、可检索、可校验的规范体系，大模型生成的结果往往只能做“演示代码”，无法真正进入工程体系。
因此，真正有效的多端技术方案，不应该只是“做一套 Design Token”，也不应该只是“尝试一套代码通吃所有端”。更合理的思路是： 先统一设计语言，再统一组件协议和页面模式，继续沉淀业务规范，最后把这些规范结构化，供大模型参与生成、校验和辅助开发。 规范不是靠发文件落地的，是靠‘让别人用起来更省事’落地的。
一、问题到底出在哪里
很多团队一提多端一致性，第一反应是颜色、字号、间距不一致。但这其实只是表层问题。真正让协作成本变高的，通常是下面几类问题。
第一类，是需求翻译成本。同一个“企业洞察页”需求，Web 理解为信息卡 + 图表 + 推荐列表，Flutter 可能理解为信息页 + Tab + 卡片流，结果做出来像两个产品。
第二类，是组件行为不一致。同样一个按钮，Web 支持 loading 态并禁止重复点击，Flutter 可能只有 disabled；同样一个空态页，Web 有引导操作，Flutter 只有一段提示文案。
第三类，是状态模型不一致。正常态大家都能做，但 loading、empty、error、no-permission、offline、partial-error 这些状态，经常每个端各自发挥。
第四类，是数据与规则不一致。接口字段解释不同，权限判断方式不同，埋点参数命名不同，最后统计口径都不一样。
第五类，是AI 无法真正接入工程体系。设计规范写在 PPT 里，组件约定写在 Confluence 里，业务规则散落在需求文档里，大模型拿不到稳定的 source of truth，自然无法参与受控生成。
所以，多端一致性不是一个“视觉层优化”问题，而是一个从需求到实现的翻译层重构问题。
二、方案总览：统一语义，而不是强行统一实现
这套方案的核心原则很简单：
统一语义，不强行统一实现。
Web、H5、小程序、Flutter 的渲染机制、组件生态和交互能力都不一样，硬要一套代码跑所有端，通常只会让所有端都不舒服。真正应该统一的，是下面这些层：
- Design Token：统一设计语言
- 组件 Contract：统一组件语义和行为
- 状态矩阵与页面 Pattern：统一交互模式
- 业务 Spec / Contract / Schema：统一需求表达
- 工程化与校验链路：统一交付方式
- Agent 接入层：统一 AI 辅助方式
可以把整个方案理解成这样一条链路：
设计源头 → Token → 组件协议 → 页面模式 → 业务规范 → 结构化规则 → 多端实现 → AI 生成与校验
这不是单点优化，而是一套可以逐步演进的前端基础设施。
三、Design Token 是基础，但不能停在这里
Design Token 解决的是“设计值如何被标准化和跨端传递”的问题。它是多端一致性的起点，但绝不是终点。
在实现上，我推荐把 Token 分成三层：
1. Primitive Token：原始值层
这是最底层的设计原材料，比如：
{
"color": {
"blue": { "500": "#2F6BFF" },
"gray": { "900": "#111827" }
},
"space": {
"8": "8px",
"16": "16px"
},
"radius": {
"4": "4px"
}
}
这一层回答的是“具体数值是多少”，适合设计系统维护者和构建脚本使用，不应该直接暴露给业务页面。
2. Semantic Token：语义层
语义层把原始值转成产品语言，例如：
{
"color-text-primary": "{color.gray.900}",
"color-bg-surface-card": "{color.white}",
"space-page-section-gap": "{space.16}"
}
这一层回答的是“这个值在界面里扮演什么角色”。它是跨端最值得统一的一层，也是页面开发默认应该使用的一层。
3. Component Token：组件层
组件层是组件内部的状态和部位规则，例如：
{
"button-primary-bg-default": "{color-bg-brand-primary}",
"button-primary-bg-hover": "{color.blue.600}",
"input-border-focus": "{color-border-focus}"
}
这一层回答的是“某个组件在某种状态下应该怎么表现”，适合组件库内部实现，不建议业务页面直接使用。
为什么要这么分层
因为业务页面真正关心的是“主文本”“卡片背景”“页面间距”，而不是 blue-500 或 button-primary-bg-hover 这种底层细节。
所以一个健康的约束应该是：
- 定义基础值，用 Primitive
- 写页面布局，用 Semantic
- 做组件实现，用 Component
对于多端来说，最应该统一的是 Semantic Token 命名和语义，而不是强求每个平台完全共享底层实现。Web 可以映射到 CSS Variables，Flutter 可以映射到 ThemeData，小程序可以做裁剪版映射。统一的是产品语言，不是渲染机制。
四、比 Token 更重要的是组件 Contract
如果说 Token 解决的是“长得像不像”，那么 Component Contract 解决的是“行为是不是同一套”。
这里的 contract，是组件层面的“协议”或“契约”。它定义的是一个组件的输入、输出、状态、行为和边界。
以 Button 为例，一个合格的 Button contract 至少应该包含这些内容：
- 支持哪些 variant：primary / secondary / text
- 支持哪些尺寸：sm / md / lg
- 支持哪些状态：default / loading / disabled
- loading 态是否禁止再次点击
- icon 支持哪些位置
- 文案最大长度建议
- 埋点何时触发
- 无障碍要求是什么
它可以写成这样的结构：
{
"component": "Button",
"variants": ["primary", "secondary", "text"],
"sizes": ["sm", "md", "lg"],
"states": {
"loading": { "disableClick": true },
"disabled": { "emitClick": false }
},
"iconPlacement": ["left", "right"],
"a11y": {
"requireLabel": true
}
}
一旦这份 contract 稳定下来，Web 和 Flutter 都可以按同一套语义实现，而不是各写各的。
这一步非常关键。因为很多团队做了 Token，却没有做 Contract，结果所有端看起来像一家人，但行为逻辑还是各自为战。
五、状态矩阵与页面 Pattern 才是多端协作的真正降本点
大部分返工，并不是因为某个颜色错了，而是因为状态和页面结构没有统一。
1. 状态矩阵
在 AI 产品和复杂 B 端产品里，页面状态往往远不止一个“加载中”。一个成熟的状态模型，至少要覆盖：
- loading
- refreshing
- empty
- partial-error
- full-error
- no-permission
- offline
- generating
- interrupted
状态矩阵不是为了写文档，而是为了让所有端都知道：同一个页面在不同状态下应该展示什么、隐藏什么、保留什么交互、是否允许重试。
2. 页面 Pattern
很多需求其实不是全新页面，而是“列表页”“详情页”“洞察页”“趋势页”“报告编辑页”“智能体配置页”的某种变体。
所以与其每次从零设计，不如沉淀页面 pattern library。每个 pattern 里定义：
- 页面区块组成
- 信息优先级
- 推荐组件组合
- 常见交互
- 状态切换方式
- 多端适配建议
例如“企业洞察页”可以规定：
- 顶部：企业基础信息卡
- 中部：趋势图 + 风险摘要
- 底部：相关推荐
- 高风险摘要必须带引用来源
- 导出按钮仅分析师可见
- loading 时骨架屏优先展示顶部和中部关键区域
一旦 pattern 稳定，同一个需求在 Web 和 Flutter 上的“翻译成本”就会下降很多。
六、把需求变成结构化规范，而不是散落的文档
到这里，多端协作已经不只是 UI 层问题了，必须往更高层抽象。
这里最容易混淆的三个概念是：spec、contract、schema。
1. Spec：整体规格说明
Spec 关注的是“这个需求整体要做成什么样”。它通常包括：
- 页面目标
- 页面结构
- 交互流程
- 状态处理
- 权限规则
- 埋点要求
- 验收标准
Spec 是完整说明书，适合给产品、设计、前后端和测试一起看。
2. Contract：边界约定
Contract 关注的是“边界两边如何对接”。它包括：
- API contract
- 组件 contract
- 事件埋点 contract
- 页面区块 contract
它强调的是输入、输出、状态、行为和边界。
3. Schema：数据结构定义
Schema 关注的是“数据长什么样”，比如：
- 字段名
- 字段类型
- 必填项
- 枚举值
- 嵌套关系
例如：
{
"companyName": "string",
"riskLevel": "low | medium | high",
"canExport": "boolean",
"tags": ["string"]
}
在工程里，可以粗略理解为：
Schema 是结构，Contract 是约定，Spec 是全局规则。
三者一起使用，才能真正把需求从“会讨论”变成“可执行”。
七、工程体系的重点不是复用代码，而是复用定义
到了工程层，很多团队会陷入一个误区：一说多端，就想“一套代码跑全部端”。
实际上，对 Web 和 Flutter 这样的异构平台来说，更现实的目标不是复用所有代码，而是复用定义、约束和生成链路。
一个比较健康的工程目录，可以是这样：
design-system/
tokens/
primitive.json
semantic.json
component.json
components/
button.contract.json
card.contract.json
input.contract.json
patterns/
insight-page.spec.md
report-editor.spec.md
business-rules/
permission.rules.json
tracking.rules.json
platform-mappings/
web/
tokens.css
flutter/
theme_mapping.dart
mini-program/
token_mapping.json
在这套结构里，Web 和 Flutter 不一定共享组件代码，但它们共享：
- 设计语言
- 组件协议
- 页面模式
- 业务规则
- 类型定义
- 校验标准
这样真正减少的，不是“写代码的次数”，而是“需求被重复翻译的次数”。
八、最后才是把规范结构化，供大模型参与生成和校验
很多团队在引入 AI 时，最容易犯的错误是：一上来就希望大模型“自动生成页面”。但如果前面的规范体系还没建立好，这种生成只能停留在 demo 层面。
更现实的路径应该是：
第一步，让 Agent 先读规范，而不是先写代码
Agent 不应该靠一大段 prompt 去猜团队规范，而应该按需读取：
- Semantic Token
- Component Contract
- Page Pattern
- Business Rules
- Schema
第二步，让 Agent 先做受控生成
最适合 AI 先接入的场景包括：
- 页面骨架生成
- 表单 / 列表 / 详情区 schema 驱动生成
- TS types / Dart models 自动生成
- 埋点 / 权限 / 状态处理检查
- 组件使用规范检查
第三步，再做确定性校验
大模型适合生成，但最终质量不能靠模型“自觉”。要把关键规则做成 validator：
- 是否用了非法 token
- 是否绕过组件库直接写样式
- 是否缺少 loading / empty / error
- 是否遗漏权限态
- 是否漏了埋点
- 是否违反页面 pattern
所以 AI 在这套体系里的位置，不是“替代开发”，而是：
基于结构化规范做受控生成，再基于确定性规则做质量校验。
九、落地路径：不要一上来就做大一统
这套方案看起来大，但完全可以分阶段推进。
第一阶段：先统一最基础的三件事
- 基础 Design Token
- 高复用组件 Contract
- 接口模型与类型自动生成
这一阶段的目标不是“多先进”，而是先把最容易反复沟通的部分统一起来。
第二阶段：沉淀页面 Pattern 和状态矩阵
挑选高频页面类型，比如列表页、详情页、洞察页、配置页，把交互模式和状态处理收敛起来。
第三阶段：开始结构化业务规范
把 Spec、Contract、Schema 分层管理，逐步形成 source of truth。
第四阶段：引入 Agent 和 Validator
先让 AI 参与骨架生成和规则检查，再逐步扩大到辅助开发。
这条路径的好处是：每一步都能独立产生价值，而不是必须一次性完成一个庞大的“平台化工程”。
这套方案最终解决了什么
如果这套体系跑起来，真正被降低的不是代码行数，而是以下几类成本：
- 同一个需求在多端之间的翻译成本
- 视觉、行为、状态不一致带来的返工成本
- 接口、权限、埋点理解不一致的沟通成本
- 新人接手复杂项目时的理解成本
- AI 生成无法进入正式工程体系的失控成本
换句话说，它把“多端协作”从一种靠人力补位的模式，变成一种靠规范驱动、工程约束和 AI 辅助的模式。
