@microi.net/cli 4.9.5 → 4.9.7

package/skills/microi-form-layout/references/progressive-01-3-/344/270/211/347/247/215/345/210/206/347/273/204/347/232/204/345/255/230/345/202/250/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,235 @@
+# microi-form-layout 详细参考 1
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=microi-form-layout-006 sha256=a78b000a9fee46d8394b0b6cb186702e520ab513f7eff098f2226f1158e46970 -->
+## 3. 三种分组的存储与配置
+
+### 3.1 diy_table.Tabs（表级 Tab）
+
+存储：`diy_table.Tabs`（JSON 字符串）+ 每个字段的 `diy_field.Tab`（归属 Tab 名）。
+
+```jsonc
+// diy_table.Tabs JSON 格式
+[
+  { "Id": "basic",   "Name": "基础信息", "Sort": 10 },
+  { "Id": "business","Name": "业务明细", "Sort": 20 },
+  { "Id": "attach",  "Name": "附件备注", "Sort": 30 }
+]
+```
+
+字段归属：在 `diy_field.Tab` 写 `Id`（不是 `Name`）。`Tab` 留空的字段属于"非 Tab 字段"（即 `diy_table.Tabs` 之外的字段），会作为隐藏的剩余字段自动归到最后 Tab。
+
+- 字段 `Tab="basic"` → 归属"基础信息"Tab
+- 字段 `Tab=""` 且 `diy_table.Tabs` 存在 → 自动归到最后一个 Tab 的剩余字段
+- 字段 `Tab=""` 且 `diy_table.Tabs` 不存在 → 全部在第一屏平铺
+
+**不推荐用法**：把 `diy_table.Tabs` 拆出 3 个 Tab、每个 Tab 内只有 2~3 个字段。这会让用户必须点击 3 次 Tab 才能看完一张表，且首屏只看到 2~3 个字段。
+
+### 3.2 字段级 Tabs 控件（`diy_field.Component='Tabs'`）
+
+存储：`diy_field` 行 + `Config.FieldTabs`（JSON）。
+
+```jsonc
+// diy_field 必要字段
+{
+  "Id": "TabsField_Main",
+  "Name": "TabsMain",
+  "Label": "主分组",
+  "Component": "Tabs",
+  "Type": "varchar(50)",
+  "Sort": 50,
+  "Visible": 0,        // 通常设为 0，因为 Tabs 本身是布局控件
+  "AppVisible": 0,
+  "Config": "{\"FieldTabs\":{...}}"
+}
+
+// Config.FieldTabs
+{
+  "ScopeMode": "FieldCount",   // 或 "Manual"
+  "TotalFieldCount": 0,        // 0 表示直到下一个 Tabs
+  "DefaultActiveKey": "tab1",
+  "Type": "card",               // "" | "card" | "border-card"
+  "Position": "top",            // top | bottom | left | right
+  "Stretch": false,
+  "ShowFieldCount": true,
+  "CaptureRest": true,
+  "Description": "",
+  "Theme": "default",
+  "Tabs": [
+    { "Key": "tab1", "Title": "页签一", "Icon": "fas fa-info-circle", "FieldCount": 6, "Disabled": false }
+  ]
+}
+```
+
+**作用范围**：从该 Tabs 字段开始，到下一个 `Component in (Tabs, CollapseGroup, Divider)` 字段为止。
+
+### 3.3 字段级 CollapseGroup 折叠分组（`diy_field.Component='CollapseGroup'`）
+
+存储：`diy_field` 行 + `Config.CollapseGroup`（JSON）。
+
+```jsonc
+// diy_field 必要字段
+{
+  "Id": "CollapseGroup_MRP",
+  "Name": "MrpGroup",
+  "Label": "MRP 运算",
+  "Component": "CollapseGroup",
+  "Type": "",
+  "Sort": 120,
+  "Visible": 1,
+  "AppVisible": 1,
+  "FormWidth": 24,
+  "Config": "{\"CollapseGroup\":{...}}"
+}
+
+// Config.CollapseGroup
+{
+  "DefaultCollapsed": false,            // 默认展开；高频访问分组可设 false
+  "ScopeMode": "UntilNextGroup",        // 直到下一个折叠/Tab/Divider
+  "FieldCount": 5,                      // ScopeMode=FieldCount 时生效
+  "Description": "MRP 运算结果与时间",
+  "Icon": "fas fa-calculator",
+  "Theme": "primary",                    // default | primary | success | warning | danger
+  "ShowFieldCount": true
+}
+```
+
+**作用范围**：从该 CollapseGroup 字段开始，到下一个 `Component in (Tabs, CollapseGroup, Divider)` 字段为止。
+
+**默认值硬规则**：`CollapseGroup` 必须保存 `FormWidth=24`（PC 表单 100% 宽度）；
+`Config.CollapseGroup.ShowFieldCount` 省略时必须补为 `true`。只有用户明确要求隐藏数量时
+才允许写 `ShowFieldCount=false`，只有用户明确要求非整行实验布局时才允许覆盖宽度。
+
+**与 Tab 的关键区别**：所有 CollapseGroup 标题**始终可见**，分组内字段**默认展开**或**默认收起**，但所有分组的字段**都在同一页面**，可同时展开多个。
+
+### 3.4 控件视觉对比
+
+| 视觉表现 | Tabs | CollapseGroup |
+|---------|------|---------------|
+| 首屏可见字段数 | 仅一个 Tab 的字段 | **所有分组的标题 + 展开分组的字段** |
+| 用户切换分组方式 | 必须点击 Tab 头 | 可直接滚动或逐个点击展开 |
+| 同时看到多组 | ❌ | ✅ |
+| 适合"展开后阅读" | ❌（频繁切换会烦） | ✅ |
+| 适合"互斥分组" | ✅ | ❌ |
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-form-layout-007 sha256=5944a965b1ac9a5c87a0e066af7f6489d2b5cd09e55fff7dc4e43d8d3a029fd6 -->
+## 7. 反例参考（必须避免）
+
+### 反例 1：MRP 运算 3 字段单独建 Tab
+
+```
+❌ 错误：
+diy_table.Tabs = [
+  { Id: 'basic',  Name: '基础信息' },     // 5 字段
+  { Id: 'mrp',    Name: 'MRP 运算' },     // 3 字段
+  { Id: 'remark', Name: '备注' }          // 1 字段
+]
+// 用户打开表单，第一屏只看到 5 个"基础信息"字段，"MRP 运算"和"备注"被藏在 Tab 里
+
+✅ 正确：
+// 不创建 diy_table.Tabs，把"MRP 运算" 3 字段用 CollapseGroup 收在表单末尾（默认展开）
+// 把"备注"也用 CollapseGroup 或 Divider 收
+// 第一屏用户能看到所有基础信息 + MRP 运算
+```
+
+### 反例 1.1：项目收款记录拆成 2/9/2 三个 Tab
+
+```
+❌ 错误：
+项目(2 个短字段) + 收款(9 个短字段) + 附件备注(2 个整行字段)分别建 Tab。
+结果是每页只有 1~5 行内容，桌面抽屉出现大面积空白，用户要切换三次才能看完整记录。
+
+✅ 正确：
+取消表级 Tab，按原顺序建立“项目信息 / 收款信息 / 附件备注”三个 CollapseGroup。
+核心组默认展开，低频附件备注可默认收起；保留原字段、数据源、必填规则和 V8 代码。
+```
+
+### 反例 2：13 字段表全平铺
+
+```
+❌ 错误：
+// 13 字段全部 Tab 留空
+// 用户必须向下滚动 3 屏才能看到所有字段
+
+✅ 正确：
+// 13 字段按业务分两组：8 字段"基础信息" + 5 字段"业务明细"
+// 用 1 个 diy_table.Tabs（基础信息 + 业务明细）
+// 或用 1 个 CollapseGroup 把"业务明细"5 字段收起
+```
+
+### 反例 3：42 字段表用 6 个 Tab
+
+```
+❌ 错误：
+// 6 个 Tab：基础(14) + 项目业主(2) + 发货通知(13) + 生产需求(3) + 审核(4) + ERP出库(4) + 其他(2)
+// 用户要点 6 次才能看完，且"项目业主"和"生产需求"这种 2~3 字段的 Tab 完全没必要
+
+✅ 正确：
+// 4 个 Tab：基础(14) + 发货通知+生产需求(16) + 审核+ERP出库(8) + 其他(4)
+// 或 3 个 Tab + 内部嵌套 CollapseGroup
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-form-layout-008 sha256=1d93c83d865ef941f62c4e8e0dd6238489645bf53367b61e6e397543447dcdbd -->
+## 8. 快速参考代码片段
+
+### 8.1 MCP 创建表级 Tab
+
+```js
+// 假设已创建 diy_table，通过 microi_update_table 设置 Tabs
+// 注意：microi_create_table 不直接接收 Tabs JSON，需创建后 microi_update_table 补全
+microi_update_table({
+  name: "yutaoliaojieguo",
+  // 暂未直接传 Tabs，需要通过 microi_update_table 文档化的方式补全
+})
+```
+
+> 实际写入 `diy_table.Tabs` 优先用 `microi_update_field` 之外的元数据写入方式或 `microi_upsert_engine` 委托接口引擎；后续 MCP 工具可补强 `Tabs` 参数。
+
+### 8.2 MCP 创建字段级 CollapseGroup
+
+```js
+// 1. 创建一个 CollapseGroup 字段
+microi_add_layout_field({
+  tableId: "01KTASHWEBE514R1XTB0WVJJRX",
+  name: "MrpGroup",
+  label: "MRP 运算",
+  component: "CollapseGroup",
+  sort: 150,
+  visible: 1,
+  appVisible: 1,
+  config: JSON.stringify({
+    CollapseGroup: {
+      DefaultCollapsed: false,
+      ScopeMode: "UntilNextGroup",
+      Description: "MRP 运算状态、批次号与时间",
+      Icon: "fas fa-calculator",
+      Theme: "primary",
+      ShowFieldCount: true
+    }
+  }),
+  confirmExecution: "MrpGroup"
+})
+
+// 工具默认写入 FormWidth=24；回读必须确认宽度为 24 且 ShowFieldCount=true。
+
+// 2. 让"MRP 运算"相关字段归属到该 CollapseGroup
+// 范围方式：把 CalcStatus、CalcBatchNo、MrpTime 三个字段的 Sort 排在 150~300 之间，
+// 下一个 CollapseGroup/Tabs/Divider 字段之前的所有字段都属于该分组
+```
+
+### 8.3 MCP 把字段 Tab 归属到 diy_table.Tabs
+
+```js
+// 创建表级 Tab
+// 1. microi_update_table 设置 diy_table.Tabs 字段（待 MCP 工具补全）
+// 2. 给字段写 Tab 归属
+microi_update_field({
+  id: "01KVTWDJ7WXB3Z60HGJ5BPTBJ0",
+  tab: "basic"  // 归属到 diy_table.Tabs.Id='basic' 的 Tab
+})
+```
+
+<!-- /microi-progressive:chunk -->

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

@@ -3,12 +3,14 @@ name: microi-frontend-sdk
 description: Microi 前端 SDK 使用规范，适用于 Vue 3、uni-app、H5、PC 网站与 Microi.Client 扩展。用于创建或修改前端请求、登录态、Token 续签、终端会话、上传、文件 URL、ApiEngine、FormEngine 或应用启动代码。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 前端 SDK
 
 所有 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 -->

package/skills/microi-left-right-layout/SKILL.md

@@ -3,7 +3,7 @@ name: microi-left-right-layout
 description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 左右树表配置规范