--- name: workspace-conventions description: 每次 Microi 任务开始前必读的基础规范。用于识别创始人源码工作区，检查平台功能的应用商城、官方文档、Skills 与 MCP 交付，并遵守共享工作区、进程、资源和发布边界。 --- # Microi 工作区全局约定 ## 任务启动前 Skill 读取规则（强制） AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。 - 通用任务至少读取本文件；涉及完整交付、MCP 建模、远端 V8、菜单、字段或生产数据时，同时读取 `microi-system-delivery`。 - 涉及采集引擎、浏览器 Worker、验证码、站点规则、导出产物时，同时读取 `spider-engine`。 - 涉及 V8 CRUD、SQL、上传下载、导入导出、菜单按钮、表单事件、前端页面或自动化测试时，继续读取对应专项 Skill。 - 最终交付说明必须能逐条对应用户编号需求；不得遗漏、合并或把仍可执行的需求写成“下一步继续”。 ### 吾码创建人身份识别（强制） - 每次新对话或接续 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.itdos.com + OsClient=iTdos` 的 `microi_itdos` 更新官方母版并发布归属应用，回读版本、状态、包正文与哈希；基础空库包和存量增量应用都相关时同时更新 | | 官方中文文档 | 新能力、配置入口、参数、兼容条件、权限、使用方式或可感知行为发生变化 | 原位补充 `microi.doc/docs/doc/` 对应页面，给出最小示例与升级要求，并完成相应文档检查；不手工维护英文副本 | | 吾码 Skills | AI 需要知道新的使用决策、配置方法、工具签名、限制、排错方式或验收条件 | 更新责任 Skill 及必要参考、能力映射，并验证基础入口、插件/CLI 分发与后端内嵌知识链路；不能只记在当前对话或本地 memory | | 吾码 MCP | AI 尚不能安全发现、配置、调用、发布或回读该能力，或现有工具的 Schema/说明缺失、过时 | 优先扩展现有通用工具及其 Schema、说明、测试；既有工具完整覆盖时无需新增工具，但必须列明可复用工具及验证依据 | - “无需修改”必须逐项有具体理由，例如纯内部优化无元数据变化可不升应用版本，现有 MCP 已支持该配置可不新增工具；不得默认四项都做，也不得默认四项都省略。需要修改的项目应在本次授权范围内完成并验证，受权限、网络或发布渠道阻挡时明确未完成项，不能用本地修改代替线上发布。 - 任务若只要求分析、评审或制定规范，仍保持只读或仅修改指定规范；身份标记不授权无关线上写入。客户部署、容器更新和应用自动安装与官方发布是独立动作，服从用户指定的手动/自动边界；用户明确手动更新时不得擅自部署。 - 收尾必须区分“源码/文档已修改、测试通过、应用已发布回读、Skills/插件已打包或已分发、镜像已推送、客户已安装或已部署”。只有实际渠道验收成功才能说其它用户已可获取；不得把文档本地构建或插件本地副本同步称为已上线。 ### 每个新增与修复必须进入统一回归门禁（强制） - 创始人源码工作区的每个功能新增、缺陷修复和兼容性调整都必须同时交付可重复执行的回归测试；先证明旧行为失败，再验证修复成功，覆盖正常、边界、失败、安全与存量兼容路径。不得只改源码或用手工截图代替自动回归。 - C# 单元/组件/集成测试归入 `Microi.Server/Microi.Tests`。前端、应用包与 V8 的 Node 行为测试可留在责任源码旁，但必须由 `Microi.Tests/run-tests.ps1` 的自动发现入口执行；真实浏览器、数据库及第三方集成必须明确归入 Full 或专项验收，不得冒充离线单测。新增公共后端能力同时补相应 HTTP 闭环。 - `Microi一键编译发布.sh` 的所有 PC/API 镜像路径（包括仅推送、热修复）都必须先通过 Full；缺少环境、零用例、失败、取消、跳过、待办或无法解析测试结果一律停止。禁止关闭断言、删测试、排除失败项目或修改门禁阈值来发布。 - 测试成功必须绑定本次候选源码和实际构建上下文的内容哈希，构建后、每次推送前复核。旧产物没有可验证回执或源码/产物漂移时必须重建重测，禁止“当前源码通过测试 + 推送另一份旧 DLL/前端 dist”。 - 交付记录逐项列明修复与测试映射、执行数量、未覆盖边界和镜像摘要。覆盖率与 Full 都不能证明所有租户业务、任意生产数据和第三方系统绝对无误；真实客户路径仍需只读验收。详细矩阵见 `microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md`。 ### Microi吾码非阻塞自动更新（强制） - VS Code 扩展、`@microi.net/cli` 与 Codex 插件默认自动检查和安装更新。任一 Microi 任务开始时可后台投递 `microi update --background --workspace "<工作区绝对路径>" --json`，但不得等待它完成才开始业务分析、MCP 调用、源码修改、构建或发布。 - CLI 最新版只从 npm 官方 registry 查询：`npm view '@microi.net/cli' version --json --prefer-online --registry=https://registry.npmjs.org/`；VS Code 扩展只使用官方扩展宿主的自动更新/安装命令。不得使用第三方 registry 或不明镜像冒充官方更新。 - 后台更新完整闭环包含全局 CLI、`microi@microi-net`、`microi ai init`、`microi doctor` 与 `microi codex status`。`codex install --yes` 的 `--yes` 只兼容旧脚本，不是用户继续工作的授权开关。 - 当前运行中的 VS Code Extension Host、CLI、Codex Router、MCP 和对话继续使用已加载版本。禁止为了更新终止进程、强制重载、要求立即新建任务或拒绝新工作；新版只在后续新进程或宿主自然重启时接管。 - npm 官方 registry 无法访问、权限不足、文件被运行中进程占用、安装失败或宿主不能热更新时，必须写入可诊断状态并延后重试。可以非模态提示“立即重试/查看日志”，但用户忽略、关闭或暂不处理时，当前、正在进行和新建的 Microi 工作仍必须继续。 - 只有任务明确依赖旧版本不存在的具体能力时，才准确说明该能力边界与可用降级方案；不得用“最新版未通过”“尚未授权升级”作为整项任务的失败理由。 ## 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 平台后端功能必须默认按多节点部署设计：多个 API/Worker 节点位于同一负载均衡入口之后，共享业务数据库、MongoDB 和 Redis，并可能在请求执行过程中滚动发布、硬重启或发生网络分区。不得先按单机实现、上线后再补分布式保护。 - 进程内 `static`、单例、内存字典、本机定时器和本地文件只能用于单节点优化、缓冲或诊断，不能作为全局唯一状态、全局锁、任务是否执行过或业务完成的事实源。会跨请求、跨节点或跨重启使用的状态必须进入共享数据库、Redis 或可靠消息系统，并按 `OsClient` 隔离。 - `Microi.Job`、定时扫描、消息消费、补偿任务和启动初始化等可能被每个节点同时触发的逻辑，必须使用带租约和超时的分布式锁或数据库抢占；锁 Key 至少包含租户和任务唯一标识。锁必须有唯一持有者令牌、续租、超时自动释放和“仅持有者可释放”语义，必要时增加 fencing token，禁止只用 `static bool`、普通 `lock` 或不带过期时间的 Redis Key。 - 分布式锁只能减少并发执行，不能代替业务幂等。任务、接口重试、消息重投和跨节点故障转移必须同时使用稳定幂等键、数据库唯一约束/条件更新、状态机或 outbox/inbox；扣款、库存、积分、流水等副作用不得因为锁过期、节点暂停或重试而执行两次。 - 用户会话、临时票据、去重窗口、进度和任务租约默认放共享 Redis/数据库；本机缓存必须允许丢失，并通过版本号、短 TTL、发布订阅失效或数据库回源容忍节点间不一致。禁止把用户固定绑定到某节点才能保证正确性。 - 每个节点可以保留独立异步队列，但事件必须在产生时分配全局唯一 `EventId`，消费端按该 Id 幂等写入。故障 spool/WAL 必须使用固定目录的持久卷，节点标识由平台自动生成，不为此增加环境变量；共享目录也必须允许多个节点并发重放且不产生重复业务结果。 - 服务停机要先停止接收新工作，再在有上限的宽限期内排空或持久化已接收工作；重启后自动扫描并幂等恢复未完成任务、临时文件和 outbox。启动迁移、建索引、种子数据和缓存预热必须可重复运行，多节点同时启动不能报错或产生重复数据。 - 发布期间新旧版本会短暂并存。数据库、缓存值、消息和 API 合约必须遵守“先扩展、后迁移、再收缩”的向前/向后兼容顺序，不能要求所有节点同一时刻升级完成。 - 健康检查必须区分 liveness、readiness 和依赖降级；节点未完成恢复或正在排空时应退出流量，而不是继续接单后硬终止。单个节点的熔断、计数和告警只代表本节点，平台级判断必须聚合全部节点。 - 验收至少启动 2 个节点连接同一组 Redis/数据库，并覆盖：同一定时任务同时到点、同一请求/消息重复投递、锁持有者中途退出、MongoDB/Redis 短暂故障、写入后响应前重启、滚动升级和未排空时强制结束。最终断言应包括业务副作用仅一次、日志/消息可幂等恢复、无永久死锁、无重复初始化、旧新版本可共存。 - 若要求宿主机掉电或 `kill -9` 窗口内也绝对零丢失，必须在返回业务成功前取得外部持久消息队列、共享 outbox 或同步 WAL 的持久化确认；“内存队列随后异步落盘”不能宣称覆盖尚未持久化的强杀窗口。 ## 本地资源与 OOM 保护规范（强制） AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker build、浏览器自动化、压力测试或其他可能长时间占用 CPU/内存的进程前，必须先评估资源，不得为了“让构建跑过”无限抬高堆内存或 Worker 数。 - 启动前检查物理内存总量、当前占用率、可用内存，并检查是否已有同类 dev server/构建进程。已有可复用服务时禁止重复启动。 - 默认只允许一个高资源任务运行；显式限制 Worker/并发数，优先按项目、包、模块、测试分组或文件分片执行，不得并行启动多个全量构建。 - 启动重任务前按“当前阶段进程树预算 + 系统安全余量”判断：阶段预算优先采用实测峰值；尚无实测时，用已限制的堆/容器上限加明确的原生进程、Worker 与缓冲开销。系统安全余量取 `max(1.5 GB, 物理内存的 5%)`，不得再按固定 20% 将大内存机器的启动门槛线性放大。顺序执行的阶段分别计算，禁止把不会并发的阶段峰值相加。机器总内存占用达到 95% 时，立即暂停或终止 AI 启动的重任务及其子进程，不得等待 OOM。 - 禁止将 `--max-old-space-size`、JVM heap、Docker memory 或类似上限设为接近物理内存总量。除非用户明确授权独占构建窗口，单个 AI 启动的进程树不得持续占用超过物理内存的 25%。 - 后台/长任务必须记录根 PID、子进程、启动时间和独立日志，每 15-30 秒监测一次进程树内存与全机可用内存。任务失败、中断或达阈值时必须停止整个子进程树，不得遗留孤儿 Node/dotnet/Java 进程。 - 全量构建无法在上述阈值内完成时，先停止并改用定向 lint、类型检查、按模块构建或按测试文件验证。如仍必须进行全量验收，应明确报告资源瓶颈，交由 CI/专用构建机或经用户明确同意的独占时段执行，禁止在用户正在使用的 VS Code 会话里硬跑。 ### `Microi.Client` 框架前端构建频率（强制） - 修改吾码低代码平台框架前端 `Microi.Client/` 时，开发阶段必须优先复用已运行的 Vite 开发服务，通过热模块更新（HMR）、定向静态测试和浏览器回归验证改动。禁止把 `npm run build` 当作每轮修改后的常规检查，禁止因切换需求、修改单个组件或上下文压缩而重复执行全量构建。 - 只有全部框架前端源码修改、定向测试和浏览器验收均已完成后，才允许在最终收尾阶段执行一次 `npm run build`，用于确认正式产物能否生成。执行前仍须按本节检查内存、同类进程和构建预算；已经成功且之后没有再修改框架前端源码时不得重复构建。 - Vite 热更新未生效时，先检查页面、控制台、文件监听和当前 61500 开发服务归属；确需重启时按共享进程与发布锁规范精确停止本工作区原有 `npm run dev`，再重新执行 `npm run dev`。不得用 `npm run build` 代替开发服务重启，也不得结束所有 `node`、浏览器或其它对话的进程。 - 本规则只约束 `Microi.Client/` 吾码框架前端源码。独立 MicroService、Web、UniApp 等应用源码仍按其交付 Skill 在发布前执行自身必要的构建；不得因为本规则跳过微服务正式产物生成。 ## 临时文件与 AI 产物放置规则（强制） AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、测试截图、临时报告**，**严禁放在工作区根目录（`/`）**，必须放在指定位置： | 类型 | 指定位置 | |------|---------| | 一次性脚本（.py / .mjs / .ps1 / .sh） | `.tmp/` | | 诊断截图、调试图片 | `.tmp/screenshots/` | | E2E 测试产物（Microi.Code 插件生成） | `.microi-e2e/` | | AI 一次性 E2E 脚本、截图、日志、报告 | `.tmp/`、`.tmp/screenshots/`、`.tmp/reports/` | | 性能测试 HTML 报告 | `.microi-performance/` | | 项目专属临时文件 | `<对应子项目目录>/` 内，不要写到根目录 | **严禁在根目录创建**： - 任何 `*.mjs`、`*.py`、`*.ps1`、`*.sh` 一次性临时脚本 - 任何 `.tmp-*.js`、`.tmp-*.json`、`.tmp-*.txt`、`.tmp-*/` 这类伪临时文件或目录 - 任何 `screenshots/`、`dark-mode-*/`、`test-*/`、`debug-*/` 临时目录 - 孤立的 `node_modules/`（根目录没有 `package.json`，不应安装 npm 包） - 孤立的 `obj/`、`dist/`、`build/`（非对应项目文件） `.tmp/` 已在 `.gitignore` 中排除，可以随意创建临时文件。任务完成后如无保留价值可以不清理。 **2026-06 强制补充**：AI 不得在任何子项目目录下放置一次性日志、自动化截图、接口回收文件或调试脚本。像 `Microi.Server/Microi.net.Api/.tmp-*.log`、`Microi.Client/*.png` 这类文件一律视为规范失败，必须移到 `/.tmp/` 或 `/.tmp/screenshots/`。正式 Playwright 工程由 Microi.Code 插件生成时可以继续使用 `.microi-e2e/`，但 AI 为某个任务手写的一次性 Playwright 脚本、报告和截图仍然必须放在 `.tmp/`。 ## Microi 源码路径速查（工作区根相对路径） 当用户提到“吾码后端源码”“吾码前端源码”“表单引擎源码”“官网源码”等简称时，默认按下列路径定位；如果当前工作区缺少对应目录，再用 `rg --files` 或目录搜索确认实际位置。 | 用户常用说法 | 默认路径 | |--------------|----------| | 吾码 MCP 前端源码 | `microi.mcp/` | | 吾码 MCP 后端源码 | `Microi.Server/Microi.MCP/`；HTTP 接口声明保留在 `Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs` | | 吾码 skills / 知识库 | `microi.skills/` | | 吾码 VS Code 插件项目 | `Microi.Code/` | | 吾码低代码平台后台系统前端源码 | `Microi.Client/` | | 吾码后台系统前端移动端自适应源码 | `Microi.Client/src/views/mobile/` | | 吾码低代码后端源码 | `Microi.Server/` | | 吾码表单引擎源码 | `Microi.Client/src/views/form-engine/` | | 吾码表单设计器源码 | `Microi.Client/src/views/form-engine/diy-design.vue` | | 吾码数据表格渲染源码 | `Microi.Client/src/views/form-engine/diy-table.vue` | | 吾码表单渲染源码 | `Microi.Client/src/views/form-engine/diy-form.vue` | | 吾码地图控件源码 | `Microi.Client/src/views/form-engine/diy-field-component/diy-map.vue` | | 吾码界面引擎源码 | `Microi.Client/src/views/page-engine/` | | 吾码打印引擎源码 | `Microi.Client/src/views/print-engine/` | | 吾码 App 源码 | `microi.app/` | | 吾码 UniApp 源码 | `microi.uniapp/` | | 吾码官方网站 / 文档源码 | `microi.doc/` | | 吾码 AI 应用及应用商城发行源码 | 默认位于 `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/`；受审计的独立源码仓库必须由发布契约显式指定 | `Microi.MCP` 与 `Microi.AI` 一样使用独立内部 Git 仓库和统一 DLL 混淆流程。`Microi.Anderson.sln` 加载源码，`Microi.net.sln` 消费同平台版本 NuGet；MCP 实现不得放回 Core 或 Controller，Core 仅保留非 MCP 入口也需要的通用原子。根公开仓必须排除 `Microi.Server/Microi.MCP/` 的普通文件和 gitlink，发布源码指纹须覆盖该独立仓库。 以上路径只作为通用工作区相对路径规范，不写入具体本机盘符。跨仓库、空工作区或普通用户项目中，如果路径不存在，以插件生成的 `AGENTS.md`、MCP 配置和实际文件树为准。 每个 `AI应用/{appKey}` 必须只有一个可编辑事实源，统一承载界面、微服务、Manifest、接口引擎、资源策略、测试、构建脚本与商城上传素材。普通应用默认使用当前连接下的 `Microi-V8-Engine` 目录；受审计的官方内置应用若由独立 Git 仓库维护，必须由版本管理的发布契约唯一指向该源码根，并让构建、跨工程测试和发行包共同读取契约。此时同名 `Microi-V8-Engine` 目录只是远端同步镜像，不得回退为构建源。禁止靠目录探测在多份副本之间自动择新，也禁止另建无契约的 `microi.apps/` 平行发行根。 ## Skills 通用化原则 编写或更新 `microi.skills/` 下的技能文档时，**不能加入特定项目名称、特定本地路径或特定业务规则**，必须保持通用性： - ❌ 不允许：`/某客户项目/某业务应用` - ❌ 不允许：任何客户、租户或交付项目名称 - ❌ 不允许：某项目特定的费率、字段名、接口 Key 作为"规范" - ✅ 允许：使用 `<项目路径>`、`` 等占位符 - ✅ 允许：通用的最佳实践、模式和约定 - ✅ 项目特定规则应维护在各项目自己的目录内（如 `AI-Project/<项目>/` 或项目根的 `tests/`） ## Skills 中文优先规则 编写、补充或重构 Microi 吾码相关技能文档和 AI 指令文件时，**能用中文就必须用中文**。适用范围包括 `microi.skills/**/SKILL.md`、`microi.skills/README.md`、`AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md`、`.cursorrules`、`.cursor/rules/*.mdc` 以及 VS Code 插件生成这些文件的模板源码。 - 标题、段落、清单说明、验收标准、注意事项、示例代码注释、提交说明和生成文案默认使用中文。 - 只有代码/API 标识符、文件名、命令、环境变量、协议名、请求头、JSON/YAML 字段名、CSS 类名、路由、包名、框架/产品专有名词、必须原样返回的错误文本等确实不能翻译的内容才保留英文。 - 如果为了搜索、触发或兼容必须保留英文术语，采用“中文说明 + 英文标识”的写法，例如 `技能文件（Skill）`，不要整段英文说明。 - 更新 VS Code 插件生成模板时，要同步检查当前已生成的 `AGENTS.md`、`CLAUDE.md`、`.github/copilot-instructions.md`、`.cursorrules` 和 Cursor rules，避免模板下一次刷新又把英文写回来。 - 收尾时用 `rg` 扫描明显英文规范短语（如 `Use when`、`Required:`、`Forbidden:`、`Acceptance:`、`Quick Workflow`、`MCP default visibility`）。剩余英文必须属于必要标识符或专有名词。 ## 官方文档原位增补与中文单源规则（强制） 修改 Microi 官方文档前，必须先用 `rg` 查找已有页面、标题和示例，并在最匹配的现有页面原位补充。不得因为方便就新建相近主题的 Markdown 页面、导航项或页面路由，避免同一 API 的说明散落多处。只有现有目录确实没有承载该独立主题的页面，而且新页面具有长期独立维护价值时，才允许新增页面，并需同时说明新建原因和导航归属。 - 前端 V8 API 的主文档固定维护在 `microi.doc/docs/doc/v8-engine/v8-client.md`。 - 后端 V8 / 接口引擎 API 的主文档固定维护在 `microi.doc/docs/doc/v8-engine/v8-server.md`。 - 导入导出等专题页可以保留深度案例，但新增或修改 `V8.Office`、`V8.Http` 等公共 API 时，必须先补齐上述前端/后端 V8 主文档，再按需同步专题页，不能另建重复 API 页面。 - `microi.doc/docs/doc/` 是人工维护的中文文档单源；`microi.doc/docs/en/` 由官网统一翻译生成。日常功能开发只修改中文文档，不手工修改英文版，不为“中英文同步”重复写一遍。 - 文档改动后执行 `npm run docs:build`；验收时检查本次没有无理由新增 `.md` 页面或导航路由。 ## 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` 或对应插件，禁止通过新建“中转层”掩盖归属问题。 ## 多对话共享工作区变更归属保护（强制） 同一工作区可能同时被用户、其它 Codex 对话、IDE、自动化任务或外部 Git 操作修改。任务启动前已经存在、或无法用本对话证据严格证明归属的差异，一律视为他人资产并保留；“工作区是脏的”不是清理授权。 - 开始修改前先保存只读基线，至少包括 `git status --short`、目标文件的 `git diff -- `，必要时记录文件 SHA-256。VS Code 重启、上下文压缩或接续中断任务后，必须重新建立基线，不能沿用对差异归属的猜测。 - 修改时间接近当前时间、提交位于最新 `HEAD`、提交作者与当前用户相同、提交信息与当前任务相关、分支已经同步到 `origin`，都不能证明改动来自本对话；其它对话可能在同一时间和身份下提交或推送。 - 可撤回的范围只能来自本对话可核验的写入证据，例如已记录的精确 `apply_patch`、写入前后内容或明确由本对话创建且逐项可对应的 hunk。即使能证明归属，也只能反向修改这些精确 hunk，不能扩大到整文件、整提交或相邻改动。 - 执行撤回、覆盖、删除、格式化、生成器重写或 `git revert` 前，必须按 hunk 核对 `git diff` 与相关 `git show`；`git blame`、`reflog` 和提交时间只能辅助调查，不能单独作为归属证明。证据不足时停止修改并询问用户。 - 禁止为了获得干净工作区而使用整文件覆盖、`git checkout -- `、`git restore `、`git reset --hard` 或删除未跟踪文件；这些操作可能抹掉其它对话尚未提交的成果。 - 修复误撤回时，只恢复被本对话删除的原始字节/行，随后断言目标 hunk 已恢复、其它既有差异保持不变，并在最终说明中明确列出仍存在但未触碰的并行改动。 - 对 `microi.doc/docs/doc/about/update-log.md` 尤其严格：已经发布的条目即使日期是当天、位于最新提交或内容覆盖当前任务，也必须默认属于既有发布成果。除非用户明确要求修改，或本对话持有精确新增证据，否则不得删除、重写或降级该条目。 ## 本地多租户浏览器隔离（强制） - 本地 `Microi.Client` 使用 `src/config.json.ApiBaseDev` 作为默认 API；URL 中位于 `#` 之前的 `ApiBase` 与 `OsClient` 是当前页面最高优先级，标准形式为 `http://localhost:61500/?OsClient=&ApiBase=#/route`。 - 同一个浏览器 Profile/Context 下的 localhost 页面共享 localStorage、Pinia、Token、CurrentUser、 ApiBase 和 OsClient。并行测试不同目标时，一组 `ApiBase + OsClient` 必须对应一个独立浏览器 Context/Profile；Playwright/Codex 使用 `browser.newContext()`，不得只在同一 context 中新开 Page。 - 人工测试的第二个不同租户至少使用无痕窗口；多个无痕窗口可能共享同一临时会话，三个以上并行 目标必须使用独立 Profile、独立 `--user-data-dir` 或自动化独立 context。 - AI 收到线上吾码地址时，先在一次性独立 context 读取 `window.__MICROI_RUNTIME_ENDPOINT__`；旧版再回退到页面全局值、同源缓存和域名解析。确认实际 ApiBase/OsClient 后，才在新的独立 context 打开本地 URL。详细流程读取 `microi-client-frontend`、 `playwright-e2e` 与 `microi-deployment`。 ## 详细参考路由（渐进披露） 仅在当前任务涉及对应主题时读取；下列文件合计保留了原 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 插件错版共存约定