flycode-mcp 1.14.2 → 1.14.4

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

@@ -0,0 +1,255 @@
+# 实体（数据表）工具手册：entity 域（5 个工具）
+
+> 属 **entity** 域：使用前需 `mcp_activate('entity')` 激活（连接后默认隐藏）。
+> 读写分工：`page_entity_list` / `get_entity` / `page_entity_directories` 只读；`create_entity` 只管**整张新建**；`patch_entity` 只管**加字段**。改/删字段未实现 → 传入即失败并提示用户到 IDE 平台手动操作。
+
+## 枚举速查
+
+- `datapattern`（实体类型）：1-原生 / 2-衍生 / 3-视图 / 4-超级表单
+- `objecttypecode`（实体分类）：1-基本 / 2-树形 / 3-数据字典 / 4-关联
+- `objectcatgory`：1-权限对象 / 2-否
+- `publishstatus`：1-已发布 / 2-未发布（⚠️ 实体级返回 **number**；`properties` 字段级返回 **string** 如 `"2"`，勿混用类型）
+- `hasoffline`：1-有 / 0-无
+- `marktype`（创建标记）：0-平台 / 1-产品 / 2-租户
+- `confsource`：1-IDE 配置 / 2-用户级配置
+- `properties[].idxtype`（索引方式）：1-无 / 2-主键索引
+
+## commitMessage 通用结构（两个写工具共用）
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `committype` | enum | 是 | `saverecord` / `feature` / `fix` / `stylefix` / `refactor` / `testfix` |
+| `committypetext` | enum | 是 | 与 committype **一一对应**：`保存记录` / `新功能添加` / `bug修改` / `样式修改` / `重构` / `测试` |
+| `msgbody` | string | 条件 | `committype=saverecord` 时忽略（服务端自动填当前时间，格式 yyyy-MM-dd hh:mm）；其余类型必填，按 git 提交规范写 |
+
+缺省时 MCP 组装默认值（`committype=saverecord`）。
+
+---
+
+## `page_entity_list` — 分页查询实体（只读）
+
+分页查询实体列表，支持按名称/类型筛选。`objectname` 会同时模糊匹配**实体中文名、实体表名、objectcode**。
+
+### 输入（全部可选，按字符串传）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectname` | string | 否 | 实体中文名、表名、objectcode 模糊匹配 |
+| `page` | string | 否 | 当前页，从 1 开始（默认 1） |
+| `rows` | string | 否 | 每页记录数（默认 20） |
+| `updatetimestart` | string | 否 | 修改开始时间，`yyyy-MM-dd hh:mm:ss`，与结束时间成对出现 |
+| `updatetimeend` | string | 否 | 修改结束时间，与开始时间成对出现 |
+| `datapattern` | string | 否 | 实体类型：1-原生 / 2-衍生 / 3-视图 / 4-超级表单 |
+| `objecttypecode` | string | 否 | 实体分类：1-基本 / 2-树形 / 3-数据字典 / 4-关联 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | array | 这一页的实体数据（每项字段见下；未声明字段原样透传） |
+| `pageCount` / `pageIndex` / `pageSize` / `resultCount` | number | 总页数 / 第几页 / 每页记录数 / 总记录数 |
+
+`data[]` 每项关键字段（除特殊说明外均为可选且可空，number/string 兼容返回）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `objectcode` | 实体编码，与 metamodelcode 构成复合主键（`get_entity` 入参） |
+| `objectname` / `objectdescr` | 实体中文名 / 描述 |
+| `objectmark` | 实体标记，一般与数据库表名同名（字典类型有自己的标记） |
+| `tablename` | 数据库表名 |
+| `metamodelcode` | 领域模型编码 |
+| `objecttypecode` | 实体分类：1-基本 / 2-树形 / 3-数据字典 / 4-关联 |
+| `datapattern` | 数据模式：1-原生 / 2-衍生 / 3-视图 / 4-超级表单 |
+| `publishstatus` | 发布状态：1-已发布 / 2-未发布 |
+| `status` | 状态：1-启用 / 2-停用 |
+| `directorytypecode` / `directorytypename` | 所属目录编码 / 名称 |
+| `parentobjectcode` | 父实体 objectcode |
+| `objecttemplatecode` | 实体模板编码 |
+| `hasoffline` | 是否有离线设置：1-有 / 0-无 |
+| `objectcatgory` | 是否权限设置对象：1-是 / 2-否 |
+| `marktype` / `confsource` | 创建标记 / 配置来源 |
+| `createtime` / `updatetime` / `createaccountname` / `updateaccountname` 等 | 审计字段 |
+
+---
+
+## `get_entity` — 查询实体详情（只读）
+
+按 `objectcode` 查询实体详情：基本信息与属性数组 `properties`。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectcode` | string | 是 | 实体编码（数字码，来自 `page_entity_list`） |
+
+### 输出（宽松对象，除 `objectcode` 必有外其余可选且可空）
+
+| 字段 | 说明 |
+| --- | --- |
+| `objectcode` | 实体编码（复合主键之一） |
+| `objectname` / `objectdescr` / `objectmark` / `tablename` | 中文名 / 描述 / 标记 / 表名 |
+| `objecttypecode` | 分类：1-基本 / 2-树形 / 3-数据字典 / 4-关联（数据字典以 number 返回） |
+| `datapattern` | 数据模式。⚠️ **详情接口多数实体类型不返回该字段**（它是列表接口字段） |
+| `status` | 状态。⚠️ **详情接口对该字段返回不稳定**（部分调用不返回） |
+| `publishstatus` | 发布状态：1-已发布 / 2-未发布（number） |
+| `properties` | 属性数组，每个属性定义一个字段，结构见下 |
+| `directorytypecode` / `parentobjectcode` / `objecttemplatecode` | 目录编码 / 父实体 / 模板编码 |
+| `diclayer` | 字典层级（原生/关联/数据字典以 string 返回，视图/超级表单以 number 返回） |
+| `storagelevel` / `seq` / `script` / `message` / `confsource` / `marktype` 等 | 其余字段按类型缺省（视图/字典/超级表单各有缺省差异） |
+
+`properties[]` 每项（均可选且可空，未声明字段透传）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `propertycode` | 属性编码，唯一标识一个属性（⚠️ 自定义字段恒为空串 `""`，**空串不是有效定位键**） |
+| `propertyname` / `propertydescr` | 属性中文名 / 描述 |
+| `columnname` | 数据库字段名（列名） |
+| `propertytypecode` | 字段类型编码，完整枚举：1-主键(int8) / 2-名称(200) / 3-文本(200) / 4-长文本 / 5-整数(int4) / 6-长整数(int8) / 10-数字(numeric) / 7-日期时间(ts) / 29-年月日(date) / 30-时间范围 / 18-状态(int4) / 16-图片 / 26-附件 / 17-定位 / 19-选项集 / 8-创建人 / 9-修改人 / 11-创建时间 / 12-修改时间 / 31-拼音 / 100-是否默认 / 13-手机号 / 15-固定电话 / 14-邮箱 / 27-邮编 / 20-排序 / 200000000000-关联对象 / 100000000000-业务对象 / 10000000000-字典对象 / 300000000000-复杂关联对象 / 1000000000-本对象 |
+| `idxtype` | 索引方式：1-无 / 2-主键索引（数据字典/超级表单以 number 返回） |
+| `relationobjectcode` | 关联的实体编码（有关联时 SQL 可用此字段连对方表主键） |
+| `relationpropertycode` | 保留字段，一般空串（视图/数据字典/超级表单缺省） |
+| `publishstatus` / `status` | 字段级发布状态 / 状态（string 或 number 兼容） |
+| `marktype` / `propertycategorycode` / `ismaster` / `seq` | 标记 / 类别 / 保留 / 序号（seq 仅视图/字典/超级表单返回） |
+| `columnnameError` / `candelete` | 仅视图实体：列名是否错误 / 是否可删 |
+| `parentpropertycode` / `defaultvalue` | 仅数据字典：父属性编码 / 默认值 |
+
+---
+
+## `page_entity_directories` — 查询实体所属目录（只读）
+
+查询实体所属目录。取回的 `directorytypecode` 即**实体 `directorytypecode` 的取值来源**，也是 `create_entity` 的必填入参。
+
+**⚠️ 接口不支持分页、全量数百条，本工具已强制收敛：**
+- 默认最多回 **30** 条，硬上限 **200** 条；
+- 未传任何筛选条件时**只回顶级目录**（通常十余条量级）并在 `hint` 说明；
+- 命中过多时 `truncated=true`，请缩小 `keys` 或用 `offset` 翻页。**切勿指望裸调拉全量。**
+
+### 输入（全部可选）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `keys` | string | 否 | **强烈建议优先用**：目录名称模糊匹配，命中 directorytypename / directoryname / centername / directorytypecode |
+| `directorytypecode` | string | 否 | 目录编码精确匹配（已知编码反查名称时用） |
+| `parentdirectorytypecode` | string | 否 | 父目录编码精确匹配；传 `"root"` 表示只要顶级目录；传具体编码取其直接子目录 |
+| `centername` | string | 否 | 所属业务中心名称模糊匹配，如「客访管理」「营销费控」 |
+| `centercode` | string | 否 | 所属业务中心编码精确匹配 |
+| `marktype` | string | 否 | 创建标记精确匹配：0-平台 / 1-产品 / 2-租户 |
+| `limit` | string | 否 | 返回条数上限，默认 30，硬上限 200 |
+| `offset` | string | 否 | 起始偏移，默认 0；配合 limit 翻页 |
+| `directorycategory` | string | 否 | 目录类别：1-实体目录（默认 `"1"`）/ 3-表单页面目录 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `sourceTotal` | number | 接口返回的目录总数（筛选前，体现全量规模） |
+| `total` | number | 按筛选条件命中的条数（截断前） |
+| `returned` | number | 本次实际返回条数 |
+| `offset` / `limit` | number | 本次起始偏移 / 生效上限 |
+| `truncated` | boolean | true 表示命中数大于本次返回，还有后续 |
+| `hint` | string \| null | 收敛/翻页提示；null 表示无需提示 |
+| `items` | array | 目录项（已裁剪，仅保留定位所需字段），每项见下 |
+
+`items[]` 每项：
+
+| 字段 | 说明 |
+| --- | --- |
+| `directorytypecode` | 目录编码（即实体 directorytypecode 的取值，`create_entity` 必填入参） |
+| `directorytypename` | 目录名称（业务中心下的目录带后缀，如「制定计划(客访管理)」） |
+| `directoryname` | 目录本名，仅在与 directorytypename 不同时返回 |
+| `parentdirectorytypecode` | 父目录编码；缺失即顶级目录 |
+| `centername` | 所属业务中心名称，仅业务中心下的目录返回 |
+| `marktype` | 创建标记：0-平台 / 1-产品 / 2-租户 |
+
+---
+
+## `create_entity` — 新增实体（写）
+
+新增一个实体（数据表）。只传必要参数，完整实体对象由 MCP 侧组装后调平台保存接口 `/bizserv/biz/saveObject`。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectname` | string | 是 | 实体中文名 |
+| `objecttypecode` | string | 是 | 实体分类：1-基本对象 / 2-树型对象 / 3-数据字典 / 4-关联对象 |
+| `tablename` | string | 是 | 数据库表名；`objectmark` 自动复制此值 |
+| `directorytypecode` | string | 是 | 所属目录编码，取自 `page_entity_directories` 查到的 directorytypecode |
+| `parentobjectcode` | string | 否 | 父实体编码（树型/关联实体使用） |
+| `propertydescr` | string | 否 | 实体描述 |
+| `initialFields` | array | 否 | 可选初始字段，每项见下表；**数据字典忽略此参数**（字段由平台预置）。非字典实体未提供主键(propertytypecode=1)时 MCP 自动补「主键/id」 |
+| `commitMessage` | object | 否 | 提交信息（见本文件顶部通用结构），缺省 committype=saverecord |
+| `confirm` | boolean | 否 | 是否确认落库，**默认 false**。必须显式 true 才会真正保存 |
+| `dryRun` | boolean | 否 | 是否仅预览不落库，**默认 true**。置 false 才执行保存（需配合 confirm=true） |
+| `verify` | boolean | 否 | 保存后是否回读校验，默认 true |
+
+`initialFields[]` 每项：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `propertyname` | 是 | 属性中文名 |
+| `propertytypecode` | 是 | 属性类型编码（枚举见 `get_entity` 的 properties 表；如 1-主键(int8)、3-文本(200)、5-整数(int4)） |
+| `columnname` | 是 | 数据库字段名（列名） |
+| `propertydescr` | 否 | 属性描述 |
+| `idxtype` | 否 | 索引方式：1-无 / 2-主键索引。缺省 1（主键字段传 2） |
+| `relationobjectcode` | 否 | 关联类型时必填的关联实体编码 |
+| `relationpropertycode` | 否 | 关联属性编码，关联类型时可选 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `ok` | boolean | 整体是否成功（dryRun 成功也为 true，但 applied=false） |
+| `applied` | boolean | 是否已落库；dryRun 时为 false |
+| `verified` | boolean \| null | 保存后回读校验：true 全部生效 / false 存在异常 / null 未落库或未开启校验 |
+| `errorCode` | string | `OK` / `DRY_RUN` / `INVALID_PARAMS` / `SAVE_FAILED` / `VERIFY_FAILED` |
+| `message` | string | 结果说明；含 publishstatus 与「请手动发布」提示 |
+| `publishStatus` | number | 实体级发布状态：非字典实体 2（未发布）、数据字典 1（已发布） |
+| `needManualPublish` | boolean | 是否需用户到平台手动发布（非字典实体为 true） |
+| `entityCode` / `entityName` | string | 新建实体编码 / 中文名 |
+| `diff` | string | 将要创建的实体摘要（字段列表），超长会截断 |
+
+### 双闸与发布约定（必读）
+
+- **双闸 fail-closed**：默认 `confirm:false` + `dryRun:true`——默认**不落库只预览**。真正保存必须显式 `confirm:true` **且** `dryRun:false`，任一不满足都不写库。流程：先 `dryRun:true` 看 diff → 向用户确认 → `confirm:true, dryRun:false`。
+- **未发布态**：保存后实体 `publishstatus=2`（仅更新元数据、**未发布到数据库**），需用户**手动去平台点「发布」**才真正建表生效；数据字典为 1。AI 不可替用户发布。保存后建议 `get_entity` 回读核对。
+- **数据字典特殊约束**（`objecttypecode=3`）：只能整张新建（`properties=[]`、`publishstatus=1`），忽略 `initialFields`；任何字段级修改见 `patch_entity` 的限制。
+
+---
+
+## `patch_entity` — 已有实体新增字段（写）
+
+对已有实体做字段级修改。**当前仅实现 `add_field`**；`modify_field` / `delete_field` 为保留 op，传入直接失败并提示「修改/删除字段请让用户到 IDE 平台手动操作」。数据字典（objecttypecode=3）不允许任何字段增改删，传入 `add_field` 会失败并提示「数据字典不允许调整字段」。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectcode` | string | 是 | 目标实体的编码 |
+| `ops` | array | 是 | 字段操作数组，至少 1 个元素；按顺序**事务性**执行，任一失败整批回滚。op 结构见下 |
+| `commitMessage` | object | 否 | 提交信息，整批 ops 共用一个（见顶部通用结构） |
+| `confirm` | boolean | 否 | 是否确认落库，默认 false（双闸同 `create_entity`） |
+| `dryRun` | boolean | 否 | 是否仅预览，默认 true（双闸同 `create_entity`） |
+| `verify` | boolean | 否 | 保存后是否回读校验，默认 true |
+
+`ops[]` 的 op 类型（discriminatedUnion，按 `op` 字段区分）：
+
+| op | 必填字段 | 可选字段 | 状态 |
+| --- | --- | --- | --- |
+| `add_field` | `propertyname`（中文名）、`propertytypecode`（类型编码）、`columnname`（数据库字段名） | `propertydescr`、`idxtype`（缺省 1，主键传 2）、`relationobjectcode`、`relationpropertycode` | ✅ 已实现 |
+| `modify_field` | `propertycode`、`patch`（要合并的属性） | — | ❌ 保留未实现，传入即失败 |
+| `delete_field` | `propertycode` | — | ❌ 保留未实现，传入即失败 |
+
+### 输出
+
+在 `create_entity` 输出基础上增加 `ops` 明细（`errorCode` 取值扩展为：`OK` / `DRY_RUN` / `FETCH_FAILED` / `ENTITY_NOT_FOUND` / `FIELD_OP_UNSUPPORTED` / `DICTIONARY_NO_FIELD_OPS` / `INVALID_PARAMS` / `DUP_PROP_CODE` / `OPS_FAILED` / `SAVE_FAILED` / `VERIFY_FAILED`）：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `ops` | array | 每个 op 的执行结果，与入参一一对应：`{ index, op, status(OK/FAILED), errorCode, message }` |
+
+### 注意
+
+- 视图 / 超级表单实体的新属性 `seq` 传 `null`（由平台处理）。
+- 字段级 `publishstatus` 由 MCP 组装时补 `"2"`（string），调用方不用管。
+- 保存后同样处于未发布态（`publishstatus=2`），需用户手动到平台发布；建议 `get_entity` 回读核对。

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

@@ -0,0 +1,248 @@
+# 表单/页面工具手册：form 域（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 级）。
+
+## 枚举速查
+
+- `type`（页面类型）：5-列表查询 / 1-普通页面 / 99-二开 / 10-switchpage / 11-树导航列表 / 100-原生 / 101-空白 / 7-报表 / 12-排序 / 300-步骤管理 / 1000-全局函数
+- `clientcategorycode`（用户端）：1-web / 2-app / 6-小程序
+- `status`：1-启用 / 2-停用；`marktype`：0-平台 / 1-产品 / 2-租户；`confsource`：1-IDE / 2-用户级
+
+## commitMessage 通用结构（两个写工具共用）
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `committype` | enum | 是 | `saverecord` / `feature` / `fix` / `stylefix` / `refactor` / `testfix` |
+| `committypetext` | enum | 是 | 与 committype **一一对应**：`保存记录` / `新功能添加` / `bug修改` / `样式修改` / `重构` / `测试` |
+| `msgbody` | string | 条件 | `saverecord` 时忽略（服务端自动填当前时间）；其余类型必填 |
+
+---
+
+## `page_form_directories` — 查询表单所属目录（只读）
+
+查询表单/页面所属目录。取回的 `directorytypecode` 即表单 `pageinfo.directorytypecode` 的取值来源。
+
+**⚠️ 接口不支持分页、全量数百条（实测 352 条/74KB），本工具已强制收敛：**
+- 默认最多回 **30** 条，硬上限 **200** 条；
+- 未传筛选条件时**只回顶级目录**（通常十条量级）并在 `hint` 说明；
+- 命中过多时 `truncated=true`，缩小 `keys` 或用 `offset` 翻页。
+
+### 输入（全部可选）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `keys` | string | 否 | **强烈建议优先用**：目录名模糊匹配，命中 directorytypename / directoryname / centername / directorytypecode |
+| `directorytypecode` | string | 否 | 目录编码精确匹配 |
+| `parentdirectorytypecode` | string | 否 | 传 `"root"` 只要顶级目录；传具体编码取直接子目录 |
+| `centername` / `centercode` | string | 否 | 业务中心名称模糊匹配 / 编码精确匹配 |
+| `marktype` | string | 否 | 0-平台 / 1-产品 / 2-租户 |
+| `limit` / `offset` | string | 否 | 上限（默认 30、硬上限 200）/ 起始偏移 |
+| `directorycategory` | string | 否 | 目录类别：3-表单/页面目录（默认 `"3"`） |
+
+### 输出
+
+结构与 `page_entity_directories` 完全一致（`sourceTotal` / `total` / `returned` / `offset` / `limit` / `truncated` / `hint` / `items[]`），`items[].directorytypecode` 即表单 `pageinfo.directorytypecode` 的取值。详见 `tools/entity.md`。
+
+---
+
+## `page_form_list` — 分页查询表单/页面（只读）
+
+### 输入（全部可选，按字符串传）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `keys` | string | 否 | 模糊匹配表单 code / title |
+| `keywords` | string | 否 | 模糊匹配表单中的关键词 |
+| `status` | string | 否 | 1-启用 / 2-停用，示例传 `"1"` |
+| `type` | string | 否 | 页面类型（见顶部枚举） |
+| `clientcategorycode` | string | 否 | 1-web / 2-app / 6-小程序 |
+| `updateopname` | string | 否 | 最近修改人姓名 |
+| `updatetimestart` / `updatetimeend` | string | 否 | 修改时间区间，`yyyy-MM-dd hh:mm:ss`，成对出现 |
+| `page` / `rows` | string | 否 | 分页（默认 1 / 20） |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | array | 这一页的表单数据（每项见下） |
+| `pageCount` / `pageIndex` / `pageSize` / `resultCount` | number | 分页信封 |
+
+`data[]` 每项（除 `code` 外均可选且可空）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `code` | 表单/页面唯一编码（**必返**，后续所有表单工具的入参） |
+| `title` / `pagedescr` / `pagetypename` | 标题 / 页面描述 / 页面类型名称 |
+| `type` | 页面类型（整数，见顶部枚举） |
+| `status` / `marktype` / `confsource` | 状态 / 创建标记 / 配置来源 |
+| `clientcategorycode` | 用户端分类：1-web / 2-app / 6-小程序 |
+| `directorytypecode` / `directorytypename` | 所属目录编码 / 名称 |
+| `metamodelcode` / `pagetemplatecode` / `versionnum` / `ref` | 领域模型编码 / 页面模板编码 / 版本号 / 外部引用（一般空串） |
+| `createtime` / `updatetime` / `createaccountname` / `updateaccountname` 等 | 审计字段 |
+
+---
+
+## `get_form` — 查询表单完整详情（只读，非必要不用）
+
+按 `code` 获取表单完整详情，**88KB 级**、结构嵌套较深。建议先 `get_form_outline` 看骨架、`get_form_fragment` 取局部，再用 `patch_form` 改。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `code` | string | 是 | 表单/页面唯一编码 |
+
+### 输出（FormResult，宽松对象；子对象以平台原始 JSON 为准）
+
+| 字段 | 说明 |
+| --- | --- |
+| `pageinfo` | **核心对象 1**：页面基础信息 |
+| `presenter` | **核心对象 2**：事件定义。含两块容器——`handlers[]`（事件处理器）与 `initial[]`（页面初始化，如「页面初始-参数接收」**在这里不在 handlers**）；每个处理器下有 `actions[]` |
+| `view` | **核心对象 3**：页面结构控件树（节点含 type/code/title/content/children 及控件属性） |
+| `businessmodel` | 页面引用的后端业务模型（接口）列表，结构同 LogicResult |
+| `actionlogic` | 动作逻辑（仅部分页面，非核心） |
+| `controls` | 控件（仅部分页面，非核心） |
+| `pageswitch` | 仅 switchpage 类型：描述包含哪些页面 |
+| `renderinfo` / `message` | IDE 渲染标记 / 提交信息 |
+
+---
+
+## `get_form_outline` — 查询表单骨架（只读，首选入口）
+
+获取表单轻量骨架（约 **2–4KB**）：pageinfo 关键字段、view 树骨架、presenter 处理器清单、businessmodel 逻辑名。用于拿全貌与所有可改对象 code，避免盲改。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `code` | string | 是 | 表单/页面唯一编码 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `code` / `title` / `type` / `status` / `clientcategorycode` / `marktype` / `versionnum` | string \| null | 页面基本信息（type 同 page_form_list） |
+| `viewTree` | array | view 树骨架（递归），每项 `{ code, type, title, children[] }` |
+| `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 }`（仅名字不回内容） |
+| `message` | string \| null | 提交信息 |
+
+---
+
+## `get_form_fragment` — 查询表单局部内容（只读）
+
+按 code 取表单局部内容（**几 KB**）。四种取法（可组合）：`nodeCode` 节点子树、`itemCode` 钻取数组元素、`handlerCode` 处理器完整定义、`section` 整段。配合 `patch_form` 使用。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `code` | string | 是 | 表单/页面唯一编码 |
+| `nodeCode` | string | 否 | 目标控件/节点编码，返回其完整子树 |
+| `itemCode` | string | 否 | 在 nodeCode 命中节点内部，按 code 深度优先钻取某个**数组元素**（如表格的某一列）并返回该元素；未找到时在 message 提示 |
+| `handlerCode` | string | 否 | 目标 presenter 处理器编码（**handlers 与 initial 均检索**），返回完整定义与 actionIndex 清单 |
+| `handlerScope` | string | 否 | `handlers` / `initial`——限定容器；默认两者都检索，同名跨容器时须指定以消歧 |
+| `section` | string | 否 | 返回整段：`pageinfo` / `view` / `presenter` / `controls` / `pageswitch` / `businessmodel` |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `code` | string | 表单编码 |
+| `node` | any | nodeCode 命中的节点子树 |
+| `item` 内含于 node | — | itemCode 命中时返回该数组元素 |
+| `handler` | any | handlerCode 命中的处理器完整定义 |
+| `section` | any | section 命中的整段内容 |
+| `actionIndex` | array | handler 的 action 清单，每项 `{ index, code, type, scriptLen, conditionLen, expressionLen }`，便于精确构造 `replace_script` |
+| `message` | string \| null | 提示信息 |
+
+---
+
+## `patch_form` — 局部补丁修改表单（写）
+
+以 delta ops 局部修改表单，无需回传完整 JSON。**11 类 ops**，事务性预演，失败整批回滚。改初始化脚本（presenter.initial）与改按钮事件用法一致。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `code` | string | 是 | 目标表单/页面唯一编码 |
+| `ops` | array | 是 | 补丁操作数组，至少 1 个；按顺序依次作用于上一步结果。11 类 op 见下 |
+| `commitMessage` | object | 是 | 提交信息，整批 ops 共用一个 |
+| `dryRun` | boolean | 否 | 只预演并输出 diff、不落库，**默认 false** |
+| `verify` | boolean | 否 | 保存后回读校验，**默认 true** |
+
+### 11 类 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 树节点内**数组元素级**操作，四种模式 + 两级嵌套，详见下节 |
+| `patch_action_array_item` | handler action 内数组 | `handlerCode`、`arrayProp`（如 `setter`）、`mode`、其余见下 | presenter.handlers/initial 中某 **action 内部数组**（如 `datarequest.setter` 界面输出绑定到控件、`param.properties`），四种模式 + 两级嵌套 |
+| `insert_node` | view 树 | `parentCode`、`node`（新节点对象）、`position?`（默认末尾） | 插入新节点 |
+| `remove_node` | view 树 | `code`、`checkRefs?`（默认 true：存在事件/handler 引用时拒绝删除） | 删除节点 |
+| `move_node` | view 树 | `code`、`newParentCode`、`position?` | 移动节点到新父节点 |
+| `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` 消歧 |
+| `add_businessmodel` | — | `modellogiccode`、`overwrite?` | **MCP 自动拉取该逻辑完整 JSON** 追加到 businessmodel（无需传大段逻辑 JSON）；已存在时默认跳过，`overwrite:true` 覆盖 |
+| `remove_businessmodel` | — | `modellogiccode`、`checkRefs?`（默认 true） | 移除引用 |
+
+### 数组元素级操作详解（patch_node_array_item / patch_action_array_item 共用语义）
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `mode` | 否 | `merge`（默认，浅合并到已存在元素）/ `append`（末尾加 `item`）/ `insert`（`position` 处加 `item`）/ `remove`（按 itemKey 删元素） |
+| `itemKey` | 否 | 元素定位键字段名，默认 `code`（merge/remove 及两级定位外层用） |
+| `itemKeyValue` | 条件 | merge/remove 时要定位/删除的元素键值；两级模式时为**外层元素**键值（如 setter 中 `name="kx_kq_product"` 的那条） |
+| `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 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `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` / `NO_TARGET` / `INVALID_PARAMS` |
+| `diff` | string | 全部 op 的 diff 片段（超长截断；只回改动摘要不回整份表单） |
+| `ops` | array | 每个 op 的结果：`{ index, op, status, errorCode, message, hunk?(replace_script 才有), suggestions?(NOT_FOUND 时的相似候选 [{startLine, score, preview}]) }` |
+
+### ⚠️ 高频陷阱：界面输出绑定的两种真实落点，patch 前必须先核对
+
+字段级绑定与模型级属性映射落点不同，**patch 前必须先 `get_form_fragment({ handlerCode })` 看清是哪一层**：
+
+1. **`datarequest.setter` 顶层**：`setter` 直接是 `[{ name, ctrl: { code } }]`（如部分表单的 `pack5_barcode`/`status` 绑定）→ 对顶层 `setter` 用普通 append/merge 即可。
+2. **`datarequest.setter[*].properties` 嵌套数组**：模型级属性映射（如 `kx_kq_product` 的 67 条 properties）→ 用 `patch_action_array_item` + `itemKey:"name"`/`itemKeyValue:"kx_kq_product"` 定位外层元素 + `elementArrayProp:"properties"` 钻进去，单 op 写一条新绑定，无需内联整段 setter。
+
+误把嵌套数组当顶层 append 会被 `ARRAY_NOT_FOUND` 阻断（默认 fail-closed，不会污染表单）；remove 删后数组变空会自动删除该数组属性，不留 `{"properties":[]}` 空壳。
+
+---
+
+## `save_form` — 全量保存表单（写，整页重构才用）
+
+回传完整 FormResult 全量保存。**仅用于整页重构**（重排布局、模板迁移）；日常局部改动一律 `patch_form`。`businessmodel` 随表单透传，MCP 不剥离。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `form` | object | 是 | 完整表单 JSON（FormResult），通常来自 `get_form` 返回、修改后回传。宽松对象：查到什么存回什么，不要丢字段 |
+| `commitMessage` | object | 是 | 提交信息（见顶部通用结构） |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `ok` | boolean | 是否保存成功 |
+| `code` | string | 保存成功的表单编码（失败时可能缺省） |
+| `message` | string | 保存结果消息（服务端返回的 resp_data 字符串；失败时返回错误体 JSON） |
+
+### 坑
+
+- **禁止对已有大表单整份回传**：极易超长截断、误改不相关字段；当且仅当 JSON 过大无法内联且局部工具无法满足时，才可用 SKILL.md「八、超大 JSON 全量保存的官方脚本」（真·MCP 客户端，非直连 REST）。
+- 全量保存会覆盖整个表单：回传前确认来源是最新的 `get_form` 结果，且改动点都已应用。

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

@@ -0,0 +1,114 @@
+# 函数工具手册：function 域（3 个工具）
+
+> 属 **function** 域：使用前需 `mcp_activate('function')` 激活（连接后默认隐藏）。
+> 三个工具全部只读。flycode 函数与数据库函数是两类东西：前者是平台函数（代码跑在 Java Nashorn 的 ES5 JS），后者是 PostgreSQL 自定义函数。
+
+## 枚举速查
+
+- `dddlayer`（函数层级）：flycode 函数列表固定传/返回 `3`
+- 数据库函数 `publishstatus`：**1-未发布 / 2-已发布**（⚠️ 与实体 `publishstatus` 的 1-已发布/2-未发布 方向相反，勿混淆）
+- `marktype`：0-平台 / 1-产品 / 2-租户；`status`：1-启用 / 2-停用
+
+---
+
+## `page_function_list` — 分页查询 flycode 函数（只读）
+
+分页查询 flycode 函数列表（`dddlayer` 由服务端固定传 `3`，无需调用方传）。
+
+### 输入（全部可选）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `classname` | string | 否 | 函数英文名 |
+| `name` | string | 否 | 函数中文名（通常与 modelname 一致） |
+| `modelname` | string | 否 | 函数中文名（通常与 name 一致） |
+| `flycodekey` | string | 否 | 函数内容关键字（搜代码内容） |
+| `page` | string | 否 | 当前页，从 1 开始 |
+| `rows` | string | 否 | 每页记录数 |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | array | 这一页的函数数据，每项字段见下 |
+| `pageCount` / `pageIndex` / `pageSize` / `resultCount` | number | 总页数 / 第几页 / 每页记录数 / 总记录数 |
+
+`data[]` 每项（均为可选字段，string|number 兼容返回）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `modelcode` | 函数的编码（`get_function` 入参） |
+| `modelname` | 函数中文名 |
+| `classname` | 函数英文名 |
+| `modeldescr` | 函数描述 |
+| `dddlayer` | 函数层级标识，列表固定 3 |
+| `directorytypecode` | 所属目录分类编码 |
+| `metamodelcode` | 领域模型编码，与 modelcode 构成复合主键 |
+| `marktype` / `status` / `seq` | 创建标记 / 状态 / 顺序 |
+| `tablename` | 数据库表名（函数一般无对应表，通常为空） |
+| `createtime` / `createaccountcode` / `createaccountname` | 创建时间 / 创建人账号 code / 创建人姓名 |
+| `updatetime` / `updateaccountcode` / `updateaccountname` | 最近更新时间 / 更新人账号 code / 更新人姓名 |
+
+> 列表**不含**函数代码；看代码用 `get_function`。
+
+---
+
+## `get_function` — 查询 flycode 函数详情（只读）
+
+按 `modelcode` 查询函数详情：基本信息 + `confjson`（flycode 函数代码内容）。
+
+### 输入
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `modelcode` | string | 是 | 函数的编码（来自 `page_function_list`） |
+
+### 输出
+
+顶层为宽松对象：`page_function_list` 的全部字段 + 详情专有的：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `confjson` | string \| null | flycode 函数代码内容（核心字段） |
+
+### 注意
+
+- 函数代码运行于 **Java Nashorn 的 ES5 JS**，无 FlyQL 编译与业务内置对象；业务逻辑中通过 `loadex('方法名')` 加载调用。
+- 详情接口结构不稳定，未声明字段会原样透传（宽松校验），以真实返回为准。
+
+---
+
+## `page_database_function_list` — 分页查询数据库函数（只读）
+
+分页查询 PostgreSQL 自定义函数列表。**函数体 `functionscript` 已随行返回**，无独立详情工具。
+
+### 输入（全部可选）
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `dbfunctionname` | string | 否 | 数据库函数名，模糊匹配 |
+| `name` | string | 否 | 函数中文名，模糊匹配 |
+| `pageindex` | string | 否 | 当前页，从 1 开始（⚠️ 参数名与其他工具的 `page` 不同） |
+| `pagesize` | string | 否 | 每页记录数（⚠️ 参数名与其他工具的 `rows` 不同） |
+
+### 输出
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `data` | array | 这一页的数据库函数数据，每项字段见下 |
+| `pageCount` / `pageIndex` / `pageSize` / `resultCount` | number | 总页数 / 第几页 / 每页记录数 / 总记录数 |
+
+`data[]` 每项（均为可选字段）：
+
+| 字段 | 说明 |
+| --- | --- |
+| `functioncode` | 函数唯一编码（与 metamodelcode 构成复合主键） |
+| `dbfunctionname` | 数据库函数名（PG 里的函数名） |
+| `functionname` | 函数中文名 |
+| `functionscript` | **数据库函数内容（PostgreSQL 函数体）**，列表随行返回 |
+| `publishstatus` | 发布状态：1-未发布 / 2-已发布（⚠️ 与实体方向相反） |
+| `status` | 状态：1-启用 / 2-停用 |
+| `marktype` | 创建标记：0-平台 / 1-产品 / 2-租户 |
+| `metamodelcode` | 领域模型编码 |
+| `remark` | 备注 |
+| `createtime` / `creator` / `updatetime` / `updator` | 创建时间 / 创建人 / 更新时间 / 更新人 |