@microi.net/cli 4.6.2 → 4.6.7

package/dist/microi.skills/app-store/SKILL.md

@@ -1,105 +1,140 @@
----
-name: app-store
-description: Microi 应用商城开发、打包、安装和升级规范。用于官方/社区应用、Manifest、源码与构建产物、依赖、后台安装任务、租户隔离、增量升级、回滚和验收。
----
-
-# Microi 应用商城
-
-## 核心原则
-
-应用包是可审计、可重复安装、可增量升级的交付单元。运行类型使用 `ApplicationType`：普通平台包的新建默认值是 `Regular`，既有商城平台应用/通知仍使用 `Platform`，另外还有 `MicroService`、`UniApp`、`Web`；读取端必须兼容 `Regular/Platform`，不能在迁移完成前强制改单值。官方/社区来源使用 `PublisherType`。
-
-`AppType` 是历史复用字段：旧包/接口曾把它用于官方/社区来源，也曾把它作为运行类型回退。新代码不能把 `AppType` 当事实源；只在读取旧数据时回退，写入新数据使用 `ApplicationType + PublisherType`。
-
-客户已有的全局 V8、表单配置、菜单、字段和自定义代码必须保留。升级采用存在性检查、差异合并和包隔离，禁止整表覆盖或把发布方租户数据原样复制到目标租户。
-
-## 包内容
-
-- Manifest：应用 Key、版本、兼容平台版本、依赖和资源清单。
-- 数据模型：表、字段、菜单、角色权限、接口引擎、事件、数据源、页面、打印、工作流、任务。
-- 源码与构建：私有源码包与可部署构建包分离，记录 SHA-256。
-- 安装/升级脚本：幂等、可恢复、可回读；不包含租户密钥、Token、连接串或 License keys。
-- 迁移采用“先扩展、后迁移、再收缩”，支持新旧节点短暂并存。
-
-## 安装流程
-
-1. 校验签名/哈希、包版本、平台兼容性、依赖和磁盘/配额。
-2. 创建全局唯一 `InstallationId` 和稳定幂等键。
-3. 使用后台任务执行，阶段性持久化进度与 checkpoint。
-4. 按 Manifest 差异创建缺失资源；已有资源只更新包拥有且允许升级的属性。
-5. 写入成功后刷新共享缓存版本。
-6. 回读表、字段、引擎、菜单、权限、页面等关键资源。
-7. 做 HTTP、UI 和权限冒烟；成功后标记安装版本。
-
-安装中断后从 checkpoint 幂等恢复；不能依赖当前 API 节点内存。
-
-## 权限与租户
-
-- 商城定义、安装、升级、卸载和应用源码只允许 `Level >= 9999`。
-- 所有资源按目标 `OsClient` 写入；包内不能携带源租户 `OsClient`、数据库、Redis、对象存储、MQ/MQTT、AI 或第三方密钥。
-- 按钮调用后台安装接口时，前端只传应用/版本/安装 Id；目标租户和管理员身份由 Token 确定。
-- 卸载是破坏性操作，必须明确列出将删除/保留的资源、二次确认并优先软删除/归档业务数据。
-
-## MCP 工作流
-
-1. 安装/更新现成商城应用时，先调用 `microi_install_store_application` / `microi_update_store_application` 且不传 `confirmExecution`，核对目标租户、商城源、StoreId 和幂等请求 Id 的预检结果。
-2. 用户明确确认后，把 `confirmExecution` 精确设为 `StoreId`，提交真实持久化后台任务；只传 StoreId、版本和商城源定位信息，不通过 MCP/HTTP 传完整 `AppPakcet`。
-3. 自建应用或低代码系统先用 `microi_list_applications` / `microi_get_application_context` 盘点源码，再用 `microi_get_manifest_schema`、`microi_plan_system` 与 `microi_generate_system(dryRun:true)` 干跑。
-4. 安装任务必须回读至 `Succeeded`，再执行 `microi_validate_system`、远端资源回读和真实 UI 验收；仅返回 TaskId 不代表安装成功。
-
-已有 MicroService 优先新增页面/路由；没有时才创建、同步源码、发布构建。复杂安装交互使用 `V8.OpenAppDialog`，后台任务上报进度。
-
-## VS Code 本地应用与发布边界
-
-- `AI应用` 本地树按每个一级目录的 `.microi-micro-app.json` 发现项目；只要 `osClient/apiBaseUrl` 与当前连接一致，就必须显示 `Web / UniApp / MicroService`，不得用 `runtime === "micro-app"` 过滤掉其它应用类型。无效清单应记录诊断，不能静默吞掉整个目录。
-- “安装到当前租户”和“发布到应用商城（不安装）”是两个独立动作。商城发布只能同步 `sys_microistore`、应用源码/构建/版本元数据及安装包，不得新增或修改当前租户的 `sys_microiservice / sys_microiservice_page`；操作前后必须回读运行态确认未变化。
-- 应用项目行必须直接显示商城发布入口，不能只藏在右键菜单；同时保留构建安装和源码同步状态入口。
-
-## 版本与回滚
-
-- 版本号单调递增，保存变更清单和前后哈希。
-- 公有发布必须同时保留两套入口：`/{OsClient}/ai-app-publish/{AppKey}/index.html` 永远指向最新版，`.../versions/{Version}/index.html` 永远保留该历史版本。先完整上传并逐字节验签不可变版本目录，再切换稳定入口。带 `data-microi-immutable-runtime` 的新入口通过版本目录解析全部资源，可先切换入口；旧入口仍在其它稳定资产之后切换。不能机械固定“入口永远最后”而破坏两种契约。
-- stage 前回读并冻结应用的 `CurrentVersion + AppVersion`；finalize 必须同时传 `ExpectedCurrentVersion + ExpectedAppVersion`，在以不可变 AppId 加锁后再次 compare-and-set。缺失前置条件、AppId/AppKey 漂移或旧请求晚到一律失败关闭；重新发布必须重新盘点，不能静默回退。
-- 新清单发布成功时，同应用 `dist/` 下不再出现的 active 文件元数据只能条件式改为可逆归档 scope，条件必须包含 AppId、路径、旧 scope 与版本；禁止删除 HDFS/数据库记录，也不得触碰 Private、非 `dist/` 或另一应用的行。
-- 官网、二维码和用户分享只使用无版本号根入口，不追加 `v/apiBase/OsClient`。目标租户的 `ApiBase/OsClient` 在发布或安装时写入入口 HTML 的 `window.__MICROI_APP_CONTEXT__ / MICROI_API_BASE / MICROI_OS_CLIENT`；安装包不得沿用发布端运行上下文。
-- 数据迁移通常只向前；回滚应用版本不能假设自动回滚业务数据。
-- 更新失败保留原版本可运行资源，记录失败阶段；不要清空客户 V8 后再尝试恢复。
-- 私有源码仓库、`Microi.net/License/keys` 和部署密钥不进入公开应用包。
-
-## 验收清单
-
-- [ ] 同一包重复安装无重复表/字段/菜单/任务
-- [ ] 客户自定义 V8 与非包拥有配置保持不变
-- [ ] 源码包、构建包、Manifest 和数据库版本一致且哈希可核
-- [ ] 无版本号根入口与当前商城版本一致，历史版本 URL 仍可独立访问
-- [ ] 安装到不同 ApiBase/OsClient 后，入口 HTML 使用目标租户上下文且分享 URL 无运行参数
-- [ ] 中断/重启后可恢复，两个节点不会重复副作用
-- [ ] 普通角色不能安装、升级、卸载或读取私有源码
-- [ ] 缓存刷新后远端 API 与真实 UI 通过
-- [ ] 卸载范围明确、可审计、可恢复或已提示不可恢复
+---
+name: app-store
+description: Microi 应用商城开发、打包、安装和升级规范。用于官方/社区应用、Manifest、源码与构建产物、依赖、后台安装任务、租户隔离、增量升级、回滚和验收。
+---
+
+# Microi 应用商城
+
+## 核心原则
+
+应用包是可审计、可重复安装、可增量升级的交付单元。运行类型使用 `ApplicationType`：普通平台包的新建默认值是 `Regular`，既有商城平台应用/通知仍使用 `Platform`，另外还有 `MicroService`、`UniApp`、`Web`；读取端必须兼容 `Regular/Platform`，不能在迁移完成前强制改单值。官方/社区来源使用 `PublisherType`。
+
+`AppType` 是历史复用字段：旧包/接口曾把它用于官方/社区来源，也曾把它作为运行类型回退。新代码不能把 `AppType` 当事实源；只在读取旧数据时回退，写入新数据使用 `ApplicationType + PublisherType`。
+
+客户已有的全局 V8、表单配置、菜单、字段和自定义代码必须保留。升级采用存在性检查、差异合并和包隔离，禁止整表覆盖或把发布方租户数据原样复制到目标租户。
+
+## 包内容
+
+- Manifest：应用 Key、版本、兼容平台版本、依赖和资源清单。
+- 数据模型：表、字段、菜单、角色权限、接口引擎、事件、数据源、页面、打印、工作流、任务。
+- 源码与构建：私有源码包与可部署构建包分离，记录 SHA-256。
+- 安装/升级脚本：幂等、可恢复、可回读；不包含租户密钥、Token、连接串或 License keys。
+- 迁移采用“先扩展、后迁移、再收缩”，支持新旧节点短暂并存。
+
+## 安装流程
+
+1. 校验签名/哈希、包版本、平台兼容性、依赖和磁盘/配额。
+2. 创建全局唯一 `InstallationId` 和稳定幂等键。
+3. 使用后台任务执行，阶段性持久化进度与 checkpoint。
+4. 按 Manifest 差异创建缺失资源；已有资源只更新包拥有且允许升级的属性。
+5. 写入成功后刷新共享缓存版本。
+6. 回读表、字段、引擎、菜单、权限、页面等关键资源。
+7. 做 HTTP、UI 和权限冒烟；成功后标记安装版本。
+
+安装中断后从 checkpoint 幂等恢复；不能依赖当前 API 节点内存。
+
+## 权限与租户
+
+- 商城定义、安装、升级、卸载和应用源码只允许 `Level >= 9999`。
+- “吾码官方平台”不能只按 `OsClient`、域名或前端变量判断：服务端必须同时校验官方 `OsClient`，并确认当前节点固定只读挂载 `/app/microi_private.pem` 的公钥部分与内嵌官方 License 信任根匹配；本地源码开发可从私有子仓库兼容查找。任意自建私钥不能建立官方身份。官方平台前端隐藏安装、更新、重新安装、离线安装和批量安装入口，后端仍必须拒绝这些写操作。
+- 所有资源按目标 `OsClient` 写入；包内不能携带源租户 `OsClient`、数据库、Redis、对象存储、MQ/MQTT、AI 或第三方密钥。
+- 按钮调用后台安装接口时，前端只传应用/版本/安装 Id；目标租户和管理员身份由 Token 确定。
+- 每次安装、更新、重新安装生成稳定 `OperationId`。官方计数服务用共享数据库事件表唯一约束去重，并在同一事务内登记事件和递增 `InstallCount`；重试、跨节点和响应丢失不得重复计数。
+- “全部安装/更新”固定只处理 `ApplicationType=Platform` 的官方平台应用中未安装与存在新版本的项目，不得把 UniApp、Web、MicroService 或其它社区/AI 应用整库安装；已是最新版的应用不重新安装。批量计划、子项状态、checkpoint 和进度必须持久化到共享数据库/后台任务，支持多节点抢占、失败重试和重启恢复，不能依赖进程内集合或浏览器状态。
+- 批量任务已经以“一个应用”为外层持久化恢复单元。规模可控的小型官方包应在一个事务中完成，避免对同一包体按 8 个字段反复下载、解析和重新排队；超过字段、表、DDL、流程、随包数据或资产安全阈值的大包继续使用内部 checkpoint 分片。热更新发现旧版批量计划不含 `ApplicationType` 时，必须丢弃旧计划并重新盘点，不能继续安装历史计划中的社区应用。
+- MySQL 宽表触发 65,535 字节行内上限时，只允许把不参与索引的 `varchar` 配置列无损提升为 `mediumtext`，并把类型覆盖持久化到后台任务 checkpoint；索引列和非行宽错误必须失败关闭。发布包对长连接串、密钥、回调地址、域名/白名单等字段应直接使用 `mediumtext`，同时更新 `DiyFields` 与建表 DDL，不能长期依赖安装时猜测。
+- 卸载是破坏性操作，必须明确列出将删除/保留的资源、二次确认并优先软删除/归档业务数据。
+
+## MCP 工作流
+
+1. 安装/更新现成商城应用时，先调用 `microi_install_store_application` / `microi_update_store_application` 且不传 `confirmExecution`，核对目标租户、商城源、StoreId 和幂等请求 Id 的预检结果。
+2. 用户明确确认后，把 `confirmExecution` 精确设为 `StoreId`，提交真实持久化后台任务；只传 StoreId、版本和商城源定位信息，不通过 MCP/HTTP 传完整 `AppPakcet`。
+3. 自建应用或低代码系统先用 `microi_list_applications` / `microi_get_application_context` 盘点源码，再用 `microi_get_manifest_schema`、`microi_plan_system` 与 `microi_generate_system(dryRun:true)` 干跑。
+4. 安装任务必须回读至 `Succeeded`，再执行 `microi_validate_system`、远端资源回读和真实 UI 验收；仅返回 TaskId 不代表安装成功。
+
+已有 MicroService 优先新增页面/路由；没有时才创建、同步源码、发布构建。复杂安装交互使用 `V8.OpenAppDialog`，后台任务上报进度。
+
+## VS Code 本地应用与发布边界
+
+- `AI应用` 本地树按每个一级目录的 `.microi-micro-app.json` 发现项目；只要 `osClient/apiBaseUrl` 与当前连接一致，就必须显示 `Web / UniApp / MicroService`，不得用 `runtime === "micro-app"` 过滤掉其它应用类型。无效清单应记录诊断，不能静默吞掉整个目录。
+- “安装到当前租户”和“发布到应用商城（不安装）”是两个独立动作。商城发布只能同步 `sys_microistore`、应用源码/构建/版本元数据及安装包，不得新增或修改当前租户的 `sys_microiservice / sys_microiservice_page`；操作前后必须回读运行态确认未变化。
+- 应用项目行必须直接显示商城发布入口，不能只藏在右键菜单；同时保留构建安装和源码同步状态入口。
+
+## 版本与回滚
+
+- 版本号单调递增，保存变更清单和前后哈希。
+- 公有发布必须同时保留两套入口：`/{OsClient}/ai-app-publish/{AppKey}/index.html` 永远指向最新版，`.../versions/{Version}/index.html` 永远保留该历史版本。先完整上传并逐字节验签不可变版本目录，再切换稳定入口。带 `data-microi-immutable-runtime` 的新入口通过版本目录解析全部资源，可先切换入口；旧入口仍在其它稳定资产之后切换。不能机械固定“入口永远最后”而破坏两种契约。
+- stage 前回读并冻结应用的 `CurrentVersion + AppVersion`；finalize 必须同时传 `ExpectedCurrentVersion + ExpectedAppVersion`，在以不可变 AppId 加锁后再次 compare-and-set。缺失前置条件、AppId/AppKey 漂移或旧请求晚到一律失败关闭；重新发布必须重新盘点，不能静默回退。
+- 新清单发布成功时，同应用 `dist/` 下不再出现的 active 文件元数据只能条件式改为可逆归档 scope，条件必须包含 AppId、路径、旧 scope 与版本；禁止删除 HDFS/数据库记录，也不得触碰 Private、非 `dist/` 或另一应用的行。
+- 官网、二维码和用户分享只使用无版本号根入口，不追加 `v/apiBase/OsClient`。目标租户的 `ApiBase/OsClient` 在发布或安装时写入入口 HTML 的 `window.__MICROI_APP_CONTEXT__ / MICROI_API_BASE / MICROI_OS_CLIENT`；安装包不得沿用发布端运行上下文。
+- 数据迁移通常只向前；回滚应用版本不能假设自动回滚业务数据。
+- 更新失败保留原版本可运行资源，记录失败阶段；不要清空客户 V8 后再尝试恢复。
+- 私有源码仓库、`Microi.net/License/keys` 和部署密钥不进入公开应用包。
+
+## 验收清单
+
+- [ ] 同一包重复安装无重复表/字段/菜单/任务
+- [ ] 客户自定义 V8 与非包拥有配置保持不变
+- [ ] 源码包、构建包、Manifest 和数据库版本一致且哈希可核
+- [ ] 无版本号根入口与当前商城版本一致，历史版本 URL 仍可独立访问
+- [ ] 安装到不同 ApiBase/OsClient 后，入口 HTML 使用目标租户上下文且分享 URL 无运行参数
+- [ ] 中断/重启后可恢复，两个节点不会重复副作用
+- [ ] 普通角色不能安装、升级、卸载或读取私有源码
+- [ ] 缓存刷新后远端 API 与真实 UI 通过
+- [ ] 卸载范围明确、可审计、可恢复或已提示不可恢复
+
+## 复盘：商城按钮已到达但依赖接口引擎缺失
+
+- 触发场景：子租户更新应用商城后能够看到“全部安装/更新”，点击却提示 `sys_apiengine` 中不存在按钮调用的接口；继续临时补引擎后，还可能因目标租户缺少批量计划表再次失败。
+- 根因：商城元数据版本、`AppPakcet.PackageInfo.Version` 与真实包正文发生分叉，页面按钮被单独更新；同时应用导入器把接口引擎新增/更新失败只写进 Debug 后继续返回成功，没有做写后回读，批量引擎又依赖未随同一应用包交付的表。
+- 通用规则：按钮及其调用的接口引擎、表和权限必须属于同一个单调版本应用包；任何依赖写入失败或回读内容不一致都要让安装事务失败。可复用的批量状态优先写入平台后台任务 `CheckpointJson`，避免仅为批量编排增加未交付的租户表。商城行版本、包内版本和包内容哈希必须同时回读一致，禁止单独提升商城行版本或只更新菜单。
+- 自动化检查：应用包契约测试必须从按钮代码提取接口 Key，断言包内存在启用且配置正确的引擎并与独立源码逐字一致；导入器测试覆盖新增失败、更新失败、缓存清理后回读缺失和源码不一致均返回 `Code=0`；真实子租户更新后回读 `sys_menu + sys_apiengine + 后台任务`，再实际执行一次“无需更新”和至少一个安装/更新计划。
+
+## 复盘：可信后台任务被 StopHttp 提前拦截
+
+- 触发场景：`V8.ApiEngine.RunBackground` 已成功创建任务，但 Worker 执行 `StopHttp=1` 的批量引擎时立即失败并提示“此接口已禁止http调用”。
+- 根因：Worker 为保留按钮调用、权限和审计语义继续使用 `_InvokeType=Client`，旧版 ApiEngine 只按该字段判断 `StopHttp`，没有识别服务端恢复的持久化任务来源。
+- 通用规则：核心 ApiEngine 仅在“服务端可信用户作用域 + `_TrustedServerInvocation=true` + 非空任务 Id + 匹配任务信封 + 正数 fencing token”全部成立时豁免 `StopHttp`；少一项都按普通 HTTP 拒绝。不得把所有后台调用粗暴改成 `Server`，也不得只凭客户端可伪造的任务 Id 或信封放行。
+- 旧节点兼容：应用资源尚需覆盖未部署核心修复的服务，可暂将批量引擎设为 `StopHttp=0`，但 V8 首行安全门必须执行同样的全条件校验；HTTP 控制器必须剥离 `_TrustedServerInvocation`。契约测试同时断言严格 `AND` 校验、独立源码与包内副本一致、普通调用失败关闭。
+
+## 复盘：后台任务基础包的自举与索引幂等
+
+- `app.microi.background-task` 自身负责创建/修复后台任务表，首次安装和离线安装必须以前台接口完成；不能先调用 `RunBackground`，否则旧库缺少 `OsClient` 等字段时会在导入开始前失败。
+- 后台任务可用性不能只检查表存在，还要检查运行时必需列；部分升级的旧表必须返回“能力尚未就绪”，不能继续拼接包含缺失列的 SQL。
+- 应用包中的独立 `CREATE INDEX` 必须按表名和索引名做执行前回读；并发创建失败后再次回读，已存在则按幂等成功处理。索引 DDL 不能重复触发整张表的字段同步。
+- 基础包必须同时携带 `OsClient` 的 `PhysicalColumns` 定义、建表内联索引与 4 条独立索引 DDL；新表靠建表一次成型，旧表靠物理列同步和独立 DDL 修复。安装前先把“应用商城”更新到包含 `BACKGROUND_TASK_BOOTSTRAP_READINESS_V1`、`APPLICATION_ASSET_BACKGROUND_CHUNKS_V1` 的 v1.8.0+ 导入器；安装成功前必须回读全部运行字段及索引，验收覆盖首次安装、部分旧表修复、重复安装和两节点竞态。
+- 其它用户更新吾码 VS Code 插件并执行“初始化 AI 配置/拉取 Skills”后，AI 应自动识别本规范：大任务优先提交真实后台任务；若基础能力未就绪，先指导用户更新应用商城并以前台方式安装 `app.microi.background-task`，不得伪造进度或让基础包自举入队。
+- 重复安装先比较应用包拥有的字段定义，完全一致就跳过 `UptFormData`。Jint 的 `LimitMemory` 统计累计托管分配而非当前存活堆；大量无效字段更新即使被 GC 回收也会耗尽预算。v1.8.0 导入器每个后台片最多实际上传 8 个文件，并以约 32 MB Base64 为分片目标；为避免单个大文件无限空转，每片至少允许处理一个文件。片末返回 `HasMore + Checkpoint`，下一片按 `AppId + FilePath + Hash` 复用已提交资产，并禁止为统计再次解码整文件 Base64。
+- 只有固定 Key `import-microi-store-package`、服务端可信身份、`Level >= 9999`、当前进程主租户、持久化后台 TaskId 五项同时成立时，后端才使用 `ResidentMemoryGuardOnly`，跳过会永久累计已回收分配的 Jint 内存约束。该特例仍受容器优先的进程 RSS 防线保护：95% 停止接收新工作，98% 有界停机并由持久任务恢复。普通/前台/子租户/其它 V8 不得借用此特例。
+
+## 复盘：官网升级资源同步的三道门
+
+- 官网当前资源只是三方合并的一侧，允许暂时落后于本地发布候选。下载阶段只校验固定白名单、稳定资源身份、JSON 可解析性及服务端返回 SHA-256；不能用“必须已包含本地最新功能标记”的规则提前拒绝旧官网，否则会形成“官网不够新所以永远无法发布新版”的循环依赖。
+- 本地输入和三方合并后的最终候选必须继续执行最低版本、功能标记、内嵌逻辑副本一致性等严格校验；发布成功并按内容哈希回读一致后才能推进 `.resource-sync-base`，不能把放宽读取门误做成放宽发布门。
+- 应用包版本与平台发布版本分别单调递增。包正文需要写回而本地包版本、平台版本均未高于官网时，应基于官网包版本自动递增补丁号；内容无变化时不得递增，必须用连续两次同步验证第二次为零变更。
+- MCP 配置中的官方 API、`OsClient` 与 Token 文件是鉴权事实源，但编辑器可执行文件、插件版本目录和 `cwd` 都是易漂移的启动信息。发布器应保留鉴权配置、固定校验 `https://api.itdos.com + itdos`，并从已配置入口、同级最新已安装插件或当前工作区依次发现可信 `mcp-server.js`，使用正在运行发布脚本的 Node 启动；插件升级或旧目录清理不能再次阻塞后端发布。
+- Token 文件的新键固定为 `ApiBase|OsClient|OsClientType|OsClientNetwork` 四段身份；Type/Network 为空时仍保留空段。读取和回写必须先用四段精确键，再兼容旧版紧凑键；旧键在多环境配置下可能被有意保留且已经失效，禁止优先读取。自动化测试要覆盖“精确键已刷新、旧键仍过期”以及 type-only/network-only 不碰撞。
+- VS Code 的 SecretStorage 恢复 broker 必须使用确定性激活事件启动；不得只依赖大型工作区可能超时的递归 `workspaceContains`。签名密钥变化时旧 Token 本身不能以旧换新，必须由已激活 broker 使用本机 SecretStorage 静默重登并回写精确身份键。
+- 本地资源同步的官网读取、发布和发布后回读应使用同一个已校验的 `microi_itdos` MCP 链路；CI 无 MCP 时才允许凭显式 Token 使用 HTTP。V8 独立文件与应用包内嵌副本合并时，先把文件头说明和 `Version` 与可执行正文分离：两端独立升版不能算代码冲突，不同正文安全合成后应基于两端最高版本再升一版；只有同一段可执行逻辑出现不同实现才失败关闭。
+- 发布验收至少包含：定向合并测试、真实 `PublishBatch`、六项资源逐项 SHA-256 回读，以及立即执行第二次幂等重跑。任何一步失败都不得宣称官网已同步，也不得推进共同基线。
 
-## 复盘：后台任务基础包的自举与索引幂等
+## 复盘：官网模板库误报平台应用可更新
 
-- `app.microi.background-task` 自身负责创建/修复后台任务表，首次安装和离线安装必须以前台接口完成；不能先调用 `RunBackground`，否则旧库缺少 `OsClient` 等字段时会在导入开始前失败。
-- 后台任务可用性不能只检查表存在，还要检查运行时必需列；部分升级的旧表必须返回“能力尚未就绪”，不能继续拼接包含缺失列的 SQL。
-- 应用包中的独立 `CREATE INDEX` 必须按表名和索引名做执行前回读；并发创建失败后再次回读，已存在则按幂等成功处理。索引 DDL 不能重复触发整张表的字段同步。
-- 基础包必须同时携带 `OsClient` 的 `PhysicalColumns` 定义、建表内联索引与 4 条独立索引 DDL；新表靠建表一次成型，旧表靠物理列同步和独立 DDL 修复。安装前先把“应用商城”更新到包含 `BACKGROUND_TASK_BOOTSTRAP_READINESS_V1`、`APPLICATION_ASSET_BACKGROUND_CHUNKS_V1` 的 v1.8.0+ 导入器；安装成功前必须回读全部运行字段及索引，验收覆盖首次安装、部分旧表修复、重复安装和两节点竞态。
-- 其它用户更新吾码 VS Code 插件并执行“初始化 AI 配置/拉取 Skills”后，AI 应自动识别本规范：大任务优先提交真实后台任务；若基础能力未就绪，先指导用户更新应用商城并以前台方式安装 `app.microi.background-task`，不得伪造进度或让基础包自举入队。
-- 重复安装先比较应用包拥有的字段定义，完全一致就跳过 `UptFormData`。Jint 的 `LimitMemory` 统计累计托管分配而非当前存活堆；大量无效字段更新即使被 GC 回收也会耗尽预算。v1.8.0 导入器每个后台片最多实际上传 8 个文件，并以约 32 MB Base64 为分片目标；为避免单个大文件无限空转，每片至少允许处理一个文件。片末返回 `HasMore + Checkpoint`，下一片按 `AppId + FilePath + Hash` 复用已提交资产，并禁止为统计再次解码整文件 Base64。
-- 只有固定 Key `import-microi-store-package`、服务端可信身份、`Level >= 9999`、当前进程主租户、持久化后台 TaskId 五项同时成立时，后端才使用 `ResidentMemoryGuardOnly`，跳过会永久累计已回收分配的 Jint 内存约束。该特例仍受容器优先的进程 RSS 防线保护：95% 停止接收新工作，98% 有界停机并由持久任务恢复。普通/前台/子租户/其它 V8 不得借用此特例。
+- 触发场景：官网 `sys_microistore` 的平台应用版本持续发布，但 `sys_microistoreversion` 仍保留旧安装版本；官网自身会显示“可更新”，从官网数据库复制出来的新租户也继承同一误报，尽管这些平台能力实际已经随官网主库维护完成。
+- 身份边界：只能在服务端同时满足 `OsClient=iTdos` 且当前节点私钥公钥部分与内嵌官方 License 公钥完全一致时执行。只使用同名租户、域名、配置开关或任意自建私钥都不得触发；客户租户的安装版本仍是其独立事实源。
+- 对齐规则：每次后端启动都在现有租户升级分布式租约内盘点 `ApplicationType=Platform + IsApprove=1` 的商城行，只处理 `Installed/Success/Succeeded/已安装` 的既有安装记录，按 `StoreId -> AppId -> 唯一 AppName` 匹配。只条件更新 `AppVersion/AppVersionInstall/PackageVersion`；稳定键仅在目标键未被其它安装记录占用时补齐。不得新增“已安装”记录、覆盖失败/异常状态、修改安装时间或删除重复历史行。
+- 分布式与验收：更新是确定值条件写入，节点中途退出后下次启动继续，第二次执行必须零更新；验收同时回读版本表三个字段，并执行官网商城列表接口，确认 `Outdated=0`、`Abnormal=0`。真实未安装应用仍应保留 `Uninstalled`，不能为了清空通知伪造成已安装。
 
-## 复盘：官网升级资源同步的三道门
+## 复盘：共同基线已有引擎但官网内嵌副本缺失
 
-- 官网当前资源只是三方合并的一侧，允许暂时落后于本地发布候选。下载阶段只校验固定白名单、稳定资源身份、JSON 可解析性及服务端返回 SHA-256；不能用“必须已包含本地最新功能标记”的规则提前拒绝旧官网，否则会形成“官网不够新所以永远无法发布新版”的循环依赖。
-- 本地输入和三方合并后的最终候选必须继续执行最低版本、功能标记、内嵌逻辑副本一致性等严格校验；发布成功并按内容哈希回读一致后才能推进 `.resource-sync-base`，不能把放宽读取门误做成放宽发布门。
-- 应用包版本与平台发布版本分别单调递增。包正文需要写回而本地包版本、平台版本均未高于官网时，应基于官网包版本自动递增补丁号；内容无变化时不得递增，必须用连续两次同步验证第二次为零变更。
-- MCP 配置中的官方 API、`OsClient` 与 Token 文件是鉴权事实源，但编辑器可执行文件、插件版本目录和 `cwd` 都是易漂移的启动信息。发布器应保留鉴权配置、固定校验 `https://api.itdos.com + itdos`，并从已配置入口、同级最新已安装插件或当前工作区依次发现可信 `mcp-server.js`，使用正在运行发布脚本的 Node 启动；插件升级或旧目录清理不能再次阻塞后端发布。
-- 本地资源同步的官网读取、发布和发布后回读应使用同一个已校验的 `microi_itdos` MCP 链路；CI 无 MCP 时才允许凭显式 Token 使用 HTTP。V8 独立文件与应用包内嵌副本合并时，先把文件头说明和 `Version` 与可执行正文分离：两端独立升版不能算代码冲突，不同正文安全合成后应基于两端最高版本再升一版；只有同一段可执行逻辑出现不同实现才失败关闭。
-- 发布验收至少包含：定向合并测试、真实 `PublishBatch`、六项资源逐项 SHA-256 回读，以及立即执行第二次幂等重跑。任何一步失败都不得宣称官网已同步，也不得推进共同基线。
+- 触发场景：本地 `app.microi.store.json`、独立接口脚本和 `.resource-sync-base` 都已有新引擎，但官网商城包尚未收录或被单侧删除；同步器在三方合并前强制读取官网内嵌代码，直接报“缺少接口引擎”，导致新版永远无法通过一键发布补到官网。
+- 根因：旧状态机只区分“共同基线不存在的首次新增”和“三端都存在的正常合并”，漏掉“共同基线已登记、官网副本缺失”的历史基线漂移；严格 getter 在合并前抛错，使已有的首次发布与逻辑副本修复规则没有机会运行。
+- 通用规则：只要副本映射仍属于当前发布契约，本地独立源码和内嵌副本能从共同基线安全合并，官网单独缺少内嵌引擎应视为不完整副本。JSON 合并前只从共同基线恢复该引擎的结构骨架；有官网独立文件时继续把它作为官网代码侧，无独立文件时把共同基线代码视为官网未修改，再执行正文三方合并并将结果写回内嵌副本。写回后必须按 `SysApiEngines.length` 重算 `PackageInfo.ApiEngineCount`。若共同基线引擎 Id 已被其它 Key 占用，或任意两侧同一代码位置实现冲突，仍必须失败关闭；不得通过覆盖/重建整个共同基线来掩盖问题。
+- 自动化检查：同时覆盖共同基线不存在的首次新增、共同基线存在但官网缺失且本地升级、官网内嵌缺失但官网独立源码升级、共同基线 Id 被其它 Key 占用四种状态；断言声明引擎数等于实际数组长度；再用真实 `microi_itdos` 只读资源重放，确认候选含目标引擎且独立源码与内嵌代码相同，正式发布后执行 SHA 回读和零变更幂等重跑。
 
 ## 复盘：老租户 NULL 数据阻止物理列收紧
-
-- 触发场景：商城应用包把既有字段从可空升级为 `NOT NULL DEFAULT ...`，老租户的物理列已经存在，但历史记录仍为 `NULL`；导入器直接执行 `ALTER TABLE ... MODIFY COLUMN ... NOT NULL` 时，MySQL 报 `Invalid use of NULL value`，整个安装分片失败。
-- 根因：物理列同步只比较类型、可空性、默认值和注释，没有在收紧可空性前迁移存量数据。列默认值只影响后续写入，不会自动修复既有 `NULL`。
-- 通用规则：当包要求 `NOT NULL`、目标列仍可空且存在历史 `NULL` 时，必须先用包内明确声明的默认值参数化回填，再执行列约束变更；包未声明默认值时失败关闭并报告影响行数，禁止猜测业务值。该步骤必须可重复执行，并允许多节点并发重试后得到同一结果。
-- 自动化检查：构造可空旧列及多条 `NULL` 行，断言导入器按“统计 NULL → 参数化回填 → `MODIFY ... NOT NULL`”顺序执行；覆盖字符串、整数、零行、缺失默认值、重复执行，以及商城包中全部发布协议状态字段。
+
+- 触发场景：商城应用包把既有字段从可空升级为 `NOT NULL DEFAULT ...`，老租户的物理列已经存在，但历史记录仍为 `NULL`；导入器直接执行 `ALTER TABLE ... MODIFY COLUMN ... NOT NULL` 时，MySQL 报 `Invalid use of NULL value`，整个安装分片失败。
+- 根因：物理列同步只比较类型、可空性、默认值和注释，没有在收紧可空性前迁移存量数据。列默认值只影响后续写入，不会自动修复既有 `NULL`。
+- 通用规则：当包要求 `NOT NULL`、目标列仍可空且存在历史 `NULL` 时，必须先用包内明确声明的默认值参数化回填，再执行列约束变更；包未声明默认值时失败关闭并报告影响行数，禁止猜测业务值。该步骤必须可重复执行，并允许多节点并发重试后得到同一结果。
+- 自动化检查：构造可空旧列及多条 `NULL` 行，断言导入器按“统计 NULL → 参数化回填 → `MODIFY ... NOT NULL`”顺序执行；覆盖字符串、整数、零行、缺失默认值、重复执行，以及商城包中全部发布协议状态字段。

package/dist/microi.skills/message-notification/agents/openai.yaml

@@ -3,4 +3,3 @@ interface:
   short_description: "设计、实现并验收租户安全的多通道与平台内部实时消息通知"
   brand_color: "#409EFF"
   default_prompt: "Use $message-notification to design and verify a tenant-safe Microi notification flow."
-

package/dist/microi.skills/microi-ai-application/SKILL.md

@@ -41,6 +41,14 @@ UniApp 使用 Vue 3 + TypeScript 的官方 Vite 工具链，并同时遵守 `mic
 - 新业务使用平台通用 v2 `/api-engine-realtime`，以普通登录 Token 调用 `SubscribeChannel`。30 秒时隙租约必须按返回的 `RenewAfterMilliseconds` 重复订阅续租，每次续租由 `realtime_{channel_key}_authorize` 按 `V8.CurrentUser` 重新授权；现有 AccessKey 在没有 `realtime:subscribe` scope 时拒绝。不要为每个游戏或业务再新增专用 C# Hub；旧 `/game-realtime` 仅作兼容。
 - 环境配置从 `window.__MICROI_APP_CONTEXT__`、宿主上下文和模式文件解析。生产构建拒绝 localhost；开发地址只写 `.env.development.local`。
 
+## 调用平台 AI
+
+- 运行在吾码表单、表格、按钮或接口引擎上下文中的代码优先使用第一等 `V8.AI`：普通对话用 `await V8.AI.Chat(param)`，真实打字机输出用 `await V8.AI.ChatStream(param, onChunk, { Signal })`。前端实现会复用当前 ApiBase、登录 Token、设备/语言头和 Token 轮换；后端实现会固定绑定当前 `OsClient` 与认证用户。
+- 独立 Web、MicroService、UniApp 的工程代码在 `src/services/ai.ts` 建立薄适配，调用当前平台 `POST /api/Ai/Chat` 或 SSE `POST /api/Ai/ChatStream`；从标准 Microi SDK/宿主上下文取得认证，不在页面中拼 Token、Endpoint、供应商 ApiKey 或任意 Header。
+- 请求只传业务白名单字段，如 `UserChatMsg`、`AiModel`、`AiModelId`、`RelayModel`、`ConversationId`、`Mode`、`ReasoningEffort`、`Attachments`。服务端身份、租户、模型 Endpoint 和密钥不可由页面覆盖；NL2SQL 必须走专用受控入口，不能把页面提交的表名当授权。
+- 外部 Agent 使用 MCP 的 `microi_chat` 获取最终对话结果；它不提供逐 token MCP 流，也不等于平台在线模型已经获得其它 MCP Tool 的 Agent Loop。需要写平台数据时仍调用对应写 Tool，执行确认、幂等和远端回读。
+- 服务器 License 在本机通过官方公钥验签；有效 License 不要求每次 AI 调用访问官网。官方中转模型还会单独校验 `sk-microi-*` 和账号额度，这两套授权不能相互替代。
+
 ## Vue 实现规则
 
 - SFC 模板承担真实 DOM 结构；事件使用 Vue 绑定，状态使用 `ref/reactive/computed`，副作用在组合函数的生命周期内注册并清理。