npm - @microi.net/cli - Versions diffs - 5.6.2 → 5.6.4 - Mend

@microi.net/cli 5.6.2 → 5.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

package/skills/v8-explorer-tree/SKILL.md CHANGED Viewed

@@ -1,226 +1,228 @@
----
-name: v8-explorer-tree
-description: Microi.VSCode 插件 V8 资源管理器目录规范（表单引擎 / 字段V8事件 / 模块引擎按钮）。覆盖 diy_table V8 事件、diy_field V8 事件、sys_menu 按钮 JSON 拆分回写，含 7 条安全不变量。用于实现 VSCode V8 事件树、重构目录布局或处理 sys_menu 按钮 JSON 序列化。
----
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-# v8-explorer-tree — V8 资源管理器目录规范 v2（2026-05）
-> 涉及文件：[Microi.VSCode/src/explorer/engineTreeProvider.ts](Microi.VSCode/src/explorer/engineTreeProvider.ts)、[Microi.VSCode/src/sync/syncManager.ts](Microi.VSCode/src/sync/syncManager.ts)、[Microi.VSCode/src/constants.ts](Microi.VSCode/src/constants.ts)、[Microi.VSCode/src/utils.ts](Microi.VSCode/src/utils.ts)、[Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs](Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs)
----
-## 0. 命名规范（强制）
-**所有目录与文件**统一使用 **中文（英文）** 形式，使用**全角括号 `（）`**：
-| 元素 | 格式 | 示例 |
-|------|------|------|
-| 表 | `<表Label>（<表Name>）` | `仓库档案（diy_cangkuda）` |
-| 字段 | `<字段Label>（<字段Name>）` | `仓库名称（CangKuName）` |
-| 菜单 | `<菜单Name中文>（<菜单英文Name>）` | `订单管理（OrderManage）` |
-| 事件 | `<事件中文名>（<EventType>）` | `前端表单进入V8事件（InFormV8）.js` |
-| 字段事件 | `<事件中文名>（<英文Key>）` | `值变更V8事件（V8Code）.js` |
-| 按钮 | `<按钮Name>（<按钮Id>）` | `指派（01K3X...）.js` |
-| 按钮显隐 | `<按钮Name>_显隐判断（<按钮Id>）` | `指派_显隐判断（01K3X...）.js` |
-| 按钮分类目录 | `<按钮类型中文>（<EnglishField>）` | `[行]更多按钮（MoreBtns）/` |
-### 0.1 7 类表单 V8 事件中文名（以 `diy_table` 对应 `diy_field.Label` 为准）
-| EventType | 中文名 |
-|-----------|--------|
-| InFormV8 | 前端表单进入V8事件 |
-| SubmitFormV8 | 前端表单提交前V8事件 |
-| SubmitBeforeServerV8 | 后端表单提交前V8事件 |
-| SubmitAfterServerV8 | 后端表单提交后V8事件 |
-| ServerDataV8 | 后端数据处理V8事件 |
-| OutFormV8 | 前端表单提交后V8事件 |
-| DataFilterV8 | 后端数据过滤V8事件 |
-> 统一用“后端”，不要再生成“服务端”或“服务器端”可见目录/文件名。
-### 0.2 4 类字段 V8 事件中文名
-| Key | 中文名 |
-|-----|--------|
-| V8Code | 值变更V8事件 |
-| KeyupV8Code | 键盘抬起V8事件 |
-| V8TmpEngineTable | 表格列模板V8事件 |
-| V8TmpEngineForm | 表单字段模板V8事件 |
-### 0.3 6 类按钮中文名
-| Field | 中文名 |
-|-------|--------|
-| PageTabs | 页面多Tab |
-| PageBtns | [页面]更多按钮 |
-| MoreBtns | [行]更多按钮 |
-| FormBtns | [表单]更多按钮 |
-| BatchSelectMoreBtns | [批量选择]更多按钮 |
-| ExportMoreBtns | [导出]更多按钮 |
----
-## 1. 当前结构（v1 基线）
-```
-<workspace>/microi-v8-engine/
-├── 接口引擎/
-│   └── <ApiEngineName>(<ApiEngineKey>).js    // 半角括号，保留不变
-└── V8事件/
-    └── <表Description(表Name)>/
-        └── <EventType>.js                    // 扁平，无中文事件名
-```
-## 2. 目标结构（v2）
-```
-<workspace>/microi-v8-engine/<server>/<osClient>/
-├── 接口引擎/                                                 // 保持不变
-│   └── <分类>/<ApiEngineName>(<ApiEngineKey>).js
-│
-├── 表单引擎/
-│   └── <表Label>（<表Name>）/
-│       ├── 表单V8事件/
-│       │   ├── 前端表单进入V8事件（InFormV8）.js              // 仅远端非空代码生成文件
-│       │   ├── 前端表单提交前V8事件（SubmitFormV8）.js
-│       │   ├── 后端表单提交前V8事件（SubmitBeforeServerV8）.js
-│       │   ├── 后端表单提交后V8事件（SubmitAfterServerV8）.js
-│       │   ├── 后端数据处理V8事件（ServerDataV8）.js
-│       │   ├── 前端表单提交后V8事件（OutFormV8）.js
-│       │   └── 后端数据过滤V8事件（DataFilterV8）.js
-│       └── 字段V8事件/
-│           └── <字段Label>（<字段Name>）/
-│               ├── 值变更V8事件（V8Code）.js                   // 右键单表拉取后生成，仅远端非空代码生成文件
-│               ├── 键盘V8事件（KeyupV8Code）.js
-│               ├── 模板V8引擎（表格）（V8TmpEngineTable）.js
-│               └── 模板V8引擎（表单）（V8TmpEngineForm）.js
-│
-└── 模块引擎/
-    └── <父菜单Name>（<ParentMenuId>）/                     // 非叶子模块只显示子模块，不生成按钮目录
-        └── <叶子菜单Name>（<LeafMenuId>）/
-            ├── Join关联（SqlJoin）.js                       // 始终生成，直接映射 sys_menu.SqlJoin
-            ├── Where条件（SqlWhere）.js                    // 始终生成，直接映射 sys_menu.SqlWhere
-            ├── 页面多Tab（PageTabs）/                     // 叶子模块固定生成全部 6 个按钮目录，即使为空
-            │   ├── <按钮Name>（<按钮Id>）.js              // V8Code，仅远端非空代码生成文件
-            │   └── <按钮Name>_显隐判断（<按钮Id>）.js     // V8CodeShow，仅在非空时生成
-            ├── [页面]更多按钮（PageBtns）/
-            ├── [行]更多按钮（MoreBtns）/
-            ├── [表单]更多按钮（FormBtns）/
-            ├── [批量选择]更多按钮（BatchSelectMoreBtns）/
-            └── [导出]更多按钮（ExportMoreBtns）/
-```
-### 2.1 ⚠️ 空代码不落文件规则（关键约束）
-> **前端 V8 引擎**只要事件 / 按钮代码字符串非空（哪怕只有注释、空格），就会调用 Jint 解析并执行——产生不必要的 CPU 开销。
->
-> 因此：拉取远端资源时，空 V8 代码**不要生成本地 `.js` 文件**。若历史同步留下空 `.js` 文件，且远端代码同样为空，应删除本地空文件，避免被“查看同步状态”误判为本地未推送。
->
-> 用户需要清空远端代码时，可以把已有非空文件清空并推送；推送成功后插件应删除该本地空文件或对齐为“无本地文件”状态。
->
-> 例外：`SqlJoin`、`SqlWhere` 是模块查询配置，不是按钮 V8 事件。叶子模块必须始终生成两个平级文件，空文件表示远端字段为空，并允许通过推送空文件清空对应字段。
----
-## 3. 数据流
-### 3.1 表单 V8 事件（✅ 已实现 2026-05）
-- **拉取**：复用 `GetV8EventList`。对每个返回项：
-  1. 每张表固定生成表单 V8 事件目录
-  2. 仅远端非空代码生成 `.js`；空代码不生成文件，历史空文件应删除
-- **保存**：`parseEventFilePath` 解析新旧两种结构，调 `UpdateV8EventCode`
-- **删除**：用户删除本地文件默认只删除本地文件，不自动清空远端；清空远端必须通过清空已有文件内容并执行推送，或使用明确的“清空远端代码”命令
-### 3.2 字段 V8 事件（✅ 已实现 2026-05）
-**接口**：
-- `GET /api/V8Debug/GetFieldList?osClient&tableId` — 返回字段列表带 `V8Code/KeyupV8Code/V8TmpEngineTable/V8TmpEngineForm`
-- `POST /api/V8Debug/UpdateField` — Body 含 `Id` 或 `TableName + Name`，仅 V8 字段更新时直接写 `diy_field`，不触发表字段物理列变更
-**实施清单**：
-1. 在 `engineTreeProvider.ts` 的表节点加 inline action「拉取此表字段V8事件」
-2. 调 `GetFieldList` 拿字段，对每个字段固定生成 4 个文件：`字段V8事件/<Label>（<Name>）/<事件中文>（<Key>）.js`
-3. 保存时按文件路径解析 `(TableId, FieldName, V8Key)` → 调 `UpdateField`
-### 3.3 sys_menu 按钮 JSON 拆分（✅ 已实现 2026-05）
-**接口**：
-- `GET /api/V8Debug/GetModule?osClient&moduleId` — 返回菜单详情，包含 6 类按钮 JSON 以及 `SqlJoin/SqlWhere`
-- `POST /api/V8Debug/UpdateModule` — Body 含 `OsClient/ModuleId` 以及目标按钮字段或 `SqlJoin/SqlWhere`
-**拉取**：
-1. 解析 `PageTabs/PageBtns/MoreBtns/FormBtns/BatchSelectMoreBtns/ExportMoreBtns` 6 个 JSON 数组（非法 JSON 记录错误并跳过该字段）
-2. 按 `ParentId` 生成与 `sys_menu/GetSysMenuStep` 一致的模块树；非叶子模块只生成子模块目录，不生成按钮目录
-3. 叶子模块固定生成全部 6 个按钮分类目录，并直接生成 `Join关联（SqlJoin）.js`、`Where条件（SqlWhere）.js`；两个配置文件即使远端为空也必须生成
-4. 对每个按钮：
-  - 仅在 `V8Code` 非空时生成 `<按钮Name>（<按钮Id>）.js`
-  - 若 `V8CodeShow` 非空 → 生成 `<按钮Name>_显隐判断（<按钮Id>）.js`
-  - 在空按钮目录中新建 `<按钮Name>（<按钮Id>）.js` 并推送时，可按文件名创建远端新按钮
-5. `.microi-meta.json` 写入按钮 JSON hash；回写前写 `.backups/<moduleId>/<ButtonField>-<timestamp>.json`
-**保存（事务，必须满足 §4 全部不变量）**：
-1. 从文件路径解析 `ModuleId / ButtonField / ButtonId / V8Code 或 V8CodeShow`
-2. 二次调 `GetModule` 拉远端当前 JSON
-3. JSON 解析失败立即中止
-4. **Id-Diff 合并**：只修改目标按钮的 `V8Code` 或 `V8CodeShow`，远端其它按钮全部原样保留
-5. 写一份 `.backups/<moduleId>/<ButtonField>-<timestamp>.json`（变更前的远端 JSON）
-6. 调 `UpdateModule` 整段写回；任何一步失败不写库
-**SqlJoin/SqlWhere 保存**：从文件路径解析 `ModuleId / SqlJoin|SqlWhere`，推送前重新 `GetModule`，备份远端原字段，`UpdateModule` 只提交目标字段；成功后必须再次 `GetModule` 回读正文完全一致，才更新 meta/mtime。空正文正常保留为空文件。
-**修改状态**：接口引擎、表单V8事件、字段V8事件、模块按钮、模块 SqlJoin/SqlWhere 文件都必须写入 `.microi-meta.json` 的 `updateTime/filePath`；本地 `mtime > updateTime + 1s` 时树节点显示 `已修改`，推送成功后同步更新 meta 并将文件 mtime 设置为远端更新时间以清除标记。
-**Controller OsClient 规则**：`CheckPermission()` 返回的 `token` 是 `dynamic`。调用 `V8McpLogic.ResolveOsClient` 时必须传 `(object)token`，并让 `ResolveOsClient(string osClient, object currentToken)` 返回真正的 `string`；Controller 中 OsClient 空判断用 `string.IsNullOrWhiteSpace(osClient)`，不要对 `osClient` 调 `DosIsNullOrWhiteSpace()`。
----
-## 4. 风险与不变量（实施 Stage 2/3 前必读）
-| # | 不变量 | 违反后果 | 检测手段 |
-|---|--------|---------|---------|
-| I1 | 按钮 `Id` 必须保留且唯一 | 远端按钮丢失/重复 | 文件名中 `（<Id>）` 段 + 头部 `@ButtonId` 双校验，二者必须一致 |
-| I2 | 远端按钮在本地缺失时**保留**而非删除 | 用户只拉了一类按钮就保存 → 其余被清空 | 保存前必须 `GetModule` 重新拉取做 Id-Diff |
-| I3 | 远端整段 JSON 哈希在保存前必须匹配 | 多人/多端冲突覆盖 | `.microi-menu.json.RemoteHash` 检查 |
-| I4 | 任何 JSON 解析失败必须中止保存 | JSON 损坏 | try/catch + 弹窗 |
-| I5 | 按钮元数据头被用户改坏（如 `@ButtonId` 被删） | 写回失败 | 元数据头丢失 → 该文件标记 dirty，提示从远端覆盖 |
-| I6 | 每次回写前自动写 `.backups/<timestamp>.json` | 误操作可恢复 | 强制执行，无配置开关 |
-| I7 | 用户重命名/删除按钮文件 | 误操作 | 重命名按 Id 匹配；删除需弹窗输入按钮名二次确认 |
----
-## 5. 实施状态（2026-05-22）
-- ✅ **Stage 1 表单V8事件分层 + 中文命名 + 空代码跳过文件生成** —— 已实现
-- ✅ **Stage 2 字段V8事件** —— 已实现：右键单表拉取字段 V8 事件；空代码不生成文件；推送仅更新目标字段的目标 V8 字段
-- ✅ **Stage 3 sys_menu 按钮拆分** —— 已实现：主拉取同步模块引擎；按钮 V8Code 仅在非空时生成 `.js`；推送前重拉远端 JSON、按 ButtonId 只改目标按钮并保留其它按钮，写入前自动备份
-- ✅ **Stage 4 树形模块引擎 + 全类型修改状态** —— 已实现：模块按 ParentId 树形拉取；非叶子只显示子模块；叶子固定生成 6 个按钮目录；字段/按钮文件也显示并清除 `已修改`
-- ✅ **Stage 5 sys_menu 查询脚本本地化** —— 已实现：叶子模块固定生成 `SqlJoin/SqlWhere` 两个平级 `.js` 文件，支持备份、预检、推送、远端回读和修改状态
----
-## 6. 实施约束总结
-- **不要**在没看过 §4 全部 7 条不变量就动手实现 Stage 3
-- **不要**为远端空 V8 事件/按钮代码生成 `.js` 文件；`SqlJoin/SqlWhere` 属于查询配置，必须保留空文件
-- **不要**用半角括号；统一用全角 `（）`
-- **不要**清空 V8事件/ 旧目录；保留兼容直到用户主动删除
-- 文件名中 `<英文Key>` 段必须 ASCII，避免 Windows 不可见字符
-- 远端 Key 若含 `\`、`/`、括号或 Windows 非法字符，文件名中的 Key 段必须使用可逆百分号编码；解析和推送时必须解码回原始 Key，禁止用 `_` 不可逆替换后误更新另一条远端记录。文件名还要处理控制字符、结尾空格/点和 `CON/PRN/AUX/NUL/COM1/LPT1` 等 Windows 保留名。
-- “拉取此服务器代码”必须按接口引擎、表单引擎、模块引擎、流程引擎、数据库结构分阶段执行。某一类型失败时要记录明细并继续后续类型；同一类型内单个文件写入失败也要继续下一项，禁止首个 `ENOENT` 让整个服务器只留下半套源码。
-## 7. AI 远端修改后的同步约束
-AI 使用 MCP、接口引擎、数据库脚本或平台 API 修改远端 V8 代码后，必须在任务收尾时同步本地 V8 资源树，并用“查看同步状态”或等价 dry-run 复核。
-- 远端写入后以远端当前生效代码为准，回写本地文件并更新/对齐 meta 与文件 mtime。
-- 覆盖范围至少包含本次 touched 的接口引擎、表单 V8 事件、字段 V8 事件、模块按钮 V8、工作流节点 V8、数据源 V8。
-- 若没有插件 API 可调用，可在 `.tmp/` 编写一次性同步脚本；脚本必须先 dry-run 输出差异数量，再 apply。
-- 收尾复核应确认 touched 范围没有 `changed/created/local-only` 差异；若存在差异，必须在最终回复中说明原因。
-- 空 V8 代码不生成本地 `.js` 文件；同步收尾时应清理历史空文件。
-- 插件“查看同步状态”不能只显示数量。若本地未推送数量大于 0，必须能列出具体资源类型、Key、名称、同步基准时间、本地修改时间和文件路径，并支持直接打开该文件。
-- 接口引擎、表单引擎、模块引擎、流程引擎四个顶层分类必须分别提供行内“查看同步状态”，分类检测只请求该类型的远端数据，禁止每次强制扫描全部引擎。表单引擎范围必须同时覆盖表单 V8 事件与字段 V8 事件，模块引擎范围必须覆盖按钮 V8 与 `SqlJoin/SqlWhere`。
-- 一次同步检测的结果必须持久保留在侧边“同步结果”树中，按双方冲突、服务器较新、本地未推送分组；用户应能连续点击不同文件查看远端/本地差异，只有主动刷新时才重新请求服务器，禁止每查看一个文件都重新执行整次检测。
-- 表单事件、字段事件、按钮事件等远端 Key 比对要做大小写兼容；当本地代码与远端代码相同但 mtime 晚于 meta 时，应自动刷新 meta/mtime，避免误报“本地未推送”。
+---
+name: v8-explorer-tree
+description: Microi.Code 插件 V8 资源管理器目录规范（表单引擎 / 字段V8事件 / 模块引擎按钮）。覆盖 diy_table V8 事件、diy_field V8 事件、sys_menu 按钮 JSON 拆分回写，含 7 条安全不变量。用于实现 VSCode V8 事件树、重构目录布局或处理 sys_menu 按钮 JSON 序列化。
+---
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+# v8-explorer-tree — V8 资源管理器目录规范 v2（2026-05）
+> 涉及文件：[Microi.Code/src/explorer/engineTreeProvider.ts](Microi.Code/src/explorer/engineTreeProvider.ts)、[Microi.Code/src/sync/syncManager.ts](Microi.Code/src/sync/syncManager.ts)、[Microi.Code/src/constants.ts](Microi.Code/src/constants.ts)、[Microi.Code/src/utils.ts](Microi.Code/src/utils.ts)、[Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs](Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs)
+---
+MCP 后端实现位于 `Microi.Server/Microi.MCP/`：`V8Engine/V8McpLogic*.cs` 维护业务操作，`Http/V8McpEndpointService.cs` 维护参数归一化与调用，HTTP/调试权限和 WebSocket 会话也由该独立库承载。API 的 `V8EngineController.cs` 只声明原有路由、HTTP 特性与转发，继续兼容 `/api/V8Engine/*`、`/api/V8Debug/*` 和 `/api/V8Debug/ws`。
+## 0. 命名规范（强制）
+**所有目录与文件**统一使用 **中文（英文）** 形式，使用**全角括号 `（）`**：
+| 元素 | 格式 | 示例 |
+|------|------|------|
+| 表 | `<表Label>（<表Name>）` | `仓库档案（diy_cangkuda）` |
+| 字段 | `<字段Label>（<字段Name>）` | `仓库名称（CangKuName）` |
+| 菜单 | `<菜单Name中文>（<菜单英文Name>）` | `订单管理（OrderManage）` |
+| 事件 | `<事件中文名>（<EventType>）` | `前端表单进入V8事件（InFormV8）.js` |
+| 字段事件 | `<事件中文名>（<英文Key>）` | `值变更V8事件（V8Code）.js` |
+| 按钮 | `<按钮Name>（<按钮Id>）` | `指派（01K3X...）.js` |
+| 按钮显隐 | `<按钮Name>_显隐判断（<按钮Id>）` | `指派_显隐判断（01K3X...）.js` |
+| 按钮分类目录 | `<按钮类型中文>（<EnglishField>）` | `[行]更多按钮（MoreBtns）/` |
+### 0.1 7 类表单 V8 事件中文名（以 `diy_table` 对应 `diy_field.Label` 为准）
+| EventType | 中文名 |
+|-----------|--------|
+| InFormV8 | 前端表单进入V8事件 |
+| SubmitFormV8 | 前端表单提交前V8事件 |
+| SubmitBeforeServerV8 | 后端表单提交前V8事件 |
+| SubmitAfterServerV8 | 后端表单提交后V8事件 |
+| ServerDataV8 | 后端数据处理V8事件 |
+| OutFormV8 | 前端表单提交后V8事件 |
+| DataFilterV8 | 后端数据过滤V8事件 |
+> 统一用“后端”，不要再生成“服务端”或“服务器端”可见目录/文件名。
+### 0.2 4 类字段 V8 事件中文名
+| Key | 中文名 |
+|-----|--------|
+| V8Code | 值变更V8事件 |
+| KeyupV8Code | 键盘抬起V8事件 |
+| V8TmpEngineTable | 表格列模板V8事件 |
+| V8TmpEngineForm | 表单字段模板V8事件 |
+### 0.3 6 类按钮中文名
+| Field | 中文名 |
+|-------|--------|
+| PageTabs | 页面多Tab |
+| PageBtns | [页面]更多按钮 |
+| MoreBtns | [行]更多按钮 |
+| FormBtns | [表单]更多按钮 |
+| BatchSelectMoreBtns | [批量选择]更多按钮 |
+| ExportMoreBtns | [导出]更多按钮 |
+---
+## 1. 当前结构（v1 基线）
+```
+<workspace>/microi-v8-engine/
+├── 接口引擎/
+│   └── <ApiEngineName>(<ApiEngineKey>).js    // 半角括号，保留不变
+└── V8事件/
+    └── <表Description(表Name)>/
+        └── <EventType>.js                    // 扁平，无中文事件名
+```
+## 2. 目标结构（v2）
+```
+<workspace>/microi-v8-engine/<server>/<osClient>/
+├── 接口引擎/                                                 // 保持不变
+│   └── <分类>/<ApiEngineName>(<ApiEngineKey>).js
+│
+├── 表单引擎/
+│   └── <表Label>（<表Name>）/
+│       ├── 表单V8事件/
+│       │   ├── 前端表单进入V8事件（InFormV8）.js              // 仅远端非空代码生成文件
+│       │   ├── 前端表单提交前V8事件（SubmitFormV8）.js
+│       │   ├── 后端表单提交前V8事件（SubmitBeforeServerV8）.js
+│       │   ├── 后端表单提交后V8事件（SubmitAfterServerV8）.js
+│       │   ├── 后端数据处理V8事件（ServerDataV8）.js
+│       │   ├── 前端表单提交后V8事件（OutFormV8）.js
+│       │   └── 后端数据过滤V8事件（DataFilterV8）.js
+│       └── 字段V8事件/
+│           └── <字段Label>（<字段Name>）/
+│               ├── 值变更V8事件（V8Code）.js                   // 右键单表拉取后生成，仅远端非空代码生成文件
+│               ├── 键盘V8事件（KeyupV8Code）.js
+│               ├── 模板V8引擎（表格）（V8TmpEngineTable）.js
+│               └── 模板V8引擎（表单）（V8TmpEngineForm）.js
+│
+└── 模块引擎/
+    └── <父菜单Name>（<ParentMenuId>）/                     // 非叶子模块只显示子模块，不生成按钮目录
+        └── <叶子菜单Name>（<LeafMenuId>）/
+            ├── Join关联（SqlJoin）.js                       // 始终生成，直接映射 sys_menu.SqlJoin
+            ├── Where条件（SqlWhere）.js                    // 始终生成，直接映射 sys_menu.SqlWhere
+            ├── 页面多Tab（PageTabs）/                     // 叶子模块固定生成全部 6 个按钮目录，即使为空
+            │   ├── <按钮Name>（<按钮Id>）.js              // V8Code，仅远端非空代码生成文件
+            │   └── <按钮Name>_显隐判断（<按钮Id>）.js     // V8CodeShow，仅在非空时生成
+            ├── [页面]更多按钮（PageBtns）/
+            ├── [行]更多按钮（MoreBtns）/
+            ├── [表单]更多按钮（FormBtns）/
+            ├── [批量选择]更多按钮（BatchSelectMoreBtns）/
+            └── [导出]更多按钮（ExportMoreBtns）/
+```
+### 2.1 ⚠️ 空代码不落文件规则（关键约束）
+> **前端 V8 引擎**只要事件 / 按钮代码字符串非空（哪怕只有注释、空格），就会调用 Jint 解析并执行——产生不必要的 CPU 开销。
+>
+> 因此：拉取远端资源时，空 V8 代码**不要生成本地 `.js` 文件**。若历史同步留下空 `.js` 文件，且远端代码同样为空，应删除本地空文件，避免被“查看同步状态”误判为本地未推送。
+>
+> 用户需要清空远端代码时，可以把已有非空文件清空并推送；推送成功后插件应删除该本地空文件或对齐为“无本地文件”状态。
+>
+> 例外：`SqlJoin`、`SqlWhere` 是模块查询配置，不是按钮 V8 事件。叶子模块必须始终生成两个平级文件，空文件表示远端字段为空，并允许通过推送空文件清空对应字段。
+---
+## 3. 数据流
+### 3.1 表单 V8 事件（✅ 已实现 2026-05）
+- **拉取**：复用 `GetV8EventList`。对每个返回项：
+  1. 每张表固定生成表单 V8 事件目录
+  2. 仅远端非空代码生成 `.js`；空代码不生成文件，历史空文件应删除
+- **保存**：`parseEventFilePath` 解析新旧两种结构，调 `UpdateV8EventCode`
+- **删除**：用户删除本地文件默认只删除本地文件，不自动清空远端；清空远端必须通过清空已有文件内容并执行推送，或使用明确的“清空远端代码”命令
+### 3.2 字段 V8 事件（✅ 已实现 2026-05）
+**接口**：
+- `GET /api/V8Debug/GetFieldList?osClient&tableId` — 返回字段列表带 `V8Code/KeyupV8Code/V8TmpEngineTable/V8TmpEngineForm`
+- `POST /api/V8Debug/UpdateField` — Body 含 `Id` 或 `TableName + Name`，仅 V8 字段更新时直接写 `diy_field`，不触发表字段物理列变更
+**实施清单**：
+1. 在 `engineTreeProvider.ts` 的表节点加 inline action「拉取此表字段V8事件」
+2. 调 `GetFieldList` 拿字段，对每个字段固定生成 4 个文件：`字段V8事件/<Label>（<Name>）/<事件中文>（<Key>）.js`
+3. 保存时按文件路径解析 `(TableId, FieldName, V8Key)` → 调 `UpdateField`
+### 3.3 sys_menu 按钮 JSON 拆分（✅ 已实现 2026-05）
+**接口**：
+- `GET /api/V8Debug/GetModule?osClient&moduleId` — 返回菜单详情，包含 6 类按钮 JSON 以及 `SqlJoin/SqlWhere`
+- `POST /api/V8Debug/UpdateModule` — Body 含 `OsClient/ModuleId` 以及目标按钮字段或 `SqlJoin/SqlWhere`
+**拉取**：
+1. 解析 `PageTabs/PageBtns/MoreBtns/FormBtns/BatchSelectMoreBtns/ExportMoreBtns` 6 个 JSON 数组（非法 JSON 记录错误并跳过该字段）
+2. 按 `ParentId` 生成与 `sys_menu/GetSysMenuStep` 一致的模块树；非叶子模块只生成子模块目录，不生成按钮目录
+3. 叶子模块固定生成全部 6 个按钮分类目录，并直接生成 `Join关联（SqlJoin）.js`、`Where条件（SqlWhere）.js`；两个配置文件即使远端为空也必须生成
+4. 对每个按钮：
+  - 仅在 `V8Code` 非空时生成 `<按钮Name>（<按钮Id>）.js`
+  - 若 `V8CodeShow` 非空 → 生成 `<按钮Name>_显隐判断（<按钮Id>）.js`
+  - 在空按钮目录中新建 `<按钮Name>（<按钮Id>）.js` 并推送时，可按文件名创建远端新按钮
+5. `.microi-meta.json` 写入按钮 JSON hash；回写前写 `.backups/<moduleId>/<ButtonField>-<timestamp>.json`
+**保存（事务，必须满足 §4 全部不变量）**：
+1. 从文件路径解析 `ModuleId / ButtonField / ButtonId / V8Code 或 V8CodeShow`
+2. 二次调 `GetModule` 拉远端当前 JSON
+3. JSON 解析失败立即中止
+4. **Id-Diff 合并**：只修改目标按钮的 `V8Code` 或 `V8CodeShow`，远端其它按钮全部原样保留
+5. 写一份 `.backups/<moduleId>/<ButtonField>-<timestamp>.json`（变更前的远端 JSON）
+6. 调 `UpdateModule` 整段写回；任何一步失败不写库
+**SqlJoin/SqlWhere 保存**：从文件路径解析 `ModuleId / SqlJoin|SqlWhere`，推送前重新 `GetModule`，备份远端原字段，`UpdateModule` 只提交目标字段；成功后必须再次 `GetModule` 回读正文完全一致，才更新 meta/mtime。空正文正常保留为空文件。
+**修改状态**：接口引擎、表单V8事件、字段V8事件、模块按钮、模块 SqlJoin/SqlWhere 文件都必须写入 `.microi-meta.json` 的 `updateTime/filePath`；本地 `mtime > updateTime + 1s` 时树节点显示 `已修改`，推送成功后同步更新 meta 并将文件 mtime 设置为远端更新时间以清除标记。
+**MCP 请求服务 OsClient 规则**：`CheckPermission()` 返回的 `token` 是 `dynamic`。调用 `V8McpLogic.ResolveOsClient` 时必须传 `(object)token`，并让 `ResolveOsClient(string osClient, object currentToken)` 返回真正的 `string`；`Microi.MCP/Http/V8McpEndpointService.cs` 中 OsClient 空判断用 `string.IsNullOrWhiteSpace(osClient)`，不要对 `osClient` 调 `DosIsNullOrWhiteSpace()`。
+---
+## 4. 风险与不变量（实施 Stage 2/3 前必读）
+| # | 不变量 | 违反后果 | 检测手段 |
+|---|--------|---------|---------|
+| I1 | 按钮 `Id` 必须保留且唯一 | 远端按钮丢失/重复 | 文件名中 `（<Id>）` 段 + 头部 `@ButtonId` 双校验，二者必须一致 |
+| I2 | 远端按钮在本地缺失时**保留**而非删除 | 用户只拉了一类按钮就保存 → 其余被清空 | 保存前必须 `GetModule` 重新拉取做 Id-Diff |
+| I3 | 远端整段 JSON 哈希在保存前必须匹配 | 多人/多端冲突覆盖 | `.microi-menu.json.RemoteHash` 检查 |
+| I4 | 任何 JSON 解析失败必须中止保存 | JSON 损坏 | try/catch + 弹窗 |
+| I5 | 按钮元数据头被用户改坏（如 `@ButtonId` 被删） | 写回失败 | 元数据头丢失 → 该文件标记 dirty，提示从远端覆盖 |
+| I6 | 每次回写前自动写 `.backups/<timestamp>.json` | 误操作可恢复 | 强制执行，无配置开关 |
+| I7 | 用户重命名/删除按钮文件 | 误操作 | 重命名按 Id 匹配；删除需弹窗输入按钮名二次确认 |
+---
+## 5. 实施状态（2026-05-22）
+- ✅ **Stage 1 表单V8事件分层 + 中文命名 + 空代码跳过文件生成** —— 已实现
+- ✅ **Stage 2 字段V8事件** —— 已实现：右键单表拉取字段 V8 事件；空代码不生成文件；推送仅更新目标字段的目标 V8 字段
+- ✅ **Stage 3 sys_menu 按钮拆分** —— 已实现：主拉取同步模块引擎；按钮 V8Code 仅在非空时生成 `.js`；推送前重拉远端 JSON、按 ButtonId 只改目标按钮并保留其它按钮，写入前自动备份
+- ✅ **Stage 4 树形模块引擎 + 全类型修改状态** —— 已实现：模块按 ParentId 树形拉取；非叶子只显示子模块；叶子固定生成 6 个按钮目录；字段/按钮文件也显示并清除 `已修改`
+- ✅ **Stage 5 sys_menu 查询脚本本地化** —— 已实现：叶子模块固定生成 `SqlJoin/SqlWhere` 两个平级 `.js` 文件，支持备份、预检、推送、远端回读和修改状态
+---
+## 6. 实施约束总结
+- **不要**在没看过 §4 全部 7 条不变量就动手实现 Stage 3
+- **不要**为远端空 V8 事件/按钮代码生成 `.js` 文件；`SqlJoin/SqlWhere` 属于查询配置，必须保留空文件
+- **不要**用半角括号；统一用全角 `（）`
+- **不要**清空 V8事件/ 旧目录；保留兼容直到用户主动删除
+- 文件名中 `<英文Key>` 段必须 ASCII，避免 Windows 不可见字符
+- 远端 Key 若含 `\`、`/`、括号或 Windows 非法字符，文件名中的 Key 段必须使用可逆百分号编码；解析和推送时必须解码回原始 Key，禁止用 `_` 不可逆替换后误更新另一条远端记录。文件名还要处理控制字符、结尾空格/点和 `CON/PRN/AUX/NUL/COM1/LPT1` 等 Windows 保留名。
+- “拉取此服务器代码”必须按接口引擎、表单引擎、模块引擎、流程引擎、数据库结构分阶段执行。某一类型失败时要记录明细并继续后续类型；同一类型内单个文件写入失败也要继续下一项，禁止首个 `ENOENT` 让整个服务器只留下半套源码。
+## 7. AI 远端修改后的同步约束
+AI 使用 MCP、接口引擎、数据库脚本或平台 API 修改远端 V8 代码后，必须在任务收尾时同步本地 V8 资源树，并用“查看同步状态”或等价 dry-run 复核。
+- 远端写入后以远端当前生效代码为准，回写本地文件并更新/对齐 meta 与文件 mtime。
+- 覆盖范围至少包含本次 touched 的接口引擎、表单 V8 事件、字段 V8 事件、模块按钮 V8、工作流节点 V8、数据源 V8。
+- 若没有插件 API 可调用，可在 `.tmp/` 编写一次性同步脚本；脚本必须先 dry-run 输出差异数量，再 apply。
+- 收尾复核应确认 touched 范围没有 `changed/created/local-only` 差异；若存在差异，必须在最终回复中说明原因。
+- 空 V8 代码不生成本地 `.js` 文件；同步收尾时应清理历史空文件。
+- 插件“查看同步状态”不能只显示数量。若本地未推送数量大于 0，必须能列出具体资源类型、Key、名称、同步基准时间、本地修改时间和文件路径，并支持直接打开该文件。
+- 接口引擎、表单引擎、模块引擎、流程引擎四个顶层分类必须分别提供行内“查看同步状态”，分类检测只请求该类型的远端数据，禁止每次强制扫描全部引擎。表单引擎范围必须同时覆盖表单 V8 事件与字段 V8 事件，模块引擎范围必须覆盖按钮 V8 与 `SqlJoin/SqlWhere`。
+- 一次同步检测的结果必须持久保留在侧边“同步结果”树中，按双方冲突、服务器较新、本地未推送分组；用户应能连续点击不同文件查看远端/本地差异，只有主动刷新时才重新请求服务器，禁止每查看一个文件都重新执行整次检测。
+- 表单事件、字段事件、按钮事件等远端 Key 比对要做大小写兼容；当本地代码与远端代码相同但 mtime 晚于 meta 时，应自动刷新 meta/mtime，避免误报“本地未推送”。

package/skills/v8-file-upload/SKILL.md CHANGED Viewed

@@ -13,6 +13,31 @@ description: Microi V8 与 MCP 文件上传下载指南。用于处理流式 AI
 ## 表单字段的公有桶与私有桶（强制）
+- `Config.FileUpload.EnableRolePermission=true` 的字段强制私有上传，优先级高于字段和请求 `Limit`。
+  每个附件 `VisibleRoleIds` 多选真实角色，三个默认关闭的开关为 `HideUnauthorizedFiles`、
+  `ShowUnauthorizedFileName`、`DisableRoleInheritance`。无权限时后端仅返回脱敏占位，不含 Path、
+  Versions 或签名地址；普通保存必须保留无权附件，不能改角色、改名、删除或通过复制路径重新授权。
+  上传响应的 `_UploadProof` 绑定当前租户、用户、字段、记录、私有路径及有效期，只用于首次保存校验，
+  持久化时移除；新文件须携带当前记录/字段上下文上传。历史公有附件需重新私有上传后才能设置角色。
+  完整配置、继承与 MCP 流程见 `../microi-form-engine/SKILL.md`。
+### 旧上传返回与接口引擎扩展
+- 系统设置 `CompatiblePlatformOldVersion` 默认关闭，空值/缺字段也关闭；开启时旧 HTTP 上传
+  保留 `Code/Data`，单文件也统一返回数组（包括 `Multiple=false`），补 `url/type/size/duration/uploading/progress/path/name/id`。
+  图片 `type=image`，名称去掉最后一个扩展名；`url` 必须沿用实际 `Url`，不能把私有文件改拼公有地址。
+- `/api/HDFS/upload`、`/api/Upload`、`/apiengine/platform-hdfs-upload` 使用当前租户上传引擎。
+  只有主库确认完整地址、别名及固定 Key 缺失才执行编译兜底；禁用、StopHttp、拒绝或异常不兜底。
+- `V8.Method.UploadCurrentRequestAsync()` 复用已验证的当前请求文件流，重复调用只上传一次；
+  `V8.Method.IsLegacyUploadCompatibilityEnabled()` 读取宿主取得的开关，二者均不接受参数。
+  它们绑定当前租户与选定引擎，普通脚本或嵌套其它引擎不能借用；无请求时使用原有 `V8.Method.Upload`。
+- 返回编排由系统设置应用拥有的 Managed `platform-hdfs-upload` 实现；持久定制使用
+  CreateIfMissing `platform-hdfs-upload-hook`，返回 `{Code:1, UploadResult:完整结果}`。
+  先用 `JSON.parse(JSON.stringify(V8.Param.Result))` 转为普通 JS 对象，再判断 `Data` 数组并遍历追加字段；不能直接对 CLR 包装对象使用 `Array.isArray` 或 `length` 分支。
+  系统设置及基础空库包都交付可空字段，但上传引擎只由系统设置包拥有；不携带租户开关值。
+- MCP 复用 `microi_add_field`、`microi_update_field`、`microi_create_engine`、
+  `microi_save_engine_code` 和管理员回读；验收分别覆盖真实上传、配置缓存、引擎优先、缺失及错误分支。
 - `ImgUpload`、`FileUpload`、`RichText` 的“禁止匿名访问”是字段权威策略：`Limit=false` 写公有桶，`Limit=true` 写私有桶。普通用户只要通过当前菜单/表的新增或编辑动作授权，也必须按该字段配置执行；不得按用户等级把全部非超级管理员上传统一改成私有桶。
 - 浏览器上传必须携带 `FormEngineKey + FieldId + SysMenuId`，编辑已有记录再带 `FormDataId`，TableChild 再带父子授权上下文。后端先用 FormEngine 校验动作权限，再从当前租户回读 `diy_field.Component/Config`，用权威 `Limit` 覆盖请求值，并把目录固定为 `ImgUpload→img`、`FileUpload→file`、`RichText→editor`。
 - 客户端 `Limit`、`Path`、字段 Id 和菜单 Id 都只是待验证线索。没有可验证字段上下文的普通交互式上传默认私有并限制到安全一级目录；不能为了恢复公有字段语义而重新信任裸 `Limit=false`。
@@ -79,7 +104,7 @@ description: Microi V8 与 MCP 文件上传下载指南。用于处理流式 AI
 可信后端 V8 可用 `V8.Http.GetResponse({ Url: url }).RawBytes` 下载，再用 `System.Convert.ToBase64String` 和 `V8.Method.Upload` 上传。该路径同样必须校验域名、大小、Content-Type、后缀和最终重定向目标。
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-file-upload-002 sha256=ed7e727c51bd2416ae1f38cf3c4bd09491e616df08473a610372e0ca648e1298 -->
+<!-- microi-progressive:chunk id=v8-file-upload-002 sha256=d55c1a7fce715bf15224a74a2ae3006f38bab04bfe876ad88d9cc064fbe7cb9a -->
 ## 接收前端上传的文件
 前端发起文件上传时，平台自动把文件以 base64 形式注入到 `V8.FilesByteBase64`：

package/skills/v8-file-upload/references/progressive-01-/345/205/254/346/234/211/346/241/266-vs-/347/247/201/346/234/211/346/241/266.md CHANGED Viewed

@@ -2,7 +2,7 @@
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-<!-- microi-progressive:chunk id=v8-file-upload-005 sha256=b09a96f25aef20eb8cbb204bd785cce370dcd2c9a28563c6f6d720fbdaa5218f -->
+<!-- microi-progressive:chunk id=v8-file-upload-005 sha256=9efd186d8af26854bbed4d675b31fff57202a0139094798d9a41c3e4769fd092 -->
 ## 公有桶 vs 私有桶
 ### 应用商城 ZIP

package/skills/v8-file-upload/references/progressive-02-office-/346/226/207/344/273/266/345/234/250/347/272/277/347/274/226/350/276/221/347/211/210/346/234/254/345/217/267/350/247/204/345/210/231.md CHANGED Viewed

@@ -2,7 +2,7 @@
 > 按需读取；本文件由 SKILL.md 的原章节无损拆分。
-<!-- microi-progressive:chunk id=v8-file-upload-008 sha256=5e3b59486745d3c54bd8ad25c43cbe2396e6d614394340b93d93794b6df56292 -->
+<!-- microi-progressive:chunk id=v8-file-upload-008 sha256=7cda0fe7bb978e7219cb3c1ba30813e1a5e777f1272410f85d4c7ecc1882cc3d -->
 ## Office 文件在线编辑版本号规则
 当文件上传控件开启【Office 在线预览】、【允许在线编辑】和【开启 Office 文件版本号】时，前后端必须遵循统一版本规则：
@@ -39,7 +39,7 @@
 ```
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-file-upload-009 sha256=50fba71370f45de3dd677f5731f3956c328a8d3b1ca2125b853128067f9af40a -->
+<!-- microi-progressive:chunk id=v8-file-upload-009 sha256=e01219d4f1a8f8c535e0b5aa5620120c37bd5e79af27dbbd63babda8d887cd13 -->
 ## ImgUpload / FileUpload 字段值兼容规则
 `ImgUpload` 不能假设只是一种值结构。PC 表单、移动端、旧数据、单图/多图、公开/私有桶会混合出现以下格式：
@@ -120,7 +120,7 @@ function publicUploadUrl(path) {
 私有桶（`Limit === true`）不要拼 `FileServer`，必须把归一化后的 `Path` 传给 `V8.Method.GetPrivateFileUrl({ FilePathName: path })` 或后端签名接口换临时 URL。
 <!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-file-upload-010 sha256=f34d476435c3a8321df017b481771d757f580c8d75f7648fdd54ee1c624d116c -->
+<!-- microi-progressive:chunk id=v8-file-upload-010 sha256=229294a07a8db953219c35292db5558430addb576505695b9ce88a275eb46232 -->
 ## 安全注意
 - ❌ 不要让前端任意指定 `Path`（路径穿越风险），只允许后端固定路径

package/skills/v8-http-integration/SKILL.md CHANGED Viewed

@@ -5,7 +5,9 @@ description: Microi V8 HTTP 集成指南。用于通过 V8.Http.Get/Post/Patch
 > **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-# Microi V8 HTTP 外部接口集成
+# Microi V8 HTTP 外部接口集成
+第三方集成一旦需要 App Secret、ClientSecret、API Key（例如畅捷通 T+），先发现现有“系统设置 → 安全与服务接入”，调用 `microi_manage_server_private_secret` 的 List/Save，将 Secret 存为当前租户 `mci_system_setting` 的加密私密项。后端通过 `V8.SysConfig.ServerPrivateSettings['Integration.Changjet.AppSecret']` 使用。不要因为 `V8.OsClientModel` 已脱敏就判断平台无法存储或读取 Secret，也不要要求新增服务器配置/C# 端点。已有用户授权即可执行保存与脱敏回读；缺少工具时先读取 `../v8-security/SKILL.md` 的现有能力与实际连接版本。
 你正在开发 Microi 吾码平台的 V8 引擎代码，需要调用外部 HTTP API（微信、支付宝、短信、ERP 等第三方系统）。

package/skills/v8-security/SKILL.md CHANGED Viewed

@@ -15,7 +15,9 @@ description: Microi V8 安全指南。用于审查 DiyToken 与权限、可逆
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=v8-security-000 sha256=d03ee34e72925db55f9022de26dfc251c0d3d69fac52ae6a910d42ddfc142ae7 -->
-## 0. 租户动态系统设置与密钥边界
+## 0. 租户动态系统设置与密钥边界
+**AI 默认处理路径：** 用户交付第三方 Secret 并授权配置时，优先调用 `microi_manage_server_private_secret`：List 只确认 Key/HasSecret；Save 使用 `confirmExecution=SAVE:<ConfigKey>`，固定 `IsSecret=true / IsPublic=false` 并自动脱敏回读。例如畅捷通使用 `Integration.Changjet.AppSecret`，后端从 `V8.SysConfig.ServerPrivateSettings` 使用。不要仅拒绝硬编码后停止，也不要因为 `OsClientModel` 不暴露密钥而误判服务端 V8 无法调用第三方。工具不提供原文揭示；更换已有 Key 前回读现状，超时只回读、不盲目重写。
 第三方密钥（微信、支付宝、OpenAI、阿里云、ERP、SMTP）**禁止**硬编码在 V8 代码或前端。公开的租户配置必须建成当前租户 `sys_config` 的实体字段；敏感或仅供后端使用的租户业务配置保存到 `mci_system_setting`。数据库、Redis、MongoDB、MinIO、MQ 等部署控制面仍由主库 `sys_osclients` 托管，子租户不能修改。