@microi.net/cli 4.6.2

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

@@ -0,0 +1,171 @@
+# 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 完成。只有真实内容与全部状态可操作、桌面和移动截图通过、控制台无错误、外部资源失败有降级、动效关闭后页面仍完整，才算完成。

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

@@ -0,0 +1,84 @@
+# 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-*` 组件。
+- 修改契约后至少截图一张受影响页面的桌面和移动版本。
+- 契约与实现冲突时，以当前合法源码和用户最新明确要求为准，并同步修订契约。

package/dist/microi.skills/ui-design/references/motion-and-media.md

@@ -0,0 +1,71 @@
+# Microi 动效与媒体规范
+
+## 预算先行
+
+| 项目 | 桌面建议 | 移动端建议 |
+| --- | --- | --- |
+| 首屏可读内容 | 尽快出现，不等待装饰资源 | 同左 |
+| 主转场 | 260-420ms | 220-340ms |
+| 微交互 | 140-220ms | 120-180ms |
+| 列表交错 | 30-60ms/项，最多前 8 项 | 20-40ms/项，最多前 6 项 |
+| Canvas/WebGL 像素比 | 上限 1.5-2 | 上限 1-1.5 |
+| 持续装饰动画 | 至少 4s/循环 | 默认减弱或关闭 |
+
+动画只使用 `transform`、`opacity` 和必要的 `background-position`。禁止持续动画布局属性、滤镜和阴影。
+
+## 首屏动效状态机
+
+```text
+idle -> entering -> settled -> interacting -> paused -> reduced
+```
+
+- `entering` 只运行一次，不能因局部数据更新整页重播。
+- `settled` 保留低振幅状态，主 CTA 始终可点击。
+- 页面隐藏、离开视口或系统省电时进入 `paused`。
+- `prefers-reduced-motion` 或低性能策略进入 `reduced`，直接显示最终布局。
+
+## 滚动叙事
+
+- 先把内容按无 JS 的普通页面排好，再增强 sticky 和进度。
+- 每个滚动段只映射一个明确状态；使用离散段落而非无限连续参数。
+- 粘性舞台不能捕获滚轮或阻止浏览器返回。
+- 移动端内容高度过长时取消 sticky，按图文段落顺序展示。
+
+## Canvas / WebGL
+
+- Canvas 仅负责展示；标题、按钮、表单和可访问文本保留在 DOM。
+- 初始化前显示同尺寸静态海报或骨架，失败时继续保留海报。
+- 使用 `IntersectionObserver` 控制启停，标签页隐藏时暂停 requestAnimationFrame。
+- 组件卸载时释放纹理、几何体、材质、事件和动画帧。
+- 纹理使用本地合法资源，压缩尺寸；禁止把远程大图直接作为不可控依赖。
+- 指针交互必须限定在容器，手机端改为陀螺仪前必须获得权限，否则使用静态视差。
+
+## 图片
+
+- 预览卡片先确定固定比例和 `object-fit`：人物/环境/商品通常 `cover`，完整界面/海报/移动端截图通常 `contain`。
+- 首屏关键图片提供 width/height 或 aspect-ratio，防止布局偏移。
+- 非首屏图片 `loading="lazy"`；首屏主图按需 preload，但不能一次 preload 多张大图。
+- 远程资源必须下载为本地合法资产或提供稳定降级；404 时显示有品牌感的空图，不显示破图图标。
+
+## 视频
+
+- 视频必须静音、可暂停、有海报；默认不在移动端自动播放背景视频。
+- 有声内容必须由用户主动触发，提供字幕或文字摘要。
+- 背景视频不承担唯一信息；失败后页面仍能理解和操作。
+
+## 可访问与低性能降级
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  [data-mci-ui-root] *,
+  [data-mci-ui-root] *::before,
+  [data-mci-ui-root] *::after {
+    scroll-behavior: auto !important;
+    animation-duration: .01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: .01ms !important;
+  }
+}
+```
+
+同时检查低端 Android、后台标签页、弱网、资源失败、浏览器缩放 200% 和高对比模式。视觉效果不能成为业务完成事实源。

package/dist/microi.skills/ui-design/references/product-flow-recipes.md

@@ -0,0 +1,94 @@
+# Microi 产品流程配方
+
+本文件用于登录、注册、订阅、支付、预约、权限、搜索、设置和敏感信息采集等真实产品流程。所有流程先保证任务闭环，再做视觉装饰。
+
+## 目录
+
+1. 登录与注册
+2. 首次引导
+3. 权限申请
+4. 订阅与付费
+5. 结算与支付
+6. 搜索、筛选与列表
+7. 创建与编辑
+8. 设置与个人中心
+9. 敏感资料采集
+10. 通用验收
+
+## 登录与注册
+
+- 默认只突出一种主登录方式，其他方式收进次级入口，避免并排两个完整登录系统。
+- 登录页保留返回首页、帮助和协议入口；输入错误时不清空账号，密码错误不暴露账号是否存在。
+- 验证码必须同时有图片、刷新、过期状态和请求中状态；后端未开启验证码时不渲染占位框。
+- “记住密码”明确作用范围；公共设备提供退出全部设备或不记住提示。
+- 登录成功直接进入目标页，禁止先闪过中间成功页。
+- 注册按账号 -> 验证 -> 必要资料 -> 完成分段；非必要资料延后到首次使用。
+
+## 首次引导
+
+- 开始前说明预计步骤、需要的资料、用途和能否稍后完成。
+- 每一步只问同一类信息；显示当前步骤和总步骤，但不要伪造进度百分比。
+- 支持保存草稿和恢复；关闭前说明哪些内容已保存。
+- 完成页给出下一项具体任务，不只显示庆祝插画。
+
+## 权限申请
+
+- 在系统权限弹窗前展示预说明：为什么需要、将获得什么、拒绝后还能做什么。
+- 一次只申请当前动作需要的权限；相机、定位、通知、通讯录不能在首屏批量索取。
+- 拒绝后提供设置入口和不授权替代路径，不循环弹窗。
+- 权限状态变化后立即刷新页面状态，不能要求用户重启应用。
+
+## 订阅与付费
+
+- 价值在价格之前；3-6 条图标化权益即可，避免长列表。
+- 价格写清周期、续费、试用结束、税费和取消条件；这些信息放在 CTA 附近。
+- 推荐方案用轻量边框/底色和说明强化，不用夸张倒计时或羞辱式拒绝按钮。
+- 只有一个方案时不制造无意义选择；多个方案按典型用户目标命名。
+- 购买后显示生效能力、订单入口、管理订阅和下一步。
+
+## 结算与支付
+
+- 结构顺序：商品/服务摘要 -> 地址/时间 -> 优惠 -> 支付方式 -> 金额明细 -> 提交。
+- 总金额和主按钮固定可见，但不能遮挡最后一项；金额变化时说明原因。
+- 提交后锁定重复支付并显示处理中；未知结果进入“正在确认”，不能直接当失败。
+- 支付失败保留订单和输入，提供更换方式、重试和联系客服。
+- 成功页展示订单号、核心信息、查看订单和继续使用。
+
+## 搜索、筛选与列表
+
+- 搜索框说明可搜字段；输入后提供清除、历史或建议，但不自动提交破坏输入。
+- 高频筛选放在页面表层，低频筛选进入抽屉；已选条件用可移除标签展示。
+- 排序和筛选结果数及时反馈；切换条件时保持列表容器高度并用骨架避免跳动。
+- 每个卡片/行都要有对象身份、状态、关键元数据、时间和明确点击结果。
+- 空结果区分“没有数据”和“筛选无匹配”，后者提供清除条件。
+
+## 创建与编辑
+
+- 字段按任务分组；必填项最少化，帮助文字靠近字段。
+- 实时校验只用于格式和明确约束；服务端校验在提交后映射到对应字段和顶部摘要。
+- 提交按钮具备默认、loading、成功、失败、disabled；失败不丢输入。
+- 离开脏表单前提示；自动保存要显示最后保存时间和失败状态。
+- 删除、归档、停用语义分开；不可逆操作二次确认并说明影响对象。
+
+## 设置与个人中心
+
+- 身份信息、账户安全、通知、隐私、外观、数据与帮助分组。
+- 当前值比入口名更重要时在右侧展示，例如手机号尾号、语言、主题。
+- 危险操作单独放在底部区域，不和普通设置混排。
+- 修改手机号、密码、密钥和付款方式时重新验证身份。
+- 注销前展示数据影响、冷静期、恢复方式和进度，不能只有一个红色按钮。
+
+## 敏感资料采集
+
+- 开始前说明采集内容、用途、存储方式、预计时间和所需环境。
+- 先选择证件/资料类型，再打开相机或上传；提供手工录入备选。
+- 相机界面使用深色背景、清晰取景框、实时成功边界和大触控按钮。
+- 上传中显示进度、取消、失败重试；识别后让用户核对关键字段。
+- 页面内嵌隐私和安全信号，但不使用无法验证的“绝对安全”宣传。
+
+## 通用验收
+
+- 键盘顺序、焦点环、错误关联、屏幕阅读标签和 44px 触摸目标可用。
+- 刷新、后退、重复提交、弱网、超时、服务端 4xx/5xx 都有确定结果。
+- 个人数据只在需要位置显示；日志、Toast 和错误信息不得泄露 token、SQL 或内部表名。
+- 390px 移动端不横向滚动，键盘弹起不遮挡当前字段和主按钮。

package/dist/microi.skills/uniapp-mall-assets/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: uniapp-mall-assets
+description: Microi UniApp、H5、商城与 PC 页面中的上传图片、附件、FileServer、私有文件临时 URL 和富文本资源安全规范。
+---
+
+# Microi UniApp / 商城资源路径规范
+
+本 Skill 只描述平台通用资源规则。不得写入客户名称、真实 `OsClient`、客户应用路径、客户接口 Key 或特定商城结算规则。
+
+## 先识别资源类型
+
+Microi 上传字段通常保存对象存储 Key 或相对路径，例如 `/demo/product/20260101/p1.jpg`。页面不能把相对路径直接交给 `<image>` / `<img>`，也不能一律拼接 API Base。
+
+| 类型 | 处理方式 |
+|---|---|
+| 已允许的 `https://` 绝对地址 | 校验协议和允许域名后使用 |
+| 公有对象存储相对路径 | 拼接当前租户 `FileServer` |
+| `/file/...` 平台本地文件路由 | 拼接当前 API Base |
+| 私有对象 | 后端鉴权后签发短期 URL，前端只使用临时 URL |
+| `blob:` | 仅用于本页创建且能及时 `revokeObjectURL` 的预览 |
+| `data:` | 仅允许经过大小和 MIME 校验的图片预览；禁止用于富文本任意 HTML |
+
+`FileServer` 是对象存储/CDN 地址，不等同于 API 服务。租户切换时必须使用当前 `OsClient` 的运行期配置，禁止在源码中写死域名或租户目录。
+
+## 统一资源解析函数
+
+项目应在共享请求/资源模块中实现一个 `resolveAssetUrl`，所有页面复用同一逻辑：
+
+```js
+export function resolveAssetUrl(raw, {
+  apiBase,
+  fileServer,
+  allowedHosts = []
+}) {
+  const value = String(raw || '').trim();
+  if (!value) return '';
+
+  if (/^https:\/\//i.test(value)) {
+    const host = new URL(value).hostname.toLowerCase();
+    return allowedHosts.includes(host) ? value : '';
+  }
+  if (/^blob:/i.test(value)) return value;
+  if (/^data:image\/(png|jpeg|gif|webp);base64,/i.test(value)) return value;
+  if (value.startsWith('/file/')) return `${apiBase.replace(/\/$/, '')}${value}`;
+
+  const relative = value.replace(/^\/+/, '');
+  return `${fileServer.replace(/\/$/, '')}/${relative}`;
+}
+```
+
+示例：
+
+```vue
+<script setup>
+import { resolveAssetUrl } from '@/utils/assets.js';
+
+function imageUrl(path) {
+  return resolveAssetUrl(path, {
+    apiBase: runtimeConfig.apiBase,
+    fileServer: runtimeConfig.fileServer,
+    allowedHosts: runtimeConfig.assetAllowedHosts
+  });
+}
+</script>
+
+<template>
+  <image v-if="row.MainImg" :src="imageUrl(row.MainImg)" mode="aspectFill" />
+</template>
+```
+
+不要让业务页面各自拼 `${API_BASE}/${path}` 或 `${FILE_SERVER}/${path}`；这会造成租户切换、私有桶、绝对 URL 和本地文件路由行为不一致。
+
+## 私有文件
+
+- 私有对象 Key 不能直接转换成可长期访问的公网地址。
+- 前端通过受保护接口请求临时 URL；后端使用 `V8.Method.GetPrivateFileUrl({ FilePathName })` 或等价受控能力。
+- 后端必须验证当前用户、`OsClient`、记录范围和字段绑定关系，不能只凭文件路径签名。
+- 临时 URL 设置较短有效期，不写入数据库、不进入长期缓存、不记录完整签名参数。
+- 下载响应使用安全的 `Content-Disposition`、MIME 白名单与文件名清洗。
+
+## 富文本与 CSS 资源
+
+- 富文本 HTML 先做标签、属性和协议白名单清洗，再改写允许的 `src` / `href`。
+- 禁止 `javascript:`、任意 `data:text/html`、事件属性和未知 iframe。
+- `background-image`、Markdown 图片、视频封面和头像与普通 `<image>` 使用同一资源解析策略。
+- 商品详情等富文本可让图片自适应宽度，但文本容器仍需留出安全边距；不得在文件名或页面文案暴露成本、导入批次、内部目录或生成规则。
+
+## 上传与预览边界
+
+- 前端扩展名、大小提示只是体验校验；服务端仍须验证单文件大小、请求总量、租户配额、真实 MIME、魔数和文件名。
+- 对象 Key 必须由服务端生成并包含租户隔离前缀，不能信任客户端提交的完整路径。
+- SVG、HTML、脚本、压缩包和办公文档按风险策略处理；可执行内容不在同源页面直接渲染。
+- 预览失败时显示受控占位，不回退到未经校验的原始 URL。
+
+## 验收清单
+
+- [ ] 公有对象、本地文件、私有对象、绝对 URL 的路径分支均有测试
+- [ ] 切换两个 `OsClient` 后使用各自 `FileServer`，无跨租户路径或缓存复用
+- [ ] 私有 URL 越权、过期、篡改签名和复制到其它账号均失败
+- [ ] 网络面板中没有硬编码客户域名、真实租户或永久签名 URL
+- [ ] 关键列表、详情、上传、预览页面有截图和真实资源加载断言
+- [ ] `blob:` URL 及时释放，大文件预览不会持续占用内存
+- [ ] 富文本协议/标签白名单可阻止 XSS
+
+参见 `microi.skills/v8-file-upload/SKILL.md`、`microi.skills/microi-uniapp-frontend/SKILL.md` 和 `microi.skills/playwright-e2e/SKILL.md`。