@microi.net/cli 6.1.3 → 6.1.4

package/skills/vision-engine/references/architecture-and-acceptance.md

@@ -1,194 +1,194 @@
-# Microi.Vision 架构与验收参考
-
-## 表模型
-
-| 表 | 主业务键 | 关键字段 |
-|---|---|---|
-| `mci_vision_category` | `CategoryNo` | Name、Scope、ParentId、Sort、Enabled |
-| `mci_vision_subject` | `ObjectNo` | Name、CategoryId、ObjectType、RecognitionMode、ThresholdOverride、ReviewRequired、默认价格/单位/币种 |
-| `mci_vision_sample` | `SampleNo` | SubjectId、Mode、ImagePath、EmbeddingBase64、ModelKey、QualityScore、Status、冰冻/新鲜度/价格及来源请求 |
-| `mci_vision_request` | `RequestNo` | Mode、Status、MatchSource、StreamSessionId、FrameSequence、DetectionsJson、StabilityJson、AI 字段、冰冻/新鲜度/价格及各自来源、纠错审计、耗时 |
-| `mci_vision_profile` | `ProfileKey` | 两类 ModelKey/Threshold、TopK、CandidateLimit、HnswEfSearch、连续投票、AI 开关、取帧间隔、保留策略 |
-
-数据库隔离租户的业务表物理层可能没有 `OsClient` 列；建索引前必须以 `microi_get_db_schema` 和物理索引回读为准。若当前部署是共享表租户模型，才把真实租户字段放到唯一索引前缀，不能机械套用。
-
-## 推荐索引
-
-独立租户库基线：
-
-- category: unique `(CategoryNo)`；普通 `(ParentId, Sort)`；
-- subject: unique `(ObjectNo)`；普通 `(CategoryId, RecognitionMode, Enabled)`；
-- sample: unique `(SampleNo)`；普通 `(ModelKey, Mode, Status)`、`(SubjectId)`；
-- request: unique `(RequestNo)`；普通 `(Status, CreateTime)`、`(SubjectId, CreateTime)`；
-- profile: unique `(ProfileKey)`；普通 `(IsDefault, Enabled)`。
-
-## 状态与来源
-
-| Status | MatchSource | Terminal | 说明 |
-|---|---|---:|---|
-| `Received` | `None` | 否 | 连续帧已处理，投票尚未稳定 |
-| `LocalMatched` | `Database` | 是 | 当前模型版本样本达到阈值 |
-| `AiPending` | `None` | 否 | 后台任务已接受 |
-| `Unmatched` | `None` | 是 | 未命中且 AI 关闭 |
-| `AiMatched` | `AI` | 是 | AI 标签已回写 |
-| `Corrected` | `Manual` | 是 | 用户已把结果修正为当前租户的可信对象 |
-| `Failed` | `None` | 是 | 本地流水线或 Worker 最终失败 |
-| `ManualReview` | `None` | 是 | 高风险场景需要人工复核 |
-| `LowQuality` | `None` | 是 | 低于质量阈值 |
-
-`Status` 与 `MatchSource` 必须一起返回。AI 成功不应填充 `SubjectId`，除非后续人工确认并通过正常业务接口绑定。
-
-生鲜字段同样保留独立来源：`FrozenStateSource`、`FreshnessSource`、`PriceSource` 只能是 `Database/AI/Manual/None`。数据库命中时样本字段优先、对象默认价格次之；未命中后 AI 才能补充。价格是区间与单位估计，不是订单或称重结算事实。
-
-## Runtime 请求
-
-### Recognize
-
-```json
-{
-  "Action": "Recognize",
-  "RequestId": "稳定幂等键",
-  "Mode": "General",
-  "ProfileKey": "default",
-  "FrameId": "camera-01-000123",
-  "StreamSessionId": "scale-01-session-42",
-  "FrameSequence": 123,
-  "Continuous": true,
-  "ResetStream": false,
-  "FileName": "frame.jpg",
-  "FileByteBase64": "...",
-  "ConsentConfirmed": false
-}
-```
-
-Face 模式必须 `ConsentConfirmed=true`；服务端不能只信任前端 checkbox。
-
-### Result
-
-```json
-{ "Action": "Result", "RequestNo": "稳定幂等键" }
-```
-
-轮询应在终态停止，并使用指数或有界间隔；页面卸载、取消或新帧覆盖旧帧时应中止旧轮询。
-
-### Enroll
-
-```json
-{
-  "Action": "Enroll",
-  "SubjectId": "当前租户对象Id",
-  "FileName": "sample.jpg",
-  "FileByteBase64": "...",
-  "ConsentConfirmed": true
-}
-```
-
-服务端读取对象的 Category/Mode，不能信任调用方自行提交 SubjectName、CategoryName 或 ModelKey。
-
-### Correct
-
-```json
-{
-  "Action": "Correct",
-  "RequestNo": "待修正识别记录",
-  "SubjectId": "当前租户正确对象Id",
-  "CorrectionReason": "人工复核原因",
-  "SaveAsSample": true
-}
-```
-
-服务端必须重新读取请求和对象，校验租户、权限、启用状态与识别模式；保存原结果、修正人、时间和原因。`SaveAsSample=true` 时按来源请求幂等录入，不能因重试重复生成样本，也不能绕过正常 `Enroll` 的图片、质量、模型和人脸同意门禁。
-
-## 公开结果最小字段
-
-允许返回：RequestNo、FrameId、StreamSessionId、FrameSequence、Mode、Status、MatchSource、SubjectId/Name、CategoryId/Name、LocalSimilarity、Confidence、对象框/TrackId、Stability、AiLabel/Category/Description/Candidates、FrozenState/Freshness/EstimatedPrice/Unit/Currency 及各自来源、ModelKey/Version、ImageWidth/Height、QualityScore、HasImage、短期授权 ImageUrl、RequestedAt、CompletedAt、ElapsedMs、ErrorMessage 和不含秘密的纠错审计摘要。
-
-禁止返回：EmbeddingBase64、InputFilePath、图片 Base64、模型磁盘路径、AI Provider Key、系统提示词、后台任务内部载荷。
-
-## 模型包 model.json
-
-```json
-{
-  "SchemaVersion": 1,
-  "ModelKey": "general-dinov2-v1",
-  "ModelVersion": "1.0.0",
-  "TaskType": "Embedding",
-  "FileName": "model.onnx",
-  "Sha256": "64位十六进制",
-  "InputName": "input",
-  "OutputName": "embedding",
-  "InputWidth": 224,
-  "InputHeight": 224,
-  "ResizeMode": "CenterCrop",
-  "ChannelOrder": "RGB",
-  "Mean": [0.485, 0.456, 0.406],
-  "Std": [0.229, 0.224, 0.225],
-  "OutputPooling": "ClsToken",
-  "Provider": "ONNX Runtime",
-  "License": "按实际模型/权重填写",
-  "SourceUrl": "权威来源"
-}
-```
-
-流水线模型包可声明 `TaskType=Detection/Segmentation/FaceDetection/Pipeline` 并引用受控 detector/embedding；目前支持 YOLOv8、YOLOX、RT-DETR、SCRFD 常见张量布局，Face 模型使用 `TaskType=FaceEmbedding`。人脸必须经过检测和五点对齐，不能用简单 resize 伪装完成对齐。
-
-## 测试矩阵
-
-### .NET 单元/契约
-
-- 合法 JPEG/PNG/WebP 提取与维数归一化；
-- 非法 Base64、伪造格式、超大图片、像素炸弹拒绝；
-- 路径穿越、错误 SHA、超大模型、不支持任务类型拒绝；
-- 相同向量、相反向量、维数不一致、TopK、候选上限；
-- YOLO/YOLOX/RT-DETR/SCRFD 解码、NMS、对象裁剪、人脸五点对齐；
-- HNSW 精确回退、缓存指纹、IoU TrackId、连续帧窗口与最少票数；
-- CPU 及目标部署环境实际可用的 CUDA/TensorRT/OpenVINO 提供程序；
-- Face/General 与 TaskType 不匹配拒绝；
-- V8 租户上下文覆盖调用参数；
-- 能力返回不泄漏模型磁盘路径。
-
-### 接口引擎
-
-- 同 RequestId 幂等；
-- 数据库优先且 AI 不入队；
-- 未命中 + AI 开启立即返回 AiPending；
-- Worker 成功/失败/重复消费收敛；
-- AI 关闭直接 Unmatched；
-- 低质量不进入匹配；
-- 生鲜字段数据库优先、AI 只在未命中后补充，字段来源不会串改；
-- Correct 校验对象与模式、保存原结果和审计，SaveAsSample 按 RequestNo 幂等；
-- Recent/Result 的历史图片只返回授权 URL，不返回原始私有路径；
-- 受保护向量只能在同租户同核心引擎解开；
-- Hook 不接收敏感载荷且 CreateIfMissing 不被升级覆盖。
-
-### 浏览器
-
-- 已登录真实菜单打开 MicroService，不是独立 Mock 页面；
-- 桌面、窄屏、暗色、键盘焦点和文字对比度；
-- 上传预览、清除、重复选择、错误格式/超限；
-- 摄像头授权拒绝、成功、暂停、继续、强制当前帧、快速关闭与卸载清理；覆盖 getUserMedia/video.play 与关闭竞态；
-- Database/AiPending/AI/Manual/Unmatched/LowQuality/AiFailed 状态和数据库→AI 两段进度；
-- 桌面全宽三栏；390×844 竖屏和短横屏中采集、结果、最近记录同屏，页面级无纵向滚动且不被宿主底栏遮挡；
-- 历史缩略图授权加载、原画弹窗、纠错和可选存样本；
-- FaceConsent 默认未勾选，未同意按钮禁用且后端拒绝；
-- Console/PageError/失败请求为 0 或逐项解释。
-
-### 准确率
-
-至少分离 train/reference 与 test，测试集不能复用完全相同文件充当准确率。商品需覆盖角度、包装、遮挡、数量、背景、秤盘和光照；鱼类需覆盖鲤鱼/鲫鱼等相近类；人脸需覆盖姿态、光照、遮挡并按同意范围采样。
-
-报告：样本数、类别数、Top-1、Top-K、混淆矩阵、阈值、FAR、FRR、P50/P95/P99、硬件、模型/权重版本与失败样本。完全相同图片命中只能算协议/回归测试，不计为泛化准确率。
-
-## 发布证据
-
-分别保存：
-
-- 源码路径与测试命令；
-- NuGet 包清单和公共源回读；
-- Docker tag/digest 与匿名回读；
-- MCP 表/字段/索引/菜单/引擎/事件回读；
-- MicroService SourceManifestHash、RuntimeManifestHash、RouteSnapshotHash 与 committed version；
-- 应用商城 PackageSha256、PackageSize、StoreVersionId、ResourceSnapshotHash；
-- 目标平台版本、实例重启、真实登录浏览器截图；
-- 素材 URL、许可证、作者/署名要求、本地 SHA-256；
-- 未完成的模型包、物理摄像头、GPU 或生产部署边界。
+# Microi.Vision 架构与验收参考
+
+## 表模型
+
+| 表 | 主业务键 | 关键字段 |
+|---|---|---|
+| `mci_vision_category` | `CategoryNo` | Name、Scope、ParentId、Sort、Enabled |
+| `mci_vision_subject` | `ObjectNo` | Name、CategoryId、ObjectType、RecognitionMode、ThresholdOverride、ReviewRequired、默认价格/单位/币种 |
+| `mci_vision_sample` | `SampleNo` | SubjectId、Mode、ImagePath、EmbeddingBase64、ModelKey、QualityScore、Status、冰冻/新鲜度/价格及来源请求 |
+| `mci_vision_request` | `RequestNo` | Mode、Status、MatchSource、StreamSessionId、FrameSequence、DetectionsJson、StabilityJson、AI 字段、冰冻/新鲜度/价格及各自来源、纠错审计、耗时 |
+| `mci_vision_profile` | `ProfileKey` | 两类 ModelKey/Threshold、TopK、CandidateLimit、HnswEfSearch、连续投票、AI 开关、取帧间隔、保留策略 |
+
+数据库隔离租户的业务表物理层可能没有 `OsClient` 列；建索引前必须以 `microi_get_db_schema` 和物理索引回读为准。若当前部署是共享表租户模型，才把真实租户字段放到唯一索引前缀，不能机械套用。
+
+## 推荐索引
+
+独立租户库基线：
+
+- category: unique `(CategoryNo)`；普通 `(ParentId, Sort)`；
+- subject: unique `(ObjectNo)`；普通 `(CategoryId, RecognitionMode, Enabled)`；
+- sample: unique `(SampleNo)`；普通 `(ModelKey, Mode, Status)`、`(SubjectId)`；
+- request: unique `(RequestNo)`；普通 `(Status, CreateTime)`、`(SubjectId, CreateTime)`；
+- profile: unique `(ProfileKey)`；普通 `(IsDefault, Enabled)`。
+
+## 状态与来源
+
+| Status | MatchSource | Terminal | 说明 |
+|---|---|---:|---|
+| `Received` | `None` | 否 | 连续帧已处理，投票尚未稳定 |
+| `LocalMatched` | `Database` | 是 | 当前模型版本样本达到阈值 |
+| `AiPending` | `None` | 否 | 后台任务已接受 |
+| `Unmatched` | `None` | 是 | 未命中且 AI 关闭 |
+| `AiMatched` | `AI` | 是 | AI 标签已回写 |
+| `Corrected` | `Manual` | 是 | 用户已把结果修正为当前租户的可信对象 |
+| `Failed` | `None` | 是 | 本地流水线或 Worker 最终失败 |
+| `ManualReview` | `None` | 是 | 高风险场景需要人工复核 |
+| `LowQuality` | `None` | 是 | 低于质量阈值 |
+
+`Status` 与 `MatchSource` 必须一起返回。AI 成功不应填充 `SubjectId`，除非后续人工确认并通过正常业务接口绑定。
+
+生鲜字段同样保留独立来源：`FrozenStateSource`、`FreshnessSource`、`PriceSource` 只能是 `Database/AI/Manual/None`。数据库命中时样本字段优先、对象默认价格次之；未命中后 AI 才能补充。价格是区间与单位估计，不是订单或称重结算事实。
+
+## Runtime 请求
+
+### Recognize
+
+```json
+{
+  "Action": "Recognize",
+  "RequestId": "稳定幂等键",
+  "Mode": "General",
+  "ProfileKey": "default",
+  "FrameId": "camera-01-000123",
+  "StreamSessionId": "scale-01-session-42",
+  "FrameSequence": 123,
+  "Continuous": true,
+  "ResetStream": false,
+  "FileName": "frame.jpg",
+  "FileByteBase64": "...",
+  "ConsentConfirmed": false
+}
+```
+
+Face 模式必须 `ConsentConfirmed=true`；服务端不能只信任前端 checkbox。
+
+### Result
+
+```json
+{ "Action": "Result", "RequestNo": "稳定幂等键" }
+```
+
+轮询应在终态停止，并使用指数或有界间隔；页面卸载、取消或新帧覆盖旧帧时应中止旧轮询。
+
+### Enroll
+
+```json
+{
+  "Action": "Enroll",
+  "SubjectId": "当前租户对象Id",
+  "FileName": "sample.jpg",
+  "FileByteBase64": "...",
+  "ConsentConfirmed": true
+}
+```
+
+服务端读取对象的 Category/Mode，不能信任调用方自行提交 SubjectName、CategoryName 或 ModelKey。
+
+### Correct
+
+```json
+{
+  "Action": "Correct",
+  "RequestNo": "待修正识别记录",
+  "SubjectId": "当前租户正确对象Id",
+  "CorrectionReason": "人工复核原因",
+  "SaveAsSample": true
+}
+```
+
+服务端必须重新读取请求和对象，校验租户、权限、启用状态与识别模式；保存原结果、修正人、时间和原因。`SaveAsSample=true` 时按来源请求幂等录入，不能因重试重复生成样本，也不能绕过正常 `Enroll` 的图片、质量、模型和人脸同意门禁。
+
+## 公开结果最小字段
+
+允许返回：RequestNo、FrameId、StreamSessionId、FrameSequence、Mode、Status、MatchSource、SubjectId/Name、CategoryId/Name、LocalSimilarity、Confidence、对象框/TrackId、Stability、AiLabel/Category/Description/Candidates、FrozenState/Freshness/EstimatedPrice/Unit/Currency 及各自来源、ModelKey/Version、ImageWidth/Height、QualityScore、HasImage、短期授权 ImageUrl、RequestedAt、CompletedAt、ElapsedMs、ErrorMessage 和不含秘密的纠错审计摘要。
+
+禁止返回：EmbeddingBase64、InputFilePath、图片 Base64、模型磁盘路径、AI Provider Key、系统提示词、后台任务内部载荷。
+
+## 模型包 model.json
+
+```json
+{
+  "SchemaVersion": 1,
+  "ModelKey": "general-dinov2-v1",
+  "ModelVersion": "1.0.0",
+  "TaskType": "Embedding",
+  "FileName": "model.onnx",
+  "Sha256": "64位十六进制",
+  "InputName": "input",
+  "OutputName": "embedding",
+  "InputWidth": 224,
+  "InputHeight": 224,
+  "ResizeMode": "CenterCrop",
+  "ChannelOrder": "RGB",
+  "Mean": [0.485, 0.456, 0.406],
+  "Std": [0.229, 0.224, 0.225],
+  "OutputPooling": "ClsToken",
+  "Provider": "ONNX Runtime",
+  "License": "按实际模型/权重填写",
+  "SourceUrl": "权威来源"
+}
+```
+
+流水线模型包可声明 `TaskType=Detection/Segmentation/FaceDetection/Pipeline` 并引用受控 detector/embedding；目前支持 YOLOv8、YOLOX、RT-DETR、SCRFD 常见张量布局，Face 模型使用 `TaskType=FaceEmbedding`。人脸必须经过检测和五点对齐，不能用简单 resize 伪装完成对齐。
+
+## 测试矩阵
+
+### .NET 单元/契约
+
+- 合法 JPEG/PNG/WebP 提取与维数归一化；
+- 非法 Base64、伪造格式、超大图片、像素炸弹拒绝；
+- 路径穿越、错误 SHA、超大模型、不支持任务类型拒绝；
+- 相同向量、相反向量、维数不一致、TopK、候选上限；
+- YOLO/YOLOX/RT-DETR/SCRFD 解码、NMS、对象裁剪、人脸五点对齐；
+- HNSW 精确回退、缓存指纹、IoU TrackId、连续帧窗口与最少票数；
+- CPU 及目标部署环境实际可用的 CUDA/TensorRT/OpenVINO 提供程序；
+- Face/General 与 TaskType 不匹配拒绝；
+- V8 租户上下文覆盖调用参数；
+- 能力返回不泄漏模型磁盘路径。
+
+### 接口引擎
+
+- 同 RequestId 幂等；
+- 数据库优先且 AI 不入队；
+- 未命中 + AI 开启立即返回 AiPending；
+- Worker 成功/失败/重复消费收敛；
+- AI 关闭直接 Unmatched；
+- 低质量不进入匹配；
+- 生鲜字段数据库优先、AI 只在未命中后补充，字段来源不会串改；
+- Correct 校验对象与模式、保存原结果和审计，SaveAsSample 按 RequestNo 幂等；
+- Recent/Result 的历史图片只返回授权 URL，不返回原始私有路径；
+- 受保护向量只能在同租户同核心引擎解开；
+- Hook 不接收敏感载荷且 CreateIfMissing 不被升级覆盖。
+
+### 浏览器
+
+- 已登录真实菜单打开 MicroService，不是独立 Mock 页面；
+- 桌面、窄屏、暗色、键盘焦点和文字对比度；
+- 上传预览、清除、重复选择、错误格式/超限；
+- 摄像头授权拒绝、成功、暂停、继续、强制当前帧、快速关闭与卸载清理；覆盖 getUserMedia/video.play 与关闭竞态；
+- Database/AiPending/AI/Manual/Unmatched/LowQuality/AiFailed 状态和数据库→AI 两段进度；
+- 桌面全宽三栏；390×844 竖屏和短横屏中采集、结果、最近记录同屏，页面级无纵向滚动且不被宿主底栏遮挡；
+- 历史缩略图授权加载、原画弹窗、纠错和可选存样本；
+- FaceConsent 默认未勾选，未同意按钮禁用且后端拒绝；
+- Console/PageError/失败请求为 0 或逐项解释。
+
+### 准确率
+
+至少分离 train/reference 与 test，测试集不能复用完全相同文件充当准确率。商品需覆盖角度、包装、遮挡、数量、背景、秤盘和光照；鱼类需覆盖鲤鱼/鲫鱼等相近类；人脸需覆盖姿态、光照、遮挡并按同意范围采样。
+
+报告：样本数、类别数、Top-1、Top-K、混淆矩阵、阈值、FAR、FRR、P50/P95/P99、硬件、模型/权重版本与失败样本。完全相同图片命中只能算协议/回归测试，不计为泛化准确率。
+
+## 发布证据
+
+分别保存：
+
+- 源码路径与测试命令；
+- NuGet 包清单和公共源回读；
+- Docker tag/digest 与匿名回读；
+- MCP 表/字段/索引/菜单/引擎/事件回读；
+- MicroService SourceManifestHash、RuntimeManifestHash、RouteSnapshotHash 与 committed version；
+- 应用商城 PackageSha256、PackageSize、StoreVersionId、ResourceSnapshotHash；
+- 目标平台版本、实例重启、真实登录浏览器截图；
+- 素材 URL、许可证、作者/署名要求、本地 SHA-256；
+- 未完成的模型包、物理摄像头、GPU 或生产部署边界。

package/skills/workspace-conventions/SKILL.md

@@ -62,14 +62,14 @@ description: 每次 Microi 任务开始前必读的基础规范。用于识别
 
 工作区保护始终有效：保留他人差异与共享进程，临时产物只放根 `.tmp/`，闭源源码只从独立内部仓提交。修改/提交前读取 [共享工作区与 Git 保障](references/progressive-04-工作区与平台专项保障.md#多对话共享工作区变更归属保护强制)；启动构建、测试服务或浏览器前读取同文件资源/OOM规则并检查现有资源。后端/任务/权限变更读取分布式与安全章节；平台源码定位、文档和 Skills 修改读取对应章节。平台能力四项检查仍固定保留在本入口。
 
-<!-- microi-progressive:begin -->
-
-### 自动清理入口与退出回执
-
-- 自动化入口共用 `Microi.Server/tools/Microi.ArtifactSafety.ps1` 的祖先/目录树预检。Full 的 `Microi.TestArtifactCleanup.ps1` 在移除输出链接前检查整个目标树、受保护属性和 Windows 文件占用；发布脚本的构建/打包/冒烟日志、NuGet 解包临时目录统一进入 `release-scratch.mjs` 新建的独占目录，以目录内标记和目录外归属记录校验身份，退出后保留小型 `.cleanup.json` 回执。没有清单、身份变化或预检失败都保留，不能扫描同名前缀代替所有权。
-- 发布退出顺序为停止本次写入者、普通清理、释放本次发布锁；成功、失败及可捕获的 INT/TERM/HUP 都走同一收尾。清理失败令原成功退出变为非零，原有失败码仍保留；测试原异常不被清理/回执写入错误覆盖。硬杀、掉电和执行器在 shell 启动前拒绝无法保证运行 `finally/EXIT`，接续时先重新盘点已登记路径，不自动清理其它任务或全部历史目录。
-
-<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=e3e6f49e83e80b958184a4d281559fd80aa0a3bb7cbcb0893ecc1821c4b2f001 -->
+<!-- microi-progressive:begin -->
+
+### 自动清理入口与退出回执
+
+- 自动化入口共用 `Microi.Server/tools/Microi.ArtifactSafety.ps1` 的祖先/目录树预检。Full 的 `Microi.TestArtifactCleanup.ps1` 在移除输出链接前检查整个目标树、受保护属性和 Windows 文件占用；发布脚本的构建/打包/冒烟日志、NuGet 解包临时目录统一进入 `release-scratch.mjs` 新建的独占目录，以目录内标记和目录外归属记录校验身份，退出后保留小型 `.cleanup.json` 回执。没有清单、身份变化或预检失败都保留，不能扫描同名前缀代替所有权。
+- 发布退出顺序为停止本次写入者、普通清理、释放本次发布锁；成功、失败及可捕获的 INT/TERM/HUP 都走同一收尾。清理失败令原成功退出变为非零，原有失败码仍保留；测试原异常不被清理/回执写入错误覆盖。硬杀、掉电和执行器在 shell 启动前拒绝无法保证运行 `finally/EXIT`，接续时先重新盘点已登记路径，不自动清理其它任务或全部历史目录。
+
+<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=e3e6f49e83e80b958184a4d281559fd80aa0a3bb7cbcb0893ecc1821c4b2f001 -->
 ## 任务启动前 Skill 读取规则（强制）
 
 AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。
@@ -129,8 +129,8 @@ AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端
 - npm 官方 registry 无法访问、权限不足、文件被运行中进程占用、安装失败或宿主不能热更新时，必须写入可诊断状态并延后重试。可以非模态提示“立即重试/查看日志”，但用户忽略、关闭或暂不处理时，当前、正在进行和新建的 Microi 工作仍必须继续。
 - 用户明确关闭自动更新或宿主不允许终端执行时，尊重该限制，报告具体未完成项和恢复命令；不能静默宣称已是最新版。自动更新只覆盖开发工具、Skills 和本机 MCP 入口，不授权升级客户 API/数据库、部署容器或安装业务应用；已签名 Microi Agent 安装目录仍通过桌面官方更新渠道升级。
 - 只有任务明确依赖旧版本不存在的具体能力时，才准确说明该能力边界与可用降级方案；不得用“最新版未通过”“尚未授权升级”作为整项任务的失败理由。
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-001 sha256=8d8dfff420c0cc768bbeb13d94e9f77f52d5002fc61d93dc82d71b3a17f2eaa0 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-001 sha256=8d8dfff420c0cc768bbeb13d94e9f77f52d5002fc61d93dc82d71b3a17f2eaa0 -->
 ## Microi吾码工作进度播报规范（强制）
 
 AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出工作过程记录时，必须默认执行本规范，无需用户再次提醒：
@@ -142,33 +142,33 @@ AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出
 - 进度、时间和 token 只需快速估算，不得为了提高估算精度中断主要工作，也不得声称这些数据来自平台精确计量。token 较多时可用 `k` 简写。
 - 推荐使用紧凑格式：`Microi吾码本次工作进度：约 55%；预计还需 12 分钟；目前已消耗约 8k tokens；预计总计约 15k tokens。以上为快速估算。`
 - 短任务若在不足 3 次工作过程记录时已经完成，不得为了凑次数拆分无意义消息；可直接在最终交付中简要汇总。
-<!-- /microi-progressive:chunk -->
-
-## AI 编写代码的意图注释规范（强制）
-
-- AI 新增或修改的非简单代码必须同时维护中文意图注释。注释重点解释“为什么这样设计”、安全/事务/租户/协议/兼容边界、非显然顺序和失败语义，不要逐行复述语法。
-- 插件注册、协议网关、鉴权与密钥处理、分布式锁和幂等、升级迁移、兼容转发、可覆盖 Hook、跨系统副作用等代码必须有醒目的边界注释；插件注册注释至少说明所注册能力，存在顺序或条件依赖时一并说明。
-- 公共可复用的 C# 类型和方法优先使用 XML 文档注释；复杂 V8/JavaScript、Vue/TypeScript 与脚本在关键分支前写短注释，说明输入信任边界、回滚/重试规则或特殊兼容原因。
-- 简单赋值、清晰命名的一行调用、显而易见的 CRUD 和模板样板不强制增加注释。禁止为了满足数量机械生成“给变量赋值”“调用方法”一类无信息注释。
-- 重构代码时同步迁移、修订或删除过时注释；注释与实际行为冲突视为代码缺陷。验收时抽查本次非简单变更是否能仅凭代码与注释理解其归属和约束。
-
-## ASP.NET Controller 归属与旧路由收口规范（强制）
-
-- 历史部门树读取可在同一兼容入口复用既有可信 Core 原子，保持 DiyToken、当前租户、组织范围和 `_Child` 契约；仅补确有历史调用的只读地址，不扩张为组织机构写操作或通用 CRUD 兜底。
-
-- 已由 V8 接口引擎完整实现的业务 Controller 必须物理删除，禁止为了“瘦身”再创建 `Microi.AspNetCore` 一类无业务归属的通用 .NET 项目，把原 Controller 原样搬过去。
-- 仍被旧版 PC、UniApp 或定制移动端调用的 `/api/*` 历史地址，只能集中在 `Microi.net.Api/Controllers/LegacyMobileCompatibilityController.cs`；文件顶部必须醒目标明“仅兼容、禁止新增业务、未来可能整体删除”。已配置的 Managed ApiEngine 始终优先；只有主库确认历史地址和固定 Key 都缺失时，登录、DiyToken 会话、公开启动配置、当前用户与菜单读取可复用既有可信 Core 原子兜底，让未完成升级的租户能进入商城修复。禁止仅因升级门禁已有自愈能力就删除此入口；禁用、StopHttp、权限拒绝、数据库异常及执行错误均不得触发兜底，不在请求中安装资源或覆盖租户配置。
-- 所有 ASP.NET Controller 源码必须留在 `Microi.net.Api/Controllers`。不得为了迁走 Controller 新建 `Microi.AspNetCore`、`Microi.SSO` 等中转项目，也不得把 `Microi.AI`、`Microi.net` 或其它 `netstandard` 类库改成 `net10.0`/多目标框架来承载 Controller。
-- V8 无法直接承担的 SSE/WebSocket、OIDC/SAML/CAS、第三方回调验签/解密、浏览器原生身份协议、供应商密钥隔离、文件流等最小协议边界，可以继续作为薄 Controller 留在 API 项目；Controller 只做协议解析、可信鉴权和安全归一化，可复用实现与业务原子必须进入对应功能类库，普通 CRUD、日志、通知和可升级业务编排继续由 Managed ApiEngine 承担。
-- `Microi.net.Api/Controllers` 除五个兼容内核 Controller 与统一旧客户端兼容 Controller 外，只能保留已证明接口引擎无法承担的薄协议 Controller；每个保留项必须同步登记 `api-ownership-catalog.json` 并由结构测试锁定。已完整迁入接口引擎的旧 Controller 必须继续物理删除。
-- `Program.cs` 只保留有说明的插件注册和最薄宿主入口；ASP.NET 组合代码可留在同项目 `Hosting`，可复用业务/运行时逻辑进入 `Microi.Core`、`Microi.net`、`Microi.Upgrade` 或对应插件，禁止通过新建“中转层”掩盖归属问题。
-
-## 详细参考路由（渐进披露）
-
-仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
-
-- [references/progressive-01-版本更新日志保护规则-强制.md](references/progressive-01-版本更新日志保护规则-强制.md)：版本更新日志保护规则（强制）；配置文件说明中文优先规则；后端 API 配置白名单与 SaaS 单一事实源（强制）；身份、可逆业务秘密与敏感操作统一规范（强制）；多语言优先约定；后台菜单层级默认规则；后台任务与安全防护约定；业务逻辑优先接口引擎约定；应用商城优先于 Microi.Upgrade（强制）；在线 AI 应用上下文默认发现规则（强制）；VS Code 插件空目录生成规则；Microi 版本号规则；C# dynamic 强类型落地规则；根目录保留文件说明
-- [references/progressive-02-microi-net-api-本地启动约定.md](references/progressive-02-microi-net-api-本地启动约定.md)：Microi.net.Api 本地启动约定；多 AI 对话共享本地服务与发布互斥（强制）；本地租户与测试凭据读取约定；自动化登录约定；V8 远端/本地同步收尾约定；V8 缓存刷新约定；MCP 元数据更新验收约定；MCP 可用性排查约定；MCP 写入超时与降级约定；Codex MCP 单入口约定；.venv Python 环境说明；后端代码改动后的重启验收；MCP 可调用性诊断补充；Windows MCP 控制台闪窗复盘
-- [references/progressive-03-cli-与-ide-插件错版共存约定.md](references/progressive-03-cli-与-ide-插件错版共存约定.md)：CLI 与 IDE 插件错版共存约定；Git 大文件推送检查
-- [references/progressive-04-工作区与平台专项保障.md](references/progressive-04-工作区与平台专项保障.md)：工作区与平台专项保障
-<!-- microi-progressive:end -->
+<!-- /microi-progressive:chunk -->
+
+## AI 编写代码的意图注释规范（强制）
+
+- AI 新增或修改的非简单代码必须同时维护中文意图注释。注释重点解释“为什么这样设计”、安全/事务/租户/协议/兼容边界、非显然顺序和失败语义，不要逐行复述语法。
+- 插件注册、协议网关、鉴权与密钥处理、分布式锁和幂等、升级迁移、兼容转发、可覆盖 Hook、跨系统副作用等代码必须有醒目的边界注释；插件注册注释至少说明所注册能力，存在顺序或条件依赖时一并说明。
+- 公共可复用的 C# 类型和方法优先使用 XML 文档注释；复杂 V8/JavaScript、Vue/TypeScript 与脚本在关键分支前写短注释，说明输入信任边界、回滚/重试规则或特殊兼容原因。
+- 简单赋值、清晰命名的一行调用、显而易见的 CRUD 和模板样板不强制增加注释。禁止为了满足数量机械生成“给变量赋值”“调用方法”一类无信息注释。
+- 重构代码时同步迁移、修订或删除过时注释；注释与实际行为冲突视为代码缺陷。验收时抽查本次非简单变更是否能仅凭代码与注释理解其归属和约束。
+
+## ASP.NET Controller 归属与旧路由收口规范（强制）
+
+- 历史部门树读取可在同一兼容入口复用既有可信 Core 原子，保持 DiyToken、当前租户、组织范围和 `_Child` 契约；仅补确有历史调用的只读地址，不扩张为组织机构写操作或通用 CRUD 兜底。
+
+- 已由 V8 接口引擎完整实现的业务 Controller 必须物理删除，禁止为了“瘦身”再创建 `Microi.AspNetCore` 一类无业务归属的通用 .NET 项目，把原 Controller 原样搬过去。
+- 仍被旧版 PC、UniApp 或定制移动端调用的 `/api/*` 历史地址，只能集中在 `Microi.net.Api/Controllers/LegacyMobileCompatibilityController.cs`；文件顶部必须醒目标明“仅兼容、禁止新增业务、未来可能整体删除”。已配置的 Managed ApiEngine 始终优先；只有主库确认历史地址和固定 Key 都缺失时，登录、DiyToken 会话、公开启动配置、当前用户与菜单读取可复用既有可信 Core 原子兜底，让未完成升级的租户能进入商城修复。禁止仅因升级门禁已有自愈能力就删除此入口；禁用、StopHttp、权限拒绝、数据库异常及执行错误均不得触发兜底，不在请求中安装资源或覆盖租户配置。
+- 所有 ASP.NET Controller 源码必须留在 `Microi.net.Api/Controllers`。不得为了迁走 Controller 新建 `Microi.AspNetCore`、`Microi.SSO` 等中转项目，也不得把 `Microi.AI`、`Microi.net` 或其它 `netstandard` 类库改成 `net10.0`/多目标框架来承载 Controller。
+- V8 无法直接承担的 SSE/WebSocket、OIDC/SAML/CAS、第三方回调验签/解密、浏览器原生身份协议、供应商密钥隔离、文件流等最小协议边界，可以继续作为薄 Controller 留在 API 项目；Controller 只做协议解析、可信鉴权和安全归一化，可复用实现与业务原子必须进入对应功能类库，普通 CRUD、日志、通知和可升级业务编排继续由 Managed ApiEngine 承担。
+- `Microi.net.Api/Controllers` 除五个兼容内核 Controller 与统一旧客户端兼容 Controller 外，只能保留已证明接口引擎无法承担的薄协议 Controller；每个保留项必须同步登记 `api-ownership-catalog.json` 并由结构测试锁定。已完整迁入接口引擎的旧 Controller 必须继续物理删除。
+- `Program.cs` 只保留有说明的插件注册和最薄宿主入口；ASP.NET 组合代码可留在同项目 `Hosting`，可复用业务/运行时逻辑进入 `Microi.Core`、`Microi.net`、`Microi.Upgrade` 或对应插件，禁止通过新建“中转层”掩盖归属问题。
+
+## 详细参考路由（渐进披露）
+
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
+
+- [references/progressive-01-版本更新日志保护规则-强制.md](references/progressive-01-版本更新日志保护规则-强制.md)：版本更新日志保护规则（强制）；配置文件说明中文优先规则；后端 API 配置白名单与 SaaS 单一事实源（强制）；身份、可逆业务秘密与敏感操作统一规范（强制）；多语言优先约定；后台菜单层级默认规则；后台任务与安全防护约定；业务逻辑优先接口引擎约定；应用商城优先于 Microi.Upgrade（强制）；在线 AI 应用上下文默认发现规则（强制）；VS Code 插件空目录生成规则；Microi 版本号规则；C# dynamic 强类型落地规则；根目录保留文件说明
+- [references/progressive-02-microi-net-api-本地启动约定.md](references/progressive-02-microi-net-api-本地启动约定.md)：Microi.net.Api 本地启动约定；多 AI 对话共享本地服务与发布互斥（强制）；本地租户与测试凭据读取约定；自动化登录约定；V8 远端/本地同步收尾约定；V8 缓存刷新约定；MCP 元数据更新验收约定；MCP 可用性排查约定；MCP 写入超时与降级约定；Codex MCP 单入口约定；.venv Python 环境说明；后端代码改动后的重启验收；MCP 可调用性诊断补充；Windows MCP 控制台闪窗复盘
+- [references/progressive-03-cli-与-ide-插件错版共存约定.md](references/progressive-03-cli-与-ide-插件错版共存约定.md)：CLI 与 IDE 插件错版共存约定；Git 大文件推送检查
+- [references/progressive-04-工作区与平台专项保障.md](references/progressive-04-工作区与平台专项保障.md)：工作区与平台专项保障
+<!-- microi-progressive:end -->