@microi.net/cli 4.8.2 → 4.8.8

package/skills/ai-platform-governance/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: ai-platform-governance
+description: Microi吾码 AI 平台治理中心设计、调用、扩展、应用商城升级与验收规范。用于门户与资源版本、身份目录/用户组/权限解释、配置模板与漂移、功能开关、发布审批/门禁/断点回滚、服务注册路由与韧性、Trace/告警/日志生命周期、资产物料、协作租约和可恢复导入。
+---
+
+# Microi吾码 AI 平台治理中心
+
+## 何时使用
+
+以下任一需求都应使用本 Skill：
+
+- 门户项目、插槽、资产、版本发布、Diff 或回滚；
+- 身份目录同步、动态用户组、标签、人群圈选、批量授权、访问申请、临时权限或权限解释；
+- 配置模板/继承/Secret 引用、配置漂移或功能开关；
+- 发布计划、多人审批、职责分离、自动门禁、断点续发或回滚；
+- 服务注册、实例心跳/排空、版本/区域/标签/权重路由、限流、熔断、重试、降级或服务拓扑；
+- W3C Trace、告警规则、值班升级、可靠通知或日志热温冷生命周期；
+- 可复用组件/区块资产、依赖解析、协作租约或跨资源变更集；
+- JSON/CSV/Excel 可恢复导入；
+- 发布或安装官方应用 `ai-platform-studio`。
+
+## 不可破坏的边界
+
+- DiyToken 是唯一会话入口；继续复用现有用户、角色、部门、菜单、表权限和数据范围，禁止建立第二套 Token/RBAC。
+- 所有治理事实写入当前 `OsClient` 数据库或租户隔离 Redis；禁止把 `static`、单例字典、本机定时器或浏览器存储作为平台完成事实。
+- 普通业务编排优先接口引擎。C# 只提供目录协议/Secret 隔离、真实 FormEngine 权限解释、Trace/日志物理访问和 Redis 原子缓存等底层可信原子能力。
+- 核心资源由应用商城交付，不为表、字段、菜单、接口、任务或种子数据添加定制 `Microi.Upgrade` 迁移。
+- 所有危险动作必须是 Plan/DryRun → Hash/CAS → 幂等执行 → 回读 → 条件回滚。
+- 锁只解决并发，不代替稳定幂等键、唯一约束、状态机、outbox/inbox 或条件写入。
+- Secret 只保存引用；列表、Diff、错误、日志、截图、导出和运行台账不得出现密码、Token、私钥或连接串原文。
+
+## 官方应用事实
+
+应用 Key：`ai-platform-studio`，当前资源合同版本：`v2.0.3`。
+
+- 40 张 `mci_` 治理表和 5 张运行基础表，应用包共 45 张表、873 个字段；
+- 42 个后台菜单：1 个 `AI平台治理` 父菜单、1 个 `AI平台治理工作台` 微服务菜单和 40 个数据菜单；
+- 64 个接口引擎：57 个 `Managed`，7 个 `CreateIfMissing`；
+- 1 个 `MciAiPlatformMinuteSweep` 维护任务；
+- 10 个微服务路由：`overview`、`portal`、`identity`、`access`、`configuration`、`release`、`services`、`observability`、`assets`、`import`。
+
+租户 Hook：
+
+```text
+mci-portal-publish-extension
+mci-identity-source-extension
+mci-release-gate-extension
+mci-alert-notify-extension
+mci-asset-validate-extension
+mci-log-archive-extension
+mci-release-execute-extension
+```
+
+Hook 首次创建后归租户维护，升级永不覆盖，也不得把同 Key 改回 `Managed`。
+
+## 菜单层级与语义
+
+应用安装或升级后必须形成以下层级，禁止把 40 个数据菜单平铺到根级或直接平铺在系统引擎下：
+
+```text
+系统引擎 (cdc0844b-7249-4d64-a9c3-563a15c9cd20)
+└─ AI平台治理 (SecondMenu)
+   ├─ AI平台治理工作台 (MicroService: /micro-app/ai-platform-studio/overview)
+   └─ 40 个 AI平台治理·* 数据菜单
+```
+
+`AI平台治理工作台` 是 10 个治理页面的统一操作入口，必须同时绑定 `MicroServiceId`、`MicroServicePageId`、`MicroServiceRoutePath=/overview` 和 `MicroServiceKey=ai-platform-studio`；不得只创建普通 URL 菜单。`system.manifest.json.menuCatalog` 是数据菜单用途与排序的事实源。40 个数据菜单按以下 9 个业务域排序：
+
+| 业务域 | 数据菜单 | 主要作用 |
+|---|---|---|
+| 门户装配 | 门户项目、门户插槽、门户资源、资源版本 | 组合门户并维护不可变发布版本 |
+| 身份目录 | 身份连接器、身份同步、身份冲突、组织快照 | 同步外部身份并处理冲突 |
+| 人群与授权 | 动态用户组、用户组成员、用户标签、标签分配、授权变更集、授权变更明细、访问申请、临时授权 | 按人群申请、授予、到期回收并保留证据 |
+| 配置与灰度 | 配置模板、配置漂移、功能开关 | 管理配置基线、环境偏差和灰度开关 |
+| 发布治理 | 发布计划、发布审批、发布运行、变更台账 | 计划、审批、门禁、执行、恢复和审计发布 |
+| 服务治理 | 服务目录、服务实例、流量策略、调用结果、服务拓扑 | 管理实例租约、路由韧性和调用事实 |
+| 可观测与日志 | 可观测策略、规则评估台账、告警事件、告警路由、告警送达、日志策略、日志生命周期 | 监控、告警、可靠通知和日志归档闭环 |
+| 资产与协作 | 资产包、资产版本、协作租约 | 交付可复用资产并避免并发覆盖 |
+| 数据迁移 | 导入批次、导入暂存行 | 预检、分片执行、恢复和回滚大批量导入 |
+
+向用户解释时必须区分页面类型：`配置` 是日常维护入口，`审批/处置` 在有待办或异常时使用，`运行` 用于观察和恢复任务，`台账` 主要供审计与排错。不得把台账页描述成需要人工逐项维护的业务模块。
+
+## 通用调用规则
+
+1. 通过 MCP 回读当前表结构、菜单、接口、应用和微服务事实。
+2. 调用 `*-plan`、`*-publish` 的 `DryRun=true` 或专用预检接口。
+3. 保存返回的 `PlanHash/ContentHash/RowVersion`，展示影响和阻断项。
+4. 只有用户授权后执行写操作；服务端从 DiyToken 重算身份与租户。
+5. 写后回读主记录、不可变版本、运行台账和实际页面。
+6. 分开报告源码/测试、远端写入、浏览器、应用商城和生产部署证据。
+
+旧 Hash、旧 RowVersion、旧 fencing token、未知状态、未知步骤或未知字段一律失败关闭。
+
+## 门户与资源版本
+
+调用顺序：
+
+```text
+mci-portal-publish-plan
+  → mci-portal-publish(ExpectedSnapshotHash)
+  → mci-portal-resolve
+```
+
+- `ProjectKey/SlotKey/AssetKey` 稳定且项目内唯一。
+- 发布先写 `mci_resource_version`，再 CAS 切换活动版本指针。
+- 相同 Hash 幂等复用；旧 Hash 冲突后必须重新计划。
+- `mci-resource-compare` 做语义比较。
+- `mci-resource-rollback` 校验 `ExpectedCurrentHash` 并创建新回滚版本，不能删除历史。
+
+## 身份与访问治理
+
+### 身份同步
+
+```text
+mci-identity-sync-plan → 人工处置冲突 → mci-identity-sync-apply
+```
+
+- 可信 SCIM 适配器为 `V8.Method.ReadIdentityDirectoryPage`；只允许 HTTPS、受控 DNS、非私网目标、有界页数和 Secret 引用。
+- 新账号默认停用。邮箱、手机号或账号多重命中时进入 `mci_identity_sync_conflict`，禁止猜测合并。
+- 增量游标、计划 Hash 和 IdempotencyKey 必须一致。
+- 非 SCIM 目录通过 `mci-identity-source-extension` 接入；Hook 也不能返回 Secret 原文。
+
+### 用户组、标签和授权
+
+- `mci-identity-group-preview`：静态成员或标签集合预览；空规则失败关闭。
+- `mci-identity-group-refresh`：写入带 SnapshotId 的共享成员快照。
+- `mci-identity-tag-assign`：分配/撤销标签，记录有效期和 `EvidenceHash`。
+- `mci-access-change-plan/apply/rollback`：批量授权计划、逐项执行和条件回滚。
+- `mci-access-request`：`Submit/Approve/Reject/Cancel/Revoke` 与临时授权。
+- `mci-access-entitlement-expire`：维护任务回收过期授权。
+- `mci-org-snapshot`：不可变组织树快照与结构差异。
+
+`mci-permission-explain` 必须调用 `V8.Method.ExplainAuthorizationDecision` 复用真实 FormEngine 授权逻辑；禁止从菜单/角色表重新拼近似结论。
+
+## 配置模板与漂移
+
+`mci-configuration-publish` 输入要点：
+
+```js
+{
+  ProfileKey, Name, Category, Environment, ParentProfileId, VersionNo,
+  Schema, Values, SecretReferences, Owner, Enabled,
+  ExpectedContentHash, ChangeSummary, DryRun
+}
+```
+
+- `Values` 只能放非敏感值；敏感路径映射到 `SecretReferences`。
+- 继承最多 10 层，检测循环。
+- 稳定规范化、SHA-256、DryRun、CAS 和 `ConfigurationProfile` 不可变版本必须同时存在。
+- `mci-configuration-resolve` 返回 `EffectiveHash`，并保持 `SecretValuesResolved=false`。
+- `mci-configuration-drift-scan` 生成有界语义差异。
+- `mci-configuration-drift-transition` 使用 `ExpectedRowVersion` 完成 Ignore/Reopen/Resolve；摘要仍不一致时不能 Resolve。
+
+## 功能开关
+
+发布调用 `mci-feature-flag-publish`，求值调用 `mci-feature-flag-evaluate`。
+
+- 规则只允许 `UserIds/ExcludedUserIds/DeptIds/RoleIds`。
+- 灰度比例 0—100，按稳定主体 Hash 分桶，禁止 `Math.random()`。
+- 普通用户只能使用当前 DiyToken 的权威 `UserId/RoleIds/DeptIds`；只有超级管理员可模拟其它主体。
+- 开关内容生成 `FeatureFlag` 不可变版本；无变化复用，版本号冲突拒绝。
+- 功能开关不能代替任何权限、状态机、幂等或审计。
+
+## 发布状态机
+
+### 固定计划
+
+使用 `mci-release-plan-publish`，不要直接 Add/Upt `mci_release_plan`。
+
+允许发布步骤：
+
+- `Verify`：`FeatureFlag/ConfigurationProfile/ServicePolicy/AssetVersion/Portal/ChangeSet`；
+- `PortalPublish`；
+- `Extension`：由 `mci-release-execute-extension` 处理并使用 `StepIdempotencyKey`。
+
+允许回滚步骤：`Verify`、`PortalRollback`、`Extension`。
+
+生产计划至少包含发布步骤、回滚步骤、测试/回读证据和审批策略。计划中发现疑似 Secret 失败关闭。
+
+### 审批
+
+`mci-release-transition` 支持：
+
+```text
+Submit / Approve / Reject / Cancel / Reopen
+```
+
+每次调用必须传 `ExpectedPlanHash + ExpectedRowVersion`。审批记录按计划 Hash、轮次和审批人生成不可变 `ApprovalKey`。职责分离开启时创建人不能审批自己的计划。
+
+### 门禁
+
+`mci-release-validate` 可检查：
+
+- 计划完整性、发布/回滚步骤、证据和审批；
+- `NoCriticalAlerts`、`NoIdentityConflicts`、`NoConfigurationDrift`；
+- `PortalVersion`、`FeatureFlag`、`ChangeSet`；
+- `Extension` 门禁。
+
+通过只进入 `Ready`，不等于已发布。
+
+### 执行与恢复
+
+`mci-release-execute` 输入：
+
+```js
+{
+  ReleasePlanId,
+  Direction: 'Release' | 'Rollback',
+  IdempotencyKey,
+  ExpectedPlanHash,
+  Resume: false
+}
+```
+
+- 每次调用只提交一个步骤；调用方依据 `HasMore` 继续。
+- 运行台账保存 RunKey、Checkpoint、LeaseToken/Expiry、FencingToken、RowVersion 和结果摘要。
+- 失败返回 `Code=1, Data.Status='Failed', ResumeRequired=true`，以便失败事实提交；业务成功不能只看 `Code`。
+- 续跑必须使用同一 IdempotencyKey 且 `Resume=true`。
+- 变更子步骤使用独立事务；成功后台账中断时用 `StepIdempotencyKey` 重试。
+
+## 服务治理
+
+### 实例协议
+
+- `mci-service-instance-register`：生成实例令牌，数据库只存摘要。
+- `mci-service-instance-heartbeat`：实例身份或管理员更新租约，使用 RowVersion/FencingToken。
+- `mci-service-instance-drain`：先排空再退出流量。
+
+### 策略与调用闭环
+
+- `mci-service-policy-publish`：版本/区域/标签/权重、限流、熔断、重试、降级；DryRun/CAS/不可变 `ServicePolicy` 版本。
+- `mci-service-resolve`：按权威角色/主体与稳定 Hash 选择单个端点，普通调用方不返回全部候选。
+- `mci-service-policy-acquire`：共享 Redis 固定窗口、持久 Outcome 重建熔断、半开共享许可。
+- `mci-service-policy-outcome`：Permit 归属校验、稳定 OutcomeKey、持久结果与调用边聚合。
+- `mci-service-topology`：从持久调用边读取运行拓扑。
+
+V8 业务只能使用租户隔离的 `SetIfNotExists/Expire/HashIncrement` 原子能力，不能获得原始 Redis 客户端或自定义 Key 前缀逃逸租户边界。
+
+## Trace、告警与日志
+
+### 可信原子能力
+
+- `V8.Method.QuerySystemLogSignal`：有界日志计数、错误率、P95 和样例；
+- `V8.Method.GetTraceTimeline`：跨月 Trace/Span 时间线；
+- `V8.Method.PlanSystemLogLifecycle`：只读生命周期估算；
+- `V8.Method.RunSystemLogLifecycle`：仅可信持久后台任务可调用的物理执行器。
+
+### 告警
+
+- `mci-alert-evaluate` 使用持久窗口台账，覆盖连续触发/恢复、去重和抑制。
+- `mci-alert-scan`、`mci-alert-dispatch`、`mci-alert-delivery-send` 均为内部任务接口。
+- Dispatch 只写 Outbox；Sender 以 ClaimToken、LeaseExpiresAt、RowVersion 和 DeliveryKey 送达。
+- `mci_alert_route` 可配置值班排班、升级链和 SLA。
+- 渠道发送只写 `mci-alert-notify-extension`。
+
+### 日志生命周期
+
+`mci_log_policy` 包含匹配/采样、脱敏规则、热温冷天数、日/总配额、超限动作、归档模式和法律保留。
+
+- 先 `mci-log-lifecycle-plan` 获取 PlanHash/估算。
+- 再通过持久后台任务调用 `mci-log-lifecycle-execute`。
+- 每片归档为 gzip JSONL，私有 HDFS 必须回读长度和 SHA-256。
+- 先写 `ArchiveVerified` 收据，再条件删除，再回读为零，最后标记 `Committed`。
+- `Extension` 模式由 `mci-log-archive-extension` 处理；法律保留不能删除。
+
+## 资产、协作和变更集
+
+- `mci-asset-publish` 使用 `microi.asset.v1`，声明 Component、Props、Setters、DataAdapters、Platforms、DependencyPackages。
+- 校验语义版本范围、缺失依赖、循环、最大深度、规范化摘要、DryRun 和 CAS。
+- `mci-asset-resolve` 验证内容 Hash，返回 `ResolvedDependencies/DependencyGraph/LoadOrder`。
+- `mci-collaboration-lease` 使用共享租约和 fencing token；旧编辑者不能保存。
+- `mci-change-set-validate` 检查资源、PlanHash、生产证据和回滚计划。
+- Page JSON ↔ Vue SFC 只处理平台生成的受控标记，不执行任意 Vue/JavaScript，也不承诺任意源码无损反编译。
+
+## 可恢复导入
+
+- `mci-import-plan`：JSON/CSV/Excel 解析、字段元数据校验、文件/计划/行 Hash、公式注入与敏感字段拒绝。
+- `mci-import-stage`：按 ExpectedPlanHash 幂等写暂存行。
+- `mci-import-execute`：必须通过持久后台任务；每片独立提交 Checkpoint/FencingToken。
+- `mci-import-control`：Pause/Resume/Cancel/Retry，使用状态条件更新。
+- `mci-import-rollback`：只恢复当前值仍等于 After 基线的记录；冲突不覆盖。
+
+单批最多 2,000 行。更大数据应拆批或使用专用迁移作业，不提高内存上限硬顶。
+
+## 页面与蓝图版本
+
+页面工具：
+
+```text
+microi_list_page_history
+microi_get_page_history
+microi_compare_page_versions
+microi_export_page_design
+microi_rollback_page_design
+```
+
+蓝图提供对应的历史、读取、比较、导出和回滚工具。修改前读取 CurrentHash，保存传 ExpectedHash，写后回读新 Hash 与不可变历史。回滚创建新版本，不删除旧历史。
+
+## 应用商城发布
+
+- 官方发布使用绑定 `https://api.itdos.com`、`OsClient=iTdos` 的 `microi_itdos`。
+- 先构建 Manifest、22 项应用契约、微服务类型检查/契约/生产构建。
+- 发布请求版本、资产准备版本和包内 `PackageInfo.Version` 必须精确相同；42 个菜单、40 张治理表和 64 个接口引擎的选择必须来自当前包正文。
+- 包内 `ResourcePolicies.ApiEngines` 必须精确为 57 个 Managed + 7 个 CreateIfMissing。
+- 发布后独立回读应用版本、状态、包内容、45 表/873 字段、42 菜单（含已绑定 `/overview` 的治理工作台）、64 接口、任务、10 路由和构建资产 Hash。
+- 定时任务必须在 `PostSchema` 后通过独立 `ScheduleJobs` checkpoint 安装并回读；成功版本只能在任务阶段之后写入。
+- 官方发布源禁止自安装和 `ValidateOnly`；发布源做精确包回读，安装验证在非官方目标租户或本地非发布源环境完成。
+- 目标安装/更新后再次回读，并做管理员 PC/390px 浏览器冒烟。
+- 商城发布不等于生产 API/Web 容器部署。
+
+## 双节点与浏览器验收
+
+至少覆盖：
+
+- 两节点同时心跳、同一策略解析、同一限流窗口和熔断半开；
+- 同一发布幂等键并发执行、租约竞争、步骤失败、台账提交前中断、同键续跑与回滚；
+- Redis/MongoDB 短暂故障、锁持有者退出、重复消息和滚动版本共存；
+- PC 10 路由、失败态、空态、重复动作；390×844 下移动导航、对话框、表单和无整页横向溢出；
+- 页面源码桥、资产依赖循环、协作旧 fencing、导入暂停/恢复和条件回滚。
+
+最终报告必须分别列出源码/测试、远端写入、真实浏览器、应用商城、正式发布和生产部署证据；没有执行的层不能声称通过。

package/skills/app-store/SKILL.md

@@ -40,11 +40,12 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 1. 校验签名/哈希、包版本、平台兼容性、依赖和磁盘/配额。
 2. 创建全局唯一 `InstallationId` 和稳定幂等键。
-3. 使用后台任务执行，阶段性持久化进度与 checkpoint。
-4. 按 Manifest 差异创建缺失资源；已有资源只更新包拥有且允许升级的属性。
-5. 写入成功后刷新共享缓存版本。
-6. 回读表、字段、引擎、菜单、权限、页面等关键资源。
-7. 做 HTTP、UI 和权限冒烟；成功后标记安装版本。
+3. 使用后台任务执行，阶段性持久化进度与 checkpoint。
+4. 按 Manifest 差异创建缺失资源；已有资源只更新包拥有且允许升级的属性。
+5. `PostSchema` 完成后，在独立 `ScheduleJobs` checkpoint 中幂等安装定时任务并回读 Quartz 运行元数据。
+6. 写入成功后刷新共享缓存版本。
+7. 回读表、字段、引擎、菜单、权限、页面、定时任务等关键资源。
+8. 做 HTTP、UI 和权限冒烟；全部成功后才标记安装版本。
 
 安装中断后从 checkpoint 幂等恢复；不能依赖当前 API 节点内存。
 
@@ -52,6 +53,7 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 - 商城定义、安装、升级、卸载和应用源码只允许 `Level >= 9999`。
 - “吾码官方平台”不能只按 `OsClient`、域名或前端变量判断：服务端必须同时校验官方 `OsClient`，并确认当前节点固定只读挂载 `/app/microi_private.pem` 的公钥部分与内嵌官方 License 信任根匹配；本地源码开发可从私有子仓库兼容查找。任意自建私钥不能建立官方身份。官方平台前端隐藏安装、更新、重新安装、离线安装和批量安装入口，后端仍必须拒绝这些写操作。
+- 官方平台是应用发布源，连安装器的 `ValidateOnly` 也必须拒绝，避免通过“只验证”绕过发布源隔离。发布源只做包正文、版本和资产 Hash 回读；真实安装、更新及预检必须切换到非官方目标租户或本地非发布源环境。
 - 所有资源按目标 `OsClient` 写入；包内不能携带源租户 `OsClient`、数据库、Redis、对象存储、MQ/MQTT、AI 或第三方密钥。
 - 按钮调用后台安装接口时，前端只传应用/版本/安装 Id；目标租户和管理员身份由 Token 确定。
 - 每次安装、更新、重新安装生成稳定 `OperationId`。官方计数服务用共享数据库事件表唯一约束去重，并在同一事务内登记事件和递增 `InstallCount`；重试、跨节点和响应丢失不得重复计数。
@@ -59,7 +61,14 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 - 必须随所有后端版本自动落地的平台基础能力，仍要封装成受信任的官方 Platform 应用包，再由升级器调用统一 `import-microi-store-package` 幂等导入；禁止把表、字段、页面或微服务复制成定制 C# 迁移。身份验证、登录方式、个人中心与租户系统设置使用 `app.microi.saas-engine.json`：携带 `mci_system_setting`、`mci_user_external_identity`、默认设置和 `microi-platform-service`。默认行必须使用 `InsertIfMissing + ConfigKey`，只补缺失，不覆盖 `ValueSource=Tenant` 的租户值或租户后来明确关闭的功能。
 - 批量任务已经以“一个应用”为外层持久化恢复单元。规模可控的小型官方包应在一个事务中完成，避免对同一包体按 8 个字段反复下载、解析和重新排队；超过字段、表、DDL、流程、随包数据或资产安全阈值的大包继续使用内部 checkpoint 分片。热更新发现旧版批量计划不含 `ApplicationType` 时，必须丢弃旧计划并重新盘点，不能继续安装历史计划中的社区应用。
 - MySQL 宽表触发 65,535 字节行内上限时，只允许把不参与索引的 `varchar` 配置列无损提升为 `mediumtext`，并把类型覆盖持久化到后台任务 checkpoint；索引列和非行宽错误必须失败关闭。发布包对长连接串、密钥、回调地址、域名/白名单等字段应直接使用 `mediumtext`，同时更新 `DiyFields` 与建表 DDL，不能长期依赖安装时猜测。
-- 卸载是破坏性操作，必须明确列出将删除/保留的资源、二次确认并优先软删除/归档业务数据。
+- 卸载是破坏性操作，必须明确列出将删除/保留的资源、二次确认并优先软删除/归档业务数据。
+
+## 发布版本与资源选择
+
+- 发布器必须把用户请求的精确版本传给资产准备器，并断言 `RequestedVersion == Prepared.PackageVersion == AppPakcet.PackageInfo.Version`；版本不存在就失败，禁止静默改用最新版本。
+- `SelectMenu`、`SelectTable`、`SelectApiEngine` 必须从当前发布包的显式选择持久化；不能读取商城行上一次保存的选择来决定本次包内容。
+- 发布完成后同时回读商城版本行、包正文和构建资产，逐项核对版本、数量与 SHA-256；任一处漂移即发布失败。
+- `ScheduleJobs` 是一等包资源，必须在 `PostSchema` 之后独立安装、持久化 checkpoint 并回读运行状态；任务失败时不得写入成功版本。
 
 ## MCP 工作流
 

package/skills/business-blueprint/SKILL.md

@@ -37,10 +37,17 @@ description: Microi 业务架构蓝图（System Blueprint）— 设计期系统
 |---|---|---|
 | `microi_get_blueprint_schema` | 读取蓝图协议指南 | 否 |
 | `microi_list_blueprints` | 列出当前 OsClient 所有蓝图 | 否 |
-| `microi_get_blueprint` | 读取单个蓝图（含 BlueprintData） | 否 |
-| `microi_save_blueprint` | 创建或更新蓝图 + 自动写历史 + 重建反向索引 | 是（需 confirmExecution） |
-| `microi_delete_blueprint` | 软删除蓝图 | 是 |
-| `microi_validate_blueprint` | 漂移检测：所有 refs 是否仍存在 | 否 |
+| `microi_get_blueprint` | 读取单个蓝图（含 BlueprintData） | 否 |
+| `microi_list_blueprint_history` | 分页读取不可变历史元数据与当前哈希 | 否 |
+| `microi_get_blueprint_history` | 读取指定历史快照 | 否 |
+| `microi_compare_blueprint_versions` | 结构化比较两个快照或历史与当前草稿 | 否 |
+| `microi_export_blueprint` | 导出 `microi.blueprint.v1` 设计包与稳定哈希 | 否 |
+| `microi_save_blueprint` | 创建或更新蓝图 + 自动写历史 + 重建反向索引 | 是（需 confirmExecution） |
+| `microi_rollback_blueprint` | 带 `ExpectedCurrentHash` 回滚并重建反向索引 | 是（需 confirmExecution） |
+| `microi_delete_blueprint` | 软删除蓝图 | 是 |
+| `microi_validate_blueprint` | 漂移检测：所有 refs 是否仍存在 | 否 |
+
+保存前必须从详情或历史列表取得当前哈希，并把它作为蓝图对象的 `ExpectedCurrentHash`。哈希冲突时先比较版本再合并，不得移除并发保护强行覆盖。回滚会先保存回滚前快照，再在同一事务中恢复目标内容并重建反向索引；历史不会被删除。
 
 ## AI 工作流（强制约定）
 

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

@@ -31,6 +31,8 @@ UniApp 使用 Vue 3 + TypeScript 的官方 Vite 工具链，并同时遵守 `mic
 4. 读取 `microi-frontend-sdk`、`ui-design`；MicroService 再读取 `microi-microservice`，UniApp 再读取 `microi-uniapp-frontend`，游戏或复杂媒体再读取 `ui-design/references/motion-and-media.md`。
 5. 在项目根目录维护 `.microi-micro-app.json`；源码必须位于当前租户的 `Microi-V8-Engine/.../AI应用/{appKey}`，不得跨租户复用目录。
 
+`microi.apps/` 只用于可审计的官方应用商城发行包工程，例如 Manifest、接口引擎、资源策略、安装测试和离线包生成；它不是 Web、UniApp 或 MicroService 的本地源码根。发行包需要包含前端产物或可选源码时，必须从上述当前服务器、当前租户的 `AI应用/{appKey}` 唯一源码构建或打包，禁止在 `microi.apps/{package}/microservice` 再维护一份可编辑副本。
+
 ## 工程边界
 
 - `src/components` 保存可复用展示组件，`src/pages` 保存页面，`src/composables` 保存 UI 用例，`src/domain` 保存纯 TypeScript 业务规则，`src/services` 保存 API/实时通信适配，`src/platform` 保存 Microi 桥接。

package/skills/microi-codex-installer/SKILL.md

@@ -7,7 +7,7 @@ description: 当用户在 Codex、WorkBuddy、CodeBuddy、Qoder、Comate、Trae
 
 本技能负责发现、安装、初始化、升级和诊断 Microi吾码 AI 开发能力。唯一 npm 包为 `@microi.net/cli`；该包同时提供 `microi` CLI、Codex Plugin、WorkBuddy/CodeBuddy 兼容插件清单、完整 Skills 与同源 MCP。正式 marketplace 名称固定为 `microi-net`，插件选择器固定为 `microi@microi-net`，禁止新建 `microi-official` 或第二个 npm 包。
 
-只要本技能已经由 Microi.VSCode、工作区 `microi.skills` 或已安装插件提供，用户说“帮我初始化 Microi吾码插件”时就必须识别该意图，用户不需要再次说出 npm 包名。绝对空白且任何宿主都尚未提供本技能的 AI 会话无法依靠尚未加载的 Skill 自我发现包名；因此冷启动入口统一固化在 VS Code 初始化产物、`@microi.net/cli` 与 Codex Plugin 三处，而不是要求用户记忆第二个包。
+只要本技能已经由 Microi.VSCode、工作区 `microi.skills` 或已安装插件提供，用户说“帮我初始化 Microi吾码插件”时就必须识别该意图，用户不需要再次说出 npm 包名。全新 Codex 与空目录尚未加载任何吾码 Skill 时，用户只需在首次请求中明确 `@microi.net/cli`，例如“通过 `@microi.net/cli` 安装吾码 Codex 插件”；具备终端与网络权限的 AI 必须直接执行本技能中的确定性安装命令。安装完成后，更短的“初始化吾码”“添加服务器/MCP”“拉取全部 V8”均由插件 Skill 自动识别。
 
 ## 自然语言入口规则
 
@@ -37,6 +37,7 @@ codex plugin list
 - marketplace 为 `microi-net`；
 - `microi@microi-net` 显示 `installed, enabled`；
 - 已安装版本等于 CLI 内置 marketplace 的目标版本。
+- 插件路径位于 `microi-net-marketplace/plugins/microi`，且 `.codex-plugin/plugin.json` 的显示名为 `Microi吾码`。
 
 `microi-official` 和 `microi@microi-official` 仅是旧标识，不得写入新文档或新配置；安装器会在新版安装成功后迁移并清理旧标识。
 
@@ -54,6 +55,14 @@ microi codex install --yes
 npx --yes @microi.net/cli@latest codex install --yes
 ```
 
+这条命令把 npm 仅作为下载通道：安装器会将包内完整 Codex Plugin 安全复制到当前用户的 `${CODEX_HOME:-~/.codex}/microi-net-marketplace/plugins/microi`，生成 Codex 官方支持的本地 marketplace，注册 `microi-net`，再安装并启用 `microi@microi-net`。完成并重载后，Codex 的“插件”页面必须显示 **Microi吾码**，来源为 **microi-net**。禁止重新写入 Codex 不支持的 `source: npm` marketplace 条目。
+
+在全新 Codex 的空目录中，以下自然语言属于明确安装授权，必须等价执行上述命令，不得仅生成项目 Skill 后就声称 Codex Plugin 已安装：
+
+```text
+通过 @microi.net/cli@latest 安装吾码 Codex 插件。
+```
+
 `--yes` 只表示当前用户已经授权这次全局修改，不得由 AI 在普通 Microi 对话中自行补上。只有版本不一致且普通安装不能升级、并确认目标 npm 包已经公开可读时，才使用：
 
 ```bash
@@ -135,6 +144,6 @@ CodeBuddy CLI 可把该 `packageRoot` 作为本地 marketplace 添加，再安
 microi codex status --json
 ```
 
-只有返回 `ok: true` 且选择器、状态和版本全部正确，才报告安装完成。随后明确提示用户新建 Codex 任务或重载 Codex；当前已经打开的任务通常不会热加载新增 Skills/MCP。
+只有返回 `ok: true` 且选择器、状态和版本全部正确，才报告安装完成；必要时再用 `codex plugin list` 核对路径。随后明确提示用户新建 Codex 任务或重载 Codex；当前已经打开的任务通常不会热加载新增 Skills/MCP，桌面端插件页面也可能需要重载后刷新。
 
 若 npm 返回 `E404`，说明 `@microi.net/cli` 的目标版本尚未公开或仍在传播。不得删除仍可用的旧插件、不得重复发布同一不可变版本，也不得声称安装成功。

package/skills/microi-deployment/SKILL.md

@@ -9,6 +9,8 @@ description: Microi 安装、部署、升级和本地运行指南。用于 Docke
 版本、端口和命令可能变化，执行前必须回读当前中文官网、仓库 compose/配置和目标
 主机状态，不能把旧示例当作当前生产事实。
 
+数据库备份 MCP 使用 `microi_list_database_backup_tenants` 盘点可备份租户，使用 `microi_run_database_backup` 提交带稳定幂等键的持久化任务。备份必须进入共享存储并回读文件大小、哈希和任务终态；本机进程返回成功不等于备份可恢复。
+
 ## 必读参考
 
 - 部署方式、依赖、配置和验收矩阵：`references/deployment-matrix.md`

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

@@ -39,6 +39,22 @@ V8 函数”或新增、调整官方中文文档时，使用本 Skill。
 6. 对每个新增或改动的 Skill 运行 `skill-creator` 的 `quick_validate.py`，
    再执行 `git diff --check` 和相对链接检查。
 
+## 中文文档视觉与可读性契约（强制）
+
+文档正确但密密麻麻仍属于未完成。修改 `microi.doc/docs/doc/**/*.md` 时同时遵守：
+
+- 正文使用清晰的 H1/H2/H3 层级和 80–90 字符左右的阅读宽度；连续长段落拆为短段、列表、对比表、步骤、流程或有语义的卡片。不要为了“丰富”把每句话都做成卡片。
+- 首屏先回答“这是什么、有什么价值、怎么选择”，再展开原理和完整参数；长篇高级细节可使用可访问的 `details/summary` 渐进披露。
+- 三个以上可比较能力优先使用表格或网格卡片；三步以上的依赖流程优先使用流程图/步骤带。图标必须帮助辨识，不能只作装饰噪声。
+- 颜色至少区分主能力、成功、警告、风险，但正文对比度必须满足易读要求；不能只靠颜色表达状态。亮色、暗色、窄屏和 `prefers-reduced-motion` 都要有样式。
+- 真实案例截图进入 `docs/public/images/...`，使用稳定英文文件名、有效 `alt` 和简短图注；图片不得代替关键文字说明，移动端不得横向撑破页面。
+- 整站共同规则优先落在 VitePress 主题层 `mci-site.scss` / `doc-readable.scss`，页面独有展示放独立 SCSS；禁止为几十篇 Markdown 机械复制内联 `<style>`。
+- 新页面可复用 `.mci-doc-grid`、`.mci-doc-card`、`.mci-doc-chip`；产品页需要独立视觉时使用页面 marker + `body:has(...)` 限定作用域，不能污染登录页、首页或英文生成页。
+- 改动后运行 `npm run check:readability` 与 `npm run check:content`，再在真实浏览器至少检查一个桌面宽度和一个移动宽度，覆盖亮/暗主题、代码块、表格、图片、侧栏与锚点。
+- `microi.doc/docs/en/` 由脚本生成，不手工同步样式化内容；日常文档工作继续禁止修改 `about/update-log.md`。
+
+自动可读性检查只能阻止缺少 H1、超长连续文字块或整站主题契约丢失，不能证明页面真正好看。最终仍要查看渲染结果，不能用构建成功替代视觉验收。
+
 ## 自动审计能证明什么
 
 脚本验证：

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

@@ -18,8 +18,10 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `form-engine/model-engine.md` | v8-template-engine | 表格/表单模板 |
 | `getting-started/docker-run.md` | microi-deployment | Docker 部署与验收 |
 | `getting-started/local-run.md` | microi-deployment | 源码本地运行 |
+| `getting-started/source-code-architecture.md` | workspace-conventions, microi-system-delivery | 多仓源码边界、模块地图和修改路由 |
 | `getting-started/start-use.md` | microi-system-delivery, module-engine | 快速使用和首个模块 |
 | `getting-started/win-install-microi.md` | microi-deployment | Windows 部署 |
+| `edition-comparison.md` | microi-system-delivery | 信息型页面；版本授权、续费边界和选型建议 |
 | `index.md` | microi-system-delivery | 产品能力总览和知识路由 |
 | `more/copy-module.md` | module-engine, app-store | 模块复制、迁移和依赖 |
 | `more/db-dictionary.md` | microi-db-schema | 核心表和字段归属 |
@@ -31,11 +33,14 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `more/security.md` | v8-security | 平台安全和兼容基线 |
 | `more/sys-config.md` | v8-utilities, microi-deployment | 系统/租户配置和敏感边界 |
 | `system-engine/ai-engine.md` | ai-engine, v8-http-integration, microi-ai-application | 模型代理、License、V8.AI、MCP 对话、跨端调用和安全 |
+| `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/app-store.md` | app-store | 应用包、安装、升级和回滚 |
 | `system-engine/databases.md` | dos-orm, v8-sql-query, microi-deployment | 扩展数据库与迁移 |
 | `system-engine/datasource-engine.md` | datasource-engine | 数据源定义、执行和供数 |
 | `system-engine/job.md` | job-engine | 调度、后台任务和分布式恢复 |
 | `system-engine/micro-app.md` | microi-microservice, microi-ai-application | 微服务/AI 前端应用的工程架构与交付 |
+| `system-engine/multi-end-client.md` | microi-client-frontend, microi-mobile-app-quality, microi-uniapp-frontend | PC、WebOS、移动自适应、UniApp 与 App 边界 |
 | `system-engine/microi-ui.md` | microi-ui | Microi.UI 组件和主题 |
 | `system-engine/message-notification.md` | message-notification | 平台内部消息、SignalR 与多通道通知 |
 | `system-engine/module-engine.md` | module-engine, v8-menu-buttons, v8-template-engine, microi-mobile-app-quality | 菜单统计、模块指标、复合列、移动卡片、按钮角标和页面入口 |
@@ -48,11 +53,13 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `system-engine/search-engine.md` | search-engine | Elasticsearch 索引和查询 |
 | `system-engine/spider-engine.md` | spider-engine | 浏览器采集和 Worker |
 | `system-engine/translate-engine.md` | translate-engine | 多语言与翻译供应商 |
+| `system-engine/visualization-engine.md` | page-engine, microi-ui | 3D、CAD、goView 与数据大屏能力边界 |
 | `system-engine/wf-engine.md` | v8-workflow | 工作流设计和事件 |
 | `v8-engine/ai-apiengine.md` | ai-engine, v8-api-config | AI 辅助接口引擎开发 |
 | `v8-engine/api-engine.md` | v8-api-config, v8-utilities | 接口上下文、配置和调用 |
 | `v8-engine/apiengine-index.md` | v8-crud-api, v8-api-config | 接口引擎实战和规范 |
 | `v8-engine/form-engine.md` | v8-crud-api, v8-formengine-http | FormEngine API 与 HTTP |
+| `v8-engine/mcp-server.md` | microi-system-delivery, microi-codex-installer, v8-security | MCP 工具、确认、审计、文件、日志、备份与访问密钥 |
 | `v8-engine/v8-client.md` | v8-utilities, v8-frontend-events, v8-http-integration, v8-security, ai-engine, print-engine | 全部前端 V8、平台 AI、强身份验证、扫码和蓝牙打印 |
 | `v8-engine/v8-server.md` | v8-utilities, v8-api-config, v8-http-integration, v8-security, ai-engine | 全部后端 V8、强身份票据、平台 AI 和专项路由 |
 | `v8-engine/vs-code-plugin.md` | v8-explorer-tree, microi-client-frontend, workspace-conventions | VS Code 插件、Microi CLI、AI/MCP 初始化、类型、资源树和共享工作区 |

package/skills/microi-form-engine/SKILL.md

@@ -83,8 +83,10 @@ MCP 建模只使用：
 - 语义仍不明确时必须在任何 MCP 写入前询问基数；禁止静默退化为 `JoinForm`。
 - 禁止把“明细”设计为主表 `XxxId + JoinForm`；禁止让 `JoinForm.TableId/TableName`
   指向当前表；禁止把 1:N 外键放在主表。
-- MCP 的组件枚举、Manifest 结构检查或 `dryRun` 即使通过，也不代表关系基数正确；AI 必须
-  单独执行本节语义门禁。
+- 完整系统 Manifest 中，`JoinForm` / `TableChild` 字段必须声明 `relation.cardinality`；
+  `microi_plan_system` 与 `microi_generate_system` 会在任何写入前执行本节门禁。直接调用
+  `microi_add_field` / `microi_update_field` 时，后端仍会校验目标表、主/子外键、隐藏菜单
+  和子表索引，不能靠绕过 Manifest 写入未初始化配置。
 
 示例：
 
@@ -100,9 +102,27 @@ MCP 建模只使用：
    `tables[].indexes`，并以 `microi_get_table_indexes` 回读。
 3. 为子表创建绑定其 `diyTableId` 的隐藏 CRUD 菜单：`Display=0`、`AppDisplay=0`、
    `HasChild=0`。
-4. 回读真实的子表 `diy_table.Id`、子菜单 `sys_menu.Id` 与子表外键名后，再在主表
-   新增/更新 `Component=TableChild`、`FormWidth=24` 的配置字段。工具还不能在一次
-   Manifest 中解析这些新建 Id 时，必须分两阶段执行；禁止编造 Id 或改用 `JoinForm`。
+4. 在完整系统 Manifest 的主表字段声明：
+
+   ```json
+   {
+     "name": "Items",
+     "label": "明细",
+     "component": "TableChild",
+     "formWidth": 24,
+     "relation": {
+       "cardinality": "1:N",
+       "targetTable": "Biz_OrderItem",
+       "childForeignKey": "OrderId",
+       "childModule": "订单明细（隐藏）",
+       "primaryTableFieldName": "Id"
+     }
+   }
+   ```
+
+   `microi_generate_system` 会先创建全部表与普通字段，再创建隐藏菜单，最后回读并写入
+   当前租户真实的 `diy_table.Id` / `sys_menu.Id`。禁止在 Manifest 中编造这些 Id，禁止
+   因依赖尚未创建而退化成 `JoinForm`。
 5. `TableChild` 控件字段通常只是表单配置位，关系事实存放在子表外键。至少保存：
 
 ```json

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

@@ -101,6 +101,16 @@ export async function login(account, pwd, captcha = {}) {
 }
 ```
 
+### MicroService 独立运行认证（强制）
+
+AI 生成的前端微服务不能假定永远在主平台 iframe/micro-app 宿主中运行：
+
+- `window.microApp` 存在且宿主下发 Token 时，直接配置同一个 SDK 实例并进入业务页，不重复显示登录。
+- 独立访问时从 `.microi-micro-app.json`/构建配置取得 `apiBase` 与 `osClient`，先复用 SDK 已保存的有效 Token；无 Token 时显示平台帐号密码登录。
+- 初始化必须调用 `V8.GetSysConfig(true)` 并按 `EnableCaptcha` 动态决定验证码。验证码接口固定为 `GET /api/Captcha/GetCaptcha`，响应头读取 `captchaid`；只有启用时才向 `V8.Login` 追加 `_CaptchaId/_CaptchaValue`。
+- 登录仍签发平台 DiyToken，不创建平行 Token、平行用户表或微服务自有密码体系。失效事件回到登录态，Token 续签仍按本 Skill 的单实例规则处理。
+- 宿主额外传入 `permissionContext={sysMenuId,moduleEngineKey,diyTableId}`。SDK/服务层需要访问 FormEngine 时使用真实授权 `moduleEngineKey`；该对象不能代替后端权限，也不能成为放宽匿名接口的理由。
+
 ## 请求头规则
 
 SDK 的 `buildHeaders` 必须集中处理所有请求头，不能让页面、业务 wrapper 或上传逻辑各自拼接租户和鉴权头。