@microi.net/cli 6.2.1 → 6.2.2

package/skills/v8-file-upload/references/progressive-01-/345/205/254/346/234/211/346/241/266-vs-/347/247/201/346/234/211/346/241/266.md

@@ -2,9 +2,15 @@
 
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
-<!-- microi-progressive:chunk id=v8-file-upload-005 sha256=71cebd2f6946be49188c430c146b9ee923ceb0719fbda4bd3701b40152732cae -->
+<!-- microi-progressive:chunk id=v8-file-upload-005 sha256=4922ff1364f2a9994d7cc47ff224e07c794e382b6f5f44b75b76ae365f7efff1 -->
 ## 公有桶 vs 私有桶
 
+### OSS 配置不完整的诊断
+
+- `OBJECT_STORAGE_CONFIG_INCOMPLETE` 不等于必须购买阿里云。先核对当前生效租户三参数和 SaaS `HDFS`（`Aliyun/MinIO/S3`）；旧库未设置时兼容默认 Aliyun。实际使用其它提供商时，通过既有 SaaS 配置入口修正并刷新缓存，不自动切换存储或借用主租户密钥。
+- 含按桶校验修复的 OSS `PutObject` 仅校验并初始化本次所需桶：普通 `Limit=false/null` 检查 `AliOssPublic*` 四项，`Limit=true` 检查 `AliOssPrivate*` 四项；每组为 `BucketName/Endpoint/AccessKeyId/AccessKeySecret`。只有 `Preview=true` 且有 `FileFullPathOrigin` 时额外读取私有原图；生成公有预览需两组。缺项失败关闭，错误保留 `ErrorType`、`StorageScope` 和字段名，不输出配置值。
+- 旧后端可能把公私两套配置一并报缺。此修复不能生成有效密钥；完整微服务交付包含私有源码和公有编译产物，仍须配置相应两类存储并验证 FileServer/CDN。只完成单桶上传不等于完整发布、回滚或客户验收成功。现有 MCP 发布/上传入口可继续复用，无需改工具签名。
+
 ### 应用商城 ZIP
 
 应用商城的 AI 应用/微服务资产禁止逐文件 Base64 持久化到数据库。源码/安装包场景可以生成 ZIP；真实在线编译目录优先使用下节的 MCP 流式发布。数据库只保存路径和校验元数据。

package/skills/v8-frontend-events/SKILL.md

@@ -25,11 +25,16 @@ description: Microi 前端 V8 事件与客户端能力指南。用于编写浏
 - 登录后的敏感操作使用 `V8.Identity.Verify` 完成 Passkey/严格人脸交互；前端只取得一次性 Ticket，后端接口引擎必须重算 `ActionHash` 并原子消费，不能把前端成功当作授权。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-001 sha256=eaab87d01b0fd2b6964326ee11edd7b793899c679930c575a0a2b309d36a367a -->
+<!-- microi-progressive:chunk id=v8-frontend-events-001 sha256=bf7d6288bece731f78dbfa29b0e04ff56631d3693979bb91d759fe26ef92d0ec -->
 ## 字段事件（在【字段属性】中配置）
 
 ### FieldValueChange — 值变更事件（最常用）
 
+关联回填先读 `../microi-form-engine/references/form-generation-quality.md`。`ThisValue`
+不是固定行对象：保存格式为 Text 时可能是原始键，Department 可能是路径，多选是数组。
+先按来源保存键解析，再逐字段回填；处理清空、改选、失败和异步代次，不从名称猜来源列。
+只有已确认选择是行对象且保存键确为 Id 时才能读取 `V8.ThisValue.Id`，不能用于原始键或部门路径。
+
 ```javascript
 // V8.EventName === 'FieldValueChange'
 // V8.ThisValue   — 当前字段新值
@@ -42,8 +47,11 @@ description: Microi 前端 V8 事件与客户端能力指南。用于编写浏
 if (V8.LoadMode === 'Design') return;
 
 // 选择部门 → 联动加载该部门下的人员到 联系人 控件
-var deptId = V8.ThisValue && V8.ThisValue.Id;
-if (deptId) {
+var selection = V8.ThisValue;
+if (Array.isArray(selection)) selection = selection.length ? selection[selection.length - 1] : '';
+var deptId = selection && typeof selection === 'object' ? selection.Id : selection;
+V8.FormSet('Contact', ''); // 清除原部门的联系人，不能只更换候选列表
+if (deptId !== '' && deptId !== null && deptId !== undefined) {
   var users = await V8.FormEngine.GetTableData('Diy_Employee', {
     _SelectFields: ['Id', 'Name', 'Account'],
     _Where: [['DeptId', '=', deptId]]
@@ -53,14 +61,14 @@ if (deptId) {
   V8.FieldSet('Contact', 'Data', []);
 }
 
-// 联动设置另一字段值
-V8.FormSet('CustomerName', V8.ThisValue.Name);
+// 对其它业务字段的回填需先取得并校验授权来源记录。
+// 不要无条件用 V8.ThisValue.Name；Text 保存格式可能只有 Id。
 
 // 联动显隐
 V8.FieldSet('TaxNo', 'Visible', V8.ThisValue === '企业');
 
 // 联动必填
-V8.FieldSet('Reason', 'Required', V8.ThisValue === '退款');
+V8.FieldSet('Reason', 'NotEmpty', V8.ThisValue === '退款');
 ```
 
 ### FieldOnKeyup — 键盘抬起事件

package/skills/v8-image-processing/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: v8-image-processing
-description: Microi V8.Image 服务端图像处理指南。用于在接口引擎或后端 V8 事件中生成图片、横向/纵向/网格拼接、图层覆盖、水印、缩放、裁剪、旋转、翻转、格式转换、绘制文字与图形、生成二维码、读取图片信息，以及设计安全的 Base64/Data URI 图像处理流程。
+description: Microi V8.Image 服务端图像处理指南。用于图片生成、合并、水印、缩放、裁剪、格式转换、文字绘制、二维码与元数据读取，以及多页中文 PDF 的字体缓存释放、原生内存增长排查和安全 Base64/Data URI 流程。
 ---
 
 > **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
 
 # Microi V8 图像处理
 
-使用 `V8.Image` 在服务端处理内存图片。所有方法统一接收对象参数并返回 `DosResult`；图片结果位于 `result.Data.FileByteBase64`。
+使用 `V8.Image` 在服务端处理内存图片。图像操作接收对象参数并返回 `DosResult`；图片结果位于 `result.Data.FileByteBase64`。`ReleaseFontCache()` 是无参维护方法，仅返回缓存统计。
 
 ## 核心原则
 
@@ -52,6 +52,7 @@ var source = {
 | 添加常规图片水印 | `V8.Image.Watermark` | `BaseImage`、`Watermark`、`Position`、`Opacity` |
 | 生成二维码 | `V8.Image.CreateQRCode` | `Content`、`Size` |
 | 读取宽高、格式等元数据 | `V8.Image.GetInfo` | 任一图片来源字段 |
+| 批量文字绘制后释放字体缓存 | `V8.Image.ReleaseFontCache()` | 无参数；返回缓存字节统计，不返回图片 |
 
 ### 3. 设计合并布局
 
@@ -169,8 +170,18 @@ return result;
 - 通用规则：图片文字能力必须随 `Dos.Common` 程序集嵌入许可允许再分发的中英文字体；解析顺序固定为指定/系统字体、内置字体、明确缺字错误，禁止把“请运维安装字体”作为基础文字功能的唯一方案。
 - 自动化检查：除 Windows 单元测试外，必须在 `FONTCONFIG_FILE` 指向空字体目录的 Linux 容器中验证英文、数字、中文和不存在的 `FontFamily`，同时确认系统 `MatchCharacter` 返回空、输出存在有效文字像素且没有缺字方框。
 
+## 多页中文绘制与字体缓存
+
+- 先区分照片像素内存、托管堆和原生字体缓存。缩放照片不能解决字体实例累积；案例册和报表若都调用 `Create`/`Draw` 绘制中文，就共享同一字体处理路径。
+- 使用后端 `V8.Image.ReleaseFontCache()` 在页或批次边界清理，通常放在绘制前和 `finally` 中。普通单图无需机械添加，不得逐字符调用或把它放进匿名的独立“清缓存”接口。
+- 最小调用：`var released = V8.Image.ReleaseFontCache(); if (!released || Number(released.Code) !== 1) return released || { Code: 0, Msg: '字体缓存释放未返回结果' };`。完整绘制与失败路径示例见 [API 参考](references/api-reference.md#releasefontcache-释放字体缓存)。
+- `BeforeBytes/AfterBytes` 是进程共享字体缓存统计；并发时缓存会重建，不能断言清零、单调下降或将差值当作 RSS 释放量。调用不强制 GC、不改限额、不清 Redis。
+- 先确认实际 API 进程已加载包含该方法的 `Microi.V8Engine`。旧部署可明确失败，或按业务要求兼容继续并标记能力未启用；不得吞掉错误后宣称问题已修复。更新 Skills、接口代码或编译成功都不能替代程序集部署和重启。
+
 ## 验收清单
 
+- 多页中文 PDF/图片出现 RSS 快速上升时，区分托管累计分配、托管存活堆和原生字体缓存。`V8.Image.ReleaseFontCache()` 是无参原子能力，返回 `{Code:1,Data:{BeforeBytes,AfterBytes}}`，可在每页绘制前后调用；不修改缓存限额、不强制 GC，影响进程共享字体缓存。缓存字节不是 RSS 释放量。先确认部署包含该方法，旧服务器兼容跳过必须在诊断结果中明确标记；不能仅靠文件缓存命中、重试或本地编译宣称内存问题已解决。
+
 - 确认每个图片来源都来自受信任的内存数据，并且没有把路径或 URL 直接传给 `V8.Image`。
 - 确认处理链中每一步都检查 `Code === 1`。
 - 确认覆盖图层的 `ZIndex`、`X/Y` 或 `Position` 与预期一致。

package/skills/v8-image-processing/references/api-reference.md

@@ -19,12 +19,13 @@
 15. [GetInfo 读取信息](#getinfo-读取信息)
 16. [兼容别名](#兼容别名)
 17. [颜色、格式与资源限制](#颜色格式与资源限制)
+18. [ReleaseFontCache 释放字体缓存](#releasefontcache-释放字体缓存)
 
 ## 调用与返回约定
 
-所有公开方法都接收一个参数对象。底层也兼容内容为 JSON 对象的字符串，但 V8 代码应优先直接传对象，并使用规范的 PascalCase 字段名。
+除无参 `ReleaseFontCache()` 外，公开方法接收一个参数对象。底层也兼容内容为 JSON 对象的字符串，但 V8 代码应优先直接传对象，并使用规范的 PascalCase 字段名。
 
-处理成功时，除 `GetInfo` 外均返回：
+处理成功时，除 `GetInfo` 和 `ReleaseFontCache` 外均返回：
 
 ```javascript
 {
@@ -42,6 +43,8 @@
 }
 ```
 
+`V8.Image.ReleaseFontCache()` 返回 `{Code:1,Data:{BeforeBytes,AfterBytes}}`。这是进程共享字体缓存统计，不是 RSS 释放量；调用只释放可回收字体缓存，不修改限额或强制 GC。多页绘制可在页面前及 `finally` 中调用，正常绘制会重新建立需要的缓存；不得每个字符清理。旧服务器需升级 `Microi.V8Engine`，兼容跳过不能记录为成功。
+
 处理失败时返回 `Code: 0`，错误说明位于 `Msg`。任何调用链都必须先判断 `Code`：
 
 ```javascript
@@ -98,7 +101,7 @@ var result = V8.Image.GetInfo({ Bytes: response.RawBytes });
 
 ## 公共输出参数
 
-除 `GetInfo` 外，各方法均支持以下参数：
+除 `GetInfo` 和无参 `ReleaseFontCache` 外，各方法均支持以下参数：
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
@@ -127,9 +130,52 @@ var result = V8.Image.GetInfo({ Bytes: response.RawBytes });
 | `V8.Image.Watermark(param)` | 按锚点添加图片水印 |
 | `V8.Image.CreateQRCode(param)` | 生成二维码 |
 | `V8.Image.GetInfo(param)` | 读取图片元数据，不重新编码 |
+| `V8.Image.ReleaseFontCache()` | 无参；释放本进程可回收字体缓存，返回统计，不返回图片 |
 
 `RemoveSolidBackground` 参数：内存图片来源、`Tolerance`（默认 36）、`Feather`（默认 24）、可选 `ChromaKeyColor`（如 `#00ff00`）、`EdgeConnectedOnly`（默认 false）、`SuppressGreenSpill`（默认 false）。开启边缘连通限制可保护主体内部同色区域；封闭背景孔洞可能保留，需检查输出。专门生成的纯绿幕素材可指定绿色并开启去溢绿，清除封闭绿幕孔洞及边缘混色；主体本身为绿色时不得开启。未指定抠像色时估计四角背景色。输出固定 PNG，输入上限为 20,000,000 像素，不接受任意图片 URL。
 
+## ReleaseFontCache 释放字体缓存
+
+签名：`V8.Image.ReleaseFontCache()`，仅后端可用，无参数。成功返回：
+
+```javascript
+{ Code: 1, Data: { BeforeBytes: 20480, AfterBytes: 0 } }
+```
+
+以上数字仅作字段示例，不能作为预期值。失败返回 `Code:0` 和 `Msg`；方法不存在的旧程序集可能直接抛错，必须显式处理。
+清理作用于当前进程共享的 Skia 字体缓存，不区分租户、不跨节点、不修改缓存上限或执行 GC。
+活跃绘制仍可持有字体，并发可重新填充缓存，所以 `AfterBytes` 不保证为零，也不保证小于 `BeforeBytes`。
+它不会清 Redis、释放照片 Base64 或保证进程 RSS 下降指定字节数。
+
+```javascript
+// 每页或每批使用；先部署包含方法的程序集，不依赖版本号猜测运行能力。
+function clearFonts() {
+    try {
+        var result = V8.Image.ReleaseFontCache();
+        return result || { Code: 0, Msg: '字体缓存释放未返回结果' };
+    } catch (error) {
+        return { Code: 0, Msg: '字体缓存释放不可用，请核对程序集和服务重启状态' };
+    }
+}
+var before = clearFonts();
+if (Number(before.Code) !== 1) return before;
+var drawn, after;
+try {
+    drawn = V8.Image.Create({ Width: 640, Height: 160,
+        Text: '中文报表 / Report 2026', FontSize: 32, OutputFormat: 'png' });
+} finally {
+    after = clearFonts(); // 不覆盖原始绘图异常。
+}
+if (!drawn || Number(drawn.Code) !== 1) return drawn || { Code: 0, Msg: '绘制未返回结果' };
+if (Number(after.Code) !== 1) return after;
+return { Code: 1, Data: drawn.Data, DataAppend: { FontCache: after.Data } };
+```
+
+普通单图无需每次清理，批量中文绘制出现原生缓存增长时才使用；禁止逐字符清理。
+如果业务必须兼容旧部署，应显式返回未启用状态，不能把成功导出等同缓存释放成功。
+验收须通过真实 API 测试连续绘图、清理后再绘图、失败时 `finally`、旧部署及并发；
+观察冷生成内存，不能只测命中 PDF 缓存的请求。无系统字体 Linux 须单独回归。
+
 ## Create 生成图片
 
 ### 参数

package/skills/v8-security/references/progressive-02-7-/346/227/245/345/277/227/350/256/260/345/275/225.md

@@ -64,7 +64,7 @@ try {
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-security-010 sha256=26ae8c22e1db1edca4d159d68423ae14ec84b528e5cc4deb305010f89871f57e -->
+<!-- microi-progressive:chunk id=v8-security-010 sha256=556686f6250c75b35428b7283f79769b5a450cb9f67138f6483d2ea73f235751 -->
 ## 9. Token、终端会话与租户隔离
 
 开发 Web、H5、UniApp、小程序、App、VS Code 或 MCP 客户端时，必须同时遵守 `microi-frontend-sdk/SKILL.md` 的 Token 协议：登录传 `_ClientType`，请求头传稳定 `did`，每次响应接收新的 `authorization`，并在浏览器/应用恢复前台时检查续签。
@@ -75,6 +75,11 @@ try {
 - 收到 `TokenReplaced` 时先检查同一终端是否已有新 Token，避免并发旧响应误清新登录态。
 - 用户提示可以显示过期时长、终端类型和租户 Key，但日志、Toast、URL、截图禁止输出完整 Token。
 
+- 平台复制的 CLI/MCP 连接必须是独立开发会话，浏览器与开发工具分别续签、撤销。CLI、VS Code、MCP 共享导入 Token 时保留已有有效签名 `Did`；不得因宿主 Header 不同反复迁移，仅缺失或 `Empty` 的历史 Did 可受控补齐。客户端解码 JWT 只用于稳定请求头，身份仍由后端验签、租户和活动缓存确定。
+- 登录、刷新、终端清理与吊销必须在同租户、同用户轮换锁内回读最新共享会话；鉴权或终端列表读取只清洗当前投影，不得整份回写旧 Token 列表，覆盖并发签发或复活已撤销终端。
+- 真正吊销、超出服务端续签边界、共享登录缓存丢失时，必须有效登录后重新复制并安全导入连接；禁止用 `tokenlogin`、放宽期限或重建缓存绕过。`TokenReplaced` 先检查同连接共享 Token 是否已更新，不盲目重复刷新。
+- HTTP 200 或空身份的 `Code=1` 不是认证成功；导入/登录/续签需核验有效 Token、非空用户 `Id` 和目标租户，随后真实初始化及状态回读。本次后端兼容修复支持已发布 CLI 6.2.1，不依赖另发 Agent 产品；源码加固、平台部署和工具产品发行分别记录。
+
 ### IP 高频拦截、受信 VS Code 独立阈值与解除
 
 - `DataAppend.SecurityBlocked=true` 是服务端已可达但当前 IP 被临时拦截，不是网络断开。前端必须展示原始 `Msg`、`Reason`、`ExpiresAtUtc`、IP 和解除建议；不能把它转换成“后端 API 服务暂时不可用”。直接返回该结果的安全中间件必须在 CORS 之后。

package/skills/v8-utilities/references/server-api-index.md

@@ -166,6 +166,7 @@ outbox 编排放在接口引擎。密钥从当前租户 `V8.SysConfig.ServerPriv
 | TCP | `V8.Tcp.Send/SendAsync/SendAndReceive/SendAndReceiveAsync`；原始字节与出站安全见 `v8-tcp-integration` |
 | IoT 设备原连接下行 | `V8.IoT.Send({DeviceId,CommandId,FrameHex,ExpireSeconds})`；可信接口 Key、协议配置、Redis 路由及执行回执边界见 `v8-tcp-integration`，不包含厂家业务操作 |
 | 图片 | `V8.Image.Create/Merge/Overlay/Watermark/Resize/Crop/Rotate/Flip/Draw/Convert/GetInfo/CreateQRCode` |
+| 字体缓存维护 | `V8.Image.ReleaseFontCache()`，后端无参；批量中文绘制的页边界使用，返回缓存统计而非图片或 RSS；用法及部署检查见 `v8-image-processing` |
 | Office | `V8.Office.ExportExcel/ExcelToList/ExportWord/ExportPowerPoint/SendEmail` |
 | OCR | `await V8.OCR.Recognize({...})`；服务端租户配置与调用参数隔离，详见 `ocr-engine` |
 | 文件 | `V8.HDFS`、`V8.Method.Upload/GetPrivateFileUrl` |

package/skills/vision-engine/references/video-timeline.md

@@ -17,6 +17,7 @@
 - 默认单帧窗口、一个在途请求，按0/1/2秒固定媒体游标连续分析，不按播放时钟跳点；协议最多8帧不是弱CPU应请求8帧。Grant约110秒、作业120秒，超时不延旧框；已Accept的帧仍通过ReadWindow权威回读。
 - 准确率优先模式默认等待已接受、显示窗口已回读的连续区段；可显式切换流畅预览，未知不计入有效统计。无效但已分析的帧可观看，不变成有效观测；最后不足一秒按实际覆盖报告。手动暂停撤销播放意图，等待门不得用晚回执重开。seek仅切显示与ReadWindow，不重置分析游标；单在途回读只保留最新定位意图，最多3次退避，空回执不是成功。
 - TimelineFrame包含实际PTS、requestedTime、frameId、imageSha256和完整来源绑定。平台逐序号CAS保存OriginalFrame/Result/State，不把前瞻统计写到当前session.ResultJson。浏览器只在原PTS到达时显示相应统计；实际解码帧回调建立纹理锚点，遮挡/断流/过期清除，不能把旧框硬贴当前画面。
+- 准确优先暂停等待时也要投影已回读窗口：若视频仍停在同一已解码原时刻，采集该帧的灰度纹理后再恢复播放，不能只依赖播放中的帧回调。原时刻短窗口可直接绘制可信框；短窗口之外必须通过当前纹理跟随，不扩大旧框容差或修改考勤。
 - 手机只用一个视频解码器、小灰度纹理缓冲与有界轮询，不下载神经网络。脸框独立验证；可跟踪同帧真实人体来辅助脸位移，但不能补造未检测到的脸、身体或身份。
 - 切服务前固定原作业连接快照，取消不能请求新节点。倒退清未来行为候选；历史通过ReadSummary只读查看，不猜分析代次或继续旧考勤。恢复识别关闭本人的旧Active会话并新建，导出按权威历史摘要标明分析范围与覆盖率；ThroughTime以前最近已接受帧的累计摘要不等于完整事件清单，行为只含该最新帧复核。