@microi.net/cli 5.7.1 → 5.7.4

package/skills/.progressive-disclosure-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-09-26T07:03:07.851Z",
+  "generatedAt": "2026-09-27T10:57:40.650Z",
   "policy": {
     "maxEntryLines": 285,
     "referenceBudgetLines": 245,
@@ -407,11 +407,11 @@
       ]
     },
     "microi-frontend-sdk": {
-      "originalSha256": "51f49270e1c65e57ff785b304fdfc32c5578c34d9b69053b0dc361566fb94837",
-      "originalLines": 318,
+      "originalSha256": "256ba9493067a250746ec027b1852d80b2dbe12577961816f839854f5bb25390",
+      "originalLines": 321,
       "prefixSha256": "5ee94a9174a22577011c64f29a93f6983c8450d471d26f12fa884d7c4b3a879a",
       "prefixBytes": 895,
-      "entryLines": 191,
+      "entryLines": 195,
       "chunks": [
         {
           "id": "microi-frontend-sdk-000",
@@ -433,8 +433,8 @@
           "id": "microi-frontend-sdk-002",
           "ordinal": 2,
           "destination": "microi-frontend-sdk/SKILL.md",
-          "sha256": "c514dbf966c96102ea04cdf6f967814f2babe74fceaaee6c1f771d351bfdb8eb",
-          "lines": 48,
+          "sha256": "7e624a3f79211435570dab7a9f4981b1bcccd73d1da5981a53c97fd1e498e007",
+          "lines": 50,
           "heading": "登录与验证码封装"
         },
         {
@@ -465,8 +465,8 @@
           "id": "microi-frontend-sdk-006",
           "ordinal": 4,
           "destination": "microi-frontend-sdk/references/progressive-01-token-当前登录用户与当前终端登录协议.md",
-          "sha256": "85694df371b7b889b5bf4aea5bc98d604232eb5c7b88b8a0eae8a26d70877009",
-          "lines": 80,
+          "sha256": "6f779d619a24b1c03fb02efbc4bc25d41ce3254dbfbf1c63af137dcd9a45790b",
+          "lines": 81,
           "heading": "Token、当前登录用户与当前终端登录协议"
         },
         {
@@ -2221,8 +2221,8 @@
       ]
     },
     "v8-file-upload": {
-      "originalSha256": "6e5cb8613552e485a6552539daf61cbc3fccb0da30393ebb16ff9bdd31544885",
-      "originalLines": 602,
+      "originalSha256": "e186e90a39840877322425a1c8f3fec8178489d92653ef387879ae244e0edab7",
+      "originalLines": 614,
       "prefixSha256": "761e74738e41d472349122770c59a31a86ca8900d9a4470b5aa912b9863382a1",
       "prefixBytes": 13304,
       "entryLines": 257,
@@ -2295,16 +2295,16 @@
           "id": "v8-file-upload-008",
           "ordinal": 8,
           "destination": "v8-file-upload/references/progressive-02-office-文件在线编辑版本号规则.md",
-          "sha256": "7cda0fe7bb978e7219cb3c1ba30813e1a5e777f1272410f85d4c7ecc1882cc3d",
-          "lines": 36,
+          "sha256": "b7b809862a9d82f0270ae99486acb5fe23185b9d5efad073ae39b282724e2e32",
+          "lines": 46,
           "heading": "Office 文件在线编辑版本号规则"
         },
         {
           "id": "v8-file-upload-009",
           "ordinal": 9,
           "destination": "v8-file-upload/references/progressive-02-office-文件在线编辑版本号规则.md",
-          "sha256": "e01219d4f1a8f8c535e0b5aa5620120c37bd5e79af27dbbd63babda8d887cd13",
-          "lines": 80,
+          "sha256": "1cc3ff1b6a5c756d957819f198c13ea181143db484527d1931aefc8e0d52993c",
+          "lines": 82,
           "heading": "ImgUpload / FileUpload 字段值兼容规则"
         },
         {
@@ -2928,11 +2928,11 @@
       ]
     },
     "v8-table-event": {
-      "originalSha256": "1af0a6924ace1532e8121345555de42efd0af5d9cb9fa3a92ea4ade80c26a7e4",
-      "originalLines": 395,
+      "originalSha256": "96d0b4c481a4432a8b8d0b0ba0cedb6a23ee23b3066c854201076d60dd2a3a1c",
+      "originalLines": 397,
       "prefixSha256": "de1f151904fd00a31a3c680c26bdb1d9c1a210193193e8bfefb5dc68f4c2bc02",
       "prefixBytes": 717,
-      "entryLines": 175,
+      "entryLines": 177,
       "chunks": [
         {
           "id": "v8-table-event-000",
@@ -2962,8 +2962,8 @@
           "id": "v8-table-event-003",
           "ordinal": 3,
           "destination": "v8-table-event/SKILL.md",
-          "sha256": "5140cd224fd5ac044715f0b3ac79d18f8816d4ce36b6c05cc04e044dbf956214",
-          "lines": 49,
+          "sha256": "a6313d9007c8c72e1b8fb56ca7764eb0856029c9937c35d5f2e294539b3c7134",
+          "lines": 51,
           "heading": "⚠️ 关键陷阱（必读）"
         },
         {

package/skills/ai-engine/SKILL.md

@@ -1,17 +1,37 @@
 ---
 name: ai-engine
-description: Microi AI 引擎、MiniMax 图片/音乐/视频生成与预览、模型代理、NL2SQL/NL2V8 和知识库规范。用于媒体生成、模型路由、密钥与订阅配额、Schema/Skill 检索、流式响应、租户隔离和验收。
+description: Microi AI 引擎、MiniMax 图片/音乐/视频生成与预览、自建数字人直播、模型代理、NL2SQL/NL2V8 和知识库规范。用于媒体生成、本机免费推理、模型路由、密钥与订阅配额、Schema/Skill 检索、流式响应、租户隔离和验收。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
-# Microi AI Engine
+# Microi AI Engine
+
+涉及 AI 员工、多岗位协作或 OpenClaw 执行节点时，读取
+[AI 员工与执行节点](references/ai-employees.md)。先区分职责、持久任务、真实工具权限与人工验收，不能把聊天提示词或设计蓝图当作已经运行的员工系统。
+
+### AI 员工的最小执行约束
+
+以下关键规则同时进入后端内嵌知识快照，详细案例留在上述参考文件：
+
+- DiyToken 决定租户与负责人；岗位不等于管理员帐号。任务、依赖、成果、报告和验收均校验同一数据范围，原生 CRUD 不能绕过状态机。
+- 先从当前用户获授权目录选择 `AiModel / AiModelId`，不能假定模型名可留空；显式模型不可用就失败，不静默切换账号。
+- 持久后台任务先领取并提交，再调用外部模型；组合稳定幂等键、数据库条件写入、租约与独立调用开始标记。等待模型时不持有业务行锁，结果未知不盲目重发。
+- OpenClaw 必须核对安装版本与实际配置格式，显式指定 Agent；按租户、负责人、任务和尝试隔离目录与会话，不回退 `main`。Gateway 密钥只留在本机服务端。
+- 草稿模式检查真实工具拒绝策略；提示词不是权限隔离。扩大工具权限必须逐项建立白名单、审批、幂等、目录/网络边界和副作用回读。
+- 报告超时重放相同成果，取消或旧租约的迟到结果不得改写任务。供应商用量缺失显示未知，尝试次数不等于金额预算。
+- OpenClaw Gateway 的模型输出只接受绑定本次执行的明确终稿区间；推理草稿不得进入成果。缺少终稿标记时保持结果未知并人工核对，不用猜测文本边界。
+- 模型成功、后台任务成功与人工验收通过分别取证；财务、招聘、研发、测试和营销草稿不能冒充付款、录用、部署、测试通过或发布。
 
 平台媒体生成的受控 HTTP 入口包括 `/api/Ai/`、`/api/Ai/GenerateMiniMaxImage`、`/api/Ai/GenerateMiniMaxMusic`、`/api/Ai/CreateMiniMaxVideo`、`/api/Ai/GetMiniMaxVideoTask`、`/api/Ai/GetMiniMaxVideoFile`、`/api/Ai/PersistMiniMaxVideoFile` 和恢复原任务的 `/api/Ai/RecoverMiniMaxImageTask`；AI 工作流统一调用 Managed 接口引擎 `/apiengine/platform-ai-workflow`，通过 `Action` 选择概览、节点详情、生成、列表、读取、保存或删除。调用方只提交业务参数和模型选择，供应商密钥、租户配额、任务归属和文件读取权限由服务端判定。生成结果必须先进入当前租户 HDFS 或受控临时句柄，浏览器不接触供应商密钥、图片 Base64、音频十六进制或原始视频任务 Id。`PersistMiniMaxVideoFile` 只能转存当前登录用户所属且已完成的任务，禁止作为任意 URL 搬运器。
 
-## 能力
-
-### 媒体模型目录与中转（2026-09）
+## 能力
+
+### 自建数字人直播与免费本机推理
+
+需求涉及“数字人直播、本机部署、免费模型、不要扣 token、MuseTalk、LiveTalking、OBS”时，先读取 [自建数字人交付规范](references/self-hosted-digital-human.md)。免费指无供应商推理账单，不得把云端试用、Edge TTS 或其它在线服务冒充离线方案；必须分别验证吾码业务资源、本机推理、音画输出和外部平台开播。
+
+### 媒体模型目录与中转（2026-09）
 
 - 媒体选择以当前租户 `mic_ai.Id` 和实际媒体 `Model` 为准，图片、音乐、视频及配音请求携带 `AiModelId`。显式记录不可用时不得静默切换其它账号、主租户密钥或聊天模型。
 - `MediaProtocol` 与 `MediaModels` 由 AI助手应用包交付。目录项为 `{ Id, Name, Capability, Protocol }`，能力支持 `image/music/video/speech`；协议与模型名称分离，未知协议明确不可选。新增供应商协议仍须真实后端适配器和契约测试，不能只改模型名称。

package/skills/ai-engine/references/ai-employees.md

@@ -0,0 +1,42 @@
+# AI 员工与执行节点
+
+用于将岗位、任务、执行、成果和验收组织成可交付应用。优先使用低代码表与受管接口引擎；缺少可信运行时原子时才扩展后端。
+
+## 组织与任务
+
+- 员工有职责、交付标准、模型、能力和状态；创建岗位不等于创建管理员帐号。
+- 任务明确目标、输入、验收标准、前置依赖、负责人和执行方式。只有已验收成果可被后续任务引用；自动接力必须由真实实现证明。
+- 数据库保存任务、执行批次、成果哈希和审计。本地 JSON、聊天记录和内存定时器不能作为跨节点任务事实源。
+- 当前 DiyToken 决定租户和负责人，忽略客户端身份字段。列表、详情、依赖、写入、报告均校验同一数据范围；前端隐藏字段不是授权。
+- 原生 CRUD 不得绕过任务状态机或伪造审批。执行者只能报告有效尝试，不能替负责人验收。
+
+## 模型与持久执行
+
+后端 `V8.AI.Chat` 的 `AiModel` 不能假定可留空。先从当前用户获授权的目录选择 `AiModel / AiModelId`；显式模型不可用时失败，不能静默切换账号。Key 与 Endpoint 保留在可信后端。
+
+长调用通过平台持久后台任务执行。领取先提交，再调用外部模型；组合稳定幂等键、数据库条件写入、租约和旧执行者拒绝。调用无法回滚时，独立保存开始标记；重启后结果未知就核对，不盲目重发。等待模型时不能持有业务行锁。
+
+远端通过 `microi_run_engine_background` 入队，使用 `microi_list_background_tasks` 看运行状态，同时回读任务与成果。TaskId、后台 Succeeded、生成成功、业务验收通过是不同证据。
+
+实际用量只来自供应商或平台计量，缺失则显示未知。尝试次数不是 Token 或金额预算。
+
+## OpenClaw 适配
+
+先核对安装版本和官方协议。旧版使用 `agents.list`，其他版本可能使用 `agents.entries`；两者并存或格式未知时报错，不能猜测迁移。
+
+- 显式指定 Agent，并按租户、负责人、任务、尝试建立会话键；不回退 `main`。
+- 每个负责人/岗位使用独立 workspace 与 agentDir，拒绝路径越界与符号链接，不共享不同身份的凭据目录。
+- Gateway HTTP 凭据具有管理范围权限，只留在本机服务端。目录隔离不等于系统隔离，不可信租户应使用独立 Gateway、系统用户或容器。
+- 草稿型员工可要求真实 `tools.deny` 包含 `*`。扩大为工具执行时，逐项增加授权、能力白名单、目录/网络边界、审批和副作用回读。提示词过滤不是沙箱。
+- 节点只领取已授权任务，续租失败或取消时停止后续工作。报告超时重放同一报告，不重新生成；未知结果不自动重试。
+- Gateway 使用当前版本 OpenClaw 所要求的 Node.js 运行时；例如 `2026.3.11` 要求 Node.js `>=22.12.0`。管理页面可访问不证明 Gateway 已启动。
+- MiniMax 等模型可能在 `message.content` 中混入推理或写作计划。用按任务、尝试生成的唯一终稿标记限定可回传正文；标记缺失、重复、错序或正文为空时失败关闭并人工核对，不按英文前缀、Markdown 标题或关键词猜测截断位置。
+- 准备配置只新增声明资源，保存前复核原配置，保留默认 Agent、密钥和并行修改。重启 Gateway 与发布新版客户端是独立动作。
+
+## 验收与边界
+
+覆盖幂等去重与内容冲突、负责人隔离、依赖未验收、同员工并发、旧租约报告、取消后迟到结果、退回后的独立成果、尝试上限、报告网络失败和进程重启。
+
+财务、招聘、合同、营销和客服草稿不代表已付款、录用、签署或发送。测试计划与代码草稿不代表测试通过；实际完成需要执行日志、产物与独立回读。
+
+分别报告云端应用、桌面源码/构建、安装包发行、真实 Gateway 联调以及官网源码/部署；任一项通过不能替代其他层。

package/skills/ai-engine/references/self-hosted-digital-human.md

@@ -0,0 +1,45 @@
+# 自建数字人直播交付规范
+
+## 先确定运行边界
+
+用户要求免费、自建、不扣 token 时，默认采用用户自己的推理设备。模型仍处理 token，但本机计算没有供应商按次账单；硬件、电费、存储和吾码自身部署成本不能省略。禁止静默使用 MiniMax、吾码中转、Edge TTS、ZeroGPU 或在线试用作为本地推理成功的证据。
+
+先盘点当前 MCP 的在线应用和实时 Schema，再读取目标应用源码。吾码负责话术、知识、角色、任务和记录，媒体运行时负责模型与音画。已有适合应用时扩展其页面，没有才创建 MicroService。业务表、字段、菜单和权限由 Manifest/应用包交付，不为数字人业务新增平台 Controller。
+
+Windows 本机参考方案可采用 CPU 运行轻量 Qwen 与中文 TTS、CUDA 运行口型模型，并通过 WebRTC 向浏览器或 OBS 输出。若实现先生成片段再播报，应如实标注缓冲策略，不应描述成低延迟全双工数字人。输出帧率、模型生成帧率、首音延迟和总等待时间必须分开报告。
+
+## 资源与模型
+
+- 检查当前显卡、可用显存、内存、磁盘、已有进程和端口。不得为了腾显存结束未知进程。使用应用自己的 Python 环境，不修改共享环境。
+- Windows 中文工作区中，部分原生 TTS / OpenCV 文件接口无法打开包含中文的绝对路径；优先在确定的运行目录中使用相对路径，并真实测试人像检测、语音生成与启动脚本，不能只测 Python 文件读取。
+- 大文件固定官方仓库 revision、预期大小和 SHA-256；分段下载校验 Content-Range，支持原任务续传，下载完成后再加载。不把失败下载或仅安装依赖计为推理通过。
+- 模型运行使用 `local_files_only` 和离线模式，无付费回退。运行时清除本进程继承的 HTTP/HTTPS/ALL proxy，避免本地代理成为外网旁路；随后限制外连。安装下载是独立过程，不全局修改用户代理。
+- 权重许可、代码许可、人像/声音的使用权分别核对。研究测试素材仅用于本地研究验证，不放进公开应用包或默认当商业主播素材。
+- 低端设备可以先合成片段、缓冲后播放；必须把该策略写入 UI 和文档。不能用静态图循环、音量驱动嘴型或测试桩冒充神经网络口型模型已经运行。
+
+## 本机配对与吾码会话
+
+- DiyToken 仍是吾码身份与权限入口。数据请求使用平台 SDK、当前租户和真实模块权限；不要把 DiyToken 发往本机模型或其它第三方。
+- 若旧节点的 MCP 模块更新白名单不支持 ModuleEngineKey，不能以接口成功代替字段回读。可通过已有平台授权菜单接口的窄字段投影解析当前租户真实菜单 Id，携带 `_SysMenuId` 调用 FormEngine；不能写死发行租户 Id、放宽表权限或绕过标准 MCP 写入。
+- 本机运行时只监听回环地址，另用随机配对码换取有期限、绑定 Origin 的本机会话。配对码、内部模型密钥和访问会话不出现在 URL、云端业务列或日志中。
+- CORS 使用精确 Origin 列表，同时校验 Host；需要浏览器本地网络权限时明确给出诊断，不以通配 CORS 或绑定公网地址规避限制。
+- 前端不开放任意 Endpoint、文件路径、命令、RTMP shell 参数或 Python 代码。模型输出只是待播报文本，不能执行 V8、SQL 或操作业务数据。
+- 请求使用稳定 requestId；相同请求返回原任务，参数改变则拒绝。队列有界、停止可见、失败可诊断；状态与文件回读一致后才标为完成。
+
+## 源码交付
+
+- `.gitignore` 不等于 MCP 源码同步排除。必须在 `.microi-micro-app.json` 显式声明 `SourceExcludes`，排除虚拟环境、模型、凭据、人像、生成媒体、缓存和本机运行日志。
+- 运行时源码、固定依赖、模型 lock、安装/启动/停止脚本和测试进入私有源码；编译产物进入公有运行目录。应用包不得带发布者的配对码或设备配置。
+- 官网完整交付文档维护在独立菜单 `microi.doc/docs/doc/system-engine/digital-human-live.md`；`ai-engine.md` 的 `self-hosted-digital-human-live` 锚点保留入口链接。功能截图从真实页面组件采集并检查原始像素；使用隔离示例数据时必须在图内和文案中明确标注，不能把它称作线上租户数据或真实开播效果。
+- MCP 已有应用发现、Manifest、元数据、源码同步和 v3 发布能力时直接复用，不为重复流程新增工具。交付记录明确四项状态：应用包、官网源码、Skills、MCP 复用/变更。
+
+## 验收
+
+1. 用 MCP 计划、dry-run、写入、结构回读，并验证业务新增/读取/修改/删除及权限拒绝。
+2. 真模型生成中文音频，检测非静音、采样率与时长；真实口型模型生成帧，检查嘴部变化和图像输出。
+3. 音频与视频探针校验时长、帧率、画面尺寸；WebRTC 接收者实际收到音视频，并检查浏览器播放。
+4. 测试错误配对码、未授权请求、非白名单 Origin、请求重放冲突、队列上限、停止、模型缺失与外网拒绝。安全测试桩与真实模型验收分别记录。
+5. 桌面/窄屏/深色界面、空态、失败态、素材 CRUD、菜单生命周期与输出页实际操作通过。
+6. OBS 捕获和外部平台开播独立验收。OBS“媒体来源”循环播放已生成 MP4，只证明片段可被 OBS 录制；浏览器来源需要确认配对面板消失、服务端 WebRTC `peers` 大于 0，且 OBS 录制回读有真实音画，才能判为实时接入。未提供直播账号、推流地址或密钥时完成本机输出，明确外部直播未验证，不请求无关账号，不伪造“已开播”。
+
+验收报告保留应用版本、模型 revision、真实设备、内存/显存峰值、生成帧率、等待时间和媒体摘要，不能只写“接口成功”。

package/skills/app-store/SKILL.md

@@ -39,12 +39,30 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 ## 包内容
 
+### 物理索引闭包
+
+标准导出器必须同时导出责任表的真实唯一索引和普通复合索引，按列顺序生成独立
+`CREATE INDEX` DDL。组合 AI 应用包按“表 + 索引名”区分物理对象；不能只按表名
+合并 DDL，否则建表语句会吞掉全部索引。同名索引定义冲突须失败，不能任选一条。
+
+当前标准物理结构导出支持 MySQL/MariaDB 的完整列升序 BTREE 与 Id 主键；前缀、
+表达式、全文、降序或其它源数据库需使用已审计的专用包，标准导出须明确拒绝，不能
+静默发布缺约束包。此边界指源库导出，不等同于目标安装器的数据库支持范围。
+
+发布前使用 `microi_get_table_indexes` 对照包内独立 DDL；安装完成后再次核对索引名称、
+唯一性和有序列集合，并测试业务重复键拒绝及重复安装不复制索引。母版存在索引、
+应用页面正常、安装任务成功均不能单独证明目标库的索引完整。
+
 ### 空库清理与开发期应用
 
 安装包应显式登记菜单、表、接口、工作流、任务和微服务的完整归属，供导出、升级和空库制作共同使用。开发期只发布运行资产而尚未制包时，不能假定商城选集已经覆盖新建业务表；应通过现有空库规则接口预览，逐项核对实际物理表、DIY元数据、菜单后代与接口Key。缺失时在责任清理器补充有限、明确的业务归属识别，保留平台核心白名单，读取失败停止制作。只生成SQL与在隔离临时库执行清理是不同动作，禁止在源主库执行脱敏SQL。
 
 清理业务应用时同时按StoreId移除其HDFS包索引，再删除商城主记录，保留平台包索引；历史库缺少索引表时兼容跳过。数据库清理不等于删除HDFS对象，禁止借制作空库清除正式已发布文件。
 
+空库安装历史须能对应保留平台应用的稳定身份，显式 `StoreId` 优先，缺失时才使用非空的旧应用身份；不能按名称或应用前缀猜测归属。角色清理须同时覆盖业务角色、保留账号的角色绑定、角色权限快照及孤立菜单权限，并验证初始模板角色等级与新租户登录。不能把空库清理策略用于卸载应用或清理正在使用的租户。
+
+空库还须清理源租户的业务组织和旧版账号关系，按已校验的初始组织模板重建保留账号部门；平台组织和关系表只清理数据，保留结构。新租户组织树与账号部门必须实际回读和浏览器验收，不能因角色、菜单已清理就推定部门也已清理。
+
 旧布局字段的退役使用可选 `DiyFieldRetirements` 数组，声明 `TableName / Name / ExpectedComponent`，按需用 `ExpectedConfig` 限定组件路径。安装器只允许退役当前包声明表中的 `DevComponent / Divider / Tabs / CollapseGroup`；核心字段、仍在包内声明的字段或控件配置不匹配必须拒绝。先安装支持此协议的商城，再安装声明退役的业务包。退役只软删字段元数据并回读、刷新缓存，不删除物理列或业务数据；已经退役或尚未安装的字段重复执行不产生副作用。
 
 - Manifest：应用 Key、版本、兼容平台版本、依赖和资源清单。
@@ -63,9 +81,27 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 - 兼容旧 Controller/移动端地址时，在唯一 Managed 接口的 `ApiRoutes` 中用英文分号声明全部旧路径。主地址被其它接口占用时，安装器清除旧占用者的该地址并让当前包收回；稳定 Id 被其它 Key 占用时为当前包资源生成新 Id。每次都要清理旧缓存别名并强回读 `ApiAddress + ApiRoutes + ApiV8Code + Version`。
 - 历史包未声明策略时按旧 `LegacyOverwrite` 覆盖兼容；重新发布时发布器必须生成策略。验收至少覆盖首次安装、官方/社区/普通 Managed 本地差异覆盖、同版本重装、软删除恢复、Id/地址自动重映射、Hook 被改后保持原样、两节点竞态，以及官方发布数据库连 `ValidateOnly` 也禁止执行安装器。
 
-## 安装流程
-
-1. 校验签名/哈希、包版本、平台兼容性、依赖和磁盘/配额。
+## 工作流定义与目标审批绑定
+
+- 安装器 `v2.9.9` 对声明 `Installation.ConfigurationPolicy='PreserveTenantValues'` 的包，
+  在共享事务内先读取目标流程配置。相同业务表、节点 Id/用途和连线结构的更新保留 `IsEnable`
+  以及节点的 `Users/Roles/Depts`；V8、按钮规则等受管定义继续按当前包更新，不保留租户代码差异。
+- 业务表、节点用途或连线结构变化时，保留仍兼容的节点绑定并停用流程，记录需要重新配置的诊断；
+  有真实 `Todo` 待办时拒绝改图，不能自动完成、撤回审批或删除历史。管理员须检查包含历史多余
+  节点/连线的完整图形后再启用。未声明该策略的历史包保持原覆盖语义。
+- 节点稳定 Id 跨流程占用、配置读取失败、写入失败或字段/V8回读不一致均失败关闭。
+  发布包只交付停用模板，目标用户、岗位、部门及业务配置不能从官方测试环境复制。
+- 验收必须包含已绑定审批人的真实租户升级与同版本重装，核对启用状态、目标绑定、受管代码
+  更新、在途待办保护及业务配置未变；空模板安装成功不能替代该验收。
+- 安装器 `v3.0.0` 起，流程、节点、连线的新增、更新与配置/结果回读均显式传入同一个
+  `V8.DbTrans`，由外层接口决定提交或回滚。不能把共享事务内的读取与独立提交的写入混用：
+  可重复读快照可能看不到刚写入的数据，并导致失败后残留部分流程。遇到“工作流写入后回读不存在”
+  先升级应用商城安装器，再按原已校验包和任务状态恢复；保留失败审计，不删业务数据或审批历史。
+  回归须模拟事务快照，覆盖首次安装、更新后可见性及节点/连线失败时整个流程回滚。
+
+## 安装流程
+
+1. 校验签名/哈希、包版本、平台兼容性、依赖和磁盘/配额。
 2. 创建全局唯一 `InstallationId` 和稳定幂等键。
 3. 使用后台任务执行，阶段性持久化进度与 checkpoint。
 4. 按 Manifest 创建缺失资源；已有 `Managed` 资源覆盖为包声明值，`CreateIfMissing`/`InsertIfMissing` 既有值保持原样。
@@ -319,6 +355,7 @@ description: Microi 应用商城开发、打包、安装和升级规范。用于
 
 - 触发场景：同一轮主租户批量任务在不同子租户分别报“数据集目标表尚未创建”“接口引擎写入后 HTTP 状态不一致”“既有菜单 Url 唯一冲突”或“未找到 OsClient”；父任务若在目录阶段对全部目标做有副作用自举，还会让一个坏租户阻断其余已可执行租户。
 - 包结构闭包：任何 `DataSets.TableName` 都必须由同一包的 `DiyTables + DiyFields + DDLStatements + PhysicalColumns` 完整创建或由显式依赖声明保证先安装，不能只因为官方母库已有该表就省略。契约测试要逐个数据集反向验证目标表、主键、字段和物理 DDL，并在真实缺表旧租户执行首次安装与重复安装。
+- 随包固定自动编号：导入器 `v2.9.8` 根据目标 `diy_field.Component=AutoNumber`，仅恢复本次允许写入的显式非空编号，并使用共享事务的最小 `_ForceUpt` 更新和严格回读。`UpsertById` 重装修复旧流水号；`InsertIfMissing` 已有配置保持原编号和值。禁止把包内 `_ForceUpt` 当作可信控制参数，也不能只验证模板存在而不检查其业务检索编号。旧安装器先通过应用商城更新，再重装原不可变应用包；冲突、字段元数据读取失败或回读不一致必须失败回滚。
 - 配置子表种子不能硬编码官方父记录 Id。`InsertIfMissing` 数据集可声明 `ParentBinding:{Field:'SysConfigId',TableName:'sys_config',MatchField:'IsEnable',MatchValue:1}`，仅在目标端查询恰好一条父记录 Id，先绑定外键再检查冲突。0 条、多条、查询失败或不安全标识立即失败；不能覆盖父配置值。导出器须保留该声明，旧导入器必须先升级，不能忽略绑定后按官方 Id 写入。
 - 大表物理兼容必须覆盖全部 DDL 路径：`BIT` 不能落入 `varchar` 默认映射，整数显示宽度与纯标签/注释差异不能触发改列；同一个包的字段元数据变化交给物理列阶段统一比较，不能先改再改回。普通标量列仅默认值变化时使用 `ALTER COLUMN ... SET DEFAULT`，移除旧值必须设为 `NULL`，禁止 `DROP DEFAULT` 留下省略字段时触发 1364 的标志；强回读并禁止 COPY 回退。TEXT/BLOB 的缺失默认标志只能保留完整定义执行 `MODIFY COLUMN` 修复，不能用不支持的 `ALTER COLUMN SET DEFAULT NULL`。空字符串默认值不等同于 NULL。安装器时间辅助必须自包含，应用文件落库等新增分支也不得直接依赖租户的 DateNow。
 - 受管接口状态：旧库 `diy_field` 元数据可能落后于 `sys_apiengine` 物理列，导致 FormEngine 返回成功却忽略 `IsEnable/StopHttp`。仅对受信官方 `Managed` 接口的固定布尔控制列，允许在 FormEngine 写后不一致时按稳定 Id 参数化校准物理列、清理租户缓存并严格二次回读；源码、匿名权限、ApiAddress 和租户扩展不得借此绕过三方冲突或所有权保护，二次回读仍不一致必须整包失败。

package/skills/microi-datasource-mapping/SKILL.md

@@ -48,7 +48,15 @@ export function createOptionLabel(options = []) {
 
 ---
 
-## 三、历史遗留数据迁移
+### 原生详情与异步关联回显
+
+- `View` 只读表单可能使用静态展示器，不挂载 `Select`。数据库Id会先成为 `{Key: Id, Value: Id}` 占位对象；只更新字段 `Data` 不能保证该对象的显示名随之更新。
+- 通过已授权接口取得当前关联记录的名称后，同时更新字段选项和同Key显示对象。仅补名称时用 `V8.Form.字段名 = {Key, Value}` 静默赋值，避免 `FormSet` 触发部门/人员等字段的异步联动或把纯查看标记为业务修改。存储字段仍为原Key，不能改成名称或默认第一条。
+- 详情解析以持久主记录和真实权限为依据，不能靠请求传入的任意关联Id读取人员或外站资料。首屏之外的当前关联须单独授权解析，不扩大候选全集；返回仅包含选择器所需字段。
+- 异步回填前核对表单实例、记录Id、依赖值和当前选择；换记录、换部门、改选后的迟到响应丢弃。失败不得伪造名称或清空已有业务关联。
+- 验收覆盖新增检索、编辑、只读详情、首屏外已有值、停用/越权关联和迟到响应；必须实际截图核对可读名称，不能仅看控件类型或接口返回成功。
+
+## 三、历史遗留数据迁移
 
 从第三方数据库迁移枚举前，先用 `microi_inspect_external_database` 确认真实字段类型和说明，再用受限 `microi_query_external_database` 抽样唯一值。第三方显示文字不能直接成为吾码协议 Key；建立明确的“源值 -> 稳定 Key -> 展示 Value”映射，未识别值进入失败清单，禁止静默写成“未知”。持续同步应把映射版本写入任务配置，并保证同一源记录重投不会重复新增。
 

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

@@ -28,6 +28,7 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `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 返回协议 |
+| `more/enterprise-ai-development-series.md` | microi-system-delivery, microi-form-engine, module-engine, v8-api-config | 信息型页面；企业 AI 开发课程与平台引擎实践索引 |
 | `more/hdfs.md` | v8-file-upload | 分布式文件存储和 URL |
 | `more/identity-verification.md` | v8-security, v8-utilities, microi-microservice, app-store, v8-saas-multi-tenant | DiyToken、登录方式气泡、Passkey、Authenticator TOTP、Gitee/微信/GitHub、动态租户设置、严格人脸、一次性步进票据、个人中心和自动升级包 |
 | `more/office.md` | v8-export-import, microi-microservice | Office 导入导出与在线编辑集成 |
@@ -35,6 +36,9 @@ Markdown。第一列是相对 `microi.doc/docs/doc/` 的路径；第二列 Skill
 | `more/sso.md` | microi-sso, v8-security, app-store | 双向 OIDC/SAML2/CAS、账号映射、协议端点、安全基线、商城发布与验收 |
 | `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-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 节点 |
 | `system-engine/ai-data-analysis.md` | ai-engine, v8-security, v8-saas-multi-tenant | 权限感知 Schema、NL2SQL、实时经营分析、追问与数据边界 |
 | `system-engine/ai-creative-studio.md` | ai-engine, v8-image-processing, v8-file-upload | 图片、视频、音乐、29 项图像工具、HDFS 结果与创作安全边界 |
 | `system-engine/ai-platform-governance.md` | ai-platform-governance, app-store, business-blueprint, page-engine | 门户、身份、配置、发布、服务韧性、Trace/日志、资产协作与可恢复导入 |

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

@@ -5,7 +5,13 @@ description: Microi 表单引擎设计与控件配置指南。用于创建或修
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
-# Microi 表单引擎设计
+# Microi 表单引擎设计
+
+## 表单设计器生成 Vue 3 代码
+
+保留现有 `Diy` 动态渲染；需要每表独立页面时，在保存设计后使用【生成 Vue 3 代码】。生成器产生 `src/pages/Form_表名.vue`，源码归当前租户 `microi-generated-forms` 微服务私有项目，AI 应用工作台可继续编辑。Vite 构建并发布运行产物后，模块菜单用 `CodeForm`，同时绑定原 `DiyTableId` 与对应微服务路由。生成页经前端 V8 SDK 传 `_SysMenuId` 调用 FormEngine，权限及后端事件继续由服务端校验。
+
+生成器遇到复杂控件、动态数据源、前端 V8 事件/模板或人工修改过的目标源码会停止并显示原因；不要静默删字段或覆盖定制代码。设计器再次变更后重新生成草稿，在源码工作台审阅和合并，再构建发布。源码保存不等于微服务已构建、菜单已切换或目标租户已安装。
 
 表单引擎同时驱动数据模型、表单、列表、模块、接口配置和工作流配置。处理“新增字段”
 不能只做物理 `ALTER TABLE`：必须让 `diy_table`、`diy_field`、物理列、组件

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

@@ -71,7 +71,7 @@ export function createApp() {
 `Microi.Client` 主后台运行时已内置前后端同构的 `V8.Http.Get/Post/Patch` 及对应 Response 方法；表单事件、按钮 V8 等宿主前端新代码必须优先使用 `V8.Http`，旧 `V8.Post/Get` 仅作兼容保留，其参数和兼容规则以 `v8-http-integration/SKILL.md` 为准。独立项目使用本 SDK、且不在主后台 V8 宿主中时，才使用 SDK 自身的小写 `V8.get/post`、`ApiEngine`、`FormEngine`；不要把它们与宿主旧版大写 `V8.Post/Get` 混为一谈，也不要假设浏览器可以绕过第三方接口的 CORS。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=microi-frontend-sdk-002 sha256=c514dbf966c96102ea04cdf6f967814f2babe74fceaaee6c1f771d351bfdb8eb -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-002 sha256=7e624a3f79211435570dab7a9f4981b1bcccd73d1da5981a53c97fd1e498e007 -->
 ## 登录与验证码封装
 
 SDK 或项目请求模块必须提供登录所需的系统配置和验证码薄封装，不要让页面散落手写。
@@ -184,7 +184,9 @@ uni.request({ url: apiBase + '/apiengine/' + key, header: { Token: token } });
 - [references/progressive-01-token-当前登录用户与当前终端登录协议.md](references/progressive-01-token-当前登录用户与当前终端登录协议.md)：Token、当前登录用户与当前终端登录协议；仅支持 Vue 3；Key-Value 枚举的跨端约定（强制）；界面层独立；验证；搭配 MCI-UI；MicroApp 宿主 Token 同步
 <!-- microi-progressive:end -->
 
-## 复盘：FormEngine 新增请求只在外层保留 Id
+## 复盘：FormEngine 新增请求只在外层保留 Id
+
+独立前端调用 `AddFormData(table, row)` 时，第二参数是业务行，会整体进入 `_RowModel`。需要显式菜单授权时使用完整对象重载：`AddFormData({ FormEngineKey: table, _SysMenuId: menuId, _RowModel: row })`；不要把 `_SysMenuId`、`_FormData` 再包进字符串重载的业务行。由平台生成主键时从 row 中省略 `Id`，不能传空字符串；确需预生成 Id 时按下述双位置契约传有效值。使用实际内嵌 SDK 的传输测试核对外层权限和行模型，再以普通角色完成真实表单新增及 After 回读。
 
 - 触发场景：uni-app/微信小程序预生成记录 Id 后调用 `V8.FormEngine.AddFormData(table, row)`，服务端表单事件中 `V8.Form.Id` 仍为空，按父 Id 查询子表时误命中外键为空的孤儿数据。
 - 根因：SDK 将 `Id` 从业务行模型 `_RowModel` 中移出后只写到请求外层；外层 Id 可用于接口寻址，但不会稳定进入表单事件的 `V8.Form`。

package/skills/microi-frontend-sdk/references/progressive-01-token-/345/275/223/345/211/215/347/231/273/345/275/225/347/224/250/346/210/267/344/270/216/345/275/223/345/211/215/347/273/210/347/253/257/347/231/273/345/275/225/345/215/217/350/256/256.md

@@ -2,7 +2,7 @@
 
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
-<!-- microi-progressive:chunk id=microi-frontend-sdk-006 sha256=85694df371b7b889b5bf4aea5bc98d604232eb5c7b88b8a0eae8a26d70877009 -->
+<!-- microi-progressive:chunk id=microi-frontend-sdk-006 sha256=6f779d619a24b1c03fb02efbc4bc25d41ce3254dbfbf1c63af137dcd9a45790b -->
 ## Token、当前登录用户与当前终端登录协议
 
 Microi 后端不是只保存一个全局 Token。每个租户、每个 `sys_user` 在 Redis 中维护一份 `CurrentToken`，其中 `CurrentUser` 表示平台当前登录用户，`Tokens` 表示该用户的多个当前终端登录。每个终端项至少包含 `Token`、`ClientType`、`Did`、`IP`、`CreateTime`、`UpdateTime`；退出、管理员清除登录信息、同终端重新登录或 Token 轮换都会影响该列表。

package/skills/microi-microservice/SKILL.md

@@ -135,6 +135,12 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 - 服务器暂未部署修复且普通应用产物很小时，可把 `StorageMode=db` 与内联 `ContentBase64` 作为短期恢复手段；必须明确记录为临时方案。修复部署后重新流式发布到公有 HDFS，并恢复 `StorageMode=file`。只有上一条满足严格资源策略的受信任平台启动应用允许长期保留小型数据库产物；禁止借此把普通或大体积 JS/CSS 长期放进数据库 JSON。
 - 子租户发布时，源码、版本资产、回读验签、页面与缓存全部绑定当前 Token 的 `OsClient`；禁止回退到主租户或宿主服务器默认租户。切换前必须由当前 API 节点通过该子租户 HDFS 配置读回每个版本文件并校验大小/SHA-256。
 
+### 宿主路由查询参数
+
+嵌入微服务的 iframe 地址与宿主地址隔离，不能仅通过子应用 location.hash 读取站点、业务Id等查询参数。菜单宿主下发 microRoute 及 route.query；应用应合并自身白名单参数，保留完整路径和查询参数，并监听宿主数据变化。同一路径的查询参数变化也应刷新业务数据、取消旧请求，主题或尺寸快照不得覆盖应用内部导航。弹窗可从 microRoute 查询串或 dialogData 读取声明参数；独立访问才回退自身hash。
+
+生成宿主页面链接时使用可信上下文的 webBase、apiBase 与 osClient，不猜测父窗口地址，不把Token写入URL。验收覆盖嵌入冷启动、同路径换参数、独立入口、无效参数和跨请求迟到响应。
+
 ## 菜单、弹窗与表单嵌入
 
 菜单 `OpenType=MicroService` 时一次绑定 `MicroServiceId`、
@@ -219,8 +225,12 @@ AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data
 - 通用 3D 设计器/渲染器与某一楼宇的定制数字孪生应使用不同 AppKey、源码目录、路由清单、运行资产与商城安装包。官方 `Platform` 包只拥有通用引擎和平台菜单；项目专属模型/贴图、业务表与字段、IoT 接口、演示数据和业务菜单属于独立业务应用（本项目采用 `MicroService`）。批量“安装/更新全部平台应用”只覆盖 `ApplicationType=Platform`，不得借平台包向所有租户散发某个客户的项目。拆分时要检查旧商城包的 `SelectMenu/SelectTable/SelectApiEngine/SelectData` 回退选择，清空旧选择后重新制作安装包，并分别回读两个包的资源快照与真实浏览器入口。
 - 道路车辆、人物、设备动画不能只靠静态截图验收。浏览器测试应同时断言对象数量、时间推进后的坐标/骨骼变化、路径末端回绕、切换楼层后的恢复及 `prefers-reduced-motion` 设置下的实际行为；测试探针只暴露非敏感数量和位置，不暴露 Token、人员或设备隐私。若持续运动本身是用户明确要求的核心功能，不得把系统的“减少动态效果”误用为整体动画总开关；只降级装饰性过渡，并提供可见、可键盘操作的暂停/恢复控制。页面隐藏或暂停期间冻结业务动画时钟，恢复时扣除停顿时间，避免物体瞬移。
 - 外部 GLB/GLTF 进入官方运行包前，逐项保存作者、原始地址、许可证、是否允许商用和再分发、署名方式、三角面数、纹理大小及优化记录。“免费下载”、搜索摘要或仓库内没有许可证都不构成可再分发授权；`NC`、`ND` 或用途不明的资产默认不进入商业应用包。
+- 可再分发的外部树木等高模要先校验原站提供的文件校验和，再用免费离线工具焊接顶点、做 LOD 简化和 WebP 纹理压缩；将运行 GLB 与原始下载、处理工具分离。单个共享资产实例化时不要给每棵树复制几何/贴图，也不要在销毁一个场景时释放仍被共享模板引用的 GPU 资源；异步加载完成后须确认原场景仍挂载，防止切换楼层后回填已卸载对象。测试应同时覆盖 GLB 魔数/大小、运行时加载数量与失败降级计数、移动端绘制预算、总览和近景截图。
 - 品牌车辆和真实建筑只能在拥有明确资产/商标使用依据时描述为精确复刻。程序化或原创近似模型使用“风格化/演示模型”措辞，不得把车型标签当作厂商认证。视觉签收与功能、运行发布、商城包、目标租户安装是不同证据层。
 - 运动物体优先使用可复用几何/材质、LOD、实例化和离屏回绕；相机近景仍要检查曲面法线、透明车窗、轮胎方向、脚底接地、穿模和阴影。页面隐藏时暂停动画，恢复时避免累积大时间差导致物体瞬移。
+- 三维数据标牌可以使用透明 PBR 厚度几何、纹理文字与空间连线，但必须保留对齐的 DOM 点击/键盘目标、读屏文本和焦点环。小屏避碰要测试真实矩形交集，不能仅检查页面无横向滚动；把冲突标牌一律向上推会在工具条边界堆叠。玻璃 transmission 会额外渲染场景，密集人群应先量测绘制次数，再选择透明近似或折射质量档。
+- 人群实例化须按可复用几何及材质属性分组，保留各人物肘膝关节矩阵，颜色用实例属性；实例化之后仍验证抬脚/落脚和长时间回绕。车辆座椅按座舱净高缩放，不能所有车型使用同一绝对头枕高度。静态源码断言之外，应实例化真实几何做边界/有限矩阵单测，并提供街景近景入口供实拍验收。
+- 建筑照片立面、实体墙和屋顶若几乎共面，旋转相机时会触发深度缓冲 z-fighting：外露侧墙的纹理面沿法向留明确间距，屋顶纹理面高于实体面，必要时用 `polygonOffset`；被相邻楼翼/门廊遮住的内部端面不要重复画照片面。验收须从东、西两端短侧墙和斜俯视分别实拍，暂停动态物体后比较同角度连续帧的大幅像素跳变；只看主立面截图不能证明无闪烁。
 
 ### 菜单页签缓存与子应用生命周期（强制）
 

package/skills/module-engine/SKILL.md

@@ -70,8 +70,15 @@ description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修
 - `CardBottomTagFields`
 - `DefaultOrderBy`
 
-普通状态、开关等低基数字段不能机械创建单列索引。只有真实查询、关联、唯一约束
-或扫描需要的索引才进入 Manifest 并通过 MCP 创建、回读。
+普通状态、开关等低基数字段不能机械创建单列索引。只有真实查询、关联、唯一约束
+或扫描需要的索引才进入 Manifest 并通过 MCP 创建、回读。
+
+Manifest 中按字段名声明统计列，使用 `statFields` 或 `statisticsFieldNames`，例如
+`statFields: ['Amount', 'Quantity']`；MCP 会解析目标租户的字段 Id。
+`statisticsFields` / `StatisticsFields` 表示已经转换好的原生 JSON，元素为
+`{ Id: '真实 diy_field.Id', Type: 'Sum' }`，不能填字段名称字符串。发布前用有记录的
+实际列表检查 `DataAppend.StatisticsFields` 及页面汇总，再以无权限账号检查汇总范围；
+HTTP 成功或菜单字段非空不足以证明统计有效。
 
 ## AI 模块视觉交付门禁（强制）
 
@@ -111,7 +118,10 @@ description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修
 | `Iframe` | 受控外部页面 |
 | `SecondMenu` | 仅作为父菜单 |
 | `Report` | 虚拟报表 |
-| `MicroService` | 已发布前端微服务页面 |
+| `MicroService` | 已发布前端微服务页面 |
+| `CodeForm` | 表单设计器生成并在已发布微服务中运行的独立 Vue 3 页面；必须绑定 `DiyTableId` |
+
+`CodeForm` 复用 MicroService 宿主与菜单权限上下文。先在表单设计器生成源码，保存至 `microi-generated-forms`，构建并发布微服务；再配置 `MicroServiceKey + MicroServiceRoutePath`（以及当前租户真实的 `MicroServiceId + MicroServicePageId`），保留原表的 `DiyTableId`。Manifest 生成器可解析可移植的 Key/RoutePath；`microi_create_module` 必须传实际 Id。不能把只保存私有源码当作已发布运行产物。
 
 Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使用短期、一次性、
 可撤销的服务端交换票据，限制 redirect/scope，并在落地后清理地址栏。

package/skills/print-engine/SKILL.md

@@ -1,36 +1,36 @@
 ---
 name: print-engine
-description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用于创建 mic_print 模板、PageObj 布局、PrintObj 数据绑定、可打印报告、标签或合同；蓝牙 TSPL/CPCL/ESC-POS、GP-M322 或 CC4 需求转交 v8-frontend-events 蓝牙参考。
+description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用于创建 mic_print 模板、PageObj 布局、PrintObj 数据绑定、可打印报告、标签或合同；蓝牙 TSPL/CPCL/ESC-POS、GP-M322 或 CC4 需求转交 v8-frontend-events 蓝牙参考。
 ---
 
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
 
-# Microi 打印引擎（Print Engine）模板 JSON 生成
-
-你正在为 Microi 吾码平台生成打印引擎模板的 JSON 数据。打印模板包含 PageObj（模板定义）和 PrintObj（打印数据）。
-
-## 设计器源码事件
-
-扩展打印设计器源码时，可通过 `EventBus.on('savePrintJson', handler)` 接收
-保存后的模板 JSON，并在组件卸载时调用 `EventBus.off('savePrintJson')`。
-这是设计器内部生命周期接口，不属于运行时打印模板 JSON，也不能替代模板的
-服务端保存与回读。
-
-## 与蓝牙直连打印的边界
-
-本 Skill 负责 `mic_print`、`PageObj`、`PrintObj`、浏览器预览和模板化纸张输出。
-如果需求明确是蓝牙标签机/小票机、TSC/TSPL、CPCL、ESC/POS、佳博 GP-M322、
-ZICOX CC4、BLE/SPP 或
-`V8.Print.prepareSend`，应同时读取
-`../v8-frontend-events/references/bluetooth-print.md`：
-
-- Print Engine 决定“页面/模板如何排版”，适合 A4、PDF、浏览器打印和统一模板。
-- `V8.Print` 生成/适配打印机原生命令并通过 BLE 或 Android SPP 写入，适合标签和热敏小票；GP-M322 保持 TSPL 原字节，CC4 可自动生成 CPCL。
-- MicroService 不能跨 iframe 访问父页面打印组件；普通打印使用 `microi.host.v1` 的
-  `openPlatformPrint`，只传当前租户 `mic_print.Id` 和同源 `/apiengine/` 数据地址。该动作
-  不是蓝牙代理，不发送 BLE/SPP 字节。详见 `../microi-microservice/references/runtime-delivery.md`。
-- 两者可以由同一个按钮按设备能力选择，但不能把 `PageObj` 直接交给
-  `V8.Print.prepareSend`，也不能把 TSPL/CPCL/ESC-POS 字节当作 Print Engine JSON。
+# Microi 打印引擎（Print Engine）模板 JSON 生成
+
+你正在为 Microi 吾码平台生成打印引擎模板的 JSON 数据。打印模板包含 PageObj（模板定义）和 PrintObj（打印数据）。
+
+## 设计器源码事件
+
+扩展打印设计器源码时，可通过 `EventBus.on('savePrintJson', handler)` 接收
+保存后的模板 JSON，并在组件卸载时调用 `EventBus.off('savePrintJson')`。
+这是设计器内部生命周期接口，不属于运行时打印模板 JSON，也不能替代模板的
+服务端保存与回读。
+
+## 与蓝牙直连打印的边界
+
+本 Skill 负责 `mic_print`、`PageObj`、`PrintObj`、浏览器预览和模板化纸张输出。
+如果需求明确是蓝牙标签机/小票机、TSC/TSPL、CPCL、ESC/POS、佳博 GP-M322、
+ZICOX CC4、BLE/SPP 或
+`V8.Print.prepareSend`，应同时读取
+`../v8-frontend-events/references/bluetooth-print.md`：
+
+- Print Engine 决定“页面/模板如何排版”，适合 A4、PDF、浏览器打印和统一模板。
+- `V8.Print` 生成/适配打印机原生命令并通过 BLE 或 Android SPP 写入，适合标签和热敏小票；GP-M322 保持 TSPL 原字节，CC4 可自动生成 CPCL。
+- MicroService 不能跨 iframe 访问父页面打印组件；普通打印使用 `microi.host.v1` 的
+  `openPlatformPrint`，只传当前租户 `mic_print.Id` 和同源 `/apiengine/` 数据地址。该动作
+  不是蓝牙代理，不发送 BLE/SPP 字节。详见 `../microi-microservice/references/runtime-delivery.md`。
+- 两者可以由同一个按钮按设备能力选择，但不能把 `PageObj` 直接交给
+  `V8.Print.prepareSend`，也不能把 TSPL/CPCL/ESC-POS 字节当作 Print Engine JSON。
 
 ## 数据模型
 
@@ -40,15 +40,15 @@ ZICOX CC4、BLE/SPP 或
 |------|------|
 | PageObj | 页面模板定义（面板 + 元素布局） |
 | PrintObj | 打印数据（运行时填充到模板中） |
-| DataApi | 关联的接口引擎 Id（动态数据） |
-
-### `mic_print` 权限边界
-
-- `mic_print` 是按角色管理的运行资源，不是只能由 `Level >= 9999` 读取的控制面表。打印渲染器通过 FormEngine 读取模板时，当前角色必须拥有菜单权限或高级表权限中的 `Read`；否则应明确返回 `NoAuth`，不能为兼容改成匿名读取。
-- 模板新增、修改、删除分别要求明确的 `Add`、`Edit`、`Del`。只需要打印的业务角色通常只授予 `Read`，不要顺带授予设计权限。
-- 角色授权界面只负责展示服务端策略。角色增删改接口必须从主库复核当前操作者确为活动平台管理员，不能相信 Postman 请求体中的 `_IsAdmin`、`Level`、`RoleIds` 或 `OsClient`。
-
-## PageObj 模板结构
+| DataApi | 关联的接口引擎 Id（动态数据） |
+
+### `mic_print` 权限边界
+
+- `mic_print` 是按角色管理的运行资源，不是只能由 `Level >= 9999` 读取的控制面表。打印渲染器通过 FormEngine 读取模板时，当前角色必须拥有菜单权限或高级表权限中的 `Read`；否则应明确返回 `NoAuth`，不能为兼容改成匿名读取。
+- 模板新增、修改、删除分别要求明确的 `Add`、`Edit`、`Del`。只需要打印的业务角色通常只授予 `Read`，不要顺带授予设计权限。
+- 角色授权界面只负责展示服务端策略。角色增删改接口必须从主库复核当前操作者确为活动平台管理员，不能相信 Postman 请求体中的 `_IsAdmin`、`Level`、`RoleIds` 或 `OsClient`。
+
+## PageObj 模板结构
 
 ```json
 {
@@ -106,17 +106,19 @@ ZICOX CC4、BLE/SPP 或
 }
 ```
 
-文本 `text` 与长文本 `longText` 的 `options.formatter` 接收
-`function(title, value, options, templateData)`；文本控件还可能传第五个 `target`。
-第一参数是标题，绑定数据在第二参数。不要直接传入 `function(value)` 编码器，否则会把
-标题当业务值打印。表格单元格的 `formatter2(title, field, row, index, options)` 是另一合同。
-金额应由后端精确计算后作为字符串输出，不能在打印页转换为 `Number` 再求和。
-业务文本经过 formatter 进入 HTML 时必须编码 `& < > " '`，并用含标签的值与大额金额
-调用真实函数签名做回归。模板保存成功只证明存储，仍须用实际数据预览分页、合计与长条款。
-
-### table — 表格元素
-
-```json
+文本 `text` 与长文本 `longText` 的 `options.formatter` 接收
+`function(title, value, options, templateData)`；文本控件还可能传第五个 `target`。
+第一参数是标题，绑定数据在第二参数。不要直接传入 `function(value)` 编码器，否则会把
+标题当业务值打印。表格单元格的 `formatter2(value, row, index, options)` 是另一合同，首参是当前单元格值，第三参是列索引。
+金额应由后端精确计算后作为字符串输出，不能在打印页转换为 `Number` 再求和。
+表格列应使用 `function(value){ return escapeText(value); }` 这一形式。验收必须检查实际打印 iframe 的商品、数量、单价及金额单元格；表头、合计正确并不能证明明细正确，设计画布的 testData 也不能作为实际打印数据。
+
+业务文本经过 formatter 进入 HTML 时必须编码 `& < > " '`，并用含标签的值与大额金额
+调用真实函数签名做回归。模板保存成功只证明存储，仍须用实际数据预览分页、合计与长条款。
+
+### table — 表格元素
+
+```json
 {
   "options": {
     "left": 30, "top": 150, "height": 56, "width": 511.5,
@@ -220,7 +222,7 @@ ZICOX CC4、BLE/SPP 或
 
 | 属性 | 函数签名 | 说明 |
 |------|----------|------|
-| formatter2 | `function(title, field, row, index, options)` | 单元格渲染 |
+| formatter2 | `function(value, row, index, options)` | 单元格渲染，首参为值、index为列索引 |
 | styler2 | `function(value, row, index, options)` | 单元格样式 |
 | rowStyler | `function(row, index, options)` | 行样式 |
 | footerFormatter | `function(options, rows, data, el)` | 表尾渲染 |