@microi.net/cli 5.9.1 → 5.9.3

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

@@ -6,7 +6,7 @@ description: 每次 Microi 任务开始前必读的基础规范。用于识别
 # Microi 工作区全局约定
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=44d962f17b8e721ae87a79fcc8f2b4fc303ef9900203ca21b725276ddb42190f -->
+<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=e8e784198efa6cd233fa9da3be0292cd6c68cea2c10e35f8f94eaacd1d381033 -->
 ## 任务启动前 Skill 读取规则（强制）
 
 AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。
@@ -64,9 +64,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=fbe1ea5c5eeefb9d5da222748d61c4215befd9aaf419dd80a1d5a663517ba58a -->
+<!-- microi-progressive:chunk id=workspace-conventions-001 sha256=c3db79fb5f6f00a6ea619f7129f1e81259efe899256a5100f9c84a5b5dca58f4 -->
 ## Microi吾码工作进度播报规范（强制）
 
 AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出工作过程记录时，必须默认执行本规范，无需用户再次提醒：
@@ -78,9 +77,8 @@ AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出
 - 进度、时间和 token 只需快速估算，不得为了提高估算精度中断主要工作，也不得声称这些数据来自平台精确计量。token 较多时可用 `k` 简写。
 - 推荐使用紧凑格式：`Microi吾码本次工作进度：约 55%；预计还需 12 分钟；目前已消耗约 8k tokens；预计总计约 15k tokens。以上为快速估算。`
 - 短任务若在不足 3 次工作过程记录时已经完成，不得为了凑次数拆分无意义消息；可直接在最终交付中简要汇总。
-
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-002 sha256=3512f626491064504d48119f11cd9f4dde9534b7cb4a88d8bc940892ac99bd9c -->
+<!-- microi-progressive:chunk id=workspace-conventions-002 sha256=795821e68c0c347c68f8cdcb6e2f81defa9a172650216288c10d313075e3247d -->
 ## 分布式部署与重启安全规范（强制）
 
 Microi 平台后端功能必须默认按多节点部署设计：多个 API/Worker 节点位于同一负载均衡入口之后，共享业务数据库、MongoDB 和 Redis，并可能在请求执行过程中滚动发布、硬重启或发生网络分区。不得先按单机实现、上线后再补分布式保护。
@@ -96,9 +94,8 @@ Microi 平台后端功能必须默认按多节点部署设计：多个 API/Worke
 - 验收至少启动 2 个节点连接同一组 Redis/数据库，并覆盖：同一定时任务同时到点、同一请求/消息重复投递、锁持有者中途退出、MongoDB/Redis 短暂故障、写入后响应前重启、滚动升级和未排空时强制结束。最终断言应包括业务副作用仅一次、日志/消息可幂等恢复、无永久死锁、无重复初始化、旧新版本可共存。
 - 若要求宿主机掉电或 `kill -9` 窗口内也绝对零丢失，必须在返回业务成功前取得外部持久消息队列、共享 outbox 或同步 WAL 的持久化确认；“内存队列随后异步落盘”不能宣称覆盖尚未持久化的强杀窗口。
 
-
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-003 sha256=66922955adb5ff6198efefd6d4d8d8f6525ef7559663ea034e86e1e45f89eb9f -->
+<!-- microi-progressive:chunk id=workspace-conventions-003 sha256=a3388a2f929f7316d2726fb09698732002fb19494682b6cc59220671bb106100 -->
 ## 本地资源与 OOM 保护规范（强制）
 
 AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker build、浏览器自动化、压力测试或其他可能长时间占用 CPU/内存的进程前，必须先评估资源，不得为了“让构建跑过”无限抬高堆内存或 Worker 数。
@@ -116,18 +113,21 @@ AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker
 - 只有全部框架前端源码修改、定向测试和浏览器验收均已完成后，才允许在最终收尾阶段执行一次 `npm run build`，用于确认正式产物能否生成。执行前仍须按本节检查内存、同类进程和构建预算；已经成功且之后没有再修改框架前端源码时不得重复构建。
 - Vite 热更新未生效时，先检查页面、控制台、文件监听和当前 61500 开发服务归属；确需重启时按共享进程与发布锁规范精确停止本工作区原有 `npm run dev`，再重新执行 `npm run dev`。不得用 `npm run build` 代替开发服务重启，也不得结束所有 `node`、浏览器或其它对话的进程。
 - 本规则只约束 `Microi.Client/` 吾码框架前端源码。独立 MicroService、Web、UniApp 等应用源码仍按其交付 Skill 在发布前执行自身必要的构建；不得因为本规则跳过微服务正式产物生成。
-
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-004 sha256=a12a204339ee40367f4c09d085d818515b0d94c7c0d748d0d455fede6b98a2e4 -->
+<!-- microi-progressive:chunk id=workspace-conventions-004 sha256=093ef306e8f2f873b76524ce69ce7fd5194cfa0b361bd564f0c767f88439a817 -->
 ## 临时文件与 AI 产物放置规则（强制）
 
+- 长期交付资料归对应 `AI-Project/` 项目；不得重新生成公开根仓 `output/`。本工作区既有资料在 `AI-Project/microi/文档/历史交付资料/output/`，第三方推广 Skill 在 `AI-Project/microi/推广/skills/yixiaoer/`，均不随公开源码分发。
+- `Microi.net.Api` 只负责协议、请求上下文、鉴权接入、DI 和宿主生命周期；状态机、Redis、持久化、业务权限与调度归 Core 或插件，其它项目不得反向依赖 API 宿主。业务编排继续优先接口引擎。
+
 AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、测试截图、临时报告**，**严禁放在工作区根目录（`<workspace-root>/`）**，必须放在指定位置：
 
 | 类型 | 指定位置 |
 |------|---------|
 | 一次性脚本（.py / .mjs / .ps1 / .sh） | `.tmp/` |
 | 诊断截图、调试图片 | `.tmp/screenshots/` |
-| E2E 测试产物（Microi.Agent 插件生成） | `.microi-e2e/` |
+| E2E 配置、用例和帮助器（Microi.Agent 插件生成） | `<projectRoot>/.microi-e2e/` |
+| E2E 截图、报告、trace、video、test-results | `<gitRoot>/.tmp/microi-e2e/<项目相对路径>/` |
 | AI 一次性 E2E 脚本、截图、日志、报告 | `.tmp/`、`.tmp/screenshots/`、`.tmp/reports/` |
 | 性能测试 HTML 报告 | `.microi-performance/` |
 | 项目专属临时文件 | `<对应子项目目录>/` 内，不要写到根目录 |
@@ -234,7 +234,7 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 - `Microi.net.Api/Controllers` 除五个兼容内核 Controller 与统一旧客户端兼容 Controller 外，只能保留已证明接口引擎无法承担的薄协议 Controller；每个保留项必须同步登记 `api-ownership-catalog.json` 并由结构测试锁定。已完整迁入接口引擎的旧 Controller 必须继续物理删除。
 - `Program.cs` 只保留有说明的插件注册和最薄宿主入口；ASP.NET 组合代码可留在同项目 `Hosting`，可复用业务/运行时逻辑进入 `Microi.Core`、`Microi.net`、`Microi.Upgrade` 或对应插件，禁止通过新建“中转层”掩盖归属问题。
 
-<!-- microi-progressive:chunk id=workspace-conventions-009 sha256=0343192b5c71d39f9f31a21bccb5046715f1b47d4876ba962b2d5f188c021271 -->
+<!-- microi-progressive:chunk id=workspace-conventions-009 sha256=43bdb1476a7751fbc251c933ccfbd1710c9269dec3e7e4b541cdaeea37d200f1 -->
 ## 多对话共享工作区变更归属保护（强制）
 
 ### 功能验收后的源码提交与推送（强制）
@@ -242,8 +242,8 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 - 每个已完成并通过相应验收的功能、修复或独立里程碑，必须把本任务源码、测试和必要文档按实际 Git 仓库分别提交并推送；不能仅保存在工作区、stash、临时目录或已发布产物中。用户明确要求不提交/不推送、只读任务和未完成的实验除外，不为无改动仓库制造空提交。
 - 提交前回读工作树、暂存区、上游和远端；按可核验的本任务 hunk 暂存，保留其它对话的改动与既有暂存项。公开根仓只提交公开代码；闭源目录只从各自独立仓库根提交并推送到其已有内部远端，严格执行公开仓闭源路径门禁，不能用 gitlink 或强制添加绕过隔离。
 - 推送前先获取上游的新提交并安全整合；共享工作区有并行改动时优先在隔离候选中合并，不用整树 stash/reset 覆盖他人成果，不强推共享分支，不绕过仓库 Hook。需要精确回滚时保留独立、说明清楚的功能提交；回滚已推送功能通常使用新的反向提交，不改写共享历史。
-- 正式发布前，候选必须包含此前已交付功能的提交，并完成本任务提交、推送及远端提交号回读，再从该冻结候选构建与发布。仅更新某个说明页面时也要核对整个站点的候选；隔离工作树不能因为没有未提交变更就被当成最新线上功能。发布锁只防并发，不能代替源码完整性检查。
-- 收尾逐仓记录本地提交号、远端分支和回读结果，并区分源码推送、构建发布与真实线上验收。网络、权限、冲突或门禁阻止推送时，保留本地提交、准确报告未推送项并继续完成可独立推进的工作；不得宣称完整交付，也不得为赶进度先发布未交付源码。
+- 正式发布的候选必须包含此前已交付功能和本任务已核验的源码，先按仓安全本地提交，再冻结完整构建输入与内容哈希；仅更新说明页面时也要核对整个站点候选。Git 远端推送与提交号回读默认在制品发布前完成；若用户明确授权“Git 推送失败不阻断 NuGet/Docker”，仅允许把这两类平台制品的远端推送移到并行或后续步骤，不放宽 Full、闭源隔离、加密、候选/产物一致性及渠道回读。隔离工作树没有未提交变更不等于已包含最新功能；发布锁也不能代替源码完整性检查。
+- 收尾逐仓记录本地提交号、远端分支和回读结果，区分源码、NuGet、Docker 与客户部署。远端网络、认证或容量故障时作有界诊断，保留本地提交、失败原因和待补推清单；在上述用户明确授权且本地候选已完成全部制品门禁时，可继续独立发布 NuGet/Docker，但必须如实标记源码尚未推送，不能宣称完整交付。源码冲突、归属不明、保护路径违规或候选漂移不是“Git 推送故障”，必须先处理，不能借例外发布不确定源码。
 
 - **Git 大文件推送确认（强制）**：每次 Git 推送前检查全部待推送提交中新引入的 Blob；单个达到 10 MiB 或合计达到 50 MiB 时，必须提供路径、实际大小、SHA-256 和目标仓库/分支，取得用户对具体清单的确认后才推送。一般提交推送授权不能代替大文件确认；完整检查、CDN 引用、历史瘦身与失败回执规则见[Git 大文件推送确认](references/progressive-03-cli-与-ide-插件错版共存约定.md#git-大文件推送确认强制)。
 

package/skills/workspace-conventions/references/progressive-03-cli-/344/270/216-ide-/346/217/222/344/273/266/351/224/231/347/211/210/345/205/261/345/255/230/347/272/246/345/256/232.md

@@ -2,7 +2,7 @@
 
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
-<!-- microi-progressive:chunk id=workspace-conventions-038 sha256=97d43d23dc7e50e2806b9ef41c0d5afce73a3dde0ee0b2c6f3fdb468278ee248 -->
+<!-- microi-progressive:chunk id=workspace-conventions-038 sha256=1dd79589434568ac963b144f4278707e4836bf477181b5e7a3a82c0275d3189e -->
 ## CLI 与 IDE 插件错版共存约定
 
 - CLI 与 IDE 插件共用配置、Token、MCP、Skills 或生成文件时，所有持久化协议必须按“新字段可选、旧字段保留、未知字段不删除”设计。不得将 JSON 解析到旧类型后只序列化已知字段。
@@ -28,7 +28,7 @@
 
 - 每次 Git 推送前检查暂存内容及全部待推送提交中新引入的 Blob，不能只看工作树、最新提交或首尾文件差异；中间提交加入后又删除的大文件仍会进入历史。以刚核验的远端引用为基线，结合 `git rev-list --objects` 与 `git cat-file --batch-check` 检查真实对象大小；基线或对象不完整时先补齐并复核，不能绕过检查。
 - 默认将单个新增 Blob 达到 **10 MiB**，或本次新增 Blob 合计达到 **50 MiB** 视为需要确认的大文件推送。列出具体路径、实际字节数、SHA-256、目标仓库/分支及合计体积，向用户明确询问是否推送，收到答复前暂停受影响的 Git 推送。一般“提交并推送”授权不能代替这份具体大文件清单的确认；用户已明确确认同一清单和内容时可继续，路径、哈希、数量或体积变化后须重新确认。不要因远端已有且本次未增加的历史大文件反复索要授权。
-- PDF、PPT/PPTX、视频、压缩资源、导出报告等交付附件默认通过当前授权租户的 MCP 上传到 CDN，核验实际下载字节数和 SHA-256 后使用 FileServer/CDN 地址引用。源码仓库保留必要源码、引用及可重复生成的说明；不能静默提交导出产物。运行必需的字体、模板和第三方二进制按用途判断，达到上述阈值仍须列入确认，不得擅自删除或转移。
+- 图片、PDF、PPT/PPTX、视频、压缩资源、导出报告等交付附件默认通过当前授权租户的 MCP 上传到 CDN，核验实际下载字节数、SHA-256 和真实 MIME 后使用 FileServer/CDN 地址引用。源码仓库保留必要源码、引用、内容指纹清单及可重复生成的说明；不能静默提交导出产物。生成和验签下载缓存放在工作区 `.tmp/`，不得把已迁移资源通过旧分支或 PR 重新合并进公开历史。运行必需的字体、模板和第三方二进制按用途判断，达到上述阈值仍须列入确认，不得擅自删除或转移。
 - 历史瘦身另行确认改写范围，保留同事提交、有效分支、标签和可恢复证据；仅删除当前文件不能释放仍被历史引用的大对象。用户授权瘦身后使用明确引用清单及旧值保护，禁止未经盘点直接执行 `push -f --all` 或 `--mirror`，禁止为解除配额清空、删除或重建仓库。服务端 PR 引用、reflog、恢复记录和配额阻挡应通过管理界面或技术支持处理。
 - 推送失败时保存原生 Git 的完整命令、退出码和 stdout/stderr，隐藏凭据但不删减错误正文，回读远端引用确认实际状态；区分本地 Hook、网络、权限与服务端容量拒绝。同一错误不盲目重跑，向技术支持提供与该次候选绑定的实际压缩体积、引用范围和完整日志，不能把本地精简成功当作远端已瘦身。