@microi.net/cli 4.9.5 → 4.9.7

package/skills/microi-codex-installer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: microi-codex-installer
-description: 当用户在 Codex、WorkBuddy、CodeBuddy、Qoder、Comate、Trae、Cursor、Claude Code 或其它 AI 编程软件中说“安装 @microi.net/cli”“初始化 Microi吾码插件”“添加吾码服务器/MCP”“拉取某连接的所有 V8 代码”，或要求安装、升级、启用、诊断吾码 AI 插件时使用。用户明确要求安装或初始化即视为对应操作授权；普通 Microi 对话只做只读检测，禁止静默安装或改写全局配置。
+description: 当用户在 Codex、WorkBuddy、CodeBuddy、Qoder、Comate、Trae、Cursor、Claude Code 或其它 AI 编程软件中说“安装 @microi.net/cli”“初始化 Microi吾码插件”“添加吾码服务器/MCP”“拉取某连接的所有 V8 代码”，或要求安装、自动升级、启用、诊断吾码 AI 插件时使用。吾码 CLI、Codex 插件及既有工作区 AI/MCP 默认后台自动更新；失败只延后和提示，不得阻断任何工作。
 ---
 
 # Microi吾码 AI 插件与 CLI 安装
@@ -9,17 +9,17 @@ description: 当用户在 Codex、WorkBuddy、CodeBuddy、Qoder、Comate、Trae
 
 只要本技能已经由 Microi.VSCode、工作区 `microi.skills` 或已安装插件提供，用户说“帮我初始化 Microi吾码插件”时就必须识别该意图，用户不需要再次说出 npm 包名。全新 Codex 与空目录尚未加载任何吾码 Skill 时，用户只需在首次请求中明确 `@microi.net/cli`，例如“通过 `@microi.net/cli` 安装吾码 Codex 插件”；具备终端与网络权限的 AI 必须直接执行本技能中的确定性安装命令。安装完成后，更短的“初始化吾码”“添加服务器/MCP”“拉取全部 V8”均由插件 Skill 自动识别。
 
-## Codex 每任务最新版硬门禁（强制）
+## 非阻塞自动更新（强制）
 
-只要当前 AI 宿主是 Codex，且当前对话能够读取任意 Microi吾码 Skill，每个新建或已有对话首次处理 Microi 任务时都必须先执行本节一次。门禁必须发生在业务分析、MCP 调用、源码修改、构建、测试或发布之前；同一任务内已经用在线结果通过后不重复执行。
+只要当前宿主已装有 Microi VS Code 扩展、`@microi.net/cli` 或 Codex 插件，就应由宿主/CLI 在后台投递自动更新。更新检查与业务工作并行，绝不能成为分析、MCP 调用、源码修改、构建、测试、发布或新任务的前置门禁。
 
-先从 npm 官方 registry 强制在线读取唯一可信的最新版：
+自动更新只从 npm 官方 registry 读取 CLI 最新版：
 
 ```bash
 npm view '@microi.net/cli' version --json --prefer-online --registry=https://registry.npmjs.org/
 ```
 
-随后核对本机与工作区状态：
+CLI、Codex 插件与工作区状态仍可用以下命令只读核对，但核对未完成不妨碍用户继续工作：
 
 ```bash
 microi version --json
@@ -27,40 +27,29 @@ microi codex status --json
 microi doctor --workspace "<工作区绝对路径>" --json
 ```
 
-旧版 CLI 尚不支持 `microi version --json` 时，使用 `npm list --global '@microi.net/cli' --depth=0 --json` 读取全局安装版本；不能把命令不存在解释为“已经最新”。`microi codex status --json` 的 `expectedVersion` 来自当前 CLI 自己携带的快照，只能检查本地一致性，不能代替前面的 npm 在线查询。
+旧版 CLI 尚不支持 `microi version --json` 时，可使用 `npm list --global '@microi.net/cli' --depth=0 --json` 读取全局安装版本。`microi codex status --json` 的 `expectedVersion` 来自当前 CLI 自带快照，只检查本地一致性，不能代替 npm 在线查询。
 
-只有以下条件全部满足才允许继续 Microi 任务：
-
-- npm 官方最新版、当前全局 CLI 版本、Codex 插件 `plugin.version` 与 `plugin.expectedVersion` 完全一致；
-- `microi@microi-net` 已安装并启用，且不存在仍在生效的 `microi-official` 旧入口；
-- `doctor.coexistence.aiBundleVersion` 不低于当前 CLI，所有 Microi MCP provider 都不是 `legacy` 或 `upgrade-available`；
-- 当前工作区 AI 配置由最新版 CLI 重新初始化过，MCP 配置已在同一流程更新。
-
-任何一项不满足时，先一次性向用户说明即将执行的全局变更并取得授权。用户当前请求已经明确包含“安装、升级、更新、初始化吾码 CLI/Codex 插件/AI 配置”时，该请求本身就是授权，不重复询问。获得授权后必须连续执行完整闭环：
+标准入口是非阻塞投递命令：
 
 ```bash
-npm install --global @microi.net/cli@latest
-microi codex install --yes
-microi ai init --workspace "<工作区绝对路径>" --json
-microi doctor --workspace "<工作区绝对路径>" --json
-microi codex status --json
+microi update --background --workspace "<工作区绝对路径>" --json
 ```
 
-`microi ai init` 默认同时更新工作区 Skills、AI 指令、typings 与全部受支持宿主的 MCP 配置；本流程禁止传 `--no-mcp`。即使只更新了 CLI 或 Codex 插件，也必须重新执行该命令，不能沿用旧工作区生成物。若 Codex 插件被安装或升级，必须新建 Codex 任务或重载 Codex；重载后的任务再次通过本门禁后才可继续，当前旧任务不得声称已热加载新版 Skills/MCP。
+后台进程会依次检查/安装全局 CLI、幂等更新 Codex 插件、执行 `microi ai init`、`microi doctor` 和 `microi codex status`。`codex install --yes` 的 `--yes` 只保留给旧脚本兼容，不再表示必须先取得用户授权。VS Code 扩展同时使用官方扩展宿主的 `workbench.extensions.installExtension` / 自动更新机制；当前 Extension Host 不强制重载。
 
-npm 官方 registry 无法访问、版本无法解析、用户拒绝授权、安装失败或尚未完成重载时，必须失败关闭：明确报告尚未证明为最新版，不继续 Microi 远端写入、源码实现、构建或发布。禁止改用第三方 registry、离线缓存或旧 CLI 冒充最新版。
+当前运行中的扩展、CLI、Codex Router 与 MCP 必须继续使用已加载版本，禁止为了升级终止进程、强制重载窗口、结束对话或拒绝新任务。新版本写入版本隔离目录，只在后续新进程或宿主自然重启时接管。npm registry 不可用、版本无法解析、权限不足、文件被占用或安装失败时，写入 `~/.microi/updater/status.json` 并延后重试；可非模态提示“立即重试/查看日志”，但无论用户是否处理，当前、正在进行和新建工作都必须继续。禁止改用第三方 registry 或不明镜像冒充最新版。
 
 ## 自然语言入口规则
 
 - 任一 AI 宿主开始处理 Microi吾码低代码、V8、MCP、表单/模块/流程、微应用或平台源码任务时，先判断当前任务是否已经提供 `microi` 的 Skills/MCP/CLI 能力。
-- 能力不明确时立即做只读检测，不得等到缺少工具或上下文后才检查。
-- 用户明确说“安装 `@microi.net/cli`”“初始化 Microi吾码插件”“添加服务器/MCP”或“拉取某连接全部 V8”时，该请求本身就是对应操作授权；立即执行本技能中的确定性命令，不再重复询问同一授权。
-- 用户只是在进行普通 Microi 业务对话、尚未要求安装或升级时，发现 CLI、Codex 插件、AI bundle 或 MCP 不是最新版，必须立即说明完整升级闭环会修改哪些全局/工作区配置，并请求一次明确同意。未获同意不得安装、下载或改写配置。
-- 用户拒绝或暂不升级时，不得反复提示，但最新版门禁保持未通过；只可回答安装说明或进行不依赖吾码运行能力的只读解释，不得继续 Microi 写入、实现、构建或发布任务。
+- 能力不明确时可立即做只读检测或后台投递 `microi update`，但不得等待检测/更新完成才开始用户工作。
+- 用户明确说“安装 `@microi.net/cli`”“初始化 Microi吾码插件”“添加服务器/MCP”或“拉取某连接全部 V8”时，直接执行确定性命令，不再询问“是否允许升级”。连接地址、帐号、密码以及远端业务写入仍遵守各自原有确认边界。
+- 普通 Microi 对话发现 CLI、Codex 插件、AI bundle 或 MCP 不是最新版时，自动更新并继续任务；如自动更新做不到，只给出不阻塞的重试提示，不得把升级选择变成继续工作的条件。
+- 用户关闭自动更新、忽略提示或暂不重载时，当前版本能力照常可用。只在任务确实依赖一个旧版本不存在的具体能力时，准确说明该能力边界并提供降级方案，不能用笼统“版本未通过”拒绝整个任务。
 
 ## 检测
 
-先完成上一节的 npm 官方在线版本查询，再使用已经安装的 CLI 检查本地状态：
+需要诊断更新状态时，使用已经安装的 CLI 检查；这些命令是可观测性工具，不是业务门禁：
 
 ```bash
 microi version --json
@@ -75,7 +64,7 @@ codex plugin marketplace list
 codex plugin list
 ```
 
-成功状态必须同时满足：
+理想状态同时满足：
 
 - 全局 CLI、npm 官方最新版与 Codex 插件版本一致；
 - marketplace 为 `microi-net`；
@@ -86,16 +75,16 @@ codex plugin list
 
 `microi-official` 和 `microi@microi-official` 仅是旧标识，不得写入新文档或新配置；安装器会在新版安装成功后迁移并清理旧标识。
 
-## 获得授权后安装
+## 自动安装与手动恢复
 
-安装或升级统一先把全局 CLI 更新到 npm 官方最新版：
+正常情况由 `microi update --background` 自动完成。需要人工立即恢复时，可直接把全局 CLI 更新到 npm 官方最新版：
 
 ```bash
 npm install --global @microi.net/cli@latest
 microi codex install --yes
 ```
 
-只有在全局安装受宿主限制且用户明确选择不安装全局命令时，才可使用下面的临时执行方式；它不能证明一个既有旧版全局 CLI 已被升级：
+全局安装受宿主限制时可使用下面的临时执行方式；它不能证明一个既有旧版全局 CLI 已被升级：
 
 ```bash
 npx --yes @microi.net/cli@latest codex install --yes
@@ -103,19 +92,19 @@ npx --yes @microi.net/cli@latest codex install --yes
 
 这条命令把 npm 仅作为下载通道：安装器会将包内完整 Codex Plugin 安全复制到当前用户的 `${CODEX_HOME:-~/.codex}/microi-net-marketplace/plugins/microi`，生成 Codex 官方支持的本地 marketplace，注册 `microi-net`，再安装并启用 `microi@microi-net`。完成并重载后，Codex 的“插件”页面必须显示 **Microi吾码**，来源为 **microi-net**。禁止重新写入 Codex 不支持的 `source: npm` marketplace 条目。
 
-在全新 Codex 的空目录中，以下自然语言属于明确安装授权，必须等价执行上述命令，不得仅生成项目 Skill 后就声称 Codex Plugin 已安装：
+在全新 Codex 的空目录中，以下自然语言必须等价执行上述命令，不得仅生成项目 Skill 后就声称 Codex Plugin 已安装：
 
 ```text
 通过 @microi.net/cli@latest 安装吾码 Codex 插件。
 ```
 
-`--yes` 只表示当前用户已经授权这次全局修改，不得由 AI 在普通 Microi 对话中自行补上。只有版本不一致且普通安装不能升级、并确认目标 npm 包已经公开可读时，才使用：
+`--yes` 仅兼容旧版无人值守脚本，安装器不再把它当作工作授权。只有版本不一致且普通安装不能升级、并确认目标 npm 包已经公开可读时，才使用：
 
 ```bash
 microi codex install --yes --force
 ```
 
-CLI 或 Codex 插件安装/升级完成后，必须立即重新初始化当前工作区 AI 配置并更新 MCP，然后双重验收：
+CLI 或 Codex 插件安装/升级完成后，后台幂等重新初始化当前工作区 AI 配置并更新 MCP，然后双重验收：
 
 ```bash
 microi ai init --workspace "<工作区绝对路径>" --json
@@ -123,7 +112,7 @@ microi doctor --workspace "<工作区绝对路径>" --json
 microi codex status --json
 ```
 
-不得用单独的 `microi mcp init` 代替完整 AI 重新初始化；`ai init` 已默认包含 MCP 更新。只有诊断表明 MCP 仍有明确残留问题时，才追加 `microi mcp init` 做定向恢复。
+不得用单独的 `microi mcp init` 代替完整 AI 重新初始化；`ai init` 已默认包含 MCP 更新。只有诊断表明 MCP 仍有明确残留问题时，才追加 `microi mcp init` 做定向恢复。初始化写入采用幂等/原子方式，不终止已启动的 MCP；当前进程继续旧版本，新进程读取新版本。
 
 开发者从可信本地源码验收时，可以显式指定 marketplace 源：
 
@@ -164,7 +153,7 @@ microi init --workspace <工作区> --pull
 microi doctor --workspace <工作区> --json
 ```
 
-当前宿主不会热加载新 Skills/MCP 时，新建任务、重载 Skills/MCP 或重启宿主后再验收。
+当前宿主不会热加载新 Skills/MCP 时，不要求用户立即重载；当前工作继续，用户自然新建任务、重载 Skills/MCP 或重启宿主后再验收新版能力。
 
 ## 按服务器连接拉取全部 V8
 
@@ -200,6 +189,6 @@ CodeBuddy CLI 可把该 `packageRoot` 作为本地 marketplace 添加，再安
 microi codex status --json
 ```
 
-只有返回 `ok: true` 且选择器、状态和版本全部正确，才报告安装完成；必要时再用 `codex plugin list` 核对路径。随后明确提示用户新建 Codex 任务或重载 Codex；当前已经打开的任务通常不会热加载新增 Skills/MCP，桌面端插件页面也可能需要重载后刷新。
+返回 `ok: true` 且选择器、状态和版本全部正确时可报告安装完成；必要时再用 `codex plugin list` 核对路径。若宿主尚未热加载，只说明“新版将在下一次自然启动时生效”，不得要求用户立即新建任务或重载才能继续当前工作。
 
 若 npm 返回 `E404`，说明 `@microi.net/cli` 的目标版本尚未公开或仍在传播。不得删除仍可用的旧插件、不得重复发布同一不可变版本，也不得声称安装成功。

package/skills/microi-datasource-mapping/SKILL.md

@@ -3,7 +3,7 @@ name: microi-datasource-mapping
 description: Microi 选项类字段的数据源 Key/Value 映射规范。用于 Select、Radio、Checkbox、UniApp 枚举显示、KeyValue 配置、数据迁移和接口返回标签映射。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # microi-datasource-mapping — 数据源 Key/Value 映射规范
 

package/skills/microi-db-schema/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: microi-db-schema
-description: Microi 吾码数据库结构与字典指南。用于检查或解释 AI-Project/microi/db.json 中的 Microi 平台表，梳理 diy_table/diy_field/sys_menu 关系，定位 V8 事件存储字段，生成安全的系统表 V8 FormEngine 查询，或分析工作流、SaaS、权限、菜单、接口引擎、数据源和系统配置结构。
+description: Microi 吾码数据库结构与字典指南。用于通过实时 MCP Schema 或当前租户快照检查 Microi 平台表，梳理 diy_table/diy_field/sys_menu 关系，定位 V8 事件存储字段，生成安全的系统表 V8 FormEngine 查询，或分析工作流、SaaS、权限、菜单、接口引擎、数据源和系统配置结构。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi DB Schema
 
@@ -11,9 +11,9 @@ description: Microi 吾码数据库结构与字典指南。用于检查或解释
 
 ## 快速流程
 
-1. 阅读 `references/schema.md` 获取完整数据库结构：固定字段、核心关系、V8 事件字段、全部表分类，以及每张核心表的字段明细。
+1. 优先调用 `microi_get_db_schema` 获取当前服务器的实时表结构；无法连接时才读取当前引擎所属 OsClient 目录的 `.microi-db-schema.md`，并明确说明快照可能过期。`references/schema.md` 只用于理解通用关系，不是任何租户的权威字段清单。
 2. 编写感知结构的 V8 代码时，优先使用带 `_Where` 的 `V8.FormEngine`。只有联表、聚合或 FormEngine 无法表达的场景才使用 `V8.Db.FromSql`，并且必须参数化动态值。
-3. 将 `AI-Project/microi/db.json` 视为当前导出字段列表的权威来源。它列出可配置字段；DIY 表还带有导出中未列出的固定系统字段（`Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted`）。
+3. 实时 MCP Schema 是字段事实源；本地 `.microi-db-schema.md` 仅作离线快照。不要假设普通用户拥有某个仓库专属数据库文件。DIY 表还带有固定系统字段（`Id`、`CreateTime`、`UpdateTime`、`UserId`、`UserName`、`IsDeleted`）。
 
 ## 核心模型
 

package/skills/microi-db-schema/references/schema-overview.md

@@ -1,6 +1,6 @@
 # Microi DB Schema Overview
 
-- Source: `ai-helper/microi/db.json`
+- Source: generic reference snapshot; current tenant truth must come from `microi_get_db_schema`.
 - Tables: 75
 - Configurable fields: 975
 

package/skills/microi-db-schema/references/schema.md

@@ -1,6 +1,6 @@
 # Microi 平台标准数据库结构
 
-> 来源：`AI-Project/microi/db.json`（共 75 张表，975 个可配置字段）
+> 通用参考快照，不代表当前租户。实际字段以 `microi_get_db_schema` 实时回读为准；离线时仅使用当前 OsClient 目录的 `.microi-db-schema.md` 并标注快照时间。
 
 ---
 

package/skills/microi-db-schema/references/table-catalog.md

@@ -1,6 +1,6 @@
 # Microi Table Catalog
 
-Full generated catalog from `ai-helper/microi/db.json`. Load this only when a task needs exact fields outside the core tables.
+Generic reference catalog. Load it only to understand common platform tables; never use it as the exact field authority for a tenant. Query `microi_get_db_schema` first.
 
 ## All Tables
 

package/skills/microi-deployment/SKILL.md

@@ -3,7 +3,7 @@ name: microi-deployment
 description: Microi 安装、部署、升级和本地运行指南。用于 Docker Compose、离线安装、Windows IIS、源码运行、MySQL、Redis、MongoDB、MinIO、反向代理、滚动发布、健康检查、备份恢复和生产部署验收。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 安装与部署
 

package/skills/microi-docs-coverage/SKILL.md

@@ -3,7 +3,7 @@ name: microi-docs-coverage
 description: Microi 中文官网文档与 Skills 能力覆盖审计。用于全面分析 microi.doc/docs/doc 与 docs/case、核对官方能力和 V8 函数是否已进入 microi.skills、补充或重构 Skills、维护文档到 Skill 的责任映射，以及防止后续新增中文文档造成 AI 知识漏项。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 中文官网文档与 Skills 覆盖审计
 

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

@@ -3,7 +3,7 @@ name: microi-form-engine
 description: Microi 表单引擎设计与控件配置指南。用于创建或修改 diy_table、diy_field、表单组件、字段属性、选项/SQL/数据源引擎数据源、子表、关联表单、定制组件、表单布局和字段事件。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 表单引擎设计
 
@@ -12,7 +12,7 @@ description: Microi 表单引擎设计与控件配置指南。用于创建或修
 Config/Data、菜单查询列与缓存保持一致。
 
 平台创建 DIY 表时会自动加入 `DiyCommon.FixedDiyField` 定义的 Id、创建/更新时间、
-创建人、租户等固定字段。业务 Manifest 不重复声明这些字段；读取 `db.json` 时也不能
+创建人、租户等固定字段。业务 Manifest 不重复声明这些字段；读取实时 Schema 或离线快照时也不能
 因为 `_Fields` 只列出可配置字段，就误判物理表缺少固定字段。
 
 ## 必读参考

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

@@ -3,7 +3,7 @@ name: microi-form-layout
 description: Microi 吾码低代码表单布局分组规范。用于通过 MCP、Manifest、VS Code 插件或 V8 引擎创建/优化 `diy_table` 和 `diy_field` 时，决定使用 `diy_table.Tabs` 表单全局 Tab、字段级 `Tabs` 控件、字段级 `CollapseGroup` 折叠分组，还是直接平铺字段。覆盖"何时分 Tab、何时分折叠分组、有效表单行判断阈值、JSON 配置示例、回读验收与回滚"。
 ---
 
-> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
 # Microi 表单布局分组规范（Tabs vs CollapseGroup）
 
@@ -13,6 +13,8 @@ Microi 吾码低代码提供 **三种** 表单分组能力，但每种都有明
 
 控件事实源：`Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json` 中 `Sort=1000` 附近的 `Divider`、`CollapseGroup`、`Tabs`、`Alert`、`StaticText`、`Html`、`RichText` 等都属于 Advanced 布局控件。
 
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=microi-form-layout-000 sha256=cade6a415454aa04f5fcf840e6d9df1323ac9751c0e3c8e1b07b360007413819 -->
 ## 1. 三种分组能力速查
 
 | 能力 | 存储位置 | 控件 | 核心作用 | 适用场景 |
@@ -22,6 +24,8 @@ Microi 吾码低代码提供 **三种** 表单分组能力，但每种都有明
 | **C. 字段级 CollapseGroup（折叠分组）** | `diy_field.Component='CollapseGroup'` + `Config.CollapseGroup` | 字段是折叠面板标题 | **所有分组可在同一页面展开**，用户一屏看到全部标题和分组字段 | 只占 **≤5 个有效表单行** 的小分组（短字段即使有 8~10 个，也常只占 4~5 行） |
 | **D. 不分组（默认平铺）** | 无 | — | 全部字段在第一屏 | 总有效表单行 ≤ 6、没有复杂控件，且没有必须强调的业务分组 |
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-form-layout-001 sha256=f43f8c6f1c156ef3669f0c1f9a9d9d2cb7baf630d0b0cb2f48307a31f3f82ae2 -->
 ## 2. 黄金决策流程（AI 必须按此顺序判断）
 
 ### 2.1 先算“有效表单行”，禁止只数字段
@@ -71,116 +75,8 @@ Q1: 核心可见字段数、子表和强任务域？
 | 8 字段简单登记表 | D. 不分组 | 禁止任何 Tab/折叠 |
 | 工作流审批表（≤10 字段） | D. 不分组 | 禁止使用 Tab |
 
-## 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-002 sha256=9165f561ba90696ce130d24f71a0e56c521b5f8935eac2ddcffb852f3af5d9b2 -->
 ## 4. AI 生成表单布局的标准动作
 
 ### 4.1 必做顺序
@@ -221,6 +117,8 @@ Q1: 核心可见字段数、子表和强任务域？
 
 V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.ClickFormTab('tabId')` 动态控制 Tab 显隐和默认选中。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-form-layout-003 sha256=eebf51aec08023443964d82e1140026ec7cef627b3d2ed6ead169e1fd14353a3 -->
 ## 5. 必填与禁止
 
 ### 5.1 必填
@@ -245,6 +143,8 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 - ❌ **禁止**把高频访问的字段（如单据编号、项目名称）放进默认收起的 CollapseGroup。
 - ❌ **禁止**用普通新增字段或通用表单数据写入创建布局节点；这类路径可能对目标业务表执行物理 DDL。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=microi-form-layout-004 sha256=539ae919554ca9eda5b5a26ac405181f601f4195f6a59baf1fd368d315987e6c -->
 ## 6. 验收清单
 
 修改或新建表单布局后，AI 必须按以下顺序验收：
@@ -264,121 +164,8 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 以及相关字段 V8，搜索 `V8.FieldSet`、`hideField`、`Visible=false`、`HideFields`。设计模式
 通常跳过这些运行态事件；未完成这一步不得直接判定为 Microi.Client 渲染缺陷。
 
-## 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
-```
-
-## 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 -->
+<!-- microi-progressive:chunk id=microi-form-layout-005 sha256=db6759bef83e520e5f137347070f85df1275e14dcbc742bebfdaac4da14be375 -->
 ## 9. 与其他 Skill 的关系
 
 - 字段创建流程：`v8-table-event/SKILL.md` 写 InFormV8 / SubmitFormV8 等。
@@ -386,3 +173,10 @@ microi_update_field({
 - 整行控件规则：`microi-system-delivery/SKILL.md` 中 `FormWidth=24` 的使用条件。
 - 表单设计器与按钮：`v8-menu-buttons/SKILL.md`。
 - V8 事件 Tab 显隐 API：`v8-table-event/SKILL.md` 中 `V8.HideFormTab` / `V8.ShowFormTab` / `V8.ClickFormTab`。
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
+
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
+
+- [references/progressive-01-3-三种分组的存储与配置.md](references/progressive-01-3-三种分组的存储与配置.md)：3. 三种分组的存储与配置；7. 反例参考（必须避免）；8. 快速参考代码片段
+<!-- microi-progressive:end -->