@microi.net/cli 4.9.6 → 4.9.8

package/skills/microi-frontend-sdk/SKILL.md

@@ -9,6 +9,8 @@ description: Microi 前端 SDK 使用规范，适用于 Vue 3、uni-app、H5、P
 
 所有 Vue 3 前端项目都应使用 `microi.skills/microi.v8.js` 作为统一的 Microi 前端 SDK。新项目不要复制旧版 Vue2/Vuex 请求封装，也不要重新手写 token、上传、文件 URL、ApiEngine 或 FormEngine 层。
 
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-000 sha256=06f944bc009a4e773ae6d5496d435d3e4a4fdb23d59107dac9cedffcfdf18f86 -->
 ## 必须采用的模式
 
 将 SDK 复制到项目源码目录，通常是：
@@ -53,6 +55,8 @@ export function createApp() {
 
 页面和业务接口模块应从项目请求模块导入已配置实例或薄封装函数，不要直接从标准 skill 文件导入。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-001 sha256=f1c2ab1fadc01dbe8ea4b9de98f7c02192c3f2cfed8b792fe62f8ef516b67d83 -->
 ## 必须委托 SDK 的能力
 
 - `ApiEngine.Run`：直接调用 `/apiengine/{key}` 时使用 `V8.ApiEngine.Run(key, data)`。
@@ -66,6 +70,8 @@ export function createApp() {
 
 `Microi.Client` 主后台运行时已内置前后端同构的 `V8.Http.Get/Post/Patch` 及对应 Response 方法；表单事件、按钮 V8 等宿主前端新代码必须优先使用 `V8.Http`，旧 `V8.Post/Get` 仅作兼容保留，其参数和兼容规则以 `v8-http-integration/SKILL.md` 为准。独立项目使用本 SDK、且不在主后台 V8 宿主中时，才使用 SDK 自身的小写 `V8.get/post`、`ApiEngine`、`FormEngine`；不要把它们与宿主旧版大写 `V8.Post/Get` 混为一谈，也不要假设浏览器可以绕过第三方接口的 CORS。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-002 sha256=5842c30af751f60041e4435efe5c993144a874cb2e9d97c41fb37d1f06d6474e -->
 ## 登录与验证码封装
 
 SDK 或项目请求模块必须提供登录所需的系统配置和验证码薄封装，不要让页面散落手写。
@@ -113,6 +119,8 @@ AI 生成的前端微服务不能假定永远在主平台 iframe/micro-app 宿
 - 登录仍签发平台 DiyToken，不创建平行 Token、平行用户表或微服务自有密码体系。失效事件回到登录态，Token 续签仍按本 Skill 的单实例规则处理。
 - 宿主额外传入 `permissionContext={sysMenuId,moduleEngineKey,diyTableId}`。SDK/服务层需要访问 FormEngine 时使用真实授权 `moduleEngineKey`；该对象不能代替后端权限，也不能成为放宽匿名接口的理由。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-003 sha256=d5d1984e6cd4efbb2340f984473146c66bb342d60bb571454c457f5673b1c68f -->
 ## 请求头规则
 
 SDK 的 `buildHeaders` 必须集中处理所有请求头，不能让页面、业务 wrapper 或上传逻辑各自拼接租户和鉴权头。
@@ -123,85 +131,8 @@ SDK 的 `buildHeaders` 必须集中处理所有请求头，不能让页面、业
 - 小程序授权登录、账号登录、刷新 Token、FormEngine、ApiEngine、上传都必须走同一套去重逻辑。
 - 验收时检查真实网络请求：不得出现 `osclient: demo, demo`、`Authorization: Bearer xxx, Bearer xxx` 这类逗号合并值。
 
-## Token、当前登录用户与当前终端登录协议
-
-Microi 后端不是只保存一个全局 Token。每个租户、每个 `sys_user` 在 Redis 中维护一份 `CurrentToken`，其中 `CurrentUser` 表示平台当前登录用户，`Tokens` 表示该用户的多个当前终端登录。每个终端项至少包含 `Token`、`ClientType`、`Did`、`IP`、`CreateTime`、`UpdateTime`；退出、管理员清除登录信息、同终端重新登录或 Token 轮换都会影响该列表。
-
-登录必须同时标记终端类型和稳定设备 Id：
-
-```js
-const V8 = createMicroiV8({
-  apiBase,
-  osClient,
-  clientType: 'Mobile', // PC / Mobile / H5 / App / WxMiniProgram / VSCode / MCP
-  didKey: 'microi_did'
-});
-
-const result = await V8.Login({
-  Account,
-  Pwd,
-  _ClientType: 'Mobile'
-});
-```
-
-- PC 后台传 `_ClientType:'PC'`，有效期读取 SaaS 引擎 `SessionAuthTimeout`，单位分钟，默认 20 分钟。
-- VS Code 传 `_ClientType:'VSCode'`，优先读取 `VSCodeAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
-- MCP 传 `_ClientType:'MCP'`，优先读取 `McpAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
-- Mobile、H5、App、各类小程序及其它非 PC 终端读取 `AccessTokenLifetime`，单位天，默认 30 天。
-- `did` 通过请求头发送，同一安装或浏览器配置必须稳定持久化；不要每次请求生成新值。标准 SDK 使用 `V8.getDid()` 自动生成和复用。
-- Token 优先从响应头 `authorization` 读取，并立即覆盖本地旧 Token；兼容接口才从响应体读取。每个受保护请求都要接收响应头中的新 Token，因为后端可能在普通请求中自动轮换。
-
-### 续签时机
-
-不要把本地固定 15 分钟当作所有终端的有效期。读取 JWT 的 `exp` 与 `MicroiTokenIssuedAt`，在到期前按以下规则触发以旧换新：
-
-```text
-提前量 = lifetime / 10
-最少提前 5 分钟
-最多提前 1 天
-```
-
-因此默认 PC 20 分钟会在约第 15 分钟续签；默认移动端、VS Code 30 天会在到期前 1 天进入续签窗口。调用：
-
-```js
-V8.startTokenMaintenance();
-
-// UniApp/App/小程序每次回到前台
-await V8.resumeAuthSession(false);
-
-// 主动以旧换新
-const result = await V8.refreshToken();
-```
-
-- Web 同时监听 `visibilitychange`、`focus`、`pageshow`。浏览器可能休眠后台标签页并暂停 `setInterval`，恢复可见时必须立即检查，不能等下一个定时周期。
-- UniApp/App/小程序在 `App.onShow` 调用 `resumeAuthSession(false)`。
-- VS Code 在扩展激活后维护 Token，并在 `vscode.window.onDidChangeWindowState` 恢复焦点时立即检查。
-- 多请求、多 Tab 续签必须 single-flight。PC 后台可使用 Web Locks；收到响应时，如果本地 Token 已被其它 Tab 更新，旧请求不得把旧 Token 覆盖回来或清掉新登录态。
-- 调用 `/api/SysUser/RefreshToken` 时同时传旧 `authorization`、当前 `OsClient`、原终端 `_ClientType`，请求头继续传稳定 `did`。不要频繁无条件换新。
-
-### 失效提示与租户边界
-
-受保护接口返回 `Code=1001/1002`，或 RefreshToken 返回登录失效时，必须原样展示后端 `Msg`，禁止覆盖成固定“登录已过期”。后端会返回 `DataAppend` 诊断：
-
-| `ReasonCode` | 处理方式 |
-|---|---|
-| `JwtExpired` / `SessionExpired` | 展示已过期分钟、小时或天以及过期时间，然后清理当前终端会话并重新登录 |
-| `TenantMismatch` | 提示 Token 所属租户与当前请求租户，切换租户或重新登录；禁止把该 Token 用于当前租户 |
-| `TokenReplaced` | 先检查本地 Token 是否已被其它 Tab/并发请求更新；有新 Token 时重试一次，否则重新登录 |
-| `SessionMissing` | 服务端登录态已退出、被管理员清除或缓存已重建；清理本地 Token 并重新登录 |
-| `AuthVersionChanged` | 后端安全版本已升级，必须重新登录 |
-| `MalformedToken` / `MissingClaims` | Token 无法继续使用，清理并重新登录 |
-
-不要显示完整 Token、用户密码或密钥。日志只记录 `ReasonCode`、终端类型、脱敏 `did`、请求租户和 Token 租户。`TokenOsClient` 只用于提示和诊断，真正鉴权仍以服务端签名、租户和 Redis 当前终端列表为准。
-
-### Token 验收
-
-- PC、移动端、VS Code 分别登录，回读 JWT `ClientType`、`Did` 和有效期，确认命中对应 SaaS 配置。
-- 模拟页面隐藏超过 PC 有效期后恢复，确认先执行续签；若已无法续签，提示精确显示过期时长。
-- 使用 A 租户 Token 请求 B 租户，确认返回 `TenantMismatch`，提示同时包含 Token 租户与当前租户且不泄漏 Token。
-- 同一旧 Token 并发调用两次 RefreshToken，确认复用同一新 Token，后续请求成功。
-- 管理员调用 `ClearUserLoginInfo` 后，旧 Token 返回 `SessionMissing` 或等价明确原因，前端不再循环续签。
-
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-004 sha256=c5f546fd4ef770459d42239b40af81d52399a3623340472b703cffe09a7b5d1e -->
 ## 上传规则
 
 `V8.uploadFile` 是 Microi 前端唯一允许的上传入口。SDK 实现必须：
@@ -218,6 +149,8 @@ const result = await V8.refreshToken();
 
 当上传突然报 `移动端文件上传路径不合法！` 时，先检查实际 multipart 表单字段和请求头。在 Microi 移动端/会员 Token 流程中，后端会在 HDFS 上传前校验 `Path`；错误的 `Content-Type` 会导致后端读不到表单字段，并表现为路径错误。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-005 sha256=1a9d0a33adbff849decf01d114e72cad96f80a6122f0b281cecf9092bbcd0c42 -->
 ## 项目封装规则
 
 面向业务页面的函数名要保持稳定。如果已有项目导出 `callEngine`、`formEngineGet`、`getImageUrl`、`parseImages` 或 `uploadFile`，保留这些导出，内部委托给 `V8`。这样既能统一 SDK，又能避免大面积改页面。
@@ -240,77 +173,10 @@ export function getImageUrl(value) {
 uni.request({ url: apiBase + '/apiengine/' + key, header: { Token: token } });
 ```
 
-## 仅支持 Vue 3
-
-新的 Microi 前端工作只支持 Vue 3。不要把 Vue2、Vuex、`Vue.prototype` 或 Vue2/uni-app 条件编译加入 `microi.v8.js`。状态管理属于项目本身，通常使用 Pinia 或本地组合函数；SDK 只负责平台访问、请求、鉴权、上传、资源 URL 和小工具。
-
-## Key-Value 枚举的跨端约定（强制）
-
-- PC、UniApp、小程序和 Web 页面遇到简单枚举时，应从字段元数据或业务接口返回的公开 `{Key,Value}` 选项获取数据源；`Value` 只负责展示，`Key` 才能进入表单值、URL、缓存键和接口筛选参数。
-- 不得把中文 `Value` 当作查询条件，也不得在各端复制维护互相漂移的中文/英文映射。若业务接口已返回选项投影，优先直接消费；本地常量只能作为接口暂时不可用时的同 Key 兜底。
-- 页面 URL 需要保存筛选状态时写入稳定英文 Key，返回页面后按 Key 恢复选中项；切换语言只替换 Value，不得改变 URL 和数据库值。
-- 兼容历史数据时，客户端可以短期识别旧 Value，但提交和新 URL 必须立即归一为 Key；长期迁移由服务端完成并回读验证。
-
-## 界面层独立
-
-SDK 不得导入 Element Plus、uni-ui、uView、TDesign、FirstUI、Pinia、Vue Router 或 axios。界面反馈通过可配置适配器提供：
-
-- `toast(message)`
-- `confirm(message)`
-- `onAuthExpired(body, V8)`
-- optional `requestAdapter(options)`
-
-这样同一个 SDK 才能同时用于 uni-app、PC 网站、后台扩展页面和文档演示。
-
-## 验证
-
-将项目改为使用 SDK 后：
-
-- 运行相关构建或类型检查。
-- 至少测试一次需要登录的 ApiEngine 调用和一次匿名调用。
-- 用 `assetUrl` 测试一个图片或上传 JSON 字段。
-- 如果任务涉及鉴权，测试 Token 过期行为。
-- 对 uni-app H5，同时验证移动视口和 PC 浏览器手机壳下 SDK 正常工作。
-
-### 复盘：生产构建被 `.env.local` 的 localhost 地址污染
-
-- 触发场景：本地开发通过 `.env.local` 指向 `localhost` API，发布后的官网仍请求开发者电脑的 loopback 地址，线上出现 `Failed to fetch`。
-- 根因：Vite 会在所有模式加载 `.env.local`；它不是仅开发模式文件。若生产模式没有更高优先级配置，loopback 地址会被编译进正式产物。
-- 通用规则：本地 API 只写入 `.env.development.local`；生产项目必须提供 `.env.production`。独立官网还要在统一 ApiBase 解析层拒绝“生产构建或非本地域名 + localhost/127.0.0.1/::1”，并安全回退到明确的正式 API。
-- 自动化检查：生产构建后扫描 JS 产物不得包含本地 ApiBase，并在正式域名上下文断言接口请求 origin 等于配置的生产 API；本地 `npm run dev` 仍应命中开发 API。
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
 
-## 搭配 MCI-UI
-
-SDK 负责平台能力，MCI-UI 负责产品界面。新的 Microi Vue3 项目应同时使用：
-
-- `microi.skills/microi.v8.js`：请求、Token、上传、文件 URL、ApiEngine/FormEngine。
-- `Microi.UI/src/theme`：`--mci-*` 设计变量。
-- `Microi.UI/src/uniapp`：移动端/UniApp 组件。
-- `Microi.UI/src/web`：PC 官网和响应式网站组件。
-
-不要在 SDK 内解决界面状态、骨架屏、富文本间距或安全区布局。这一层应使用 MCI-UI 组件处理。
-
-## MicroApp 宿主 Token 同步
-
-Vue3 前端微服务通过 `window.microApp.getData()` 接收主平台上下文时，不能只把 `token` 放进普通配置对象后假设请求会自动携带。标准 `microi.v8.js` 必须支持 `config.token`，且 `getToken()` 要优先读取运行时 token，再回退到 `storage[tokenKey]`。微服务必须复用同一个 V8 客户端实例，不能在每次按钮点击时重新 `createMicroiV8()`。
-
-`getData()` 中的 Token 是宿主传入的快照，只能用于首次引导或宿主确实下发了不同值时更新；不能在每次 `configureMicroiV8()` 时用旧快照覆盖 SDK 已从响应头取得的新 Token。推荐同时配置 `onTokenChanged`，把新 Token 与发起请求所用的旧 Token 回传宿主，宿主通过 `DiyCommon.ApplyAuthorizationToken(newToken, requestToken)` 接力并防止多标签页旧响应回写：
-
-```js
-const microiV8 = V8; // 模块级单例
-let appliedHostToken = '';
-
-microiV8.configure({
-  apiBase: ctx.apiBase,
-  osClient: ctx.osClient,
-  onTokenChanged: (token, requestToken) => {
-    window.microApp?.dispatch?.({ type: 'micro-app:token', data: { token, requestToken } });
-  }
-});
-if (ctx.token && ctx.token !== appliedHostToken) {
-  appliedHostToken = ctx.token;
-  microiV8.setToken(ctx.token);
-}
-```
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
 
-普通 `request`、浏览器 `fetch(FormData)` 上传和 `uni.uploadFile` 都必须读取响应头的新 Token。验收时必须连续执行至少两个需要登录态的请求（前一个允许发生 Token 轮换），确认后一个仍返回 `Code=1`；不能只看页面首屏渲染成功。
+- [references/progressive-01-token-当前登录用户与当前终端登录协议.md](references/progressive-01-token-当前登录用户与当前终端登录协议.md)：Token、当前登录用户与当前终端登录协议；仅支持 Vue 3；Key-Value 枚举的跨端约定（强制）；界面层独立；验证；搭配 MCI-UI；MicroApp 宿主 Token 同步
+<!-- microi-progressive:end -->

package/skills/microi-frontend-sdk/references/progressive-01-token-/345/275/223/345/211/215/347/231/273/345/275/225/347/224/250/346/210/267/344/270/216/345/275/223/345/211/215/347/273/210/347/253/257/347/231/273/345/275/225/345/215/217/350/256/256.md

@@ -0,0 +1,171 @@
+# microi-frontend-sdk 详细参考 1
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=microi-frontend-sdk-006 sha256=a834ee9855361ec5ed3f466de8d8fef53de89e40a6882b563694471d060a0dfe -->
+## Token、当前登录用户与当前终端登录协议
+
+Microi 后端不是只保存一个全局 Token。每个租户、每个 `sys_user` 在 Redis 中维护一份 `CurrentToken`，其中 `CurrentUser` 表示平台当前登录用户，`Tokens` 表示该用户的多个当前终端登录。每个终端项至少包含 `Token`、`ClientType`、`Did`、`IP`、`CreateTime`、`UpdateTime`；退出、管理员清除登录信息、同终端重新登录或 Token 轮换都会影响该列表。
+
+登录必须同时标记终端类型和稳定设备 Id：
+
+```js
+const V8 = createMicroiV8({
+  apiBase,
+  osClient,
+  clientType: 'Mobile', // PC / Mobile / H5 / App / WxMiniProgram / VSCode / MCP
+  didKey: 'microi_did'
+});
+
+const result = await V8.Login({
+  Account,
+  Pwd,
+  _ClientType: 'Mobile'
+});
+```
+
+- PC 后台传 `_ClientType:'PC'`，有效期读取 SaaS 引擎 `SessionAuthTimeout`，单位分钟，默认 20 分钟。
+- VS Code 传 `_ClientType:'VSCode'`，优先读取 `VSCodeAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- MCP 传 `_ClientType:'MCP'`，优先读取 `McpAccessTokenLifetime`，否则读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- Mobile、H5、App、各类小程序及其它非 PC 终端读取 `AccessTokenLifetime`，单位天，默认 30 天。
+- `did` 通过请求头发送，同一安装或浏览器配置必须稳定持久化；不要每次请求生成新值。标准 SDK 使用 `V8.getDid()` 自动生成和复用。
+- Token 优先从响应头 `authorization` 读取，并立即覆盖本地旧 Token；兼容接口才从响应体读取。每个受保护请求都要接收响应头中的新 Token，因为后端可能在普通请求中自动轮换。
+
+### 续签时机
+
+不要把本地固定 15 分钟当作所有终端的有效期。读取 JWT 的 `exp` 与 `MicroiTokenIssuedAt`，在到期前按以下规则触发以旧换新：
+
+```text
+提前量 = lifetime / 10
+最少提前 5 分钟
+最多提前 1 天
+```
+
+因此默认 PC 20 分钟会在约第 15 分钟续签；默认移动端、VS Code 30 天会在到期前 1 天进入续签窗口。调用：
+
+```js
+V8.startTokenMaintenance();
+
+// UniApp/App/小程序每次回到前台
+await V8.resumeAuthSession(false);
+
+// 主动以旧换新
+const result = await V8.refreshToken();
+```
+
+- Web 同时监听 `visibilitychange`、`focus`、`pageshow`。浏览器可能休眠后台标签页并暂停 `setInterval`，恢复可见时必须立即检查，不能等下一个定时周期。
+- UniApp/App/小程序在 `App.onShow` 调用 `resumeAuthSession(false)`。
+- VS Code 在扩展激活后维护 Token，并在 `vscode.window.onDidChangeWindowState` 恢复焦点时立即检查。
+- 多请求、多 Tab 续签必须 single-flight。PC 后台可使用 Web Locks；收到响应时，如果本地 Token 已被其它 Tab 更新，旧请求不得把旧 Token 覆盖回来或清掉新登录态。
+- 调用 `/api/SysUser/RefreshToken` 时同时传旧 `authorization`、当前 `OsClient`、原终端 `_ClientType`，请求头继续传稳定 `did`。不要频繁无条件换新。
+
+### 失效提示与租户边界
+
+受保护接口返回 `Code=1001/1002`，或 RefreshToken 返回登录失效时，必须原样展示后端 `Msg`，禁止覆盖成固定“登录已过期”。后端会返回 `DataAppend` 诊断：
+
+| `ReasonCode` | 处理方式 |
+|---|---|
+| `JwtExpired` / `SessionExpired` | 展示已过期分钟、小时或天以及过期时间，然后清理当前终端会话并重新登录 |
+| `TenantMismatch` | 提示 Token 所属租户与当前请求租户，切换租户或重新登录；禁止把该 Token 用于当前租户 |
+| `TokenReplaced` | 先检查本地 Token 是否已被其它 Tab/并发请求更新；有新 Token 时重试一次，否则重新登录 |
+| `SessionMissing` | 服务端登录态已退出、被管理员清除或缓存已重建；清理本地 Token 并重新登录 |
+| `AuthVersionChanged` | 后端安全版本已升级，必须重新登录 |
+| `MalformedToken` / `MissingClaims` | Token 无法继续使用，清理并重新登录 |
+
+不要显示完整 Token、用户密码或密钥。日志只记录 `ReasonCode`、终端类型、脱敏 `did`、请求租户和 Token 租户。`TokenOsClient` 只用于提示和诊断，真正鉴权仍以服务端签名、租户和 Redis 当前终端列表为准。
+
+### Token 验收
+
+- PC、移动端、VS Code 分别登录，回读 JWT `ClientType`、`Did` 和有效期，确认命中对应 SaaS 配置。
+- 模拟页面隐藏超过 PC 有效期后恢复，确认先执行续签；若已无法续签，提示精确显示过期时长。
+- 使用 A 租户 Token 请求 B 租户，确认返回 `TenantMismatch`，提示同时包含 Token 租户与当前租户且不泄漏 Token。
+- 同一旧 Token 并发调用两次 RefreshToken，确认复用同一新 Token，后续请求成功。
+- 管理员调用 `ClearUserLoginInfo` 后，旧 Token 返回 `SessionMissing` 或等价明确原因，前端不再循环续签。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-007 sha256=32ff522b3d30d94eb6cc1747b1f1238e35c1c3d43091f3ce308067e320ecb2a4 -->
+## 仅支持 Vue 3
+
+新的 Microi 前端工作只支持 Vue 3。不要把 Vue2、Vuex、`Vue.prototype` 或 Vue2/uni-app 条件编译加入 `microi.v8.js`。状态管理属于项目本身，通常使用 Pinia 或本地组合函数；SDK 只负责平台访问、请求、鉴权、上传、资源 URL 和小工具。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-008 sha256=0c59d00b2e54dd61d194d6246dd787a456ab8f12d4abe6dc330b002f41d7ee26 -->
+## Key-Value 枚举的跨端约定（强制）
+
+- PC、UniApp、小程序和 Web 页面遇到简单枚举时，应从字段元数据或业务接口返回的公开 `{Key,Value}` 选项获取数据源；`Value` 只负责展示，`Key` 才能进入表单值、URL、缓存键和接口筛选参数。
+- 不得把中文 `Value` 当作查询条件，也不得在各端复制维护互相漂移的中文/英文映射。若业务接口已返回选项投影，优先直接消费；本地常量只能作为接口暂时不可用时的同 Key 兜底。
+- 页面 URL 需要保存筛选状态时写入稳定英文 Key，返回页面后按 Key 恢复选中项；切换语言只替换 Value，不得改变 URL 和数据库值。
+- 兼容历史数据时，客户端可以短期识别旧 Value，但提交和新 URL 必须立即归一为 Key；长期迁移由服务端完成并回读验证。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-009 sha256=2e428f404342ad21af261e5f5876e34e2b9fc9455791bf0ad73ff4ad5b3e2ed0 -->
+## 界面层独立
+
+SDK 不得导入 Element Plus、uni-ui、uView、TDesign、FirstUI、Pinia、Vue Router 或 axios。界面反馈通过可配置适配器提供：
+
+- `toast(message)`
+- `confirm(message)`
+- `onAuthExpired(body, V8)`
+- optional `requestAdapter(options)`
+
+这样同一个 SDK 才能同时用于 uni-app、PC 网站、后台扩展页面和文档演示。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-010 sha256=ee237c45899f7204d3da1a2d589a89268c2db2a9b765f68fc7097eadf8da7104 -->
+## 验证
+
+将项目改为使用 SDK 后：
+
+- 运行相关构建或类型检查。
+- 至少测试一次需要登录的 ApiEngine 调用和一次匿名调用。
+- 用 `assetUrl` 测试一个图片或上传 JSON 字段。
+- 如果任务涉及鉴权，测试 Token 过期行为。
+- 对 uni-app H5，同时验证移动视口和 PC 浏览器手机壳下 SDK 正常工作。
+
+### 复盘：生产构建被 `.env.local` 的 localhost 地址污染
+
+- 触发场景：本地开发通过 `.env.local` 指向 `localhost` API，发布后的官网仍请求开发者电脑的 loopback 地址，线上出现 `Failed to fetch`。
+- 根因：Vite 会在所有模式加载 `.env.local`；它不是仅开发模式文件。若生产模式没有更高优先级配置，loopback 地址会被编译进正式产物。
+- 通用规则：本地 API 只写入 `.env.development.local`；生产项目必须提供 `.env.production`。独立官网还要在统一 ApiBase 解析层拒绝“生产构建或非本地域名 + localhost/127.0.0.1/::1”，并安全回退到明确的正式 API。
+- 自动化检查：生产构建后扫描 JS 产物不得包含本地 ApiBase，并在正式域名上下文断言接口请求 origin 等于配置的生产 API；本地 `npm run dev` 仍应命中开发 API。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-011 sha256=81ac75e383ea5a32ae45aeff1276fc2b8f56141961e70cc3956ae818aaf2fa1d -->
+## 搭配 MCI-UI
+
+SDK 负责平台能力，MCI-UI 负责产品界面。新的 Microi Vue3 项目应同时使用：
+
+- `microi.skills/microi.v8.js`：请求、Token、上传、文件 URL、ApiEngine/FormEngine。
+- `Microi.UI/src/theme`：`--mci-*` 设计变量。
+- `Microi.UI/src/uniapp`：移动端/UniApp 组件。
+- `Microi.UI/src/web`：PC 官网和响应式网站组件。
+
+不要在 SDK 内解决界面状态、骨架屏、富文本间距或安全区布局。这一层应使用 MCI-UI 组件处理。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-012 sha256=d869adb0abd87d9ba03b58faa84944a61895773a6c3642f5c20c8a03e315a2ce -->
+## MicroApp 宿主 Token 同步
+
+Vue3 前端微服务通过 `window.microApp.getData()` 接收主平台上下文时，不能只把 `token` 放进普通配置对象后假设请求会自动携带。标准 `microi.v8.js` 必须支持 `config.token`，且 `getToken()` 要优先读取运行时 token，再回退到 `storage[tokenKey]`。微服务必须复用同一个 V8 客户端实例，不能在每次按钮点击时重新 `createMicroiV8()`。
+
+`getData()` 中的 Token 是宿主传入的快照，只能用于首次引导或宿主确实下发了不同值时更新；不能在每次 `configureMicroiV8()` 时用旧快照覆盖 SDK 已从响应头取得的新 Token。推荐同时配置 `onTokenChanged`，把新 Token 与发起请求所用的旧 Token 回传宿主，宿主通过 `DiyCommon.ApplyAuthorizationToken(newToken, requestToken)` 接力并防止多标签页旧响应回写：
+
+```js
+const microiV8 = V8; // 模块级单例
+let appliedHostToken = '';
+
+microiV8.configure({
+  apiBase: ctx.apiBase,
+  osClient: ctx.osClient,
+  onTokenChanged: (token, requestToken) => {
+    window.microApp?.dispatch?.({ type: 'micro-app:token', data: { token, requestToken } });
+  }
+});
+if (ctx.token && ctx.token !== appliedHostToken) {
+  appliedHostToken = ctx.token;
+  microiV8.setToken(ctx.token);
+}
+```
+
+普通 `request`、浏览器 `fetch(FormData)` 上传和 `uni.uploadFile` 都必须读取响应头的新 Token。验收时必须连续执行至少两个需要登录态的请求（前一个允许发生 Token 轮换），确认后一个仍返回 `Code=1`；不能只看页面首屏渲染成功。
+<!-- /microi-progressive:chunk -->