@microi.net/cli 5.7.8 → 5.8.0

package/skills/ocr-engine/SKILL.md

@@ -1,113 +1,113 @@
----
-name: ocr-engine
-description: 为 Microi 吾码集成、配置、调用和验收通用 OCR 能力。处理 V8.OCR、/apiengine/platform-ocr-recognize、PaddleX/PaddleOCR 服务、SaaS 租户 OCR 配置、图片或 PDF 文字识别、OCR 安全边界、Docker 部署和多节点交付时使用。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi OCR 引擎
-
-## 先读取相关规范
-
-- 涉及租户配置时，读取 `../v8-saas-multi-tenant/SKILL.md`。
-- 涉及外部 OCR 服务时，读取 `../v8-http-integration/SKILL.md`。
-- 涉及 Base64、上传文件或私有文件时，读取 `../v8-file-upload/SKILL.md`。
-- 涉及权限、密钥、日志或匿名接口时，读取 `../v8-security/SKILL.md`。
-- 涉及数据库字段和表单 Tab 时，读取 `../microi-db-schema/SKILL.md`。
-
-## 固定架构
-
-Microi 后端只实现统一 OCR 网关、租户隔离、协议适配和安全治理，不在 .NET 进程内训练或维护 OCR 模型。默认提供方为独立部署的 PaddleX OCR 服务；业务代码只能调用 `IMicroiOcr`、`V8.OCR` 或官方 Managed 接口 `/apiengine/platform-ocr-recognize`，不得直接读取 SaaS 密钥并自行拼接 HTTP 请求。
-
-同步识别必须绑定当前请求和当前租户。批量、超大文件或长耗时 OCR 应进入共享数据库/MQ/outbox，以全局任务 Id 做幂等；不得把任务状态、队列或锁只放在单机内存中。
-
-## SaaS 配置
-
-配置位于 `sys_osclients` 的独立“OCR识别”Tab：
-
-| 字段 | 用途 | 默认值 |
-|---|---|---|
-| `OcrEnabled` | 租户总开关，默认关闭 | `0` |
-| `OcrProvider` | `PaddleX` 或 `PaddleXHighStability` | `PaddleX` |
-| `OcrEndpoint` | OCR 服务完整接口地址 | 空 |
-| `OcrApiKey` | 可选 Bearer 密钥，只允许后端使用 | 空 |
-| `OcrHeadersJson` | 可选服务端固定请求头 JSON | 空 |
-| `OcrTimeoutSeconds` | 单次超时秒数 | `60` |
-| `OcrMaxFileMB` | 单文件大小上限 | `20` |
-| `OcrMaxPages` | PDF 页数上限 | `10` |
-| `OcrMinConfidence` | 返回文本最低置信度 | `0` |
-
-这些配置不得投影到 `V8.OsClientModel`，不得由前端请求覆盖，不得写入普通日志。没有启用、没有 endpoint 或配置无效时必须失败关闭。
-
-## 调用
-
-接口引擎或后端表单事件中：
-
-```js
-var result = await V8.OCR.Recognize({
-  FileByteBase64: V8.FilesByteBase64.invoice,
-  FileName: 'invoice.png',
-  UseDocOrientationClassify: true,
-  UseDocUnwarping: true,
-  UseTextlineOrientation: true,
-  TextRecScoreThresh: 0.5,
-  ReturnWordBox: false
-});
-
-if (result.Code !== 1) {
-  return result;
-}
-
-return {
-  Code: 1,
-  Data: {
-    Text: result.Data.Text,
-    Pages: result.Data.Pages,
-    Provider: result.Data.Provider
-  }
-};
-```
-
-已登录客户端调用 `POST /apiengine/platform-ocr-recognize`，请求体与 `V8.OCR.Recognize` 一致，并携带正常登录 Token。`OsClient` 以 Token 解析结果为准。该接口由官方应用以 `Managed` 策略恢复；个性化逻辑只能写入租户 `platform-runtime-custom-hook`，且官方接口不会把文件 Base64、识别原文或密钥传给 Hook。
-
-标准成功结果包含 `Provider`、`Text`、`Pages`、`ElapsedMilliseconds`。每页包含 `PageIndex`、`Text`、`Regions`，每个区域包含 `Text`、`Confidence` 和归一化后的 `Polygon`。
-
-## 协议与输入边界
-
-- `PaddleX` 使用基础服务协议 `POST /ocr`。
-- `PaddleXHighStability` 使用 KServe 协议 `POST /v2/models/ocr/infer`。
-- 接受 PDF、PNG、JPEG、BMP、GIF、TIFF、WebP；同时检查文件扩展名、Base64 和文件魔数。
-- 固定 `visualize=false`，避免服务返回大体积可视化图片。
-- 由服务端限制文件大小、超时、PDF 页数、响应体大小和最低置信度。
-- 禁止接受调用方传入 endpoint、API key、任意请求头、代理地址或本地文件路径，防止 SSRF 和密钥绕过。
-- 日志只记录租户、提供方、状态码、耗时和安全裁剪后的错误，不记录文件 Base64、识别原文、API key 或完整响应。
-
-## Docker 与多节点
-
-- OCR 模型服务独立部署，固定 PaddleX/PaddlePaddle/模型版本；不要使用浮动 `latest` 直接上线。
-- CPU 基线位于 `../../Microi.Server/Microi.OCR/deploy/paddlex/`，固定 PaddleX 3.6.1 与 PaddlePaddle 3.2.2；公开镜像固定为 `registry.cn-hangzhou.aliyuncs.com/microios/paddlex-ocr:3.6.1-paddle3.2.2-cpu`，当前只交付 `linux/amd64`。PaddlePaddle 3.3.0 存在 CPU oneDNN PIR 推理兼容问题，在完成真实图片回归前不得升级。
-- 发布镜像使用同目录 `publish-image.ps1`：它从根目录发布配置读取凭据，通过隔离 Docker 配置和 `--password-stdin` 登录，推送后退出并匿名回读公开摘要。不得在命令行、日志或文档中展开用户名/密码，也不得只凭 `docker push` 返回成功就宣布国内镜像可用。
-- 发布镜像时执行 `create_pipeline("OCR")` 预置默认产线模型。运行时使用 named volume 挂载 `/home/microi/.paddlex`，让 Docker 首次创建卷时从镜像复制模型；不要改成空宿主机 bind mount，否则会遮住镜像内的预置模型并触发重新下载。
-- OCR 宿主机端口只绑定 `127.0.0.1`；Docker 化 API 与 OCR 同时加入 external bridge 网络 `microi-ocr`，一键安装的内部 endpoint 固定为 `http://microi-install-ocr:8080/ocr`。不得通过公网/LAN 回环调用同机 OCR。
-- `install-microi.sh` 默认尝试安装 OCR，但先部署 API/Web 并通过 liveness、完整 `ServerVersion` 升级链和 readiness。随后必须依次满足“固定镜像拉取并回读为 amd64 → OCR healthy → Upgrade29 的 9 个物理字段数据库回读 → 唯一活动主租户 → 配置写入后回读 → API 重启 readiness”才设置 `OcrEnabled=1`；任一步失败都保持 OCR 能力关闭并记录警告，但不得中断已经可用的核心平台。字段每秒回读一次且最多 15 秒；正常升级应首轮命中，镜像过旧或迁移失败应快速关闭 OCR，禁止无意义等待 5 分钟。不要用安装脚本直接伪造 `diy_field` 元数据绕过 Upgrade29。
-- API/Web 官方浮动 `latest` 必须在 Compose 启动时强制回源拉取，避免旧本机镜像缺少 Upgrade29。核心门禁失败时输出“安装未完成”恢复汇总并保留非零退出码；OCR 字段、服务或配置门禁失败时，成功汇总明确显示“OCR SaaS 未启用”和附加能力警告。两种汇总都不是启用 OCR 的依据。
-- OCR 使用固定不可变版本，不加入只跟踪 API/Web 浮动标签的 Watchtower 自动更新列表；升级镜像时先发布新 tag、匿名回读 digest/架构，再修改 Compose 与安装器。
-- 登录国内镜像源必须从本机发布配置读取凭据并走 `docker login --password-stdin`，不得输出密码。推送成功不是发布验收，必须使用隔离的匿名 Docker config 回读 manifest/digest，必要时再做匿名拉取。
-- 不要在内存不足的共享开发机上直接构建模型镜像。构建前检查物理内存、Docker 占用与同类进程；保留至少 `max(6 GB, 物理内存 20%)`，不足时延后构建而不是停止他人服务。
-- API 多节点共享同一个或同一组 OCR endpoint；每节点仅保留无状态 `HttpClient`。
-- OCR 服务至少配置 readiness、并发上限、CPU/GPU 资源上限、请求体上限和访问控制。
-- GPU 推理采用独立 Worker/服务池，避免 OCR 模型抢占 Microi API 内存。
-- 滚动升级时保持旧新 OCR 响应协议兼容；协议变更先扩展解析器，再升级服务。
-
-## 验收门禁
-
-交付时分别报告：
-
-1. 源码：网关、V8、REST、SaaS 字段、密钥投影隔离是否齐全。
-2. 定向测试：基础协议、高稳定协议、低置信度过滤、错误响应、配置隔离。
-3. 数据库：目标 `OsClient` 的 Tab、字段和物理列经 MCP 写后回读。
-4. 服务：真实 PNG/JPEG/PDF 至少各一例，包含中英文、旋转和多页场景。
-5. 多节点：两个 API 节点同时调用，同租户限制一致，服务故障时均能超时/降级且不泄漏密钥。
-6. UI：SaaS 配置表单能查看独立 Tab、保存配置，密码字段不出现在普通前端上下文。
-
-没有真实 OCR endpoint、服务版本和样例识别结果时，只能声明“平台接入完成、运行验收待配置”，不能声明生产 OCR 已可用。
+---
+name: ocr-engine
+description: 为 Microi 吾码集成、配置、调用和验收通用 OCR 能力。处理 V8.OCR、/apiengine/platform-ocr-recognize、PaddleX/PaddleOCR 服务、SaaS 租户 OCR 配置、图片或 PDF 文字识别、OCR 安全边界、Docker 部署和多节点交付时使用。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi OCR 引擎
+
+## 先读取相关规范
+
+- 涉及租户配置时，读取 `../v8-saas-multi-tenant/SKILL.md`。
+- 涉及外部 OCR 服务时，读取 `../v8-http-integration/SKILL.md`。
+- 涉及 Base64、上传文件或私有文件时，读取 `../v8-file-upload/SKILL.md`。
+- 涉及权限、密钥、日志或匿名接口时，读取 `../v8-security/SKILL.md`。
+- 涉及数据库字段和表单 Tab 时，读取 `../microi-db-schema/SKILL.md`。
+
+## 固定架构
+
+Microi 后端只实现统一 OCR 网关、租户隔离、协议适配和安全治理，不在 .NET 进程内训练或维护 OCR 模型。默认提供方为独立部署的 PaddleX OCR 服务；业务代码只能调用 `IMicroiOcr`、`V8.OCR` 或官方 Managed 接口 `/apiengine/platform-ocr-recognize`，不得直接读取 SaaS 密钥并自行拼接 HTTP 请求。
+
+同步识别必须绑定当前请求和当前租户。批量、超大文件或长耗时 OCR 应进入共享数据库/MQ/outbox，以全局任务 Id 做幂等；不得把任务状态、队列或锁只放在单机内存中。
+
+## SaaS 配置
+
+配置位于 `sys_osclients` 的独立“OCR识别”Tab：
+
+| 字段 | 用途 | 默认值 |
+|---|---|---|
+| `OcrEnabled` | 租户总开关，默认关闭 | `0` |
+| `OcrProvider` | `PaddleX` 或 `PaddleXHighStability` | `PaddleX` |
+| `OcrEndpoint` | OCR 服务完整接口地址 | 空 |
+| `OcrApiKey` | 可选 Bearer 密钥，只允许后端使用 | 空 |
+| `OcrHeadersJson` | 可选服务端固定请求头 JSON | 空 |
+| `OcrTimeoutSeconds` | 单次超时秒数 | `60` |
+| `OcrMaxFileMB` | 单文件大小上限 | `20` |
+| `OcrMaxPages` | PDF 页数上限 | `10` |
+| `OcrMinConfidence` | 返回文本最低置信度 | `0` |
+
+这些配置不得投影到 `V8.OsClientModel`，不得由前端请求覆盖，不得写入普通日志。没有启用、没有 endpoint 或配置无效时必须失败关闭。
+
+## 调用
+
+接口引擎或后端表单事件中：
+
+```js
+var result = await V8.OCR.Recognize({
+  FileByteBase64: V8.FilesByteBase64.invoice,
+  FileName: 'invoice.png',
+  UseDocOrientationClassify: true,
+  UseDocUnwarping: true,
+  UseTextlineOrientation: true,
+  TextRecScoreThresh: 0.5,
+  ReturnWordBox: false
+});
+
+if (result.Code !== 1) {
+  return result;
+}
+
+return {
+  Code: 1,
+  Data: {
+    Text: result.Data.Text,
+    Pages: result.Data.Pages,
+    Provider: result.Data.Provider
+  }
+};
+```
+
+已登录客户端调用 `POST /apiengine/platform-ocr-recognize`，请求体与 `V8.OCR.Recognize` 一致，并携带正常登录 Token。`OsClient` 以 Token 解析结果为准。该接口由官方应用以 `Managed` 策略恢复；个性化逻辑只能写入租户 `platform-runtime-custom-hook`，且官方接口不会把文件 Base64、识别原文或密钥传给 Hook。
+
+标准成功结果包含 `Provider`、`Text`、`Pages`、`ElapsedMilliseconds`。每页包含 `PageIndex`、`Text`、`Regions`，每个区域包含 `Text`、`Confidence` 和归一化后的 `Polygon`。
+
+## 协议与输入边界
+
+- `PaddleX` 使用基础服务协议 `POST /ocr`。
+- `PaddleXHighStability` 使用 KServe 协议 `POST /v2/models/ocr/infer`。
+- 接受 PDF、PNG、JPEG、BMP、GIF、TIFF、WebP；同时检查文件扩展名、Base64 和文件魔数。
+- 固定 `visualize=false`，避免服务返回大体积可视化图片。
+- 由服务端限制文件大小、超时、PDF 页数、响应体大小和最低置信度。
+- 禁止接受调用方传入 endpoint、API key、任意请求头、代理地址或本地文件路径，防止 SSRF 和密钥绕过。
+- 日志只记录租户、提供方、状态码、耗时和安全裁剪后的错误，不记录文件 Base64、识别原文、API key 或完整响应。
+
+## Docker 与多节点
+
+- OCR 模型服务独立部署，固定 PaddleX/PaddlePaddle/模型版本；不要使用浮动 `latest` 直接上线。
+- CPU 基线位于 `../../Microi.Server/Microi.OCR/deploy/paddlex/`，固定 PaddleX 3.6.1 与 PaddlePaddle 3.2.2；公开镜像固定为 `registry.cn-hangzhou.aliyuncs.com/microios/paddlex-ocr:3.6.1-paddle3.2.2-cpu`，当前只交付 `linux/amd64`。PaddlePaddle 3.3.0 存在 CPU oneDNN PIR 推理兼容问题，在完成真实图片回归前不得升级。
+- 发布镜像使用同目录 `publish-image.ps1`：它从根目录发布配置读取凭据，通过隔离 Docker 配置和 `--password-stdin` 登录，推送后退出并匿名回读公开摘要。不得在命令行、日志或文档中展开用户名/密码，也不得只凭 `docker push` 返回成功就宣布国内镜像可用。
+- 发布镜像时执行 `create_pipeline("OCR")` 预置默认产线模型。运行时使用 named volume 挂载 `/home/microi/.paddlex`，让 Docker 首次创建卷时从镜像复制模型；不要改成空宿主机 bind mount，否则会遮住镜像内的预置模型并触发重新下载。
+- OCR 宿主机端口只绑定 `127.0.0.1`；Docker 化 API 与 OCR 同时加入 external bridge 网络 `microi-ocr`，一键安装的内部 endpoint 固定为 `http://microi-install-ocr:8080/ocr`。不得通过公网/LAN 回环调用同机 OCR。
+- `install-microi.sh` 默认尝试安装 OCR，但先部署 API/Web 并通过 liveness、完整 `ServerVersion` 升级链和 readiness。随后必须依次满足“固定镜像拉取并回读为 amd64 → OCR healthy → Upgrade29 的 9 个物理字段数据库回读 → 唯一活动主租户 → 配置写入后回读 → API 重启 readiness”才设置 `OcrEnabled=1`；任一步失败都保持 OCR 能力关闭并记录警告，但不得中断已经可用的核心平台。字段每秒回读一次且最多 15 秒；正常升级应首轮命中，镜像过旧或迁移失败应快速关闭 OCR，禁止无意义等待 5 分钟。不要用安装脚本直接伪造 `diy_field` 元数据绕过 Upgrade29。
+- API/Web 官方浮动 `latest` 必须在 Compose 启动时强制回源拉取，避免旧本机镜像缺少 Upgrade29。核心门禁失败时输出“安装未完成”恢复汇总并保留非零退出码；OCR 字段、服务或配置门禁失败时，成功汇总明确显示“OCR SaaS 未启用”和附加能力警告。两种汇总都不是启用 OCR 的依据。
+- OCR 使用固定不可变版本，不加入只跟踪 API/Web 浮动标签的 Watchtower 自动更新列表；升级镜像时先发布新 tag、匿名回读 digest/架构，再修改 Compose 与安装器。
+- 登录国内镜像源必须从本机发布配置读取凭据并走 `docker login --password-stdin`，不得输出密码。推送成功不是发布验收，必须使用隔离的匿名 Docker config 回读 manifest/digest，必要时再做匿名拉取。
+- 不要在内存不足的共享开发机上直接构建模型镜像。构建前检查物理内存、Docker 占用与同类进程；保留至少 `max(6 GB, 物理内存 20%)`，不足时延后构建而不是停止他人服务。
+- API 多节点共享同一个或同一组 OCR endpoint；每节点仅保留无状态 `HttpClient`。
+- OCR 服务至少配置 readiness、并发上限、CPU/GPU 资源上限、请求体上限和访问控制。
+- GPU 推理采用独立 Worker/服务池，避免 OCR 模型抢占 Microi API 内存。
+- 滚动升级时保持旧新 OCR 响应协议兼容；协议变更先扩展解析器，再升级服务。
+
+## 验收门禁
+
+交付时分别报告：
+
+1. 源码：网关、V8、REST、SaaS 字段、密钥投影隔离是否齐全。
+2. 定向测试：基础协议、高稳定协议、低置信度过滤、错误响应、配置隔离。
+3. 数据库：目标 `OsClient` 的 Tab、字段和物理列经 MCP 写后回读。
+4. 服务：真实 PNG/JPEG/PDF 至少各一例，包含中英文、旋转和多页场景。
+5. 多节点：两个 API 节点同时调用，同租户限制一致，服务故障时均能超时/降级且不泄漏密钥。
+6. UI：SaaS 配置表单能查看独立 Tab、保存配置，密码字段不出现在普通前端上下文。
+
+没有真实 OCR endpoint、服务版本和样例识别结果时，只能声明“平台接入完成、运行验收待配置”，不能声明生产 OCR 已可用。

package/skills/ocr-engine/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Microi OCR 引擎"
-  short_description: "集成、配置和验证 Microi 通用 OCR 能力"
-  default_prompt: "Use $ocr-engine to integrate and validate tenant-isolated OCR in Microi."
+interface:
+  display_name: "Microi OCR 引擎"
+  short_description: "集成、配置和验证 Microi 通用 OCR 能力"
+  default_prompt: "Use $ocr-engine to integrate and validate tenant-isolated OCR in Microi."

package/skills/page-engine/SKILL.md

@@ -1,12 +1,12 @@
----
-name: page-engine
-description: 生成和审查 Microi 界面引擎 Page Engine 页面 JSON。用于创建仪表盘、图表、表格、地图、组件、页面布局，或校验 mic_page formData JSON。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 界面引擎（Page Engine）页面 JSON 生成
-
+---
+name: page-engine
+description: 生成和审查 Microi 界面引擎 Page Engine 页面 JSON。用于创建仪表盘、图表、表格、地图、组件、页面布局，或校验 mic_page formData JSON。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 界面引擎（Page Engine）页面 JSON 生成
+
 MCP 的生成/保存入口包含 `microi_build_page_design` 与 `microi_save_page_design`；版本治理入口见下文。保存工具写入后仍需回读 `mic_page`，不能把生成成功当作持久化成功。
 
 ## 紧凑报表与平台主题
@@ -18,7 +18,7 @@ MCP 的生成/保存入口包含 `microi_build_page_design` 与 `microi_save_pag
 运行容器默认 `wrapperOption.heightMode="content"`，`height` 只保留设计器布局尺寸。仅需固定图形画布时设为 `fixed`；图表自身可以设置 240–320px 高度。不要为一行指标、标题、三行表格预留 200–400px 空容器。紧凑布局的卡片间距建议 10–16px，面板内边距 8–16px；统计组件 `widgetParams[24].value` 支持 `summary`（图标和大数字）、`detail`（多行小指标）及兼容的 `cards`。
 
 用户提供参考截图时，先拆出面板行列比例、指标主次、图表与表格高度、标题/筛选位置，再用原生 pannel/statistic/chart/tabel/list 组合配置。不能把所有指标替换成一排大色块，也不能用模板假数据声称已接通客户业务。必须用同一视口截图检查浅色和平台深色，检查页面缩放后的断行与纵向空白；布局接近度和真实数据绑定分别验收。
-
+
 ### 平台智能工作首页
 
 保留 `aiengine` 原生 AI 创作中心，与 `homeoverview` 工作概览组成桌面首行 14/10 栅格；任务、月历与公告放在下一行，移动端自动切为 24 栅格。不能把任务的完整 15 行列表或未配置日程的大空白块直接堆在首屏。
@@ -30,177 +30,177 @@ MCP 的生成/保存入口包含 `microi_build_page_design` 与 `microi_save_pag
 - 修改已有首页前通过 MCP 读取页面及历史 `CurrentHash`，保存传 `expectedCurrentHash`，再回读 JSON 和历史，保留可恢复版本。
 
 你正在为 Microi 吾码平台生成界面引擎页面的 JSON 数据。界面引擎页面由 `formData` 对象描述，用户导入 JSON 即可使用。
-
-<!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=page-engine-000 sha256=e9ccd20e2c3504afc0a91f5dbe93ed755aed4e83e9ffec13af5b9d60528986e0 -->
-## 设计器源码事件
-
-只有在扩展界面引擎设计器源码时才使用全局事件总线。用
-`EventBus.on(eventName, handler)` 监听保存、日期选择或组件跳转等事件，并在
-组件卸载时逐项调用 `EventBus.off(eventName)`。重复挂载不解绑会造成一次操作
-触发多次；普通页面 JSON 生成不需要注册事件总线。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-001 sha256=57717991f9c7de557b524ec36fc9bdd716080b71b682439f1b6662b0b9b2f45c -->
-## 核心数据结构
-
-```
-formData（页面）
-├── Id: string                  // 页面唯一ID（GUID）
-├── Title: string               // 页面标题
-├── Number: string              // 页面编号（如 PAGE1）
-├── Desc: string                // 页面描述
-└── JsonObj
-    ├── formConfig              // 页面全局配置
-    └── wrapperList[]           // 容器列表
-        ├── wrapperOption       // 容器配置
-        └── widgetList[]        // 组件列表
-            ├── widgetOption    // 组件通用配置
-            └── widgetParams[]  // 组件私有参数
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-002 sha256=6a1a85b40bcb5f8be694b0aad73a805083acd0d6fcd9cba36278dc9b51d24dcb -->
-## formConfig 页面全局配置
-
-```json
-{
-  "gutter": 0, "mask": true, "drag": true, "left": true,
-  "hover": true, "shadow": true, "link": false, "watermark": false,
-  "mobile": false, "dark": false, "autoRefresh": 0, "lastRefreshTime": "",
-  "watermarkStyle": {
-    "content": "Microi吾码",
-    "font": { "fontSize": 16, "color": "rgba(255, 0, 0, 0.15)" },
-    "rotate": -22
-  },
-  "dynamicStyle": { "padding": "4px", "backgroundColor": "", "opacity": 1 }
-}
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-003 sha256=8afb75b0e4d85ab9f56a7ba018e1cc50f758d3e604683d8c38d5f0a45d53f135 -->
-## 容器类型
-
-| type | label | 说明 |
-|------|-------|------|
-| `pannel` | 卡片 | 标准容器，包含一个 `widgetList` |
-| `tabs` | 选项卡 | 多标签页容器，使用 `tabWidgetMap` 存储每个 tab 的组件 |
-
-### 卡片容器（pannel）关键字段
-
-```json
-{
-  "type": "pannel",
-  "label": "卡片",
-  "hidden": false,
-  "wrapperOption": {
-    "number": 10001,               // 随机5位整数，页面内唯一
-    "span": 12,                    // 栅格宽度（1-24，24=满宽）
-    "height": 300,                 // 容器高度（px）
-    "margin": "0px 10px 10px 0px",
-    "dynamicStyle": { "padding": "10px", "backgroundColor": "" },
-    "titleOption": {
-      "hidden": true,              // true=隐藏标题
-      "title": "未命名",
-      "dynamicStyle": { "textAlign": "left", "padding": "0px", "height": "20px", "lineHeight": "20px", "fontSize": "14px", "color": "" },
-      "moreOption": { "hidden": true, "icon": "More", "iconShow": false, "text": "更多", "linkurl": "/", "linktype": "router", "refresh": "0", "datetime": "0", "autotime": false, "autotimeval": 1, "dynamicStyle": { "color": "", "fontSize": "12px" } }
-    }
-  },
-  "widgetList": []
-}
-```
-
-### 选项卡容器（tabs）
-
-组件放在 `tabWidgetMap[tabKey][]` 中，**不**放在 `widgetList` 中。
-
-```json
-{
-  "type": "tabs",
-  "wrapperOption": {
-    "number": 10002, "span": 24, "height": 400,
-    "tabType": "",            // '' | 'card' | 'border-card'
-    "tabPosition": "top",     // 'top' | 'right' | 'bottom' | 'left'
-    "tabs": [
-      { "key": "tab_1", "label": "标签页1" },
-      { "key": "tab_2", "label": "标签页2" }
-    ],
-    "activeTab": "tab_1"
-  },
-  "tabWidgetMap": { "tab_1": [], "tab_2": [] },
-  "widgetList": []
-}
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-004 sha256=9c7c85bb0d25267d07e45d9abeb5691c2f0ffd9da233351cf2f448a9b848cea5 -->
-## 组件通用结构
-
-```json
-{
-  "type": "bar",
-  "label": "柱状图",
-  "category": 0,
-  "show": 1,
-  "widgetOption": {
-    "number": 20001,           // 随机5位整数，页面内唯一
-    "wrapperNumber": 10001,    // 必须等于所在容器的 wrapperOption.number
-    "span": 24,
-    "height": 280,
-    "dynamicStyle": { "padding": "8px", "backgroundColor": "" }
-  },
-  "widgetParams": []
-}
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-005 sha256=c1e31dede775f14761182fc197cf428d494806c4503a622ffdad3d16d091d3e0 -->
-## widgetParams 参数类型
-
-| type | 说明 | value 类型 |
-|------|------|-----------|
-| `textarea` | 多行文本（数据来源） | `string` |
-| `input` | 单行文本 | `string` |
-| `number` | 数字 | `number` |
-| `switch` | 开关 | `boolean` |
-| `slider` | 滑块 | `number` |
-| `color` | 颜色选择 | `string` |
-| `select` | 下拉选择 | `string` |
-| `radio` | 单选组 | `string` |
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-006 sha256=2c021e43f4f0d730da1f5a5cf6a2d314589435e2bb9ff573148c787538a8cc86 -->
-## 数据来源（widgetParams[0]）
-
-大多数组件的第一个参数（sort=0）是"数据来源"：
-- **静态数据**：`value` 为空，数据在 `typeOptions.dataJson` 中
-- **动态接口**：`value` 设为接口地址，运行时请求替换 `dataJson`
-
-**接口引擎地址格式：**
-```
-$ApiBase$/apiengine/{ApiEngineKey}
-```
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=page-engine-007 sha256=ce0486eb9d2282bc199972e167e85aca7b03860d15abdd03982c4a23a90e206e -->
-## 运行态布局与滚动规范
-
+
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=page-engine-000 sha256=e9ccd20e2c3504afc0a91f5dbe93ed755aed4e83e9ffec13af5b9d60528986e0 -->
+## 设计器源码事件
+
+只有在扩展界面引擎设计器源码时才使用全局事件总线。用
+`EventBus.on(eventName, handler)` 监听保存、日期选择或组件跳转等事件，并在
+组件卸载时逐项调用 `EventBus.off(eventName)`。重复挂载不解绑会造成一次操作
+触发多次；普通页面 JSON 生成不需要注册事件总线。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-001 sha256=57717991f9c7de557b524ec36fc9bdd716080b71b682439f1b6662b0b9b2f45c -->
+## 核心数据结构
+
+```
+formData（页面）
+├── Id: string                  // 页面唯一ID（GUID）
+├── Title: string               // 页面标题
+├── Number: string              // 页面编号（如 PAGE1）
+├── Desc: string                // 页面描述
+└── JsonObj
+    ├── formConfig              // 页面全局配置
+    └── wrapperList[]           // 容器列表
+        ├── wrapperOption       // 容器配置
+        └── widgetList[]        // 组件列表
+            ├── widgetOption    // 组件通用配置
+            └── widgetParams[]  // 组件私有参数
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-002 sha256=6a1a85b40bcb5f8be694b0aad73a805083acd0d6fcd9cba36278dc9b51d24dcb -->
+## formConfig 页面全局配置
+
+```json
+{
+  "gutter": 0, "mask": true, "drag": true, "left": true,
+  "hover": true, "shadow": true, "link": false, "watermark": false,
+  "mobile": false, "dark": false, "autoRefresh": 0, "lastRefreshTime": "",
+  "watermarkStyle": {
+    "content": "Microi吾码",
+    "font": { "fontSize": 16, "color": "rgba(255, 0, 0, 0.15)" },
+    "rotate": -22
+  },
+  "dynamicStyle": { "padding": "4px", "backgroundColor": "", "opacity": 1 }
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-003 sha256=8afb75b0e4d85ab9f56a7ba018e1cc50f758d3e604683d8c38d5f0a45d53f135 -->
+## 容器类型
+
+| type | label | 说明 |
+|------|-------|------|
+| `pannel` | 卡片 | 标准容器，包含一个 `widgetList` |
+| `tabs` | 选项卡 | 多标签页容器，使用 `tabWidgetMap` 存储每个 tab 的组件 |
+
+### 卡片容器（pannel）关键字段
+
+```json
+{
+  "type": "pannel",
+  "label": "卡片",
+  "hidden": false,
+  "wrapperOption": {
+    "number": 10001,               // 随机5位整数，页面内唯一
+    "span": 12,                    // 栅格宽度（1-24，24=满宽）
+    "height": 300,                 // 容器高度（px）
+    "margin": "0px 10px 10px 0px",
+    "dynamicStyle": { "padding": "10px", "backgroundColor": "" },
+    "titleOption": {
+      "hidden": true,              // true=隐藏标题
+      "title": "未命名",
+      "dynamicStyle": { "textAlign": "left", "padding": "0px", "height": "20px", "lineHeight": "20px", "fontSize": "14px", "color": "" },
+      "moreOption": { "hidden": true, "icon": "More", "iconShow": false, "text": "更多", "linkurl": "/", "linktype": "router", "refresh": "0", "datetime": "0", "autotime": false, "autotimeval": 1, "dynamicStyle": { "color": "", "fontSize": "12px" } }
+    }
+  },
+  "widgetList": []
+}
+```
+
+### 选项卡容器（tabs）
+
+组件放在 `tabWidgetMap[tabKey][]` 中，**不**放在 `widgetList` 中。
+
+```json
+{
+  "type": "tabs",
+  "wrapperOption": {
+    "number": 10002, "span": 24, "height": 400,
+    "tabType": "",            // '' | 'card' | 'border-card'
+    "tabPosition": "top",     // 'top' | 'right' | 'bottom' | 'left'
+    "tabs": [
+      { "key": "tab_1", "label": "标签页1" },
+      { "key": "tab_2", "label": "标签页2" }
+    ],
+    "activeTab": "tab_1"
+  },
+  "tabWidgetMap": { "tab_1": [], "tab_2": [] },
+  "widgetList": []
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-004 sha256=9c7c85bb0d25267d07e45d9abeb5691c2f0ffd9da233351cf2f448a9b848cea5 -->
+## 组件通用结构
+
+```json
+{
+  "type": "bar",
+  "label": "柱状图",
+  "category": 0,
+  "show": 1,
+  "widgetOption": {
+    "number": 20001,           // 随机5位整数，页面内唯一
+    "wrapperNumber": 10001,    // 必须等于所在容器的 wrapperOption.number
+    "span": 24,
+    "height": 280,
+    "dynamicStyle": { "padding": "8px", "backgroundColor": "" }
+  },
+  "widgetParams": []
+}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-005 sha256=c1e31dede775f14761182fc197cf428d494806c4503a622ffdad3d16d091d3e0 -->
+## widgetParams 参数类型
+
+| type | 说明 | value 类型 |
+|------|------|-----------|
+| `textarea` | 多行文本（数据来源） | `string` |
+| `input` | 单行文本 | `string` |
+| `number` | 数字 | `number` |
+| `switch` | 开关 | `boolean` |
+| `slider` | 滑块 | `number` |
+| `color` | 颜色选择 | `string` |
+| `select` | 下拉选择 | `string` |
+| `radio` | 单选组 | `string` |
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-006 sha256=2c021e43f4f0d730da1f5a5cf6a2d314589435e2bb9ff573148c787538a8cc86 -->
+## 数据来源（widgetParams[0]）
+
+大多数组件的第一个参数（sort=0）是"数据来源"：
+- **静态数据**：`value` 为空，数据在 `typeOptions.dataJson` 中
+- **动态接口**：`value` 设为接口地址，运行时请求替换 `dataJson`
+
+**接口引擎地址格式：**
+```
+$ApiBase$/apiengine/{ApiEngineKey}
+```
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=page-engine-007 sha256=ce0486eb9d2282bc199972e167e85aca7b03860d15abdd03982c4a23a90e206e -->
+## 运行态布局与滚动规范
+
 - 页面只保留一个主滚动容器：仪表盘、首页和嵌套界面优先继承最外层页面滚动；单个 `pannel`、`workcenter`、`diytable`、`diycalendar`、嵌套 `pageengine` 在运行态默认使用内容自适应高度和 `overflow: visible`，不得无条件设置 `overflow: auto`。
 - 经典桌面主滚动容器为路由内容区，导航与 Tab 留在视口内；移动端继续保留外层文档滚动。图表在异步挂载后绑定尺寸观察器，切换导航、收缩侧栏及改变窗口宽度都应重新测量，禁止仅隐藏溢出而保留错误画布宽度。真实回归覆盖两种导航、两种桌面宽度，以及日程创建后刷新、备注编辑和删除。
-- 固定高度只用于设计器拖拽预览、图表画布或确有虚拟滚动需求的组件。设计态可按 `widgetOption.height` 提供滚动，运行态必须先验证内容能完整展开；不能用双滚动条掩盖容器高度不足。
-- 表格型容器通常按 15 条数据验收，表头、工具栏、全部数据行和分页区应同时可见；首页紧凑表格可通过 `diy-table` 的 `PageSizeList` 追加 `[10]`，并在 `sys_menu.DefaultPageSize` 为空时默认选择候选页码中的最小值。空间不足时先压缩统计卡、工具栏、行高和间距，再考虑增加外层页面长度，不隐藏分页、不在卡片内部滚动。
-- 同一行的容器使用一致的左右边距、内边距、标题高度和顶部基线；同层卡片间距必须相同，左右边缘、标题、工具栏和内容区应形成稳定对齐线。推荐使用统一的 8px 基础间距和 8/12/16px 倍数。
-- 成对容器应设置相同的最小高度；内容较少的组件通过内容居中、合理留白或自适应布局消化空间，不能在底部留下明显的大块无意义空白。内容较多时允许容器自然增高并由页面继续向下滚动。
-- 日历和公告应完整展示工具栏、主体和底部操作区；日历优先使用 `height: auto` / `contentHeight: auto`，公告优先使用标准表单引擎分页与权限按钮。
-- 运行态移动端必须按实际视口自动切为 24 栅格，不能只依赖保存 JSON 中的 `formConfig.mobile`；窗口旋转或宽度变化时也要同步。嵌入的 `diytable` 不得渲染独立列表页的固定返回栏和全局 FAB，新增、页面按钮、批量操作应留在当前容器工具栏内；容器标题操作区允许紧凑换行，但不能绝对定位覆盖标题或其它卡片。
-- `aiengine` 在移动端嵌入首页时应使用内容自适应高度和外层页面滚动，指标卡与快捷入口优先两列紧凑排布，避免 4 个指标和全部快捷入口单列堆叠造成超长首屏；输入区和模型/推理设置必须保持可见且不横向溢出。
-- 交付前必须在真实运行页检查：是否存在内部纵向/横向滚动条、15 条表格分页是否可见、同排容器是否对齐、四周边距是否一致、组件底部是否有异常空白。仅检查设计器画布不算验收完成。
-
-<!-- /microi-progressive:chunk -->
-## 详细参考路由（渐进披露）
-
-仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
-
-- [references/progressive-01-所有组件类型.md](references/progressive-01-所有组件类型.md)：所有组件类型；Office/PDF 在线预览自然语言生成规则；searchData 查询条件通用结构
-- [references/progressive-02-版本历史-并发保存与回滚.md](references/progressive-02-版本历史-并发保存与回滚.md)：版本历史、并发保存与回滚；本地撤销、Vue 源码桥与资产包；生成 JSON 注意事项；经营看板周期筛选与布局规则
-<!-- microi-progressive:end -->
+- 固定高度只用于设计器拖拽预览、图表画布或确有虚拟滚动需求的组件。设计态可按 `widgetOption.height` 提供滚动，运行态必须先验证内容能完整展开；不能用双滚动条掩盖容器高度不足。
+- 表格型容器通常按 15 条数据验收，表头、工具栏、全部数据行和分页区应同时可见；首页紧凑表格可通过 `diy-table` 的 `PageSizeList` 追加 `[10]`，并在 `sys_menu.DefaultPageSize` 为空时默认选择候选页码中的最小值。空间不足时先压缩统计卡、工具栏、行高和间距，再考虑增加外层页面长度，不隐藏分页、不在卡片内部滚动。
+- 同一行的容器使用一致的左右边距、内边距、标题高度和顶部基线；同层卡片间距必须相同，左右边缘、标题、工具栏和内容区应形成稳定对齐线。推荐使用统一的 8px 基础间距和 8/12/16px 倍数。
+- 成对容器应设置相同的最小高度；内容较少的组件通过内容居中、合理留白或自适应布局消化空间，不能在底部留下明显的大块无意义空白。内容较多时允许容器自然增高并由页面继续向下滚动。
+- 日历和公告应完整展示工具栏、主体和底部操作区；日历优先使用 `height: auto` / `contentHeight: auto`，公告优先使用标准表单引擎分页与权限按钮。
+- 运行态移动端必须按实际视口自动切为 24 栅格，不能只依赖保存 JSON 中的 `formConfig.mobile`；窗口旋转或宽度变化时也要同步。嵌入的 `diytable` 不得渲染独立列表页的固定返回栏和全局 FAB，新增、页面按钮、批量操作应留在当前容器工具栏内；容器标题操作区允许紧凑换行，但不能绝对定位覆盖标题或其它卡片。
+- `aiengine` 在移动端嵌入首页时应使用内容自适应高度和外层页面滚动，指标卡与快捷入口优先两列紧凑排布，避免 4 个指标和全部快捷入口单列堆叠造成超长首屏；输入区和模型/推理设置必须保持可见且不横向溢出。
+- 交付前必须在真实运行页检查：是否存在内部纵向/横向滚动条、15 条表格分页是否可见、同排容器是否对齐、四周边距是否一致、组件底部是否有异常空白。仅检查设计器画布不算验收完成。
+
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
+
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
+
+- [references/progressive-01-所有组件类型.md](references/progressive-01-所有组件类型.md)：所有组件类型；Office/PDF 在线预览自然语言生成规则；searchData 查询条件通用结构
+- [references/progressive-02-版本历史-并发保存与回滚.md](references/progressive-02-版本历史-并发保存与回滚.md)：版本历史、并发保存与回滚；本地撤销、Vue 源码桥与资产包；生成 JSON 注意事项；经营看板周期筛选与布局规则
+<!-- microi-progressive:end -->