@microi.net/cli 6.1.0 → 6.1.1

package/skills/workspace-conventions/SKILL.md

@@ -1,168 +1,168 @@
----
-name: workspace-conventions
-description: 每次 Microi 任务开始前必读的基础规范。用于识别创始人源码工作区，检查平台功能的应用商城、官方文档、Skills 与 MCP 交付，并遵守共享工作区、进程、资源和发布边界。
----
-
-# Microi 工作区全局约定
-
-## 每次修改微服务前重新拉取（强制入口）
-
-与每次对话的 CLI 版本检查一样，所有 AI 模型和宿主在**每次开始修改已有 MicroService**（包括接续任务、只改一行、路由修复和紧急发布）前，必须读取 `../microi-microservice/SKILL.md` 的协作门禁，重新拉取当前租户完整私有源码到本地，逐文件核对路径、原始字节大小和 SHA-256，并与本地和上次同步基线三方比较。保留本地独有改动、合并远端变化；正文缺失、哈希不一致或冲突未解决时，不开始修改。完整工程下载在工具进程内完成，不把源码 Base64 全量塞入模型上下文。
-
-完成比较后保存**修改前**的 `SourceManifestHash`，调用 `microi_sync_microservice_source` 时传 `expectedSourceManifestHash`。现有源码缺少基线或远端已变化时工具拒绝写入；不能只重新取一个新哈希来重试旧本地代码。发布前再次校验，保留其它页面、`LegacyComponentPaths/LegacyMenuUrls` 以及实际组件注册。此要求必须同时出现在 CLI/IDE 生成的各 AI 宿主入口中；文字规则不能冒充已执行拉取、校验或渠道分发。
-
-## Git 原分支交付（强制）
-
-禁止 AI 自动创建并推送额外远端分支。开工记录用户原本的分支及上游；优先在原分支完成工作，确有并发隔离或冻结测试输入需要时，才使用本地临时分支或 detached worktree。验收后必须安全合回原分支，只推送该原分支；不得将临时分支、发布候选、备份分支或标签推到远端代替合并。只有用户明确要求创建某个远端分支时才例外。清理前核对未合并提交、活动工作树及其它任务，保留有效成果后删除本任务临时分支和工作树。详细步骤见[共享工作区与 Git 保障](references/progressive-04-工作区与平台专项保障.md#功能验收后的源码提交与推送强制)。
-
-## 截图与大体积资源必须走 CDN（默认强制）
-
-- 截图、宣传配图、PDF、PPT/PPTX、视频、音频、模型、压缩包、安装包、导出报告及其它大体积资源不得提交或推送到 Gitee、GitHub 等源码仓库。截图和交付附件无论压缩后是否低于大小阈值都走 CDN；禁止通过 Base64、Git LFS、分卷、改后缀、强制暂存或中间提交绕过。一般“提交并推送”的授权不能解除此规则，也不再走“先上传大文件到 Git 再处理”的路径。
-- 吾码官方公开资源必须通过已核验 `https://api.microi.net + OsClient=iTdos` 的 `microi_itdos` MCP 上传公有桶，并使用 `https://file.microi.net` 前缀访问。普通客户资源使用已授权租户 MCP 与实际 CDN/FileServer，敏感、私有资料保持私有权限，不能为了公开链接改为公有桶。大文件使用已有流式/分片上传能力，不绕过 MCP 直接使用存储密钥。
-- 源码只保存必要代码、轻量可编辑模板、CDN URL、文件名、字节数、SHA-256、MIME 和必要生成说明；原图、压缩件、PDF、下载校验缓存放任务专属临时目录，交付后按清理规则回收。上传成功后必须独立下载核对字节数、哈希和真实 MIME；PDF 同时检查 Range 分段读取。未知上传结果先回读，不能盲重传。
-- 提交前检查暂存区，推送前以刚核验的远端引用检查全部待推送提交的新增 Blob；既查资源类型，也查单个 10 MiB / 合计 50 MiB 的体积门槛。发现禁止入库资源就停止受影响的提交/推送，迁移 CDN 并从本次候选索引/提交中排除；中间提交加入后又删除也不合格。不得改写共享历史、删除用户本地原图或清空既有仓库。必要运行依赖另按真实用途审查，但不能借此提交截图和交付附件。
-
-完整上传与回读流程见 [文件上传下载规范](../v8-file-upload/SKILL.md)，Git 对象检查与历史边界见 [Git 大文件推送检查](references/progressive-03-cli-与-ide-插件错版共存约定.md#git-大文件推送检查强制)。
-
-## 测试临时文件必须随任务清理（强制）
-
-本节适用于开发、测试、诊断和发布产生的全部自有临时资产，包括工作区根 `.tmp/`、宿主临时目录（如 `$CODEX_HOME/tmp`）和隔离 Git worktree，并替代历史“任务完成后可以不清理”的约定。目录位置和 `.gitignore` 不改变收尾责任。
-
-- 创建前使用独立的 `.tmp/<任务标识>/`，登记本任务创建的目录、文件、进程及用途；不得混用其它任务目录，既有文件或共享依赖不因本轮使用而取得删除权。每轮测试及任务成功、失败、取消或中断退出时都执行 `finally` / teardown，先核验并关闭本任务的写入者、浏览器和临时服务，再删除本轮已无用途的临时文件；不能等用户再次要求清理磁盘。
-- 默认删除本任务的一次性脚本、下载/解压副本、编译输出、隔离依赖、测试夹具和冗余截图/trace/video/日志。交付必需的少量报告、关键截图、发布哈希/回执先脱敏并归档到对应项目的长期交付目录，回读归档完整后再删临时副本；不得把完整构建树、源码副本或依赖目录当作验收证据长期留存。
-- 失败仍需排查或下一阶段确实依赖的文件，只保留可解释的最小集合，记录路径、体积、原因、归属和清理时机；排查/依赖结束后立即删除。崩溃来不及执行 teardown 时，下次接续先核对自有清单并补清；不能以“测试失败”“以后可能有用”为由无限保留。
-- 隔离副本只为实际并发冲突或构建输入冻结创建，优先复用合适的工作树、稀疏检出和最小夹具；禁止每次重试复制整套源码、Git 历史、依赖、SDK 和运行目录。创建前盘点源盘与目标盘可用空间及已有同类副本，按本轮实际需求估算新增体积；测试结束先回收旧运行/编译目录，再创建下一轮。不要把临时目录移到另一块盘当作清理。
-- 工作树不是永久保留项：任务结束逐仓检查未提交、未跟踪、忽略文件和未推送提交，已合入/已归档且无活动引用的副本按 Git/宿主支持的方式移除并回读注册表；必要差异先最小归档并校验可恢复性，不复制完整构建树。嵌套独立 Git 仓库逐个核对；禁止因存在 `.git` 就跳过整个任务目录，也禁止把主工作区存在当成差异已安全保存的证明。
-- **规则必须落到执行入口**：新增或维护测试、构建、发布脚本时，将自有临时资产回收写入实际的 `finally`、测试框架 teardown/after hook 或宿主归档流程，并验证成功与失败退出均回收。`Microi.Tests/run-tests.ps1` 的 Full 隔离 `.net-artifacts` 由入口自动回收，保留结果报告与 `artifact-cleanup.json`；已有共享目录不取得删除权。仅修改 Skill、模型读过规则或工具显示最新版，都不能声称自动清理已生效；须检查已安装正文及实际执行结果。硬崩溃/强杀可能跳过收尾，恢复时按归属清单补清，不能承诺任意中断都即时删除。
-- 删除前核验解析后的绝对路径位于已登记的本任务临时目录或独占副本内，不能仅依赖字符串前缀；检查目标及祖先的重解析点/符号链接、当前进程 CWD/文件锁、Git worktree 与未提交源码、发布锁以及虚拟机/容器引用。禁止跟随链接递归到共享或外部目录；无法确认真实边界时保留。保留用户文件、唯一源码/未提交改动、正式交付物、共享资源和其它任务资产；独占 Git 工作树先按 Git/宿主支持的移除方式完成检查，不能直接递归删除。
-- 历史垃圾清理先做体积与引用盘点，只删已核验无引用、无跟踪源码且可再生成的产物；文件名含 `.tmp`、目录名为 `bin/obj` 或时间较旧都不能单独证明可删。禁止整体清空共享 `.tmp/`，禁止为了清理结束其它任务或重启 Docker/WSL。
-- 清理后独立回读已删路径不存在、保护对象仍在；必要时比对源码、用户原图、正式交付物的哈希及其它工作树登记。收尾报告已删路径/文件数、逻辑字节数、磁盘可用空间变化、剩余保留项及清理时机；并行写入、硬链接等会使逻辑大小与实际净空间变化不同，不能混报。遇到文件锁、权限或策略拒绝时记录执行阶段、原始错误和未完成范围，禁止换工具绕过。测试通过与临时文件清理完成是两个验收项，不能互相代替。
-
-### Windows 默认普通删除与策略拒绝排查（强制）
-
-- 自动收尾默认使用原生 PowerShell 普通删除：已完成上述核验的普通文件使用 `Remove-Item -LiteralPath $verifiedTaskFile -ErrorAction Stop`，已核验的独占目录才使用 `Remove-Item -LiteralPath $verifiedTaskDirectory -Recurse -ErrorAction Stop`。变量必须来自本任务明确登记并重新解析的单个绝对路径，禁止空值、通配符、盘符根目录、用户目录根、源码根或共享 `.tmp` 根；不能把这两行当作跳过核验的通用清盘命令。
-- **删除命令不默认添加 `-Force`，自动 teardown 也不得失败后升级为强制删除。** 不通过清除只读/隐藏/系统属性、修改 ACL、改审批配置、编码命令、换语言/API、换 shell 或间接脚本完成被拒绝的同一动作。只读盘点可使用 `Get-ChildItem -Force` 发现隐藏项；它不授予强制删除权。普通删除遇到受保护属性、占用或权限错误，保留相应项并报告，不能因其体积小或由 AI 创建就忽略限制。
-- `CreateProcess ... rejected: blocked by policy` 表示执行器在启动 shell 前拒绝；命令里的路径/归档检查也没有运行，不能把它当作 Windows ACL 报错或清理成功。已核验的 Codex Windows `0.163.0-alpha.10.2` 将 `Remove-Item … -Force` 识别为危险删除，并在 `approval_policy=never` 下直接拒绝；`danger-full-access` 不取消命令策略，`never` 也不等于全部允许。其它版本/宿主必须依据当前有效配置、日志或对应版本实现定位，不能把所有同名错误都归因于 `-Force`。实现依据：[强制删除识别](https://github.com/openai/codex/blob/rust-v0.163.0-alpha.10.2/codex-rs/shell-command/src/command_safety/windows_dangerous_commands.rs#L489)、[禁止审批时的决策](https://github.com/openai/codex/blob/rust-v0.163.0-alpha.10.2/codex-rs/core/src/exec_policy.rs#L799)。
-- 若已明确拒绝针对强制删除，只有在原有授权和归属/路径核验仍成立、且普通删除确实保留系统保护语义时，才可收窄为上述原生非强制操作；这不授权扩大删除范围。拒绝原因未知、存在明确禁止，或普通操作仍被拒绝时停止该项，保留并报告，不反复变换写法试探策略，也不修改规则放行。
-- `git worktree remove` 的 `Result too large` 等是命令执行后的失败，与策略拒绝分开处理。失败后分别回读工作树登记与目录，不能假定“登记没了，文件也没了”；先验证差异/未推送提交已可恢复、残留源码与对应提交一致、无其它任务引用和外部链接，才将已注销的残留产物纳入普通清理清单。归属或恢复证据不足时保留，不强删独占副本或嵌套仓库。
-
-## 质量优先与适用范围
-
-**测试依赖默认复用 MCP（强制）**：普通联调、Full 和发布测试使用当前已核验 MCP 对应的 MySQL、Redis、MongoDB、HDFS/OSS/MinIO 服务，并在已授权范围以独立测试库、租户、Key/对象前缀隔离。固定夹具库名被占用、归属标记冲突、端口冲突、本机无容器或旧夹具被清理，都不是“迫不得已”另建本地测试容器的理由；先修正测试入口的可配置隔离和归属校验，不能覆盖他人的夹具或放宽保护。不能复用时按[依赖生命周期](references/progressive-02-microi-net-api-本地启动约定.md#本地测试程序与依赖生命周期强制)核实具体限制；用户明确禁止的本地容器不会因测试或发布授权自动解禁。
-
-准确性、业务完整性、安全和真实验收优先于 token 与回复长度。先确定完整系统、局部修改或只读分析；新建系统意图按完整交付，不能因短提示词或预算缩小八项清单及菜单/报表增补。局部修改定位真实目标和依赖，信息不足、动态关系或影响不明时扩大读取，不凭摘要猜测或写入。
-
-必须读取总控的 [质量与增量开发规范](../microi-system-delivery/references/context-quality.md)，按任务映射实际读取与验收记录。同一会话只复用内容哈希未变且已完整读取的规范；首次、版本变化和读取记录不明时补读。权限、写入前检查和执行后回读不复用旧成功结论。
-
-工作区保护始终有效：保留他人差异与共享进程，临时产物只放根 `.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 -->
-## 任务启动前 Skill 读取规则（强制）
-
-AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。
-
-- 任何吾码任务先读取本文件和 `microi-system-delivery/SKILL.md`，再按总控路由读取相关专项 Skill；无需用户指定 Skill 名称。
-- 涉及采集引擎、浏览器 Worker、验证码、站点规则、导出产物时，同时读取 `spider-engine`。
-- 涉及 V8 CRUD、SQL、上传下载、导入导出、菜单按钮、表单事件、前端页面或自动化测试时，继续读取对应专项 Skill。
-- 最终交付说明必须能逐条对应用户编号需求；不得遗漏、合并或把仍可执行的需求写成“下一步继续”。
-
-### 吾码 AI 开发默认路由（强制）
-
-- 在已通过吾码插件或 CLI 初始化的工作区中，用户直接描述业务需求即可。即使用户未写“吾码”、`Microi`、`microi-system-delivery` 或任何 Skill 名称，AI 仍须根据当前项目和已配置连接识别吾码任务，自动读取本基础入口及 `microi-system-delivery/SKILL.md`，不能等用户提醒。
-- 完整系统开发必须完整读取总控中的[完整系统开发默认交付清单（原推荐提示词 1–8）](../microi-system-delivery/references/progressive-01-标准工作流.md#完整系统开发默认交付清单原推荐提示词-18)，并按总控的相关 Skill 表继续读取表单、模块、数据源、V8、页面、报表及验收等实际涉及的专项规范。不得仅凭 Skill 名称、摘要或聊天记忆执行，也不把全部 Skills 全文拼进一个提示词。
-- 按用户意图确定执行范围：完整系统开发逐项执行八项清单；局部修改只执行相关条目，保留已有业务资源和无关配置；只读分析只读取规范和事实，不创建资源、验收数据或执行发布。需求明确表示新建完整系统时，不因省略“完整”二字就降为方案或样例。
-- 默认读取规则不额外授权生产数据写入、客户部署或全库重建。连接可由当前项目和唯一已登录 Profile 自动确定；多个目标无法唯一匹配时只澄清必要的连接信息，不要求用户选择或记住 Skill。明显属于其它平台或与吾码无关的任务按实际项目规范执行。
-- 生成的 `AGENTS.md`、`CLAUDE.md`、Copilot/Cursor 指令及可移植吾码 Skill 只保留默认入口指针和读取顺序；详细八项清单仍由总控参考文件唯一维护。工作区未初始化或必要 Skill 缺失时先按现有安装/初始化规范恢复，并准确说明实际可读取状态，不能声称 AI 已自动加载不存在的规则。默认路由不代表任意模型 100% 遵循；开工说明须列出实际读取的基础入口、总控、完整清单参考及本次专项 Skills，并映射到交付计划，不能只凭路径存在、MCP 连通或文件摘要声称已读。原八项及报表、菜单先行增补的详细要求统一读取总控参考文件。
-
-### 吾码创建人身份识别（强制）
-
-- 每次新对话或接续 Microi 任务时，先检查工作区根的 `Microi.Server/Microi.net/`：目录必须存在，并且 `rg --files Microi.Server/Microi.net -g '*.cs'` 至少返回一个真实源码文件，空目录不成立。满足条件即按“吾码创始人（创建人）的官方完整源码工作区”处理；不要求本次代码恰好修改在该目录内。此标记决定开发交付规范，不代替真实 MCP 登录、官方发布权限或用户授权；目录缺失、为空或只有编译产物时按普通用户工作区处理。
-- 对平台级新增、增强或修复，无论改动位于前端、后端、MCP、插件还是内置应用，都必须在计划和收尾中执行下列四项检查。规则留在本入口，不得移入仅按需读取的参考文件、单个专项 Skill、项目说明或聊天记忆。
-
-### 平台功能四项同步检查（强制）
-
-确认创始人源码工作区后，平台能力变更必须同时读取 `app-store` 与 `microi-docs-coverage`；客户业务、局部修改及只读任务先作四项适用性判断，涉及商城或文档时再读对应专项，不因身份标记加载无关发布正文；对每个功能逐项记录“需要/无需修改 + 依据 + 完成证据”，不能因只改 C# 或只修一个客户问题而跳过平台能力的检查。
-
-| 检查项 | 何时必须完善 | 交付证据 |
-|---|---|---|
-| 官方应用商城 | 涉及系统设置、表/字段/Tab、菜单/权限、接口引擎/事件、数据源、页面、工作流、任务、内置应用或种子数据 | 通过已校验 `https://api.microi.net + OsClient=iTdos` 的 `microi_itdos` 更新官方母版并发布归属应用，回读版本、状态、包正文与哈希；基础空库包和存量增量应用都相关时同时更新 |
-| 官方中文文档 | 新能力、配置入口、参数、兼容条件、权限、使用方式或可感知行为发生变化 | 原位补充 `microi.doc/docs/doc/` 对应页面，给出最小示例与升级要求，并完成相应文档检查；不手工维护英文副本 |
-| 吾码 Skills | AI 需要知道新的使用决策、配置方法、工具签名、限制、排错方式或验收条件 | 更新责任 Skill 及必要参考、能力映射，并验证基础入口、插件/CLI 分发与后端内嵌知识链路；不能只记在当前对话或本地 memory |
-| 吾码 MCP | AI 尚不能安全发现、配置、调用、发布或回读该能力，或现有工具的 Schema/说明缺失、过时 | 优先扩展现有通用工具及其 Schema、说明、测试；既有工具完整覆盖时无需新增工具，但必须列明可复用工具及验证依据 |
-
-- “无需修改”必须逐项有具体理由，例如纯内部优化无元数据变化可不升应用版本，现有 MCP 已支持该配置可不新增工具；不得默认四项都做，也不得默认四项都省略。需要修改的项目应在本次授权范围内完成并验证，受权限、网络或发布渠道阻挡时明确未完成项，不能用本地修改代替线上发布。
-- 任务若只要求分析、评审或制定规范，仍保持只读或仅修改指定规范；身份标记不授权无关线上写入。客户部署、容器更新和应用自动安装与官方发布是独立动作，服从用户指定的手动/自动边界；用户明确手动更新时不得擅自部署。
-- 收尾必须区分“源码/文档已修改、测试通过、应用已发布回读、Skills/插件已打包或已分发、镜像已推送、客户已安装或已部署”。npm、NuGet、Docker、Visual Studio Marketplace、Open VSX 等制品渠道以发布命令明确成功作为发布完成依据，默认不做发布后回读、不等待索引或 CDN 传播；不得把本地构建或插件本地副本同步称为已发布。发布成功不等于目标服务已部署，运行与业务验收仍按任务要求执行。
-
-### 平台回归与独立应用测试归属（强制）
-
-- 创始人源码工作区中的每个平台功能新增、缺陷修复和兼容性调整都必须同时交付可重复执行的回归测试；先证明旧行为失败，再验证修复成功，覆盖正常、边界、失败、安全与存量兼容路径。不得只改源码或用手工截图代替自动回归。
-- 平台 C# 单元/组件/集成测试归入 `Microi.Server/Microi.Tests`。平台前端、平台内置应用包与平台 V8 的 Node 行为测试可留在责任源码旁，由 `Microi.Tests/run-tests.ps1` 自动发现执行；平台真实浏览器、数据库及第三方集成归入 Full 或平台专项验收，不得冒充离线单测。新增公共后端能力同时补相应 HTTP 闭环。
-- 官方或社区独立业务应用、游戏及客户项目的测试归应用自身源码根的 `tests/` 或独立测试工程，由该应用自己的测试和发布入口执行；不得放入 `Microi.Tests`、创建转调包装或接入平台 Quick/Full。官方发布身份不改变测试归属。应用开发中涉及平台通用缺陷时，仅把通用最小回归夹具加入平台门禁，应用业务断言仍在应用项目维护。
-- `Microi一键编译发布.sh` 的所有 PC/API 镜像路径（包括仅推送、热修复）都必须先通过按指定 MCP 实际依赖选定的 Full 发布矩阵；选中范围内缺少环境、零用例、失败、取消、跳过、待办或无法解析测试结果一律停止。未纳入本次矩阵的提供商标为“不适用（未执行）”，不冒充通过，也不单独阻塞常规发布。禁止关闭断言、删测试、排除已选失败项目或修改门禁阈值来发布。
-- 测试成功必须绑定本次候选源码和实际构建上下文的内容哈希，构建后、每次推送前复核。旧产物没有可验证回执或源码/产物漂移时必须重建重测，禁止“当前源码通过测试 + 推送另一份旧 DLL/前端 dist”。 所有测试默认使用当前 MCP 经同源只读发现的 MongoDB 实际版本与当前租户实际生效的 HDFS 提供商；目标唯一时直接沿已授权隔离范围执行，不为旧 MongoDB 或其它 OSS/MinIO/S3 反复询问、新建服务或替换当前提供商。只有明确的兼容、迁移或提供商缺陷任务才扩展真实矩阵；未执行项如实记未覆盖，不以同一端点冒充多版本，也不因环境发现获得生产业务写入授权。
-- 常规发布只验证用户指定 MCP 对应的实际依赖：MySQL、MongoDB 实际版本、Redis，以及租户实际生效的 MinIO 或 OSS/HDFS 等存储；不默认同时验证所有数据库版本或所有存储提供商。先核实 Profile、ApiBase、OsClient 和依赖类型，在已授权隔离范围执行；默认复用已配置依赖，不因本地无容器另建服务；依赖发现不扩大生产业务写入、付费资源或用户明确禁止的操作范围。
-- SQL Server 的真实连接、提供商兼容与专项验收默认不纳入常规发布矩阵；只有用户明确指定排查、修复或验收 SQL Server 问题时才执行。检测到 SQL Server 连接/驱动、旧 Full 清单或通用数据库代码变更都不能自行触发该专项，也不需要每次申请 SQL Server 免测。既有不连接 SQL Server 的离线单元断言照常保留，但不能据此声称 SQL Server 已实测。
-- 交付记录逐项列明修复与测试映射、执行数量、未覆盖边界和镜像摘要。覆盖率与 Full 都不能证明所有租户业务、任意生产数据和第三方系统绝对无误；真实客户路径仍需只读验收。详细矩阵见 `microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md`。
-
-### Microi吾码非阻塞自动更新（强制）
-
-- 本规范与“Microi吾码工作进度播报规范”同属无条件基础规则，适用于任何 AI 模型与宿主，不限 Codex，也不要求用户提到安装、版本或更新。每次新建或接续 Microi 对话，AI 必须读取本节并检查版本；已有 CLI 时必须投递 `microi update --background --workspace "<工作区绝对路径>" --json`，由更新器去重、节流和重试，不得改写为“可选”“建议更新”或等用户提醒。后台任务与业务工作并行，不得等待更新完成才开始业务分析、MCP 调用、源码修改、构建或发布。
-- `@microi.net/cli` 必须自动升级到 npm 官方 `latest`，并使用新版包重新同步吾码 Skills、AI 宿主规则、插件与 MCP。不能只执行 `npx @latest`、只查询版本或只更新全局 CLI 后就声称完整升级；旧 CLI 缺少 `update` 时按 `microi-codex-installer` 的官方安装恢复路径更新。完全未安装且本次未授权初始化时准确记录缺失，不擅自创建服务器连接。
-- 首次工作过程说明必须包含一次版本播报，以“Microi吾码开发工具版本”开头，报告当前实际 CLI 版本、npm 官方最新版本（含查询时间）、自动更新是否启用及状态、Skills/MCP 是否已同步。读取 `microi version --json` 与后台状态文件，或 MCP `profiles.toolchain`；后者的 `loadedVersion` 只代表当前 MCP 提供者，`latestObservedVersion` 是带时间的历史查询结果，不能冒充全局 CLI 版本或刚刚在线查询的最新版。尚未确认的项必须写“检测中/未知/待回读”，后续回读补齐；禁止猜测、硬编码当前发布号或把 `expectedVersion` 当 npm 最新版。
-- CLI 最新版只从 npm 官方 registry 查询：`npm view '@microi.net/cli' version --json --prefer-online --registry=https://registry.npmjs.org/`；VS Code 扩展只使用官方扩展宿主的自动更新/安装命令。不得使用第三方 registry 或不明镜像冒充官方更新。
-- 后台更新完整闭环包含全局 CLI、已安装宿主的 `microi@microi-net` / DSH bundle，以及已配置连接工作区的 `microi ai init`、`microi doctor`、`microi codex status` / `microi dsh status`。回读全局版本、工作区 Skills bundle/file 版本及 MCP provider 版本，确认不低于本次官方查询版本；较新提供者保留。未安装的宿主安静跳过，未配置连接的目录不生成 AI/MCP 文件。完成后重新读取已更新的基础规范与本任务专项 Skill，并在收尾说明升级或延后结果。`codex install --yes` 的 `--yes` 只兼容旧脚本，不是用户继续工作的授权开关。
-- 当前运行中的 VS Code Extension Host、CLI、Codex Router、MCP 和对话继续使用已加载版本。禁止为了更新终止进程、强制重载、要求立即新建任务或拒绝新工作；新版只在后续新进程或宿主自然重启时接管。
-- npm 官方 registry 无法访问、权限不足、文件被运行中进程占用、安装失败或宿主不能热更新时，必须写入可诊断状态并延后重试。可以非模态提示“立即重试/查看日志”，但用户忽略、关闭或暂不处理时，当前、正在进行和新建的 Microi 工作仍必须继续。
-- 用户明确关闭自动更新或宿主不允许终端执行时，尊重该限制，报告具体未完成项和恢复命令；不能静默宣称已是最新版。自动更新只覆盖开发工具、Skills 和本机 MCP 入口，不授权升级客户 API/数据库、部署容器或安装业务应用；已签名 Microi Agent 安装目录仍通过桌面官方更新渠道升级。
-- 只有任务明确依赖旧版本不存在的具体能力时，才准确说明该能力边界与可用降级方案；不得用“最新版未通过”“尚未授权升级”作为整项任务的失败理由。
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-001 sha256=8d8dfff420c0cc768bbeb13d94e9f77f52d5002fc61d93dc82d71b3a17f2eaa0 -->
-## Microi吾码工作进度播报规范（强制）
-
-AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出工作过程记录时，必须默认执行本规范，无需用户再次提醒：
-
-- 每累计输出 3-5 次面向用户的工作过程记录，根据任务复杂度和实际阶段选择合适时机，追加一次进度播报；首次播报不得晚于第 5 次工作过程记录。工具调用结果、系统消息和最终答复不计入次数。
-- 播报必须以“Microi吾码本次工作进度”开头，让用户明确知道这是【Microi吾码】规范；不得改成含义模糊的“当前进度”，也不得描述为 AI 自带功能。
-- 每次播报必须同时包含四项快速估算：已完成进度百分比、预计还需要多长时间结束、目前大概已消耗多少 token、预计总共需要消耗多少 token。
-- 预计剩余时间不足 60 分钟时使用分钟；达到 60 分钟后换算为“X小时Y分钟”；达到 24 小时后换算为“X天Y小时Z分钟”。为 0 的低位单位可以省略，禁止继续只显示累计分钟数。
-- 进度、时间和 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 -->
+---
+name: workspace-conventions
+description: 每次 Microi 任务开始前必读的基础规范。用于识别创始人源码工作区，检查平台功能的应用商城、官方文档、Skills 与 MCP 交付，并遵守共享工作区、进程、资源和发布边界。
+---
+
+# Microi 工作区全局约定
+
+## 每次修改微服务前重新拉取（强制入口）
+
+与每次对话的 CLI 版本检查一样，所有 AI 模型和宿主在**每次开始修改已有 MicroService**（包括接续任务、只改一行、路由修复和紧急发布）前，必须读取 `../microi-microservice/SKILL.md` 的协作门禁，重新拉取当前租户完整私有源码到本地，逐文件核对路径、原始字节大小和 SHA-256，并与本地和上次同步基线三方比较。保留本地独有改动、合并远端变化；正文缺失、哈希不一致或冲突未解决时，不开始修改。完整工程下载在工具进程内完成，不把源码 Base64 全量塞入模型上下文。
+
+完成比较后保存**修改前**的 `SourceManifestHash`，调用 `microi_sync_microservice_source` 时传 `expectedSourceManifestHash`。现有源码缺少基线或远端已变化时工具拒绝写入；不能只重新取一个新哈希来重试旧本地代码。发布前再次校验，保留其它页面、`LegacyComponentPaths/LegacyMenuUrls` 以及实际组件注册。此要求必须同时出现在 CLI/IDE 生成的各 AI 宿主入口中；文字规则不能冒充已执行拉取、校验或渠道分发。
+
+## Git 原分支交付（强制）
+
+禁止 AI 自动创建并推送额外远端分支。开工记录用户原本的分支及上游；优先在原分支完成工作，确有并发隔离或冻结测试输入需要时，才使用本地临时分支或 detached worktree。验收后必须安全合回原分支，只推送该原分支；不得将临时分支、发布候选、备份分支或标签推到远端代替合并。只有用户明确要求创建某个远端分支时才例外。清理前核对未合并提交、活动工作树及其它任务，保留有效成果后删除本任务临时分支和工作树。详细步骤见[共享工作区与 Git 保障](references/progressive-04-工作区与平台专项保障.md#功能验收后的源码提交与推送强制)。
+
+## 截图与大体积资源必须走 CDN（默认强制）
+
+- 截图、宣传配图、PDF、PPT/PPTX、视频、音频、模型、压缩包、安装包、导出报告及其它大体积资源不得提交或推送到 Gitee、GitHub 等源码仓库。截图和交付附件无论压缩后是否低于大小阈值都走 CDN；禁止通过 Base64、Git LFS、分卷、改后缀、强制暂存或中间提交绕过。一般“提交并推送”的授权不能解除此规则，也不再走“先上传大文件到 Git 再处理”的路径。
+- 吾码官方公开资源必须通过已核验 `https://api.microi.net + OsClient=iTdos` 的 `microi_itdos` MCP 上传公有桶，并使用 `https://file.microi.net` 前缀访问。普通客户资源使用已授权租户 MCP 与实际 CDN/FileServer，敏感、私有资料保持私有权限，不能为了公开链接改为公有桶。大文件使用已有流式/分片上传能力，不绕过 MCP 直接使用存储密钥。
+- 源码只保存必要代码、轻量可编辑模板、CDN URL、文件名、字节数、SHA-256、MIME 和必要生成说明；原图、压缩件、PDF、下载校验缓存放任务专属临时目录，交付后按清理规则回收。上传成功后必须独立下载核对字节数、哈希和真实 MIME；PDF 同时检查 Range 分段读取。未知上传结果先回读，不能盲重传。
+- 提交前检查暂存区，推送前以刚核验的远端引用检查全部待推送提交的新增 Blob；既查资源类型，也查单个 10 MiB / 合计 50 MiB 的体积门槛。发现禁止入库资源就停止受影响的提交/推送，迁移 CDN 并从本次候选索引/提交中排除；中间提交加入后又删除也不合格。不得改写共享历史、删除用户本地原图或清空既有仓库。必要运行依赖另按真实用途审查，但不能借此提交截图和交付附件。
+
+完整上传与回读流程见 [文件上传下载规范](../v8-file-upload/SKILL.md)，Git 对象检查与历史边界见 [Git 大文件推送检查](references/progressive-03-cli-与-ide-插件错版共存约定.md#git-大文件推送检查强制)。
+
+## 测试临时文件必须随任务清理（强制）
+
+本节适用于开发、测试、诊断和发布产生的全部自有临时资产，包括工作区根 `.tmp/`、宿主临时目录（如 `$CODEX_HOME/tmp`）和隔离 Git worktree，并替代历史“任务完成后可以不清理”的约定。目录位置和 `.gitignore` 不改变收尾责任。
+
+- 创建前使用独立的 `.tmp/<任务标识>/`，登记本任务创建的目录、文件、进程及用途；不得混用其它任务目录，既有文件或共享依赖不因本轮使用而取得删除权。每轮测试及任务成功、失败、取消或中断退出时都执行 `finally` / teardown，先核验并关闭本任务的写入者、浏览器和临时服务，再删除本轮已无用途的临时文件；不能等用户再次要求清理磁盘。
+- 默认删除本任务的一次性脚本、下载/解压副本、编译输出、隔离依赖、测试夹具和冗余截图/trace/video/日志。交付必需的少量报告、关键截图、发布哈希/回执先脱敏并归档到对应项目的长期交付目录，回读归档完整后再删临时副本；不得把完整构建树、源码副本或依赖目录当作验收证据长期留存。
+- 失败仍需排查或下一阶段确实依赖的文件，只保留可解释的最小集合，记录路径、体积、原因、归属和清理时机；排查/依赖结束后立即删除。崩溃来不及执行 teardown 时，下次接续先核对自有清单并补清；不能以“测试失败”“以后可能有用”为由无限保留。
+- 隔离副本只为实际并发冲突或构建输入冻结创建，优先复用合适的工作树、稀疏检出和最小夹具；禁止每次重试复制整套源码、Git 历史、依赖、SDK 和运行目录。创建前盘点源盘与目标盘可用空间及已有同类副本，按本轮实际需求估算新增体积；测试结束先回收旧运行/编译目录，再创建下一轮。不要把临时目录移到另一块盘当作清理。
+- 工作树不是永久保留项：任务结束逐仓检查未提交、未跟踪、忽略文件和未推送提交，已合入/已归档且无活动引用的副本按 Git/宿主支持的方式移除并回读注册表；必要差异先最小归档并校验可恢复性，不复制完整构建树。嵌套独立 Git 仓库逐个核对；禁止因存在 `.git` 就跳过整个任务目录，也禁止把主工作区存在当成差异已安全保存的证明。
+- **规则必须落到执行入口**：新增或维护测试、构建、发布脚本时，将自有临时资产回收写入实际的 `finally`、测试框架 teardown/after hook 或宿主归档流程，并验证成功与失败退出均回收。`Microi.Tests/run-tests.ps1` 的 Full 隔离 `.net-artifacts` 由入口自动回收，保留结果报告与 `artifact-cleanup.json`；已有共享目录不取得删除权。仅修改 Skill、模型读过规则或工具显示最新版，都不能声称自动清理已生效；须检查已安装正文及实际执行结果。硬崩溃/强杀可能跳过收尾，恢复时按归属清单补清，不能承诺任意中断都即时删除。
+- 删除前核验解析后的绝对路径位于已登记的本任务临时目录或独占副本内，不能仅依赖字符串前缀；检查目标及祖先的重解析点/符号链接、当前进程 CWD/文件锁、Git worktree 与未提交源码、发布锁以及虚拟机/容器引用。禁止跟随链接递归到共享或外部目录；无法确认真实边界时保留。保留用户文件、唯一源码/未提交改动、正式交付物、共享资源和其它任务资产；独占 Git 工作树先按 Git/宿主支持的移除方式完成检查，不能直接递归删除。
+- 历史垃圾清理先做体积与引用盘点，只删已核验无引用、无跟踪源码且可再生成的产物；文件名含 `.tmp`、目录名为 `bin/obj` 或时间较旧都不能单独证明可删。禁止整体清空共享 `.tmp/`，禁止为了清理结束其它任务或重启 Docker/WSL。
+- 清理后独立回读已删路径不存在、保护对象仍在；必要时比对源码、用户原图、正式交付物的哈希及其它工作树登记。收尾报告已删路径/文件数、逻辑字节数、磁盘可用空间变化、剩余保留项及清理时机；并行写入、硬链接等会使逻辑大小与实际净空间变化不同，不能混报。遇到文件锁、权限或策略拒绝时记录执行阶段、原始错误和未完成范围，禁止换工具绕过。测试通过与临时文件清理完成是两个验收项，不能互相代替。
+
+### Windows 默认普通删除与策略拒绝排查（强制）
+
+- 自动收尾默认使用原生 PowerShell 普通删除：已完成上述核验的普通文件使用 `Remove-Item -LiteralPath $verifiedTaskFile -ErrorAction Stop`，已核验的独占目录才使用 `Remove-Item -LiteralPath $verifiedTaskDirectory -Recurse -ErrorAction Stop`。变量必须来自本任务明确登记并重新解析的单个绝对路径，禁止空值、通配符、盘符根目录、用户目录根、源码根或共享 `.tmp` 根；不能把这两行当作跳过核验的通用清盘命令。
+- **删除命令不默认添加 `-Force`，自动 teardown 也不得失败后升级为强制删除。** 不通过清除只读/隐藏/系统属性、修改 ACL、改审批配置、编码命令、换语言/API、换 shell 或间接脚本完成被拒绝的同一动作。只读盘点可使用 `Get-ChildItem -Force` 发现隐藏项；它不授予强制删除权。普通删除遇到受保护属性、占用或权限错误，保留相应项并报告，不能因其体积小或由 AI 创建就忽略限制。
+- `CreateProcess ... rejected: blocked by policy` 表示执行器在启动 shell 前拒绝；命令里的路径/归档检查也没有运行，不能把它当作 Windows ACL 报错或清理成功。已核验的 Codex Windows `0.163.0-alpha.10.2` 将 `Remove-Item … -Force` 识别为危险删除，并在 `approval_policy=never` 下直接拒绝；`danger-full-access` 不取消命令策略，`never` 也不等于全部允许。其它版本/宿主必须依据当前有效配置、日志或对应版本实现定位，不能把所有同名错误都归因于 `-Force`。实现依据：[强制删除识别](https://github.com/openai/codex/blob/rust-v0.163.0-alpha.10.2/codex-rs/shell-command/src/command_safety/windows_dangerous_commands.rs#L489)、[禁止审批时的决策](https://github.com/openai/codex/blob/rust-v0.163.0-alpha.10.2/codex-rs/core/src/exec_policy.rs#L799)。
+- 若已明确拒绝针对强制删除，只有在原有授权和归属/路径核验仍成立、且普通删除确实保留系统保护语义时，才可收窄为上述原生非强制操作；这不授权扩大删除范围。拒绝原因未知、存在明确禁止，或普通操作仍被拒绝时停止该项，保留并报告，不反复变换写法试探策略，也不修改规则放行。
+- `git worktree remove` 的 `Result too large` 等是命令执行后的失败，与策略拒绝分开处理。失败后分别回读工作树登记与目录，不能假定“登记没了，文件也没了”；先验证差异/未推送提交已可恢复、残留源码与对应提交一致、无其它任务引用和外部链接，才将已注销的残留产物纳入普通清理清单。归属或恢复证据不足时保留，不强删独占副本或嵌套仓库。
+
+## 质量优先与适用范围
+
+**测试依赖默认复用 MCP（强制）**：普通联调、Full 和发布测试使用当前已核验 MCP 对应的 MySQL、Redis、MongoDB、HDFS/OSS/MinIO 服务，并在已授权范围以独立测试库、租户、Key/对象前缀隔离。固定夹具库名被占用、归属标记冲突、端口冲突、本机无容器或旧夹具被清理，都不是“迫不得已”另建本地测试容器的理由；先修正测试入口的可配置隔离和归属校验，不能覆盖他人的夹具或放宽保护。不能复用时按[依赖生命周期](references/progressive-02-microi-net-api-本地启动约定.md#本地测试程序与依赖生命周期强制)核实具体限制；用户明确禁止的本地容器不会因测试或发布授权自动解禁。
+
+准确性、业务完整性、安全和真实验收优先于 token 与回复长度。先确定完整系统、局部修改或只读分析；新建系统意图按完整交付，不能因短提示词或预算缩小八项清单及菜单/报表增补。局部修改定位真实目标和依赖，信息不足、动态关系或影响不明时扩大读取，不凭摘要猜测或写入。
+
+必须读取总控的 [质量与增量开发规范](../microi-system-delivery/references/context-quality.md)，按任务映射实际读取与验收记录。同一会话只复用内容哈希未变且已完整读取的规范；首次、版本变化和读取记录不明时补读。权限、写入前检查和执行后回读不复用旧成功结论。
+
+工作区保护始终有效：保留他人差异与共享进程，临时产物只放根 `.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=fefc18da554473ded99a55c3b2e66d698fcc4b37506622dcd2d17bca09c2fcbc -->
+## 任务启动前 Skill 读取规则（强制）
+
+AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。
+
+- 任何吾码任务先读取本文件和 `microi-system-delivery/SKILL.md`，再按总控路由读取相关专项 Skill；无需用户指定 Skill 名称。
+- 涉及采集引擎、浏览器 Worker、验证码、站点规则、导出产物时，同时读取 `spider-engine`。
+- 涉及 V8 CRUD、SQL、上传下载、导入导出、菜单按钮、表单事件、前端页面或自动化测试时，继续读取对应专项 Skill。
+- 最终交付说明必须能逐条对应用户编号需求；不得遗漏、合并或把仍可执行的需求写成“下一步继续”。
+
+### 吾码 AI 开发默认路由（强制）
+
+- 在已通过吾码插件或 CLI 初始化的工作区中，用户直接描述业务需求即可。即使用户未写“吾码”、`Microi`、`microi-system-delivery` 或任何 Skill 名称，AI 仍须根据当前项目和已配置连接识别吾码任务，自动读取本基础入口及 `microi-system-delivery/SKILL.md`，不能等用户提醒。
+- 完整系统开发必须完整读取总控中的[完整系统开发默认交付清单（原推荐提示词 1–8）](../microi-system-delivery/references/progressive-01-标准工作流.md#完整系统开发默认交付清单原推荐提示词-18)，并按总控的相关 Skill 表继续读取表单、模块、数据源、V8、页面、报表及验收等实际涉及的专项规范。不得仅凭 Skill 名称、摘要或聊天记忆执行，也不把全部 Skills 全文拼进一个提示词。
+- 按用户意图确定执行范围：完整系统开发逐项执行八项清单；局部修改只执行相关条目，保留已有业务资源和无关配置；只读分析只读取规范和事实，不创建资源、验收数据或执行发布。需求明确表示新建完整系统时，不因省略“完整”二字就降为方案或样例。
+- 默认读取规则不额外授权生产数据写入、客户部署或全库重建。连接可由当前项目和唯一已登录 Profile 自动确定；多个目标无法唯一匹配时只澄清必要的连接信息，不要求用户选择或记住 Skill。明显属于其它平台或与吾码无关的任务按实际项目规范执行。
+- 生成的 `AGENTS.md`、`CLAUDE.md`、Copilot/Cursor 指令及可移植吾码 Skill 只保留默认入口指针和读取顺序；详细八项清单仍由总控参考文件唯一维护。工作区未初始化或必要 Skill 缺失时先按现有安装/初始化规范恢复，并准确说明实际可读取状态，不能声称 AI 已自动加载不存在的规则。默认路由不代表任意模型 100% 遵循；开工说明须列出实际读取的基础入口、总控、完整清单参考及本次专项 Skills，并映射到交付计划，不能只凭路径存在、MCP 连通或文件摘要声称已读。原八项及报表、菜单先行增补的详细要求统一读取总控参考文件。
+
+### 吾码创建人身份识别（强制）
+
+- 每次新对话或接续 Microi 任务时，先检查工作区根的 `Microi.Server/Microi.net/`：目录必须存在，并且 `rg --files Microi.Server/Microi.net -g '*.cs'` 至少返回一个真实源码文件，空目录不成立。满足条件即按“吾码创始人（创建人）的官方完整源码工作区”处理；不要求本次代码恰好修改在该目录内。此标记决定开发交付规范，不代替真实 MCP 登录、官方发布权限或用户授权；目录缺失、为空或只有编译产物时按普通用户工作区处理。
+- 对平台级新增、增强或修复，无论改动位于前端、后端、MCP、插件还是内置应用，都必须在计划和收尾中执行下列四项检查。规则留在本入口，不得移入仅按需读取的参考文件、单个专项 Skill、项目说明或聊天记忆。
+
+### 平台功能四项同步检查（强制）
+
+确认创始人源码工作区后，平台能力变更必须同时读取 `app-store` 与 `microi-docs-coverage`；客户业务、局部修改及只读任务先作四项适用性判断，涉及商城或文档时再读对应专项，不因身份标记加载无关发布正文；对每个功能逐项记录“需要/无需修改 + 依据 + 完成证据”，不能因只改 C# 或只修一个客户问题而跳过平台能力的检查。
+
+| 检查项 | 何时必须完善 | 交付证据 |
+|---|---|---|
+| 官方应用商城 | 涉及系统设置、表/字段/Tab、菜单/权限、接口引擎/事件、数据源、页面、工作流、任务、内置应用或种子数据 | 通过已校验 `https://api.microi.net + OsClient=iTdos` 的 `microi_itdos` 更新官方母版并发布归属应用，回读版本、状态、包正文与哈希；基础空库包和存量增量应用都相关时同时更新 |
+| 官方中文文档 | 新能力、配置入口、参数、兼容条件、权限、使用方式或可感知行为发生变化 | 原位补充 `microi.doc/docs/doc/` 对应页面，给出最小示例与升级要求，并完成相应文档检查；不手工维护英文副本 |
+| 吾码 Skills | AI 需要知道新的使用决策、配置方法、工具签名、限制、排错方式或验收条件 | 更新责任 Skill 及必要参考、能力映射，并验证基础入口、插件/CLI 分发与后端内嵌知识链路；不能只记在当前对话或本地 memory |
+| 吾码 MCP | AI 尚不能安全发现、配置、调用、发布或回读该能力，或现有工具的 Schema/说明缺失、过时 | 优先扩展现有通用工具及其 Schema、说明、测试；既有工具完整覆盖时无需新增工具，但必须列明可复用工具及验证依据 |
+
+- “无需修改”必须逐项有具体理由，例如纯内部优化无元数据变化可不升应用版本，现有 MCP 已支持该配置可不新增工具；不得默认四项都做，也不得默认四项都省略。需要修改的项目应在本次授权范围内完成并验证，受权限、网络或发布渠道阻挡时明确未完成项，不能用本地修改代替线上发布。
+- 任务若只要求分析、评审或制定规范，仍保持只读或仅修改指定规范；身份标记不授权无关线上写入。客户部署、容器更新和应用自动安装与官方发布是独立动作，服从用户指定的手动/自动边界；用户明确手动更新时不得擅自部署。
+- 收尾必须区分“源码/文档已修改、测试通过、应用已发布回读、Skills/插件已打包或已分发、镜像已推送、客户已安装或已部署”。npm、NuGet、Docker、Visual Studio Marketplace、Open VSX 等制品渠道以发布命令明确成功作为发布完成依据，默认不做发布后回读、不等待索引或 CDN 传播；不得把本地构建或插件本地副本同步称为已发布。发布成功不等于目标服务已部署，运行与业务验收仍按任务要求执行。
+
+### 平台回归与独立应用测试归属（强制）
+
+- 创始人源码工作区中的每个平台功能新增、缺陷修复和兼容性调整都必须同时交付可重复执行的回归测试；先证明旧行为失败，再验证修复成功，覆盖正常、边界、失败、安全与存量兼容路径。不得只改源码或用手工截图代替自动回归。
+- 平台 C# 单元/组件/集成测试归入 `Microi.Server/Microi.Tests`。平台前端、平台内置应用包与平台 V8 的 Node 行为测试可留在责任源码旁，由 `Microi.Tests/run-tests.ps1` 自动发现执行；平台真实浏览器、数据库及第三方集成归入 Full 或平台专项验收，不得冒充离线单测。新增公共后端能力同时补相应 HTTP 闭环。
+- 官方或社区独立业务应用、游戏及客户项目的测试归应用自身源码根的 `tests/` 或独立测试工程，由该应用自己的测试和发布入口执行；不得放入 `Microi.Tests`、创建转调包装或接入平台 Quick/Full。官方发布身份不改变测试归属。应用开发中涉及平台通用缺陷时，仅把通用最小回归夹具加入平台门禁，应用业务断言仍在应用项目维护。
+- `Microi一键编译发布.sh` 的所有 PC/API 镜像路径（包括仅推送、热修复）都必须先通过按指定 MCP 实际依赖选定的 Full 发布矩阵；选中范围内缺少环境、零用例、失败、取消、跳过、待办或无法解析测试结果一律停止。未纳入本次矩阵的提供商标为“不适用（未执行）”，不冒充通过，也不单独阻塞常规发布。禁止关闭断言、删测试、排除已选失败项目或修改门禁阈值来发布。
+- 测试成功必须绑定本次候选源码和实际构建上下文的内容哈希，构建后、每次推送前复核。旧产物没有可验证回执或源码/产物漂移时必须重建重测，禁止“当前源码通过测试 + 推送另一份旧 DLL/前端 dist”。 所有测试默认使用当前 MCP 经同源只读发现的 MongoDB 实际版本与当前租户实际生效的 HDFS 提供商；目标唯一时直接沿已授权隔离范围执行，不为旧 MongoDB 或其它 OSS/MinIO/S3 反复询问、新建服务或替换当前提供商。只有明确的兼容、迁移或提供商缺陷任务才扩展真实矩阵；未执行项如实记未覆盖，不以同一端点冒充多版本，也不因环境发现获得生产业务写入授权。
+- 常规发布只验证用户指定 MCP 对应的实际依赖：MySQL、MongoDB 实际版本、Redis，以及租户实际生效的 MinIO 或 OSS/HDFS 等存储；不默认同时验证所有数据库版本或所有存储提供商。先核实 Profile、ApiBase、OsClient 和依赖类型，在已授权隔离范围执行；默认复用已配置依赖，不因本地无容器另建服务；依赖发现不扩大生产业务写入、付费资源或用户明确禁止的操作范围。
+- SQL Server 的真实连接、提供商兼容与专项验收默认不纳入常规发布矩阵；只有用户明确指定排查、修复或验收 SQL Server 问题时才执行。检测到 SQL Server 连接/驱动、旧 Full 清单或通用数据库代码变更都不能自行触发该专项，也不需要每次申请 SQL Server 免测。既有不连接 SQL Server 的离线单元断言照常保留，但不能据此声称 SQL Server 已实测。
+- 交付记录逐项列明修复与测试映射、执行数量、未覆盖边界和镜像摘要。覆盖率与 Full 都不能证明所有租户业务、任意生产数据和第三方系统绝对无误；真实客户路径仍需只读验收。详细矩阵见 `microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md`。
+
+### Microi吾码非阻塞自动更新（强制）
+
+- 本规范与“Microi吾码工作进度播报规范”同属无条件基础规则，适用于任何 AI 模型与宿主，不限 Codex，也不要求用户提到安装、版本或更新。每次新建或接续 Microi 对话，AI 必须读取本节并检查版本；已有 CLI 时必须投递 `microi update --background --workspace "<工作区绝对路径>" --json`，由更新器去重、节流和重试，不得改写为“可选”“建议更新”或等用户提醒。后台任务与业务工作并行，不得等待更新完成才开始业务分析、MCP 调用、源码修改、构建或发布。
+- `@microi.net/cli` 必须自动升级到 npm 官方 `latest`，并使用新版包重新同步吾码 Skills、AI 宿主规则、插件与 MCP。不能只执行 `npx @latest`、只查询版本或只更新全局 CLI 后就声称完整升级；旧 CLI 缺少 `update` 时按 `microi-codex-installer` 的官方安装恢复路径更新。完全未安装且本次未授权初始化时准确记录缺失，不擅自创建服务器连接。
+- 首次工作过程说明必须包含一次版本播报，以“Microi吾码开发工具版本”开头，报告当前实际 CLI 版本、npm 官方最新版本（含查询时间）、自动更新是否启用及状态、Skills/MCP 是否已同步。读取 `microi version --json` 与后台状态文件，或 MCP `profiles.toolchain`；后者的 `loadedVersion` 只代表当前 MCP 提供者，`latestObservedVersion` 是带时间的历史查询结果，不能冒充全局 CLI 版本或刚刚在线查询的最新版。尚未确认的项必须写“检测中/未知/待回读”，后续回读补齐；禁止猜测、硬编码当前发布号或把 `expectedVersion` 当 npm 最新版。
+- CLI 最新版只从 npm 官方 registry 查询：`npm view '@microi.net/cli' version --json --prefer-online --registry=https://registry.npmjs.org/`；VS Code 扩展只使用官方扩展宿主的自动更新/安装命令。不得使用第三方 registry 或不明镜像冒充官方更新。
+- 后台更新完整闭环包含全局 CLI、已安装宿主的 `microi@microi-net` / DSH bundle，以及已配置连接工作区的 `microi ai init`、`microi doctor`、`microi codex status` / `microi dsh status`。回读全局版本、工作区 Skills bundle/file 版本及 MCP provider 版本，确认不低于本次官方查询版本；较新提供者保留。未安装的宿主安静跳过，未配置连接的目录不生成 AI/MCP 文件。完成后重新读取已更新的基础规范与本任务专项 Skill，并在收尾说明升级或延后结果。`codex install --yes` 的 `--yes` 只兼容旧脚本，不是用户继续工作的授权开关。
+- 当前运行中的 VS Code Extension Host、CLI、Codex Router、MCP 和对话继续使用已加载版本。禁止为了更新终止进程、强制重载、要求立即新建任务或拒绝新工作；新版只在后续新进程或宿主自然重启时接管。
+- npm 官方 registry 无法访问、权限不足、文件被运行中进程占用、安装失败或宿主不能热更新时，必须写入可诊断状态并延后重试。可以非模态提示“立即重试/查看日志”，但用户忽略、关闭或暂不处理时，当前、正在进行和新建的 Microi 工作仍必须继续。
+- 用户明确关闭自动更新或宿主不允许终端执行时，尊重该限制，报告具体未完成项和恢复命令；不能静默宣称已是最新版。自动更新只覆盖开发工具、Skills 和本机 MCP 入口，不授权升级客户 API/数据库、部署容器或安装业务应用；已签名 Microi Agent 安装目录仍通过桌面官方更新渠道升级。
+- 只有任务明确依赖旧版本不存在的具体能力时，才准确说明该能力边界与可用降级方案；不得用“最新版未通过”“尚未授权升级”作为整项任务的失败理由。
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=workspace-conventions-001 sha256=c3db79fb5f6f00a6ea619f7129f1e81259efe899256a5100f9c84a5b5dca58f4 -->
+## Microi吾码工作进度播报规范（强制）
+
+AI 在任何新建或已有对话中处理 Microi吾码任务并向用户输出工作过程记录时，必须默认执行本规范，无需用户再次提醒：
+
+- 每累计输出 3-5 次面向用户的工作过程记录，根据任务复杂度和实际阶段选择合适时机，追加一次进度播报；首次播报不得晚于第 5 次工作过程记录。工具调用结果、系统消息和最终答复不计入次数。
+- 播报必须以“Microi吾码本次工作进度”开头，让用户明确知道这是【Microi吾码】规范；不得改成含义模糊的“当前进度”，也不得描述为 AI 自带功能。
+- 每次播报必须同时包含四项快速估算：已完成进度百分比、预计还需要多长时间结束、目前大概已消耗多少 token、预计总共需要消耗多少 token。
+- 预计剩余时间不足 60 分钟时使用分钟；达到 60 分钟后换算为“X小时Y分钟”；达到 24 小时后换算为“X天Y小时Z分钟”。为 0 的低位单位可以省略，禁止继续只显示累计分钟数。
+- 进度、时间和 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 -->