@microi.net/cli 5.7.9 → 5.8.1

package/skills/v8-workflow/SKILL.md

@@ -7,6 +7,39 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 
 # Microi V8 工作流事件开发
 
+## AI / MCP 生成流程的必检契约
+
+这里的流程是 `wf_flowdesign + wf_node + wf_line` 审批引擎，不是 `ai-workflow`。
+先用 `microi_get_db_schema` 查询 `wf_flowdesign`、`wf_node`、`wf_line`、
+`sys_menu` 与目标业务表，再用 `microi_list_roles` 或管理员只读表查询确认当前租户的
+真实用户、角色、部门、岗位 Id。人工节点 `Approve/Countersign/End` 必须配置
+`Users/Roles/Depts/BindJobs` 至少一种真实 `[{"Id":"...","Name":"..."}]`
+绑定，或明确采用上游节点 `AllowSelectUsers=1` 手动选人。
+应用安装母版可显式设置 `FlowDesign.IsEnable=0`（也接受字符串 `"0"`），
+此时人工节点允许空绑定并保持禁用；`false/null/空字符串/省略` 不属于该例外。
+禁用模板仍检查所有节点、连线、坐标及绑定格式，任何非空人员、角色、部门或岗位
+仍必须通过当前租户真实 Id 回读。不得填入 `UNBOUND_*` 等不存在的占位 Id。
+目标租户配置真实审批人后，应先重新检查再显式启用，并验收真实业务流转；
+禁用模板保存成功只证明安装结构完整，不能当作审批已可用或商业交付完成。
+`SameDeptApprove=1` 只筛选候选人，不能单独产生审批人。
+不能把 `Roles:"Manager"`、字符串 Id 数组或另一个租户的 Id 当作绑定。
+
+节点类型只使用 `Start/Auto/Business/Approve/Countersign/End/AutoEnd`；
+`End` 是人工节点，自动结束用 `AutoEnd`。每个节点应有稳定 Id；
+`PositionLeft/PositionTop` 使用像素（如 `"320px"`）。新版 MCP 对缺失坐标按
+拓扑层级布局并补 `px`，明确重叠、非法类型、断线、不可达、无人审批会在写入前失败。
+节点人员绑定在写入时仅保留 `Id/Name`，不能把完整 `sys_user` 记录及密码字段嵌入流程。
+MCP 写入前会回读当前租户的用户、角色、部门和岗位 Id；回读失败或 Id 不存在时停止保存。
+
+模块入口使用 `sys_menu.OpenType="WorkFlow"`、`FlowDesignId=<已启用流程真实 Id>`，
+`DiyTableId` 与 `wf_flowdesign.TableId` 相同。完整 Manifest 内可用模块
+`flowName` 指向同一份 `workflows[].FlowDesign.FlowName`，生成器保存流程后补写并回读
+`FlowDesignId`；引用既有流程时传 `flowDesignId`。上线前从模块打开并发起一条真实
+业务记录，确认流程图节点、人员待办、审批、历史与模块入口均正确。
+
+全部配置字段、节点类型和运行操作见
+[流程配置清单](references/workflow-configuration.md)。
+
 你正在开发 Microi 吾码平台的工作流（审批流程）V8 事件。流程引擎基于表单引擎，通过 V8 事件控制审批逻辑。
 
 ## 后端类库与接口边界
@@ -18,7 +51,7 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 - 官方发布时 `Microi.WorkFlow` 必须生成 NuGet 包，并与 `Microi.AI` 使用同一 Obfuscar 配置加密后替换包内 DLL；不得推送未加密的 WorkFlow 包。开源安装只消费 NuGet，不要求存在私有源码。
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=v8-workflow-000 sha256=9030cd2de9f1febfb9a749c82cf83e97ccb8fb972a3f8f0ff11067488e14cd8e -->
+<!-- microi-progressive:chunk id=v8-workflow-000 sha256=bd13a63ee55b2a01041fc2e080ca06ab2fbfd3146fa130811061c9f9e8b4cf84 -->
 ## 本地优先与版本头（必做）
 
 工作流节点、连线条件、开始/结束节点等 V8 代码如果有本地文件，必须优先修改 `microi-v8-engine/<租户>/<项目>/...` 下的本地文件，再同步到数据库。插件提示本地/远端不一致时，先比对并合并，不得直接覆盖。
@@ -41,7 +74,7 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 生成工作流 V8 代码时，代码内容本身（文件头、普通注释、`console.log`、返回 `Msg` 等）不要包含 `Microi`、`吾码` 等平台品牌文字，除非业务数据或字段值本身必须如此。生成代码要有可维护注释：每个 `function` 前写清用途、关键参数和返回值；路线选择、审批人计算、状态回写、撤回/驳回处理、跨表联动等复杂代码段前写短注释说明业务原因；避免“给变量赋值”这类无信息量注释。若工作流存储表支持 `Version`/`ChangeHistory`，历史说明也必须最新在前并保留旧记录。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-001 sha256=53550786c531c347cfe9d92247b07d127c348210f07e302a1b68f278136c3e77 -->
+<!-- microi-progressive:chunk id=v8-workflow-001 sha256=d365b3b609c35d28c129f6c31cb453d97e17d0b2ace53eb229d6654d7c5ddbc0 -->
 ## 工作流物理表
 
 | 表名 | 说明 |
@@ -59,6 +92,8 @@ description: Microi V8 工作流事件指南。用于编写审批流条件、节
 - 自动结束节点的 `NodeType` 使用 `AutoEnd`。它可能继承上一人工节点的 `ApprovalType=Agree`，并生成一条结束历史；核对独立审批人数时只计入明确配置的人工节点，不能把结束节点当成额外审核人。
 - 原生 `CancelFlow` 可将请求中的 `FormData` 写回 `wf_flow.FormData`；未传时可能保存 `{}`。应用不能把取消后的实例 `FormData` 当成不可变的原始提交快照。需要恢复冻结业务单时，优先核对业务表保存的服务端快照摘要；若使用原生历史，必须限定同一实例、同一业务表/行、唯一原始开始节点及发起人、自动提交历史，并检查版本、金额、配置摘要和零待办。此分支只能恢复草稿或驳回状态，不能据此批准或过账。
 - 当前 `CancelFlow(WFParam)` 使用独立事务，没有 `StartWork/SendWork` 的共享 `DbTrans` 重载。应用不得在持有实例、工作或业务行锁的接口事务内调用取消，也不能假设给它多传一个参数便会共享事务。微服务可顺序执行“服务端核验并返回真实待办坐标 → 原生取消 → 业务终态复核”，每个请求完成后释放其事务；网络结果未知时先复核终态，不能盲目重发取消或提前恢复业务状态。
+- 业务接口与原生节点共同读取配置、公共引用和业务行时，先画出宿主与脚本合并的锁图。原生审批进入节点前可能已持有流程实例锁；既存流程的业务复核应先通过当前主库有界只读发现真实实例，再在同一共享事务锁定该实例，随后获取固定配置/引用锁及业务行锁，重读验证归属未变。待办发现扫描只读不能提前锁工作行后再等流程；公共引用围栏只协调锁序，不能读取配置值来继承授权。必须逐入口审查包括定义、身份与配置的相反锁序，不以一条 SQL 或单次模拟成功宣称全系统无死锁。
+- 已由可信原生历史证明取消或驳回的终态恢复只校验原提交归属、当前授权和可恢复状态，不应要求审批期间未发生正常库存、成本或其他业务余额变化；此恢复不产生过账副作用。批准与过账仍必须严格比较冻结快照、当前期间及业务版本，并覆盖撤权、并发和响应未知时使用原请求键恢复。
 - 验收至少覆盖真实取消时不传 `FormData`、伪造取消载荷、退回后直接重提被拒绝、取消后新实例重提、自动结束继承 `Agree`，以及普通角色不能修改取证用的流程历史。模拟正确 JSON 不替代原生 HTTP 验收。
 
 直接 SQL 查询常用场景：
@@ -85,7 +120,7 @@ var history = V8.Db.FromSql(
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-002 sha256=377698ecb64266fb74399ea664010e0a46156d13c3e047de1b2cbae3dbba15c7 -->
+<!-- microi-progressive:chunk id=v8-workflow-002 sha256=38a77bbee9ea30f036a9d9ef7150e2a738f4533dc9f05c23a3d00ff86aefc60d -->
 ## 流程 V8 事件执行顺序
 
 工作流合并提交请求的 `_FormSubmitAction` 可使用 `Add/Edit`；表单后端事件中的
@@ -112,7 +147,7 @@ var history = V8.Db.FromSql(
 13. **节点结束 V8 事件（前端 WFNodeEnd）**
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-003 sha256=f5776a5b8fe4e460f79e20e9806b3a80bcadf6f1e09408880bd5ca911cb79533 -->
+<!-- microi-progressive:chunk id=v8-workflow-003 sha256=2cef523c79040139ffdfba070930ce94db18d5b3486fa35a2a694dafa2c8a186 -->
 ## V8.WF 上下文属性
 
 ### 所有流程事件可访问
@@ -147,7 +182,7 @@ var history = V8.Db.FromSql(
 | `V8.WF.WorkResult` | 流程执行结果（发送到了哪个节点、哪些审批人） |
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-004 sha256=d8445c1d473579fde063179d6330eefaa2373f1166e837656b780058295de3a3 -->
+<!-- microi-progressive:chunk id=v8-workflow-004 sha256=99db9f8361d90ce1659922ee2497b7d2f235da009219b8b6a8f22d603b818eff -->
 ## ApprovalType 审批类型
 
 | 值 | 说明 |
@@ -158,7 +193,7 @@ var history = V8.Db.FromSql(
 | `Auto` | 发起流程(开始节点) / 业务节点 / 自动结束节点 |
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-005 sha256=96e49e15fcb4b9da83f46b6818e198f338cb77ce76d11c56dfddebc2cc24f881 -->
+<!-- microi-progressive:chunk id=v8-workflow-005 sha256=28ada7e06b18590b20935fcaaa2006c868532db89838dfe3799ce2ca0f97c918 -->
 ## 条件判断 V8 事件（后端 WFNodeLine）
 
 根据业务规则决定流程走向。优先推荐设置 `V8.NextNodeId` 直接指定下一节点；如仍使用条件线的条件值，也可以设置 `V8.LineValue`。
@@ -177,7 +212,7 @@ if (V8.Form.Money <= 100) {
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-006 sha256=8e2a82330c7f49c3a03920123531d310ea329fd310179918d835e3c05d49771a -->
+<!-- microi-progressive:chunk id=v8-workflow-006 sha256=d3a984b0e45aed19da942e0fa6c4183751d6057b7360e6eb11068e538d598cf9 -->
 ## 前端发起流程
 
 ```javascript

package/skills/v8-workflow/references/progressive-01-/350/212/202/347/202/271/345/274/200/345/247/213-v8-/344/272/213/344/273/266.md

@@ -2,7 +2,7 @@
 
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
-<!-- microi-progressive:chunk id=v8-workflow-007 sha256=9c40c62b67065c7e9f6821ef748d75595f004f069909258d9867490b74e115b7 -->
+<!-- microi-progressive:chunk id=v8-workflow-007 sha256=953f9a9405bc929adab9365997f917e10df0fa16bbb2cf1448806d07fdcc945a -->
 ## 节点开始 V8 事件
 
 ### 前端 — 指定审批人
@@ -26,7 +26,7 @@ if (!V8.Form.ApprovalFiles) {
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-008 sha256=f023312e7d95c518428c2e6d1df99b43cc36d41659aa75768b13ff83cf52b3b0 -->
+<!-- microi-progressive:chunk id=v8-workflow-008 sha256=5849ffaac5c7ffdf3dcfbf4fe8e18951415e1843bd7e233f6a50e36673767f14 -->
 ## 节点结束 V8 事件
 
 ### 后端 — 流程结束后业务处理
@@ -88,7 +88,7 @@ if (V8.WF.WorkResult) {
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-009 sha256=a927ce0325e130608823800c83c85d9e83d54fea61dbcfed32208d49f4012118 -->
+<!-- microi-progressive:chunk id=v8-workflow-009 sha256=301ee4a5554069c509c559377fa57340af41b5c014cfdf95be834150ab8c8899 -->
 ## 前端打开流程表单
 
 ```javascript
@@ -106,7 +106,7 @@ V8.OpenFormWF(V8.Form, 'View', {
 ```
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-010 sha256=ea15dea212f044a16bdccbf75ebe3a28ce3eb3ff27c989e8c6b4ec567e170032 -->
+<!-- microi-progressive:chunk id=v8-workflow-010 sha256=99dde7c6359317e8b4eb72bddfc568520506550c8381e53d3d238e716c92272c -->
 ## MCP 创建/检查/测试工作流
 
 从自然语言需求创建审批流时，优先整理成完整 Manifest 的 `workflows` 配置，再走 MCP 干跑和验收流程。
@@ -149,13 +149,13 @@ MCP 操作顺序：
 - 图形条件生成的 V8 会带 `MICROI_WF_LINE_CONDITION_JSON` 标记，MCP 测试工具只解析该标记，不执行任意手写 V8。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-011 sha256=ab8c37da582f7463663ab9a609cf31e95c94e38181bc37b7c880a27f19f01a0e -->
+<!-- microi-progressive:chunk id=v8-workflow-011 sha256=70703905fd4bdbde1d645e8d1dbb77569a352da8c2014b2acd2e997464b7397a -->
 ## 发起流程与表单保存
 
 新建业务数据并发起流程时，应先保存表单，再启动流程，或使用平台的合并接口 `StartWorkWithForm` 在同一事务里完成。首次发起建议以 `Add` 模式打开流程表单；如果前端提前生成了 `Id` 但业务表还没有该行，后端会使用 `_NoLineForAdd` 兜底，避免 `UptFormData` 报“数据显示不存在”。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-012 sha256=39a371dc5106862955945741a65c2fd08423cfedbc028e6aba0ba6aadde9cc34 -->
+<!-- microi-progressive:chunk id=v8-workflow-012 sha256=4f7575ce99688366c05f2267d8271c12215d05c89e5664f7564d5cf04a94f281 -->
 ## 流程相关表
 
 | 表 | 说明 |
@@ -168,7 +168,7 @@ MCP 操作顺序：
 | `WF_History` | 流程轨迹表 |
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-workflow-013 sha256=1e0afbf91035c773357ab43dbc3658a62e368ce65ca329d1047d543558ea2e90 -->
+<!-- microi-progressive:chunk id=v8-workflow-013 sha256=d6b942d331b8504cb0e59e48ecb370e88ce572d50b1e50bf367dcbc6796fed23 -->
 ## 注意事项
 
 - 条件判断 V8 事件可以设置 `V8.NextNodeId` 直接指定下一节点；未设置时才按 `V8.LineValue` 匹配条件线的**条件值**

package/skills/workspace-conventions/SKILL.md

@@ -6,7 +6,7 @@ description: 每次 Microi 任务开始前必读的基础规范。用于识别
 # Microi 工作区全局约定
 
 <!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=0343e85fedcdf44a2dbf11c73b697b39a713d9b00054f979e40b9a085aae2353 -->
+<!-- microi-progressive:chunk id=workspace-conventions-000 sha256=d64145e9e39c0796f680659543d7504871749ea93858938aa31c9884a15a1e79 -->
 ## 任务启动前 Skill 读取规则（强制）
 
 AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端、后端、UniApp、文档、测试或交付任务前，必须先按任务类型读取相关 `microi.skills/**/SKILL.md`。不能等到写代码或出问题后才补读。
@@ -36,10 +36,11 @@ AI 处理任何 Microi 低代码、V8、MCP、OpenClaw、采集引擎、前端
 - 任务若只要求分析、评审或制定规范，仍保持只读或仅修改指定规范；身份标记不授权无关线上写入。客户部署、容器更新和应用自动安装与官方发布是独立动作，服从用户指定的手动/自动边界；用户明确手动更新时不得擅自部署。
 - 收尾必须区分“源码/文档已修改、测试通过、应用已发布回读、Skills/插件已打包或已分发、镜像已推送、客户已安装或已部署”。只有实际渠道验收成功才能说其它用户已可获取；不得把文档本地构建或插件本地副本同步称为已上线。
 
-### 每个新增与修复必须进入统一回归门禁（强制）
+### 平台回归与独立应用测试归属（强制）
 
-- 创始人源码工作区的每个功能新增、缺陷修复和兼容性调整都必须同时交付可重复执行的回归测试；先证明旧行为失败，再验证修复成功，覆盖正常、边界、失败、安全与存量兼容路径。不得只改源码或用手工截图代替自动回归。
-- C# 单元/组件/集成测试归入 `Microi.Server/Microi.Tests`。前端、应用包与 V8 的 Node 行为测试可留在责任源码旁，但必须由 `Microi.Tests/run-tests.ps1` 的自动发现入口执行；真实浏览器、数据库及第三方集成必须明确归入 Full 或专项验收，不得冒充离线单测。新增公共后端能力同时补相应 HTTP 闭环。
+- 创始人源码工作区中的每个平台功能新增、缺陷修复和兼容性调整都必须同时交付可重复执行的回归测试；先证明旧行为失败，再验证修复成功，覆盖正常、边界、失败、安全与存量兼容路径。不得只改源码或用手工截图代替自动回归。
+- 平台 C# 单元/组件/集成测试归入 `Microi.Server/Microi.Tests`。平台前端、平台内置应用包与平台 V8 的 Node 行为测试可留在责任源码旁，由 `Microi.Tests/run-tests.ps1` 自动发现执行；平台真实浏览器、数据库及第三方集成归入 Full 或平台专项验收，不得冒充离线单测。新增公共后端能力同时补相应 HTTP 闭环。
+- 官方或社区独立业务应用、游戏及客户项目的测试归应用自身源码根的 `tests/` 或独立测试工程，由该应用自己的测试和发布入口执行；不得放入 `Microi.Tests`、创建转调包装或接入平台 Quick/Full。官方发布身份不改变测试归属。应用开发中涉及平台通用缺陷时，仅把通用最小回归夹具加入平台门禁，应用业务断言仍在应用项目维护。
 - `Microi一键编译发布.sh` 的所有 PC/API 镜像路径（包括仅推送、热修复）都必须先通过 Full；缺少环境、零用例、失败、取消、跳过、待办或无法解析测试结果一律停止。禁止关闭断言、删测试、排除失败项目或修改门禁阈值来发布。
 - 测试成功必须绑定本次候选源码和实际构建上下文的内容哈希，构建后、每次推送前复核。旧产物没有可验证回执或源码/产物漂移时必须重建重测，禁止“当前源码通过测试 + 推送另一份旧 DLL/前端 dist”。
 - 交付记录逐项列明修复与测试映射、执行数量、未覆盖边界和镜像摘要。覆盖率与 Full 都不能证明所有租户业务、任意生产数据和第三方系统绝对无误；真实客户路径仍需只读验收。详细矩阵见 `microi-system-delivery/references/progressive-02-自动化测试必须覆盖的坑.md`。
@@ -106,7 +107,7 @@ AI 在用户本机启动 Node.js、Vite、Webpack、dotnet build、Java、Docker
 - 本规则只约束 `Microi.Client/` 吾码框架前端源码。独立 MicroService、Web、UniApp 等应用源码仍按其交付 Skill 在发布前执行自身必要的构建；不得因为本规则跳过微服务正式产物生成。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-004 sha256=533d4a6d674f5980fdf6e9ae376b240af20e3191126a20eae3d6235897f45a88 -->
+<!-- microi-progressive:chunk id=workspace-conventions-004 sha256=a12a204339ee40367f4c09d085d818515b0d94c7c0d748d0d455fede6b98a2e4 -->
 ## 临时文件与 AI 产物放置规则（强制）
 
 AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、测试截图、临时报告**，**严禁放在工作区根目录（`<workspace-root>/`）**，必须放在指定位置：
@@ -115,7 +116,7 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 |------|---------|
 | 一次性脚本（.py / .mjs / .ps1 / .sh） | `.tmp/` |
 | 诊断截图、调试图片 | `.tmp/screenshots/` |
-| E2E 测试产物（Microi.Code 插件生成） | `.microi-e2e/` |
+| E2E 测试产物（Microi.Agent 插件生成） | `.microi-e2e/` |
 | AI 一次性 E2E 脚本、截图、日志、报告 | `.tmp/`、`.tmp/screenshots/`、`.tmp/reports/` |
 | 性能测试 HTML 报告 | `.microi-performance/` |
 | 项目专属临时文件 | `<对应子项目目录>/` 内，不要写到根目录 |
@@ -129,10 +130,10 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 
 `.tmp/` 已在 `.gitignore` 中排除，可以随意创建临时文件。任务完成后如无保留价值可以不清理。
 
-**2026-06 强制补充**：AI 不得在任何子项目目录下放置一次性日志、自动化截图、接口回收文件或调试脚本。像 `Microi.Server/Microi.net.Api/.tmp-*.log`、`Microi.Client/*.png` 这类文件一律视为规范失败，必须移到 `<workspace-root>/.tmp/` 或 `<workspace-root>/.tmp/screenshots/`。正式 Playwright 工程由 Microi.Code 插件生成时可以继续使用 `.microi-e2e/`，但 AI 为某个任务手写的一次性 Playwright 脚本、报告和截图仍然必须放在 `.tmp/`。
+**2026-06 强制补充**：AI 不得在任何子项目目录下放置一次性日志、自动化截图、接口回收文件或调试脚本。像 `Microi.Server/Microi.net.Api/.tmp-*.log`、`Microi.Client/*.png` 这类文件一律视为规范失败，必须移到 `<workspace-root>/.tmp/` 或 `<workspace-root>/.tmp/screenshots/`。正式 Playwright 工程由 Microi.Agent 插件生成时可以继续使用 `.microi-e2e/`，但 AI 为某个任务手写的一次性 Playwright 脚本、报告和截图仍然必须放在 `.tmp/`。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-005 sha256=c48d857c8e3086b29f99ab14d362f99c60d7dd00f9617709ea4f4dcad370611e -->
+<!-- microi-progressive:chunk id=workspace-conventions-005 sha256=f627ee155b40014af76926b3a432601aa3f6bec5a7eb98ca0540c83fa41f1e5a -->
 ## Microi 源码路径速查（工作区根相对路径）
 
 当用户提到“吾码后端源码”“吾码前端源码”“表单引擎源码”“官网源码”等简称时，默认按下列路径定位；如果当前工作区缺少对应目录，再用 `rg --files` 或目录搜索确认实际位置。
@@ -142,7 +143,7 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 | 吾码 MCP 前端源码 | `microi.mcp/` |
 | 吾码 MCP 后端源码 | `Microi.Server/Microi.MCP/`；HTTP 接口声明保留在 `Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs` |
 | 吾码 skills / 知识库 | `microi.skills/` |
-| 吾码 VS Code 插件项目 | `Microi.Code/` |
+| 吾码 VS Code 插件项目 | `Microi.Agent/` |
 | 吾码低代码平台后台系统前端源码 | `Microi.Client/` |
 | 吾码后台系统前端移动端自适应源码 | `Microi.Client/src/views/mobile/` |
 | 吾码低代码后端源码 | `Microi.Server/` |
@@ -222,9 +223,17 @@ 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=dc7dbe2d2f60466a7170fff65a5df8769bc795b4ab23151a24b665380d7c6e37 -->
+<!-- microi-progressive:chunk id=workspace-conventions-009 sha256=cb0a9b2286d51e41dfd3c4249f28d4ac57b6736112be3c1f57f8eb405d0631b1 -->
 ## 多对话共享工作区变更归属保护（强制）
 
+### 功能验收后的源码提交与推送（强制）
+
+- 每个已完成并通过相应验收的功能、修复或独立里程碑，必须把本任务源码、测试和必要文档按实际 Git 仓库分别提交并推送；不能仅保存在工作区、stash、临时目录或已发布产物中。用户明确要求不提交/不推送、只读任务和未完成的实验除外，不为无改动仓库制造空提交。
+- 提交前回读工作树、暂存区、上游和远端；按可核验的本任务 hunk 暂存，保留其它对话的改动与既有暂存项。公开根仓只提交公开代码；闭源目录只从各自独立仓库根提交并推送到其已有内部远端，严格执行公开仓闭源路径门禁，不能用 gitlink 或强制添加绕过隔离。
+- 推送前先获取上游的新提交并安全整合；共享工作区有并行改动时优先在隔离候选中合并，不用整树 stash/reset 覆盖他人成果，不强推共享分支，不绕过仓库 Hook。需要精确回滚时保留独立、说明清楚的功能提交；回滚已推送功能通常使用新的反向提交，不改写共享历史。
+- 正式发布前，候选必须包含此前已交付功能的提交，并完成本任务提交、推送及远端提交号回读，再从该冻结候选构建与发布。仅更新某个说明页面时也要核对整个站点的候选；隔离工作树不能因为没有未提交变更就被当成最新线上功能。发布锁只防并发，不能代替源码完整性检查。
+- 收尾逐仓记录本地提交号、远端分支和回读结果，并区分源码推送、构建发布与真实线上验收。网络、权限、冲突或门禁阻止推送时，保留本地提交、准确报告未推送项并继续完成可独立推进的工作；不得宣称完整交付，也不得为赶进度先发布未交付源码。
+
 同一工作区可能同时被用户、其它 Codex 对话、IDE、自动化任务或外部 Git 操作修改。任务启动前已经存在、或无法用本对话证据严格证明归属的差异，一律视为他人资产并保留；“工作区是脏的”不是清理授权。
 
 - 开始修改前先保存只读基线，至少包括 `git status --short`、目标文件的 `git diff -- <file>`，必要时记录文件 SHA-256。VS Code 重启、上下文压缩或接续中断任务后，必须重新建立基线，不能沿用对差异归属的猜测。

package/skills/workspace-conventions/references/progressive-01-/347/211/210/346/234/254/346/233/264/346/226/260/346/227/245/345/277/227/344/277/235/346/212/244/350/247/204/345/210/231-/345/274/272/345/210/266.md

@@ -100,7 +100,7 @@ AI 为 Microi 平台新增或修改任何业务逻辑、后台工具、数据维
 - 平台级强制安全校验不能为了“全部低代码化”放进租户可编辑脚本而被绕过；可以留在 C#，但必须是通用、失败关闭的安全边界，不得夹带某个项目的业务文案、字段组合或状态机。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-018 sha256=9364579ba944874dcdcc71c44066e285e2a3e88140255531e03deb2ec2cab598 -->
+<!-- microi-progressive:chunk id=workspace-conventions-018 sha256=e33b8387bbe8dbc400249ca9d16f91656149492f5f7ce253cbfa67b80f4ca8ef -->
 ## 应用商城优先于 Microi.Upgrade（强制）
 
 能由应用包声明、差异安装和回读验收完成的升级，不得在 `Microi.Server/Microi.Upgrade/` 新增定制 .NET 升级类。表、字段、Tab、菜单、角色权限、接口引擎、表单事件、数据源、页面、打印、工作流、任务及可幂等安装的种子数据，默认都属于应用商城资源。
@@ -109,6 +109,7 @@ AI 为 Microi 平台新增或修改任何业务逻辑、后台工具、数据维
 - 吾码官方开发者若可调用绑定 `https://api.itdos.com`、`OsClient=iTdos` 的 `microi_itdos`，必须先在官方主租户通过 MCP 更新资源，重新制作并发布对应官方应用，发布后按字段/菜单/引擎/包版本回读；再用目标租户 MCP 安装/更新并轮询后台任务到 `Succeeded`。
 - 当前用户没有 `microi_itdos` 权限时，通过其自己的 MCP/Manifest 幂等升级自己的数据库并回读；不得为了单个租户把定制迁移塞进通用后端。确需让更多用户复用时，应生成其有权维护的社区/私有应用包。
 - 只有应用商城运行前就必须存在的物理兼容基础、跨版本核心协议迁移、存储格式变化，或安装器自身无法安全表达的不可逆平台迁移，才允许进入 `Microi.Upgrade`。每个例外必须写明“为什么应用包不能完成”、影响范围、回滚/前后兼容、分布式幂等和验收依据。
+- 自动恢复只保证启动、普通登录、菜单导航和应用商城安装／更新，SSO、AI、通知、备份、OCR、翻译等应用不能成为自动升级或启动门禁。完整官方资源放在 `Microi.Server/OfficialApplications/Resource/`，按显式清单生成 `Microi.Upgrade/Resource/` 的两项恢复资源；完整官方包的增长不得自动扩大启动闭包。更高版本且就绪的手动商城更新和既有租户 Hook 保留，失败不推进版本。
 - 允许的 .NET 迁移只能按持久化版本/迁移账本执行待办步骤，使用共享租约且业务幂等；禁止把新迁移同时加入版本链和“每次启动无条件全租户对账”列表。启动成本必须与待执行迁移数相关，不能随历史升级文件总数对每个租户线性增长。
 - 评审 `Microi.Upgrade` PR 时先做资源分类：若只是补字段、Tab 或低代码元数据，移出升级器并发布应用包；若保留 C#，必须提供双节点、重复启动、租约丢失、失败不推进版本以及旧新节点共存测试。
 
@@ -139,10 +140,10 @@ AI 开始处理定制页面、弹窗、Web、UniApp、微服务或应用商城
 如果 MCP 返回登录过期，必须先修复或刷新目标 MCP 身份，再继续把 MCP 读取结果当作当前事实；不能因为读取失败就假设在线应用不存在并重复创建。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-020 sha256=64ab3dbde08488e8cf9f320bf74d97c938507170723022efeb6ab4f96380f9ca -->
+<!-- microi-progressive:chunk id=workspace-conventions-020 sha256=60e6dac03e25861d4e0507c30ab28d28e26ada4cbe3231c3b029eb2367dc7224 -->
 ## VS Code 插件空目录生成规则
 
-Microi.Code 面向普通用户时，用户本地可能只是一个空工作区。插件生成 AI 指令文件时不能假设用户已经有 `microi.skills/`、`Microi-V8-Engine/`、`AI-Project/` 或某个固定前端项目目录。
+Microi.Agent 面向普通用户时，用户本地可能只是一个空工作区。插件生成 AI 指令文件时不能假设用户已经有 `microi.skills/`、`Microi-V8-Engine/`、`AI-Project/` 或某个固定前端项目目录。
 
 强制要求：
 - 插件的“初始化AI配置”必须能在空目录生成 `microi.skills/`、`.github/copilot-instructions.md`、`AGENTS.md`、`CLAUDE.md`、`.cursorrules`、`.cursor/rules/microi-skills.mdc`、类型提示、`jsconfig.json` 和 MCP 配置。
@@ -151,14 +152,14 @@ Microi.Code 面向普通用户时，用户本地可能只是一个空工作区
 - 插件升级时应继续保护用户本地修改过的 skill 文件，只覆盖插件曾生成且用户未改过的文件。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-021 sha256=cee19f2fffffce3b4bcd9347a50ecf27add4be0c919e1cf5d00df98d487d29b8 -->
+<!-- microi-progressive:chunk id=workspace-conventions-021 sha256=963e489e2bdda4614c8b3089830b8bb855603dbd4338ddcc7ae29519d560766f -->
 ## Microi 版本号规则
 
 Microi 通用版本号采用 `主版本.次版本.修订版本` 三段数字格式，从 `1.0.0` 开始。每次发布时最后一位加 1；当某一位超过 `9` 时向前一位进位并将当前位归 `0`，例如 `1.0.9 -> 1.1.0`、`1.9.9 -> 2.0.0`、`9.9.9 -> 10.0.0`。
 
 接口引擎代码头、表单/工作流 V8 事件代码头、前端微服务 `sys_microiservice.BuildVersion` 与 `sys_microiservice_page.BuildVersion` 这类业务发布版本统一使用带 `v` 前缀的格式：`v1.0.0 -> v1.0.1 -> v1.0.9 -> v1.1.0 -> v1.9.9 -> v2.0.0 -> v9.9.9 -> v10.0.0`。禁止使用时间戳、随机串或日期作为 BuildVersion；前端微服务上传到分布式存储的目录也必须使用同一个 BuildVersion 分段，便于回溯与 CDN 缓存隔离。
 
-`Microi.Code` 发布时会通过 `bump-version.js` 自动自增插件版本，并把 `microi.skills/.microi-skills-version.json` 中的 skills 发布版本写成同一个插件版本号；skills 不再独立自增。`.microi-skills-version.json` 只用于记录 skills 包版本和提示用户当前来源，不能单独作为覆盖依据。
+`Microi.Agent` 发布时会通过 `bump-version.js` 自动自增插件版本，并把 `microi.skills/.microi-skills-version.json` 中的 skills 发布版本写成同一个插件版本号；skills 不再独立自增。`.microi-skills-version.json` 只用于记录 skills 包版本和提示用户当前来源，不能单独作为覆盖依据。
 
 插件初始化或升级同步 `microi.skills/` 时，必须以 `.microi-skills-manifest.json` 的逐文件 hash 判断是否可覆盖：本地文件不存在则写入；本地文件与旧 manifest hash 一致说明用户未改，可自动升级；本地文件已被用户修改、或本地版本比插件捆绑版本更新时，必须保留用户版本并提示差异。不能因为插件版本号更高或更低，就粗暴覆盖本地 skills。创始人本地随时修改 skills 的工作区尤其要保护；普通用户未修改过的旧 skills 才应该被最新插件覆盖升级。
 
@@ -185,7 +186,7 @@ if (string.IsNullOrWhiteSpace(tableName)) { return; }
 如果方法内部只通过 `DynamicHelper` 读取对象字段，方法参数优先声明为 `object`，不要声明为 `dynamic`。这样可以减少 C# 运行时动态绑定进入普通字符串工具链的机会。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-023 sha256=1dfe4286cfee04571a3d24a32af15365b9da6abffe9acfd92a75539e6160f2bd -->
+<!-- microi-progressive:chunk id=workspace-conventions-023 sha256=4ef009cbfca343640e69ccdb6be47f3cb13ad8a67f9ff770debce20c919f1bb3 -->
 ## 根目录保留文件说明
 
 根目录只允许存在以下类型的文件和目录：
@@ -202,7 +203,7 @@ if (string.IsNullOrWhiteSpace(tableName)) { return; }
 | `AI-Project/` | 各租户/项目 | 否 |
 | `switch-env.ps1` | 本地环境切换工具 | 否（有用） |
 | `.tmp/` | AI 临时文件（gitignored） | 可删整个目录 |
-| `.microi-e2e/` | Microi.Code 插件 E2E 产物 | 可定期清理 |
+| `.microi-e2e/` | Microi.Agent 插件 E2E 产物 | 可定期清理 |
 | `.microi-performance/` | 性能测试报告 | 可定期清理 |
 
 <!-- /microi-progressive:chunk -->

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

@@ -2,7 +2,7 @@
 
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
 
-<!-- microi-progressive:chunk id=workspace-conventions-024 sha256=be9b3561d67f0b5489ce4b9f8c8775b563707adb9b75214807bd9c4d4fe226d4 -->
+<!-- microi-progressive:chunk id=workspace-conventions-024 sha256=4e97c278d0a813e23c2c56b11aec8b157b2b100ed6f46ea07d45dbe9954ca5aa -->
 ## Microi.net.Api 本地启动约定
 
 默认本地后端项目是 `Microi.Server/Microi.net.Api/Microi.net.Api.csproj`。AI 需要启动后端、验证接口、跑 Playwright、回读接口引擎或排查前后端联调问题时，优先使用下面的 PowerShell 命令：
@@ -20,7 +20,7 @@ Pop-Location
 **本地后端自动重启要求（强制）**：本地联调需要启动或重启 `Microi.net.Api` 时，先检查 `.tmp/microi-process-state/release.lock`；发布锁存在时禁止启动或重启。无发布时先回读标准端口和 `/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=f9b654a451871b2759c42dc0cfe532f41d71f1e57a7ebe566abe4b0eafec50a9 -->
+<!-- microi-progressive:chunk id=workspace-conventions-025 sha256=07c3d729c8f1e9a2bf93ff00937e5d6eae4602d346e4f9254b03a33211ac4848 -->
 ## 多 AI 对话共享本地服务与发布互斥（强制）
 
 同一工作区的 4、5 个 AI 对话共用同一份源码和固定端口时，`61500/61501` 是工作区级单例共享服务，不属于某个对话。端口相同意味着无法让每个对话拥有一套独立进程；正确模型是“复用健康服务 + 需要重载时串行重启 + 发布时独占”，不能让每个对话都无条件先杀再启动。
@@ -52,7 +52,7 @@ OsClient 等状态；同一 Profile/Context 内切换租户会污染其它窗口
   分层报告。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-026 sha256=7886b082424673965ce27622424be52d392a3868ebedff8c949b5d8d5e6c4caa -->
+<!-- microi-progressive:chunk id=workspace-conventions-026 sha256=73207c0cfcc442a177c47c36503dd6145fc826e23e79df3913861f65d8d16df3 -->
 ## 本地租户与测试凭据读取约定
 
 AI 在本地启动后端、跑 Playwright、做登录态页面截图或调用需要登录的接口前，必须先尝试从本地配置判断租户和测试账号，不要直接以“未登录无法测试”结束：
@@ -64,13 +64,13 @@ AI 在本地启动后端、跑 Playwright、做登录态页面截图或调用需
 5. `.microi-local`、Token、数据库连接串、Redis 密码和测试凭据都视为本地敏感配置。最终回复、日志摘要和测试报告中不得输出真实值，只能写 `<redacted>`、`本地配置账号` 或 `本地配置凭据`。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-027 sha256=5ab58f345dcff9caea31d07d7598792ddaa8a301f3527d4121a7548d32107df3 -->
+<!-- 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=5b3ff231c7fd6266c7cff45b48707bf9053da596eaf574fc0490fe6a6fe1fca6 -->
+<!-- microi-progressive:chunk id=workspace-conventions-028 sha256=6ff58ce80aab2bd47c5af022382159e98e4c4ca5eb955281e61918079d4175a5 -->
 ## V8 远端/本地同步收尾约定
 
 AI 通过 MCP、接口引擎、数据库脚本或平台 API 修改任何远端 V8 代码后，任务结束前必须把远端当前生效代码同步回本地 `Microi-V8-Engine/<server>/<osClient>/` 目录，并做一次同步状态复核。
@@ -86,22 +86,22 @@ AI 通过 MCP、接口引擎、数据库脚本或平台 API 修改任何远端 V
 收尾流程：
 - 若远端是通过 MCP 写入的，以远端当前生效代码为准回写本地文件。
 - 若本地文件是先手工修改的，先推送到远端，再重新拉取/复核，确保本地与远端一致。
-- 优先使用 Microi.Code 插件的同步/查看同步状态能力；没有可调用插件时，可在 `.tmp/` 写一次性同步脚本，但脚本必须先 dry-run 输出差异摘要，再 apply。
+- 优先使用 Microi.Agent 插件的同步/查看同步状态能力；没有可调用插件时，可在 `.tmp/` 写一次性同步脚本，但脚本必须先 dry-run 输出差异摘要，再 apply。
 - 复核结果应确认 touched 范围内 `Changed=0`、`Created=0`、`LocalOnly=0` 或说明剩余差异原因。
 - 空 V8 代码不生成本地 `.js` 文件；若已有空 `.js` 文件，收尾同步时应删除，避免被误判为本地未推送。
-- AI 收尾不能只看自写脚本的 dry-run；只要工作区安装了 Microi.Code 插件，就必须按插件“查看同步状态”的口径再复核一次。最终回复中要明确说明插件口径是否为 0；若仍有本地未推送/远端差异，必须列出具体资源类型、Key 和本地文件路径，不能只报数量。
+- AI 收尾不能只看自写脚本的 dry-run；只要工作区安装了 Microi.Agent 插件，就必须按插件“查看同步状态”的口径再复核一次。最终回复中要明确说明插件口径是否为 0；若仍有本地未推送/远端差异，必须列出具体资源类型、Key 和本地文件路径，不能只报数量。
 - 当远端代码与本地代码完全一致但插件仍提示“本地未推送”时，优先校准 `.microi-meta.json` 的 `updateTime/filePath` 与本地文件 `mtime`，并再次执行插件口径同步检查；不要让时间戳误差遗留给用户。
 - AI 通过 MCP/API 直接写远端 V8 后，必须立即回读远端当前生效代码到本地并校准 `.microi-meta.json` 与文件 `mtime`。这不是可选清理动作，而是交付完成条件；否则 VS Code 插件会按时间戳继续提示“本地未推送”。
 - 若同步状态非 0，必须先列出具体文件并分类处理：正文一致仅校准 meta/mtime，远端较新则拉回，本地较新则推送，双方都改过则人工合并。生产资金/资产系统不能为清状态盲目覆盖远端。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-029 sha256=d18db7dd385b3e691a2fdfce5cc7c32ea09f30beb6ebe19ea2193d2e98b8f7ac -->
+<!-- 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=cb93afa9d5cddef627d561b4b46c56715486ebad8be78dc13b72e1065ff89bb5 -->
+<!-- microi-progressive:chunk id=workspace-conventions-030 sha256=c25d0aaffec64d8a66cda36acd9ec337eda99a4411fddb0e966e45247ba574de -->
 ## MCP 元数据更新验收约定
 
 AI 通过 MCP 修改 `diy_field`、`diy_table`、`sys_menu`、`sys_osclients`、`sys_config` 等平台元数据后，不能只看写入返回成功，必须按前端真实消费方式回读验证：
@@ -111,7 +111,7 @@ AI 通过 MCP 修改 `diy_field`、`diy_table`、`sys_menu`、`sys_osclients`、
 3. 最终交付说明必须写清楚：改了哪个表/字段，回读值是什么，刷新了哪些缓存，验证入口是什么。若某个缓存刷新接口失败或只能部分成功，需要把失败消息原样摘要出来，不能把“写入成功”当作“页面一定生效”。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-031 sha256=51e7e4c9e28a6547613068b7758411b934c30c8d19ebfdf64569c079d05346ed -->
+<!-- microi-progressive:chunk id=workspace-conventions-031 sha256=cea2d1c912ffc31136a859fd10f282c488b5b8d1bf3f2ced7c39084b23e5ccf5 -->
 ## MCP 可用性排查约定
 
 VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”，不代表当前 AI 会话一定已经成功加载了对应工具。AI 在声称“可以通过 MCP 操作”之前，必须完成一次真实可调用性验证：
@@ -124,10 +124,10 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - MCP 的初始化说明必须使用真实 `MICROI_OS_CLIENT` 作为租户边界。中文显示名通过 ASCII 的 `MICROI_LABEL_BASE64` 传输并在 MCP 内解码，旧版 `MICROI_LABEL` 只作兼容；显示名不能当成租户 Key 写入“只能管理某租户”的安全提示。
 - 遇到 `ByteString`、`greater than 255` 或“第 N 个字符无法写入 Header”时，必须先检查实际异常索引和所有 HTTP Header 来源。Microi MCP 的设备标识来自 `did` / `MICROI_MCP_DID`；默认值若直接拼接中文 Windows 主机名，会在 `MCP:` 后第 4 个字符报错。`MICROI_LABEL_BASE64` 只用于显示，不会作为业务 HTTP Header 发送，禁止在未核对调用链前把错误归因于中文 Label。插件和 MCP 必须把 DID 规范化为稳定的可打印 ASCII。
 - MCP 连接失败时，AI 在完成配置、进程、Header、`initialize`、`tools/list` 和只读状态调用的证据链之前，不得修改 Token、租户、服务器地址或执行远端写入。连接恢复后先完成只读基线盘点，再按用户授权开始写入。
-- 修复 Microi.Code 插件的 MCP 生成逻辑后，必须重新生成配置、重启对应 MCP server，并在当前 AI 会话中再次验证工具发现与一次只读工具调用。
+- 修复 Microi.Agent 插件的 MCP 生成逻辑后，必须重新生成配置、重启对应 MCP server，并在当前 AI 会话中再次验证工具发现与一次只读工具调用。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-032 sha256=147cbc7a3870a1bc41c6e0b5ec317cf27e0e99e51eb71a1c540ebffde9507f10 -->
+<!-- microi-progressive:chunk id=workspace-conventions-032 sha256=230c8683389d2b1ee4f5ba88dc4e51cb4dc4eb6a89b76a142b07f479ff5be1c8 -->
 ## MCP 写入超时与降级约定
 
 - 写请求超时后的远端回读必须使用独立的短超时，不能继续沿用普通查询的长超时。否则一次 60 秒写超时后，每次回读还可能等待 120 秒，AI 会长期停留在“等待远端回读”，用户误以为菜单按钮或接口引擎完全写不进去。
@@ -143,7 +143,7 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - 发生连续写入超时时，要先停止并发写入，记录具体工具、资源 Key、耗时和回读结果；禁止用“服务器整体不可用”“缓存锁死”等没有日志证据的结论代替诊断。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-033 sha256=dfa4fbba6af537dfc5b4128f15652474dbbd492cdf8be1b4397cc293953b71f1 -->
+<!-- microi-progressive:chunk id=workspace-conventions-033 sha256=b642bb516a42b50e8b459e5237588e85d71c9715970779e155b88d7c0e8c6536 -->
 ## Codex MCP 单入口约定
 
 - Codex 对普通 MCP 大工具集可能无法稳定注入时，使用插件生成的 `microi_codex` 单入口，不要据此判断服务器或帐号不可用。
@@ -154,7 +154,7 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 - VS Code/Copilot、Cursor、Claude Code 仍使用完整 MCP 工具集；不要把 Codex 的 `enabled_tools = ["microi_codex"]` 复制到其他客户端配置。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-034 sha256=c47c938ab74b167fbaa6947adf58ac17d538b6736224132933328cd53b1283cc -->
+<!-- microi-progressive:chunk id=workspace-conventions-034 sha256=073253c786f85fb23b8b09c71418eaaa00f6a36262bf32e9da857340faa3e75f -->
 ## .venv Python 环境说明
 
 工作区根目录的 `.venv/` 是 Python 虚拟环境，**保留，不要删除**。已安装：
@@ -165,7 +165,7 @@ VS Code、Cursor 或 Codex 设置界面显示某个 MCP 服务器“已启用”
 
 AI 执行 Python 脚本时应使用 `.venv\Scripts\python.exe`（Windows）而非系统 Python。
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-035 sha256=811550d457030f1571c957b9d38ed706610467752d03cc1498f52bb9a8656c17 -->
+<!-- microi-progressive:chunk id=workspace-conventions-035 sha256=c114dffea6978f289601a8f71aa83a0466f3d934e96e45bb871af179d319a1e3 -->
 ## 后端代码改动后的重启验收
 
 AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果的后端源码、配置、控制器、服务、依赖项目或接口行为，任务收尾前必须完成一次“编译 + 重启本地后端 + 健康验证”，不要只用隔离输出目录 build 后结束。
@@ -185,24 +185,24 @@ AI 只要修改了 `Microi.Server/**` 下会影响 `Microi.net.Api` 运行结果
 这条规则优先于“避免打断正在运行服务”的默认谨慎策略；本地开发联调场景下，用户通常需要 launch profile 当前端口上的后端加载最新代码。
 
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=workspace-conventions-036 sha256=90694dd1a4df791de2965274c56791d4d06d131a91b472e8765dfc8a2f8f263a -->
+<!-- microi-progressive:chunk id=workspace-conventions-036 sha256=b91c431950e4c5d268d40c6372e5780b2c7e8b4ca4339871085cda91b7d932bc -->
 ## MCP 可调用性诊断补充
 
 当用户反馈“Codex/VS Code 设置中能看到 MCP，但当前 AI 会话不能调用对应工具”时，不能只回答“当前会话没有注入”。必须按层排查：
 
 1. 先确认 `.vscode/mcp.json`、`.cursor/mcp.json`、工作区根 `.mcp.json` 和 `~/.codex/config.toml` 都能解析，且目标 server key 为稳定 ASCII 格式，例如 `microi_itdos`，不要使用中文名或横杠。
-2. 再用 Microi.Code 插件的“诊断 MCP 可调用性”命令，或等价脚本直接启动对应 `mcp-server.js` / `mcp-codex-stdio-adapter.js`，执行 `initialize` 和 `tools/list`，确认 `microi_get_db_schema`、`microi_get_field_list`、`microi_add_field`、`microi_update_field`、`microi_refresh_schema_cache` 等核心工具真实返回。
-3. 如果当前 AI 客户端支持工具发现或延迟加载，AI 必须先主动执行工具发现/热加载流程，例如 `tool_search`、客户端 MCP refresh、Microi.Code 的启动/诊断命令；不要先让用户手动重启、重载或重新生成 MCP。
+2. 再用 Microi.Agent 插件的“诊断 MCP 可调用性”命令，或等价脚本直接启动对应 `mcp-server.js` / `mcp-codex-stdio-adapter.js`，执行 `initialize` 和 `tools/list`，确认 `microi_get_db_schema`、`microi_get_field_list`、`microi_add_field`、`microi_update_field`、`microi_refresh_schema_cache` 等核心工具真实返回。
+3. 如果当前 AI 客户端支持工具发现或延迟加载，AI 必须先主动执行工具发现/热加载流程，例如 `tool_search`、客户端 MCP refresh、Microi.Agent 的启动/诊断命令；不要先让用户手动重启、重载或重新生成 MCP。
 4. 如果真实握手成功但 Codex 当前对话仍没有注入 `mcp__...` 工具，AI 仍应优先使用等价的 MCP stdio JSON-RPC 直连 fallback 完成当前任务：读取对应 MCP 配置、启动 adapter/server、执行 `initialize`、`tools/list`、`tools/call`，并严格遵守该 MCP 绑定的 API Server 和 OsClient 边界。直连脚本必须放在 `.tmp/` 或使用一次性 stdin，不得散落到项目目录。
 5. 只有在客户端不支持热加载、直连 fallback 也无法完成任务，或写操作边界无法确认时，才告知用户需要新开对话、重载 Codex 或检查 MCP 配置。说明必须写清楚：MCP 配置和进程是否可用、当前会话为什么没有注入工具、已经尝试过哪些自动恢复动作。
 6. 如果握手失败，要把失败层级说清楚：配置文件解析失败、路径不存在、token 文件缺失、MCP 进程启动失败、`initialize` 失败、`tools/list` 缺核心工具，不能把这些问题混成“用户没启用 MCP”。
-7. Microi.Code 生成 MCP 配置时应清理旧的中文/横杠 Microi MCP key，只保留 `microi_<osClient>` 或 `microi_<osClient>_<host>` 形式，避免不同 AI 客户端因 namespace 不稳定而无法注入工具。
+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=8906aca9ab0a621ffc8f50c4909e6a858543acd803e427880dbdf5932a52ec8f -->
+<!-- microi-progressive:chunk id=workspace-conventions-037 sha256=287a898ffb90322af12deea949c4bcf43b9ac9a355419561898cde8de2b99ac8 -->
 ## Windows MCP 控制台闪窗复盘
 
-当用户反馈“打开 Microi.Code、添加服务器或初始化 MCP 后连续弹出并立即关闭多个 cmd 窗口”时，应按进程风暴排查，不能只给已有 `spawn` 补 `windowsHide`：
+当用户反馈“打开 Microi.Agent、添加服务器或初始化 MCP 后连续弹出并立即关闭多个 cmd 窗口”时，应按进程风暴排查，不能只给已有 `spawn` 补 `windowsHide`：
 
 1. MCP 配置文件是各客户端的事实源。内容未变化时必须使用 write-if-changed，禁止仅为“同步”而反复改写文件并触发监听器重启。
 2. 生成 `~/.codex/config.toml` 后，禁止再隐式循环执行 `codex mcp list/remove/add`；服务器数量越多，这类逐项 CLI 同步越会放大成几十个瞬时控制台进程。

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=0f36b907aab83c32be0403ce9152d1cf6ce3da23c31d6ec337643236212e77fb -->
+<!-- microi-progressive:chunk id=workspace-conventions-038 sha256=57098466d31d0636bf330fde545daff8cb8e4116ac6ea2efff8abc729fdcef77 -->
 ## CLI 与 IDE 插件错版共存约定
 
 - CLI 与 IDE 插件共用配置、Token、MCP、Skills 或生成文件时，所有持久化协议必须按“新字段可选、旧字段保留、未知字段不删除”设计。不得将 JSON 解析到旧类型后只序列化已知字段。