@microi.net/cli 4.9.6 → 4.9.8

package/skills/ui-design/references/progressive-07-/351/200/237/346/237/245-/344/273/216/345/244/264/346/220/255/345/273/272/344/270/200/344/270/252/347/247/273/345/212/250/347/253/257/351/241/265/351/235/242.md

@@ -0,0 +1,207 @@
+# ui-design 详细参考 7
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-020 sha256=25aa81a39c664b1873ff5e7a3c5d0e8ad2b929824c90e16bd020f64c98a34b54 -->
+## 速查：从头搭建一个移动端页面
+
+```vue
+<template>
+  <div class="mci-mobile-page">
+    <!-- 顶部导航 -->
+    <header class="mci-navbar">
+      <h1 class="mci-navbar__title">{{ title }}</h1>
+    </header>
+
+    <!-- 主内容 -->
+    <main class="page-content">
+      <section
+        v-for="(item, i) in list"
+        :key="item.id"
+        class="mci-card mci-stagger-item"
+        :style="{ '--mci-index': i }"
+      >
+        <span class="mci-tag mci-tag--hot">HOT</span>
+        <h3>{{ item.name }}</h3>
+        <p class="mci-text-gradient price">{{ item.price }}</p>
+        <button class="mci-btn">立即查看</button>
+      </section>
+    </main>
+
+    <!-- 底部 Tabbar -->
+    <nav class="mci-tabbar">
+      <a class="mci-tabbar__item mci-tabbar__item--active"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-home" /></svg><span>首页</span></a>
+      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-message" /></svg><span>消息</span></a>
+      <a class="mci-tabbar__item"><svg class="mci-tabbar__icon" aria-hidden="true"><use href="#icon-user" /></svg><span>我的</span></a>
+    </nav>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.page-content {
+  padding: var(--mci-space-4);
+  padding-bottom: calc(var(--mci-touch-target) + var(--mci-safe-bottom) + var(--mci-space-8));
+  display: flex;
+  flex-direction: column;
+  gap: var(--mci-space-4);
+}
+.price {
+  font-size: var(--mci-text-2xl);
+  font-weight: var(--mci-font-bold);
+}
+</style>
+```
+
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-021 sha256=8a8884b0b064e7805cd03d904541b12da4539e73172d31f00d32c1ecfaee32f6 -->
+## 🚨 移动端低代码项目落地踩坑（必读，2026.5）
+
+实战中频繁出现的 7 类问题，统一按以下规则处理。
+
+### 1. 路由前缀不要硬编码租户名
+
+- 错误：在 `manifest.json` 写死 `"router": { "base": "/fixed-tenant/" }`。
+- 正确：默认使用 `"router": { "base": "/" }`；租户由运行配置、`OsClient` 和请求头/参数确定。
+- 不要自行把租户名拼进 API 路径。平台接口使用 `/api/...`、`/apiengine/...` 等标准路由。
+
+### 2. tabBar 使用本地静态 PNG 图标
+
+- uni-app/微信小程序 tabBar 的 `iconPath`、`selectedIconPath` 使用项目内静态 PNG。
+- 不使用 emoji、字体图标、远程 URL；SVG 仅在目标端明确支持并已做真实设备验证时使用。
+- 普通态与选中态保持相同画布和轮廓，推荐 60×60 至 81×81 px，并验证深浅色背景可读性。
+
+### 3. 字号样式不要通配所有 `text`
+
+Scoped SCSS 中的 `.entry text { font-size: 40rpx; }` 会同时放大图标文字和子标签。图标、标题、说明必须使用独立 class：
+
+```scss
+.entry .entry-icon { font-size: 40rpx; }
+.entry .entry-label { font-size: 22rpx; }
+```
+
+### 4. 个人中心/详情入口按信息层级选布局
+
+- 高频资产、订单状态、服务入口适合 4～5 列网格。
+- 设置、安全、协议等低频入口适合纵向列表。
+- 单元格须有稳定触控区域、清晰标签和一致间距；不要为了追求密度牺牲可读性。
+
+### 5. 每个可点击元素都要有反馈
+
+```scss
+.cell, .entry-item, .product-card, .zone-card {
+  position: relative;
+  transition: transform .2s ease, box-shadow .2s ease;
+}
+.cell:active, .entry-item:active {
+  transform: scale(.94);
+}
+@keyframes fadein-up {
+  from { opacity: 0; transform: translateY(16rpx); }
+  to { opacity: 1; transform: translateY(0); }
+}
+.animate-fadein { animation: fadein-up .45s ease both; }
+@media (prefers-reduced-motion: reduce) {
+  .animate-fadein { animation: none; }
+}
+```
+
+动效只表达状态，不承担业务完成事实；提交、支付、安装等动作仍以服务端返回和可恢复状态为准。
+
+### 6. 品牌名和 Logo 的用户可见位置保持一致
+
+同步检查 `manifest.json` 的 `name/h5.title`、`pages.json` 的导航标题、登录/注册/首页品牌区、空状态和分享标题。控制台中的技术标识可保留，但用户可见文案必须统一。
+
+### 7. 接口地址由标准引擎工具维护
+
+- `microi_create_engine`/`microi_upsert_engine` 会维护 `ApiEngineKey`、`ApiAddress` 和路由缓存。
+- 写入超时先用标准 get/list 工具回读，不得立即重复创建。
+- 禁止通过手工 SQL、直接修改 `sys_apiengine` 或自行拼 Redis Key 修补路由；这会绕过租户、审计、缓存失效和控制面权限。
+- 长任务使用后台任务并持久化进度；普通接口写入后以远端回读为最终依据。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-022 sha256=4962a1ec7bc49ae1a2706c58fb6f929304ca254e3fd4d8b626fefbc17067bce2 -->
+## 🔗 关联字段：保存真实 Id，界面展示可读标签
+
+关联字段的数据库事实值通常是 `XxxId`。表单使用 `JoinForm`、`OpenTable` 或带数据源的 `Select` 显示名称，`SelectSaveField` 保存 `Id`，`SelectLabel` 展示名称。不要因为列表默认显示 Id，就强制所有业务表冗余一对可编辑的 `XxxId/XxxName` 字段。
+
+### Select 数据源示例
+
+```json
+{
+  "DataSource": "Sql",
+  "Sql": "select Id, Name from mall_category where Name like '%$Keyword$%' limit 0,20",
+  "SelectLabel": "Name",
+  "SelectSaveField": "Id",
+  "SelectSaveFormat": "Text",
+  "EnableSearch": true,
+  "DataSourceSqlRemote": true
+}
+```
+
+- `$Keyword$` 是平台数据源占位符，不要把浏览器输入直接拼进任意 SQL。
+- 关联表、字段和数据源必须来自当前租户，并受当前表单/菜单的授权与数据范围约束。
+- 大表使用远程搜索和分页，不一次性把全表拉到浏览器。
+- 列表展示名称优先配置 Join/模块关联字段或受控数据源，不把隐藏 Id 暴露给用户。
+
+### 什么时候增加 `XxxName` 快照字段
+
+只有在业务明确要求“保存当时名称”、离线展示、历史审计或高频报表需要时才增加 `XxxName`。它是快照/冗余字段，不是外键事实源，并遵守：
+
+1. 后端 SubmitBefore/接口引擎在同一事务内根据 `XxxId` 校验并写入名称。
+2. 前端 V8 可以即时回显，但不能作为唯一一致性保障。
+3. 关联名称后续变化时，先明确历史快照是否应随之更新。
+4. 批量回填必须参数化、可恢复、可幂等，并经过明确写入确认。
+
+### MCP 建模流程
+
+1. 先用 `microi_get_db_schema` 获取真实表和字段。
+2. 使用 `microi_build_field_config` 生成 JoinForm/OpenTable/Select 配置。
+3. 使用 `microi_add_field` 或 `microi_update_field` 写入字段。
+4. 修改 KeyValue/Config 后回读 `microi_get_field_list`，并执行 `microi_refresh_schema_cache`。
+5. 在真实菜单下验证普通角色能看到标签，但不能借数据源越权读取其它表或行。
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-023 sha256=1c731f6915dae4de788e84af3f6a59cf5d116a4de1f9ca5541f13b55110521ca -->
+## 表单布局规范（Column）
+
+> 平台默认设计标准：所有 `diy_table` **应使用双列布局** (`Column = 2`)，更紧凑现代，符合主流后台 SaaS 视觉密度。
+
+### 创建表时
+
+```jsonc
+microi_create_table {
+  "name": "Crm_Customer",
+  "description": "客户",
+  "column": 2     // ✅ 默认就是 2，无需显式传，但推荐写明
+}
+```
+
+### 修复存量表（一次性把所有 `Column=null` 改成 2）
+
+```jsonc
+microi_update_table {
+  "name": "Crm_Customer",
+  "column": 2
+}
+```
+
+### 何时使用 Column=1（单列）
+
+- 工作流审批表单（字段少且需要专注）
+- 移动端优先表单（手机宽度不够双列）
+- 含大量富文本/长文本字段的内容编辑表
+
+### 何时使用 Column=3（三列）
+
+- 字段≥18 的"基础档案"类大表（员工、商品 SKU、设备清单）
+- 桌面分辨率≥1920px 的内部管理后台
+
+> 修改 `Column` 后会自动清缓存（`microi_update_table` 后端走 `UptFormData('diy_table')` + 主动 `RefreshSchemaCache`），前端硬刷新（Ctrl+Shift+R）即可看到效果。
+
+---
+
+<!-- /microi-progressive:chunk -->

package/skills/ui-design/references/progressive-08-/350/241/250/345/215/225/345/210/206/347/273/204/350/247/204/350/214/203-tabs-vs-collapsegroup-/345/274/272/345/210/266.md

@@ -0,0 +1,142 @@
+# ui-design 详细参考 8
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=ui-design-024 sha256=7af53d03d0828232aaf7ab54d6527f5e2cf292d8eb493d75d9ab42adc3030ba3 -->
+## 表单分组规范：Tabs vs CollapseGroup（强制）
+
+> **核心原则**：默认**不分组** → 小业务域用 **`CollapseGroup` 折叠分组** → 只有足够长或强任务隔离的业务域才用 **`Tabs` 分页**。禁止只按字段数判断：双列布局中 8 个短字段约占 4 行，仍不应独占 Tab；普通业务域通常达到 6 个有效表单行才考虑 Tab。
+
+### 三种分组方式
+
+| 方式 | 存储位置 | 控件 | 适用场景 |
+|------|---------|------|---------|
+| **A. 表级 Tab** | `diy_table.Tabs` + 字段 `Tab` | 表单顶部 Tab 条 | 大表单拆 2~5 个业务域，每域通常 ≥6 个有效表单行，或属于扫码/子表/代码编辑等强任务模式 |
+| **B. 字段级 CollapseGroup** | `diy_field.Component='CollapseGroup'` + `Config.CollapseGroup` | 折叠面板标题 | 小业务域（≤5 个有效表单行），**所有分组同屏可见、可同时展开** |
+| **C. 字段级 Tabs 控件** | `diy_field.Component='Tabs'` + `Config.FieldTabs` | 字段是 Tab 容器 | 嵌套 Tab 场景（不推荐优先用） |
+
+### 表单规模与分组决策表
+
+| 有效表单行与任务特征 | 推荐方案 |
+|---------|---------|
+| ≤ 6 行且无复杂控件 | **不分组**（直接平铺） |
+| 7 ~ 12 行且无强任务隔离 | `CollapseGroup` 收起次要字段，或直接平铺 |
+| > 12 行且至少两个业务域各 ≥ 6 行 | `diy_table.Tabs`（大域）或混合（Tab + 嵌套 CollapseGroup） |
+| 扫码、报工、大型子表、代码编辑等强任务模式 | 可独立使用 `diy_table.Tabs`，不受普通行数阈值限制 |
+
+### CollapseGroup Config 示例
+
+```jsonc
+// diy_field 必要字段
+{
+  "Component": "CollapseGroup",
+  "Type": "varchar(50)",
+  "Visible": 1,
+  "AppVisible": 1,
+  "Config": "{\"CollapseGroup\":{\"DefaultCollapsed\":false,\"ScopeMode\":\"UntilNextGroup\",\"Description\":\"MRP 运算状态、批次号与时间\",\"Icon\":\"fas fa-calculator\",\"Theme\":\"primary\",\"ShowFieldCount\":true}}"
+}
+```
+
+### 必做与禁止
+
+- ✅ 任何 Tab / CollapseGroup 必须有 `Description` 解释分组用途。
+- ✅ CollapseGroup 必须设 `Icon`（如 `fas fa-calculator`、`fas fa-info-circle`），不默认空白。
+- ✅ 修改 Tab/CollapseGroup 配置后必须 `microi_refresh_schema_cache`。
+- ❌ **禁止**为 ≤5 个有效表单行的业务域单独建 Tab；8~10 个双列短字段通常也应使用 CollapseGroup。
+- ❌ **禁止**仅凭 13~30 个原始字段决定平铺或分 Tab；总有效行超过 6 且存在明确业务域时，至少使用 CollapseGroup 分组。
+- ❌ **禁止**给 Tabs/CollapseGroup/Divider/Alert 等布局控件设 `FormWidth=24`（天然占整行）。
+- ❌ **禁止**只创建 Tab 不写字段的 `Tab` 归属。
+- ❌ 布局优化不得顺带覆盖字段 `Config/V8Code/KeyupV8Code` 或表级 V8 事件；修改前后必须回读比较，发现 Tab 显隐 API 时先适配再迁移。
+
+完整规范、Config JSON 模板、回读验收清单和反例参考见 `microi-form-layout/SKILL.md`。
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-025 sha256=e6e11a8153bc5d1a1c5e9f1868aaae9a101843961fcf94dba42681b0a6091ad7 -->
+## 缓存刷新（解决"我改了字段但页面不变"问题）
+
+平台对 `diy_field` 的字段列表有 Redis 缓存，键格式 `Microi:{OsClient}:FormData:diy_table_field_list:{TableId|TableName}`。
+
+**何时缓存会失效**：
+- ✅ 通过 `microi_add_field` / `microi_update_field` / `microi_update_table` 走原生 API → 自动清
+- ✅ 通过低代码后台界面操作（diy_table 表单事件触发）→ 自动清
+- ❌ 直接 `V8.FormEngine.UptFormData('diy_field', ...)` → **不会触发清缓存**（这是历史 bug）
+
+**何时手动清**：
+```jsonc
+microi_refresh_schema_cache { "tables": ["mall_address", "mall_member"] }
+```
+该工具会清除每张表的 6 个 key 变种（`diy_table` / `Diy_Table` / `diy_table_field_list` × `id|name`）。
+
+---
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-026 sha256=3d53780b3ae17dabba22a2567d0d6e2c51e4dbce504d6e341b737881a3c4e749 -->
+## 接口引擎匿名访问
+
+登录、注册、首页公共数据等接口必须 `AllowAnonymous=1`，否则未登录用户调用会拿到 `null`：
+
+```jsonc
+microi_set_engine_anonymous {
+  "apiEngineKeys": ["mall_member_login", "mall_member_register", "mall_home_data"],
+  "allowAnonymous": 1
+}
+```
+
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-027 sha256=e6e15cc34871821da89f70cb2a5326942d9d90fe99ed5c5a315415ac57f1532c -->
+## MCI-UI 与第三方组件库策略
+
+Microi 的 UI 规范不应该只停留在 skills 文档。面向品牌长期建设时，应形成可复用的 MCI-UI 体系：设计变量、基础样式、组件约定、示例站点、移动端与 PC 网站组件库。
+
+- **默认规则**：当用户没有主动指定 UI 风格、UI 库或品牌视觉时，AI 必须默认采用 Microi吾码UI（Microi.UI / MCI-UI）作为移动端、PC 官网、企业网站、产品站、活动页和响应式网站的设计基础。
+- **自动识别**：只要项目属于 Microi 生态、吾码源码、吾码客户项目，或需求中出现“移动端项目、网站、企业站、商城、会员中心、资产页、官网、H5、uni-app、Vue3”等关键词，即使用户没有单独说明 UI 风格，也应自动套用本规范与 `Microi.UI/` 组件。
+- **落地要求**：业务页面优先使用 `MciPage`、`MciSection`、`MciButton`、`MciCard`、`MciCell`、`MciTabs`、`MciSkeleton`、`MciDataState`、`MciThemePanel` 等组件或项目级 `mci-*` 封装；不要重新发明一套分散样式。
+- **例外场景**：后台管理系统继续使用 Element Plus + Microi theme；强行业 UI 或客户指定视觉可以定制主题 token，但仍优先保留 `--mci-*` 变量、骨架屏、安全区和动效规范。
+- UniApp 项目不强制业务页面直接依赖某一个第三方 UI 库。推荐把 `uni-ui` 作为官方跨端基础组件底座之一，但业务视觉必须通过 `MCI-UI Mobile` 或项目级 `mci-*` 组件封装承载，避免页面直接散落 `uni-ui/uView/FirstUI/TDesign` 风格。
+- PC 后台管理系统继续使用 Element Plus，不替换选型；但主题变量、间距、骨架屏、空态、安全区、表单密度和品牌色必须服从 `--mci-*` 设计变量。
+- PC 官网、产品站、文档站、营销页和响应式网站应优先使用 `MCI-UI Web` 的设计变量与轻量组件。只有当页面是强表单、强数据录入或后台化工具时，才引入 Element Plus、TDesign Vue、Naive UI、Arco Design Vue 等成熟组件库作为底座。
+- MCI-UI 应分层建设：`@microi/theme` 负责 tokens；`@microi/v8` 负责前端 SDK；`@microi/ui-mobile` 面向 UniApp；`@microi/ui-web` 面向官网和响应式站点；`Microi.Client` 后台则用 Element Plus + MCI theme。
+- `microi.doc` 作为 VitePress 官方文档站，应逐步成为 MCI-UI 的展示入口：组件演示、设计变量、移动端骨架屏、安全区、富文本、上传资源、主题切换都应该有可查看示例，而不是只写在 skill 中。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-028 sha256=eee54b657b766f1d1ef137fb1df07fc8eec0b5363502838475eda81f9d031512 -->
+## MCI-UI 源码落地位置
+
+MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。
+
+- 新的移动端 UniApp/H5 项目应优先使用 `Microi.UI/src/uniapp` 中的 `MciPage`、`MciNavbar`、`MciButton`、`MciCard`、`MciCell`、`MciSection`、`MciTabs`、`MciMetricCard`、`MciActionBar`、`MciAvatar`、`MciProductCard`、`MciSkeleton`、`MciDataState`、`MciRichText`，再按业务补项目组件。
+- 新的 PC 官网、产品站、文档站、响应式网站应优先使用 `Microi.UI/src/web` 和 `Microi.UI/src/theme`，不要直接套后台 Element Plus 风格。
+- `Microi.UI/src/theme/tokens.css` 是品牌 token 源头；新组件颜色、圆角、阴影、间距、安全区、骨架屏都必须走 `--mci-*` 变量。
+- `Microi.UI/src/theme/runtime.js` 是主题运行时入口；项目应通过 `initMciDesign()`、`setMciPalette()`、`setMciShape()`、`setMciTheme()` 统一设置黑白红橙黄绿青蓝紫主色、圆角/扁平、亮暗主题和动效偏好。
+- `MciPage` 默认带页面入场动效；业务页如果有特殊路由转场，可以关闭 `animated` 后使用项目级转场，但不能让动态页面无反馈地直接闪现。
+- `MciButton`、`MciCard` 必须保留 hover/pressed/focus/sheen 等基础反馈；业务组件可以封装样式，但不能删掉交互状态。
+- 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=ui-design-029 sha256=470bda7401f3a1d6713872d89370bb89785e693b9e94862a7df4808db0200065 -->
+## VitePress 中文文档布局规范
+
+`microi.doc` 不是纯文本仓库，而是 Microi 产品体验的一部分。创建或重构
+`docs/doc`、`docs/case` 中文阅读页时：
+
+- 页面首屏使用标题、简短价值说明和 2–4 个关键能力视觉分组，避免打开后先看到十几段连续正文。
+- 正文阅读宽度控制在约 `86ch`，代码、表格、架构图和案例截图可使用全宽；标题间距必须明显大于段落间距。
+- 卡片用于并列能力、选择和案例，表格用于精确对比，流程带用于阶段关系，截图用于真实结果；不要把相同信息在四种视觉里重复一遍。
+- 使用 MCI 主题变量，不在 Markdown 中散落硬编码颜色；亮/暗主题均保证文字、边框、代码和状态对比度。
+- 页面专属 CSS 独立存放并以 marker 限定范围；全站字体、段落、列表、`details`、图片与焦点样式归整站主题层。
+- 桌面使用多列时，980px 以下要能降为单列；表格和代码可横向滚动，普通正文与图片不得产生页面级横向滚动。
+- 图片必须有语义化 `alt` 与图注；纯装饰图标设置 `aria-hidden`。交互控件保留键盘焦点，动画遵守 `prefers-reduced-motion`。
+- 完成后同时跑中文文档可读性门禁、VitePress 构建，并用真实浏览器查看桌面/移动、亮色/暗色。只看 Markdown 源码或构建日志不能算视觉验收。
+
+全站文档视觉改造还必须遵守：
+
+- 清单必须覆盖 `/doc` 和 `/case` 中文阅读路由；首页、应用广场、应用详情、用户中心、登录与联系页采用专用交互布局，应显式登记后按自己的组件契约验收，不能漏扫，也不能强套正文档卡片样式。英文生成页与受保护更新日志按项目规则排除。
+- 为每个中文路由维护显式视觉类型，至少区分概览、指南、参考、规范和展示页；同一主题契约按类型调节信息密度，不能把 API 参考页机械改造成营销卡片。
+- 所有自定义面板都先定义“表面 + 主文字 + 次文字 + 边框”的亮暗成对 token，再使用 token 组合背景。禁止浅色硬编码背景继续继承暗色全局文字，也禁止只改背景不改前景。
+- Sass 位于 `html:lang(zh)` 嵌套作用域时，暗色根状态写 `&.dark`，编译结果必须是 `html:lang(zh).dark`；不得写成会生成 `html:lang(zh) .dark` 的后代选择器。单元测试应编译 SCSS 并阻止这一回归。
+- 常规正文和次要文字对其实际面板底色至少满足 WCAG AA 4.5:1，大标题至少 3:1；渐变面板按最不利的实色底计算，不能只看 token 名称推断对比度。
+- “全站扫描”必须输出逐页档案和问题结果；静态通过后仍要遍历全部中文路由做 H1、横向溢出和低对比冒烟，并对五类代表页执行桌面/移动、亮/暗截图矩阵。扫描数量、构建成功或单页截图均不能单独证明全站已经美化。
+<!-- /microi-progressive:chunk -->

package/skills/v8-crud-api/SKILL.md

@@ -9,6 +9,8 @@ description: Microi V8 CRUD 接口引擎开发。用于编写服务端 JavaScrip
 
 你正在开发 Microi 吾码平台的 V8 接口引擎。接口引擎是运行在服务端的 JavaScript 函数，通过 `V8.FormEngine` 操作数据库，通过 `V8.Result` 或 `return` 返回结果。
 
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=v8-crud-api-000 sha256=bfeaae480ebf6028fe98904cc6f8feb630b140b99551fefcc551c8038a2ca078 -->
 ## 本地优先与版本头（必做）
 
 AI 本地开发接口引擎时，优先修改 `microi-v8-engine/<租户>/<项目>/接口引擎/.../*.js` 本地文件，再通过 MCP 或 VS Code 插件同步到数据库。插件提示“本地和远端不一致”时，必须先读取本地与远端代码并合并有效差异，不能盲目用任一侧覆盖另一侧。
@@ -35,6 +37,8 @@ Microi.net.Api 普通本地启动不要额外设置 `ASPNETCORE_ENVIRONMENT` / `
 
 生成接口引擎代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；跨表事务、权限校验、状态机、金额/库存计算、复杂 `_Where` 条件等代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-001 sha256=86768d106f68593e51beb29bcff1ee0291c483706431181da34984b22228ff21 -->
 ## 核心规则
 
 - 接口引擎文件是纯 JavaScript（Jint 引擎，非 Node.js）
@@ -46,6 +50,8 @@ Microi.net.Api 普通本地启动不要额外设置 `ASPNETCORE_ENVIRONMENT` / `
 - 服务端调用 FormEngine 默认**不触发**表单 V8 事件，加 `_InvokeType: 'Client'` 才触发
 - 接口内 `return Code=1` 自动提交事务、`Code≠1` 自动回滚事务，**禁止**手动 Commit/Rollback
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-002 sha256=9f10ab278468f292b5e26679b7a7ab2ea91bb6d4094e2bff8adb7cb15e39adce -->
 ## 性能底线（必须自检）
 
 - 写接口引擎前必须先做数据访问计划：需要哪些表、哪些字段、预计数据量、是否分页、是否需要缓存。
@@ -64,6 +70,8 @@ Microi.net.Api 普通本地启动不要额外设置 `ASPNETCORE_ENVIRONMENT` / `
 - 面向个人中心的流水接口必须按 `V8.CurrentUser.Id` 强制隔离，并返回 `PageIndex`、`PageSize`、`TotalCount`；列表只取页面需要的审计字段。
 - 为便于用户核对，可以保存经过空白归一化的用户输入短摘要；摘要按 Unicode 文本元素截取，不能截断 emoji 或代理对，也不要把完整请求 JSON 当摘要。
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-003 sha256=d46768bbaaf8b2ebfdd38e09d11e886b135cb65e78984dbfa67d75ec5f947175 -->
 ## DosResult 状态码
 
 | Code | 含义 |
@@ -82,6 +90,8 @@ if (r.Code !== 1) return r;
 // r.Data 才是真实数据
 ```
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-004 sha256=6d58584cabd1659ae3af6cbddb797df2c0844c99fd8d2627d02a9c0eae98e8c2 -->
 ## 全局日期函数
 
 ```javascript
@@ -90,82 +100,8 @@ DateFormat(new Date(), 'yyyy-MM-dd')          // 格式化
 DateAdd(new Date(), 'd', 7, 'yyyy-MM-dd')     // 加减（s/m/h/d/w/q/M/y）
 ```
 
-## 查询列表（分页）
-
-```javascript
-var result = V8.FormEngine.GetTableData('SysUser', {
-  _Where: [
-    ['Status', '=', 1],
-    ['AND', 'Name', 'Like', V8.Param.keyword || '']
-  ],
-  _SelectFields: ['Id', 'Account', 'Name', 'Phone', 'CreateTime'],
-  _OrderBy: 'CreateTime',
-  _OrderByType: 'DESC',
-  _PageIndex: V8.Param.pageIndex || 1,
-  _PageSize: V8.Param.pageSize || 20
-});
-
-return { Code: 1, Data: result.Data, DataCount: result.DataCount, Msg: '成功' };
-```
-
-### 请求内异步查询
-
-后端接口引擎可在本次请求内使用真实异步查询；前端 V8 不使用这个方法名：
-
-```javascript
-var result = await V8.FormEngine.GetTableDataAsync('SysUser', {
-  _Where: [['Status', '=', 1]],
-  _SelectFields: ['Id', 'Account', 'Name'],
-  _PageIndex: 1,
-  _PageSize: 20
-});
-
-return { Code: 1, Data: result.Data, DataCount: result.DataCount };
-```
-
-必须 `await` 结果。需要接口先返回、后续再批量处理时，应改用平台后台任务、Job、MQ 或 outbox，而不是丢弃 Promise。
-
-### 多字段排序
-
-```javascript
-var result = V8.FormEngine.GetTableData('SysUser', {
-  _Where: [['Status', '=', 1]],
-  _OrderBys: { 'CreateTime': 'desc', 'Name': 'asc' }
-});
-```
-
-### 匿名查询（无需登录）
-
-```javascript
-var result = V8.FormEngine.GetTableDataAnonymous('Article', {
-  _Where: [['IsPublished', '=', 1]],
-  _PageSize: 10
-});
-```
-
-匿名新增的公开入口是
-`POST /api/formengine/AddFormDataAnonymous`，且目标表必须显式允许匿名新增。
-当前后端 `V8.FormEngine` 接口不公开
-`V8.FormEngine.AddFormDataAnonymous`；接口引擎内部仍使用
-`V8.FormEngine.AddFormData(...)` 并遵守可信执行身份。不要仅因为历史文档出现
-该名称就为匿名业务接口关闭服务端校验。
-
-### 获取树形数据
-
-```javascript
-// 表单属性需开启【树形结构】
-var result = V8.FormEngine.GetTableDataTree('Department', {});
-```
-
-### 仅获取数据条数
-
-```javascript
-var result = V8.FormEngine.GetTableDataCount('SysUser', {
-  _Where: [['Status', '=', 1]]
-});
-// result.DataCount 为总数
-```
-
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-005 sha256=35220022799bbed7f9b3d82fe14dc0855aa8f77d0640ac411c61d222d02b0eda -->
 ## 查询单条
 
 ```javascript
@@ -186,6 +122,8 @@ if (result.Code !== 1 || !result.Data) {
 return { Code: 1, Data: result.Data };
 ```
 
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-crud-api-006 sha256=510588ad14503caff0a92c614f0e7453bdd343a1e22711c6c5a2b3f8893b5a8d -->
 ## 新增
 
 ```javascript
@@ -227,174 +165,11 @@ for (var i = 0; i < V8.Param.items.length; i++) {
 var result = V8.FormEngine.AddTableData(addList);
 ```
 
-## 更新
-
-```javascript
-if (!V8.Param.Id) {
-  return { Code: 0, Msg: 'Id 不能为空' };
-}
-
-var result = V8.FormEngine.UptFormData('SysUser', {
-  Id: V8.Param.Id,          // 必传
-  Name: V8.Param.Name,
-  Phone: V8.Param.Phone,
-  _NotSaveField: ['Account'],  // 可选：忽略这些字段不更新
-  _NoLineForAdd: true,         // 可选：数据不存在时自动插入
-  _ForceUpt: true              // 可选：强制修改自动编号字段
-});
-
-return { Code: result.Code, Msg: result.Code === 1 ? '更新成功' : result.Msg };
-```
-
-### 批量更新
-
-```javascript
-var uptList = [];
-for (var i = 0; i < V8.Param.items.length; i++) {
-  uptList.push({
-    FormEngineKey: 'SysUser',
-    Id: V8.Param.items[i].Id,
-    Status: V8.Param.items[i].Status
-  });
-}
-V8.FormEngine.UptTableData(uptList);
-```
-
-## 删除
-
-```javascript
-// 删除单条
-var result = V8.FormEngine.DelFormData('SysUser', { Id: V8.Param.Id });
-
-// 批量删除（传 Ids 数组）
-var result = V8.FormEngine.DelFormData('SysUser', { Ids: V8.Param.Ids });
-
-return { Code: result.Code, Msg: result.Code === 1 ? '删除成功' : result.Msg };
-```
-
-### 批量删除（跨表）
-
-```javascript
-var delList = [];
-delList.push({ FormEngineKey: 'OrderDetail', Id: V8.Param.detailId });
-delList.push({ FormEngineKey: 'OrderHeader', Id: V8.Param.orderId });
-V8.FormEngine.DelTableData(delList);
-```
-
-## 按条件批量操作
-
-```javascript
-// 按条件更新
-V8.FormEngine.UptFormDataByWhere('SysUser', {
-  _Where: [['DeptId', '=', V8.Param.deptId]],
-  Status: 0,
-  _NoLineForAdd: true  // 可选：不存在时插入
-});
-
-// 按条件删除（不支持 _Where 以外的删除方式）
-V8.FormEngine.DelFormDataByWhere('SysUser', {
-  _Where: [['Status', '=', 0], ['AND', 'CreateTime', '<', '2024-01-01']]
-});
-```
-
-## 事务处理
-
-```javascript
-// 接口引擎中 V8.Db 自动开启事务：
-// 返回DosResult/带Code对象：仅Code=1提交，其他值回滚
-// 返回对象但没有Code：回滚
-// 返回字符串/数字/数组/布尔/null且未异常：提交
-// 手动调用 V8.DbTrans.Commit() 或 Rollback() 无效，由平台统一管理
-
-// FormEngine 可传入事务对象（第三个参数）
-V8.FormEngine.AddFormData('Table1', { Name: '测试' }, V8.DbTrans);
-V8.FormEngine.UptFormData('Table2', { Id: 'xxx', Status: 1 }, V8.DbTrans);
-
-// 调用其他接口引擎也可共享事务
-V8.ApiEngine.Run('other-engine-key', { Id: 'xxx' }, V8.DbTrans);
-```
-
-## 请求内异步与后台处理
-
-```javascript
-// 本次请求必须拿到结果时，使用真实Async API并await
-var resp = await V8.Http.PostResponseAsync({
-  Url: 'https://other.com/notify',
-  PostParam: { Id: V8.Param.id },
-  Timeout: 10
-});
-return resp.StatusCode >= 200 && resp.StatusCode < 300
-  ? { Code: 1 }
-  : { Code: 0, Msg: '通知失败' };
-```
-
-禁止用 `setTimeout` / `Task.Run` 实现“立即返回、后台继续”：接口返回后 Jint Engine、租户上下文、事务和执行租约会释放。脱离请求的任务使用后台任务、Job、MQ 或 outbox，并按 `EventId` 幂等处理与恢复。
-
-## 动态加字段（运行时改表结构）
-
-```javascript
-V8.FormEngine.AddField({
-  TableName: 'diy_test',
-  Name: 'Age',
-  Type: 'int',          // 仅使用平台允许的varchar(N)/mediumtext/longtext/int/bigint/decimal(18,N)
-  Label: '年龄',
-  Component: 'NumberText',
-  TableWidth: '100',
-  Visible: 1
-});
-```
-
-> 风险：会执行 DDL（ALTER TABLE）。仅在低代码自定义配置场景使用，业务运行时**不要**频繁调用。
-
-日期时间字段统一使用 `varchar(25)` 保存 `yyyy-MM-dd HH:mm:ss`，组件使用 `DateTime`。禁止 `datetime/date/timestamp/float/double/boolean/string/text/nvarchar` 等平台不允许的物理类型。动态表/字段属于控制面能力，只允许 `Level >= 9999` 的可信管理脚本使用。
-
-## 旧版 _Where 兼容
-
-```javascript
-// 老版本前端 / 老接口可能传旧格式 _Where：[{ Name, Value, Type, AndOr, Group }, ...]
-// 转换成新格式：
-var newWhere = V8.Method.ParseWhere(V8.Param._Where);
-V8.FormEngine.GetTableData('Table', { _Where: newWhere });
-```
-
-## _Where 条件语法速查
-
-```javascript
-// 等于
-[['Field', '=', value]]
-
-// 模糊查询
-[['Name', 'Like', '张']]      // %张%
-[['Name', 'StartLike', '张']] // 张%
-[['Name', 'EndLike', '三']]   // %三
-
-// AND / OR
-[['A', '=', 1], ['AND', 'B', '>', 10]]
-[['A', '=', 1], ['OR', 'B', '=', 2]]
-
-// IN / NotIn
-[['Id', 'In', ['id1', 'id2', 'id3']]]
-[['Status', 'NotIn', [0, -1]]]
-
-// NULL
-[['Field', '=', null]]    // IS NULL
-[['Field', '<>', null]]   // IS NOT NULL
-
-// 分组（括号）
-[['Name', 'Like', '张'], ['AND', '(', 'Age', '>', 18], ['OR', 'Status', '=', 1, ')']]
-
-// 日期范围
-[['CreateTime', '>=', '2024-01-01'], ['AND', 'CreateTime', '<', '2024-02-01']]
-```
-
-**支持的操作符：** `=`, `==`, `<>`, `!=`, `>`, `>=`, `<`, `<=`, `Like`, `NotLike`, `StartLike`, `EndLike`, `In`, `NotIn`
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
 
-## 注意事项
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
 
-- `_Where` 是参数化查询，自动防 SQL 注入，**不要拼接 SQL 字符串**
-- `AddFormData` 不需要传 `Id`，后端自动生成 GUID
-- `UptFormData` 必须包含 `Id` 字段
-- 如需触发表单 V8 事件，在参数中加 `_InvokeType: 'Client'`
-- 返回值中 `Code: 1` 表示成功，`Code: 0` 表示失败，`Code: 2` 表示数据不存在
-- 分页参数使用 `_PageIndex` 和 `_PageSize`（带下划线前缀）
-- 列表返回总数字段为 `result.DataCount`（非 Total）
+- [references/progressive-01-查询列表-分页.md](references/progressive-01-查询列表-分页.md)：查询列表（分页）；更新；删除；按条件批量操作；事务处理；请求内异步与后台处理；动态加字段（运行时改表结构）；旧版 _Where 兼容
+- [references/progressive-02-where-条件语法速查.md](references/progressive-02-where-条件语法速查.md)：_Where 条件语法速查；注意事项
+<!-- microi-progressive:end -->