@microi.net/cli 4.6.2 → 4.6.7

package/dist/microi.skills/ui-design/references/design-pattern-library.md

@@ -1,171 +1,184 @@
-# Microi 设计模式库
-
-本文件是 Microi.UI 的内部设计知识库。它把成熟数字产品中反复有效的构图、流程、动效和设计系统方法统一为 Microi 自有规则；不得在成品、类名、文案或资源中保留外部品牌痕迹。
-
-## 目录
-
-1. [模式选择](#模式选择)
-2. [品牌叙事](#品牌叙事)
-3. [真实产品流程](#真实产品流程)
-4. [趋势构图](#趋势构图)
-5. [沉浸互动](#沉浸互动)
-6. [动态首屏](#动态首屏)
-7. [数据工作台](#数据工作台)
-8. [组合与验收](#组合与验收)
-
-## 模式选择
-
-先用一句话定义页面首要任务，再选一个主模式。页面不能同时拥有两个互相竞争的视觉中心。
-
-| 页面目标 | 主模式 | 第一屏必须出现 | 常见误区 |
-| --- | --- | --- | --- |
-| 解释品牌、产品或新能力 | 品牌叙事 | 价值主张、产品对象、主 CTA、信任证明 | 只有大标题和装饰背景 |
-| 完成登录、购买、预约、设置等任务 | 真实产品流程 | 当前任务、必要输入、进度、主要动作 | 为了好看打乱操作顺序 |
-| 内容、作品、活动或创意展示 | 趋势构图 | 明确主题、主视觉、可扫读分类 | 把多种潮流效果叠在一起 |
-| 产品体验需要空间感和互动反馈 | 沉浸互动 | 可操作对象、静态降级、退出/继续路径 | WebGL 覆盖正文或阻塞首屏 |
-| 首秒需要建立记忆点 | 动态首屏 | 先可读的标题和 CTA，再出现装饰动效 | 动画先于内容、按钮不可用 |
-| 管理、分析、运营和调度 | 数据工作台 | 2-4 个核心指标、待办、异常、主动作 | 彩虹图表、卡片过多、信息平权 |
-
-选择后填写：页面目标、用户角色、主模式、辅助能力、视觉锚点、主动作、最大宽度、栅格、字体层级、主题、状态矩阵、动效预算、移动端重排和验收截图。
-
-## 品牌叙事
-
-### 首屏结构
-
-1. 顶部导航只保留 4-6 个高价值入口，主 CTA 放在最右侧。
-2. 标题先表达结果，再说明产品名；桌面通常 48-72px，移动端 34-44px，行宽控制在 8-13 个汉字或 9-14 个英文单词。
-3. 副标题回答“给谁、解决什么、怎样不同”，宽度不超过标题的 80%。
-4. 主 CTA 与次 CTA 语义明确：开始使用/立即体验是主动作，查看文档/观看演示是次动作。
-5. 右侧或背景必须出现真实产品对象：界面、设备、场景、数据、人物或可操作模型，不能只放抽象光球。
-6. 首屏下沿给出下一段提示：可信数字、客户/能力证明、滚动线索或内容预览。
-
-### 叙事节奏
-
-- 第一段：问题与结果；第二段：核心机制；第三段：真实场景；第四段：证据；第五段：再次行动。
-- 每段只承担一个论点。滚动触发只改变一个主变量，例如视角、进度、亮度或对象状态。
-- 复杂故事使用粘性舞台加分段文案；移动端降级为普通纵向卡片，不强制保留长距离 sticky。
-- 产品截图、数字和客户证据优先于形容词。无真实数据时使用明确标注的示例数据。
-
-### 视觉规则
-
-- 采用 12 列桌面栅格和 4 列移动栅格；内容上限通常 1180-1320px。
-- 一个页面只保留一个主色和一个强调色，装饰色不能抢占语义状态色。
-- 大标题可使用紧字距，但正文必须保持舒适行高；中文正文建议 1.75-1.9。
-- 图片与文本必须形成明暗或尺度对比，避免左右两边都很重。
-
-## 真实产品流程
-
-产品界面从任务链而不是单张页面出发。先画出入口、输入、校验、处理中、成功、失败、恢复和退出，再设计每一屏。
-
-### 通用状态矩阵
-
-| 状态 | 必须包含 |
-| --- | --- |
-| 初始 | 任务说明、最少输入、主动作、帮助入口 |
-| 输入中 | 即时格式反馈、保留输入、键盘/焦点顺序 |
-| 提交中 | 按钮 loading、禁止重复提交、可理解文案 |
-| 成功 | 结果摘要、下一步、可返回位置 |
-| 可恢复错误 | 原输入、具体原因、重试动作 |
-| 不可恢复错误 | 安全说明、替代路径、联系/返回入口 |
-| 权限不足 | 缺少的权限、申请方式、不会丢失的内容 |
-| 空数据 | 为什么为空、如何创建第一条、示例价值 |
-
-### 信息密度
-
-- 每屏只突出一个主动作。危险动作与主动作不能使用相同视觉权重。
-- 表单默认按任务分段，字段少时直接平铺；步骤超过 3 个或有强校验时显示明确进度。
-- 关键说明放在动作附近，不把风险、续费、隐私或取消条件埋进页脚。
-- 列表卡片必须包含对象身份、状态、关键元数据、时间和可预期的主操作。
-- 弹窗用于短决策；超过三个字段、含上传/联动/表格/步骤时使用独立页面或抽屉。
-
-完整流程见 [product-flow-recipes.md](product-flow-recipes.md)。
-
-## 趋势构图
-
-趋势只能服务内容，不能成为页面目标。采用“结构固定、媒介可变”的方式：先确定栅格、层级和操作，再替换色彩、字体、图像或动效。
-
-### 可用构图语法
-
-- **编辑式网格**：大标题、细分隔线、编号、跨列图像；适合内容、案例和活动。
-- **安静产品化**：浅中性色、紧凑卡片、细边框、少阴影；适合 SaaS、工具、后台。
-- **深色指挥中心**：暗背景、少量高饱和状态色、密集但清晰的数据；适合监控和 AI 工具。
-- **暖色生活方式**：低饱和暖底、真实照片、柔和圆角、自然语言；适合生活与消费应用。
-- **高对比创意**：大字号、单一强色、错位网格、几何形；适合创意展示，不能用于高频录入页。
-- **材质化展示**：纸张、玻璃、金属或柔光纹理只作为局部媒介，必须提供纯色降级。
-
-### 组合约束
-
-- 同屏最多两种字号跨度、两种圆角家族和三层阴影。
-- 8px 间距体系为默认；4px 用于微间距，24/32/48px 用于区域层级。
-- 图像比例固定并按内容选择 `cover` 或 `contain`，列表内不混用随机比例。
-- 任何装饰线、编号、英文 eyebrow 都必须帮助分组或定位，不能只为“显得高级”。
-
-## 沉浸互动
-
-沉浸效果只应占据 Hero、产品舞台或独立展示区域。正文、表单、表格和可访问导航必须保持普通 DOM。
-
-### 三层模型
-
-1. 内容层：标题、按钮、表单和导航，永远可访问、可选择、可键盘操作。
-2. 互动层：产品模型、Canvas/WebGL、指针反馈，失败时可移除。
-3. 氛围层：网格、渐变、光影或静态海报，不接收指针事件。
-
-### 降级顺序
-
-完整互动 -> 降低粒子/分辨率/帧率 -> 静态海报加轻微 CSS 动效 -> 纯色或渐变背景。`prefers-reduced-motion`、低性能设备、后台标签页和省电模式应自动进入较低等级。
-
-### 交互规则
-
-- 鼠标跟随位移不超过容器尺寸的 2%-4%，移动端不模拟鼠标跟随。
-- 滚动驱动必须有开始、完成和回滚边界；离开视口后暂停渲染。
-- 互动对象不能遮挡 CTA；Canvas 设置 `pointer-events:none` 时，真实操作放在 DOM。
-- 加载失败不能留下黑屏，必须在 1-2 秒内显示静态占位或骨架。
-
-完整性能与媒体预算见 [motion-and-media.md](motion-and-media.md)。
-
-## 动态首屏
-
-首屏第一目标是让用户在动画开始前也能读懂页面。
-
-### 建议时间线
-
-- 0-120ms：背景和布局稳定，避免白屏。
-- 80-320ms：品牌标识与标题淡入上移。
-- 180-460ms：副标题和 CTA 出现，按钮立即可用。
-- 320-760ms：产品对象或主视觉进入。
-- 600-1200ms：次要卡片、指标和装饰错落出现。
-- 1200ms 后：只保留低振幅停留动效，停止大范围位移。
-
-### 运动语法
-
-- 每页选一个主方向：上浮、横向揭示、缩放聚焦、遮罩擦除或深度推进。
-- 主元素时长 260-420ms；微交互 140-220ms；装饰循环至少 4 秒且振幅小。
-- CTA hover/pressed 必须独立于背景动画；动画停止后所有操作仍可用。
-- 不自动播放有声视频，不用大面积持续 blur，不在移动端保留复杂背景视频。
-
-## 数据工作台
-
-- 第一屏先展示 2-4 个高信号指标、待处理事项和异常，不把所有统计平铺成同权卡片。
-- 指标包含当前值、比较基准、方向和时间范围；单独一个大数字不能表达趋势。
-- 图表颜色固定语义：主系列、对比系列、成功、警告、危险、中性，不能每张图随机配色。
-- 表格默认提供搜索、关键筛选、排序、分页、列可读性和空/错/加载状态。
-- 高密度页面减少阴影和圆角，依靠间距、分隔线、对齐和字号建立层级。
-- 移动端先展示摘要和待办，复杂图表进入详情；禁止把桌面大表硬缩进手机。
-
-## 组合与验收
-
-### 推荐组合
-
-- 官网：品牌叙事 + 动态首屏 + 设计契约。
-- C 端应用：真实产品流程 + 暖色/安静构图 + 轻动效。
-- SaaS 工具：真实产品流程 + 安静产品化 + 数据工作台。
-- 互动产品展示：品牌叙事 + 沉浸互动，必须有静态降级。
-- 数据中心：数据工作台 + 深色指挥中心，动效只表达状态变化。
-
-### 截图矩阵
-
-至少生成 1440/1920 桌面、390 移动、亮色、暗色以及相关的加载、空、错误、成功、权限状态。检查首屏重心、网格对齐、文字对比度、按钮居中、横向滚动、键盘焦点、安全区和 `prefers-reduced-motion`。
-
-### 完成定义
-
-构建通过不等于 UI 完成。只有真实内容与全部状态可操作、桌面和移动截图通过、控制台无错误、外部资源失败有降级、动效关闭后页面仍完整，才算完成。
+# Microi 设计模式库
+
+本文件是 Microi.UI 的内部设计知识库。它把成熟数字产品中反复有效的构图、流程、动效和设计系统方法统一为 Microi 自有规则；不得在成品、类名、文案或资源中保留外部品牌痕迹。
+
+## 目录
+
+1. [模式选择](#模式选择)
+2. [品牌叙事](#品牌叙事)
+3. [真实产品流程](#真实产品流程)
+4. [趋势构图](#趋势构图)
+5. [沉浸互动](#沉浸互动)
+6. [动态首屏](#动态首屏)
+7. [数据工作台](#数据工作台)
+8. [组合与验收](#组合与验收)
+
+## 模式选择
+
+先用一句话定义页面首要任务，再选一个主模式。页面不能同时拥有两个互相竞争的视觉中心。
+
+| 页面目标 | 主模式 | 第一屏必须出现 | 常见误区 |
+| --- | --- | --- | --- |
+| 解释品牌、产品或新能力 | 品牌叙事 | 价值主张、产品对象、主 CTA、信任证明 | 只有大标题和装饰背景 |
+| 完成登录、购买、预约、设置等任务 | 真实产品流程 | 当前任务、必要输入、进度、主要动作 | 为了好看打乱操作顺序 |
+| 内容、作品、活动或创意展示 | 趋势构图 | 明确主题、主视觉、可扫读分类 | 把多种潮流效果叠在一起 |
+| 产品体验需要空间感和互动反馈 | 沉浸互动 | 可操作对象、静态降级、退出/继续路径 | WebGL 覆盖正文或阻塞首屏 |
+| 首秒需要建立记忆点 | 动态首屏 | 先可读的标题和 CTA，再出现装饰动效 | 动画先于内容、按钮不可用 |
+| 管理、分析、运营和调度 | 数据工作台 | 2-4 个核心指标、待办、异常、主动作 | 彩虹图表、卡片过多、信息平权 |
+
+选择后填写：页面目标、用户角色、主模式、辅助能力、视觉锚点、主动作、最大宽度、栅格、字体层级、主题、状态矩阵、动效预算、移动端重排和验收截图。
+
+### 用具体隐喻定义气质
+
+宽泛形容词不能直接指导实现。把“高级、现代、极简、科技”收敛成一个可以推导规则的具体隐喻，并同时写出它排除什么：
+
+| 具体隐喻 | 可推导规则 | 明确排除 |
+| --- | --- | --- |
+| 安静的专业工作台 | 中性色表面、细边框、四列可读卡片、紧凑内部间距、宽松区块留白 | 大面积字母占位、彩虹渐变、所有按钮同权 |
+| 温暖的手工纸张 | 暖底、自然低饱和色、柔和圆角、轻触感阴影 | 冷硬霓虹、尖锐切角、持续发光 |
+| 夜间发光仪表舱 | 深色分层、少量青蓝紫状态光、清晰数字层级、短促状态动效 | 大面积炫光、随机彩色图表、低对比正文 |
+| 雾感通透界面 | 灰白低彩、细线、轻透明表面、大留白、慢速淡入 | 厚重投影、不透明色块堆叠、过度模糊 |
+
+先写“用户任务、主情绪、具体隐喻、三条应当、三条禁止”，再选择 token 与组件。完整双层契约见 [mci-design-contract.md](mci-design-contract.md)。
+
+## 品牌叙事
+
+### 首屏结构
+
+1. 顶部导航只保留 4-6 个高价值入口，主 CTA 放在最右侧。
+2. 标题先表达结果，再说明产品名；桌面通常 48-72px，移动端 34-44px，行宽控制在 8-13 个汉字或 9-14 个英文单词。
+3. 副标题回答“给谁、解决什么、怎样不同”，宽度不超过标题的 80%。
+4. 主 CTA 与次 CTA 语义明确：开始使用/立即体验是主动作，查看文档/观看演示是次动作。
+5. 右侧或背景必须出现真实产品对象：界面、设备、场景、数据、人物或可操作模型，不能只放抽象光球。
+6. 首屏下沿给出下一段提示：可信数字、客户/能力证明、滚动线索或内容预览。
+
+### 叙事节奏
+
+- 第一段：问题与结果；第二段：核心机制；第三段：真实场景；第四段：证据；第五段：再次行动。
+- 每段只承担一个论点。滚动触发只改变一个主变量，例如视角、进度、亮度或对象状态。
+- 复杂故事使用粘性舞台加分段文案；移动端降级为普通纵向卡片，不强制保留长距离 sticky。
+- 产品截图、数字和客户证据优先于形容词。无真实数据时使用明确标注的示例数据。
+
+### 视觉规则
+
+- 采用 12 列桌面栅格和 4 列移动栅格；内容上限通常 1180-1320px。
+- 一个页面只保留一个主色和一个强调色，装饰色不能抢占语义状态色。
+- 大标题可使用紧字距，但正文必须保持舒适行高；中文正文建议 1.75-1.9。
+- 图片与文本必须形成明暗或尺度对比，避免左右两边都很重。
+
+## 真实产品流程
+
+产品界面从任务链而不是单张页面出发。先画出入口、输入、校验、处理中、成功、失败、恢复和退出，再设计每一屏。
+
+### 通用状态矩阵
+
+| 状态 | 必须包含 |
+| --- | --- |
+| 初始 | 任务说明、最少输入、主动作、帮助入口 |
+| 输入中 | 即时格式反馈、保留输入、键盘/焦点顺序 |
+| 提交中 | 按钮 loading、禁止重复提交、可理解文案 |
+| 成功 | 结果摘要、下一步、可返回位置 |
+| 可恢复错误 | 原输入、具体原因、重试动作 |
+| 不可恢复错误 | 安全说明、替代路径、联系/返回入口 |
+| 权限不足 | 缺少的权限、申请方式、不会丢失的内容 |
+| 空数据 | 为什么为空、如何创建第一条、示例价值 |
+
+### 信息密度
+
+- 每屏只突出一个主动作。危险动作与主动作不能使用相同视觉权重。
+- 表单默认按任务分段，字段少时直接平铺；步骤超过 3 个或有强校验时显示明确进度。
+- 关键说明放在动作附近，不把风险、续费、隐私或取消条件埋进页脚。
+- 列表卡片必须包含对象身份、状态、关键元数据、时间和可预期的主操作。
+- 弹窗用于短决策；超过三个字段、含上传/联动/表格/步骤时使用独立页面或抽屉。
+
+完整流程见 [product-flow-recipes.md](product-flow-recipes.md)。
+
+## 趋势构图
+
+趋势只能服务内容，不能成为页面目标。采用“结构固定、媒介可变”的方式：先确定栅格、层级和操作，再替换色彩、字体、图像或动效。
+
+### 可用构图语法
+
+- **编辑式网格**：大标题、细分隔线、编号、跨列图像；适合内容、案例和活动。
+- **安静产品化**：浅中性色、紧凑卡片、细边框、少阴影；适合 SaaS、工具、后台。
+- **深色指挥中心**：暗背景、少量高饱和状态色、密集但清晰的数据；适合监控和 AI 工具。
+- **暖色生活方式**：低饱和暖底、真实照片、柔和圆角、自然语言；适合生活与消费应用。
+- **高对比创意**：大字号、单一强色、错位网格、几何形；适合创意展示，不能用于高频录入页。
+- **材质化展示**：纸张、玻璃、金属或柔光纹理只作为局部媒介，必须提供纯色降级。
+
+### 组合约束
+
+- 同屏最多两种字号跨度、两种圆角家族和三层阴影。
+- 8px 间距体系为默认；4px 用于微间距，24/32/48px 用于区域层级。
+- 图像比例固定并按内容选择 `cover` 或 `contain`，列表内不混用随机比例。
+- 任何装饰线、编号、英文 eyebrow 都必须帮助分组或定位，不能只为“显得高级”。
+
+## 沉浸互动
+
+沉浸效果只应占据 Hero、产品舞台或独立展示区域。正文、表单、表格和可访问导航必须保持普通 DOM。
+
+### 三层模型
+
+1. 内容层：标题、按钮、表单和导航，永远可访问、可选择、可键盘操作。
+2. 互动层：产品模型、Canvas/WebGL、指针反馈，失败时可移除。
+3. 氛围层：网格、渐变、光影或静态海报，不接收指针事件。
+
+### 降级顺序
+
+完整互动 -> 降低粒子/分辨率/帧率 -> 静态海报加轻微 CSS 动效 -> 纯色或渐变背景。`prefers-reduced-motion`、低性能设备、后台标签页和省电模式应自动进入较低等级。
+
+### 交互规则
+
+- 鼠标跟随位移不超过容器尺寸的 2%-4%，移动端不模拟鼠标跟随。
+- 滚动驱动必须有开始、完成和回滚边界；离开视口后暂停渲染。
+- 互动对象不能遮挡 CTA；Canvas 设置 `pointer-events:none` 时，真实操作放在 DOM。
+- 加载失败不能留下黑屏，必须在 1-2 秒内显示静态占位或骨架。
+
+完整性能与媒体预算见 [motion-and-media.md](motion-and-media.md)。
+
+## 动态首屏
+
+首屏第一目标是让用户在动画开始前也能读懂页面。
+
+### 建议时间线
+
+- 0-120ms：背景和布局稳定，避免白屏。
+- 80-320ms：品牌标识与标题淡入上移。
+- 180-460ms：副标题和 CTA 出现，按钮立即可用。
+- 320-760ms：产品对象或主视觉进入。
+- 600-1200ms：次要卡片、指标和装饰错落出现。
+- 1200ms 后：只保留低振幅停留动效，停止大范围位移。
+
+### 运动语法
+
+- 每页选一个主方向：上浮、横向揭示、缩放聚焦、遮罩擦除或深度推进。
+- 主元素时长 260-420ms；微交互 140-220ms；装饰循环至少 4 秒且振幅小。
+- CTA hover/pressed 必须独立于背景动画；动画停止后所有操作仍可用。
+- 不自动播放有声视频，不用大面积持续 blur，不在移动端保留复杂背景视频。
+
+## 数据工作台
+
+- 第一屏先展示 2-4 个高信号指标、待处理事项和异常，不把所有统计平铺成同权卡片。
+- 指标包含当前值、比较基准、方向和时间范围；单独一个大数字不能表达趋势。
+- 图表颜色固定语义：主系列、对比系列、成功、警告、危险、中性，不能每张图随机配色。
+- 表格默认提供搜索、关键筛选、排序、分页、列可读性和空/错/加载状态。
+- 高密度页面减少阴影和圆角，依靠间距、分隔线、对齐和字号建立层级。
+- 移动端先展示摘要和待办，复杂图表进入详情；禁止把桌面大表硬缩进手机。
+
+## 组合与验收
+
+### 推荐组合
+
+- 官网：品牌叙事 + 动态首屏 + 设计契约。
+- C 端应用：真实产品流程 + 暖色/安静构图 + 轻动效。
+- SaaS 工具：真实产品流程 + 安静产品化 + 数据工作台。
+- 互动产品展示：品牌叙事 + 沉浸互动，必须有静态降级。
+- 数据中心：数据工作台 + 深色指挥中心，动效只表达状态变化。
+
+### 截图矩阵
+
+至少生成 1440/1920 桌面、390 移动、亮色、暗色以及相关的加载、空、错误、成功、权限状态。检查首屏重心、网格对齐、文字对比度、按钮居中、横向滚动、键盘焦点、安全区和 `prefers-reduced-motion`。
+
+### 完成定义
+
+构建通过不等于 UI 完成。只有真实内容与全部状态可操作、桌面和移动截图通过、控制台无错误、外部资源失败有降级、动效关闭后页面仍完整，才算完成。

package/dist/microi.skills/ui-design/references/mci-design-contract.md

@@ -1,84 +1,163 @@
-# MCI-DESIGN 设计契约
-
-大型项目在根目录维护 `MCI-DESIGN.md`，让设计决策可版本管理、可复用、可被 AI 和人共同读取。它是对 `Microi.UI/src/theme/tokens.css` 的语义说明，不替代真实源码 token。
-
-## 必需章节
-
-1. 产品与用户
-2. 视觉性格
-3. 颜色
-4. 字体
-5. 布局与间距
-6. 层级与形状
-7. 组件契约
-8. 页面模式
-9. 动效与媒体
-10. 响应式与安全区
-11. 可访问性
-12. 禁止事项
-
-## 最小模板
-
-```markdown
-# 项目设计契约
-
-## 产品与用户
-- 首要用户：
-- 首要任务：
-- 关键设备：
-
-## 视觉性格
-- 三个关键词：专业、清晰、克制
-- 主模式：真实产品流程
-- 辅助能力：数据工作台
-
-## 颜色
-- `--mci-color-primary`：主动作与选中态
-- `--mci-color-success`：已完成、在线
-- `--mci-color-warning`：需关注
-- `--mci-color-danger`：错误与危险动作
-- `--mci-bg-base/card/elevated`：页面、卡片、浮层
-- `--mci-text-primary/secondary/tertiary`：正文层级
-
-## 字体
-- Display：48/56, 800
-- H1：32/40, 750
-- H2：24/32, 700
-- Body：16/28, 400
-- Meta：13/20, 500
-
-## 布局与间距
-- Desktop：12 列，最大宽度 1280px
-- Mobile：4 列，左右 16px
-- 间距：4/8/12/16/24/32/48/64
-
-## 组件契约
-### PrimaryButton
-- 高度 44px；图标 + 文字居中
-- 状态：default/hover/focus/pressed/loading/disabled
-- 主按钮每个页面最多一个视觉焦点
-
-### Card
-- 使用 `--mci-bg-card`、`--mci-border-color`、`--mci-shape-card`
-- 卡片可点击时才有 hover/pressed
-
-## 页面模式
-- 首页：品牌叙事 + 产品对象
-- 列表：筛选 + 骨架 + 业务卡片 + 分页
-- 表单：分段 + 草稿 + 错误摘要 + 固定操作栏
-
-## 动效与媒体
-- 入场 320ms；微交互 160ms；仅 transform/opacity
-- 复杂媒体提供静态海报与 reduced-motion 降级
-
-## 禁止事项
-- 禁止全局泛化 CSS、纯文字底部导航、假按钮、无降级远程资源
-```
-
-## AI 使用规则
-
-- 开始实现前读取本契约和 `ui-design` skill。
-- 契约缺少的值优先继承 Microi.UI token，不临时发明新色值或圆角。
-- 新模式在两个以上页面重复时先更新契约，再抽成 `Mci*` 或项目级 `mci-*` 组件。
-- 修改契约后至少截图一张受影响页面的桌面和移动版本。
-- 契约与实现冲突时，以当前合法源码和用户最新明确要求为准，并同步修订契约。
+# MCI-DESIGN 设计契约
+
+大型项目在根目录维护 `MCI-DESIGN.md`，让界面意图、精确取值和组件状态可以版本管理、自动检查，并由人和 AI 共同延续。它是 `Microi.UI/src/theme/tokens.css` 的项目级语义说明，不替代真实源码 token，也不替代线框、原型和视觉验收。
+
+## 双层单源模型
+
+设计契约必须同时包含两层，缺少任一层都不完整：
+
+1. **机器可读层**：颜色、字体、间距、圆角、阴影、组件状态和引用关系。它回答“准确使用什么值”，用于检查、差异比较和生成运行时变量。
+2. **人类可读层**：产品对象、受众、情绪目标、视觉隐喻、信息层级、选择理由和明确禁区。它回答“为什么这样设计”，帮助接手者在契约没有覆盖的新场景中作出一致判断。
+
+精确值会随项目变化，设计理由决定取舍方向。若两层暂时冲突，先核对用户最新要求和合法源码，再同时修订契约与实现，禁止只改其中一边。
+
+## 意图优先级
+
+设计前按以下顺序收敛，不从颜色选择器开始：
+
+1. 用户进入页面后的首要任务与成功结果。
+2. 页面希望产生的一个主情绪，例如可信、安静、敏捷、温暖或专注。
+3. 一个具体视觉隐喻，例如“安静的专业工作台”“柔和的手工纸张”“夜间发光仪表舱”。具体隐喻比堆叠“高级、现代、极简”等形容词更能约束色彩、材质、密度和动效。
+4. 一组明确的“应当 / 禁止”，把隐含边界写出来。
+5. 最后才是 token、组件和页面实现。
+
+一个页面只保留一个主隐喻，辅助气质最多两项。不要把温暖圆润、深色霓虹、通透玻璃和高密度数据等多套语言同时堆在一个界面。
+
+## 固定章节顺序
+
+核心章节按以下顺序书写，便于稳定解析和审查：
+
+1. 产品概览与目标用户
+2. 视觉性格与情绪目标
+3. 颜色
+4. 字体
+5. 布局与间距
+6. 层级、材质与形状
+7. 组件与状态
+8. 页面模式与信息架构
+9. 动效与媒体
+10. 响应式与安全区
+11. 可访问性、性能与降级
+12. 应当与禁止
+
+允许在末尾增加项目专属章节，但必须保留未知扩展内容，不能重复核心章节，也不能用近似拼写制造第二套同义章节。确实不适用的项目可以省略某一规则，但要在“有意省略”中说明理由。
+
+## 机器可读层
+
+机器块应使用语义命名，避免 `blue500`、`bigRadius`、`shadow2` 这类只描述外观、不说明用途的名字。组件可通过 `{路径}` 引用共享 token；引用必须存在，不能形成循环。
+
+```yaml
+contract:
+  version: 1
+  project: 示例项目
+  mode: data-workspace
+  intent: 安静、清晰、可快速扫描的专业工作台
+
+tokens:
+  color:
+    canvas: var(--mci-bg-base)
+    surface: var(--mci-bg-card)
+    surfaceElevated: var(--mci-bg-elevated)
+    textPrimary: var(--mci-text-primary)
+    textSecondary: var(--mci-text-secondary)
+    primary: var(--mci-color-primary)
+    danger: var(--mci-color-danger)
+  typography:
+    title: { size: 16px, lineHeight: 1.45, weight: 700 }
+    body: { size: 14px, lineHeight: 1.65, weight: 400 }
+    meta: { size: 12px, lineHeight: 1.5, weight: 500 }
+  spacing:
+    compact: 8px
+    control: 12px
+    card: 16px
+    section: 24px
+  shape:
+    control: var(--mci-shape-input)
+    card: var(--mci-shape-card)
+    pill: var(--mci-radius-full)
+  elevation:
+    card: var(--mci-shadow-card)
+    cardHover: var(--mci-shadow-card-hover)
+
+components:
+  dataCard:
+    background: "{tokens.color.surface}"
+    radius: "{tokens.shape.card}"
+    padding: "{tokens.spacing.card}"
+    states:
+      default: { elevation: "{tokens.elevation.card}" }
+      hover: { elevation: "{tokens.elevation.cardHover}", lift: -2px }
+      focus: { outline: "{tokens.color.primary}" }
+      selected: { border: "{tokens.color.primary}" }
+      disabled: { opacity: 0.56 }
+
+omissions:
+  - rule: backgroundVideo
+    reason: 高频数据页不需要持续媒体，减少干扰与资源开销
+```
+
+机器块至少满足：
+
+- 有主色、页面底色、表面色、主/次文字色和危险色。
+- 字体角色包含字号、行高、字重；间距、圆角和层级都有明确单位或 `--mci-*` 引用。
+- 组件状态覆盖适用的 default、hover、focus、pressed、loading、empty、error、disabled、selected、success。
+- 同一语义只定义一次；组件优先引用共享 token，而不是重新复制值。
+- Alpha、混色和玻璃表面必须说明叠加在哪种底色上；只给透明度不算完整颜色定义。
+
+## 人类可读层
+
+每个核心选择都要写一行理由，尤其是：
+
+- 为什么这种气质适合目标用户与任务。
+- 颜色如何区分主动作、状态、表面和内容层级。
+- 字体如何形成阅读节奏，中文和数字如何共存。
+- 内部紧凑与外部宽松分别使用哪些间距。
+- 深度来自色调层、细边框、环境阴影、透明材质还是实体投影。
+- 圆角、切角、胶囊或有机形状表达什么性格。
+- 卡片、按钮、输入、导航、弹层在所有状态下如何变化。
+- 哪些装饰会破坏任务，应明确禁止。
+
+## 可迁移的视觉气质
+
+以下不是成品主题，而是把意图翻译为系统规则的示例：
+
+| 气质 | 色彩与材质 | 形状与间距 | 动效 | 禁止 |
+| --- | --- | --- | --- | --- |
+| 温暖友好 | 暖白或浅沙底、自然低饱和强调色、轻触感层次 | 圆润或轻微有机形，外部留白宽松 | 柔和上浮与按压 | 冷硬高对比、密集霓虹、尖锐切角 |
+| 深色发光 | 深色表面、少量青蓝紫发光语义、清晰高对比文字 | 边界精确、圆角克制、层级紧凑 | 短促聚焦与状态脉冲 | 大面积炫光、彩虹状态色、持续漂移 |
+| 雾感通透 | 灰白低彩底、细线边框、轻透明表面 | 大留白、轻圆角、细腻分层 | 慢速淡入与透明度变化 | 厚重投影、不透明色块堆叠、过度模糊 |
+
+## 后台数据卡片契约
+
+后台数据卡片是高频操作容器，不是营销海报：
+
+- 固定信息顺序：真实图片或紧凑身份标记 → 标题与状态 → 2—4 个关键字段 → 时间/辅助标签 → 操作区。
+- 配置了图片但当前行无图时，使用 40—44px 的首字/图标标记；禁止生成占据卡片三分之一以上的装饰占位图。
+- 默认桌面四列，显式列数配置优先；中等宽度自动降为三列或两列，移动端单列。卡片最小可读宽度优先于“同屏塞更多”。
+- 标题最多两行，主次文字、金额、状态与时间有固定层级；标签只表达状态或分类，不把每个字段都做成胶囊。
+- 操作区优先一个主动作、一至两个次动作，其余收进“更多”；危险动作不得与主动作同权。移动端触控目标不小于 44px。
+- 骨架屏必须复刻最终标题、字段和操作区的几何结构；空态解释原因并提供下一步。
+- 整卡可进入详情时必须提供键盘焦点、Enter/Space 触发和可见 focus；内部按钮阻止事件冒泡。
+
+## 契约检查、差异与输出
+
+每次修改契约或 UI 时，按顺序检查：
+
+1. **结构**：核心章节存在且顺序正确，无重复章节、疑似拼写错误或无法识别的 token 组。
+2. **类型**：颜色、长度、数字、布尔值和状态对象类型正确，token 式文本没有被误放在普通说明里而漏解析。
+3. **引用**：所有 `{路径}` 可解析，无循环引用；未被组件、页面或输出消费的孤立 token 要删除或说明用途。
+4. **语义**：主色、表面、文字层级、组件状态和有意省略完整；命名能解释用途。
+5. **可访问性**：正文和交互态对比度满足项目标准，焦点可见，键盘路径连续，低动效降级完整。
+6. **差异门禁**：评审设计契约的语义变更和实现变更是否同时出现；意外删除、重命名或大范围 token 漂移应阻止合入。
+7. **输出**：需要生成运行时变量或其它主题格式时，只由已校验的机器块派生，禁止维护第二份手工 token。
+
+契约格式若仍在演进，项目必须锁定 `contract.version`，升级时先查看差异并一次性迁移。跨平台脚本要提供不依赖文件扩展名的稳定入口，避免不同终端执行出不同结果。
+
+## AI 使用规则
+
+- 开始实现前完整读取契约和 `ui-design` skill；先复述页面任务、主气质和三条禁止事项，再写页面。
+- 契约缺少的精确值优先继承 Microi.UI token；不能用“看起来差不多”的硬编码补洞。
+- 先稳定颜色、字体、间距、层级和形状，再定义组件状态；不要在基础 token 尚未收敛时过早堆复杂组件结构。
+- 新模式在两个以上页面重复时，先更新契约，再抽成 `Mci*` 或项目级 `mci-*` 组件。
+- 修改契约后至少截图一张受影响页面的桌面和移动版本，并覆盖亮/暗主题及相关业务状态。
+- 契约、源码、浏览器截图三者冲突时不得宣称完成；修复后重新执行结构检查、定向测试和视觉验收。

package/dist/microi.skills/v8-file-upload/SKILL.md

@@ -186,6 +186,14 @@ var extractResult = V8.Method.ExtractZip({
 - 安装脚本还必须同步当前有效 `sys_config`：`ApiBase` 使用对外可访问的 API 端口，`FileServer` 使用 `http://<访问IP>:<MinIO API端口>/mci-public`。`ApiBase` 不能误用 Web 前端端口，因为 V8 代码会直接在其后拼接 `/api/...` 或 `/apiengine/...`。
 - 安装验收必须使用真实登录 Token 分别执行一次 `Limit=false` 和 `Limit=true` 上传：公有文件匿名访问应返回 `200`，私有文件匿名访问应返回 `403`，私有文件通过签名 URL 访问应返回 `200`，并核对下载内容与上传内容一致。
 
+### 复盘：旧空库缺少可选字段导致 MinIO 初始化后中断
+
+- 触发场景：MinIO 容器、私有桶和公有桶均已成功创建，但安装器更新 `sys_osclients` 时因旧库缺少 `NetworkIsInternet` 返回 `Unknown column`，整套安装停在 API 部署之前。
+- 根因：安装器在 API/Upgrade 尚未启动时依赖了并非 MinIO 必需、且存量数据库不保证存在的旧可选字段；同时只按 `OsClient` 更新且没有写后回读。
+- 通用规则：MinIO 安装前先校验真正必需的物理字段，并按 `OsClient + OsClientType + OsClientNetwork + IsEnable + IsDeleted` 唯一定位运行租户。内外网端点由 API 允许的启动项 `OsClientNetwork` 选择，安装器不得再写 `NetworkIsInternet`；配置更新后逐字段回读一致才继续。
+- 恢复规则：桶初始化成功而配置写入失败不需要删除桶或数据卷。中断的新安装应先备份现有 Compose 并记录绑定数据目录，只对对应编排执行不带 `-v` 的 `docker compose down`，保留数据恢复点后再使用最新版脚本；禁止直接删除数据库或对象存储目录。
+- 自动化检查：用一个不含 `NetworkIsInternet`、但包含 MinIO 必需字段的临时 MySQL 表执行 schema、唯一租户、UPDATE 和回读闭环；再插入重复三参数租户，断言安装器失败关闭且不批量覆盖。
+
 ### 复盘：MinIO 已可上传但系统设置仍指向官方地址
 
 - 触发场景：一键安装和桶初始化均成功，用户手工上传也成功，但读取系统设置时发现 `ApiBase`、`FileServer` 仍是空库模板中的官方地址。