flycode-mcp 1.14.6 → 1.14.7

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 (6) hide show
  1. package/README.md +122 -820
  2. package/dist/cli.js +537 -8
  3. package/dist/flycode-mcp.min.js +1 -1
  4. package/dist/skills/flycode-mcp-skill/SKILL.md +7 -4
  5. package/dist/skills/flycode-mcp-skill/tools/form.md +55 -5
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -1,48 +1,19 @@
1
1
  # flycode-mcp
2
2
 
3
- A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the **FlyCode** language platform
4
- （Flycode / 玄瞳科技 APaaS 平台）。它把 APaaS 平台的实体、领域相关能力以 MCP 工具的形式暴露给支持 MCP 的客户端
5
- （如各类 AI 编程助手），让模型能够直接检索实体、业务领域中的逻辑定义。
3
+ 一个 MCP 服务（[Model Context Protocol (MCP)](https://modelcontextprotocol.io)），让 AI 能够操作 IDE 。
6
4
 
7
- ---
8
-
9
- ## 特性
10
-
11
- - 基于官方 `@modelcontextprotocol/sdk` 实现，使用标准 `stdio` 传输协议。
12
- - 启动即完成 APaaS IDE 平台鉴权链路：账号登录 → 获取租户信息 → 获取 IDE Token。
13
- - 内置统一请求层 `request`，自动按请求类型（`center` / `tenant` / `business`）切换中心服务地址、当前租户连接地址或当前租户业务地址，并自动注入鉴权 Token：`business` 类型主要用于 H5 表单查询（需以特定预览账号 token 发起）。
14
- - 当前提供工具：业务逻辑类；实体类；表单类；H5 表单类；flycode 函数类；数据库函数类；SQL 执行类；通用类。
5
+ 官网：[flycode-mcp](https://flycodemcpwebsite-3swq2ww.maozi.io)
15
6
 
16
7
  ---
17
8
 
18
- ## 工具渐进式披露（Progressive Disclosure）
19
-
20
- 部分客户端在 `tools/list` 阶段会把全部工具的 schema 一次性塞进上下文，受预算 / 截断策略影响可能只保留一部分，导致 AI 看不到另一些工具。本服务采用 MCP 协议原生支持的渐进式披露机制缓解该问题：
21
-
22
- - **始终可见（连接后）**：`mcp_catalog`（工具目录）、`mcp_activate`（启用 / 收起域）两个网关工具，外加 `core` 域的 `run_sql`、`generate_unique_code`，共 4 个工具。
23
- - **按需解锁**：其余工具按能力聚为 `entity` / `form` / `logic` / `function` / `h5` 五个域，默认隐藏。AI 先调 `mcp_catalog` 了解有哪些域与工具，再调 `mcp_activate('form')` 启用某域；服务端随即推送 `tools/list_changed` 通知，合规客户端重拉清单后即见该域工具。亦可 `mcp_activate('form', true)` 收起以回收上下文。
24
-
25
- 实现要点：`src/tools/registry.ts` 预注册全部工具并维护「域 → 工具」映射，progressive 模式下对非核心域工具默认 `disable()`；`enable()/disable()` 由 `@modelcontextprotocol/sdk` 的 `RegisteredTool` 提供，并自动触发 `tools/list_changed`。回归用例见 `test/unit/gateway-registry.test.ts`。
26
-
27
- > **约定（勿回退）：`mcp_catalog` 不返回工具的入参 schema**，`registry.focus()` 只回「工具名 / 说明 / 启用状态」。原因有二：① 工具入参的 zod schema 经 SDK 转 JSON Schema 后会被**完全内联展开**（递归结构实测最大深度 28 层、`$defs` 为 0），再叠加 `JSON.stringify(..., null, 2)` 的缩进，logic 域单次 focus 曾返回 **504KB**（线上实测 526KB）；② 该信息与「启用后客户端重拉的 `tools/list`」**完全重复**，而工具返回值一旦进入上下文就无法撤回、`tools/list` 反倒可由客户端自行管理。参数细节以 `tools/list` 为准。
28
-
29
- > **两道防线**：① 工具返回体一律**紧凑序列化**（`JSON.stringify(data)`，不带缩进）——全仓库已无 `null, 2` 式美化输出；② `mcp_catalog` 返回体带**硬上限熔断**（`CATALOG_MAX_CHARS` = 32KB），超限会自动分级降级：先截断工具描述 → 再清空描述只留工具名 → 最后才丢弃工具清单，并在响应里回 `truncated` 与 `note`。降级顺序刻意牺牲描述、保住工具清单，因为「哪些工具可用」才是 catalog 的核心价值。回归用例见 `test/unit/catalog-budget.test.ts`。
9
+ ## 技术栈
30
10
 
31
- > **第三道防线（公告 schema 压缩）**：`tools/list` 里每个工具的 `inputSchema` 也可压缩——SDK 会把 zod schema 投影成完全内联的 JSON Schema（本仓库实测最大单 schema 14.9KB），叠加部分客户端存在 per-schema 硬上限（如 Kimi 约 15KB 直接拒绝）。`FLYCODE_MCP_INPUT_SCHEMA_PROFILE=compact` 时，`tools/list` 响应中每个工具的 `inputSchema` 被压缩到单 schema 13KiB 预算内：先剥离嵌套注解（description/examples/default/title，校验关键字保留）；仍超预算或超深度的回退「浅形」——只保留根属性的 type/description/enum 并注明为精简公告。**工具级描述一字不减、服务端 canonical 校验原样保留**，客户端看到的只是引导参数生成的公告形态。实测 27 工具公告 155KB → 103KB，最大单 schema 14.9KB → 1.4KB。实现见 `src/utils/compact-input-schema.ts`，回归用例见 `test/unit/compact-input-schema.test.ts` 与 `test/unit/tools-list-size.test.ts`。
11
+ 1. MCP 服务
12
+ - Node.js ≥ 18
13
+ - Typescript
32
14
 
33
- 环境变量：
34
-
35
- - `PROGRESSIVE_DISCLOSURE=on`（默认）：启用渐进式披露。
36
- - `PROGRESSIVE_DISCLOSURE=off`：退化回「全部 27 个工具始终启用」的原有行为，作为客户端未实现 `tools/list_changed` 重拉时的兜底。若 `mcp_activate` 启用某域后调用域工具仍报 `tool not found`，说明当前客户端不支持该通知，请设为 `off`。
37
- - `FLYCODE_MCP_INPUT_SCHEMA_PROFILE=full`（默认）：`tools/list` 公告原始 schema，保持兼容。
38
- - `FLYCODE_MCP_INPUT_SCHEMA_PROFILE=compact`：启用公告 schema 压缩（见上「第三道防线」）。推荐给有 per-schema 大小限制或上下文预算紧张的客户端。
39
-
40
- ---
41
-
42
- ## 环境要求
43
-
44
- - Node.js ≥ 18（使用了 ES Module 与 `fetch`- 无关的现代语法，建议 18+）
45
- - npm（或 pnpm / yarn）
15
+ 2. 静态说明文档（官网）
16
+ - VitePress
46
17
 
47
18
  ---
48
19
 
@@ -52,818 +23,149 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the
52
23
  # 安装依赖
53
24
  npm install
54
25
 
55
- # 类型校验(tsc -p tsconfig.json，tsconfig 设 noEmit) + esbuild 经 scripts/build.mjs 打包压缩为单文件 dist/flycode-mcp.min.js
26
+ # 打包构建
56
27
  npm run build
57
28
 
58
- # 仅做类型校验（不产出）
29
+ # 类型校验
59
30
  npm run typecheck
60
31
 
61
- # 开发模式：esbuild --watch 持续重建产物
62
- npm run dev
63
- ```
64
-
65
- 构建产物有两份：`dist/flycode-mcp.min.js`（MCP server，minify 后折叠为单行以减小体积）与 `dist/cli.js`（命令行入口，不 minify、不折叠——内含界面文案）；`package.json` 的 `bin` 将 `flycode-mcp` 命令注册到 `dist/cli.js`。运行时依赖 `@modelcontextprotocol/sdk` / `axios` / `zod` / `@clack/prompts` 保持外置。
66
-
67
- > **注意（构建期易踩坑）**：单行折叠由 `scripts/collapse.mjs` 完成，**不可**退化为 `code.replace(/\n/g, '')`。
68
- > esbuild 为省一个字符会把含换行的字符串打印成「内含真实换行字符的模板字符串」（`` `\<LF>` ``，而非转义写法 `"\n"`），
69
- > 无差别删除换行会把字符串内部的换行一起吃掉（`'\n'` → `''`），导致 `str_replace_flycode` 保存的 flycode 被整段压扁、
70
- > 工具描述的多行提示词被粘成一行（2026-09-20 线上事故根因）。
71
- > 该模块用扫描器区分「代码层换行」与「字符串内换行」，后者转写为 `\n` 转义；
72
- > 结构无法可靠判定时整段放弃折叠，并由 `node --check` 兜底回退，回归用例见 `test/unit/build-collapse.test.ts`。
73
-
74
- ---
75
-
76
- ## CLI（flycode-mcp 命令）
77
-
78
- 全局安装后即可使用 `flycode-mcp` 命令：
79
-
80
- ```bash
81
- npm install -g flycode-mcp
82
- ```
83
-
84
- | 命令 | 说明 |
85
- | ----------------------------------- | -------------------------------------------------------------------------------------- |
86
- | `flycode-mcp` / `flycode-mcp mcp` | 启动 MCP stdio server（兼容 `key=value` 启动参数写法，行为与直跑 `dist/flycode-mcp.min.js` 一致） |
87
- | `flycode-mcp setup` | 交互安装配套 skill 到所选智能体（初版支持 WorkBuddy / Trae CN） |
88
- | `flycode-mcp update` | 自更新全局包，并刷新本工具安装过的 skill |
89
- | `flycode-mcp --version` / `--help` | 版本与帮助 |
90
-
91
- ### setup：安装 skill
92
-
93
- ```bash
94
- flycode-mcp setup # 交互：选 WorkBuddy / Trae CN → 预览计划 → 回车确认
95
- flycode-mcp setup -c workbuddy -c trae-cn --yes # 非交互执行
96
- flycode-mcp setup --dry-run # 只打印安装计划，零写入
97
- ```
98
-
99
- 安装目标（初版只装 skill）：
100
-
101
- | 客户端 | skill 目录 |
102
- | --------- | -------------------------------------------- |
103
- | WorkBuddy | `~/.workbuddy/skills/flycode-mcp-skill/` |
104
- | Trae CN | `~/.trae-cn/skills/flycode-mcp-skill/` |
105
-
106
- 保护机制：
107
-
108
- - **已存在即更新替换**：目标目录已有 skill（无论当初是 CLI 安装还是手工放置）都会直接更新到当前版本；内容与版本均已一致时跳过写入。
109
- - **旧目录移入废纸篓**：替换时**不在同目录留任何备份**——旧目录整体移入系统废纸篓（macOS 废纸篓 / Windows 回收站 / Linux `gio trash`），需要时可从废纸篓手动恢复，绝不 `rm -rf`。
110
- - **事务写入**：先复制到临时 staging 目录并回读校验（文件清单 + `SKILL.md` + marker），校验通过、旧目录成功进废纸篓之后才原子切换为正式目录；全程 fail-closed，任何一步失败旧目录都原封不动。
111
-
112
- ### update：自更新
113
-
114
- ```bash
115
- flycode-mcp update
116
- ```
117
-
118
- 自动检测安装方式（npm / bun 全局安装）→ 从 npm registry 查最新版本 → 全局升级 → 回读包根校验版本 → 刷新已安装的 skill 目录（未安装的智能体跳过，旧目录移入废纸篓）。`npx` 临时安装或本地源码运行时给出对应的手动升级提示，不会盲改；失败路径（registry 不可达 / 安装命令失败 / 版本校验失败）均给出 remediation 提示。
119
-
120
- ---
121
-
122
- ## 配置
123
-
124
- 服务启动时需要一组连接参数，格式为**命令行参数字符串**，以 `&` 拼接的 `key=value` 形式传入（与 `URLSearchParams` 解析一致）：
32
+ # 运行文档
33
+ npm run docs:dev
125
34
 
35
+ # 构建文档
36
+ npm run docs:build
126
37
  ```
127
- username=<账号>&password=<密码>&tenantCode=<租户号>&envName=<环境名>
128
- ```
129
-
130
- 参数说明：
131
-
132
- | 参数 | 必填 | 说明 |
133
- | ------------- | ---- |-------------------|
134
- | `username` | ✅ | APaaS IDE平台登录账号 |
135
- | `password` | ✅ | APaaS IDE平台登录密码 |
136
- | `tenantCode` | ✅ | 租户号（用于匹配目标租户） |
137
- | `envName` | ✅ | 环境名（用于在租户下定位具体环境） |
138
-
139
- > ⚠️ **安全提示**：密码为明文传入，请勿在公开环境或版本库中泄露。仓库已通过 `.gitignore` 忽略 `mcp.json` 等含凭据文件。
140
38
 
141
39
  ---
142
40
 
143
- ## 客户端接入示例
41
+ ## 使用
144
42
 
145
- 在你的 MCP 客户端（如 Cursor、Claude Desktop、VS Code 插件等）的配置中添加一个 server。
146
- **请使用你自己真实的账号信息替换占位符**，不要提交真实凭据：
43
+ 1. 配置 MCP 服务
147
44
 
148
- ```json
149
- {
150
- "mcpServers": {
151
- "flycode-mcp-你的环境": {
152
- "command": "npx",
153
- "args": [
154
- "flycode-mcp",
155
- "username=你的账号&password=你的密码&tenantCode=你的租户号&envName=你的环境名"
156
- ]
45
+ ```json
46
+ {
47
+ "mcpServers": {
48
+ "flycode-mcp": {
49
+ "command": "npx",
50
+ "args": [
51
+ "flycode-mcp",
52
+ "username=你的IDE账号&password=你的IDE密码&tenantCode=要连接的租户号&envName=要连接的环境名"
53
+ ]
54
+ }
55
+ }
157
56
  }
158
- }
159
- }
160
- ```
161
-
162
- v1.14.2 及以上版本以上推荐增加两个环境变量组合 `PROGRESSIVE_DISCLOSURE` 和 `FLYCODE_MCP_INPUT_SCHEMA_PROFILE` 获得更优体验：
163
-
164
- ```json
165
- {
166
- "mcpServers": {
167
- "flycode-mcp-你的环境": {
168
- "command": "npx",
169
- "args": [
170
- "flycode-mcp",
171
- "username=你的账号&password=你的密码&tenantCode=你的租户号&envName=你的环境名"
172
- ],
173
- "env": {
174
- "PROGRESSIVE_DISCLOSURE": "off",
175
- "FLYCODE_MCP_INPUT_SCHEMA_PROFILE": "compact"
57
+ ```
58
+
59
+ `v1.14.2` 及以上版本以上推荐增加两个环境变量组合 `PROGRESSIVE_DISCLOSURE` 和 `FLYCODE_MCP_INPUT_SCHEMA_PROFILE` 获得更优体验：
60
+
61
+ ```json
62
+ {
63
+ "mcpServers": {
64
+ "flycode-mcp": {
65
+ "command": "npx",
66
+ "args": [
67
+ "flycode-mcp",
68
+ "username=你的IDE账号&password=你的IDE密码&tenantCode=要连接的租户号&envName=要连接的环境名"
69
+ ],
70
+ "env": {
71
+ "PROGRESSIVE_DISCLOSURE": "off",
72
+ "FLYCODE_MCP_INPUT_SCHEMA_PROFILE": "compact"
73
+ }
74
+ }
176
75
  }
177
76
  }
178
- }
179
- }
180
- ```
181
-
182
- ---
183
-
184
- ## 使用说明书网站（website/）
185
-
186
- 本仓库在 `website/` 子目录下附带一份 **面向终端用户的使用说明书网站**（不是给贡献者看的开发文档，而是给「通过 AI 客户端使用本 MCP 的普通用户」看的图文向导）。它用 [VitePress](https://vitepress.dev) 构建，整体卡通风格、带轻量动画，内容是本 README 的「小白友好版」：首页 → 快速开始 → 接入 WorkBuddy / Cursor / Claude Desktop → 准备账号 → 能力清单 → 常见场景 → 排错 FAQ → 版本更新记录。
77
+ ```
187
78
 
188
- > 说明：本 README 是开发者与工具行为的权威参考；`website/` 是给最终用户阅读的上手向导，两者内容定位不同、需随工具变更同步更新。
79
+ >
80
+ > PROGRESSIVE_DISCLOSURE：是否开启渐进披露功能，默认开启。开启后工具数量减少，AI 按需激活工具，激活后才可使用，用于降低上下文。
81
+ >
82
+ > FLYCODE_MCP_INPUT_SCHEMA_PROFILE：工具的 `input schema` 模式，可选值 `full | compact` 。`compact` 下会对 `input schema` 进行压缩，同样用于减少上下文。
83
+ >
84
+ > 实测 `v1.14.2` 以后，`FLYCODE_MCP_INPUT_SCHEMA_PROFILE` 设置为 `compact` 后，上下文占用已不会太大，可以关闭渐进式披露，不需要 AI 再多调一次激活工具。
85
+ >
189
86
 
190
- ### 技术栈与目录
87
+ 2. 安装命令行工具
191
88
 
192
- - 构建工具：**VitePress 1.6.x**（Markdown 写文档、零前端框架门槛，产物为纯静态 HTML）。
193
- - 自定义二次元主题：`website/.vitepress/theme/style.css`（柔和粉紫渐变、圆角卡片、漂浮星星、星空暗色、动效，且尊重系统「减少动态效果」偏好）。
194
- - 卡通吉祥物：`website/public/mascot.svg`（SVG 自绘，无位图授权风险）。
195
- - 站点图标（favicon）：`website/public/favicon.svg`（浏览器页签，与吉祥物同源设计）+ `favicon.ico` / `favicon-32x32.png` / `apple-touch-icon.png`（位图兜底，由 `scripts/gen-favicon.py` 从同一设计生成）。
196
- - 内容源码：`website/*.md`（首页、`guide/`、`capabilities/`、`cookbook.md`、`faq.md`、`changelog.md`）。其中 `changelog.md` 为**版本更新记录**，按 git tag 从新到旧整理每个版本的变化（面向使用者表述）。
89
+ ```bash
90
+ npm install -g flycode-mcp
91
+ ```
197
92
 
198
- ### 本地预览 / 构建
93
+ 3. 安装配套 SKILL
199
94
 
200
- 仓库根 `package.json` 已内置快捷脚本（通过 `--prefix website` 转发）：
201
-
202
- ```bash
203
- # 本地开发预览（热更新，默认 http://localhost:5173）
204
- npm run docs:dev
205
-
206
- # 生产构建（纯静态产物输出到 website/.vitepress/dist/）
207
- npm run docs:build
208
-
209
- # 预览构建产物（默认 http://localhost:4173）
210
- npm run docs:preview
211
- ```
95
+ ```bash
96
+ flycode-mcp setup
97
+ ```
212
98
 
213
- 也可进入子目录直接操作：
214
-
215
- ```bash
216
- cd website
217
- npm install # 首次需安装 VitePress 依赖
218
- npm run docs:dev
219
- ```
220
-
221
- ### 部署
222
-
223
- 站点产物为纯静态文件，可托管到任意静态托管服务（如 GitHub Pages、腾讯云 COS 静态网站托管）。部署脚本随平台后续补充，源码与构建命令不变。
99
+ >
100
+ > 使用命令 `flycode-mcp update` 可以更新 SKILL 。
101
+ >
224
102
 
225
103
  ---
226
104
 
227
- ## 提供的工具
228
-
229
- ### `page_model_logic_list` — 分页查询业务逻辑列表
230
-
231
- 根据查询条件分页查询 IDE 领域中的业务逻辑定义（只读、幂等）。
232
-
233
- **输入参数：**
234
-
235
- | 参数 | 类型 | 必填 | 说明 |
236
- | --------- | -------- | ---- | -------------------------- |
237
- | `keys` | string | 否 | 业务逻辑名，模糊匹配 |
238
- | `keywords`| string | 否 | 代码中的关键字，模糊匹配 |
239
- | `page` | string | 否 | 当前页，从 1 开始，默认 1 |
240
- | `rows` | string | 否 | 每页记录数，默认 20 |
241
-
242
- **返回：** 业务逻辑列表的 JSON（`resp_data`），包含 `modellogiccode`、`modellogicname`、`modelname`、`functionname`、`status` 等字段。
243
-
244
- ### `get_model_logic` — 查询业务逻辑详情
245
-
246
- 根据业务逻辑的编码 `modellogiccode` 查询其完整详情（只读、幂等），包括 flycode 脚本、输入输出参数结构、操作步骤等。底层调用 `logicClient.getModelLogic`。
247
-
248
- **输入参数：**
249
-
250
- | 参数 | 类型 | 必填 | 说明 |
251
- | --------- | -------- | ---- | -------------------------- |
252
- | `modellogiccode` | string | 是 | 要查详情的业务逻辑的编码 |
253
-
254
- **返回：** 业务逻辑详情的 JSON（`resp_data`），主要字段：
255
-
256
- - `modellogicname` / `modellogiccode` / `modelcode`：业务逻辑标题、编码、所属业务模型编码
257
- - `actiontype` / `actioncategory` / `execmode` / `executionmode`：操作/行为类型、执行方式
258
- - `input` / `output`：flycode 内置对象 `IN` / `OUT` 的结构与字段属性（含 `propertytypecode` 字段类型映射）
259
- - `operations`：操作步骤，其中 `templateparams.flycode` 内含具体的 flycode 脚本代码
260
- - `description` / `message` / `status` 等
261
-
262
- ### `save_model_logic` — 保存业务逻辑（完整全量保存；仅新增，或全量 JSON 很小如微服务）
263
-
264
- 将一条业务逻辑保存到 APaaS 平台（非破坏性写入）。本工具只适合两类场景，**其余改动请用另两个工具**：
265
-
266
- ① **新增业务逻辑（最常见）**：首次创建一条业务逻辑时，回传从 `get_model_logic` 模板构造或新建的完整 `LogicResult` 对象（含 flycode 脚本、input/output、标题等），连同提交信息 `commitMessage` 一起保存；
267
- ② **已有逻辑的全量 JSON 很小**（典型如微服务 `actioncategory=2`，往往只有几行）：`patch_model_logic` / `str_replace_flycode` 都没有针对微服务的专用 op，直接用本工具全量保存更省事。
268
-
269
- 底层调用 `service/logic.ts` 的 `saveModelLogic`，再经 `logicClient.saveModelLogic` 以 `overwrite: false`（不覆盖他人最新版本）提交到 `/bizserv/bizmodel/saveModelLogic`。
270
-
271
- > **编辑已有逻辑（JSON 较大，如普通 flycode 接口）请勿用本工具回传整份对象**：回传整份 `LogicResult` 上下文占用极大、易因超长被截断，且易误改不相关字段。微服务 / 导出等 JSON 很小的已有逻辑可直接全量保存（见上文②）。
272
- > - 改 flycode 脚本 → 用 `str_replace_flycode`
273
- > - 改 input/output 结构或顶层元数据 → 用 `patch_model_logic`
274
-
275
- **输入参数：**
276
-
277
- | 参数 | 类型 | 必填 | 说明 |
278
- | -------------- | -------- | ---- | ---------------------------------------------------------------------------------------------------------- |
279
- | `logic` | object | 是 | 完整的业务逻辑 JSON 对象（`LogicResult`）。通常来自 `get_model_logic` 的返回，修改后原样回传；微服务 / 导出 / 内部函数等各类结构均兼容（未声明字段会被保留） |
280
- | `commitMessage`| object | 是 | 提交信息，含以下字段： |
281
- | `committype`| enum | 是 | 提交类型：`saverecord` / `feature` / `fix` / `stylefix` / `refactor` / `testfix`（与 `committypetext` 一一对应） |
282
- | `committypetext`| enum | 是 | 提交类型名称：`保存记录` / `新功能添加` / `bug修改` / `样式修改` / `重构` / `测试`（与 `committype` 一一对应） |
283
- | `msgbody` | string | 条件 | 提交内容。`committype=saverecord` 时忽略（服务端自动填入 `yyyy-MM-dd hh:mm` 格式的当前时间）；其他类型必填，按 git 提交规范书写 |
284
-
285
- **返回：** 保存操作的结果消息（服务端返回的 `resp_data` 字符串；失败时返回错误体 JSON）。
286
-
287
- > 注：保存后建议重新 `get_model_logic` 核对最新版本。`committype=saverecord` 的提交时间由服务端写入，无需在 `msgbody` 中重复填写。
288
-
289
- ### `patch_model_logic` — 局部补丁修改业务逻辑（input/output/元数据，替代旧版 simple_save）
290
-
291
- 以结构化补丁（delta ops）局部修改业务逻辑的 **input/output 结构或顶层元数据**，**无需回传完整 `LogicResult`，大幅节省上下文**（flycode 脚本不在本工具范围内，由 `str_replace_flycode` 负责）。底层调用 `service/logic.ts` 的 `patchLogic`：先按 `modellogiccode` 拉取最新完整对象，在内存副本上按顺序合并 ops，再一次性全量保存（服务端仅提供全量覆盖保存接口，故仍是一次性 `overwrite: false` 提交）。
292
-
293
- **事务性**：ops 具备事务性——全部 op 预演成功才落库，任一 op 失败（`PARAM_NOT_FOUND` / `PROP_NOT_FOUND` / `DUP_NAME` / `INVALID_PARAMS`）则整批中止、**不产生任何写入**。整批只发起一次保存请求，不存在「写一半再回滚」的中间态。改动较大或不确定时建议先 `dryRun=true` 预览摘要。
294
-
295
- **输入参数：**
296
-
297
- | 参数 | 类型 | 必填 | 说明 |
298
- | --------------- | ------ | ---- | ------------------------------------------------------------------------------------- |
299
- | `modellogiccode`| string | 是 | 目标业务逻辑编码（即 `get_model_logic` 返回的 `modellogiccode`） |
300
- | `ops` | array | 是 | 补丁操作数组，**至少一个元素**（`min(1)`），按数组顺序依次作用于上一步结果（见下表） |
301
- | `commitMessage` | object | 是 | 提交信息，整批 ops 共用一个；结构与 `save_model_logic` 的 `commitMessage` 一致 |
302
- | `dryRun` | boolean | 否 | 只预演输出 diff、不落库，默认 `false` |
303
- | `verify` | boolean | 否 | 保存后是否回读校验所有改动已生效，默认 `true` |
304
-
305
- `ops[]` 共 12 类（按 `op` 字段区分的 discriminated union）：
306
-
307
- **input/output 结构类（6 类）**
308
-
309
- | `op` | 必填载荷 | 说明 |
310
- | ---------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
311
- | `add_param` | `target`(`input`/`output`) + `param`(单条 `LogicParameters`) + 可选 `position` | 向 input/output 追加一条参数（增加一个 input / 增加一个 output） |
312
- | `remove_param` | `target` + `name` | 按 `name` 从 input/output 删除整条参数（删除一个 input / output） |
313
- | `set_param_attrs`| `target` + `name` + `patch`(`Record<string,unknown>`) | 按 `name` 定位参数，浅合并其顶层属性（如 `datatype`/`objectcode`/`objectname`） |
314
- | `add_property` | `target` + `paramName` + `property`(单条 `LogicParameterProperties`) + 可选 `position` | 向指定参数的 `properties[]` 追加一个字段（增加 input 属性 / 增加 output 属性） |
315
- | `remove_property`| `target` + `paramName` + `propertyName` 或 `propertyCode`（二选一） | 从指定参数的 `properties[]` 删除一个字段 |
316
- | `replace_property`| `target` + `paramName` + `propertyName`/`propertyCode` + `property` | 定位并整体替换一个字段 |
317
-
318
- **元数据类（1 类）**
319
-
320
- | `op` | 必填载荷 | 说明 |
321
- | ---------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
322
- | `set_meta` | `patch`(`Record<string,unknown>`) | 浅合并顶层业务逻辑元数据（如 `modellogicname`/`description`/`actiontype`/`execmode`/`functionname`/`marktype`）；**不能含 `input`/`output`/`operations`** |
323
-
324
- **导出列类（仅 `actioncategory=5` 导出类，5 类）**
325
-
326
- > 仅导出类业务逻辑可用；若对微服务 / 普通 flycode 调用会报 `INVALID_PARAMS` 并引导改用 `save_model_logic`。**切勿用 `set_meta` 去碰 `bindjson`**——`set_meta` 会整体覆盖顶层字段、可能丢失导出列定义；改 `bindjson` 请用 `set_bind_meta`（自动排除 `bindcols`）。各导出 op 以 `field`（优先）或 `column` 定位，假设能唯一定位；若匹配到多个会报 `DUP_NAME` 并拒绝。空串 `field`/`column` 同属「未提供定位键」，不参与匹配（见下方空串约定）。
327
-
328
- | `op` | 必填载荷 | 说明 |
329
- | ---------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
330
- | `add_export_column` | `column`(单条 `LogicBindColumn`，建议至少带 `field`) + 可选 `position` | 向 `bindjson.bindcols` 追加一列 |
331
- | `remove_export_column` | `field` 或 `column`（二选一） | 从 `bindjson.bindcols` 按 `field`/`column` 删除一列 |
332
- | `replace_export_column`| `field`/`column`（二选一）+ `newColumn`(新的完整列对象) | 按 `field`/`column` 定位并整体替换一列 |
333
- | `set_export_column_attrs`| `field`/`column`（二选一）+ `patch`(`Record<string,unknown>`) | 按 `field`/`column` 定位某列，浅合并其部分属性（如改 `column` 标题 / `width` 列宽 / `type` 类型；不改 `field`） |
334
- | `set_bind_meta` | `patch`(`Record<string,unknown>`) | 安全浅合并 `bindjson` 顶层（如 `logicname`），**不影响 `bindcols`**；**不能含 `bindcols`** |
335
-
336
- > 注：`param` / `property` 结构与 `save_model_logic` 的 `input`/`output` 元素一致（`LogicParameters` / `LogicParameterProperties`，含 `datatype` / `marktype` / `name` / `objectcode` / `objectname` / `properties` 等字段）。`add_param` / `set_param_attrs` / 各 property op 均以 `name`（或 `propertyCode`）定位，假设同一 `target` 内 `name` 唯一；若同名会报 `DUP_NAME` 并拒绝。
337
-
338
- > **空字符串不是定位键（重要）**：自定义字段（未挂到实体字段上的属性）其 `propertycode` / `objectcode` 恒为空字符串 `""`。空串一律视为「未提供该键」，不参与匹配与判重——所以新增自定义字段时 `propertycode` 传 `""` 是安全且推荐的写法，**不会**与既有自定义字段误判为重复。相应地，`remove_property` / `replace_property` 若只传空串 `propertyCode` 而无 `propertyName`，会报 `INVALID_PARAMS`。
339
- >
340
- > 报 `DUP_NAME`「已存在」时，消息会明确指明命中了哪一个键（`name=xxx` 或 `propertycode=xxx`），据此核对即可；不要臆测为平台自动同步或外部改动——工具只按上述规则在服务端最新数据上判定。
341
-
342
- **返回：** `{ ok, applied, verified, errorCode, message, diff, ops[] }` —— `diff` 仅回每个 op 的执行摘要（不回整份对象），`ops[]` 与入参一一对应，便于定位失败项。
343
-
344
- ### `str_replace_flycode` — 批量局部替换 / 整份重写 flycode 脚本
345
-
346
- 以 str_replace_editor 模式局部修改业务逻辑的 flycode 脚本：**只需传入要改动的新旧代码片段**，不必回传整份脚本。底层调用 `service/logic.ts` 的 `replaceFlyCodeSegments`：按 `modelLogicCode` 拉取完整对象，在内存副本上完成定位与替换，再以 `overwrite: false` 提交一次 `saveModelLogic`。
347
-
348
- **与另两个写工具的分工：**
349
-
350
- | 场景 | 建议工具 |
351
- | ------------------------------------------------ | ----------------------------------------------------- |
352
- | 改 1~N 处局部片段（最常用） | `str_replace_flycode`（`oldString` / `newString`） |
353
- | 整份脚本重写、大范围重构 | `str_replace_flycode` + 单个 op 置 `rewrite: true` |
354
- | 改 input/output 结构（增删参数、增删字段、改属性） | `patch_model_logic` |
355
- | 改顶层元数据（标题 / 描述 / actiontype 等） | `patch_model_logic` |
356
- | 新增一条业务逻辑（首次创建） | `save_model_logic` |
357
- | 已有逻辑全量 JSON 很小（如微服务 actioncategory=2） | `save_model_logic` 全量保存 |
358
-
359
- **事务性**：`ops` 具备事务性——全部 op 预演成功才落库，任一 op 失败则整批中止、**不产生任何写入**。实现上整批只发起一次保存请求，因此不存在「写一半再回滚」的中间态。
360
-
361
- **执行顺序**：`ops` 按数组顺序依次执行，`ops[i+1]` 在 `ops[i]` 的结果上匹配，因此支持「先插入一段代码、再改这段里的某行」这类依赖。
362
-
363
- **输入参数：**
364
-
365
- | 参数 | 类型 | 必填 | 说明 |
366
- | ---------------- | ------- | ---- | ------------------------------------------------------------------------ |
367
- | `modelLogicCode` | string | 是 | 要修改的业务逻辑编码 |
368
- | `ops` | array | 是 | 替换操作数组，**至少一个元素**（`min(1)`），按数组顺序依次执行 |
369
- | `commitMessage` | object | 是 | 提交信息，整批 ops 共用一个 |
370
- | `dryRun` | boolean | 否 | 只预演输出 diff、不落库，默认 `false` |
371
- | `contextLines` | number | 否 | diff 中每个改动点上下保留的上下文行数，默认 `3` |
372
- | `verify` | boolean | 否 | 保存后是否回读校验所有改动已生效，默认 `true` |
373
-
374
- `ops[]` 元素：
375
-
376
- | 参数 | 类型 | 必填 | 说明 |
377
- | ---------------- | -------------------------- | ---- | -------------------------------------------------------------------- |
378
- | `oldString` | string | 否 | 待替换原文；**partial 模式（默认）下必填**、非空且唯一命中。`rewrite: true` 时被忽略 |
379
- | `newString` | string | 是 | partial 模式下为替换后的新文本（传空串表示删除）；`rewrite: true` 时为整份替换的目标全文 |
380
- | `rewrite` | boolean | 否 | **整份替换开关**，默认 `false`。为 `true` 时忽略 `oldString`，把整个 operation 的脚本整体替换为 `newString` |
381
- | `operationIndex` | number | 否 | 作用于第几个 operation 的脚本，默认 `0` |
382
- | `replaceAll` | boolean | 否 | 替换全部匹配，默认 `false`；与 `occurrence` 互斥 |
383
- | `occurrence` | number | 否 | 只替换第 N 个匹配（1-based）；与 `replaceAll` 互斥 |
384
- | `matchMode` | `'exact' \| 'normalized'` | 否 | 默认 `normalized`，容忍 CRLF/LF 与行尾空白差异；`exact` 为字节严格相等 |
385
- | `label` | string | 否 | 可选标识，仅用于返回报告中辨认该 op |
386
-
387
- **整份重写（`rewrite` 模式）**：整份脚本重写时无需把旧全文塞进 `oldString`（那会把刚读到的旧脚本又回传一遍、浪费上下文），改为给单个 op 置 `rewrite: true`、只传新全文 `newString` 即可：
388
-
389
- ```jsonc
390
- {
391
- "modelLogicCode": "2087720632723837017",
392
- "ops": [{ "rewrite": true, "newString": "/* 全新脚本全文 */" }],
393
- "commitMessage": { "committype": "saverecord", "committypetext": "保存记录" }
394
- }
395
- ```
396
-
397
- `rewrite` op 可与后续 partial op 混用（如「先整份重写，再在其上局部微调」），`ops` 仍按数组顺序在新结果上依次执行。该模式下 `newString` 必填；`oldString` 被忽略。整份替换不渲染 unified hunk，只在 `diff` 中以一行「整份替换：N → M 字符」标记，长度变化见 `lengthBefore` / `lengthAfter`。
398
-
399
- **返回：** `ok` / `applied` / `verified` / `errorCode` / `message` / `lengthBefore` / `lengthAfter` / `diff` / `ops[]`。其中 `ops[].message` 说明失败原因，`NOT_FOUND` 时 `ops[].suggestions` 给出最相似的候选（行号 + 相似度 + 预览），`diff` 只回改动片段、不回整份脚本。
400
-
401
- **匹配与容错：** 默认 `normalized` 模式会先做归一化再匹配（CRLF/CR 统一为 LF、忽略行尾空白），并把 `newString` 的换行符统一成源脚本的主导换行符，避免混用。`oldString` 未命中 / 命中多处时分别报 `NOT_FOUND` / `NOT_UNIQUE` 并整批中止。partial 模式下 `oldString` 为空串报 `EMPTY_OLD_STRING`（整份重写请改用 `rewrite: true`）。
402
-
403
- **失败即关闭：** 成功后重复调用同一 `oldString` 会因原文已不存在而报 `NOT_FOUND`，不会重复写入。
404
-
405
- ### `page_entity_list` — 分页查询实体列表
406
-
407
- 根据查询条件分页查询 APaaS 平台中的实体定义（只读、幂等）。底层调用 `entityClient.pageEntityList`。
408
-
409
- **输入参数：**
410
-
411
- | 参数 | 类型 | 必填 | 说明 |
412
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
413
- | `objectname` | string | 否 | 实体中文名、实体表名、实体 objectcode，模糊匹配 |
414
- | `page` | string | 否 | 当前页，从 1 开始，默认 1 |
415
- | `rows` | string | 否 | 每页记录数，默认 20 |
416
- | `updatetimestart` | string | 否 | 修改开始时间，格式 `yyyy-MM-dd hh:mm:ss`，与结束时间成对出现 |
417
- | `updatetimeend` | string | 否 | 修改结束时间，格式 `yyyy-MM-dd hh:mm:ss`，与开始时间成对出现 |
418
- | `datapattern` | string | 否 | 实体类型（整数）：1-原生实体；2-衍生实体；3-视图；4-超级表单实体 |
419
- | `objecttypecode`| string | 否 | 实体分类（整数）：1-基本实体；2-树形实体；3-数据字典；4-关联实体 |
420
-
421
- **返回：** 实体列表的 JSON（`resp_data`），包含分页信封 `pageCount` / `pageIndex` / `pageSize` / `resultCount`，以及 `data` 数组中每个实体的基本信息：`objectcode`、`objectname`、`objectmark`、`tablename`、`directorytypename`、`datapattern`、`publishstatus`、`status`、`marktype`、`confsource`、`createaccountname`、`updateaccountname`、`createtime`、`updatetime` 等。
422
-
423
- > 注：接口另有固定默认参数（`centercode`、`directorytypecode`、`starttime`），已在工具内部硬编码传入，不对外暴露。
424
-
425
- ### `get_entity` — 查询实体详情
426
-
427
- 根据实体的编码 `objectcode` 查询其完整详情（只读、幂等），包含实体的基本信息与属性数组 `properties`（每个属性的列名、类型、关联实体、索引方式等）。底层调用 `entityClient.getEntity`。
428
-
429
- **输入参数：**
430
-
431
- | 参数 | 类型 | 必填 | 说明 |
432
- | ----------- | ------ | ---- | -------------------------- |
433
- | `objectcode` | string | 是 | 要查详情的实体的编码 |
434
-
435
- **返回：** 实体详情的 JSON（`resp_data`），主要字段：
436
-
437
- - `objectcode` / `objectname` / `objectmark` / `tablename` / `metamodelcode`：实体编码、中文名、标记、数据库表名、领域模型编码
438
- - `objectdescr` / `objecttypecode` / `datapattern` / `directorytypecode`：描述、实体分类、数据模式、所属目录编码
439
- - `marktype` / `confsource` / `publishstatus` / `status` / `storagelevel`：创建标记、配置来源、发布状态、状态、存储等级
440
- - `parentobjectcode`：父实体的 objectcode
441
- - `message`：保存时编写的提交信息（作用类似 git 提交信息）
442
- - `properties`：实体属性数组，每个属性含 `propertyname` / `columnname` / `propertytypecode`（字段类型映射）/ `relationobjectcode`（关联实体）/ `idxtype`（索引方式）/ `publishstatus` / `status` 等
443
-
444
- ### `page_entity_directories` — 分页查询实体所属目录
445
-
446
- 根据目录名等条件查询 APaaS 平台中的实体目录（只读、幂等）。底层调用 `entityClient.pageDirectories`（接口 `POST /bizserv/biz/getDirectorys`，与表单目录同源，实体传 `directorycategory: "1"`）。返回的 `directorytypecode` 即 `create_entity` 的 `directorytypecode` 必填入参。
447
-
448
- **输入参数：**
449
-
450
- | 参数 | 类型 | 必填 | 说明 |
451
- | ------------- | ------ | ---- | -------------------------------------------------------------------------- |
452
- | `keys` | string | 否 | 目录名称模糊匹配（建议优先用它检索，避免拉全量） |
453
- | `directorytypecode` | string | 否 | 目录编码精确匹配 |
454
- | `parentdirectorytypecode` | string | 否 | 父目录编码精确匹配；传 `"root"` 只看顶级目录 |
455
- | `centername` / `centercode` | string | 否 | 所属业务中心名称 / 编码模糊或精确匹配 |
456
- | `marktype` | string | 否 | 创建标记精确匹配：0-平台；1-产品；2-租户 |
457
- | `limit` | string | 否 | 返回条数上限，默认 30，硬上限 200 |
458
- | `offset` | string | 否 | 起始偏移，默认 0；配合 `limit` 翻页 |
459
-
460
- **返回：** 实体目录列表的 JSON（`items`），含 `directorytypecode` / `directorytypename` / `parentdirectorytypecode` / `marktype` 等，以及 `total` / `truncated` / `hint` 收敛提示。该接口不支持分页（全量数百条），工具已在服务层强制收敛。
461
-
462
- ### `create_entity` — 新增实体（数据表）
463
-
464
- 新增一张数据表（实体），仅传入必要参数，完整实体对象由 MCP 侧组装后调平台保存接口（非只读、有事务性保护）。底层调用 `service/entity.ts` 的 `createEntity`：构造实体骨架（`datapattern` 固定 `"1"`、自动补主键、非字典实体可选初始字段）→ 一次性保存到 `POST /bizserv/biz/saveObject`。
465
-
466
- **输入参数：**
467
-
468
- | 参数 | 类型 | 必填 | 说明 |
469
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
470
- | `objectname` | string | 是 | 实体中文名 |
471
- | `objecttypecode`| string | 是 | 实体分类：1-基本对象；2-树型对象；3-数据字典；4-关联对象 |
472
- | `tablename` | string | 是 | 数据库表名；`objectmark` 自动复制此值 |
473
- | `directorytypecode` | string | 是 | 所属目录编码，来自 `page_entity_directories` 查询到的 `directorytypecode` |
474
- | `parentobjectcode` | string | 否 | 父实体编码，树型 / 关联实体使用 |
475
- | `propertydescr` | string | 否 | 实体描述 |
476
- | `initialFields` | array | 否 | 可选初始字段（每项仅 `propertyname` / `propertytypecode` / `columnname` 必填）；数据字典忽略此参数。非字典实体若未提供主键（`propertytypecode=1`），MCP 会自动补一个「主键 / id」 |
477
- | `commitMessage` | object | 是 | 提交信息，结构与 `save_model_logic` 的 `commitMessage` 一致 |
478
- | `confirm` | boolean | 否 | 是否确认落库，默认 `false`。必须显式 `true` 才会真正保存 |
479
- | `dryRun` | boolean | 否 | 是否仅预览不落库，默认 `true`。置 `false` 才执行保存（需配合 `confirm=true`） |
480
- | `verify` | boolean | 否 | 保存后是否回读校验，默认 `true` |
481
-
482
- **返回：** `{ ok, applied, verified, errorCode, message, diff, publishStatus, needManualPublish, entityCode, entityName }`。`publishStatus` 实体级固定 `2`（数据字典为 `1`）；`needManualPublish` 为 `true` 时提示需到平台手动发布。
483
-
484
- > **写操作有风险，默认先预览后确认**：`confirm=false` + `dryRun=true` 时只回一份「将要创建什么」的预览（`errorCode: "DRY_RUN"`），确认无误后再以 `confirm=true`、`dryRun=false` 真正落库。保存后实体处于「未发布」态（数据字典除外），需到平台手动点发布才会真正改表结构。
485
- >
486
- > 数据字典（`objecttypecode=3`）字段由平台预置，创建时 `properties` 强制为空、忽略 `initialFields`，且 `publishstatus=1` 已发布。
487
-
488
- ### `patch_entity` — 给已有实体加字段（patch ops，当前仅 `add_field`）
489
-
490
- 对已有实体做字段级修改，当前仅实现 `add_field`（新增字段），其余字段级 op 保留未实现。完整对象由 MCP 侧按 ops 在内存副本上预演、再整体保存到 `POST /bizserv/biz/saveObject`（非只读、有事务性保护）。底层调用 `service/entity.ts` 的 `patchEntity`。
491
-
492
- **输入参数：**
493
-
494
- | 参数 | 类型 | 必填 | 说明 |
495
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
496
- | `objectcode` | string | 是 | 目标实体的编码 |
497
- | `ops` | array | 是 | 字段操作数组，至少一个元素；按数组顺序事务性执行，任一失败整批回滚。仅 `add_field` 已实现 |
498
- | `commitMessage` | object | 是 | 提交信息，整批 ops 共用一个；结构与 `save_model_logic` 的 `commitMessage` 一致 |
499
- | `confirm` | boolean | 否 | 是否确认落库，默认 `false`。必须显式 `true` 才会真正保存 |
500
- | `dryRun` | boolean | 否 | 是否仅预览不落库，默认 `true`。置 `false` 才执行保存（需配合 `confirm=true`） |
501
- | `verify` | boolean | 否 | 保存后是否回读校验，默认 `true` |
502
-
503
- `ops[]` 元素（`op` 判别联合）：
504
-
505
- | `op` | 必填载荷 | 说明 |
506
- | --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
507
- | `add_field` | `propertyname` / `propertytypecode` / `columnname`（均必填）+ 可选 `propertydescr` / `idxtype` / 关联属性 | 新增一个字段（`columnname` 为数据库列名）；事务性预演通过后才落库 |
508
- | `modify_field` | `propertycode` + `patch` | **保留未实现**：传入会直接失败并提示「修改 / 删除字段请让用户到 IDE 平台手动操作」 |
509
- | `delete_field` | `propertycode` | **保留未实现**：同上，运行时拒绝 |
510
-
511
- > **写操作有风险，默认先预览后确认**：同 `create_entity`，`confirm=false` + `dryRun=true` 仅预览；保存后处于未发布态、需手动发布。
512
- >
513
- > **数据字典不允许调整字段**：数据字典（`objecttypecode=3`）字段由平台预置，传入 `add_field` / `modify_field` / `delete_field` 任一均会失败并提示「数据字典不允许调整字段」。
514
-
515
- **返回：** `{ ok, applied, verified, errorCode, message, diff, ops[] }`，`ops[]` 与入参一一对应，便于定位失败项。
516
-
517
- ### `page_form_list` — 分页查询表单 / 页面列表
518
-
519
- 根据查询条件分页查询 APaaS 平台中的表单 / 页面定义（只读、幂等）。底层调用 `formClient.pageFormList`（接口 `POST /bizserv/bizpage/pageList`）。
520
-
521
- **输入参数：**
522
-
523
- | 参数 | 类型 | 必填 | 说明 |
524
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
525
- | `status` | string | 否 | 状态（整数）：1-启用；2-停用。示例传 `"1"` |
526
- | `keys` | string | 否 | 模糊匹配表单 `code` / `title` |
527
- | `keywords` | string | 否 | 模糊匹配表单中的关键词 |
528
- | `clientcategorycode` | string | 否 | 用户端分类编码：1-web 端；2-app 端；6-小程序端 |
529
- | `page` | string | 否 | 当前页，从 1 开始，默认 1 |
530
- | `rows` | string | 否 | 每页记录数，默认 20 |
531
- | `type` | string | 否 | 类型（整数）：5-列表查询；1-普通页面；99-二开页面；10-switchpage；11-树导航列表；100-原生页面；101-空白页面；7-报表页面；12-排序页面；300-步骤管理表单；1000-全局函数 |
532
- | `updateopname` | string | 否 | 最近修改人姓名，模糊匹配 |
533
- | `updatetimestart` | string | 否 | 修改开始时间，格式 `yyyy-MM-dd hh:mm:ss`，与结束时间成对出现 |
534
- | `updatetimeend` | string | 否 | 修改结束时间，格式 `yyyy-MM-dd hh:mm:ss`，与开始时间成对出现 |
535
-
536
- **返回：** 表单 / 页面列表的 JSON（`resp_data`），包含分页信封 `pageCount` / `pageIndex` / `pageSize` / `resultCount`，以及 `data` 数组中每个表单 / 页面的基本信息。`code` 为必填字段，其余字段（如 `createtime`、`title`、`clientcategorycode`、`confsource`、`marktype`、`directorytypename`、`metamodelcode`、`pagetypename`、`pagedescr`、`status`、`type`、`updatetime`、`updateaccountname`、`versionnum` 等）均为可选，且值可能为 `null`。
537
-
538
- > 注：接口另有固定默认参数（`centercode`、`directorytypecode`、`starttime`），已在工具内部硬编码传入，不对外暴露。
539
-
540
- ### `get_form` — 查询表单 / 页面详情
541
-
542
- 根据表单 / 页面的唯一编码 `code` 获取其完整详情（只读、幂等）。底层调用 `formClient.getForm`（接口 `POST /bizserv/bizpage/getPage`）。
543
-
544
- **输入参数：**
545
-
546
- | 参数 | 类型 | 必填 | 说明 |
547
- | ----- | ------ | ---- | -------------------------- |
548
- | `code` | string | 是 | 要查详情的表单 / 页面的唯一编码 |
549
-
550
- **返回：** 表单 / 页面详情的 JSON（`resp_data`），结构为顶层对象 `FormResult`，主要字段：
551
-
552
- - `pageinfo`：页面基础信息（`code` / `title` / `type` / `status` / `marktype` / `clientcategorycode` / `versionnum` / `pagetemplatecode` / `pagedescr` 等；`eventlist` 页面级事件、`reportdesclist` 关联报表、`cache` 缓存配置）
553
- - `businessmodel`：引用的后端业务模型 / 接口数组，结构同 `logicClient` 的 `LogicResult`（`actiontype` / `modelcode` / `modellogiccode` / `input` / `output` / `operations` 等）
554
- - `presenter`：事件处理器（`initial` 初始化 / `interface` 对外接口 / `handlers` 事件处理器），每项含 `code` / `key` / `condition` / `actions`
555
- - `view`：页面结构，递归的控件节点树；每个节点 `type` 为控件种类判别符（`layout` / `report` / `datagrid` / `textinput` / `button` / `table` / `select` / `checkbox` / `upload` 等），`content` 为递归子节点数组
556
- - `controls`：扁平控件数组（部分页面才有）
557
- - `pageswitch`：仅 switchpage 类型才有的页面切换配置（`mode` / `menu` / `pagerefs` / `eventlist`）
558
- - `message`：每次保存填写的提交信息（类似 git 提交信息）
559
-
560
- > 注：工具的 `description` 中附有「字段速查」，列出了各顶层对象的关键字段与编码枚举含义（如 `pageinfo.type` 页面类型、`marktype` 创建标记、`clientcategorycode` 用户端等），便于理解返回 JSON。详情类型的字段定义见 `src/clients/form.ts`（`FormResult` / `FormPageInfo` / `FormViewNode` / `FormControl` 等接口）。
561
-
562
- ### `get_form_outline` — 查询表单 / 页面骨架
563
-
564
- 获取表单 / 页面的轻量骨架（地址簿 / 决策依据），约 2–4KB，避免为日常改动拉取完整 88KB 的表单 JSON（只读、幂等）。底层调用 `service/form.ts` 的 `getFormOutline`。
565
-
566
- **输入参数：**
567
-
568
- | 参数 | 类型 | 必填 | 说明 |
569
- | ------ | ------ | ---- | -------------------------------- |
570
- | `code` | string | 是 | 要查骨架的表单 / 页面的唯一编码 |
571
-
572
- **返回：** `pageinfo` 关键字段、`viewTree`（递归骨架，仅 `code` / `type` / `title` + `children`）、`handlers` 与 `interfaces` 清单、`businessModels`（仅逻辑名，不回内容）。
573
-
574
- `handlers` 清单同时覆盖 `presenter.handlers`（事件处理器）与 `presenter.initial`（页面初始化处理器），每项带 `scope` 字段标注所在容器（`handlers` / `initial`）。
575
-
576
- > 用途：在不知道全量内容时先拿到所有可改对象的 `code`，避免 `NODE_NOT_FOUND` 盲猜；随后用 `get_form_fragment` 看局部真实属性名，再用 `patch_form` 修改。
577
- >
578
- > 注意：页面初始化的 flycode 常位于 `presenter.initial`（`code` 形如 `initial_xxx_event`），outline 会一并列出并标注 `scope='initial'`，不要只按 `handlers` 找。
579
-
580
- ### `get_form_fragment` — 查询表单 / 页面局部内容
581
-
582
- 按 `code` 取表单的局部内容（几 KB），避免为改一处而拉完整 88KB 表单 JSON（只读、幂等）。三种寻址方式三选一，可组合。底层调用 `service/form.ts` 的 `getFormFragment`。
583
-
584
- **输入参数：**
585
-
586
- | 参数 | 类型 | 必填 | 说明 |
587
- | ------------- | ------ | ---- | ------------------------------------------------------------------------------- |
588
- | `code` | string | 是 | 表单 / 页面的唯一编码 |
589
- | `nodeCode` | string | 否 | 目标控件 / 节点编码，返回其完整子树 |
590
- | `handlerCode` | string | 否 | 目标 presenter 处理器编码（`handlers` 与 `initial` 均检索），返回其完整定义与 `actionIndex` 清单 |
591
- | `handlerScope` | string | 否 | 限定处理器容器 `handlers` / `initial`；同名 code 跨容器时须指定以消歧 |
592
- | `section` | string | 否 | 整段 `pageinfo` / `view` / `presenter` / `controls` / `pageswitch` / `businessmodel` |
593
-
594
- **返回：** 命中的 `node` / `handler` / `section`，以及 `actionIndex`（每个 action 的 `code` / `type` 与 `script` / `condition` / `expression` 长度），便于精确构造 `patch_form` 的 `replace_script`。同名 `code` 跨 `handlers` / `initial` 出现时 `handler` 为 `undefined`，并在 `message` 中提示加 `handlerScope` 消歧。
595
-
596
- ### `patch_form` — 局部补丁修改表单 / 页面
597
-
598
- 以结构化补丁（delta ops）局部修改表单 / 页面，**无需回传完整 88KB 的表单 JSON**（非只读、有事务性保护）。底层调用 `service/form.ts` 的 `patchForm`：先拉取最新完整对象 → 在内存副本上按 `ops` 顺序合并 → 一次性保存到 `POST /biserv/bizpage/saveNewPage`。
599
-
600
- **输入参数：**
601
-
602
- | 参数 | 类型 | 必填 | 说明 |
603
- | --------------- | ------- | ---- | --------------------------------------------------------- |
604
- | `code` | string | 是 | 目标表单 / 页面的唯一编码 |
605
- | `ops` | array | 是 | 补丁操作数组，至少一个元素；10 类见下表，按数组顺序依次作用 |
606
- | `commitMessage` | object | 是 | 提交信息，结构与 `save_model_logic` 的 `commitMessage` 一致 |
607
- | `dryRun` | boolean | 否 | 只预演输出 diff、不落库，默认 `false` |
608
- | `verify` | boolean | 否 | 保存后回读校验改动是否生效，默认 `true` |
609
-
610
- **11 类 ops：**
611
-
612
- | op | 关键参数 | 说明 |
613
- | ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- |
614
- | `set_pageinfo` | `patch` | 浅合并进 pageinfo（如改标题 / 状态） |
615
- | `set_attrs` | `code`、`patch`、`overwriteArray?` | 按 `code` 定位节点，浅合并**标量**属性（如 `hidden` / `required`）；`patch` 含数组属性时默认**阻断**（报 `ARRAY_OVERWRITE_BLOCKED`），需显式 `overwriteArray:true` 才整段覆盖（避免误改丢列）；action 结构请用 `patch_action_array_item` |
616
- | `patch_node_array_item`| `nodeCode`、`arrayProp`、`mode?`、`itemKey?`、`itemKeyValue?`、`item?`、`position?`、`patch?`、`elementArrayProp?`、`elementItemKey?`、`elementItemKeyValue?`、`createIfMissing?` | 按 `nodeCode`+`arrayProp` 定位节点内数组；`mode` 默认 `merge`（按 `itemKey` 浅合并单个元素，如只改某列 `options`），另支持 `append`/`insert`/`remove`；`elementArrayProp` 支持钻到「数组内元素的嵌套数组」（如 `cols[colCode].options`）。目标数组缺失时默认 `ARRAY_NOT_FOUND` 阻断（`createIfMissing:true` 才新建），`remove` 清空调自动删属性避免空壳 |
617
- | `patch_action_array_item`| `handlerCode`、`actionIndex?`/`actionCode?`、`scope?`、`parentProp?`、`arrayProp`、`mode`、`itemKey?`、`itemKeyValue?`、`item?`、`position?`、`patch?`、`elementArrayProp?`、`elementItemKey?`、`elementItemKeyValue?`、`createIfMissing?` | 改 presenter.handlers/initial 中某 action 内部数组（如 `datarequest.setter` 绑定「界面输出→控件 code」、`param.properties`）；`mode` 支持 `merge`/`append`/`insert`/`remove`。**把状态输出绑定到新控件只需传一条新 setter**；真实绑定若在嵌套数组（如 `setter[0].properties` 模型级属性映射），用 `itemKey`/`itemKeyValue` 定位外层元素 + `elementArrayProp` 钻进去即可，无需内联整段 setter；目标数组缺失默认 `ARRAY_NOT_FOUND` 阻断 |
618
- | `insert_node` | `parentCode`、`node`、`position?` | 在父节点下插入新节点 |
619
- | `remove_node` | `code`、`checkRefs?` | 按 `code` 删除节点，默认校验引用 |
620
- | `move_node` | `code`、`newParentCode`、`position?` | 移动节点到新父节点下 |
621
- | `set_section` | `section`、`value` | 整段替换 `view` / `presenter` / `controls` / `pageswitch` |
622
- | `replace_script` | `handlerCode`、`actionIndex?` / `actionCode?`、`field?`、`scope?`、`replacement?` / `ops?` | 改 action 的 `script` / `condition` / `expression`，支持整段覆盖或 old→new 局部替换；`handlerCode` 在 `handlers` 与 `initial` 两块容器中均会检索，`scope` 用于同名 code 跨容器消歧 |
623
- | `add_businessmodel` | `modellogiccode`、`overwrite?` | 仅给逻辑编码，MCP 自动拉取其完整 JSON 追加到 `businessmodel` |
624
- | `remove_businessmodel` | `modellogiccode`、`checkRefs?` | 从 `businessmodel` 移除指定逻辑 |
625
-
626
- **事务性：** 全部 `op` 预演成功才会落库，任一 `op` 失败（`NODE_NOT_FOUND` / `DUP_CODE` / `REF_VIOLATION` / `FETCH_FAILED`）则整批中止、零写入回滚；整批只发起一次保存请求，不存在写一半的中间态。
627
-
628
- **返回：** `ok` / `applied` / `verified` / `errorCode` / `message` / `diff` / `ops[]`，其中 `ops[].suggestions` 在 `NOT_FOUND` 时给出相似候选。
629
-
630
- > 错误码：`OK` / `DRY_RUN` / `EMPTY_OPS` / `FETCH_FAILED` / `NODE_NOT_FOUND` / `DUP_CODE` / `REF_VIOLATION` / `OPS_FAILED` / `SAVE_FAILED` / `VERIFY_FAILED`。
631
-
632
- > **回读校验口径**：平台普遍把脚本按 CRLF（`\r\n`）落库，而提交的 `oldString` / `newString` 多为 LF。回读校验与写入侧共用 `matchMode`（默认 `normalized`）的归一化口径，**仅容忍换行符与行尾空白差异**，内容不同依旧如实报 `VERIFY_FAILED`。因此 `applied:true` + `verified:false` 且报错为「新内容未出现」时，应先用 `get_form_fragment` 实际回读确认，不要仅凭该错误码重复提交；若确需字节严格校验，给对应 op 设 `matchMode:'exact'`。
633
-
634
- ### `save_form` — 全量保存表单 / 页面
635
-
636
- 整页重构（重排布局、模板迁移等）时没有其他表达方式，才用本工具：把从 `get_form` 查询到的完整 `FormResult` 对象按需修改后整份回传保存（非只读）。底层调用 `service/form.ts` 的 `saveForm` → `POST /biserv/bizpage/saveNewPage`。日常局部改动请优先用 `patch_form`。
637
-
638
- **输入参数：**
639
-
640
- | 参数 | 类型 | 必填 | 说明 |
641
- | --------------- | ------ | ---- | -------------------------------------------------------------- |
642
- | `form` | object | 是 | 完整的 `FormResult` 对象，通常来自 `get_form` 的返回，改后回传 |
643
- | `commitMessage` | object | 是 | 提交信息，结构与 `save_model_logic` 的 `commitMessage` 一致 |
644
-
645
- **返回：** `ok` / `code` / `message`。
646
-
647
- > 注：保存接口 `conf` / `ui` 要求传入完整对象，故 `businessmodel`（完整 `LogicResult[]`）**原样透传、不剥离**；`message` 作为顶层提交参数传入，不是 `FormResult` 内部的 `message` 字段。服务端按 `overwrite: false` 保存（不覆盖他人最新版本），`clearuserconfig` 默认 `true`。
648
-
649
- ### `page_h5_form` — 分页查询 H5 表单列表
650
-
651
- 根据查询条件分页查询智慧100 H5 引擎配置的 H5 表单列表（只读、幂等）。底层调用 `h5Client.pageH5List`（接口 `POST /api/masterserv/hpage/listH5Page`）。
652
-
653
- > 说明：列表结果**不包含** `confjson` 字段（该字段为 H5 表单的内容 JSON，体积较大）；如需获取表单的 `confjson`（含 Vue 代码与元数据配置），请调用 `get_h5_form` 获取详情。
654
-
655
- **输入参数：**
656
-
657
- | 参数 | 类型 | 必填 | 说明 |
658
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
659
- | `keywords` | string | 否 | H5 表单代码及其元数据中包含的关键字，模糊匹配 |
660
- | `pagecode` | string | 否 | H5 表单的唯一编码，模糊匹配 |
661
- | `status` | string | 否 | 状态，整数：1-启用；2-停用。示例传 `"1"` |
662
- | `title` | string | 否 | H5 表单的标题，模糊匹配 |
663
- | `updateopname` | string | 否 | 最近修改人姓名，模糊匹配 |
664
- | `page` | string | 否 | 当前页，从 1 开始，默认 1 |
665
- | `rows` | string | 否 | 每页记录数，默认 20 |
666
-
667
- **返回：** H5 表单列表的 JSON（`resp_data`），包含分页信封 `pageCount` / `pageIndex` / `pageSize` / `resultCount`，以及 `data` 数组中每个 H5 表单的基本信息：`pagecode`（唯一编码）/ `title`（标题）/ `status`（状态：1-启用；2-停用）/ `pagedescr`（描述）/ `platstatus`（平台状态）/ `platcreateop` / `platcreatetime` / `platupdateop` / `platupdatetime` 等。字段值可能为 `null`，且 `status` 以字符串或数字两种形态返回。
668
-
669
- > 注：当接口返回数据包含 `HTTP 404 Not Found` 时，说明此租户未安装 H5 引擎。该工具以宽松结构（`catchall`）透传服务端返回的额外字段，确保任意列表结果均可正常返回。字段定义见 `src/clients/h5.ts`（`H5PageResult` 接口）。
670
-
671
- ### `get_h5_form` — 查询 H5 表单详情
672
-
673
- 根据 H5 表单的唯一编码 `pagecode` 获取其完整详情（只读、幂等），核心内容 `confjson` 为 H5 表单的内容 JSON（含 Vue 代码与元数据配置）。底层调用 `h5Client.getH5`（接口 `POST /api/masterserv/hpage/listH5PageByOne`）。
674
-
675
- **输入参数：**
676
-
677
- | 参数 | 类型 | 必填 | 说明 |
678
- | ---------- | ------ | ---- | -------------------------- |
679
- | `pagecode` | string | 是 | 要查详情的 H5 表单的唯一编码 |
680
-
681
- **返回：** H5 表单详情的 JSON（`resp_data`），主要字段：
682
-
683
- - `pagecode` / `title` / `pagedescr`：H5 表单唯一编码、标题、描述
684
- - `status`：状态（1-启用；2-停用），以字符串或数字返回
685
- - `confjson`：H5 表单的内容 JSON 字符串，包含 H5 表单的 Vue 代码与元数据配置（核心内容）
686
- - `platcreateop` / `platcreatetime`：创建人 / 创建时间
687
- - `platupdateop` / `platupdatetime`：最近更新人 / 最近更新时间
688
- - `platstatus`：平台状态
689
-
690
- > 注：当接口返回数据包含 `HTTP 404 Not Found` 时，说明此租户未安装 H5 引擎。详情类型的字段定义见 `src/clients/h5.ts`（`H5PageResult` 接口）。H5 查询接口需要以特定预览账号（职位为 `SFA系统管理员`）的 token 发起，该鉴权细节由 `service/h5.ts` 自动解析，调用方无需关心。
691
-
692
- ### `page_function_list` — 分页查询 flycode 函数列表
693
-
694
- 根据查询条件分页查询 APaaS 平台中的 flycode 函数定义（只读、幂等）。底层调用 `functionClient.pageFunctionList`（接口 `POST /bizserv/bizmodel/pageList`）。
695
-
696
- **输入参数：**
697
-
698
- | 参数 | 类型 | 必填 | 说明 |
699
- | ------------- | ------ | ---- | -------------------------------------------------------------------------- |
700
- | `classname` | string | 否 | 函数英文名 |
701
- | `name` | string | 否 | 函数中文名，通常和 `modelname` 一致 |
702
- | `modelname` | string | 否 | 函数中文名，通常和 `name` 一致 |
703
- | `flycodekey` | string | 否 | 函数内容关键字，模糊匹配 |
704
- | `page` | string | 否 | 当前页，从 1 开始，默认 1 |
705
- | `rows` | string | 否 | 每页记录数，默认 20 |
706
-
707
- **返回：** flycode 函数列表的 JSON（`resp_data`），包含分页信封 `pageCount` / `pageIndex` / `pageSize` / `resultCount`，以及 `data` 数组中每个函数的基本信息：`classname`（函数英文名）/ `modelname`（函数中文名）/ `modeldescr`（函数描述）/ `modelcode`（函数编码）/ `metamodelcode`（领域模型编码）/ `dddlayer`（函数层级，固定 3）/ `marktype`（创建标记：0-平台；1-产品；2-租户）/ `status`（状态：1-启用；2-停用）/ `tablename` / `createtime` / `updatetime` / `createaccountname` / `updateaccountname` 等。字段值可能为 `null`，且 `marktype` / `status` / `dddlayer` 等部分字段以数字或字符串两种形态返回。
708
-
709
- > 注：接口另有固定默认参数（`dddlayer` 固定传 3、`directorytypecode`、`starttime`），已在工具内部硬编码传入，不对外暴露。
710
-
711
- ### `get_function` — 查询 flycode 函数详情
712
-
713
- 根据函数的编码 `modelcode` 查询其完整详情（只读、幂等），包含函数的基本信息与 flycode 函数代码内容 `confjson`。底层调用 `functionClient.getFunction`（接口 `POST /bizserv/bizmodel/get`）。
714
-
715
- **输入参数：**
716
-
717
- | 参数 | 类型 | 必填 | 说明 |
718
- | ----------- | ------ | ---- | -------------------------- |
719
- | `modelcode` | string | 是 | 要查详情的函数的编码 |
720
-
721
- **返回：** flycode 函数详情的 JSON（`resp_data`），主要字段：
722
-
723
- - `classname` / `modelname` / `modeldescr` / `modelcode` / `metamodelcode`：函数英文名、中文名、描述、编码、领域模型编码
724
- - `dddlayer`：函数层级，固定为 3
725
- - `marktype` / `status`：创建标记（0-平台；1-产品；2-租户）、状态（1-启用；2-停用）
726
- - `tablename` / `createtime` / `updatetime` / `createaccountname` / `updateaccountname`：数据库表名（函数一般无对应表，通常为空）、时间戳与创建 / 更新人
727
- - `confjson`：flycode 函数代码内容，是函数实现体的核心字段
728
-
729
- > 注：详情接口返回结构不稳定（部分字段调用时可能缺省），工具以宽松结构（`z.looseObject`）透传服务端返回的额外字段，确保任意详情均可正常返回。字段定义见 `src/clients/function.ts`（`FunctionResult` / `FunctionPageResult` 接口）。
730
-
731
- ### `page_database_function_list` — 分页查询数据库函数列表
732
-
733
- 根据查询条件分页查询 APaaS 平台中的 PostgreSQL 自定义数据库函数定义（只读、幂等）。底层调用 `databaseFunctionClient.pageDatabaseFunctionList`（接口 `POST /bizserv/customfunction/list`）。
734
-
735
- > 说明：数据库函数的函数体 `functionscript`（PostgreSQL 函数体）已在列表查询中随行返回，因此该工具**只提供列表查询**，无需单独的详情查询工具。
736
-
737
- **输入参数：**
738
-
739
- | 参数 | 类型 | 必填 | 说明 |
740
- | --------------- | ------ | ---- | -------------------------------------------------------------------------- |
741
- | `dbfunctionname`| string | 否 | 数据库函数名，模糊匹配 |
742
- | `name` | string | 否 | 函数中文名，模糊匹配 |
743
- | `pageindex` | string | 否 | 当前页，从 1 开始，默认 1 |
744
- | `pagesize` | string | 否 | 每页记录数，默认 20 |
745
-
746
- **返回：** 数据库函数列表的 JSON（`resp_data`），包含分页信封 `pageCount` / `pageIndex` / `pageSize` / `resultCount`，以及 `data` 数组中每个数据库函数的基本信息：`dbfunctionname`（数据库函数名）/ `functionname`（函数中文名）/ `functioncode`（函数唯一编码）/ `functionscript`（数据库函数内容，PostgreSQL 函数体，列表随行返回）/ `metamodelcode`（领域模型编码）/ `marktype`（创建标记：0-平台；1-产品；2-租户）/ `publishstatus`（发布状态：1-已发布；2-未发布）/ `status`（状态：1-启用；2-停用）/ `creator` / `updator` / `createtime` / `updatetime` / `remark` 等。字段值可能为 `null`，且 `marktype` / `publishstatus` / `status` 等部分字段以数字或字符串两种形态返回。
747
-
748
- > 注：返回的 `data` 为服务端实际结构透传，工具以宽松结构（`catchall`）保留服务端返回的额外字段，确保任意列表结果均可正常返回。字段定义见 `src/clients/database-function.ts`（`DatabaseFunctionPageParams` / `DatabaseFunctionPageResult` 接口）。
749
-
750
- ### `run_sql` — 执行 SQL 查询
751
-
752
- 在业务库中执行一条 SELECT 查询 SQL（只读、幂等），直接探查业务表数据、核对字段值、验证同步结果等。底层调用 `runClient.sqlRun`（接口 `POST /api/biz/sqlrun`）。
753
-
754
- **输入参数：**
755
-
756
- | 参数 | 类型 | 必填 | 说明 |
757
- | ----- | ------ | ---- | -------------------------------------------------------------------------- |
758
- | `sql` | string | 是 | 要执行的 SQL 查询语句，只支持 SELECT 查询，一次只能一条 SQL |
759
-
760
- **返回：** 查询结果的 JSON（`resp_data`），主要字段：
761
-
762
- - `data`：查询结果数据，数组中的每一项为一条查询结果记录（对象）；查询无结果时为 `null` 或空数组
763
- - `influenceCount`：查询结果总数（数值）
764
-
765
- > 注：接口仅支持 SELECT 查询，不支持 INSERT / UPDATE / DELETE 等写操作。返回的 `data` 行结构不可预知，工具以宽松结构透传，确保任意查询结果均可正常返回。
766
-
767
- ### `generate_unique_code` — 生成唯一编码
768
-
769
- 通过雪花算法（`src/utils/snowflake.ts`）生成一个全局唯一 ID（code）。在新建实体、领域、表单等内容时，其 JSON 字段中通常需要携带一个唯一 `code`（如实体的 `objectcode`、表单的 `code` 等），可调用本工具获取并填入。底层直接调用 snowflake 实例的 `nextId()`。
770
-
771
- **输入参数：**
772
-
773
- | 参数 | 类型 | 必填 | 说明 |
774
- | ------- | ------ | ---- | ---------------------------------------------------------------------------- |
775
- | `prefix`| string | 否 | 可选前缀，拼接到生成的唯一 ID 之前（例如实体编码前缀）；不传则只返回纯数字 ID 字符串 |
776
-
777
- **返回：** 一个 JSON 对象 `{ "code": "..." }`：
778
-
779
- - `code`：生成的唯一编码。以**字符串**形式返回，避免雪花 ID 超过 `Number.MAX_SAFE_INTEGER` 时的大整数精度丢失。
780
-
781
- > 注：本工具仅在本地生成 ID，**不修改任何服务端数据**，且每次调用返回不同的 ID（非幂等）。如需带固定前缀的编码（如 `kx_877483974950260736`），传入 `prefix` 即可。
105
+ ## 工具
106
+
107
+ 1. 实体类工具
108
+ - `page_entity_list`：查实体列表
109
+ - `get_entity`：查实体详情
110
+ - `page_entity_directories`：查实体目录列表
111
+ - `create_entity`：新增实体
112
+ - `patch_entity`：改实体（**指令式**，非全量回传，降上下文）
113
+
114
+ 2. 领域类工具
115
+ - `page_model_logic_directories`：查领域目录列表
116
+ - `page_model_logic_list`：查领域列表
117
+ - `get_model_logic`：查领域详情与脚本
118
+ - `save_model_logic`：全量保存领域
119
+ - `patch_model_logic`：局部改领域结构（**指令式**，非全量回传，降上下文）
120
+ - `str_replace_flycode`：局部替换脚本片段（**指令式**，非全量回传，降上下文）
121
+
122
+ 3. 表单类工具
123
+ - `page_form_directories`：查表单目录列表
124
+ - `page_form_list`：查表单列表
125
+ - `get_form`：查表单完整详情
126
+ - `get_form_outline`：查表单骨架（替代全量回传降上下文）
127
+ - `get_form_fragment`：查表单局部内容（替代全量回传降上下文）
128
+ - `patch_form`：局部修改表单（**指令式**，非全量回传，降上下文）
129
+ - `save_form`：全量保存表单
130
+
131
+ 4. `flycode` 函数类工具
132
+ - `page_function_list`：查函数列表
133
+ - `get_function`：查函数详情与代码
134
+
135
+ 5. 数据库函数类工具
136
+ - `page_database_function_list`：查数据库函数列表
137
+
138
+ 6. H5 表单工具
139
+ - `page_h5_form`：查 H5 表单列表
140
+ - `get_h5_form`：查 H5 表单详情
141
+
142
+ 7. 执行类工具
143
+ - `run_sql`：执行只读 SELECT 查询
144
+
145
+ 8. 通用工具
146
+ - `generate_unique_code`：生成全局唯一编码
147
+ - `mcp_catalog`：查看工具域与清单（渐进式披露开启时才需要使用）
148
+ - `mcp_activate`：启用或收起工具域（渐进式披露开启时才需要使用）
782
149
 
783
150
  ---
784
151
 
785
152
  ## 项目结构
786
153
 
154
+ ```text
155
+ flycode-mcp
156
+ ├── src
157
+ │ ├── cli # 命令行工具
158
+ │ ├── clients # API 接口客户端，调用 IDE 接口
159
+ │ ├── service # 核心服务层，工具的核心处理逻辑
160
+ │ ├── store # 状态管理层，用于存储和管理应用状态
161
+ │ ├── tools # 工具层，包含所有工具的定义
162
+ │ └── utils # 通用工具
163
+ ├── test # 测试，含所有测试用例
164
+ ├── scripts # 构建脚本
165
+ ├── docs # 文档
166
+ ├── flycode-mcp-skill # 配套 SKILL
167
+ └── website # 官网
787
168
  ```
788
- flycode-mcp/
789
- ├── website/ # 使用说明书网站（VitePress，面向终端用户，二次元卡通风格）
790
- │ ├── .vitepress/
791
- │ │ ├── config.ts # 站点导航 / 侧边栏 / 本地搜索配置
792
- │ │ └── theme/ # 二次元卡通主题（style.css / index.ts）
793
- │ ├── public/ # 静态资源（mascot.svg 卡通吉祥物）
794
- │ ├── guide/ # 快速开始 / 接入客户端 / 准备账号
795
- │ ├── capabilities/ # 能力清单与详解（25 个工具，用户视角）
796
- │ ├── cookbook.md # 常见场景话术
797
- │ ├── faq.md # 排错 FAQ
798
- │ ├── changelog.md # 版本更新记录（按 git tag 整理，用户视角）
799
- │ └── index.md # 首页 Hero
800
- ├── src/
801
- │ ├── index.ts # 入口：启动鉴权、注册工具、启动 stdio 服务
802
- │ ├── types.ts # 跨模块共用的通用类型（如提交信息 CommitMessage）
803
- │ ├── service/ # 业务封装
804
- │ │ ├── auth.ts # 登录 → 获取租户信息 → 获取 IDE Token
805
- │ │ ├── logic.ts # 保存业务逻辑（saveModelLogic / patchLogic（12 类 ops，事务性）/ replaceFlyCodeSegments）：提交信息处理 + 局部补丁 + 异常兜底
806
- │ │ ├── form.ts # 表单骨架 getFormOutline / 局部读取 getFormFragment / 补丁合并引擎 patchForm（11 类 ops，事务性）/ 全量保存 saveForm
807
- │ │ └── h5.ts # H5 表单查询鉴权（解析 SFA系统管理员预览账号 token） + 列表/详情查询 service 封装
808
- │ ├── clients/ # 平台接口封装
809
- │ │ ├── auth.ts # 登录 / 获取租户信息 / 获取 IDE Token 请求
810
- │ │ ├── logic.ts # 业务逻辑分页/详情查询、保存请求；LogicResult 等类型定义
811
- │ │ ├── entity.ts # 实体列表 pageEntityList / 详情 getEntity 请求；EntityResult 等类型定义
812
- │ │ ├── function.ts # flycode 函数列表 pageFunctionList、详情 getFunction 请求；FunctionResult 等类型定义
813
- │ │ ├── database-function.ts # 数据库函数（PostgreSQL 自定义函数）列表 pageDatabaseFunctionList 请求；DatabaseFunctionPageResult 等类型定义
814
- │ │ ├── form.ts # 表单 / 页面列表 pageFormList、详情 getForm、保存 saveForm（POST /biserv/bizpage/saveNewPage）请求；FormResult 等详情类型定义
815
- │ │ ├── h5.ts # H5 表单列表 listH5Page、详情 listH5PageByOne 请求；H5PageResult 等类型定义
816
- │ │ ├── run.ts # SQL 查询 sqlRun 请求（POST /api/biz/sqlrun）
817
- │ │ ├── test-case.ts # 预览账号列表 getPreviewAccounts 请求（H5 查询鉴权所需的 SFA系统管理员 token 来源）
818
- │ │ └── types.ts # 公共响应信封类型（DataResponse / PageResponse / CommonResponse）
819
- │ ├── store/ # 运行时内存存储
820
- │ │ ├── token.ts # 鉴权 Token 存储器
821
- │ │ └── tenant.ts # 当前租户及连接信息存储器
822
- │ ├── tools/ # 按能力分类的 MCP 工具定义
823
- │ │ ├── common.ts # 通用工具（generate_unique_code：雪花算法生成唯一编码）
824
- │ │ ├── logic/
825
- │ │ │ ├── read.ts # 只读类工具（page_model_logic_list / get_model_logic）
826
- │ │ │ ├── write.ts # 写入类工具（save_model_logic / patch_model_logic / str_replace_flycode）
827
- │ │ │ └── schemas.ts # 业务逻辑共享 zod schema（LogicResult / 参数 / operations / bindjson）
828
- │ │ ├── entity/
829
- │ │ │ ├── read.ts # 只读类工具（page_entity_list / get_entity / page_entity_directories）
830
- │ │ │ ├── write.ts # 写入类工具（create_entity / patch_entity）
831
- │ │ │ └── schemas.ts # 实体共享 zod schema（EntityResult / EntityProperty，宽松透传结构）
832
- │ │ ├── form/
833
- │ │ │ ├── read.ts # 只读类工具（page_form_list / get_form / get_form_outline / get_form_fragment）
834
- │ │ │ └── write.ts # 写入类工具（patch_form / save_form）
835
- │ │ ├── h5/
836
- │ │ │ └── read.ts # 只读类工具（page_h5_form / get_h5_form）
837
- │ │ ├── function/
838
- │ │ │ └── read.ts # 只读类工具（page_function_list / get_function）
839
- │ │ ├── database-function/
840
- │ │ │ └── read.ts # 只读类工具（page_database_function_list：数据库函数列表，函数体随行返回）
841
- │ │ └── run/
842
- │ │ └── read.ts # 只读类工具（run_sql：执行 SQL 查询）
843
- │ └── utils/
844
- │ ├── config.ts # 从命令行参数解析连接配置（BASE_URL / 账号等）
845
- │ ├── request.ts # 统一 axios 请求层（中心/租户地址切换 + Token 注入）
846
- │ ├── mcp-types.ts # MCP 工具统一定义类型 ToolDef
847
- │ ├── snowflake.ts # 雪花算法 ID 生成器（generate_unique_code 依赖）
848
- │ ├── date.ts # 日期格式化工具（saverecord 提交时间用）
849
- │ ├── error.ts # 统一错误信息提取
850
- │ └── str-replace.ts # str_replace_editor 模式纯文本替换（归一化匹配 / 批量 applyOps / diff hunk / 候选建议）
851
- ├── dist/ # 编译产物（由 tsc 生成，已忽略）
852
- ├── package.json
853
- ├── tsconfig.json
854
- └── .gitignore
855
- ```
856
-
857
- ---
858
-
859
- ## 工作原理
860
-
861
- 1. **解析配置**：从 `process.argv` 读取 `username / password / tenantCode / envName` 解析。
862
- 2. **登录**：登录 IDE 获取 Token，存入内存。
863
- 3. **定位租户与环境**：依据 `tenantCode + envName` 匹配出目标租户，保存其连接信息（`conn.config`）到内存。
864
- 4. **获取 IDE Token**：换取具体租户环境专用 Token 并覆盖内存中的 Token。
865
- 5. **注册并启动**：创建 `McpServer`，注册工具，通过 `StdioServerTransport` 监听请求。
866
- 6. **业务请求**：工具被调用时，分层处理 `Tool` 层定义工具 -> `Service` 层核心处理逻辑 -> `Client` 层发 `HTTP` 请求调用 IDE 接口。
867
169
 
868
170
  ---
869
171