@microi.net/cli 4.8.2 → 4.8.8

package/skills/microi-microservice/SKILL.md

@@ -64,8 +64,10 @@ src/
 AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，删除/新增路由后由
 发布流程同步 `sys_microiservice_page`，不要从 Vue 源码猜路由。
 
-构建前遵守本地 OOM 保护；已有 dev server 可复用时不重复启动。独立 Vite 预览缺少
-完整宿主 Token/OsClient/菜单/弹窗上下文，不能替代宿主验收。
+本地项目必须位于当前连接对应的 `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}`。`microi.apps/` 是官方应用商城发行包工程目录，不是 MicroService 源码目录；发行包只能引用、构建或快照当前租户的唯一源码，不得在包内嵌套第二份可编辑 `microservice/` 工程。
+
+构建前遵守本地 OOM 保护；已有 dev server 可复用时不重复启动。新脚手架必须支持独立
+访问时的平台帐号登录，但独立 Vite 预览仍没有菜单/弹窗等完整宿主上下文，不能替代宿主验收。
 
 迁移 Vue2 定制页到独立 Vite 微服务时，不得假设宿主会提供 Tailwind/UnoCSS 等原子类；
 页面依赖的宽高、颜色、间距、响应式和打印/下载样式必须由组件自身的语义 class 明确声明，
@@ -74,10 +76,18 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 筛选、确认、导入参数或状态同步。验收需用旧版截图逐项核对标题、工具栏、选项、按钮、表格
 和分页，而不只确认组件已挂载。
 
+### 本地源码同步禁止人工分段
+
+- 已有本地工程时，`microi_sync_microservice_source` 首选只传项目绝对路径 `directory`；先 dry-run 审阅文件数、总大小、逐文件哈希和清单哈希，再传 `confirmExecution`。
+- 源码扫描、读取、哈希和上传内容组装必须在 MCP 进程内完成，模型上下文只接触清单。禁止让 AI 读取整个源码为 Base64，禁止生成 `.sync-seg-*`、`sync-source-files.json`，禁止把一个真实源码文件拆成多个临时文件反复调用工具。
+- 目录扫描必须排除 `node_modules`、`dist`、`build`、`coverage`、缓存、版本库和 UniApp 构建目录；发现 `.env`、证书、私钥、符号链接或越过根目录时失败关闭。
+- AI 工具单次读取上限不是 MicroService 源码文件上限。即使 `microi.v8.js` 等文件超过 50KB，也应保持一个完整文件，由 MCP 直接从磁盘读取。
+- `sourceFiles` 仅用于调用方本来就持有内存文件的旧版兼容场景；不得把它作为本地工程默认路径，也不得用人工切片规避上下文限制。
+
 ## 发布
 
 - 创建/更新元数据：`microi_create_microservice`。
-- 同步私有源码：`microi_sync_microservice_source`。
+- 同步私有源码：`microi_sync_microservice_source`；本地工程必须优先传 `directory`，不构造 Base64 文件数组。
 - 真实编译目录优先 `microi_publish_application_directory_stream` 流式发布。
 - 发布动作必须明确区分两种模式：默认“源码+编译产物”先把完整工程同步到私有桶并逐文件回读 SHA-256，再把 `dist` 流式发布到公有桶；显式“仅编译产物”只更新公有桶，必须在界面中告知其他用户仍会拉取上一次私有源码，禁止暗示源码已同步。
 - 私有源码同步使用 `ReplacePrivateSourceOnly` 精确清理过期源码；兼容调用可以继续接受 `replace`，但实现不得用旧式全表 `Replace=true` 删除同一应用的公有运行产物元数据。
@@ -95,8 +105,23 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 
 菜单 `OpenType=MicroService` 时一次绑定 `MicroServiceId`、
 `MicroServicePageId`、`MicroServiceRoutePath`、`MicroServiceKey`。
+完整系统 Manifest 不得固化不同租户会变化的两个 Id；模块声明 `openType=MicroService`、`microServiceKey` 和 `microServiceRoutePath` 即可，由 `microi_generate_system` 在任何写入前回读 `sys_microiservice/sys_microiservice_page`，解析并校验当前租户的 `MicroServiceId/MicroServicePageId`。微服务或页面不存在时必须在首个写操作前失败，不能留下半套系统。
 复杂弹窗用 `V8.OpenAppDialog`，业务参数放 `Data`，回调放顶层。
 
+### 独立、菜单与弹层三种入口
+
+- 同一发布物必须支持：直接打开独立运行、`sys_menu` 使用 `/micro-app/{AppKey}/{RoutePath}` 打开指定路由、`V8.OpenAppDialog` 按 AppKey/RoutePath 以 Dialog 或 Drawer 打开。
+- 菜单路由必须同时回读并传入 `SysMenuId`、`ModuleEngineKey`、`DiyTableId`；弹层默认继承调用菜单，也允许跨模块时显式传真实授权模块。宿主统一下发 `{ sysMenuId, moduleEngineKey, diyTableId }` 的 `permissionContext`。
+- `permissionContext` 只是选择正确 API 调用上下文，不是授权凭证。后端仍依据 DiyToken、OsClient、角色、菜单、表、按钮和数据范围校验；禁止删除权限参数、改成匿名接口或写死管理员 Token 来消除“没权限”。
+
+### 独立运行的认证门
+
+- 嵌入菜单或 `V8.OpenAppDialog` 时直接复用宿主 Token，不显示第二套登录页；同一个 V8 SDK 实例继续处理 Token 轮换。
+- 独立访问时先配置当前 `apiBase/osClient` 并复用本地有效 Token；没有有效 Token 才显示吾码帐号密码登录。
+- 页面启动时调用 `V8.GetSysConfig(true)`，用统一 `isEnabledFlag` 解析 `EnableCaptcha`。开启时请求 `GET /api/Captcha/GetCaptcha?OsClient=...`、读取响应头 `captchaid`，登录提交 `_CaptchaId/_CaptchaValue`；关闭时不渲染、不提交验证码字段。
+- 登录使用统一 `V8.Login` 与 DiyToken，不创建第二套用户体系。Token 失效后回到认证门；禁止在 URL、日志、源码、`.env` 或业务数据中保存 Token。
+- “无权限”排查顺序固定为：Token/OsClient → 目标 `ModuleEngineKey` → 宿主 `permissionContext` → 当前角色的菜单/表/按钮/数据范围。登录成功不等于拥有全部模块权限。
+
 微服务内部禁止调用浏览器原生 `alert/confirm/prompt`。优先复用宿主 `Tips`/`V8.ConfirmTips`；需要由子应用自行承载时，使用 teleport 到 `body` 的品牌化可访问弹层，固定在当前视口正中央并高于宿主滚动内容。长列表只允许一次性加载后在前端内存搜索时，不得随着关键词重复请求服务器。
 
 Token 只通过宿主上下文传递，不硬编码、不放 URL、不写日志。子应用回传成功/取消/
@@ -152,7 +177,8 @@ AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data
 - 组合发布成功前，私有源码回读必须与本地源码在路径集合、文件数、字节数、逐文件 SHA-256 和规范化清单哈希上完全一致；任何缺失、多余或读取错误都要阻止运行版本切换。
 - 直接刷新友好路由与连续切换多个微应用不 404、白屏或实例名冲突。
 - Dialog/Drawer 成功、取消、错误和关闭协议正确。
-- 宿主 API 请求携带当前 Token/OsClient/菜单上下文，普通用户权限正确。
+- 独立地址覆盖“已有 Token 自动进入”和“无 Token 显示帐号密码”；`EnableCaptcha` 开/关各验一次，验证码响应头和登录参数正确。
+- 宿主 API 请求携带当前 Token/OsClient/`permissionContext`，普通用户用真实授权模块成功、未授权模块仍明确拒绝。
 - 至少验证桌面和窄屏；上传、表格、滚动、弹窗底部操作不被截断。
 - 长弹窗滚动到顶部/中部/底部后，错误提示和确认层仍位于当前视口中央；自动化监听到原生 JavaScript 对话框直接判失败。
 - 本地构建、MCP 发布和真实浏览器验收分别说明，未执行的层不宣称通过。

package/skills/microi-microservice/references/runtime-delivery.md

@@ -62,13 +62,17 @@
 | `microi_get_application_file` | 读取单文件 |
 | `microi_get_microservice` | 回读已发布运行时 |
 | `microi_create_microservice` | dry-run/创建运行元数据 |
-| `microi_sync_microservice_source` | 同步私有源码 |
+| `microi_sync_microservice_source` | 同步私有源码；本地工程首选绝对路径 `directory` |
 | `microi_publish_application_directory_stream` | 流式发布真实构建目录 |
 | `microi_publish_microservice` | 小产物兼容发布 |
 
 `replace=true` 会清理源码清单外的旧元数据，属于覆盖性写入；必须先展示文件差异并
 获得明确确认。超时先回读，不重复发布。
 
+本地源码目录由 MCP 进程直接扫描和读取，AI 只看路径、大小、哈希与清单；禁止生成
+`.sync-seg-*`、`sync-source-files.json` 或手工 Base64 分段。单个源码超过模型读取上限时仍保持
+一个真实文件。`sourceFiles` 只保留没有本地目录时的旧调用兼容。
+
 真实构建目录一律使用逐文件 multipart 流：默认/硬上限为 20,000 文件、总计 20GB，
 文件体不进入 JSON、Base64 或 Jint。`StorageMode=db` 的 256 文件/5MB 仅用于小型
 应急恢复，不能作为大项目发布器。发布器必须持久化同一交付批次的
@@ -90,6 +94,7 @@
 - `MicroServiceRoutePath`
 - `MicroServiceKey`
 - `ComponentPath=/micro-app/host`
+- `ModuleEngineKey`（宿主权限上下文）
 
 无需导航的内部页面直接在 `sys_microiservice_page.RouteMetaJson` 设置
 `InternalOnly=true`；不再依赖伪造的隐藏 `sys_menu` 才能刷新友好路由。真正需要菜单
@@ -105,6 +110,7 @@ V8.OpenAppDialog({
   Width: 'min(960px, calc(100vw - 32px))',
   OpenType: 'Drawer',
   Data: { Id: V8.Form.Id },
+  ModuleEngineKey: 'authorized-module-key',
   OnSuccess: function (data) {
     V8.RefreshTable({ _PageIndex: -1 });
   },
@@ -124,8 +130,16 @@ V8.OpenAppDialog({
 const host = window.microApp?.getData?.() || {};
 ```
 
-常见字段：`apiBase`、`osClient`、`token`、`appKey`、`version`、
-`microRoute`、`dialog`、`dialogData`。只在内存中使用 Token。
+常见字段：`apiBase`、`osClient`、`token`、`menuId`、`moduleEngineKey`、`diyTableId`、
+`permissionContext`、`appKey`、`version`、`microRoute`、`dialog`、`dialogData`。只在内存中使用 Token。
+
+独立访问时没有宿主 Token：先配置清单中的 `apiBase/osClient`，读取 `V8.GetSysConfig(true)`，
+没有有效本地 Token 才显示吾码帐号密码登录；按 `EnableCaptcha` 动态请求验证码并向 `V8.Login`
+提交 `_CaptchaId/_CaptchaValue`。嵌入菜单或弹层时复用宿主身份，不显示第二套登录。
+
+`permissionContext={sysMenuId,moduleEngineKey,diyTableId}` 只帮助子应用选择正确的 FormEngine
+模块上下文，不能授予权限。无权限时依次核对 Token/OsClient、模块 Key、宿主上下文和角色授权；
+禁止去掉权限参数、改匿名接口或硬编码管理员 Token。
 
 页面根容器使用 `min-height: var(--micro-app-available-height, 100vh)`，让后台菜单、弹窗和
 移动端共享宿主实测高度；不要在嵌入模式直接固定 `100vh`。宿主高度变化时还会通过

package/skills/microi-mobile-app-quality/SKILL.md

@@ -41,6 +41,8 @@ description: Microi 移动端质量门禁，适用于 UniApp/H5/微信小程序
 - 只保留小型交互图标和离线关键资源在主包。任何远程迁移都必须同步检查小程序下载域名、失败占位、缓存策略和弱网首屏。
 - 压缩以用户可感知质量为边界：图片检查文字与主体细节，音频抽听，视频抽播；禁止仅为满足扫描数字而过度压缩。
 - 验收必须同时给出包体扫描、CDN 匿名 `200`、正确媒体类型和多尺寸截图证据。缺任一层都不能宣称资源问题已通过。
+- 微信小程序上传前增加硬门禁：扫描 `dist/build/mp-weixin` 的真实文件；单个非关键静态资源超过 `256 KB`、主包静态资源达到 `1.5 MB`，或主包距微信当前硬上限不足 `300 KB` 时，发布步骤必须失败并列出最大文件，不能等开发者工具上传后才发现超限。
+- 迁移到 HDFS/CDN 后必须从构建产物确认原大文件已经消失，并从业务记录/配置回读相对 `Path`；页面要先加载当前租户 `SysConfig.FileServer`，不得以源码硬编码 CDN 域名替代运行期配置。远程资源加载失败时只能回退到轻量本地占位，不得把原大图重新塞回主包。
 
 ## 2. 不要猜测 Microi 前端 SDK 登录接口
 
@@ -128,6 +130,13 @@ Microi 请求只能发送一个不区分大小写的 OsClient 请求头。浏览
 - 模拟 `uni.request` 域名未配置、超时、HTTP 500、接口 `Code=0`，前端均显示具体原因，loading 在 `finally` 中恢复。
 - 体验版真机复测授权登录；不能只以开发者工具模拟成功作为上线依据。
 
+## 3.1.1 手机号快速验证前置页不得混淆腾讯官方
+
+- 调用手机号快速验证组件前展示的登录页、弹窗、按钮、说明、分享标题和失败提示中，禁止出现“微信”“微信官方”“微信登录”“一键登录”等可能让用户误认为腾讯官方功能或官方产品的文案。
+- 前置页不得使用微信官方 Logo、相似绿色气泡图标、仿官方按钮或其它腾讯官方视觉元素；只允许展示小程序自身主体名称、品牌 Logo 和通用手机/验证图标。
+- 推荐统一使用“手机号快捷登录”“手机号快速验证”“验证中”等中性文案。底层仍按平台要求保留 `open-type="getPhoneNumber"`、`provider:'weixin'` 等技术实现，不能为改文案破坏真实授权链路。
+- `build:mp-weixin` 后必须扫描登录页源码和 `dist/build/mp-weixin/pages/login/` 产物中的可见文案，并对手机号快速验证前置页截图；发现混淆词、官方 Logo 或近似元素时阻止上传和提审。
+
 ## 3.2 微信小程序每个页面默认支持分享
 
 小程序项目必须默认支持转发给朋友和分享到朋友圈，不能只给首页或公开页添加分享。登录和权限控制属于访问阶段，不得用来隐藏分享能力。

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

@@ -52,7 +52,8 @@ description: Microi 吾码从自然语言交付完整系统的总控规范。用
 - 对资金/资产类生产数据执行清理、重算、修复、补发、扣减前，必须留下可审计痕迹：中文备注 SQL、维护接口说明、执行时间、影响行数、回读验证结果。能用小范围条件时不要全表更新。
 - 写入菜单时，业务按钮一次性配齐 `MoreBtns`、`FormBtns`、`PageBtns`、`BatchSelectMoreBtns`、`PageTabs`，按钮前端只负责交互，后端逻辑放接口引擎。
 - 写入后台菜单时必须至少规划两级菜单树：先创建业务域父菜单，再把 CRUD、报表、日志、设置模块挂到对应父菜单。不要把客户、设备、工单、报告、日志、配置等所有模块直接创建为一级菜单。Manifest dry-run 和最终交付说明都必须列出菜单树。
-- 新建前端 MicroService 时，必须先 `microi_list_applications` 盘点，再用 `microi_scaffold_vue_microservice` 在当前租户 `AI应用/{appKey}` 做预演和确认创建；构建后依次同步私有源码、发布公有产物、回读页面 Id。每个菜单通过 `microi_create_module` 一次绑定 `MicroServiceId/MicroServicePageId/MicroServiceRoutePath/MicroServiceKey`，写后用 `microi_get_module` 回读，不得把普通 URL 菜单的创建成功误报成微服务菜单已交付。
+- 新建前端 MicroService 时，必须先 `microi_list_applications` 盘点，再用 `microi_scaffold_vue_microservice` 在当前租户 `AI应用/{appKey}` 做预演和确认创建；构建后依次同步私有源码、发布公有产物、回读页面 Id。每个菜单通过 `microi_create_module` 一次绑定 `MicroServiceId/MicroServicePageId/MicroServiceRoutePath/MicroServiceKey`，写后用 `microi_get_module` 回读，不得把普通 URL 菜单的创建成功误报成微服务菜单已交付。
+- 完整系统 Manifest 中的 MicroService 菜单使用 `microServiceKey + microServiceRoutePath` 作为跨租户可移植引用；`microi_generate_system` 必须在任何写入前回读并解析当前租户的服务/页面 Id。直接调用 `microi_create_module` 时仍须一次提供全部四个绑定字段。
 - Windows 上脚手架从临时目录原子改名时，杀毒软件或索引器可能短暂返回 `EPERM/EACCES/EBUSY`；MCP 应做有上限的短重试并保持原子改名，重试仍失败才清理临时目录并报错，禁止改成逐文件覆盖目标目录。
 - 编译产物优先调用 `microi_publish_application_directory_stream`。流式端点失败时必须检查 `uploadedCount/retrySafe`：只有 `uploadedCount=0` 且 `retrySafe=true`、并且产物较小时，才可临时回退 `microi_publish_microservice`；已上传部分文件时先按版本和哈希回读，禁止无判断重复发布。回退与远端版本缺口必须写进交付结论。
 - `microi_get_application_context` 返回文件清单不等于源码可读；必须检查 `ContentsComplete/ContentErrorCount` 以及逐文件 `ContentReadError`。MinIO 服务端读取私有源码应走内网端点，不能因公网代理拒绝私有桶而把 `IncludedContents=true` 误判为完整上下文。
@@ -104,12 +105,30 @@ description: Microi 吾码从自然语言交付完整系统的总控规范。用
   回查索引，并创建 `Display=0`、`AppDisplay=0`、`HasChild=0` 的子表菜单。
 - `JoinForm` 只用于主表保存一个目标 Id、并嵌入一条独立目标记录完整表单的 N:1/1:1
   场景；目标表不能是当前表。需要列表、多行增删改或可能有多条记录时禁止使用。
-- `TableChild` 的 `TableChildTableId`、`TableChildSysMenuId`、`TableChildFkFieldName`
-  必须引用回读后的真实资源。资源尚未创建时分两阶段写入，禁止猜 Id，禁止退化成
-  `JoinForm`。
-- 基数不清楚时必须在远端写入前询问用户。调用 `microi_plan_system` / `dryRun` 前先做
-  关系语义审查；即使工具没有报错，AI 发现“1:N + JoinForm”、缺子表外键、缺隐藏
-  子菜单或缺回查索引时仍必须阻断。
+- `TableChild` 的 `TableChildTableId`、`TableChildSysMenuId`、`TableChildFkFieldName`
+  必须引用回读后的真实资源。完整系统 Manifest 使用
+  `relation:{cardinality:"1:N",targetTable,childForeignKey,childModule}`，生成器按“全部表与
+  普通字段 → 隐藏子表菜单 → 关系字段”分阶段解析当前租户 Id；禁止猜 Id，禁止退化成
+  `JoinForm`。
+- 基数不清楚时必须在远端写入前询问用户。调用 `microi_plan_system` / `dryRun` 前先做
+  关系语义审查。MCP 会硬性拒绝“1:N + JoinForm”、自关联 JoinForm、缺主/子外键、缺
+  `Display=0/AppDisplay=0/HasChild=0` 隐藏子菜单或缺 `(OsClient, FK)` 回查索引；AI
+  不得改用直接单字段工具绕过。
+
+`JoinForm` 的可移植 Manifest 只写名称，不写租户 Id：
+
+```json
+{
+  "name": "CustomerProfile",
+  "label": "客户资料",
+  "component": "JoinForm",
+  "relation": {
+    "cardinality": "N:1",
+    "targetTable": "Biz_Customer",
+    "joinFieldName": "CustomerId"
+  }
+}
+```
 
 `JoinForm` / `OpenTable` 等单记录关联仍需兼顾可读字段，不能只生成一个裸 `XxxId`。
 

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

@@ -51,6 +51,8 @@ Microi 标准小程序必须采用“平台内核 + 版本化元数据 + Profile
 - H5/App 可提供手机号输入兜底，但必须确认后端接口支持 `Phone` 登录；微信小程序优先走 `Code + LoginCode`。
 - 登录按钮、去登录按钮、手机号授权按钮必须是图标 + 文案按钮，具备 loading、disabled/pressed 反馈，且原生 button 默认边框要清掉。
 - 体验版授权登录必须保留可诊断错误：请求层归一化 `uni.request.fail.errMsg`、HTTP 状态和接口 `Msg`，登录页用模态框完整展示“阶段 + 原因 + 追踪号”。后端接口引擎按阶段写脱敏系统日志；不能只在前端 catch 后显示固定“手机号登录失败”。
+- 小程序调用手机号快速验证组件的前置页、按钮、弹窗、分享标题和失败提示不得出现“微信”“微信官方”“微信登录”“一键登录”等可能混淆腾讯官方的文案，也不得展示微信官方 Logo、相似绿色气泡图标或仿官方品牌元素。统一使用“手机号快捷登录”“手机号快速验证”等中性业务文案，只展示应用自身品牌 Logo。
+- 微信小程序构建后必须扫描登录页源码以及 `dist/build/mp-weixin/pages/login/` 产物，并截图核对手机号快速验证前置页；命中上述混淆文案、官方图形或近似元素时必须阻止上传和提审，不能只检查按钮主文案而漏掉说明文字、错误弹窗或分享标题。
 
 ## 微信小程序全页面分享
 
@@ -99,6 +101,9 @@ Microi 标准小程序必须采用“平台内核 + 版本化元数据 + Profile
 - 压缩后必须在至少 375px、430px 和目标小程序设备截图中核对清晰度、裁切、首屏加载与失败占位；音视频还要抽听/抽播。质量不合格时优先调整编码、分辨率和缓存策略，而不是继续极端压缩。
 - 项目只能通过统一配置或资源解析器保存 CDN 地址，页面不得散落硬编码 FileServer；切换环境或租户时必须能整体替换。
 - CDN 资源必须设置加载失败占位或降级路径。构建验收同时检查小程序主包资源总量、单资源大小、远程域名白名单和真实 CDN 可达性，不能只看源码文件大小。
+- 小程序发布前必须扫描实际构建目录，而不只扫描 `src`：单个非离线关键资源超过 `256 KB` 时默认迁移 HDFS/CDN；主包静态资源达到 `1.5 MB` 或距离平台硬上限不足 `300 KB` 时必须停止上传，先瘦身或分包。确需本地保留的例外要记录离线必要性、大小和验证证据。
+- HDFS 迁移顺序固定为“保留/归档原始素材 -> 按真实展示尺寸压缩 -> 上传当前租户公有 HDFS -> 保存相对 `Path` -> 运行期通过 `SysConfig.FileServer` 解析 -> 匿名 GET 回读”。回读必须断言 `200`、正确 `Content-Type`、非空大小，重要资源再比对 SHA-256；不能把上传接口返回成功当成完成。
+- 原始高清图、视频母版、设计源文件不得继续放在会被 UniApp 收集的 `src/static`、分包目录或其它构建入口中；应移到项目资料/设计源目录。主包仅保留小于门禁的轻量失败占位图和离线关键图标。
 
 ## 头像必须异步统一解析
 

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

@@ -71,6 +71,8 @@
 
 路由优先 `/micro-app/{MsKey}/{RoutePath}`，并兼容历史 Id 路由。
 
+完整系统 Manifest 使用可移植引用：模块写 `openType=MicroService`、`microServiceKey`、`microServiceRoutePath`，不把某个租户的 `MicroServiceId/MicroServicePageId` 固化进发行包。`microi_generate_system` 会在首个写操作前回读运行元数据并补齐两个 Id；解析失败必须停止整次生成。直接调用 `microi_create_module` 时仍须一次提供全部四个绑定字段。
+
 ## 跨端 ViewSchema
 
 专用物理字段：

package/skills/page-engine/SKILL.md

@@ -5,6 +5,8 @@ description: 生成和审查 Microi 界面引擎 Page Engine 页面 JSON。用
 
 # Microi 界面引擎（Page Engine）页面 JSON 生成
 
+MCP 的生成/保存入口包含 `microi_build_page_design` 与 `microi_save_page_design`；版本治理入口见下文。保存工具写入后仍需回读 `mic_page`，不能把生成成功当作持久化成功。
+
 你正在为 Microi 吾码平台生成界面引擎页面的 JSON 数据。界面引擎页面由 `formData` 对象描述，用户导入 JSON 即可使用。
 
 ## 设计器源码事件
@@ -379,6 +381,36 @@ return { Code: 1, Data: { NotModified: true, FileKey: currentFileKey } };
 - 交付类首页如果使用一个远程 `html` 组件承载整页驾驶舱，运行态应由外层框架滚动，不要给容器和组件写死 1000px 这类固定高度。页面 JSON 可将 `wrapperOption.height` 与 `widgetOption.height` 设为 `0`（或运行态支持的 `auto`），前端运行态必须按内容自适应高度；设计器模式再使用可编辑的默认高度。
 - 首页写入口径说明时，必须区分“用户口头期望数量”“原始资料条目数量”“按业务主体合并后的数量”“后台项目/规则/别名数量”。不要只显示一个“未交付 N 个”，应同时列出部分交付、待执行、阻塞/需业务人员配合的清单和原因。
 
+## 版本历史、并发保存与回滚
+
+修改现有页面时必须先读取页面详情中的 `CurrentHash`，保存时把它作为 `expectedHash` 传入，并填写简短 `changeSummary`。不要仅凭本地旧 JSON 覆盖远端页面。
+
+| MCP 工具 | 用途 |
+|---|---|
+| `microi_list_page_history` | 获取历史元数据与当前哈希 |
+| `microi_get_page_history` | 获取指定不可变快照 |
+| `microi_compare_page_versions` | 结构化比较两个版本；右侧省略时比较当前页面 |
+| `microi_export_page_design` | 导出 `microi.page.v1` 设计包 |
+| `microi_rollback_page_design` | 使用 `expectedCurrentHash` 回滚并新增审计版本 |
+
+- 内容规范化后哈希未变化时，不应新增空历史。
+- 遇到哈希冲突先重新读取、比较，再决定合并或重做；禁止去掉 `expectedHash` 强行覆盖。
+- 回滚不是删除：目标快照成为新当前版本，回滚前内容仍保留。
+- 写后必须再次读取页面详情和历史，确认 `CurrentHash`、版本号、变更摘要和 JSON 一致。
+- 页面历史属于当前租户数据库；不要假定业务表有物理 `OsClient` 列。
+
+## 本地撤销、Vue 源码桥与资产包
+
+- 设计器本地历史最多 50 步、总计最多 20MB；连续编辑允许合并，但保存前必须刷新当前 `CurrentHash`。
+- `Ctrl/Cmd+Z`、`Ctrl/Cmd+Shift+Z`、`Ctrl/Cmd+Y` 不能抢占输入框、textarea、contenteditable 或代码编辑器自己的撤销行为。
+- 本地 Undo/Redo 不是审计版本；跨会话恢复仍使用服务端历史与 CAS。
+- Page JSON → Vue SFC 只使用确定性 `microi.page.sfc.v1` 模板；禁止 eval、动态执行用户 JSON 或注入任意 import。
+- Vue SFC → Page JSON 只接受平台生成标记、完整元数据和匹配 Hash；任意手写 Vue、第三方 SFC 或未知 script 必须拒绝。
+- 导入源码后先规范化、显示 Diff，再由用户确认写入；不得因为“解析成功”直接覆盖当前页面。
+- 可复用组件/区块使用治理中心 `microi.asset.v1`，声明 Props、Setters、DataAdapters、Platforms 和 DependencyPackages；调用 `mci-asset-publish` DryRun 后再发布。
+- 资产依赖必须检查缺失、语义版本范围、循环和最大深度；运行时使用 `mci-asset-resolve` 返回的 `LoadOrder`。
+- 复杂页面需要完整工程能力时提升为前端微服务；不要承诺任意 Vue 源码无损反编译回界面引擎。
+
 ## 生成 JSON 注意事项
 
 1. **编号唯一**：`wrapperOption.number` 和 `widgetOption.number` 页面内唯一（随机5位整数）

package/skills/ui-design/SKILL.md

@@ -1583,7 +1583,7 @@ Microi 的 UI 规范不应该只停留在 skills 文档。面向品牌长期建
 - 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 中。
 
-## MCI-UI 源码落地位置
+## MCI-UI 源码落地位置
 
 MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。
 
@@ -1593,4 +1593,17 @@ MCI-UI 已在吾码源码根目录落地：`Microi.UI/`。
 - `Microi.UI/src/theme/runtime.js` 是主题运行时入口；项目应通过 `initMciDesign()`、`setMciPalette()`、`setMciShape()`、`setMciTheme()` 统一设置黑白红橙黄绿青蓝紫主色、圆角/扁平、亮暗主题和动效偏好。
 - `MciPage` 默认带页面入场动效；业务页如果有特殊路由转场，可以关闭 `animated` 后使用项目级转场，但不能让动态页面无反馈地直接闪现。
 - `MciButton`、`MciCard` 必须保留 hover/pressed/focus/sheen 等基础反馈；业务组件可以封装样式，但不能删掉交互状态。
-- 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。
+- 第三方 UI 库只能作为底层能力或局部补充，不能绕过 MCI-UI 直接决定产品视觉。
+
+## VitePress 中文文档布局规范
+
+`microi.doc` 不是纯文本仓库，而是 Microi 产品体验的一部分。创建或重构中文文档页时：
+
+- 页面首屏使用标题、简短价值说明和 2–4 个关键能力视觉分组，避免打开后先看到十几段连续正文。
+- 正文阅读宽度控制在约 `86ch`，代码、表格、架构图和案例截图可使用全宽；标题间距必须明显大于段落间距。
+- 卡片用于并列能力、选择和案例，表格用于精确对比，流程带用于阶段关系，截图用于真实结果；不要把相同信息在四种视觉里重复一遍。
+- 使用 MCI 主题变量，不在 Markdown 中散落硬编码颜色；亮/暗主题均保证文字、边框、代码和状态对比度。
+- 页面专属 CSS 独立存放并以 marker 限定范围；全站字体、段落、列表、`details`、图片与焦点样式归整站主题层。
+- 桌面使用多列时，980px 以下要能降为单列；表格和代码可横向滚动，普通正文与图片不得产生页面级横向滚动。
+- 图片必须有语义化 `alt` 与图注；纯装饰图标设置 `aria-hidden`。交互控件保留键盘焦点，动画遵守 `prefers-reduced-motion`。
+- 完成后同时跑中文文档可读性门禁、VitePress 构建，并用真实浏览器查看桌面/移动、亮色/暗色。只看 Markdown 源码或构建日志不能算视觉验收。

package/skills/uniapp-mall-assets/SKILL.md

@@ -70,6 +70,13 @@ function imageUrl(path) {
 
 不要让业务页面各自拼 `${API_BASE}/${path}` 或 `${FILE_SERVER}/${path}`；这会造成租户切换、私有桶、绝对 URL 和本地文件路由行为不一致。
 
+## 大资源与小程序包体门禁
+
+- Hero、Banner、资讯封面、视频、音频、字体和大型占位图等公开资源，先按真实显示尺寸压缩，再上传当前 `OsClient` 的公有 HDFS；数据库和配置只保存相对 `Path`，客户端运行时读取 `SysConfig.FileServer` 组成 CDN 地址。
+- 发布前扫描真实小程序构建目录。单个非离线关键资源超过 `256 KB` 时默认不得进入主包；主包静态资源达到 `1.5 MB` 或距平台硬上限不足 `300 KB` 时必须中止上传并输出最大文件清单。
+- 上传完成必须执行 CDN 匿名 GET 回读，验证 `200`、媒体类型、字节数，重要资源比对 SHA-256；同时回读业务字段确认已由 `/static/...` 改为 HDFS 相对路径。只有上传成功、数据库回读、CDN 回读和构建产物瘦身全部通过，才能关闭问题。
+- 原始设计素材移到不会参与构建的资料目录；主包只保留轻量失败占位和离线关键图标。远程资源加载失败时显示该占位，禁止回退为同一张大图的本地副本。
+
 ## 私有文件
 
 - 私有对象 Key 不能直接转换成可长期访问的公网地址。

package/skills/v8-debugging/SKILL.md

@@ -3,9 +3,11 @@ name: v8-debugging
 description: Microi V8 调试与日志指南。用于排查接口引擎、V8 事件、console.log、DataAppend.DebugLog、sys_log、异常处理和远程执行问题。
 ---
 
-# Microi V8 调试与日志
-
-你正在为 Microi 吾码平台编写 V8 引擎代码，需要在开发/测试/生产环境进行排错。本指南提供调试模式、异常捕获、系统日志、调试输出的标准做法。
+# Microi V8 调试与日志
+
+你正在为 Microi 吾码平台编写 V8 引擎代码，需要在开发/测试/生产环境进行排错。本指南提供调试模式、异常捕获、系统日志、调试输出的标准做法。
+
+MongoDB 运行日志通过 `microi_query_mongodb_logs` 只读查询；必须限制租户、时间窗、页大小和返回字段，不在结果或回答中输出 Token、连接串、Secret 或完整敏感请求体。
 
 ## 三种输出通道
 

package/skills/v8-file-upload/SKILL.md

@@ -3,9 +3,11 @@ name: v8-file-upload
 description: Microi V8 与 MCP 文件上传下载指南。用于处理流式 AI 应用发布、V8.FilesByteBase64、V8.Method.Upload、私有文件 URL、文件响应、HDFS、OSS、MinIO 和 S3 存储。
 ---
 
-# Microi V8 文件上传下载
-
-你正在为 Microi 吾码平台编写文件上传/下载/返回相关代码。平台分布式存储（HDFS）支持阿里云OSS、MinIO、亚马逊S3，存储方案由 SaaS 引擎按租户配置。
+# Microi V8 文件上传下载
+
+你正在为 Microi 吾码平台编写文件上传/下载/返回相关代码。平台分布式存储（HDFS）支持阿里云OSS、MinIO、亚马逊S3，存储方案由 SaaS 引擎按租户配置。
+
+公开入口覆盖 `V8.uploadFile`、多文件 `V8.uploadFiles` 与 MCP `microi_upload_file_base64`。多文件上传必须限制并发、逐文件返回结果；Base64 工具只接受明确文件名、大小和租户内目标范围，写后回读路径、大小与哈希。
 
 ## 核心 API
 
@@ -186,6 +188,14 @@ var extractResult = V8.Method.ExtractZip({
 - 安装脚本还必须同步当前有效 `sys_config`：`ApiBase` 使用对外可访问的 API 端口，`FileServer` 使用 `http://<访问IP>:<MinIO API端口>/mci-public`。`ApiBase` 不能误用 Web 前端端口，因为 V8 代码会直接在其后拼接 `/api/...` 或 `/apiengine/...`。
 - 安装验收必须使用真实登录 Token 分别执行一次 `Limit=false` 和 `Limit=true` 上传：公有文件匿名访问应返回 `200`，私有文件匿名访问应返回 `403`，私有文件通过签名 URL 访问应返回 `200`，并核对下载内容与上传内容一致。
 
+### 复盘：签名 HEAD 被代理转换为 GET 导致上传后回读误报
+
+- 触发场景：`PutObject` 已返回成功、对象可通过 GET 下载，但公有桶和私有桶的上传后 `StatObject` 均对桶根路径返回 `AccessDenied`；常见于启用严格回读校验后，MinIO Endpoint 前的 Nginx 同时启用了缓存与默认的 `proxy_cache_convert_head on`。
+- 根因判断：S3 SigV4 的签名包含 HTTP 方法；代理把客户端签名的 HEAD 转为上游 GET 后会造成签名不一致。另一个可能原因是对象级凭据缺少桶级 `ListBucket` / `GetBucketLocation` 权限，因此不能只凭 `AccessDenied /bucket/` 推断对象未落盘，也不能把空 Region 当作唯一原因。
+- 通用规则：优先在 MinIO 代理位置设置 `proxy_cache_convert_head off`；若仍使用缓存，缓存键需区分 `$request_method`。平台不得跳过上传后回读：当 HEAD/Stat 失败时，使用同一凭据生成签名 GET，并以 `Range: bytes=0-0` 回读；禁用重定向，非空对象必须同时验证期望总长度与首字节，空对象验证长度为零，`404` 判不存在，`403`、网络错误和证据不足继续失败关闭。禁止记录或返回带签名查询参数的 URL。
+- 配置边界：只有实时回读证明 Endpoint、桶名、Region 或凭据确实错误时才修改 SaaS 配置；对象 GET 正常而仅 HEAD 失败时应修复代理或兼容回读路径，不能猜测内网地址、降低校验强度或轮换正常凭据。
+- 自动化检查：覆盖签名 GET 的单字节 Range、期望总长度、首字节实际读取、空对象、长度不符、重定向、`403` 和 `404`；真实环境同时验证公有桶与私有桶的 `Put -> Range GET -> 内容一致`，并对比相同签名在 GET 与 HEAD 方法下的响应。
+
 ### 复盘：旧空库缺少可选字段导致 MinIO 初始化后中断
 
 - 触发场景：MinIO 容器、私有桶和公有桶均已成功创建，但安装器更新 `sys_osclients` 时因旧库缺少 `NetworkIsInternet` 返回 `Unknown column`，整套安装停在 API 部署之前。

package/skills/v8-security/SKILL.md

@@ -3,9 +3,11 @@ name: v8-security
 description: Microi V8 安全指南。用于审查 DiyToken 与权限、可逆业务秘密、Passkey/TOTP/人脸步进验证、接口引擎安全、密钥管理、SQL 注入、匿名端点、文件上传和租户隔离。
 ---
 
-# Microi V8 安全最佳实践
-
-你正在开发 Microi 吾码平台的 V8 引擎代码，必须遵守以下安全规范。
+# Microi V8 安全最佳实践
+
+你正在开发 Microi 吾码平台的 V8 引擎代码，必须遵守以下安全规范。
+
+访问密钥由 `microi_list_my_access_keys`、`microi_create_my_access_key`、`microi_revoke_my_access_key` 管理，只允许当前用户、限期、最小 scope，明文仅创建时返回一次。外部身份回调固定为 `/api/ExternalLogin/Callback`，服务端校验租户、Provider、state、redirect 和回调域名，验证成功后仍签发 DiyToken。
 
 ## 0. 租户动态系统设置与密钥边界
 

package/skills/workspace-conventions/SKILL.md

@@ -102,6 +102,8 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 | 吾码 App 源码 | `microi.app/` |
 | 吾码 UniApp 源码 | `microi.uniapp/` |
 | 吾码官方网站 / 文档源码 | `microi.doc/` |
+| 吾码 AI 应用源码 | `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/` |
+| 吾码官方应用商城发行包源码 | `microi.apps/{packageKey}/` |
 
 以上路径只作为通用工作区相对路径规范，不写入具体本机盘符。跨仓库、空工作区或普通用户项目中，如果路径不存在，以插件生成的 `AGENTS.md`、MCP 配置和实际文件树为准。