@microi.net/cli 5.1.9 → 5.2.1

package/skills/README.md

@@ -8,7 +8,7 @@
 
 ## 包含的 Skills
 
-当前仓库包含 63 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
+当前仓库包含 64 个 `SKILL.md`。以下清单按任务类型组织；AI 必须先完整读取与当前任务匹配的 Skill，再执行源码、MCP、文档或交付操作。
 
 ### V8 引擎核心（后端）
 
@@ -66,6 +66,7 @@
 | **ai-engine** | 模型代理、NL2SQL/NL2V8、Schema/Skill 关键词检索与可选向量融合 | `ai-engine/SKILL.md` |
 | **ai-platform-governance** | 门户/身份/配置/发布、服务韧性、Trace/日志、资产协作与可恢复导入 | `ai-platform-governance/SKILL.md` |
 | **app-store** | 应用包、Manifest、后台安装、差异升级、回滚和验收 | `app-store/SKILL.md` |
+| **microi-sso** | 双向 OIDC/SAML2/CAS、账号映射、Secret/证书、官方商城发布与伙伴联调 | `microi-sso/SKILL.md` |
 
 ### 项目交付、前端与移动端
 

package/skills/app-store/SKILL.md

@@ -33,10 +33,10 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 ## 接口引擎资源所有权（强制）
 
 - 新发布包必须声明 `ResourcePolicies.ApiEngines`，不得再依赖“同 Key 直接覆盖”。官方不可随租户修改的核心使用 `{ Ownership:'Application', UpgradePolicy:'Managed' }`；提供给租户改业务的 Hook 使用 `{ Ownership:'Tenant', UpgradePolicy:'CreateIfMissing' }`。
-- 发布器从上一版 `AppPakcet.SysApiEngines` 计算 `BaseHash`；导入成功后把本版摘要写入 `sys_microistoreversion.InstallResult.ResourceState.ApiEngines`。更新判定固定为 Base/Local/Incoming：`Local == Base` 才允许更新；`Local != Base && Local != Incoming` 必须回滚并报告冲突，禁止静默覆盖。
+- 发布器从上一版 `AppPakcet.SysApiEngines` 计算 `BaseHash`；导入成功后把本版摘要写入 `sys_microistoreversion.InstallResult.ResourceState.ApiEngines`。普通/社区应用仍按 Base/Local/Incoming 三方保护：`Local == Base` 才更新，`Local != Base && Local != Incoming` 必须冲突回滚。唯一覆盖例外是从固定 `https://api.itdos.com + iTdos` 实时回读并校验为官方 `ApplicationType=Platform` 的应用：其中 `Ownership=Application + UpgradePolicy=Managed` 属于平台发行物，安装/更新按包覆盖本地差异；离线包、自报官方、非 Platform 来源都不能获得该权限。
 - `CreateIfMissing` 只在目标 Key 不存在时创建，存在时不得对齐 Id、源码、启用状态或其它字段。扩展模板发布后即归租户维护；后续版本禁止把同一 Key 改回 `Managed` 接管，确需新的官方核心时发布新 Key 并显式迁移。
-- 官方功能采用“Managed 核心 + CreateIfMissing Hook”。核心只提供稳定协议和默认行为；客户日志、写表、通知和业务动作放 Hook，并以稳定 `EventId`、唯一约束或 outbox 幂等。安全核心冲突不自动三方合并代码。
-- 历史包未声明策略时只能按旧兼容流程安装；重新发布时发布器必须生成策略。验收至少覆盖首次安装、未修改核心升级、核心被改后冲突回滚、Hook 被改后保持原样、重复安装和两节点竞态。
+- 官方功能采用“Managed 核心 + CreateIfMissing Hook”。核心只提供稳定协议和默认行为，并在可信官方 Platform 包更新时覆盖升级；客户日志、写表、通知和业务动作放 Hook，并以稳定 `EventId`、唯一约束或 outbox 幂等。`CreateIfMissing` 一旦交给租户维护，即使后续官方包误改为 Managed 也必须冲突回滚。
+- 历史包未声明策略时只能按旧兼容流程安装；重新发布时发布器必须生成策略。验收至少覆盖首次安装、可信官方 Managed 本地有差异仍覆盖、普通应用核心差异冲突回滚、Hook 被改后保持原样、重复安装、两节点竞态，以及官方发布数据库连 `ValidateOnly` 也禁止执行安装器。
 
 ## 安装流程
 
@@ -58,8 +58,10 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 - 官方平台是应用发布源，连安装器的 `ValidateOnly` 也必须拒绝，避免通过“只验证”绕过发布源隔离。发布源只做包正文、版本和资产 Hash 回读；真实安装、更新及预检必须切换到非官方目标租户或本地非发布源环境。
 - 所有资源按目标 `OsClient` 写入；包内不能携带源租户 `OsClient`、数据库、Redis、对象存储、MQ/MQTT、AI 或第三方密钥。
 - 按钮调用后台安装接口时，前端只传应用/版本/安装 Id；目标租户和管理员身份由 Token 确定。
-- 每次安装、更新、重新安装生成稳定 `OperationId`。官方计数服务用共享数据库事件表唯一约束去重，并在同一事务内登记事件和递增 `InstallCount`；重试、跨节点和响应丢失不得重复计数。
-- “全部安装/更新”固定只处理 `ApplicationType=Platform` 的官方平台应用中未安装与存在新版本的项目，不得把 UniApp、Web、MicroService 或其它社区/AI 应用整库安装；已是最新版的应用不重新安装。批量计划、子项状态、checkpoint 和进度必须持久化到共享数据库/后台任务，支持多节点抢占、失败重试和重启恢复，不能依赖进程内集合或浏览器状态。
+- 每次安装、更新、重新安装生成稳定 `OperationId`。官方计数服务用共享数据库事件表唯一约束去重，并在同一事务内登记事件和递增 `InstallCount`；重试、跨节点和响应丢失不得重复计数。
+- 安装次数回传属于非阻塞幂等遥测，不是应用导入事务的成功条件。来源节点返回旧格式 `True`、空响应、非 JSON、业务失败或请求异常时，只能写入带 `OperationId`/`InstallationKey` 的 warning 诊断，不得用 `_error_` 标记或回滚已经成功导入的应用；重试仍须复用同一幂等键。
+- “全部安装/更新”固定只处理 `ApplicationType=Platform` 的官方平台应用中未安装与存在新版本的项目，不得把 UniApp、Web、MicroService 或其它社区/AI 应用整库安装；已是最新版的应用不重新安装。批量计划、子项状态、checkpoint 和进度必须持久化到共享数据库/后台任务，支持多节点抢占、失败重试和重启恢复，不能依赖进程内集合或浏览器状态。
+- 主租户批量维护全部子租户时，前端入口和接口引擎都必须校验主租户上下文及 `Level >= 9999`，再由可信控制面为每个启用子租户创建独立持久后台任务；父任务必须按子任务真实百分比聚合进度，等全部子任务终态后才成功或失败，并在通知中心保留每个租户、阶段和原始失败原因。所有子任务可立即创建，但固定商城工作器必须通过配置租户 Redis 的集群并发租约跨租户串行执行，避免共享物理库并发 DDL/元数据写入死锁；分片幂等任务使用足以覆盖短时死锁和滚动重启的有界重试预算，禁止无限重试。目标租户固定商城工作器只允许从受信任官方谱系向更高版本刷新；同版本不同源码、目标端更新版或未知谱系必须失败关闭。历史空库缺少生成实体所需物理列时，导入器须在首次 FormEngine 调用前幂等补齐并回读，不能再把真实表结构错误包装成 `Value cannot be null (source)`。
 - 必须随所有后端版本自动落地的平台基础能力，仍要封装成受信任的官方 Platform 应用包，再由升级器调用统一 `import-microi-store-package` 幂等导入；禁止把表、字段、页面或微服务复制成定制 C# 迁移。身份验证、登录方式、个人中心与租户系统设置使用 `app.microi.saas-engine.json`：携带 `mci_system_setting`、`mci_user_external_identity`、默认设置和平台内置微服务。默认行必须使用 `InsertIfMissing + ConfigKey`，只补缺失，不覆盖 `ValueSource=Tenant` 的租户值或租户后来明确关闭的功能。小型平台启动微服务应以 `Source=NotIncluded + Build=DatabaseOnly + StorageMode=db` 随程序集交付并接受 256 文件/5MB、逐文件哈希和无源码门禁，使新租户在 HDFS 故障时仍能打开商城与恢复入口；普通应用安装、源码编辑和文件能力继续失败关闭，不得伪装成全平台健康。
 - 批量任务已经以“一个应用”为外层持久化恢复单元。规模可控的小型官方包应在一个事务中完成，避免对同一包体按 8 个字段反复下载、解析和重新排队；超过字段、表、DDL、流程、随包数据或资产安全阈值的大包继续使用内部 checkpoint 分片。热更新发现旧版批量计划不含 `ApplicationType` 时，必须丢弃旧计划并重新盘点，不能继续安装历史计划中的社区应用。
 - MySQL 宽表触发 65,535 字节行内上限时，只允许把不参与索引的 `varchar` 配置列无损提升为 `mediumtext`，并把类型覆盖持久化到后台任务 checkpoint；索引列和非行宽错误必须失败关闭。发布包对长连接串、密钥、回调地址、域名/白名单等字段应直接使用 `mediumtext`，同时更新 `DiyFields` 与建表 DDL，不能长期依赖安装时猜测。

package/skills/job-engine/SKILL.md

@@ -117,7 +117,7 @@ return {
 - `V8.ApiEngine.Run` 的多层编排可以保留。新版父子单层分配隔离后，子接口不会被所有祖先重复计费，但根调用树仍有整体预算；循环调用由独立的嵌套深度上限终止。
 - 捕获失败时读取 `DataAppend.V8Limit.Code`。内存/调用树/语句/超时分别缩小批次，递归错误修复函数递归，嵌套深度错误检查循环编排；不要统一归因于服务器资源不足。
 - 可记录 `V8.Limits` 到脱敏诊断日志，但不要在每条业务数据上重复输出。
-- 接口引擎默认 `sys_apiengine.V8Limit=0`，不设置 Jint 单片预算；只有明确需要限制单片时才设为 `1` 并配置超时、语句、分配和递归值。后台任务仍优先 `HasMore + Checkpoint`，因为不限 Jint 预算不等于数据库长事务、进程常驻内存、取消、并发或节点故障风险消失。表后端事件的受控例外继续使用 `diy_table.V8Unlimited`。
+- 接口引擎和表后端事件分别使用正向 `sys_apiengine.V8Limit`、`diy_table.V8Limit`；二者默认 `0`，不设置 Jint 单片预算，只有明确需要限制单片时才设为 `1` 并配置超时、语句、分配和递归值。后台任务仍优先 `HasMore + Checkpoint`，因为不限 Jint 预算不等于数据库长事务、进程常驻内存、取消、并发或节点故障风险消失。
 
 ## MCP 工作流
 

package/skills/microi-client-frontend/references/progressive-01-3-/345/212/250/346/200/201/346/214/211/351/222/256/347/263/273/347/273/237.md

@@ -16,7 +16,7 @@
 | `PageTabs` | 列表页 Tab |
 | `ExportMoreBtns` | 导出下拉扩展 |
 
-`PageTabs.TargetSysMenuId` 是通用的跨模块页签协议。未配置时继续执行当前模块的页签 V8；配置其它 `sys_menu.Id` 时，`diy-table.vue` 使用动态路由替换当前地址，让目标模块按自身 `sys_menu / diy_table / diy_field` 完整重建，并移除旧的顶部访问标签。不得为应用商城或其它单一模块在 schema/data mixin 中增加专用数据源分支。
+`PageTabs.TargetSysMenuId` 是通用的跨模块页签协议。未配置时继续执行当前模块的页签 V8；配置其它 `sys_menu.Id` 时，`diy-table.vue` 在同一个组件实例内切换模块上下文，按目标 `sys_menu / diy_table / diy_field` 重载数据，同时保留入口路由、面包屑、顶部访问标签、宿主 Hero 和入口 PageTabs，URL 只更新 `Tab` 查询参数。入口模块是唯一 PageTabs 配置源，隐藏目标模块不得复制 PageTabs。不得为应用商城或其它单一模块在 schema/data mixin 中增加专用数据源分支。
 
 按钮显隐链路：
 

package/skills/microi-docs-coverage/references/capability-map.md

@@ -31,6 +31,7 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `more/identity-verification.md` | v8-security, v8-utilities, microi-microservice, app-store, v8-saas-multi-tenant | DiyToken、登录方式气泡、Passkey、Authenticator TOTP、Gitee/微信/GitHub、动态租户设置、严格人脸、一次性步进票据、个人中心和自动升级包 |
 | `more/office.md` | v8-export-import, microi-microservice | Office 导入导出与在线编辑集成 |
 | `more/security.md` | v8-security | 平台安全和兼容基线 |
+| `more/sso.md` | microi-sso, v8-security, app-store | 双向 OIDC/SAML2/CAS、账号映射、协议端点、安全基线、商城发布与验收 |
 | `more/sys-config.md` | v8-utilities, microi-deployment | 系统/租户配置和敏感边界 |
 | `system-engine/ai-engine.md` | ai-engine, v8-http-integration, microi-ai-application | 模型代理、License、V8.AI、MCP 对话、跨端调用和安全 |
 | `system-engine/ai-platform-governance.md` | ai-platform-governance, app-store, business-blueprint, page-engine | 门户、身份、配置、发布、服务韧性、Trace/日志、资产协作与可恢复导入 |

package/skills/microi-form-engine/SKILL.md

@@ -43,8 +43,40 @@ Config/Data、菜单查询列与缓存保持一致。
 Drawer 只服务超长复杂表单，不能作为所有 CRUD 模块的模板默认值。
    若设计器显示而运行态不显示，先检查 `InFormV8`/字段 V8 是否调用
    `V8.FieldSet(..., 'Visible', false)`、`hideField` 或传入 `HideFields`，再判断前端源码。
-
-## 物理类型底线
+
+## 表单 Banner（所有新业务表必做）
+
+标准表单 Banner 默认显示，以当前主题色约 50% 混合强度叠加深蓝灰渐变，并适配浅色、
+深色与移动端。视觉应有层次但保持清爽，标题始终维持安全对比度；统计卡片使用半透明背景
+和柔和阴影分层，避免堆叠边框。它属于表单语义，配置
+必须写入 `diy_table` 的 `FormBannerEnabled`、`FormBannerTitleField`、
+`FormBannerSubtitleField`、`FormBannerImageField`、`FormBannerIcon`、
+`FormBannerBackgroundField`、`FormBannerTagFields`、`FormBannerMetrics`，禁止写进
+`sys_menu`、`DiyConfig` 或项目定制组件。
+
+- 标题优先业务自动编号/单号/编码，再选名称或标题；副标题优先客户、项目、公司、分类、
+  日期等可读字段。
+- 左侧图片使用 `ImgUpload`。单图、多图取首图，继续遵循吾码公有/私有文件路径与授权
+  规则；图片为空时必须有语义合适的 Font Awesome 图标回退。
+- 右侧标签优先 `Select/Radio/Switch/Checkbox/SelectTree/Department` 等选项字段，最多
+  选择 3 个有业务意义的状态、类型或等级。显式 `[]` 表示不要自动标签。
+- 自动统计最多 3 项，只选择真实金额、合计、数量、成本、余额、评分、比率、进度等具有
+  明确业务口径的数值字段；必须排除 Id、排序、启用、状态、版本、分页和本页加载量。
+  存在 `TableChild` 时，默认统计必须携带完整父表/父字段/父记录授权上下文，在服务端对全部
+  关联子表数据计算行数或业务数值合计，不能只统计当前页。跨表自定义口径使用 `ApiEngineKey +
+  ValuePath + ParamMap + RefreshSeconds`，相同接口批量返回，禁止 N+1、随机数和固定演示数；
+  没有可靠指标时隐藏统计区。显式 `[]` 表示不要自动统计。
+- 兼容旧模块 Hero 时仅迁移视觉、`Source=Field` 或显式记录作用域指标；列表总数、分类数量和
+  未引用当前 `Form/RecordId` 的全局接口统计不得进入单记录 Banner，缺省时回到当前记录和
+  授权 `TableChild` 的语义统计。
+- 未配置的存量表由运行时按字段类型智能推断，不能因为物理字段为空而隐藏或展示空壳。
+  只有 `FormBannerEnabled=0` 才隐藏。
+- 完整系统 Manifest 使用 `tables[].formBanner`；未提供时 `microi_generate_system` 仍须写入
+  类型感知的默认值。逐步创建字段后调用 `microi_configure_form_banner` 并回读验证。
+- 表单设计器验收必须覆盖有/无图片、有/无统计、子表完整聚合、接口失败回退、浅色、深色、
+  PC 和窄屏，并检查文字对比度以及不存在技术字段伪统计。
+
+## 物理类型底线
 
 MCP 建模只使用：
 

package/skills/microi-form-layout/SKILL.md

@@ -18,9 +18,14 @@ Microi 吾码低代码提供 **三种** 表单分组能力，但每种都有明
 表单打开方式与分组是两个独立决策：新表默认 `FormOpenType=Dialog`、
 `FormOpenWidth=80%`。只有约 36 个以上业务字段、至少 2 个大型子表，或同等密度的重型控件
 才评估 Drawer；不能用 Drawer 代替 Tabs/CollapseGroup 的信息架构。Dialog 统一使用居中、可拖动、
-大圆角弹层；Drawer 贴边且不使用大圆角。
-
-<!-- microi-progressive:begin -->
+大圆角弹层；Drawer 贴边且不使用大圆角。
+
+`CollapseGroup` 的运行态视觉统一使用清爽的白色/主题表面卡片：短主题色指示条、紧凑
+标题、可选图标、单行副标题、标题旁轻量 `x 项` 文案，以及最右侧无底色的折叠箭头。
+不得使用整块主题色填充、蓝色大描边或醒目的实心数量胶囊；分组内容与标题属于同一张
+卡片，展开后不再嵌套第二套外框。深色模式使用 Element 主题变量，不能写死白色/蓝色。
+
+<!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=microi-form-layout-000 sha256=cade6a415454aa04f5fcf840e6d9df1323ac9751c0e3c8e1b07b360007413819 -->
 ## 1. 三种分组能力速查
 

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

@@ -54,6 +54,7 @@ description: Microi 吾码模块引擎“树形+表格/表单”左右结构配
 | `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
 | `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
 | `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
+| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
 
 ## 初始化 V8 与分页契约
 
@@ -132,6 +133,7 @@ V8.Result = {
 - 左树标题无 `undefined`、`{}`、空白重复项。
 - 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
 - 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
+- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
 - 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
 - 右侧新增数据自动写入正确外键，切换节点后不会串数据。
 - 普通用户不出现仅管理员可用的“页面配置”。

package/skills/microi-sso/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: microi-sso
+description: 设计、实现、配置、迁移、发布和验收 Microi 吾码双向 SSO 身份联邦。用于外部系统通过 OIDC、SAML2、CAS 登录吾码，或吾码作为 OIDC OP、SAML IdP、CAS Server 集成其它系统，以及 diy_sso、账号/角色映射、Secret/证书、官方应用 app.microi.sso 和真实伙伴联调。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi SSO 身份联邦
+
+## 何时使用
+
+以下任务必须使用本 Skill：
+
+- Keycloak、Entra ID、ADFS、CAS Server、企业统一身份中心登录吾码。
+- 吾码账号登录 ERP、OA、BI、门户或其它第三方系统。
+- 修改 `diy_sso`、SSO 登录页、OIDC/SAML/CAS Controller、Claim/角色映射或旧 Token SSO。
+- 发布、安装、升级或验收官方商城应用 `app.microi.sso`。
+
+固定 Gitee、微信、GitHub 登录与 Passkey/TOTP 仍以 `v8-security` 为主；当需求是可配置企业身份联邦时转到本 Skill。
+
+## 先读取什么
+
+按任务读取，不要一次加载全部参考：
+
+- 外部身份源登录吾码：读 [references/inbound.md](references/inbound.md)。
+- 吾码给第三方提供登录：读 [references/outbound.md](references/outbound.md)。
+- 表字段、Secret、证书、安全与存量迁移：读 [references/configuration-and-security.md](references/configuration-and-security.md)。
+- 测试、商城发布、目标安装与交付结论：读 [references/acceptance.md](references/acceptance.md)。
+
+源码修改前同时完整读取 `workspace-conventions/SKILL.md`；认证、DiyToken、秘密或权限任务再读 `v8-security/SKILL.md`；商城任务再读 `app-store/SKILL.md`。
+
+## 不可破坏的事实
+
+1. DiyToken 是进入吾码后的唯一平台会话入口。SSO 认证成功后签发 DiyToken，不创建第二套用户/权限 Token。
+2. 吾码向外提供的 OIDC/SAML/CAS 协议票据独立、短期、可撤销，绝不把 DiyToken 给第三方。
+3. `OsClient + ConnectionKey + Subject` 是外部主体隔离边界；所有回调、票据、缓存和审计都绑定租户。
+4. 新连接只用 OIDC、SAML2、CAS；URL Token 是迁移兼容项，不是推荐协议。
+5. Redirect URI、ACS、Destination、Audience 和 CAS service 必须精确匹配；生产端点必须 HTTPS。
+6. Secret/私钥只存 `mci_system_setting` 的受控值；`diy_sso` 只存 Setting Key。匿名接口只返回登录入口白名单投影。
+7. 外部角色、邮箱或昵称不能直接获得管理员权限。默认 `BoundOnly`，JIT 必须显式默认角色、唯一性、回收和审计。
+8. HTTP 200、构建成功、商城任务入队或包可下载都不是完整 SSO 验收。
+9. SSO 业务逻辑必须接口引擎优先：连接投影、绑定/JIT、角色与 Claim 映射、审计、登录完成和租户扩展不得重新写进 Controller。只有协议报文、签名验签、Secret/私钥隔离、一次性票据与 DiyToken 等可信原子可以保留 C#。
+10. 客户端调用应用接口使用稳定 `/api/ApiEngine/Run?OsClient=`；应用未安装时必须得到结构化错误，禁止重新依赖可能由网关缺失而 404 的动态 `/apiengine/*` 或已删除的 `/api/Sso/Capabilities` 等定制路由。
+
+## 标准工作流
+
+1. 识别方向、协议、租户、身份伙伴、用户生命周期、退出和密钥/证书责任人。
+2. 读取当前 `diy_sso` Schema、菜单、真实连接和已部署 Server/Client 版本；不要从旧截图猜测。
+3. 先选标准协议和安全 profile，再配置字段、Secret/证书 Key、Claim/角色映射。
+4. 先把业务编排写成可随应用发布的接口引擎；仅当现有 V8 无法安全完成底层原子能力时，才扩展最小 `V8.Method`，并把调用权限制到精确官方接口 Key。禁止把整个流程放进新 Controller，也禁止让原子方法接受任意租户、回调地址或 Secret。
+5. 分别验证源码/单测、后端构建、前端构建、运行时端点、浏览器 UI、真实伙伴和多节点。
+6. 平台级资源通过官方应用包发布；官方源用 `microi_itdos` 更新并发布，普通目标租户走商城安装/升级任务。
+7. 最终明确已验证与未验证边界，尤其是“配置包已发布”与“运行时代码已部署”的区别。
+
+## 官方应用合同
+
+- AppId：`app.microi.sso`
+- 名称：`SSO 身份联邦`
+- 资源：`diy_sso`、`/system/sso`、字段/布局/视图、10 个 Managed 核心接口引擎和 1 个 CreateIfMissing 租户 Hook；不发布用户绑定、连接实例、Secret、证书或示例账号。
+- `ResourcePolicies.ApiEngines` 必须逐 Key 显式声明。核心使用 `Managed/Application`；`sso_event_hook` 使用 `CreateIfMissing/Tenant`，安装后永不被官方覆盖。
+- 官方 `iTdos` 是发布源，保护性拒绝安装属于正确行为；普通租户安装才必须轮询到 `Succeeded`。
+
+## C# 与接口引擎责任线
+
+接口引擎固定承载：
+
+- `sso_capabilities`、`sso_legacy_capabilities` 的匿名白名单投影；
+- `sso_connection_runtime`、`sso_user_runtime` 的内部最小投影；
+- `sso_resolve_federated_identity` 的绑定、JIT 与角色映射；
+- `sso_outbound_claims`、`sso_protocol_event`、`sso_event_hook`；
+- `sso_complete_login`、`sso_rotate_client_secret`、`sso_legacy_token_login` 的业务编排。
+
+C# 只保留：
+
+- OIDC/SAML/CAS 原始 HTTP/重定向/XML/JWT 报文与签名验签；
+- Secret、私钥、证书和协议 Token 的可信隔离；
+- 高熵一次性 code/ticket、重放保护和 DiyToken 签发；
+- 仅允许精确 Managed Key 调用的 `CreateFederatedUser`、`CreateSsoLoginTicket`、`CompleteSsoLogin`、`RotateSsoClientSecret` 原子。
+
+新增 SSO 需求先判断是否只需修改上述接口引擎。只有缺少不可伪造、不可泄露的底层原子时才增加 V8 方法；增加后同时更新应用 `RequiredPlatformCapabilities`、后端文档、测试与最低版本。
+
+详细用户文档：`microi.doc/docs/doc/more/sso.md`。

package/skills/microi-sso/references/acceptance.md

@@ -0,0 +1,49 @@
+# 验收、商城发布与交付结论
+
+## 分层证据
+
+| 层 | 最低证据 |
+|---|---|
+| 源码 | 协议/安全原语测试，静态扫描无 Secret/Token 日志 |
+| 后端构建 | 隔离输出 `dotnet build` 成功，不覆盖共享运行目录 |
+| 前端构建 | 现代包和项目要求的兼容包完成 |
+| 应用包 | 可重复生成；Name/AppId/Version、DDL、字段数、菜单、空数据集、11 个接口引擎源码同源与 ResourcePolicies 校验 |
+| 官方商城 | `microi_itdos` 发布后回读 `sys_microistore` 与官方资源 API；状态、版本、包哈希一致 |
+| 目标租户 | 安装/升级任务终态 `Succeeded`，再读真实表、字段、菜单、安装版本 |
+| 运行时 | Capabilities、Discovery/Metadata/JWKS 和实际使用端点命中已部署程序集 |
+| 浏览器 | 登录入口、弹窗 Origin、URL 清理、管理页 7 Tab、秘密无明文 |
+| 伙伴联调 | 登录/拒绝/过期/重放/退出/停用/角色变化/轮换 |
+| 多节点 | state、code、ticket、session、撤销和缓存跨节点一致 |
+
+## 官方应用发布
+
+1. 使用官方 `microi_itdos`，核对绑定 `https://api.itdos.com` 与 `OsClient=iTdos`。
+2. 在发布源更新真实 `diy_sso`、字段、表单 Tabs 和菜单视图并回读。
+3. 导出精确菜单/表和 11 个接口引擎，不带连接数据、用户绑定、Secret、证书或示例账号；接口源码必须与 `Microi-V8-Engine/.../SSO身份联邦` 逐字同源。
+4. AppId 固定 `app.microi.sso`，PublisherType 为官方应用；10 个核心 Key 为 `Managed/Application`，`sso_event_hook` 为 `CreateIfMissing/Tenant`。
+5. 发布后从官方资源 API 读取 `app.microi.sso.json`，校验 SHA-256、版本、1 菜单、1 表、64 字段、11 个接口引擎及策略。
+6. 官方 iTdos 是发布源，安装任务被“发布源不允许安装”拒绝是保护性终态；不要绕过或伪装成成功。
+7. 普通目标租户才执行安装/更新，并轮询后台任务到终态。Pending/Running/入队不算成功。
+
+## 协议负向用例
+
+- OIDC：state/nonce/PKCE 错、code 重放、issuer/audience 错、未知 kid、过期 token、refresh 重放、回调前缀攻击。
+- SAML：签名错、过期、Audience/Destination/InResponseTo 错、Request/Assertion 重放、错误证书、未授权 ACS。
+- CAS：ticket 重放、service 不同、过期 ticket、错误租户、CAS 失败响应。
+- 通用：跨租户连接、停用用户、停用连接、SSRF 私网/回环、访问密钥会话授权、匿名读取 `diy_sso`。
+
+## 结论措辞
+
+只有真实伙伴和多节点验收也通过，才能说“该协议连接已可生产使用”。
+
+- 包已发布但 Server/Client 未部署：写“官方配置包已发布，运行时代码待部署”。
+- 端点冒烟通过但无真实 IdP/SP：写“协议端点已验证，伙伴联调待完成”。
+- 官方源安装被保护性拒绝：写“发布源保护生效，不构成普通租户安装证据”。
+- 因用户未授权输入密码而无法浏览器登录：写明 UI 登录后验收未完成，不用接口/源码代替视觉证据。
+
+## 404 与应用缺失回归
+
+- 客户端能力发现和登录完成只允许调用 `/api/ApiEngine/Run?OsClient=`，请求体携带精确 `ApiEngineKey`。
+- 在未安装 `app.microi.sso` 的租户调用通用入口，应返回结构化“接口引擎不存在”；不能返回 `/api/Sso/Capabilities` 路由 404。
+- 安装后回读 11 个 `sys_apiengine` 行并刷新缓存，再验证 `sso_capabilities` 为 `Code=1`。
+- `/api/Sso/Capabilities`、`LegacyCapabilities`、`CompleteLogin`、`RotateClientSecret` 与 `/api/SysUser/SsoPengrui` 必须保持删除，防止业务逻辑重新漂回 Controller。

package/skills/microi-sso/references/configuration-and-security.md

@@ -0,0 +1,53 @@
+# 配置、Secret、安全与迁移
+
+## diy_sso 分组
+
+- `basic`：Key、名称、方向、协议、启用、排序。
+- `oidc`：Issuer/Discovery/端点、Client、Scope、精确 Redirect URI。
+- `saml`：Entity ID、Metadata、SSO/SLO、ACS。
+- `cas`：Server URL、版本。
+- `mapping`：Subject/Account/Name/Email/Role Claim、JSON 映射、JIT。
+- `security`：Secret/证书设置 Key、签名/加密、PKCE/nonce、生命周期、私网开关。
+- `legacy`：旧 Server/Client API、TokenName、GetTokenType。
+
+`diy_sso` 是管理员专用平台表。匿名能力接口只投影 ConnectionKey、名称、协议、图标、说明和发起地址；旧兼容投影只允许同源 `/api/` 路径与安全 Token 参数名。
+
+匿名投影由 `sso_capabilities` / `sso_legacy_capabilities` 接口引擎提供；Controller 不得直接查询并返回 `diy_sso`。内部协议网关通过 StopHttp 的 `sso_connection_runtime` 取得最小运行投影。客户端统一调用 `/api/ApiEngine/Run?OsClient=`，避免应用尚未安装或网关未注册动态路由时出现 404。
+
+## Secret 与证书
+
+- `ClientSecretSettingKey` 等字段只存 `mci_system_setting` Key。
+- 第三方 Client Secret 和私钥证书使用后端 Secret 存储，不出现在日志、导出、包、浏览器或 MCP 回读。
+- 吾码对外 OIDC Client Secret 只存专用密码哈希；不能用 AES/DES 代替验证哈希。
+- SAML 验签/加密公开证书与签名/解密私钥严格区分用途。
+- 证书/签名 Key 轮换要有新旧重叠、伙伴确认、撤销和回滚窗口。
+
+## 网络和 URL
+
+所有外部 Discovery、JWKS、Metadata、Token、UserInfo 地址先过 HTTPS/SSRF 检查。默认拒绝回环、私网、链路本地、带用户信息 URL 和 DNS 重绑定；内网 IdP 只能由管理员显式开启并用网络出口白名单补强。
+
+Redirect/Logout/ACS/CAS service 使用规范化后的绝对 URL 精确比较。不要允许通配符、子域后缀、前缀或 fragment。反向代理下使用可信外部 Origin，不能根据任意 Host/Header 构造安全回调。
+
+## 账号与角色
+
+默认 `BoundOnly`。JIT 需要：
+
+- 稳定 Subject 与账号唯一性。
+- 非管理员默认角色。
+- 外部角色到 RoleId 的显式 allowlist。
+- 离职、禁用、角色收回与冲突处理。
+- 创建、匹配、拒绝和变更审计。
+
+这些规则由 Managed `sso_resolve_federated_identity` 编排。JIT 创建最终调用精确受限的 `V8.Method.CreateFederatedUser` 原子，并用平台专用带盐密码哈希写入不可登录的随机初始密码；不得回退到 DES，也不得把外部角色名直接写成平台 RoleId。
+
+不能把外部 `admin` 字符串、邮箱域或昵称直接解释为平台管理员。
+
+## LegacyToken 迁移
+
+1. 盘点旧 `ClientSsoApi/ServerSsoApi/TokenName` 和使用系统。
+2. 为每个系统选择 OIDC、SAML2 或 CAS 并建立新连接。
+3. 并行验证登录/退出和账号映射；新入口默认标准协议。
+4. URL 中的旧 Token 读取后立即清理，不写 Referer、日志或分析平台。
+5. 迁移完成后停用旧行；不要继续给新系统复制 LegacyToken。
+
+旧兼容只允许调用同源 `/api/`，绝不把 DiyToken POST 到管理员配置的任意绝对 URL。浏览器只处理 `LegacyCapabilities` 已返回连接中明确登记的 `TokenName`；不得恢复“只要 URL 出现 `?token=` 就自动登录”的无配置旁路。

package/skills/microi-sso/references/inbound.md

@@ -0,0 +1,53 @@
+# 外部身份源登录吾码
+
+## 目标流程
+
+外部身份源只证明主体身份。回调完成后按当前租户查找绑定/受控 JIT 用户，重新确认 `sys_user` 仍启用，再签发 DiyToken。菜单、表、字段、角色、部门与数据范围不从外部 Token 直接继承。
+
+## OIDC RP
+
+必须覆盖：
+
+- Authorization Code；公共客户端使用 PKCE S256。
+- 随机 state、nonce、短时效、一次性消费和原始 Origin 绑定。
+- Discovery 与 JWKS 的 HTTPS、SSRF、issuer 一致性和缓存更新。
+- id_token 签名、算法、issuer、audience、有效期、nonce；必要时再请求 UserInfo。
+- code 不能写日志、URL 清理、回调错误不泄露 Token/Secret。
+- `client_secret_basic`、`client_secret_post` 或 `none` 与伙伴注册一致。
+
+禁止 Implicit、Password Grant、宽松回调前缀、关闭签名或仅解码 JWT 不验签。
+
+## SAML SP
+
+必须覆盖：
+
+- SP Metadata、AuthnRequest、RelayState、ACS 与可选 SLO。
+- 浏览器回调使用 `/api/Sso/SamlCallback`，Assertion Consumer Service 使用 `/api/Sso/SamlAcs`。
+- Response/Assertion 签名、Destination、Issuer、Audience、时间窗口、InResponseTo。
+- Request ID 与 Assertion/Response 重放保护。
+- 加密断言时使用本租户解密私钥；验签只用伙伴公开证书。
+- NameID/Claim 到稳定 Subject 的明确规则。
+
+不能因为伙伴证书配置困难而在生产关闭签名校验。
+
+## CAS Client
+
+- service 必须是精确、受控的吾码回调 URL。
+- CAS 1.0 `/validate`、2.0 `/serviceValidate`、3.0 `/p3/serviceValidate` 按配置解析。
+- Service Ticket 单次使用、短时效、绑定 service；失败响应不能当作用户属性。
+- CAS 根地址生产使用 HTTPS，并经过 SSRF 检查。
+
+## 用户解析顺序
+
+1. 规范化 `OsClient`、连接方向和协议。
+2. 提取稳定 Subject；拒绝空值、控制字符和不稳定昵称。
+3. 先查 `mci_user_external_identity` 的精确绑定。
+4. `BoundOnly` 未绑定即拒绝；`JitMatch/JitCreate` 仅按已审核映射运行。
+5. 重新读取 `sys_user`，确认未删除、未停用。
+6. 签发 DiyToken，写不含凭据的 SSO 审计。
+
+步骤 2–5 固定由 `sso_resolve_federated_identity` 执行；协议 Controller 只把已经验签、归一化且不含原始 Token/断言的 Claim 交给该引擎。步骤 6 由 `sso_complete_login` 编排并调用一次性票据/DiyToken 原子。不要在 OIDC、SAML、CAS 三个 Controller 中各复制一套用户查询、JIT 和角色映射。
+
+## 浏览器回调
+
+弹窗消息必须同时校验 `event.source`、精确 `event.origin`、消息类型和 ConnectionKey。回调只传 90 秒左右的一次性票据；登录页再用该票据换 DiyToken。不要通过 `postMessage('*')`、URL fragment 或 Query 传 DiyToken。

package/skills/microi-sso/references/outbound.md

@@ -0,0 +1,39 @@
+# 吾码向第三方提供登录
+
+## 共同边界
+
+先验证当前交互式 DiyToken，再生成第三方协议票据。访问密钥会话不能替代用户交互授权。外部 Client/SP/service 只能读取按 Scope/映射允许的最小资料，不能获得 DiyToken、菜单权限对象或内部角色策略。
+
+## OIDC Provider
+
+应提供：
+
+- Discovery、JWKS、Authorize、Token、UserInfo。
+- 机密客户端认证与公共客户端 PKCE S256。
+- 一次性授权码，绑定 ClientId、Redirect URI、Scope、PKCE、用户、租户和过期时间。
+- 签名 id_token，校验 nonce；按客户端派生 pairwise subject。
+- 高熵不透明 Access/Refresh Token；仅保存哈希索引。
+- Refresh Token rotation/reuse detection，family 撤销。
+- Introspection、Revocation、RP-Initiated Logout 与精确 post-logout redirect。
+
+Client Secret 轮换动作只显示一次明文，持久化 PBKDF2-SHA256 哈希。签名 Key 必须有 `kid`，轮换时保留验证重叠窗口。
+
+对外 Claim 固定由 `sso_outbound_claims` 从启用用户与连接白名单生成；OIDC/SAML/CAS 协议网关只负责把同一投影编码成对应协议。Client Secret 轮换由 `sso_rotate_client_secret` 编排，并调用精确受限的可信原子生成一次性明文与持久哈希，不能恢复为 Controller 定制动作。
+
+## SAML IdP
+
+应提供 IdP Metadata、SSO、签名 Response/Assertion、可选加密和 SLO。必须校验 SP Entity ID、ACS、Destination、AuthnRequest 签名/重放；Attribute 只来自白名单映射。每个伙伴独立证书/配置，不把私钥放进应用包或前端。
+
+## CAS Server
+
+应提供 `/login`、CAS 1.0 `/validate`、CAS 2.0 `/serviceValidate`、CAS 3.0 `/p3/serviceValidate` 和 `/logout`。Service Ticket 必须：
+
+- 随机、短时、单次使用。
+- 绑定当前租户、连接、用户和精确 service。
+- 校验成功才返回用户属性；CAS 1.0 使用协议规定的 yes/no 文本。
+
+当前不实现 CAS Proxy Ticket；需要代理链时先评估改用 OIDC。
+
+## 授权页面
+
+第三方发起 Authorize/SAML/CAS 登录后，若没有有效 Provider Session，先跳到吾码登录页；登录成功回到一次性 handoff。页面必须说明目标系统、请求 Scope 和退出影响。即使后续加入 Consent，仍不能把第三方请求的任意 Scope 自动映射为吾码管理员能力。

package/skills/microi-system-delivery/SKILL.md

@@ -7,9 +7,15 @@ description: Microi 吾码从自然语言交付完整系统的总控规范。用
 
 # Microi 全系统交付复盘与总控规范
 
-本 Skill 来自一次完整业务系统交付复盘。目标是让下一套 OA、ERP、MES、CRM、商城、预约、互联网项目等 Microi 系统少走返工路：先固定事实源，再用 MCP 正确建模，最后用可视化和业务闭环测试证明可交付。
-
-<!-- microi-progressive:begin -->
+本 Skill 来自一次完整业务系统交付复盘。目标是让下一套 OA、ERP、MES、CRM、商城、预约、互联网项目等 Microi 系统少走返工路：先固定事实源，再用 MCP 正确建模，最后用可视化和业务闭环测试证明可交付。
+
+每张由 AI/MCP 创建的业务表都必须同时设计默认表单 Banner，不能只建字段和菜单。完整
+Manifest 使用 `tables[].formBanner`；未显式配置时仍按字段类型选择业务编号/名称标题、
+客户/项目副标题、首个 `ImgUpload`、状态/类型标签和真实数值指标，并写入 `diy_table`
+语义字段。跨表统计由接口引擎批量返回，禁止随机数、固定演示值和 N+1；Banner 不属于
+模块引擎或 `sys_menu`。逐步建模在字段完成后调用 `microi_configure_form_banner` 回读验收。
+
+<!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=microi-system-delivery-000 sha256=b09c3f2d05e2927322de0c42913f85813296e9001bccf31b6dc85779cbe3099f -->
 ## 交付总原则
 

package/skills/microi-system-delivery/references/progressive-01-/346/240/207/345/207/206/345/267/245/344/275/234/346/265/201.md

@@ -1,8 +1,13 @@
 # microi-system-delivery 详细参考 1
 
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=microi-system-delivery-005 sha256=e27ee98421974395b858927ab7b7fbebe27f314e54a8f616064b9c77c01ba808 -->
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+新建业务表的字段落地后必须配置默认表单 Banner：完整 Manifest 使用
+`tables[].formBanner`，逐步建模调用 `microi_configure_form_banner`。标题、图片、标签和
+统计都应来自真实字段或真实接口引擎；配置写 `diy_table`，禁止写入 `sys_menu`。即使用户
+没有逐项指定，也必须写入类型感知的合理默认值，不能交付空 Banner。
+
+<!-- microi-progressive:chunk id=microi-system-delivery-005 sha256=e27ee98421974395b858927ab7b7fbebe27f314e54a8f616064b9c77c01ba808 -->
 ## 标准工作流
 
 ### 1. 需求蓝图阶段

package/skills/microi-ui/SKILL.md

@@ -11,15 +11,19 @@ Microi.UI 是 Microi 产品共享前端设计系统。Vue 3 网站、响应式
 
 当用户要求制作 Microi 移动端应用、H5、小程序、客户门户、员工端、会员中心、官网、产品站、活动页、仪表盘或报告页，且没有指定其它设计系统时，默认使用 Microi.UI。
 
-这是自动规则。不要等用户明确说“遵循 `microi.skills/microi-ui/SKILL.md`”。只要仓库、需求、文件路径或项目上下文属于 Microi 生态，且工作涉及前端界面、网站界面、H5、uni-app、小程序、客户/员工/会员页面、报告、仪表盘或视觉打磨，就默认读取并应用本 skill。
-
-<!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=microi-ui-000 sha256=5952d38dd1ffabb11b55b833bc26c432b723159c4ad688897e3bdbbb20a03b52 -->
+这是自动规则。不要等用户明确说“遵循 `microi.skills/microi-ui/SKILL.md`”。只要仓库、需求、文件路径或项目上下文属于 Microi 生态，且工作涉及前端界面、网站界面、H5、uni-app、小程序、客户/员工/会员页面、报告、仪表盘或视觉打磨，就默认读取并应用本 skill。
+
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=microi-ui-000 sha256=1fdfec21b03bf209a64b65bc4c1d22cf443b065125d3fb7700d8e1751694394b -->
 ## 核心承诺
 
-Microi.UI 不只是组件集合，它是 AI 构建软件的视觉交付标准：
-
-- 每个首屏都必须有明确视觉锚点。
+Microi.UI 不只是组件集合，它是 AI 构建软件的视觉交付标准：
+
+- 首要产品气质是清爽、清新、易读：减少重复标题、说明、统计卡和无业务意义的装饰层，用清晰层级、稳定间距与真实内容建立品质。
+- 清爽不等于大面积空白或固定白底；页面必须在信息密度与可扫读性之间取得平衡，核心任务和主要操作应在首屏内清楚可见。
+- 每个组件和页面都必须消费语义 token，适配任意租户主题色，并同时支持亮色、暗色模式；禁止把某一种主色、白色表面或深色背景写成唯一正确外观。
+- 新增视觉验收至少覆盖一个浅色主题、一个暗色主题和一个非默认租户主题色，并检查文字、边界、状态色及焦点态的可读性。
+- 每个首屏都必须有明确视觉锚点。
 - 每个页面都必须使用有品牌意识的色彩和组件层级。
 - 每个重要操作都必须明显、美观且容易触达。
 - 每个列表、详情、表单都应基于可复用场景模式构建，而不是复制一次性 CSS。

package/skills/module-engine/SKILL.md

@@ -121,7 +121,7 @@ Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使
 
 PC 列表的固定结构顺序是“模块 Hero（标题/副标题/动态指标）→ PageTabs → 查询与表格”，Hero 必须渲染在页面多 Tab 上方。头部只使用一次性入场和一次性轻量光效，禁止持续循环动画；`prefers-reduced-motion: reduce` 必须关闭动画和过渡。
 
-PageTabs 通过 `TargetSysMenuId` 切换不同模块/表时，入口模块必须作为稳定宿主：客户端在同一个 `diy-table` 实例内加载目标模块的菜单、表、字段与列表数据，只更新当前 URL 的 `Tab` 查询参数，不替换路由、面包屑、顶部访问标签或宿主 Hero。入口模块只配置一组 PageTabs；目标菜单可隐藏导航，但只需保留目标表格设计和角色权限，不得复制同一组 PageTabs。切换时必须中止旧请求并以模块上下文版本丢弃迟到响应，失败时回滚原模块。
+PageTabs 通过 `TargetSysMenuId` 切换不同模块/表时，入口模块必须作为稳定宿主：客户端在同一个 `diy-table` 实例内加载目标模块的菜单、表、字段与列表数据，只更新当前 URL 的 `Tab` 查询参数，不替换路由、面包屑、顶部访问标签或宿主 Hero。入口模块只配置一组 PageTabs；目标菜单可隐藏导航，但只需保留目标表格设计和角色权限，不得复制同一组 PageTabs。隐藏目标菜单统一设置 `ParentId=入口菜单Id、Display=0、AppDisplay=0、HasChild=0、PageTabs=[]`，入口菜单保持 `HasChild=0` 以继续作为可点击业务入口。模块设计器必须用可搜索菜单树显示 `TargetSysMenuId` 的模块名称，不能只在运行时 JSON 中保存不可见 Id。切换时必须中止旧请求并以模块上下文版本丢弃迟到响应，失败时回滚原模块。
 
 模块首屏或跨模块切换期间，Hero 标题/指标、PageTabs、工具栏与列表必须显示与最终布局同尺寸的主题化骨架屏；不能先渲染空白旧布局再整体位移。骨架屏同样遵守 `prefers-reduced-motion: reduce`，并在无指标或无 PageTabs 时按元数据提示隐藏对应占位。
 
@@ -135,9 +135,9 @@ PageTabs 通过 `TargetSysMenuId` 切换不同模块/表时，入口模块必须
 
 ### 重要模块的统计与信息层级
 
-- 待办、库存预警、未读、逾期、待收/待付等有行动含义的菜单，主动询问并配置
-  `MenuBadgeEnabled=1` 与 `MenuBadgeApiEngineKey`。接口统一返回
-  `{ Code:1, Data:{ Value: number } }`，并按当前用户权限统计。
+- 待办、库存预警、未读、逾期、待收/待付等有行动含义的菜单，主动询问并配置
+  `MenuBadgeEnabled=1`、`MenuBadgeApiEngineKey` 与说明统计口径的 `MenuBadgeTooltip`。接口统一返回
+  `{ Code:1, Data:{ Value: number } }`，并按当前用户权限统计。
 - `Scene=List` 的 `Layout.Hero` 用 `Eyebrow/Title/Description/Metrics` 建立模块标题与
   指标条。相同 `ApiEngineKey` 的指标必须由一个聚合接口批量返回，使用 `ValuePath`
   取值；禁止一个指标一次请求。

package/skills/module-engine/references/module-config.md

@@ -26,6 +26,7 @@
 | `DefaultOrderBy` | 默认排序 |
 | `MenuBadgeEnabled` | 左侧菜单统计角标开关 |
 | `MenuBadgeApiEngineKey` | 菜单统计接口引擎 Key，返回 `Data.Value` |
+| `MenuBadgeTooltip` | 鼠标移入菜单数字角标时显示的统计口径说明；应写清对象、用户范围及待办/未读/总数等含义 |
 
 默认隐藏 Id、外键、系统字段、布局字段、上传、富文本、地图和子表等重字段。
 默认搜索优先名称、标题、编号、状态、类型、分类、负责人和时间；统计优先金额、
@@ -40,6 +41,8 @@
 
 菜单角标只用于少量待办、未读、逾期、预警等重要入口；PageTabs 与按钮角标按业务价值
 选择。相同页面的一组指标/角标使用一个批量接口，不逐指标、逐按钮、逐行请求。
+配置菜单角标时应同时配置 `MenuBadgeTooltip`；历史菜单缺少该字段时，客户端回退显示菜单名
+和原始数字，不得因提示文案缺失影响角标本身。
 自动默认值只保证旧库和漏配模块不出现空白标题，不替代业务设计；严禁用随机数或静态演示
 数字伪造统计。没有可推断业务指标时只使用真实 `DataCount/PageCount` 兜底。
 
@@ -191,7 +194,7 @@ PageTabs 可以通过 `BadgeApiEngineKey` 显示数字角标。接口按 `Button
 
 PageTabs 只表达当前模块的数据类别/状态，不能取代模块 Hero，也不能渲染到 Hero 上方。
 
-跨表 Tab 由入口模块统一配置一组 PageTabs，目标菜单只保留各自的模块设计、表绑定和角色权限，不复制 PageTabs。切换只更新当前 URL 的 `Tab` 查询参数；路由、面包屑、顶部访问标签和入口模块 Hero 保持稳定，表格上下文在原实例中切换。实现时必须取消旧请求、丢弃迟到响应并在失败时回滚，禁止按菜单名或业务表名写死。
+跨表 Tab 由入口模块统一配置一组 PageTabs，目标菜单只保留各自的模块设计、表绑定和角色权限，不复制 PageTabs。隐藏目标菜单统一设置 `ParentId=入口菜单Id、Display=0、AppDisplay=0、HasChild=0、PageTabs=[]`，入口菜单继续保持 `HasChild=0` 作为可直接点击的业务入口。模块设计器用【关联模块】可搜索菜单树展示名称、保存 `TargetSysMenuId`。切换只更新当前 URL 的 `Tab` 查询参数；路由、面包屑、顶部访问标签和入口模块 Hero 保持稳定，表格上下文在原实例中切换。实现时必须取消旧请求、丢弃迟到响应并在失败时回滚，禁止按菜单名或业务表名写死。
 
 首屏和跨模块切换应为 Hero 标题/统计、PageTabs、工具栏和列表提供与最终几何尺寸一致的主题化骨架屏；根据模块元数据判断是否预留指标区和 PageTabs，并支持 `prefers-reduced-motion: reduce`。
 

package/skills/ui-design/SKILL.md

@@ -9,17 +9,21 @@ description: Microi UI 设计系统指南。用于设计 PC Vue、Element Plus
 
 你正在为 Microi 吾码平台创建界面。所有页面、组件、弹窗必须遵循本规范，打造高级、克制、具有科技感和品牌识别度的视觉体验。
 
-> **适用平台**：PC 端（Vue 3 + Element Plus + SCSS）、移动端 H5/uni-app/原生 WebView（纯 CSS / 无第三方组件库）
-> **核心理念**：高级但不浮夸，动效丰富但可维护，多端统一同时尊重平台差异
-> **变量前缀**：所有 CSS 变量统一使用 `--mci-` 前缀（Microi Interface）
-
----
+> **适用平台**：PC 端（Vue 3 + Element Plus + SCSS）、移动端 H5/uni-app/原生 WebView（纯 CSS / 无第三方组件库）
+> **核心理念**：高级但不浮夸，动效丰富但可维护，多端统一同时尊重平台差异
+> **变量前缀**：所有 CSS 变量统一使用 `--mci-` 前缀（Microi Interface）
+
+---
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=ui-design-000 sha256=4b6409ab265eb741b2f4b28b51b7de12cde79ff4a19c8a6e8acf80ac867444be -->
-## 整体风格定义
-
-- **风格关键词**：高级、通透、科技感、品牌化、轻量精致、视觉张力。
+<!-- microi-progressive:chunk id=ui-design-000 sha256=205676798890adacffba77fa7ffb48f044b5d4443f11620831f361d2edf97a81 -->
+## 整体风格定义
+
+- **默认基线**：优先呈现清爽、清新、易读的界面，减少重复层级、冗长说明、同义统计卡和无业务意义的装饰，把视觉重量留给真实内容与关键操作。
+- **信息密度**：清爽不是空白越多越好；应用应以任务完成效率决定首屏密度，并通过字号、间距、对齐和语义表面建立层次。
+- **主题适配**：所有颜色、表面、边界、阴影和交互状态必须使用语义 token，适配任意租户主题色，并同时覆盖亮色、暗色模式；不得只在默认主题下成立。
+- **视觉验收**：至少选择浅色、暗色及一个非默认租户主题色，检查文本对比度、焦点态、状态色、悬停与禁用状态。
+- **风格关键词**：高级、通透、科技感、品牌化、轻量精致、视觉张力。
 - **质感**：柔和多层阴影、清晰边界、结构化光影、细腻纹理、精致微动效。
 - **氛围**：默认亮色多彩主题（colorful + gradient + soft shadow），暗黑主题作为可选切换；避免廉价装饰，优先用布局、层级、动效和真实内容建立高级感。
 - **参考吸收**：可参考成熟移动端 UI 灵感库的组件完整度、色彩节奏、入场动效和模板化能力，但 Microi 视觉必须通过 `--mci-*` token 与 MCI-UI 组件形成自己的品牌系统，不照搬第三方外观，也不在吾码源码、文档或样式命名中保留外部 UI 品牌痕迹。

package/skills/v8-cache-pattern/SKILL.md

@@ -285,4 +285,5 @@ fire-and-forget；否则数千个 `SCAN/DEL/PUBLISH` 会同时进入同一个
 - 同一租户的失效广播要有界并发，短暂连接异常可做有限次数重试；
 - 持续故障的日志应按时间窗口汇总，但不得静默吞掉一致性告警；
 - 每个租户可能使用不同 Redis，订阅初始化状态不得用一个全局 `static bool` 共享；
+- 缓存实例必须保存创建时的准确 `OsClient`，按模式 `SCAN/DEL` 时直接使用该租户连接；禁止根据 Redis DB 编号反推连接，因为不同租户可能在不同服务器上使用相同 DB 编号；
 - 等待发布只解决回压，业务写入和缓存失效仍需保持 `OsClient` 隔离及可重试幂等。