flycode-mcp 1.14.7 → 1.14.8

package/dist/skills/flycode-mcp-skill/SKILL.md

@@ -72,9 +72,9 @@ Python / Node（或 curl / psql / 其他语言）直接打 APaaS 平台 HTTP 接
 | **form**          | `page_form_directories`       | 只读       | 查**表单所属目录**：返回 `directorytypecode`（即表单 `pageinfo.directorytypecode` 的取值）。接口无分页、全量数百条，故**必须带 `keys` 检索**（目录名模糊，也命中 `centername`），或用 `parentdirectorytypecode` 下钻（`root`=只看顶级）；默认回 30 条、硬上限 200，回 `truncated`/`hint` |
 | **form**          | `page_form_list`              | 只读       | 分页搜表单/页面（按 `code`/`title`/`keywords`/`type`/`status`）           |
 | **form**          | `get_form`                    | 只读       | 查表单完整详情（88KB 级，含 `view` 控件树 / `presenter` 事件 / `businessmodel`） |
-| **form**          | `get_form_outline`            | 只读       | 表单轻量骨架（2–4KB）：节点树 + handlers/interfaces 清单 + 逻辑名                |
+| **form**          | `get_form_outline`            | 只读       | 表单轻量骨架（数 KB）：节点树 + **弹窗骨架 `subviews`** + handlers/interfaces 清单 + 逻辑名 |
 | **form**          | `get_form_fragment`           | 只读       | 表单局部内容（按 `nodeCode`/`handlerCode`/`section` 取几 KB）              |
-| **form**          | `patch_form`                  | 写        | 局部改表单（14 类 ops：控件属性/数组项增删/action 增删改/action 内数组绑定/插删移节点/改脚本/增删 businessmodel）             |
+| **form**          | `patch_form`                  | 写        | 局部改表单（15 类 ops：控件属性/数组项增删/**弹窗增删改**/action 增删改/action 内数组绑定/插删移节点/改脚本/增删 businessmodel）             |
 | **form**          | `save_form`                   | 写        | 整页重构时才用：回传完整 `FormResult` 全量保存                                  |
 | **h5**            | `page_h5_form`                | 只读       | 分页搜 H5 表单（智慧100 引擎）                                             |
 | **h5**            | `get_h5_form`                 | 只读       | 查 H5 表单详情（核心 `confjson` 含 Vue 代码）                               |
@@ -149,8 +149,8 @@ flycode-mcp 默认开启 `PROGRESSIVE_DISCLOSURE=on`：连接后客户端只看
 | 搜名字/代码关键字带「价格同步」的逻辑       | `logic`    | `page_model_logic_list`（`keys`/`keywords`）                     |
 | 查业务逻辑(modelLogic/模型逻辑/领域)所属目录 / 找某逻辑(modelLogic/模型逻辑/领域)挂在哪个目录     | `logic`    | `page_model_logic_directories`（`modelname` 模糊搜 / `directorytypecode` 下钻子目录，默认 `rootNode` 查一级；返回 `modelcode` 即查该目录逻辑要用的编码） |
 | 看某条业务逻辑(modelLogic/模型逻辑/领域)完整内容（含 flycode）    | `logic`    | `get_model_logic`（`modellogiccode`）                            |
-| 先看表单长啥样（骨架）               | `form`     | `get_form_outline`（`code`）→ 2–4KB                              |
-| 看表单里某段脚本 / 某节点            | `form`     | `get_form_fragment`（`code`+`nodeCode`/`handlerCode`/`section`） |
+| 先看表单长啥样（骨架）               | `form`     | `get_form_outline`（`code`）→ 数 KB；**弹窗 code 在返回的 `subviews` 里**（`viewTree` 不含弹窗）           |
+| 看表单里某段脚本 / 某节点            | `form`     | `get_form_fragment`（`code`+`nodeCode`/`handlerCode`/`section`；`nodeCode` 可命中弹窗及其内部控件，`section:"subviews"` 取全部弹窗） |
 | 看表单完整结构（含控件树/事件）          | `form`     | `get_form`（`code`，88KB 级，非必要不用）                                |
 | 搜表单/页面                    | `form`     | `page_form_list`（`keys`/`type`/`status`）                       |
 | 查表单挂在哪个目录 / 取目录编码 directorytypecode | `form`     | `page_form_directories`（**先 `keys` 模糊搜目录名**；无筛选时只回顶级目录。切勿裸调拉全量——接口无分页、实测 352 条/74KB） |
@@ -169,7 +169,7 @@ flycode-mcp 默认开启 `PROGRESSIVE_DISCLOSURE=on`：连接后客户端只看
 | 加/删 input 或 output 参数、加/改字段属性 | `patch_model_logic`                                              |
 | 改逻辑标题/描述/`actiontype` 等顶层元数据  | `patch_model_logic`（`set_meta`）                                  |
 | 改导出类（`actioncategory=5`）的导出列  | `patch_model_logic`（5 类导出 op，**勿用 `set_meta` 碰 `bindjson`**）     |
-| 给表单加/删/移控件、改控件属性、改 UI 脚本、增删改 action、改 action 内数组绑定 | `patch_form`（14 类 ops）                                           |
+| 给表单加/删/移控件、改控件属性、改 UI 脚本、增删改 action、改 action 内数组绑定、**改/加/删弹窗（popview）** | `patch_form`（15 类 ops）                                           |
 | 整页重构表单布局                      | `save_form`（回传完整 `FormResult`）                                   |
 | **新建**一条业务逻辑（首次创建）            | `save_model_logic`（配 `generate_unique_code` 生成 `modellogiccode`） |
 | 已有逻辑全量 JSON 很小（如微服务）          | `save_model_logic` 全量保存                                          |
@@ -203,10 +203,12 @@ flycode-mcp 默认开启 `PROGRESSIVE_DISCLOSURE=on`：连接后客户端只看
 
 | 改的内容                                                                  | 选                                                                                  |
 | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| 局部：改控件属性、数组内单元素（列 `options`/样式）、插/删/移节点、改某 action 脚本、**增删改 action 本身**、增删 businessmodel、**把界面输出绑定到控件（改 `datarequest.setter`）** | **`patch_form`**（14 类 ops；view 树数组用 `patch_node_array_item`，handler action 内数组用 `patch_action_array_item`，action 本身增删改用 `add_action`/`patch_action`/`remove_action`，避免 `set_attrs` 整段覆盖大数组） |
+| 局部：改控件属性、数组内单元素（列 `options`/样式）、插/删/移节点、改某 action 脚本、**增删改 action 本身**、增删 businessmodel、**把界面输出绑定到控件（改 `datarequest.setter`）**、**弹窗（`view.subviews`）及其内部控件的增删改** | **`patch_form`**（15 类 ops；view 树数组用 `patch_node_array_item`，handler action 内数组用 `patch_action_array_item`，**弹窗根节点用 `patch_view_array_item`（`arrayProp:"subviews"`）**，action 本身增删改用 `add_action`/`patch_action`/`remove_action`，避免 `set_attrs` 整段覆盖大数组） |
 | 整页重构（重排布局、模板迁移）                                                       | **`save_form`**（回传完整 `FormResult`）                                                 |
 
-> 数组元素级改动一律用 `patch_node_array_item`（view 树节点数组，如单列 `options`/`cols`，支持 merge/append/insert/remove）或 `patch_action_array_item`（presenter.handlers/initial 的 action 内数组，如 `datarequest.setter` 绑定输出到控件、`param.properties`，支持四种模式）。**`set_attrs` 默认禁止整段覆盖数组**（`patch` 含数组属性会直接阻断并要求显式 `overwriteArray:true`），因其大 payload 曾触发调用方 stringify bug 致 36 列丢失；且 `set_attrs` 只覆盖 view 树节点/controls，够不到 action 结构。
+> 数组元素级改动一律用 `patch_node_array_item`（view 树节点数组，如单列 `options`/`cols`，支持 merge/append/insert/remove）、`patch_view_array_item`（**view 级数组，弹窗 `subviews`**）或 `patch_action_array_item`（presenter.handlers/initial 的 action 内数组，如 `datarequest.setter` 绑定输出到控件、`param.properties`，支持四种模式）。**`set_attrs` 默认禁止整段覆盖数组**（`patch` 含数组属性会直接阻断并要求显式 `overwriteArray:true`），因其大 payload 曾触发调用方 stringify bug 致 36 列丢失；且 `set_attrs` 只覆盖 `view.body` 树、`view.subviews` 弹窗及内部控件、`controls`，够不到 action 结构。
+
+> **弹窗（popview）**：平台把弹窗放在 `view.subviews`（与 `view.body` **平级**的数组，元素 `type=popview`），弹窗内控件在弹窗节点的 `content` 下。**弹窗 code 不在 `viewTree` 里，只能从 `get_form_outline` 的 `subviews` 拿**。弹窗内加/删/移控件用 `insert_node`/`remove_node`/`move_node`，改属性用 `set_attrs`；弹窗**根节点**自身（没有父节点）的增/改/删用 `patch_view_array_item`（`arrayProp:"subviews"`，新建首次须 `createIfMissing:true`）。**删弹窗两条等价路径**（`remove_node{code}` / `patch_view_array_item{mode:"remove"}`）都默认校验 `popsubview` 的 `viewcode` 引用，报 `REF_VIOLATION` 时先 `remove_action` 解引用，确需强删传 `checkRefs:false`。红线：弹窗内控件 `code` 常被 `datarequest.setter` 引用，**勿改 code、勿删仍被引用的节点**。详见 `tools/form.md`「弹窗专章」。
 
 > **action 本身的增删改**不走上面两个数组 op（`patch_action_array_item` 只管 action **内部**的数组）：新增用 `add_action`（按 `type` 自动补平台空骨架，`initial` 仅允许 `flycode`/`receivelink`），改字段用 `patch_action`（浅合并任意字段，但**不能改 `type`/`code`**），删除用 `remove_action`（删空保留 `actions: []`）。定位一律用 `actionCode`，`actionIndex` 会随同批次增删漂移。详见 `tools/form.md`。
 
@@ -247,12 +249,13 @@ flycode-mcp 默认开启 `PROGRESSIVE_DISCLOSURE=on`：连接后客户端只看
 ## 六、关键避坑（高频雷区）
 
 - **🚫 禁止自写脚本调用平台（最高优先级）**：见「零、红线」。旧版用户记忆里可能残留「Python/Node 直连接口」「手写脚本模拟工具」的做法，**一律禁止**；所有读写只走官方 MCP 工具，找不到能力就如实告知用户，不绕过。
-- **不回传整份大 JSON**：已有普通逻辑/表单只用局部工具（`str_replace_flycode`/`patch_model_logic`/`patch_form`），`save_model_logic`/`save_form` 全量仅用于新建或极小 JSON；**当且仅当** JSON 过大无法内联且局部工具无法满足时，才可用「八、超大 JSON 全量保存的官方脚本」（真正的 MCP 客户端，非直接打 REST）。
+- **不回传整份大 JSON**：已有普通逻辑/表单只用局部工具（`str_replace_flycode`/`patch_model_logic`/`patch_form`），`save_model_logic`/`save_form` 全量仅用于新建或极小 JSON；**当且仅当** JSON 过大无法内联且局部工具无法满足时，才可用「八、超大 JSON 全量保存的官方脚本」（真正的 MCP 客户端，非直接打 REST）。⚠️ **含弹窗的表单尤其不能用 `save_form` 兜底**：它按提交内容整份覆盖，旧快照会把 `view.subviews`（弹窗及其 `eventlist`）一起抹掉（线上已发生过）；弹窗现已能用 `patch_form` 直接改。
 - **校验口径（2026-09-22 修正）**：`verify:false` / `VERIFY_FAILED` **视为真实未生效信号**（旧版「换行假阴性」已由 MCP 修复）。`applied:true`+`verified:false` 且报「新内容未出现」时，用 `get_form_fragment`/`get_model_logic` 实际回读确认，不要凭错误码重复提交；确需字节严格校验给 op 设 `matchMode:'exact'`。
 - **导出列专用 ops**：`patch_model_logic` 改导出列（`actioncategory=5`）用 5 类导出 op；**切勿用 `set_meta` 碰 `bindjson`**（会整体覆盖顶层字段、丢失导出列定义），改用 `set_bind_meta`。
 - **空串不是定位键**：自定义字段 `propertycode`/`objectcode` 恒为 `""`，传 `""` 安全且推荐（不会误判重复）；但 `remove_property`/`replace_property` 只传空串 `propertyCode` 而无 `propertyName` 会报 `INVALID_PARAMS`。
 - **表单 `initial` vs `handlers`**：页面初始类事件（如「页面初始-参数接收」）在 `presenter.initial[]`，**不在 `handlers[]`**；`patch_form` 的 `replace_script` / `add_action` / `patch_action` / `remove_action` / `patch_action_array_item` 都会在两块容器检索，`handlerCode` 同名跨容器须消歧 —— 参数名是 **`scope`**（`handlers`/`initial`），**也接受等价别名 `handlerScope`**（与 `get_form_fragment` 同名，任传其一；都传且取值不同报 `INVALID_PARAMS`）；`get_form_outline` 会一并列出并标 `scope='initial'`。
 - **动作（action）增删改的三条硬约束**：① **类型按容器分域**——`initial`（页面初始化）只允许 `flycode`/`receivelink`，其余 24 种只能加到 `handlers`，越界报 `TYPE_NOT_ALLOWED`；② **定位一律用 `actionCode`**，不用 `actionIndex`（同批次前序 op 增删会让下标漂移，回读校验会打到邻居身上）；③ `patch_action` 的 `patch` **不能含 `type`/`code`**（`type` 是字段骨架锚点、`code` 是定位键），换类型或改名一律 `remove_action` + `add_action`。另：数据提交是 `datasubmit`（不是 `datacommit`）；「数据字典绑定」不是独立 type，是 `datarequest` 的 `_type_spe:"dictbind"` 变体。
+- **弹窗（popview）三条硬约束**：① **code 只从 `get_form_outline().subviews` 拿**——弹窗不在 `viewTree` 里，用 `get_form` 全量翻找是浪费上下文；② 弹窗根节点（挂在 `view.subviews`、没有父节点）的增/改/删用 `patch_view_array_item`（`arrayProp:"subviews"`，首次新建须 `createIfMissing:true`），弹窗**内部**控件才用 `insert_node`/`remove_node`/`set_attrs`；③ **删弹窗前先解引用**——`popsubview`/`closesubview` 的 `viewcode` 仍指向它时报 `REF_VIOLATION`（先 `remove_action`，或 `checkRefs:false` 强删）；弹窗内控件 `code` 常被 `datarequest.setter` 引用，勿改 code、勿删被引用节点。
 - **新建逻辑用官方 ID（且勿带 prefix）**：`modellogiccode`/`modellogicstepcode` 必须调 `generate_unique_code` 获取，**调用时不要传 `prefix`**（返回纯 18 位纯数字 ID），不要自写脚本按 epoch 算（官方现 18 位、旧「19 位」约定已过期，硬编码会落到平台雪花方案外）。带字母前缀的 `code` 会被后端 `saveModelLogic` 判 `modellogiccode不能为空` 拒绝。新建逻辑顶层对象**不要带** `metamodelcode`/`confsource`。
 - **`run_sql` 只读**：仅 SELECT、一次一条；不支持 INSERT/UPDATE/DELETE。
 - **数据字典文本**：实体字典字段存 `dickey`（bigint，全局唯一），翻译一律 `LEFT JOIN pl_dictionary d ON d.dickey=k.<col>`，不必拼 `dictionarycode`；字典编码 >2^53 用字符串常量。

package/dist/skills/flycode-mcp-skill/tools/form.md

@@ -2,7 +2,7 @@
 
 > 属 **form** 域：使用前需 `mcp_activate('form')` 激活（连接后默认隐藏）。
 > 读写分工：前 5 个只读，`patch_form` 局部改、`save_form` 整页才用。
-> 推荐流程：`page_form_list` 拿 code → `get_form_outline` 看骨架 → `get_form_fragment` 看局部 → `patch_form` 改。**避免一上来 `get_form` 拉全量**（88KB 级）。
+> 推荐流程：`page_form_list` 拿 code → `get_form_outline` 看骨架（**弹窗 code 在 `subviews` 里**）→ `get_form_fragment` 看局部 → `patch_form` 改。**避免一上来 `get_form` 拉全量**（88KB 级）。
 
 ## 枚举速查
 
@@ -111,7 +111,7 @@
 
 ## `get_form_outline` — 查询表单骨架（只读，首选入口）
 
-获取表单轻量骨架（约 **2–4KB**）：pageinfo 关键字段、view 树骨架、presenter 处理器清单、businessmodel 逻辑名。用于拿全貌与所有可改对象 code，避免盲改。
+获取表单轻量骨架（**数 KB，随控件数量增长**：小页面 2–4KB，大页面实测 18.6KB / body 127 节点）：pageinfo 关键字段、view 树骨架（body）、**弹窗视图骨架（`subviews`）**、presenter 处理器清单、businessmodel 逻辑名。用于拿全貌与所有可改对象 code，避免盲改。
 
 ### 输入
 
@@ -124,7 +124,8 @@
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `code` / `title` / `type` / `status` / `clientcategorycode` / `marktype` / `versionnum` | string \| null | 页面基本信息（type 同 page_form_list） |
-| `viewTree` | array | view 树骨架（递归），每项 `{ code, type, title, children[] }` |
+| `viewTree` | array | view 树骨架（递归），每项 `{ code, type, title, children[] }`。⚠️ **只含 `view.body`，不含弹窗** |
+| `subviews` | array | **弹窗视图骨架**，与 `viewTree` 同构，每项一棵弹窗树（元素 `type=popview`）。⚠️ **弹窗及其内部控件的 code 只能从这里拿**——它们不在 `viewTree` 里；无弹窗时恒为 `[]` |
 | `handlers` | array | presenter 处理器清单，每项 `{ code, name, desc, key, condition, actionCount, actionTypes[], scope }`。⚠️ **`scope='handlers'` 为事件处理器 / `'initial'` 为页面初始化**（`replace_script` 寻址依据） |
 | `interfaces` | array | presenter 对外接口清单，每项 `{ code, key, desc, actionCount }` |
 | `businessModels` | array | businessmodel 引用的业务逻辑名清单，每项 `{ modelcode, modellogiccode, modellogicname, actiontype }`（仅名字不回内容） |
@@ -141,11 +142,11 @@
 | 参数 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `code` | string | 是 | 表单/页面唯一编码 |
-| `nodeCode` | string | 否 | 目标控件/节点编码，返回其完整子树 |
+| `nodeCode` | string | 否 | 目标控件/节点编码，返回其完整子树。**支持 `view.subviews` 里的弹窗节点及其内部控件**；未命中时不会静默返回空壳，`message` 会写明已检索范围 |
 | `itemCode` | string | 否 | 在 nodeCode 命中节点内部，按 code 深度优先钻取某个**数组元素**（如表格的某一列）并返回该元素；未找到时在 message 提示 |
 | `handlerCode` | string | 否 | 目标 presenter 处理器编码（**handlers 与 initial 均检索**），返回完整定义与 actionIndex 清单 |
 | `handlerScope` | string | 否 | `handlers` / `initial`——限定容器；默认两者都检索，同名跨容器时须指定以消歧 |
-| `section` | string | 否 | 返回整段：`pageinfo` / `view` / `presenter` / `controls` / `pageswitch` / `businessmodel` |
+| `section` | string | 否 | 返回整段：`pageinfo` / `view` / `presenter` / `controls` / `pageswitch` / `businessmodel` / `subviews`（只取弹窗数组） |
 
 ### 输出
 
@@ -157,44 +158,49 @@
 | `handler` | any | handlerCode 命中的处理器完整定义 |
 | `section` | any | section 命中的整段内容 |
 | `actionIndex` | array | handler 的 action 清单，每项 `{ index, code, type, scriptLen, conditionLen, expressionLen }`，便于精确构造 `replace_script` |
-| `message` | string \| null | 提示信息 |
+| `message` | string \| null | 提示信息。⚠️ **`node`/`handler` 为空且有 message = 未命中**（会写明已检索 view.body 树、view.subviews 弹窗 N 个、controls），不要当成「这表单是空的」 |
 
 ---
 
 ## `patch_form` — 局部补丁修改表单（写）
 
-以 delta ops 局部修改表单，无需回传完整 JSON。**14 类 ops**，事务性预演，失败整批回滚。改初始化脚本（presenter.initial）与改按钮事件用法一致。
+以 delta ops 局部修改表单，无需回传完整 JSON。**15 类 ops**，事务性预演，失败整批回滚。改初始化脚本（presenter.initial）与改按钮事件用法一致。
+
+> **弹窗（popview）也在管辖内**：平台把弹窗挂在 `view.subviews`（与 `view.body` 平级的数组）。弹窗内控件用 `set_attrs`/`insert_node`/`remove_node`/`move_node`/`patch_node_array_item` 直接改；弹窗**根节点**（没有父节点）的增/改/删用 `patch_view_array_item`。详见「弹窗（popview）专章」。
 
 ### 输入
 
 | 参数 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
 | `code` | string | 是 | 目标表单/页面唯一编码 |
-| `ops` | array | 是 | 补丁操作数组，至少 1 个；按顺序依次作用于上一步结果。14 类 op 见下 |
+| `ops` | array | 是 | 补丁操作数组，至少 1 个；按顺序依次作用于上一步结果。15 类 op 见下 |
 | `commitMessage` | object | 是 | 提交信息，整批 ops 共用一个 |
 | `dryRun` | boolean | 否 | 只预演并输出 diff、不落库，**默认 false** |
 | `verify` | boolean | 否 | 保存后回读校验，**默认 true** |
 
-### 14 类 op 一览
+### 15 类 op 一览
 
 | op | 定位 | 关键字段 | 说明 |
 | --- | --- | --- | --- |
 | `set_pageinfo` | — | `patch` | 浅合并 pageinfo（如 `{ "title": "新标题", "status": "1" }`） |
-| `set_attrs` | view 树节点/controls | `code`、`patch`、`overwriteArray?` | 按 code 定位节点**浅合并属性**。⚠️ 仅限 view 树节点与 controls 数组（action 结构改用 patch_action_array_item）。⚠️ **patch 含数组属性默认阻断**（ARRAY_OVERWRITE_BLOCKED，防误改丢列——曾致 36 列丢失）；确要整段覆盖须显式 `overwriteArray:true`，否则改用 patch_node_array_item / patch_action_array_item 做元素级增改删 |
-| `patch_node_array_item` | 节点内数组 | `nodeCode`、`arrayProp`（如 `cols`/`options`/`content`）、`mode`、其余见下 | view 树节点内**数组元素级**操作，四种模式 + 两级嵌套，详见下节 |
+| `set_attrs` | view 树节点（body + subviews 弹窗）、controls | `code`、`patch`、`overwriteArray?` | 按 code 定位节点**浅合并属性**。⚠️ 范围是 `view.body` 树、**`view.subviews` 里的弹窗及其内部控件**、`controls` 数组（action 结构改用 patch_action_array_item）。⚠️ **patch 含数组属性默认阻断**（ARRAY_OVERWRITE_BLOCKED，防误改丢列——曾致 36 列丢失）；确要整段覆盖须显式 `overwriteArray:true`，否则改用 patch_node_array_item / patch_action_array_item / patch_view_array_item 做元素级增改删 |
+| `patch_node_array_item` | 节点内数组 | `nodeCode`、`arrayProp`（如 `cols`/`options`/`content`/`eventlist`）、`mode`、其余见下 | 节点内**数组元素级**操作，四种模式 + 两级嵌套，详见下节。`nodeCode` 可为**弹窗节点或弹窗内控件**（弹窗 `eventlist` 与其内部节点的事件都用它追加） |
+| `patch_view_array_item` | **view 级数组**（`subviews`） | `arrayProp`（弹窗用 `"subviews"`）、`mode`、`itemKeyValue`、`item`/`patch`、`createIfMissing?`、`checkRefs?`、其余见下 | **弹窗根节点**的增/改/删：base 是整份 `view` 而非某个节点。append 新建弹窗（首次须 `createIfMissing:true`）、merge 改 title/needconfirm 等、remove 删弹窗（默认校验 `popsubview` 引用）。四模式 + 两级嵌套同下节 |
 | `patch_action_array_item` | handler action 内数组 | `handlerCode`、`arrayProp`（如 `setter`）、`mode`、其余见下 | presenter.handlers/initial 中某 **action 内部数组**（如 `datarequest.setter` 界面输出绑定到控件、`param.properties`），四种模式 + 两级嵌套 |
 | `add_action` | handler 的 `actions[]` | `handlerCode`、`scope?`、`type?`（默认 `flycode`）、`code?`、`desc?`、`condition?`、`position?`、`script?`、`fields?` | **追加一条动作**，按 type 自动补平台空骨架；`initial` 仅允许 `flycode`/`receivelink`；`code` 默认 `action_<handlerCode 末8位>`（同 handler 内重复自动加 `_2`/`_3`）。详见「动作的增/改/删」 |
 | `patch_action` | handler 的单条 action | `handlerCode`、`scope?`、`actionCode?`/`actionIndex?`、`patch` | **浅合并任意字段**（`desc`/`condition`/`message`/`url`/`logiccode`/`queue`…，`script` 仅 flycode 可写）。⚠️ 不能含 `type`/`code`（换类型或改名走 `remove_action` + `add_action`） |
 | `remove_action` | 同上 | 同上（无 `patch`） | **删除一条动作**；删空后保留 `actions: []`（不删属性，与平台形态一致） |
-| `insert_node` | view 树 | `parentCode`、`node`（新节点对象）、`position?`（默认末尾） | 插入新节点 |
-| `remove_node` | view 树 | `code`、`checkRefs?`（默认 true：存在事件/handler 引用时拒绝删除） | 删除节点 |
-| `move_node` | view 树 | `code`、`newParentCode`、`position?` | 移动节点到新父节点 |
+| `insert_node` | view 树（body + subviews） | `parentCode`、`node`（新节点对象）、`position?`（默认末尾） | 插入新节点。`parentCode` 可为**弹窗 code**（往弹窗 `content` 加控件） |
+| `remove_node` | view 树（body + subviews） | `code`、`checkRefs?`（默认 true：存在事件/handler 引用时拒绝删除） | 删除节点。`code` 可为**弹窗根节点**；`checkRefs` 也会拦「仍有 `popsubview`/`closesubview` 的 `viewcode` 指向该弹窗」。删掉最后一个弹窗后 `subviews` 属性被清掉（不留 `[]`） |
+| `move_node` | view 树（body + subviews） | `code`、`newParentCode`、`position?` | 移动节点到新父节点；body 与弹窗之间可互移 |
 | `set_section` | 整段 | `section`（`view`/`presenter`/`controls`/`pageswitch`）、`value` | 整段替换（大 payload，慎用） |
 | `replace_script` | handler 的脚本字段 | `handlerCode`、`actionIndex?`/`actionCode?`、`field?`（`script`(默认)/`condition`/`expression`）、`scope?`（`handlers`/`initial`）、`replacement?` 或 `ops[]` | 改 UI 脚本。`replacement` 整段替换优先于 `ops`；`ops[]` 每项 `{ oldString(唯一命中), newString(空串=删除), replaceAll?, occurrence?, matchMode?, label? }`。⚠️ handlerCode 同名跨容器须加 `scope`（或等价别名 `handlerScope`）消歧 |
 | `add_businessmodel` | — | `modellogiccode`、`overwrite?` | **MCP 自动拉取该逻辑完整 JSON** 追加到 businessmodel（无需传大段逻辑 JSON）；已存在时默认跳过，`overwrite:true` 覆盖 |
 | `remove_businessmodel` | — | `modellogiccode`、`checkRefs?`（默认 true） | 移除引用 |
 
-### 数组元素级操作详解（patch_node_array_item / patch_action_array_item 共用语义）
+### 数组元素级操作详解（patch_node_array_item / patch_view_array_item / patch_action_array_item 共用语义）
+
+> 三者字段语义一致，差别只在 **base（基准容器）**：`patch_node_array_item` 的 base 是 `view` 树里的某个节点（`nodeCode` 定位）；`patch_view_array_item` 的 base 是**整份 `view`**（没有 `nodeCode`，弹窗用 `arrayProp:"subviews"`）；`patch_action_array_item` 的 base 是某 handler 的某 action（`handlerCode` → `actionCode` → `parentProp`）。
 
 | 字段 | 必填 | 说明 |
 | --- | --- | --- |
@@ -204,14 +210,15 @@
 | `item` / `position` / `patch` | 条件 | append/insert 的新元素 / 插入下标 / merge 的浅合并属性 |
 | `elementArrayProp` | 否 | **【两级嵌套】**目标在「数组内某元素的嵌套数组」时填子数组名（如 `setter[0].properties` 的 `properties`）；必须配合 itemKey/itemKeyValue 先定位外层元素 |
 | `elementItemKey` / `elementItemKeyValue` | 否 | 两级模式下定位嵌套数组内子元素的键/键值（merge/remove 用） |
-| `createIfMissing` | 否 | append/insert 时目标数组（含两级嵌套目标）不存在是否自动新建，**默认 false——fail-closed 报 ARRAY_NOT_FOUND**（防误造平行 orphan 结构，如错层 `datarequest.setter`）；确需新建才显式置 true |
+| `createIfMissing` | 否 | append/insert 时目标数组（含两级嵌套目标）不存在是否自动新建，**默认 false——fail-closed 报 ARRAY_NOT_FOUND**（防误造平行 orphan 结构，如错层 `datarequest.setter`）；确需新建才显式置 true。⚠️ 表单**首次加弹窗**时 `view.subviews` 通常不存在，必须置 true |
+| `checkRefs` | 否 | **仅 `patch_view_array_item`**：`mode:"remove"` 删**顶层弹窗**时是否校验引用（`popsubview`/`closesubview` 的 `viewcode`），默认 true → 仍被打开动作指向时报 `REF_VIOLATION`；确需强删置 false。删弹窗内嵌套元素时不生效 |
 
 ### 输出
 
 | 字段 | 类型 | 说明 |
 | --- | --- | --- |
 | `ok` / `applied` / `verified` / `message` | — | 同 patch_model_logic 口径 |
-| `errorCode` | string | `OK` / `DRY_RUN` / `EMPTY_OPS` / `FETCH_FAILED` / `NODE_NOT_FOUND` / `DUP_CODE` / `REF_VIOLATION` / `OPS_FAILED` / `SAVE_FAILED` / `VERIFY_FAILED` / `ARRAY_OVERWRITE_BLOCKED` / `ARRAY_NOT_FOUND` / `TYPE_NOT_ALLOWED` / `NO_TARGET` / `INVALID_PARAMS` |
+| `errorCode` | string | `OK` / `DRY_RUN` / `EMPTY_OPS` / `FETCH_FAILED` / `NODE_NOT_FOUND` / `DUP_CODE` / `REF_VIOLATION` / `OPS_FAILED` / `SAVE_FAILED` / `VERIFY_FAILED` / `ARRAY_OVERWRITE_BLOCKED` / `ARRAY_NOT_FOUND` / `TYPE_NOT_ALLOWED` / `NO_TARGET` / `INVALID_PARAMS`。⚠️ `REF_VIOLATION` 也覆盖「弹窗仍被 `popsubview`/`closesubview` 的 `viewcode` 指向」——先 `remove_action` 解引用或传 `checkRefs:false` |
 | `diff` | string | 全部 op 的 diff 片段（超长截断；只回改动摘要不回整份表单） |
 | `ops` | array | 每个 op 的结果：`{ index, op, status, errorCode, message, hunk?(replace_script 才有), suggestions?(NOT_FOUND 时的相似候选 [{startLine, score, preview}]) }` |
 
@@ -271,6 +278,56 @@
 
 误把嵌套数组当顶层 append 会被 `ARRAY_NOT_FOUND` 阻断（默认 fail-closed，不会污染表单）；remove 删后数组变空会自动删除该数组属性，不留 `{"properties":[]}` 空壳。
 
+### 弹窗（popview）专章：读、改、加、删
+
+**结构**：弹窗挂在 `view.subviews`——一个与 `view.body` **平级的数组**（不是某个节点的 `content`）；每项是弹窗根节点，`type: "popview"`，弹窗内控件挂在它的 `content` 下。实测（采购订单-V6.0-详情，4 个弹窗）弹窗根节点**恰好 9 个字段**：
+
+```
+{ "type":"popview", "code":"…", "title":"货补", "flexdirection":"vertical",
+  "needconfirm":"1", "confirmtitle":"确定", "resetwhenopen":"1",
+  "content":[...], "eventlist":[{ "trigger":"onopen", "handler":"…" }] }
+```
+
+⚠️ **没有 `showclosebutton`**（设计器里那条是可选字段，别硬编进模板）；弹窗事件 `trigger` 只有 **`onopen` / `onconfirm`**（不是 `onclicked`）。
+
+**先拿到弹窗 code**：`get_form_outline` 的 `subviews`（`viewTree` 里没有弹窗）；要看整段弹窗源码用 `get_form_fragment({ section:"subviews" })`，要看单个弹窗用 `get_form_fragment({ nodeCode: 弹窗code })`。
+
+| 想做的事 | 用哪个 op |
+| --- | --- |
+| 改弹窗属性（`title` / `needconfirm` / `confirmtitle` / `resetwhenopen` / `flexdirection`） | `set_attrs{code:弹窗code, patch:{…}}`，或 `patch_view_array_item{mode:"merge", itemKeyValue:弹窗code, patch:{…}}` |
+| 弹窗**内**加控件 | `insert_node{parentCode: 弹窗code, node:{…}}` |
+| 弹窗**内**删控件 / 移动控件 | `remove_node{code}` / `move_node{code, newParentCode}` |
+| 给弹窗自身或弹窗内控件加事件 | `patch_node_array_item{nodeCode:弹窗code或控件code, arrayProp:"eventlist", mode:"append", item:{trigger:"onopen", handler:"…"}}` |
+| 弹窗内表格的列 / 下拉选项 | `patch_node_array_item{nodeCode:弹窗内节点code, arrayProp:"cols"/"options", …}` |
+| **新建弹窗** | `patch_view_array_item{arrayProp:"subviews", mode:"append", createIfMissing:true, item:{…完整 popview 节点…}}` |
+| **删除弹窗** | 见下（两条等价路径） |
+| 打开弹窗（按钮事件） | `add_action{handlerCode, type:"popsubview", fields:{"viewcode":弹窗code, "viewwidth":"1020", "viewheight":"580", "viewtitle":"", "popupmode":"center"}}`——模板已内置，无需手写骨架 |
+
+**新建弹窗示例**（首次加弹窗时 `view.subviews` 不存在，必须 `createIfMissing:true`，否则报 `ARRAY_NOT_FOUND`）：
+
+```jsonc
+{ "op": "patch_view_array_item", "arrayProp": "subviews", "mode": "append", "createIfMissing": true,
+  "item": { "type": "popview", "code": "生成的新code", "title": "货补", "flexdirection": "vertical",
+            "needconfirm": "1", "confirmtitle": "确定", "resetwhenopen": "1",
+            "content": [], "eventlist": [] } }
+```
+
+**删除弹窗（两条等价路径，都默认校验引用）**：
+
+```jsonc
+// A. 通用节点删除（弹窗根也支持）
+{ "op": "remove_node", "code": "1501119668772016226" }
+// B. view 数组级删除
+{ "op": "patch_view_array_item", "arrayProp": "subviews", "mode": "remove", "itemKeyValue": "1501119668772016226" }
+// 强删（跳过引用校验）
+{ "op": "remove_node", "code": "…", "checkRefs": false }
+```
+
+- 弹窗常被 `popsubview` / `closesubview` 动作的 `viewcode` 指向 → 直接删会报 **`REF_VIOLATION`**。正确顺序：先 `remove_action` 掉指向它的打开动作，再删；确需保留动作悬空才用 `checkRefs:false`。
+- 删掉**最后一个**弹窗后 `subviews` 属性会被清掉（回读为 `undefined`，不留 `[]` 空壳）。
+
+**红线**：弹窗内控件的 `code` 常被 `datarequest.setter` 等绑定引用（线上单表单实测 48 处）——**不要改弹窗内控件的 code、不要删仍被引用的节点**；patch 前先 `get_form_fragment({nodeCode})` 核对真实属性名与引用关系。
+
 ---
 
 ## `save_form` — 全量保存表单（写，整页重构才用）
@@ -296,3 +353,4 @@
 
 - **禁止对已有大表单整份回传**：极易超长截断、误改不相关字段；当且仅当 JSON 过大无法内联且局部工具无法满足时，才可用 SKILL.md「八、超大 JSON 全量保存的官方脚本」（真·MCP 客户端，非直连 REST）。
 - 全量保存会覆盖整个表单：回传前确认来源是最新的 `get_form` 结果，且改动点都已应用。
+- **含弹窗的表单不要用 `save_form` 兜底**：它按提交内容整份覆盖，用改动前的旧快照保存会把 `view.subviews`（弹窗及其 `eventlist`）一起抹掉——线上「布局测试」就因此丢过弹窗。弹窗现已能用 `patch_form` 直接改（见上节），没有理由再走全量。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flycode-mcp",
-  "version": "1.14.7",
+  "version": "1.14.8",
   "private": false,
   "type": "module",
   "main": "dist/flycode-mcp.min.js",