@microi.net/cli 6.1.4 → 6.1.6

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/references/progressive-02-microi-net-api-/346/234/254/345/234/260/345/220/257/345/212/250/347/272/246/345/256/232.md

@@ -1,8 +1,8 @@
-# workspace-conventions 详细参考 2
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=workspace-conventions-039 sha256=ff09cc6c76c9c6d13280f1d0fe45db19775863bca06eae8dadd1c4b2358183d3 -->
+# workspace-conventions 详细参考 2
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=workspace-conventions-039 sha256=ff09cc6c76c9c6d13280f1d0fe45db19775863bca06eae8dadd1c4b2358183d3 -->
 ## 本地测试程序与依赖生命周期（强制）
 
 - 启动前盘点当前源码/Vite/API、数据库、Redis、MongoDB、MinIO、端口及其归属。健康且适用的开发/测试服务优先复用；已有服务不满足时，优先直接启动本地源码，或把本轮编译产物复制到任务隔离目录启动，避免锁住共享构建输出。登记实际源码、配置来源、PID、创建时间、工作目录和监听端口；不能启动另一份旧 DLL 冒充当前候选。
@@ -17,8 +17,8 @@
 - 数据保留与运行资源分开处理：自建且只含可重建测试数据的临时容器、专用测试卷、任务目录和测试命名空间，用完即按登记归属精确删除并独立回读，不能只停止容器或以“下次可能用到”为由积累。共享依赖、既有卷、缓存镜像、用户数据和其它任务资源不在清理范围。若临时资源含唯一业务数据或归属不明，先归档最小必要数据并验证，不能以清理名义删除；需要数据处置决定时明确指出具体对象。Redis 关闭持久化时，保留空卷不能代替保存唯一数据；避免资源紧张时默认 fork 保存。禁止全局 `prune`、通配删除或对共享编排使用 `down -v`。
 - 资源不足时先盘点并收回本任务闲置/遗留的进程和临时容器，再重新测量，不能留下自建数据库占用后要求用户关闭应用。测试结果、清理结果、数据保留和渠道发布分别记录；清理失败必须列出精确资源及原因，不能声称“已全部退出”或用减少用例、关闭断言、放宽发布门禁代替恢复环境。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-024 sha256=92c453b5fafa36d68098b3da5817d0de260a3cf454d8cae63f71a3f65e57bbdc -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-024 sha256=92c453b5fafa36d68098b3da5817d0de260a3cf454d8cae63f71a3f65e57bbdc -->
 ## Microi.net.Api 本地启动约定
 
 默认本地后端项目是 `Microi.Server/Microi.net.Api/Microi.net.Api.csproj`。AI 需要启动后端、验证接口、跑 Playwright、回读接口引擎或排查前后端联调问题时，优先使用下面的 PowerShell 命令：
@@ -35,8 +35,8 @@ Pop-Location
 
 **本地后端自动重启要求（强制）**：本地联调需要启动或重启 `Microi.net.Api` 时，先执行 `node Microi.Server/tools/release-lock.mjs assert api <工作区根>`；API 锁存在时禁止启动或重启后端。PC、官网和 Agent 发布不阻塞 API 服务。无发布时先回读标准端口和 `/api/Diagnostics/liveness`，健康服务默认复用；只有本任务修改了需重载的后端代码、服务不健康或用户明确要求重启时，才可精确停止当前工作区的后端进程，然后在 `Microi.Server/Microi.net.Api` 目录执行 `dotnet run --launch-profile Microi.net.Api`。优先使用用户能在 VS Code 中看到和停止的终端（包含 VS Code 集成终端、VS Code 任务终端、用户明确允许的 VS Code 可追踪隐藏终端）；如果当前工具没有 VS Code 终端能力，允许使用本机可见的 `cmd`/PowerShell 窗口启动，禁止使用脱离用户可见窗口的后台服务或守护进程。不要误杀数据库、Redis、Node 前端或其它业务进程。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-025 sha256=4cf40c4ca771f7e04b80279646323a816378b98669f562ff8f4c647d5bf837ca -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-025 sha256=4cf40c4ca771f7e04b80279646323a816378b98669f562ff8f4c647d5bf837ca -->
 ## 多 AI 对话共享本地服务与发布互斥（强制）
 
 同一工作区的 4、5 个 AI 对话共用同一份源码和固定端口时，`61500/61501` 是工作区级单例共享服务，不属于某个对话。端口相同意味着无法让每个对话拥有一套独立进程；正确模型是“复用健康服务 + 需要重载时串行重启 + 同范围发布时独占”，不能让每个对话都无条件先杀再启动。
@@ -68,8 +68,8 @@ OsClient 等状态；同一 Profile/Context 内切换租户会污染其它窗口
 - 目标 API 还需允许 `http://localhost:61500` 的 CORS。运行目标识别、本地源码验证与线上部署验收
   分层报告。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-026 sha256=73207c0cfcc442a177c47c36503dd6145fc826e23e79df3913861f65d8d16df3 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-026 sha256=73207c0cfcc442a177c47c36503dd6145fc826e23e79df3913861f65d8d16df3 -->
 ## 本地租户与测试凭据读取约定
 
 AI 在本地启动后端、跑 Playwright、做登录态页面截图或调用需要登录的接口前，必须先尝试从本地配置判断租户和测试账号，不要直接以“未登录无法测试”结束：
@@ -80,14 +80,14 @@ AI 在本地启动后端、跑 Playwright、做登录态页面截图或调用需
 4. `MICROI_OSCLIENT`、`PW_OS_CLIENT` 等只属于自动化工具进程，不是 API 生产环境变量；显式设置时可用于选择测试租户。
 5. `.microi-local`、Token、数据库连接串、Redis 密码和测试凭据都视为本地敏感配置。最终回复、日志摘要和测试报告中不得输出真实值，只能写 `<redacted>`、`本地配置账号` 或 `本地配置凭据`。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-027 sha256=84988eac9cf7543a192b3e829b879afb7b35ef92798dc9ea69243f173a8ab674 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-027 sha256=84988eac9cf7543a192b3e829b879afb7b35ef92798dc9ea69243f173a8ab674 -->
 ## 自动化登录约定
 
 本地和远端 E2E 统一传真实 `Account` / `Pwd`。需要跳过图形验证码时，只能在目标租户 `sys_config.AutoTestSkipCaptcha=true` 后传 `_AutomationTestLogin=true`；它只跳过验证码，绝不能绕过密码校验。禁止恢复 `DevLoginBypass`、`X-Microi-Dev-Key`、`_DEV_BYPASS_` 或让脚本自动改写后端 `appsettings`。测试完成后不持久化账号密码。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-028 sha256=6ff58ce80aab2bd47c5af022382159e98e4c4ca5eb955281e61918079d4175a5 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-028 sha256=6ff58ce80aab2bd47c5af022382159e98e4c4ca5eb955281e61918079d4175a5 -->
 ## V8 远端/本地同步收尾约定
 
 AI 通过 MCP、接口引擎、数据库脚本或平台 API 修改任何远端 V8 代码后，任务结束前必须把远端当前生效代码同步回本地 `Microi-V8-Engine/<server>/<osClient>/` 目录，并做一次同步状态复核。
@@ -111,14 +111,14 @@ AI 通过 MCP、接口引擎、数据库脚本或平台 API 修改任何远端 V
 - AI 通过 MCP/API 直接写远端 V8 后，必须立即回读远端当前生效代码到本地并校准 `.microi-meta.json` 与文件 `mtime`。这不是可选清理动作，而是交付完成条件；否则 VS Code 插件会按时间戳继续提示“本地未推送”。
 - 若同步状态非 0，必须先列出具体文件并分类处理：正文一致仅校准 meta/mtime，远端较新则拉回，本地较新则推送，双方都改过则人工合并。生产资金/资产系统不能为清状态盲目覆盖远端。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-029 sha256=e90e532f9448b67f98f28a68fd4ea45b79868cf25fc14c5283b9074e91559f27 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-029 sha256=e90e532f9448b67f98f28a68fd4ea45b79868cf25fc14c5283b9074e91559f27 -->
 ## V8 缓存刷新约定
 
 如果 AI 绕过平台表单提交事件，直接通过 MCP、数据库脚本或自写同步工具更新 `sys_apiengine`、`diy_table`、`diy_field`、`sys_menu`、`wf_node` 等远端 V8 代码，收尾时除了同步本地文件，还必须刷新运行中服务的缓存。至少清理当前 `<OsClient>` 下对应资源的 `Microi:<OsClient>:FormData:<table>:<key>`、`Id` 和地址形式缓存；若可用，优先调用平台缓存接口或插件内置同步流程。清缓存后要重新调用受影响接口做一次真实验证，避免本地/远端代码已一致但 API 仍执行旧缓存代码。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-030 sha256=c25d0aaffec64d8a66cda36acd9ec337eda99a4411fddb0e966e45247ba574de -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-030 sha256=c25d0aaffec64d8a66cda36acd9ec337eda99a4411fddb0e966e45247ba574de -->
 ## MCP 元数据更新验收约定
 
 AI 通过 MCP 修改 `diy_field`、`diy_table`、`sys_menu`、`sys_osclients`、`sys_config` 等平台元数据后，不能只看写入返回成功，必须按前端真实消费方式回读验证：
@@ -127,8 +127,8 @@ AI 通过 MCP 修改 `diy_field`、`diy_table`、`sys_menu`、`sys_osclients`、
 2. 修改字段、表、菜单后，必须调用 `microi_get_field_list` / `microi_get_table_data` 回读关键字段，并调用 `microi_refresh_schema_cache` 或对应清缓存接口刷新 Redis。涉及 SaaS 引擎、系统设置、菜单按钮、接口引擎等运行态缓存时，还要调用对应租户清缓存接口并重新请求受影响页面/API。
 3. 最终交付说明必须写清楚：改了哪个表/字段，回读值是什么，刷新了哪些缓存，验证入口是什么。若某个缓存刷新接口失败或只能部分成功，需要把失败消息原样摘要出来，不能把“写入成功”当作“页面一定生效”。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-031 sha256=cea2d1c912ffc31136a859fd10f282c488b5b8d1bf3f2ced7c39084b23e5ccf5 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-031 sha256=cea2d1c912ffc31136a859fd10f282c488b5b8d1bf3f2ced7c39084b23e5ccf5 -->
 ## MCP 可用性排查约定
 
 VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”，不代表当前 AI 会话一定已经成功加载了对应工具。AI 在声称“可以通过 MCP 操作”之前，必须完成一次真实可调用性验证：
@@ -143,8 +143,8 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - MCP 连接失败时，AI 在完成配置、进程、Header、`initialize`、`tools/list` 和只读状态调用的证据链之前，不得修改 Token、租户、服务器地址或执行远端写入。连接恢复后先完成只读基线盘点，再按用户授权开始写入。
 - 修复 Microi.Agent 插件的 MCP 生成逻辑后，必须重新生成配置、重启对应 MCP server，并在当前 AI 会话中再次验证工具发现与一次只读工具调用。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-032 sha256=230c8683389d2b1ee4f5ba88dc4e51cb4dc4eb6a89b76a142b07f479ff5be1c8 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-032 sha256=230c8683389d2b1ee4f5ba88dc4e51cb4dc4eb6a89b76a142b07f479ff5be1c8 -->
 ## MCP 写入超时与降级约定
 
 - 写请求超时后的远端回读必须使用独立的短超时，不能继续沿用普通查询的长超时。否则一次 60 秒写超时后，每次回读还可能等待 120 秒，AI 会长期停留在“等待远端回读”，用户误以为菜单按钮或接口引擎完全写不进去。
@@ -159,8 +159,8 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - 远端源码不少于 8000 字符，而新源码减少超过 15% 时，应先视为可能只拿到了截断片段并停止写入。只有核对完整源码且确需大幅删减时，才使用写工具提供的显式大幅删减确认参数。
 - 发生连续写入超时时，要先停止并发写入，记录具体工具、资源 Key、耗时和回读结果；禁止用“服务器整体不可用”“缓存锁死”等没有日志证据的结论代替诊断。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-033 sha256=b642bb516a42b50e8b459e5237588e85d71c9715970779e155b88d7c0e8c6536 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-033 sha256=b642bb516a42b50e8b459e5237588e85d71c9715970779e155b88d7c0e8c6536 -->
 ## Codex MCP 单入口约定
 
 - Codex 对普通 MCP 大工具集可能无法稳定注入时，使用插件生成的 `microi_codex` 单入口，不要据此判断服务器或帐号不可用。
@@ -170,8 +170,8 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - 资源模板只是兼容传输层，执行的仍是原始 `microi_*` handler。写操作同样必须携带原工具要求的 `confirmExecution`，不得把 resource read 当成绕过确认的通道。
 - VS Code/Copilot、Cursor、Claude Code 仍使用完整 MCP 工具集；不要把 Codex 的 `enabled_tools = ["microi_codex"]` 复制到其他客户端配置。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-034 sha256=073253c786f85fb23b8b09c71418eaaa00f6a36262bf32e9da857340faa3e75f -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-034 sha256=073253c786f85fb23b8b09c71418eaaa00f6a36262bf32e9da857340faa3e75f -->
 ## .venv Python 环境说明
 
 工作区根目录的 `.venv/` 是 Python 虚拟环境，**保留，不要删除**。已安装：
@@ -181,8 +181,8 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - 其他工具（flake8、pytest 等）
 
 AI 执行 Python 脚本时应使用 `.venv\Scripts\python.exe`（Windows）而非系统 Python。
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-035 sha256=c114dffea6978f289601a8f71aa83a0466f3d934e96e45bb871af179d319a1e3 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-035 sha256=c114dffea6978f289601a8f71aa83a0466f3d934e96e45bb871af179d319a1e3 -->
 ## 后端代码改动后的重启验收
 
 AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果的后端源码、配置、控制器、服务、依赖项目或接口行为，任务收尾前必须完成一次“编译 + 重启本地后端 + 健康验证”，不要只用隔离输出目录 build 后结束。
@@ -201,8 +201,8 @@ AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果
 
 这条规则优先于“避免打断正在运行服务”的默认谨慎策略；本地开发联调场景下，用户通常需要 launch profile 当前端口上的后端加载最新代码。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-036 sha256=b91c431950e4c5d268d40c6372e5780b2c7e8b4ca4339871085cda91b7d932bc -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-036 sha256=b91c431950e4c5d268d40c6372e5780b2c7e8b4ca4339871085cda91b7d932bc -->
 ## MCP 可调用性诊断补充
 
 当用户反馈“Codex/VS Code 设置中能看到 MCP，但当前 AI 会话不能调用对应工具”时，不能只回答“当前会话没有注入”。必须按层排查：
@@ -215,8 +215,8 @@ AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果
 6. 如果握手失败，要把失败层级说清楚：配置文件解析失败、路径不存在、token 文件缺失、MCP 进程启动失败、`initialize` 失败、`tools/list` 缺核心工具，不能把这些问题混成“用户没启用 MCP”。
 7. Microi.Agent 生成 MCP 配置时应清理旧的中文/横杠 Microi MCP key，只保留 `microi_<osClient>` 或 `microi_<osClient>_<host>` 形式，避免不同 AI 客户端因 namespace 不稳定而无法注入工具。
 
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-037 sha256=287a898ffb90322af12deea949c4bcf43b9ac9a355419561898cde8de2b99ac8 -->
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-037 sha256=287a898ffb90322af12deea949c4bcf43b9ac9a355419561898cde8de2b99ac8 -->
 ## Windows MCP 控制台闪窗复盘
 
 当用户反馈“打开 Microi.Agent、添加服务器或初始化 MCP 后连续弹出并立即关闭多个 cmd 窗口”时，应按进程风暴排查，不能只给已有 `spawn` 补 `windowsHide`：
@@ -230,4 +230,4 @@ AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果
 7. Codex 仍只能生成一个 `microi_codex` 路由块，禁止按 Profile 注册多个 Codex MCP。验收必须同时回读配置和进程：凡 `Code.exe`/`Cursor.exe` 命令都带 Node 模式，且不得存在以 `mcp-codex-stdio-adapter.js`、`microi-codex-router.js` 为普通文件参数的可见编辑器根进程；多个对话的 Router 应复用共享 Broker，而不是各自再拉起全部真实 Profile MCP。
 8. 回归测试至少静态断言：Codex CLI 批量注册函数不存在、后台 monitor 不包含 `startServer`、自动配置不包含诊断、Codex 配置内容不变时不改写、Windows GUI 宿主检查早于外部 Node 探测、CLI 与 Codex 路由配置都保留 `ELECTRON_RUN_AS_NODE=1`。再在扩展开发宿主中覆盖打开侧栏、添加连接、初始化 MCP，观察无连续控制台闪窗或脚本文件被自动打开。
 
-<!-- /microi-progressive:chunk -->
+<!-- /microi-progressive:chunk -->

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

@@ -1,8 +1,8 @@
-# workspace-conventions 详细参考 3
-
-> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-
-<!-- microi-progressive:chunk id=workspace-conventions-038 sha256=1b65652abc8ca096a22d79a62b32c74557e5fc3daa7d81f3c192c4b9e37e4665 -->
+# workspace-conventions 详细参考 3
+
+> 按需读取；本文件由 SKILL.md 的原章节无损拆分。
+
+<!-- microi-progressive:chunk id=workspace-conventions-038 sha256=1b65652abc8ca096a22d79a62b32c74557e5fc3daa7d81f3c192c4b9e37e4665 -->
 ## CLI 与 IDE 插件错版共存约定
 
 - CLI 与 IDE 插件共用配置、Token、MCP、Skills 或生成文件时，所有持久化协议必须按“新字段可选、旧字段保留、未知字段不删除”设计。不得将 JSON 解析到旧类型后只序列化已知字段。
@@ -32,4 +32,4 @@
 - 历史瘦身另行确认改写范围，保留同事提交、有效分支、标签和可恢复证据；仅删除当前文件不能释放仍被历史引用的大对象。用户授权瘦身后使用明确引用清单及旧值保护，禁止未经盘点直接执行 `push -f --all` 或 `--mirror`，禁止为解除配额清空、删除或重建仓库。服务端 PR 引用、reflog、恢复记录和配额阻挡应通过管理界面或技术支持处理。
 - 推送失败时保存原生 Git 的完整命令、退出码和 stdout/stderr，隐藏凭据但不删减错误正文，回读远端引用确认实际状态；区分本地 Hook、网络、权限与服务端容量拒绝。同一错误不盲目重跑，向技术支持提供与该次候选绑定的实际压缩体积、引用范围和完整日志，不能把本地精简成功当作远端已瘦身。
 
-<!-- /microi-progressive:chunk -->
+<!-- /microi-progressive:chunk -->