@microi.net/cli 6.2.4 → 6.3.2

package/skills/microi-deployment/references/deployment-matrix.md

@@ -1,145 +1,167 @@
-# 部署矩阵与验收
-
-## 中文官网路由
-
-| 文档 | 主要用途 |
-|---|---|
-| `microi.doc/docs/doc/getting-started/docker-run.md` | Docker、Compose、离线包、依赖编排 |
-| `microi.doc/docs/doc/getting-started/win-install-microi.md` | Windows/IIS 安装 |
-| `microi.doc/docs/doc/getting-started/local-run.md` | 后端/前端源码运行、测试与构建 |
-| `microi.doc/docs/doc/getting-started/start-use.md` | 部署后创建表、表单、菜单的首条业务链路 |
-
-英文目录由中文生成，不作为本轮人工单独维护源。
-
-## 服务依赖
-
-| 依赖 | 作用 | 生产要求 |
-|---|---|---|
-| API/Worker | 后端、V8、任务与接口 | 至少双节点关键场景验证 |
-| Web/Nginx/IIS | 前端与反向代理 | HTTPS、上传体积、超时、静态缓存 |
-| MySQL/兼容业务库 | 平台与业务数据 | 备份、字符集、连接池、慢查询 |
-| Redis | 会话、缓存、租约、进度 | 持久化/高可用、按租户 Key |
-| MongoDB | 日志等文档数据 | 持久卷、容量与重放验收 |
-| MinIO/HDFS | 上传和应用资源 | 公私桶、持久卷、备份、CORS |
-
-可选依赖如翻译服务、Ollama、Qdrant 只在相应能力启用时部署，不把演示编排无条件
-带入生产。
-
-视觉引擎使用一个独立编排，默认运行 `vision/media` 两个容器；`behavior` 通过同名
-profile 显式选装，默认不下载 Qwen、不启动 Ollama。复用吾码API、Web和数据库。
-服务器准备工具为 `Microi.Server/tools/vision-deployment/deploy.py`，详细操作原位维护在
-`docker-run.html#vision-engine-compose`。CPU/CUDA分别锁定已发布镜像digest；模型下载
-校验大小/SHA，配置私有挂载，手机走平台HTTPS中继。行为模型默认不启用，独立准确率
-验收与基础部署就绪分别记录。Ollama设置 `OLLAMA_NOPRUNE=true`，模型导入期间临时RW，
-结束恢复RO；备份整个模型目录及注册清单。更多模型/许可边界读取 `vision-engine`。
-官网各组件的独立Compose必须完整保留，按用户要求将代码默认折叠，栏目标题保留在页面大纲中；
-不能因简化一键入口而删除；恢复时查询Gitee历史，
-保留参数与注释，同时修正固定密码、租户配置和网络边界。群晖等未配置共享资源组的宿主默认
-不启用cgroup_parent。视觉NAS辅助脚本位于官网public/downloads/vision，使用容器内Python，
-无Docker socket、拒绝覆盖既有目录；完整YAML和准备步骤须同时提供，不能只给下载器链接。
-
-## 配置归类
-
-| 配置 | 原则 |
-|---|---|
-| 数据库连接 | 密钥管理/环境注入，不入库明文示例 |
-| Redis/Mongo/对象存储 | 全节点一致、网络可达、租户隔离 |
-| AuthSecret/JWT | 集群一致；变更会影响已有登录态 |
-| ApiBase/FileServer | 与反向代理外部地址一致 |
-| 上传上限 | API、代理、租户配置三层一致 |
-| 日志 spool | 每节点持久卷；Mongo 恢复后幂等重放 |
-| 容器内存 | 多服务共机时给每容器合理 limit |
-
-## Docker/Compose
-
-### 安装器的 API 容器 DNS 验收
-
-MySQL 已还原、临时客户端权限检查通过，但 API 报 `DatabaseHostInvalid` /
-`The host name or IP address is invalid` 时，不能归因为密码错误或重复导库。
-先从实际 API 容器验证解析，临时客户端与 API 的网络命名空间不是同一份证据。
-一键安装及 `--repair-app` 共用实际容器解析门禁；失败才对安装器管理的数据库、
-Redis、MongoDB 按 Docker 实时回读的 `microi` IPv4 写 `extra_hosts` 兜底，
-校验及备份编排后仅重建 API，并回读解析结果，失败恢复原编排。
-外部数据库连接不参与地址固定，不改 Docker daemon、全局 DNS、防火墙或数据卷。
-缺少解析工具不能视为 DNS 故障；缺少共享网络、非法地址、配置并发变化均失败关闭。
-依赖重建导致 IP 变化后需重新运行修复刷新映射；解析通过不代替 HTTP、登录和业务验收。
-
-### 部署与升级检查
-
-恢复库在 API/Worker 启动前必须暂停业务任务与 Quartz 触发器并强回读。MySQL 5.7 的无表 `SELECT` 带 `WHERE` 时显式使用 `FROM DUAL`，兼容 8.0 和空任务表；校验命令非零退出、无标记或仅错误文本包含标记时均停止，区分 SQL 执行失败与状态不一致。中断的新安装先备份编排和数据库，保留原数据目录后恢复，不通过跳过任务暂停门禁续装。
-
-小规格宿主部署翻译与 OCR 时必须实际执行推理并同时检查 SSH/API 响应、线程数和可用内存。LibreTranslate 1.9.6 的容器入口使用 `LT_THREADS` 作为 Gunicorn worker 数，`LT_WORKERS` 不生效；使用 `LT_THREADS=1`、`ARGOS_INTER_THREADS=1`、`ARGOS_INTRA_THREADS=1` 并约束 OMP/OpenBLAS/MKL/NumExpr 原生线程。OCR 同样约束原生数学库线程。容器 Running、模型列表和健康 GET 不能代替首次真实推理验收；这些是附加服务配置，不进入吾码 API 十项启动环境变量。
-
-一键新安装在 Docker 可用后、每个模型启动前检查真实内存：物理低于 7680MiB 或可用低于 2048MiB 时，本次安装固定停用 OCR/LibreTranslate，精确停止已有同名安装容器并将 restart 设为 no，回读必须为 stopped；不删除模型或数据库。唯一活动主租户在核心升级完成后设置 OcrEnabled=0、TranslateProvider=None，保留 URL/Key，写后回读成功才刷新 API。空 Provider 会根据保留 URL 自动回退，不代表禁用。内存充足时模型分别限制 1024/768MiB RAM、1536/1280MiB RAM+Swap、0.75CPU，并保留单线程。小规格新建 MySQL buffer pool 上限 384MiB；无 Swap 时在文件系统、磁盘及备份前提满足后尝试 2GiB Swap，不能覆盖既存文件，也不能将 Swap 计入模型物理内存准入。内存保护已触发时禁止继续做 OCR/翻译真实推理验收；改为验收停止状态、租户开关与核心登录，待资源调整后单独启用和实测。
-
-执行前：
-
-1. 固定目标目录和 compose 文件，解析所有 volume 的绝对宿主路径。
-2. 校验镜像 tag/digest、端口、网络、重启策略、healthcheck 和 secrets。
-3. 备份数据库、对象存储与配置，并验证备份可读。
-4. `docker compose config` 只作静态校验，不代表服务可运行。
-
-发布时一次只替换部分 API 节点；readiness 正常后再替换下一节点。数据库和对象存储
-卷不随应用容器重建删除。Watchtower/自动更新若启用，必须保证 AuthSecret、配置卷和
-健康检查不因容器替换漂移。
-
-离线安装包要包含精确镜像、校验和、compose、配置模板和安装说明；目标机导入后复核
-镜像 digest，不能只看文件解压成功。
-
-## Windows/IIS
-
-至少核对：
-
-- .NET Hosting Bundle 与应用目标框架匹配；
-- Application Pool 使用无托管代码并具备目录权限；
-- API 和 Web 站点绑定、HTTPS、反向代理与 WebSocket 配置；
-- 应用数据、上传、日志和 spool 目录不放临时发布目录；
-- Windows 服务/计划任务不会与 IIS 节点重复执行同一后台任务；
-- MySQL、Redis、MongoDB、MinIO 服务开机启动和恢复策略。
-
-IIS 进程启动不代表 API 可用，仍要检查 readiness 和真实登录路径。
-
-## 本地源码运行
-
-macOS 的一键发布探针通过 `run_with_timeout` 使用 GNU `timeout`、`gtimeout` 或仓库 Node 工具 `Microi.Server/tools/run-with-timeout.mjs`。缺少 GNU 命令不能据此判定 Docker 不健康；超时工具只停止自身创建的探针进程。官网专用选项 6 不发布 DLL/NuGet，后端发布的加密门禁保持有效。
-
-Obfuscar 路径转换只适用于 Git Bash/MSYS/Cygwin。macOS/Linux 的 `/Users`、`/usr` 等绝对路径直接传给工具；Windows 优先 `cygpath`，无该命令时只转换完整盘符根路径。修复后使用隔离副本验证五个 DLL 和指纹，再重新执行一键脚本的 PlatformRelease 与最终加密产物冒烟。
-
-在线 AI MCP 的生产依赖和命令复制为完整、自足的运行快照，生产命令链接解析为真实文件，保留执行权限；损坏、越界及目录循环链接提前拒绝。临时构建目录清理后命令必须仍能运行，旧依赖不得残留；不放宽原制品门禁。
-
-前端构建的 macOS 可用内存按有界 `vm_stat` 的真实页大小计算空闲页加可回收文件页，不叠加匿名非活动、压缩或预读页。解析失败和探针超时回退原生空闲量；Windows/Linux 保持原统计方式。吾码PC默认现代构建保持6144MiB堆，以5632MiB进程树预算加max(1GiB,物理内存3%)准入，32GiB约6.5GiB、64GiB约7.42GiB；97%暂停、95%以内连续五秒恢复。低于8GiB宿主至少保留1.5GiB余量，宿主限堆/自定义堆及未知阶段回退到堆加有界原生开销；串行压缩/legacy仍为1536/2048MiB堆、768MiB原生下限，32GiB启动目标约3.25/3.75GiB。各阶段分别计算，不跳过保护，不结束共享服务。
-
-后端：
-
-- 使用当前仓库规定的 .NET SDK；
-- 公开源码打开 `Microi.Server/Microi.net.sln`，五个闭源库使用同版本 NuGet；创建人完整源码才使用 `Microi.Anderson.sln`。目标 `net10.0` 需要 Visual Studio 2026 18.0 起及与 SDK 功能带匹配的 IDE，不能把 VS 2022 加装 SDK 视为受支持配置。
-- 排查 `NU1105` / `NETSDK1004` 时，分别检查项目文件是否公开交付、是否完整列入方案、是否被卸载以及还原是否成功。CLI 递归 restore 通过不能证明 VS 方案项目图完整；公开闭包回归还必须检查全部传递依赖及 Debug/Release 配置，包含 `ReferenceOutputAssembly=false` 的独立进程夹具。
-- 修复方案后在不含闭源源码的隔离公开候选中还原、构建；可用 `dotnet restore Microi.Server/Microi.net.sln -p:RestoreRecursive=false` 验证方案列出的全部项目均获得还原资产，再执行 `dotnet build Microi.Server/Microi.net.sln -c Debug --no-restore`。该命令行证据不等于真实 Visual Studio 界面验收，不删除引用或关闭功能来掩盖错误。
-- 配置开发专用数据库/Redis/Mongo/对象存储；
-- 先跑定向测试，再按资源允许程度执行更大构建；
-- 不让本地调试连接生产写库。
-
-前端：
-
-- 使用仓库规定的 Node/npm/pnpm 版本；
-- 复用已有 Vite 服务，不重复启动；
-- `src/config.json` 的 `ApiBaseDev` 是默认值；本地 URL 可在 `#` 前用
-  `?OsClient=...&ApiBase=...` 以最高优先级覆盖 ApiBase 与租户；
-- 多组 `ApiBase + OsClient` 并行时按组创建独立浏览器 Profile/进程或 Playwright context，不能在
-  同一同源 context 的多个 Page 中混测；
-- 人工第二组至少使用无痕窗口，但多个 Chrome 无痕窗口可能共享临时会话，不能承担多组强隔离；
-- 从线上页面读取 `window.__MICROI_RUNTIME_ENDPOINT__`；旧版无该对象时按 URL、window 全局、
-  同源状态、域名解析/成功请求逐级确认，禁止猜测；
-- 本地页面成功不替代宿主 Token、OsClient、菜单权限和生产构建验收。
-
-## 最小上线验收
-
-- API liveness 200，readiness 200；依赖降级能在 readiness/日志中体现。
-- Web 首屏、登录、退出、Token 刷新正常。
-- 管理员与普通角色各验证一个菜单和数据权限。
-- FormEngine 新增/编辑/查询，ApiEngine 调用正常。
-- 公有/私有文件各上传、预览/下载一次，Range/HEAD 按需验证。
-- Redis/Mongo/对象存储短暂不可用后可恢复，无永久死锁或静默丢失。
-- 双节点同时触发同一 Job/消息，业务副作用仅一次。
-- 发布中终止一个节点，其余节点继续服务；恢复节点不重复初始化。
-- 回滚步骤和恢复点已实际验证或明确标记未验证。
+# 部署矩阵与验收
+
+## 中文官网路由
+
+| 文档 | 主要用途 |
+|---|---|
+| `microi.doc/docs/doc/getting-started/docker-run.md` | Docker、Compose、离线包、依赖编排 |
+| `microi.doc/docs/doc/getting-started/win-install-microi.md` | Windows/IIS 安装 |
+| `microi.doc/docs/doc/getting-started/local-run.md` | 后端/前端源码运行、测试与构建 |
+| `microi.doc/docs/doc/getting-started/start-use.md` | 部署后创建表、表单、菜单的首条业务链路 |
+
+英文目录由中文生成，不作为本轮人工单独维护源。
+
+## 服务依赖
+
+| 依赖 | 作用 | 生产要求 |
+|---|---|---|
+| API/Worker | 后端、V8、任务与接口 | 至少双节点关键场景验证 |
+| Web/Nginx/IIS | 前端与反向代理 | HTTPS、上传体积、超时、静态缓存 |
+| MySQL/兼容业务库 | 平台与业务数据 | 备份、字符集、连接池、慢查询 |
+| Redis | 会话、缓存、租约、进度 | 持久化/高可用、按租户 Key |
+| MongoDB | 日志等文档数据 | 持久卷、容量与重放验收 |
+| MinIO/HDFS | 上传和应用资源 | 公私桶、持久卷、备份、CORS |
+
+可选依赖如翻译服务、Ollama、Qdrant 只在相应能力启用时部署，不把演示编排无条件
+带入生产。
+
+视觉引擎使用一个独立编排，默认运行 `vision/media` 两个容器；`behavior` 通过同名
+profile 显式选装，默认不下载 Qwen、不启动 Ollama。复用吾码API、Web和数据库。
+服务器准备工具为 `Microi.Server/tools/vision-deployment/deploy.py`，详细操作原位维护在
+`docker-run.html#vision-engine-compose`。CPU/CUDA分别锁定已发布镜像digest；模型下载
+校验大小/SHA，配置私有挂载，手机走平台HTTPS中继。行为模型默认不启用，独立准确率
+验收与基础部署就绪分别记录。Ollama设置 `OLLAMA_NOPRUNE=true`，模型导入期间临时RW，
+结束恢复RO；备份整个模型目录及注册清单。更多模型/许可边界读取 `vision-engine`。
+官网各组件的独立Compose必须完整保留，按用户要求将代码默认折叠，栏目标题保留在页面大纲中；
+不能因简化一键入口而删除；恢复时查询Gitee历史，
+保留参数与注释，同时修正固定密码、租户配置和网络边界。群晖等未配置共享资源组的宿主默认
+不启用cgroup_parent。视觉NAS辅助脚本位于官网public/downloads/vision，使用容器内Python，
+无Docker socket、拒绝覆盖既有目录；完整YAML和准备步骤须同时提供，不能只给下载器链接。
+
+## 配置归类
+
+| 配置 | 原则 |
+|---|---|
+| 数据库连接 | 密钥管理/环境注入，不入库明文示例 |
+| Redis/Mongo/对象存储 | 全节点一致、网络可达、租户隔离 |
+| AuthSecret/JWT | 集群一致；变更会影响已有登录态 |
+| ApiBase/FileServer | 与反向代理外部地址一致 |
+| 上传上限 | API、代理、租户配置三层一致 |
+| 日志 spool | 每节点持久卷；Mongo 恢复后幂等重放 |
+| 容器内存 | 多服务共机时给每容器合理 limit |
+
+## Docker/Compose
+
+### 安装器的 API 容器 DNS 验收
+
+MySQL 已还原、临时客户端权限检查通过，但 API 报 `DatabaseHostInvalid` /
+`The host name or IP address is invalid` 时，不能归因为密码错误或重复导库。
+先从实际 API 容器验证解析，临时客户端与 API 的网络命名空间不是同一份证据。
+一键安装及 `--repair-app` 共用实际容器解析门禁；失败才对安装器管理的数据库、
+Redis、MongoDB 按 Docker 实时回读的 `microi` IPv4 写 `extra_hosts` 兜底，
+校验及备份编排后仅重建 API，并回读解析结果，失败恢复原编排。
+外部数据库连接不参与地址固定，不改 Docker daemon、全局 DNS、防火墙或数据卷。
+缺少解析工具不能视为 DNS 故障；缺少共享网络、非法地址、配置并发变化均失败关闭。
+依赖重建导致 IP 变化后需重新运行修复刷新映射；解析通过不代替 HTTP、登录和业务验收。
+
+### 部署与升级检查
+
+恢复库在 API/Worker 启动前必须暂停业务任务与 Quartz 触发器并强回读。MySQL 5.7 的无表 `SELECT` 带 `WHERE` 时显式使用 `FROM DUAL`，兼容 8.0 和空任务表；校验命令非零退出、无标记或仅错误文本包含标记时均停止，区分 SQL 执行失败与状态不一致。中断的新安装先备份编排和数据库，保留原数据目录后恢复，不通过跳过任务暂停门禁续装。
+
+小规格宿主部署翻译与 OCR 时必须实际执行推理并同时检查 SSH/API 响应、线程数和可用内存。LibreTranslate 1.9.6 的容器入口使用 `LT_THREADS` 作为 Gunicorn worker 数，`LT_WORKERS` 不生效；使用 `LT_THREADS=1`、`ARGOS_INTER_THREADS=1`、`ARGOS_INTRA_THREADS=1` 并约束 OMP/OpenBLAS/MKL/NumExpr 原生线程。OCR 同样约束原生数学库线程。容器 Running、模型列表和健康 GET 不能代替首次真实推理验收；这些是附加服务配置，不进入吾码 API 十项启动环境变量。
+
+一键新装从实际 MemTotal 规划整套预算：宿主预留 max(12.5%, 低于8GiB为1GiB/其余2GiB)，
+其余为受管父池；API/主数据库/Redis/MongoDB/MinIO/Web 与获准模型均有单项内存硬帽并进入同一父池。
+核心各帽之和超过父池时先失败；父池CPU合计为逻辑核95%，RAM+Swap帽等于RAM帽。
+Redis maxmemory至多自身帽一半，Mongo显式WT cache；MySQL pool约自身帽40%，查询预留约25%，
+其余扣固定开销后估计连接容量。外部数据库/MinIO、Panel和其它客户进程必须另计，不得重复预算。
+
+新建managed MySQL的白名单OsClientDbConn按服务端连接数分配客户端池：先预留max(4,ceil(max_connections/5))，
+其余按业务/Quartz两池均分且每池至多100、Min Pool Size=0。主租户相同参数读写共池，
+Quartz默认寿命120秒、ORM300秒会形成独立池；多个节点/独立读库不在单API默认范围内，须重新合计。
+公式不放大server max_connections，不重写external或repair旧客户连接串，也不证明重SQL并发峰值通过。
+
+OCR默认2048MiB、翻译1024MiB，各0.75CPU/单线程；翻译初始化临时容器同样有帽。
+完整核心与已选模型总帽须放得下，物理≥7680MiB且可用≥max(2048MiB,已选模型预算)才启动。
+默认16GiB全同机通常跳过两个模型，不能通过压低热峰所需帽宣称全套正常。
+启动后回读父级、每容器内存与含Swap帽；配置解析通过不代表运行可用。
+
+已有安装先只读审计并退出，不能为了新默认预算自动停模型、重建容器或覆盖客户自定义。
+`bash install-microi.sh --resource-audit`只读名称、Memory/MemorySwap/CgroupParent/OOMKilled，
+不读取Env/秘密；Memory=0或缺父级明确告警。需备份、观察真实峰值并在维护窗口调整旧编排。
+新装容量降级时唯一活动主租户在完整升级完成后设OcrEnabled=0、TranslateProvider=None，保留URL/Key，
+写后回读成功才刷新API。物理不足时不得进行OCR/翻译推理验收；小规格新建MySQL pool仍至多384MiB。
+应急2GiB Swap仅在既有文件、文件系统、磁盘与备份保护条件满足时准备，不计模型准入，也不扩大父池。
+
+
+执行前：
+
+1. 固定目标目录和 compose 文件，解析所有 volume 的绝对宿主路径。
+2. 校验镜像 tag/digest、端口、网络、重启策略、healthcheck 和 secrets。
+3. 备份数据库、对象存储与配置，并验证备份可读。
+4. `docker compose config` 只作静态校验，不代表服务可运行。
+
+发布时一次只替换部分 API 节点；readiness 正常后再替换下一节点。数据库和对象存储
+卷不随应用容器重建删除。Watchtower/自动更新若启用，必须保证 AuthSecret、配置卷和
+健康检查不因容器替换漂移。
+
+离线安装包要包含精确镜像、校验和、compose、配置模板和安装说明；目标机导入后复核
+镜像 digest，不能只看文件解压成功。
+
+## Windows/IIS
+
+至少核对：
+
+- .NET Hosting Bundle 与应用目标框架匹配；
+- Application Pool 使用无托管代码并具备目录权限；
+- API 和 Web 站点绑定、HTTPS、反向代理与 WebSocket 配置；
+- 应用数据、上传、日志和 spool 目录不放临时发布目录；
+- Windows 服务/计划任务不会与 IIS 节点重复执行同一后台任务；
+- MySQL、Redis、MongoDB、MinIO 服务开机启动和恢复策略。
+
+IIS 进程启动不代表 API 可用，仍要检查 readiness 和真实登录路径。
+
+## 本地源码运行
+
+macOS 的一键发布探针通过 `run_with_timeout` 使用 GNU `timeout`、`gtimeout` 或仓库 Node 工具 `Microi.Server/tools/run-with-timeout.mjs`。缺少 GNU 命令不能据此判定 Docker 不健康；超时工具只停止自身创建的探针进程。官网专用选项 6 不发布 DLL/NuGet，后端发布的加密门禁保持有效。
+
+Obfuscar 路径转换只适用于 Git Bash/MSYS/Cygwin。macOS/Linux 的 `/Users`、`/usr` 等绝对路径直接传给工具；Windows 优先 `cygpath`，无该命令时只转换完整盘符根路径。修复后使用隔离副本验证五个 DLL 和指纹，再重新执行一键脚本的 PlatformRelease 与最终加密产物冒烟。
+
+在线 AI MCP 的生产依赖和命令复制为完整、自足的运行快照，生产命令链接解析为真实文件，保留执行权限；损坏、越界及目录循环链接提前拒绝。临时构建目录清理后命令必须仍能运行，旧依赖不得残留；不放宽原制品门禁。
+
+前端构建的 macOS 可用内存按有界 `vm_stat` 的真实页大小计算空闲页加可回收文件页，不叠加匿名非活动、压缩或预读页。解析失败和探针超时回退原生空闲量；Windows/Linux 保持原统计方式。吾码PC默认现代构建保持6144MiB堆，以5632MiB进程树预算加max(1GiB,物理内存3%)准入，32GiB约6.5GiB、64GiB约7.42GiB；97%暂停、95%以内连续五秒恢复。低于8GiB宿主至少保留1.5GiB余量，宿主限堆/自定义堆及未知阶段回退到堆加有界原生开销；串行压缩/legacy仍为1536/2048MiB堆、768MiB原生下限，32GiB启动目标约3.25/3.75GiB。各阶段分别计算，不跳过保护，不结束共享服务。
+
+后端：
+
+- 使用当前仓库规定的 .NET SDK；
+- 公开源码打开 `Microi.Server/Microi.net.sln`，五个闭源库使用同版本 NuGet；创建人完整源码才使用 `Microi.Anderson.sln`。目标 `net10.0` 需要 Visual Studio 2026 18.0 起及与 SDK 功能带匹配的 IDE，不能把 VS 2022 加装 SDK 视为受支持配置。
+- 排查 `NU1105` / `NETSDK1004` 时，分别检查项目文件是否公开交付、是否完整列入方案、是否被卸载以及还原是否成功。CLI 递归 restore 通过不能证明 VS 方案项目图完整；公开闭包回归还必须检查全部传递依赖及 Debug/Release 配置，包含 `ReferenceOutputAssembly=false` 的独立进程夹具。
+- 修复方案后在不含闭源源码的隔离公开候选中还原、构建；可用 `dotnet restore Microi.Server/Microi.net.sln -p:RestoreRecursive=false` 验证方案列出的全部项目均获得还原资产，再执行 `dotnet build Microi.Server/Microi.net.sln -c Debug --no-restore`。该命令行证据不等于真实 Visual Studio 界面验收，不删除引用或关闭功能来掩盖错误。
+- 配置开发专用数据库/Redis/Mongo/对象存储；
+- 先跑定向测试，再按资源允许程度执行更大构建；
+- 不让本地调试连接生产写库。
+
+前端：
+
+- 使用仓库规定的 Node/npm/pnpm 版本；
+- 复用已有 Vite 服务，不重复启动；
+- `src/config.json` 的 `ApiBaseDev` 是默认值；本地 URL 可在 `#` 前用
+  `?OsClient=...&ApiBase=...` 以最高优先级覆盖 ApiBase 与租户；
+- 多组 `ApiBase + OsClient` 并行时按组创建独立浏览器 Profile/进程或 Playwright context，不能在
+  同一同源 context 的多个 Page 中混测；
+- 人工第二组至少使用无痕窗口，但多个 Chrome 无痕窗口可能共享临时会话，不能承担多组强隔离；
+- 从线上页面读取 `window.__MICROI_RUNTIME_ENDPOINT__`；旧版无该对象时按 URL、window 全局、
+  同源状态、域名解析/成功请求逐级确认，禁止猜测；
+- 本地页面成功不替代宿主 Token、OsClient、菜单权限和生产构建验收。
+
+## 最小上线验收
+
+- API liveness 200，readiness 200；依赖降级能在 readiness/日志中体现。
+- Web 首屏、登录、退出、Token 刷新正常。
+- 管理员与普通角色各验证一个菜单和数据权限。
+- FormEngine 新增/编辑/查询，ApiEngine 调用正常。
+- 公有/私有文件各上传、预览/下载一次，Range/HEAD 按需验证。
+- Redis/Mongo/对象存储短暂不可用后可恢复，无永久死锁或静默丢失。
+- 双节点同时触发同一 Job/消息，业务副作用仅一次。
+- 发布中终止一个节点，其余节点继续服务；恢复节点不重复初始化。
+- 回滚步骤和恢复点已实际验证或明确标记未验证。

package/skills/microi-deployment/references/offline-installer.md

@@ -1,64 +1,66 @@
-# 完全断网的一键安装
-
-## 入口与范围
-
-平台安装器源码位于 `数据库、案例、文档、资料/`：
-
-- `microi-offline-prepare.sh` 调用 `offline/prepare.py`，在联网机器用 Python 3.11+
-  标准库制作 Linux x86_64 核心 ZIP，不要求制包机安装 Docker。
-- `install-microi-offline.sh` 验证清单、准备 Docker、导入并核对镜像，再执行同包的
-  `install-microi.sh`；禁止再维护一份独立、落后于在线安装器的业务编排。
-- ZIP 带 shell 自解压前导、静态 BusyBox 和独立 musl 工具运行时；root 使用
-  `sha256sum -c microi-offline-linux-x86_64.zip.sha256 && sh microi-offline-linux-x86_64.zip`。
-  目标机无需预装 Docker、Compose、unzip、Python、curl 或 OpenSSL。
-
-Linux 内核、systemd、cgroup 控制器、CPU 指令与必要内核模块不是用户态包可以补齐的
-依赖。当前核心包要求 x86_64、内核 4.18+、systemd 与 CPU AVX；CentOS 7 旧内核应
-早期拒绝，不能沿用在线脚本的发行版清单冒充所有版本通过。发行时记录实际 Ubuntu、
-CentOS 等版本的断网安装结果；WSL/chroot 工具验证不等于完整服务器验收。
-
-核心镜像从冻结的在线脚本提取：MySQL 5.7、Redis、MongoDB、MinIO、MinIO mc、
-MySQL 管理客户端、API/Web、Microi.Panel。在线脚本已停用的向量组件不恢复默认安装；
-OCR 和翻译的模型必须另行离线交付并实测后才能启用，不能在断网环境启动下载任务。
-
-## 制品与宿主边界
-
-1. 制包前盘点输出盘与 Docker VHD 所在宿主盘。Registry 清单、压缩层 digest 与解压后
-   diff_id 逐个核对，导出到指定输出目录，不向容量不足的本机 Docker 拉取。
-2. 固定脚本输入快照和镜像 config/digest；续做复用同一快照。明确采用新输入时使用
-   `--refresh-inputs`，随后重新制作候选并验收，不能混搭并发发布中的面板版本。
-3. ZIP64 支持由包内 Python 处理，路径、普通文件类型、去重清单、大小和 SHA-256 全部
-   校验后才部署。工具运行时在 `/opt/microi-offline/runtime` 独立安装，不替换系统 libc
-   或 Python；对应服务运行期间该目录是长期依赖，不能作为临时目录删除。
-4. Docker classic store 的 `.Id` 是 config ID；Docker 29 containerd store 可能返回
-   manifest digest。只接受清单中的这两种身份；legacy archive 导入产生新 manifest 时，
-   用 `docker image save` 流式回读原 config 字节 SHA-256、架构和实际 RootFS diff_ids。
-   不能只按 tag、架构或 Running 状态认定镜像相同。
-5. 已有 Docker 只复用，不覆盖 daemon、数据或启动失败的服务；缺少 Compose 且目标
-   插件路径不存在时可安装包内插件。离线 Compose 持久使用 `pull_policy: never`，
-   安装入口同时禁止联网 pull/build、包管理器和外网 curl。镜像缺失或身份冲突失败关闭。
-6. 新装入口发现已有吾码编排、面板或 Ops 即停止，保留数据。宿主锁防并发；工具运行时
-   使用临时目录解压、成功后原子替换。成功/失败和可捕获信号均清理自有临时目录，
-   硬中断残留须先按 PID/归属核验，不能删除活动任务锁或用户原 ZIP。
-
-## 验收与公开下载
-
-- 真实断网 VM 使用独占虚拟交换机、没有默认网关，记录内核/系统、预装工具与空 Docker
-  状态。使用实际 ZIP 自解压并完成数据库导入、核心升级与 readiness、Web 登录和
-  MinIO 公私桶操作、面板 HTTPS 健康；重启后复核持久化及服务自动启动。
-- 离线入口 umask 077 下，MySQL 无秘密配置必须显式 0644，避免容器忽略大小写设置。
-  面板登记继承本次 API/Web 仓库，宿主监测只读暴露 `/home`；运行目录由 systemd
-  以 0700 创建并保留 inode，防止 Docker 重启时先创建 0755 导致严格校验失败。
-- MySQL 使用 `--protocol=TCP --host=127.0.0.1` 执行就绪查询和后续 SQL，拒绝镜像
-  初始化期间尚未开放 TCP 的临时 socket；不要用固定延时接受随机成功。
-  CentOS sudo secure_path 缺少 /usr/local/bin 时由离线入口补齐，校验文本使用 LF。
-- 单元回归覆盖损坏/缺失/越界归档、工具引导、镜像两种 ID 与重打包验证；保留既有端口、
-  十项 API 配置白名单与先装面板保护的回归。测试自有 VM、目录、进程和临时产物须收尾。
-- 官方 ZIP 通过已核验的 iTdos MCP v3 原始字节流上传，源码仓只存代码、下载 URL、大小、
-  SHA-256 与验收回执。不得把 ZIP、镜像层、截图或测试 VHD 提交 Git。
-- 当前 NAS 历史安装包原生协议上限是 2 GiB，先从 Capabilities 实测；小于上限的公开
-  ZIP 可用 `PinHistoricalAsset` 精确选择已完成 V3 版本，等待原生复制和匿名校验 Ready。
-  禁止直写 Ready、伪造下载流量、泄露 MinIO 密钥或绕过当前源/版本绑定。
-- 官网下载使用受管 `mci-file-resource-archive-download` 的精确 SourceTenant/AppKey/
-  VersionId/AssetPath 入口，NAS 未就绪或健康失败时回到同版本 CDN。分别验证上传、
-  NAS 原始字节/Range/MIME、入口选址与回退；不要用桶 Probe 或云上传成功替代复制验收。
+# 完全断网的一键安装
+
+## 入口与范围
+
+平台安装器源码位于 `数据库、案例、文档、资料/`：
+
+- `microi-offline-prepare.sh` 调用 `offline/prepare.py`，在联网机器用 Python 3.11+
+  标准库制作 Linux x86_64 核心 ZIP，不要求制包机安装 Docker。
+- `install-microi-offline.sh` 验证清单、准备 Docker、导入并核对镜像，再执行同包的
+  `install-microi.sh`；禁止再维护一份独立、落后于在线安装器的业务编排。
+- ZIP 带 shell 自解压前导、静态 BusyBox 和独立 musl 工具运行时；root 使用
+  `sha256sum -c microi-offline-linux-x86_64.zip.sha256 && sh microi-offline-linux-x86_64.zip`。
+  目标机无需预装 Docker、Compose、unzip、Python、curl 或 OpenSSL。
+
+Linux 内核、systemd、cgroup 控制器、CPU 指令与必要内核模块不是用户态包可以补齐的
+依赖。当前核心包要求 x86_64、内核 4.18+、systemd 与 CPU AVX；CentOS 7 旧内核应
+早期拒绝，不能沿用在线脚本的发行版清单冒充所有版本通过。发行时记录实际 Ubuntu、
+CentOS 等版本的断网安装结果；WSL/chroot 工具验证不等于完整服务器验收。
+
+核心镜像从冻结的在线脚本提取：MySQL 5.7、Redis、MongoDB、MinIO、MinIO mc、
+MySQL 管理客户端、API/Web、Microi.Panel。在线脚本已停用的向量组件不恢复默认安装；
+OCR 和翻译的模型必须另行离线交付并实测后才能启用，不能在断网环境启动下载任务。
+
+核心ZIP继续复用同包在线安装器的完整资源预算：宿主余量、所有核心单项硬帽、MySQL/Redis/Mongo内部缓存与父池总帽一致，不维护离线特例。重新制包后才包含修复；修改源码不能证明既有下载ZIP已更新。旧安装只读审计并退出，保留客户限额和数据。
+
+## 制品与宿主边界
+
+1. 制包前盘点输出盘与 Docker VHD 所在宿主盘。Registry 清单、压缩层 digest 与解压后
+   diff_id 逐个核对，导出到指定输出目录，不向容量不足的本机 Docker 拉取。
+2. 固定脚本输入快照和镜像 config/digest；续做复用同一快照。明确采用新输入时使用
+   `--refresh-inputs`，随后重新制作候选并验收，不能混搭并发发布中的面板版本。
+3. ZIP64 支持由包内 Python 处理，路径、普通文件类型、去重清单、大小和 SHA-256 全部
+   校验后才部署。工具运行时在 `/opt/microi-offline/runtime` 独立安装，不替换系统 libc
+   或 Python；对应服务运行期间该目录是长期依赖，不能作为临时目录删除。
+4. Docker classic store 的 `.Id` 是 config ID；Docker 29 containerd store 可能返回
+   manifest digest。只接受清单中的这两种身份；legacy archive 导入产生新 manifest 时，
+   用 `docker image save` 流式回读原 config 字节 SHA-256、架构和实际 RootFS diff_ids。
+   不能只按 tag、架构或 Running 状态认定镜像相同。
+5. 已有 Docker 只复用，不覆盖 daemon、数据或启动失败的服务；缺少 Compose 且目标
+   插件路径不存在时可安装包内插件。离线 Compose 持久使用 `pull_policy: never`，
+   安装入口同时禁止联网 pull/build、包管理器和外网 curl。镜像缺失或身份冲突失败关闭。
+6. 新装入口发现已有吾码编排、面板或 Ops 即停止，保留数据。宿主锁防并发；工具运行时
+   使用临时目录解压、成功后原子替换。成功/失败和可捕获信号均清理自有临时目录，
+   硬中断残留须先按 PID/归属核验，不能删除活动任务锁或用户原 ZIP。
+
+## 验收与公开下载
+
+- 真实断网 VM 使用独占虚拟交换机、没有默认网关，记录内核/系统、预装工具与空 Docker
+  状态。使用实际 ZIP 自解压并完成数据库导入、核心升级与 readiness、Web 登录和
+  MinIO 公私桶操作、面板 HTTPS 健康；重启后复核持久化及服务自动启动。
+- 离线入口 umask 077 下，MySQL 无秘密配置必须显式 0644，避免容器忽略大小写设置。
+  面板登记继承本次 API/Web 仓库，宿主监测只读暴露 `/home`；运行目录由 systemd
+  以 0700 创建并保留 inode，防止 Docker 重启时先创建 0755 导致严格校验失败。
+- MySQL 使用 `--protocol=TCP --host=127.0.0.1` 执行就绪查询和后续 SQL，拒绝镜像
+  初始化期间尚未开放 TCP 的临时 socket；不要用固定延时接受随机成功。
+  CentOS sudo secure_path 缺少 /usr/local/bin 时由离线入口补齐，校验文本使用 LF。
+- 单元回归覆盖损坏/缺失/越界归档、工具引导、镜像两种 ID 与重打包验证；保留既有端口、
+  十项 API 配置白名单与先装面板保护的回归。测试自有 VM、目录、进程和临时产物须收尾。
+- 官方 ZIP 通过已核验的 iTdos MCP v3 原始字节流上传，源码仓只存代码、下载 URL、大小、
+  SHA-256 与验收回执。不得把 ZIP、镜像层、截图或测试 VHD 提交 Git。
+- 当前 NAS 历史安装包原生协议上限是 2 GiB，先从 Capabilities 实测；小于上限的公开
+  ZIP 可用 `PinHistoricalAsset` 精确选择已完成 V3 版本，等待原生复制和匿名校验 Ready。
+  禁止直写 Ready、伪造下载流量、泄露 MinIO 密钥或绕过当前源/版本绑定。
+- 官网下载使用受管 `mci-file-resource-archive-download` 的精确 SourceTenant/AppKey/
+  VersionId/AssetPath 入口，NAS 未就绪或健康失败时回到同版本 CDN。分别验证上传、
+  NAS 原始字节/Range/MIME、入口选址与回退；不要用桶 Probe 或云上传成功替代复制验收。

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

@@ -87,7 +87,7 @@ V8 函数”或新增、调整官方中文文档时，使用本 Skill。
 - 客户姓名、租户标识、部署地址、联系信息和业务秘密不进入公开明细；遮挡名称中一个字或发布逐行哈希不等于匿名化。优先使用聚合数据，具名案例和新增截图先确认公开权限并脱敏。
 - 功能、规模和性能分别给出来源、统计日期、目标版本及复核方法；来源未提供的内容写明未核验，不把构建时间当作事实核实时间。没有原始数据时不补造改善比例或认证。
 - 服务地区与联系人采用已确认事实，SSR 正文与结构化数据共用事实源；地区覆盖不自动代表分公司、驻点、认证或统一服务时限。
-- 公开指标工具及方法位于源码工作区 `microi.benchmarks/`（工作区提供时）；缺少工具不绕过 MCP 权限或读取整表秘密。公开仓、官网、搜索收录和第三方评价分别验收，不能以本站 HTTP 成功或 AI 索引存在声称排名提升。
+- 公开指标工具及方法位于源码工作区 `microi.doc/scripts/benchmarks/`（工作区提供时）；缺少工具不绕过 MCP 权限或读取整表秘密。公开仓、官网、搜索收录和第三方评价分别验收，不能以本站 HTTP 成功或 AI 索引存在声称排名提升。
 - 机器可读正文从实际构建的公开 SSR 正文生成，排除全站导航、脚本、注释和交互私有数据；与 HTML 使用同一内容源，不另写迎合模型的事实。逐页索引保留规范页面地址、纯文本地址、语言、正文大小和 SHA-256；只有真实来源可支持时才记录修订日期，未知时省略，不以构建日期冒充内容更新。
 - 官网以 HTML 为规范收录页面，纯文本是便于抓取和核对的替代格式；`llms.txt`、HTML 替代链接与正文清单互相一致。发布前验证所有正文入口可生成、内部链接可解析、表格与代码含义保留，并检查账户页、撤回页和非公开内容不进入正文清单。生成完成不能证明搜索引擎已收录或模型已经使用。
 

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

@@ -25,6 +25,9 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `edition-comparison.md` | microi-system-delivery | 信息型页面；版本授权、续费边界和选型建议 |
 | `index.md` | microi-system-delivery | 产品能力总览和知识路由 |
 | `more/copy-module.md` | module-engine, app-store | 模块复制、迁移和依赖 |
+| `more/password-policy.md` | v8-security, microi-system-delivery | 密码强度、首次登录强制改密、旧账号兼容、活动会话与原子提交回执 |
+| `system-engine/left-tree-descendants.md` | microi-left-right-layout, module-engine | 上级树节点按授权后代范围加载、标量/JSON组织关系与跨租户应用升级 |
+| `system-engine/mci-button-states.md` | microi-ui, ui-design | 按钮文案/图标布局、加载/禁用/聚焦状态、主题对比度及可访问名称 |
 | `more/db-dictionary.md` | microi-db-schema | 核心表和字段归属 |
 | `more/dos-orm.md` | dos-orm, v8-sql-query | ORM 查询、参数和事务 |
 | `more/dos-result.md` | v8-utilities, v8-crud-api | DosResult/DosResultList 返回协议 |
@@ -34,8 +37,10 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `more/office.md` | v8-export-import, microi-microservice | Office 导入导出与在线编辑集成 |
 | `more/security.md` | v8-security, v8-sql-query | 平台安全和兼容基线、业务接口禁止客户端 SQL 与受权控制面边界 |
 | `more/sso.md` | microi-sso, v8-security, app-store | 双向 OIDC/SAML2/CAS、账号映射、协议端点、安全基线、商城发布与验收 |
-| `more/sys-config.md` | v8-utilities, microi-deployment, microi-client-frontend, ui-design | 系统/租户配置、独立玻璃材质与降级、登录前外观缓存与壁纸、个人覆盖、全框架密度、框架显隐和敏感边界 |
+| `more/sys-config.md` | v8-utilities, microi-deployment, microi-client-frontend, ui-design, v8-security, v8-api-config, dos-orm, microi-frontend-sdk | 系统/租户配置、外观、密度与框架显隐；9.0.2支付原始协议、元数据MCP/秘密分离、固定StopHttp业务适配、永久幂等和独立验收 |
 | `system-engine/ai-engine.md` | ai-engine, v8-http-integration, microi-ai-application | 模型代理、License、V8.AI、MCP 对话、跨端调用和安全 |
+| `system-engine/ai-cpu-timeline.md` | ai-engine, v8-file-upload, job-engine, v8-security | 本人私有素材探针、原生CPU有声剪辑、受保护上传音频检查收据、独立队列与分层验收 |
+| `system-engine/ai-local-speech-s2v.md` | ai-engine, job-engine, v8-security | 本地预置音色配音、声音驱动视频、共享GPU准入、本人强引用、口型与真实媒体验收边界 |
 | `system-engine/ai-cad.md` | ai-engine, v8-api-config, microi-ai-application, app-store | 吾码接口引擎到 SolidWorks 桌面插件的参数计划、模型回读、BOM 与图纸交付边界 |
 | `system-engine/digital-human-live.md` | ai-engine, microi-microservice, app-store, playwright-e2e | 自建数字人直播、本机推理、话术知识、OBS 接入、4K 功能截图与实测边界 |
 | `system-engine/ai-employee-center.md` | ai-engine, job-engine, v8-security, microi-microservice | AI 员工职责、任务依赖、草稿验收、执行租约和 OpenClaw 节点 |
@@ -44,6 +49,7 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/ai-platform-governance.md` | ai-platform-governance, app-store, business-blueprint, page-engine | 门户、身份、配置、发布、服务韧性、Trace/日志、资产协作与可恢复导入 |
 | `system-engine/ai-workflow-suite.md` | business-blueprint, v8-workflow, microi-system-delivery | AI 工作流、蓝图、状态机、自动化流和流程挖掘 |
 | `system-engine/system-observability.md` | system-observability, performance-testing, v8-debugging, microi-microservice | 系统日志、Trace、热点接口、资源监控、网络流量归因、安全治理、AI/MCP 与商城交付 |
+| `system-engine/framework-status-widgets.md` | system-observability, microi-client-frontend, v8-api-config, microi-deployment, app-store | 顶部与侧栏状态、WS定时快照、宿主/容器来源、可信provider、布局CAS和默认升级保全 |
 | `system-engine/app-store.md` | app-store | 应用包、安装、升级和回滚；当前公开 API 固定入口、精确历史 CDN 预览与内部发布字段边界 |
 | `system-engine/databases.md` | dos-orm, v8-sql-query, microi-deployment | 扩展数据库与迁移 |
 | `system-engine/datasource-engine.md` | datasource-engine | 数据源定义、执行和供数 |
@@ -69,16 +75,16 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/vision-engine.md` | vision-engine, ai-engine, microi-microservice, app-store, v8-security | ONNX 视觉特征、样本匹配、视频脸框与有界跟随、授权图库与私有示例、异步候选复核、微服务与商城交付 |
 | `system-engine/translate-engine.md` | translate-engine | 多语言与翻译供应商 |
 | `system-engine/unity-integration.md` | unity-integration, v8-api-config, microi-client-frontend | Unity UPM、WebGL/Windows、多人租约、公屏、DiyToken 与 V8 通讯边界 |
-| `system-engine/visualization-engine.md` | page-engine, microi-ui, microi-microservice | 3D、LIS 型材库、CAD、goView 与数据大屏能力边界及微服务交付 |
+| `system-engine/visualization-engine.md` | page-engine, microi-ui, microi-microservice | 3D、LIS 型材库、CAD、goView 与数据大屏能力边界；空间合批、透明/AO、完整手势、安全镜头、纯读取诊断和同DPR连续交互验收；世界坐标玻璃牌、实际相机裁剪与异步场景原子提交；真实ModelKey实例与CAD细部绑定、静态AO的T·R·S/独立UV1/非色彩/合批核验、限定族有界并集与来源保全；明确暂停的完整AO结果复用与真实输入/资源失效验证 |
 | `system-engine/wf-engine.md` | v8-workflow | 工作流设计和事件 |
 | `v8-engine/ai-apiengine.md` | ai-engine, v8-api-config, microi-system-delivery | AI 编程与短提示词；完整开发默认清单覆盖原推荐提示词 1–8 |
 | `v8-engine/api-engine.md` | v8-api-config, v8-utilities | 接口上下文、配置、分布式锁续租和调用 |
 | `v8-engine/apiengine-index.md` | v8-crud-api, v8-api-config, v8-sql-query | 接口引擎实战、参数白名单与禁止客户端 SQL 的生成规范 |
 | `v8-engine/form-engine.md` | v8-crud-api, v8-formengine-http, module-engine, microi-form-engine | FormEngine API、HTTP、原生查询身份/统计范围与按表主库策略 |
-| `v8-engine/mcp-server.md` | microi-system-delivery, microi-codex-installer, v8-security | MCP 工具、确认、审计、文件、日志、备份与访问密钥 |
-| `v8-engine/microi-agent.md` | microi-codex, microi-codex-installer | Microi Agent 桌面安装、连接诊断与更新 |
+| `v8-engine/mcp-server.md` | microi-system-delivery, microi-codex-installer, v8-security | MCP 工具、当前对话官方 CLI 通道、确认、审计、文件、日志、备份与访问密钥 |
+| `v8-engine/microi-agent.md` | microi-codex, microi-codex-installer | Microi Agent 桌面安装、宿主工具发现、官方 CLI MCP 调用、连接诊断与更新 |
 | `v8-engine/v8-client.md` | v8-utilities, v8-frontend-events, v8-table-event, v8-http-integration, v8-security, ai-engine, print-engine, uniapp-mall-assets | 全部前端 V8、日志/评论/版本四阶段事件及真实写入回执、平台 AI、强身份验证、扫码与文件边界 |
-| `v8-engine/v8-server.md` | v8-utilities, v8-table-event, v8-api-config, v8-http-integration, v8-security, ai-engine, v8-sql-query | 全部后端 V8、活动事件同父事务/空配置兼容、强身份票据、平台 AI、专项路由及可信服务端 SQL/绑定值边界 |
+| `v8-engine/v8-server.md` | v8-utilities, v8-table-event, v8-api-config, v8-http-integration, v8-security, ai-engine, v8-sql-query | 全部后端 V8、活动事件同父事务/空配置兼容、强身份票据、平台 AI、影视可信JSON/Stream/模型与管理员文件镜像、永久回执及0–100MiB私有流边界、专项路由及可信服务端 SQL/绑定值边界 |
 | `v8-engine/vs-code-plugin.md` | v8-explorer-tree, microi-client-frontend, workspace-conventions | VS Code 插件、Microi CLI、AI/MCP 初始化、类型、资源树和共享工作区 |
 | `v8-engine/where.md` | v8-crud-api, v8-sql-query | 参数化 `_Where` 条件 |
 

package/skills/microi-form-engine/references/form-generation-quality.md

@@ -5,6 +5,18 @@
 
 ## 每张表的字段契约
 
+### 字段名称与真实目标库
+
+新增物理字段使用 ASCII 标识符 `[A-Za-z_][A-Za-z0-9_]*`，绝对不得超过 64 个字符。
+从后端 9.0.3 起，只有通过正式数据库解析器确认、且目标配置原始 `DbType` 为
+`mysql/mysql5.7/mysql8` 的新增字段允许 31–64 字符；其它 provider（包含 OceanBase
+兼容协议）保持 30 字符限制，未知配置仍拒绝。绑定了 `diy_table.DataBaseId` 时必须以
+该外接库为准，不能从主库是 MySQL 推断外接库也支持长字段名。
+
+MCP 对超过 64 字符报错，对 31–64 字符告警；规划和 dryRun 不连接目标库执行 DDL，
+不能把零 errors 当作已可落地。先核对实际后端版本与真实目标库，再用正式新增字段接口，
+写后独立回读元数据及物理列。现有字段不因本规则自动更名，不改元数据列容量、默认值或权限。
+
 建模前为适用字段记录：名称与物理类型、控件、Config、数据源、显示键、保存键、
 关联来源及回填目标、清空行为、默认值、精度/单位、权限和验收动作。
 先回读当前表全部字段和来源表字段；已有负责人、联系方式、组织等列时，主动检查它们

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

@@ -153,9 +153,11 @@ SDK 的 `buildHeaders` 必须集中处理所有请求头，不能让页面、业
 当上传突然报 `移动端文件上传路径不合法！` 时，先检查实际 multipart 表单字段和请求头。在 Microi 移动端/会员 Token 流程中，后端会在 HDFS 上传前校验 `Path`；错误的 `Content-Type` 会导致后端读不到表单字段，并表现为路径错误。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=microi-frontend-sdk-005 sha256=1a9d0a33adbff849decf01d114e72cad96f80a6122f0b281cecf9092bbcd0c42 -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-005 sha256=c1d756f5276ce9089c5ea42939e2d05cf2a06c695785fcdcb8eb9338c4b68ce0 -->
 ## 项目封装规则
 
+支付专用HTTPS协议由项目请求模块薄封装，复用同一SDK的当前Token、唯一osclient头与续签规则，不改走通用ApiEngine/普通FormEngine传秘密。客户端只传稳定业务Id/RequestId，金额与积分由服务器冻结；未知结果查询原单，支付跳转/二维码扫描不代表入账。隐藏或会话变化取消轮询并丢弃迟到结果，二维码本地生成，不把URI交给外部服务。
+
 面向业务页面的函数名要保持稳定。如果已有项目导出 `callEngine`、`formEngineGet`、`getImageUrl`、`parseImages` 或 `uploadFile`，保留这些导出，内部委托给 `V8`。这样既能统一 SDK，又能避免大面积改页面。
 
 正确写法：
@@ -204,3 +206,12 @@ uni.request({ url: apiBase + '/apiengine/' + key, header: { Token: token } });
 
 
 - HTML 媒体只在拥有的 PageEngine/RichText 容器内、插入 DOM 前用惰性 template 投影，复用 resolver 和 sanitizer，私有/签名及 srcset/CSS/脚本不改。hydration 用编辑器原生 disable 锁并禁用源码/附件入口，旧响应不得回填或释放新锁；源码 Edit→等待 View→Edit 同步取消旧轮。保存 canonicalize 回原 URL，错误只在当前容器最多一次回退，真实浏览器首请求与编辑保存另验。
+
+
+## 冷启动核验、跨标签撤销与身份代次
+
+- 发现SDK缓存Token只表示有待核验凭据，不表示已登录。冷启动、刷新和端点切换后保持明确的checking/正在核验状态，直到当前apiBase/osClient上的权威本人接口确认当前有效账号；不能先显示缓存账号、积分或无限权益再回退。本人核验失败若是网络/服务错误，应显示可重试错误，不能假装匿名或把业务Bootstrap成功当本人认证。
+- 每次退出、换号、租户/API切换以及接收其它标签页撤销信号都推进身份代次，立即清除当前界面的旧用户、余额/配额、菜单和私有业务投影。异步本人/积分/任务响应必须同时匹配发起时的端点代次、会话代次和本人UserId；旧账号的迟到成功/失效响应既不能复活旧会话，也不能清掉新账号。
+- 复用既有SDK的Token维护和单实例机制。Web在同源storage/BroadcastChannel等受控会话通知后重新读取SDK当前凭据并核验，不另造JWT或平行密码体系；通知仅表达变化，不能把客户端广播当服务端授权，不向业务日志、URL或自定义广播输出Token原文。页面销毁清理监听/订阅。
+- 续签与换号必须区分：只有原会话仍有效且requestToken/身份代次匹配时才能接力新Token；外部标签已退出或换成另一账号时丢弃旧请求续签结果。关闭标签、恢复前台和网络重连都要复查真实当前会话。
+- 验收包括：缓存Token冷启动与刷新全过程checking；A标签退出使B标签清除旧身份；A账号请求未返回时切B账号；旧本人/积分响应晚到；合法同账号续签保持登录；错误端点/网络故障独立反馈。单元测试与真实双标签/手机浏览器证据分别登记，不能把本地缓存或HTTP200当完整验收。