weaver-work-cli 0.1.23 → 0.1.25

package/skills/weaver-e10-builder/references/ebuilder-designer/guide-designer.md

@@ -0,0 +1,288 @@
+# 设计器布局层指南
+
+> 本文件为 `SKILL.md` 的子模块，在用户于 Ebuilder 设计器中读/改/存页面布局时加载。覆盖：页面元信息（info）、布局树（layout）、保存（save）、锁定/解锁（lock）、主题（theme）、栅格位置（position）、加组件（comp-add，factory 模板自带打包）。
+>
+> **契约来源**：本指南全部字段、参数、取值枚举来自 ebuilder-designer 的 7 个 HTTP 接口规约（layout/page-info、layout/list、layout/save、layout/lock、layout/refTheme、page/version/list、page/version/revert）。凡接口未给出、须运行时 inspect 真实页面才能确定的具体取值（组件 config 子字段集、取值枚举、header 样本集等），一律标 **「需 inspect 真实页面查原始值」**，不凭空构造——盲造组件 config 会触发 ERR-007/008 崩页。
+>
+> 本 skill 自包含分发，不依赖任何本机文件；"inspect 真实页面"指用户对自己的页面运行 `designer layout <pageId> --json` 查看实际数据，是运行时操作。
+
+---
+
+## 命令总览
+
+| 命令 | 说明 | 对应接口 |
+|------|------|----------|
+| `e10-cli designer info <pageId>` | 获取页面元信息（权限/变量/数据集/主题/锁定态） | GET `/layout/page/info` |
+| `e10-cli designer layout <pageId> [--no-cuscomp]` | 获取 PC/MOBILE 两端完整组件树（默认 `returnCusComp=true`；`--no-cuscomp` 切 false 需 READONLY 权限） | GET `/layout/list` |
+| `e10-cli designer layout <pageId> --json` | 导出布局 JSON 文件，供 save/comp-add 复用（`--json` 是全局选项，非 layout 专属隐藏） | GET `/layout/list`（落地为文件） |
+| `e10-cli designer save <pageId> --layouts <json\|@file> [--page-name] [--sync-outdate]` | 保存布局（CLI 内部 LZ 压缩后 POST）。`--layouts` 必填（**不是位置参数**） | POST `/layout/save` |
+| `e10-cli designer lock <pageId>` / `designer unlock <pageId>` | 锁定/解锁页面 | POST `/layout/lock` |
+| `e10-cli designer css read <pageId> <compId> [--terminal <pc\|mobile\|both>]` | 读组件自定义 CSS（默认双端；`<compId>` 给任一端都行） | GET `/layout/list` |
+| `e10-cli designer css write <pageId> <compId> (--css <文本> \| --css-file <路径>) [--append\|--clear] [--terminal] [--yes]` | 写组件自定义 CSS（默认**双端同写**、默认整段替换）。写后回读比对，对不上报错 | POST `/layout/save` |
+| `e10-cli designer dom-list` / `designer dom <type> [--keys] [--section <path>] [--refs]` | 查写 CSS 要用的**组件 DOM 结构索引**（27 个组件；先 `--keys` 看骨架，再 `--section` 取子树） | 读随包资产 |
+| `e10-cli designer position <pageId> <compId> --x --y --w --h` | 调组件栅格位置（PC，封装 `/layout/save`：改 `config.layout.x/y/w/h` 后 save） | POST `/layout/save` |
+| `e10-cli designer comp-add <pageId> --type <Type> [--template @<file>] [--from <srcPage> --comp <id>] [--x --y --w --h]` | 加组件（封装 `/layout/save`）。**`--type` 是选项不是位置参数**。两种取源：`--type --template @<file>`（factory 模板，见 `guide-designer-factory.md`）/ `--from <srcPage> --comp <id>`（从活页克隆）。`--h` 按该指南「组件高度判断」自行算 | POST `/layout/save` |
+| `e10-cli designer comp-remove <pageId> <compId>` | 移除组件（含 PC/MOBILE refCompId 两端） | POST `/layout/save` |
+
+> **页面主题（`/layout/refTheme`）、页面可用组件库（`/api/ebuilder/coms/component/list`）这两类接口目前没有 CLI 命令封装**，故不列在此表 —— 上表只列**实际可执行**的命令。
+
+> 组件 config 字段名与配置机制见 `guide-designer-components.md`；自定义 CSS 与 DOM 结构索引见 `guide-designer-css.md`；版本 list/revert 见 `guide-designer-version.md`。
+
+---
+
+## designer info — 获取页面布局信息
+
+**接口契约**：GET `/api/bs/ebuilder/designer/layout/page/info`，Query `pageId`（Long，必填），请求头 `ETEAMSID`。
+
+**返回字段**（`Map<String,Object>`，随 `BelongModule` 不同字段集不同）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id / pageId | String | 页面 ID |
+| module | Enum | 所属模块，如 `EB_PAGE` / `EB_FORM_VIEW` / `PORTAL_PAGE` |
+| moduleName | String | 模块中文名 |
+| layoutType | Enum | `GRID` / `ABSOLUTE` / `FLEX` |
+| isLock | Integer | `0` 未锁 / `1` 已锁 |
+| allowEdit | Boolean | 当前用户是否可编辑（仅 EB 页面模块返回） |
+| terminalScopes | String | 终端范围，如 `"PC,MOBILE"` |
+| appid / appName / appLabelId | - | 所属应用信息（仅 EB 页面模块） |
+| dataset | Array | 页面数据集 |
+| pageVar / appVar / pageModel | Array | 页面变量 / 全局变量 / 变量模型 |
+| refTheme | String | 关联主题 ID |
+| isIntro | Boolean | 是否需新手引导 |
+| pageAnonymousEnable | Boolean | 是否免登录访问 |
+| compPermit / compStylePermit | Boolean | 组件库/样式库创建权限（仅 `PORTAL_PAGE`） |
+
+> **坑**：
+> - 本接口**无 `@Permission` 注解**，只校验登录态；可编辑性通过 `allowEdit` 字段返回，前端据此控制——`allowEdit=false` 不要调 save。
+> - `isLock=1` 须先 `designer unlock` 再 save。
+> - `isIntro=true` 首次使用需引导，完成后调 `/finishIntro`（本 skill 未封装，需界面）。
+
+---
+
+## designer layout — 获取页面布局列表
+
+**接口契约**：GET `/api/bs/ebuilder/designer/layout/list`，Query `pageId`（必填）、`returnCusComp`（Boolean，默认 `true`），请求头 `ETEAMSID`。
+
+**权限分层**：`returnCusComp=true` 校验 `ObjType.PAGE`+`OptType.VIEW`，返回完整组件（含权限过滤）；`returnCusComp=false` 校验 `READONLY`，不返回自定义组件（`/api/bs` 路径下自动置 `false`）。
+
+**返回**：`Array<PageLayoutEntity>`，通常 2 元素（PC + MOBILE），按 `terminalType` 区分。
+
+**PageLayoutEntity 核心字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Long | 布局唯一标识 |
+| pageId | Long | 所属页面 ID |
+| layoutType | Enum | `GRID` / `ABSOLUTE` / `FLEX` |
+| terminalType | Enum | `PC` / `MOBILE` |
+| module | Enum | `EB_PAGE` / `PORTAL_PAGE` 等 |
+| config | Map | 布局配置（页面样式/背景/缩放等） |
+| comps | Array<LayoutComponentEntity> | 组件列表 |
+| sourceCode | Map | 页面源码 |
+| ecodeVersion | Integer | ecode 版本标识 `1`~`4` |
+| rightCompIds | Array<String> | 当前用户有权限查看的组件 ID |
+| appId | Long | 所属应用 ID |
+| thumbnail | String | 缩略图文件 ID |
+| sysVariable / cssCache* | - | 组件变量 / 样式缓存相关 |
+
+**LayoutComponentEntity 核心字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 组件唯一标识（32 位无连字符 UUID） |
+| type | String | 组件类型名，如 `Slide` / `NList` / `NText` |
+| package | String | 组件 npm 包路径 |
+| category | String | 组件分类编号 |
+| pid | String | 父组件 ID |
+| refCompId | String | 关联组件 ID（PC/MOBILE 同名组件互指） |
+| config | Map | 组件配置（含 `layout`、样式、属性、事件等） |
+| isCustom / isLock | Boolean | 是否自定义 / 是否锁定 |
+| applyStyle | String | 应用样式 ID 列表（逗号分隔） |
+| prop | String | 组件属性标识 |
+| styleCategoryCompKey / styleCategoryPackage | String | 样式分类 key / 包路径 |
+
+> **坑**：
+> - `returnCusComp=true` 时 comps 经权限过滤，只返有权查看的组件；`rightCompIds` 列出有权组件 ID。
+> - PC 与 MOBILE 同名组件经 `refCompId` 互连——改一端时注意另一端是否需同步。
+> - 跨租户页面走 `/api/{module}/designer/layout/list` 路径会额外查 `isNoTenantPage`。
+
+---
+
+## designer save — 保存页面布局（核心）
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/save`，Query `pageId`（必填）、`pageName`（可选，1-200）、`isSyncOutDateComps`（可选，默认 `false`）；**Body = `layouts` 字符串，是 LZ 压缩后的 JSON**。请求头 `ETEAMSID`。需 `ObjType.PAGE`+`OptType.EDIT` 权限。
+
+### 入参数据来源铁律
+
+> **layouts 直接取自 `/layout/list` 返回值作为基础，调用方只需完整构造 `comps` 属性**——`pageId`、`terminalType`、`module`、`layoutType`、`ecodeVersion`、`appId`、`config`、`sourceCode`、`rightCompIds` 等元数据保持 `/list` 原值不动。CLI 的 `designer save` 也遵循此模式：先 `layout --json` 导出，改 `comps`，再 save。
+
+### PageLayoutEntity 入参字段（解密后 JSON 数组每元素）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | Long | 是 | 布局 ID |
+| pageId | Long | 是 | 所属页面 ID |
+| terminalType | Enum | 是 | `PC` / `MOBILE` |
+| module | Enum | 是 | `EB_PAGE` / `PORTAL_PAGE` 等 |
+| comps | Array<LayoutComponentEntity> | 是 | 组件列表（**唯一需完整构造**） |
+| layoutType | Enum | 否 | `GRID` / `ABSOLUTE` / `FLEX` |
+| config | Map | 否 | 布局配置 |
+| compStyles / dataset / pageVar / pageModel / appVar | Array | 否 | 样式/数据集/变量/模型 |
+| sourceCode | Map | 否 | 页面源码 |
+| ecodeId / ecodeVersion / appId | - | 否 | ecode/应用标识 |
+| thumbnail / refTheme / themeData | - | 否 | 缩略图/主题 |
+| sysVariable | Map<String,String> | 否 | 组件变量 |
+
+### LayoutComponentEntity 入参字段（comps 子元素）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| id | String | 是 | 32 位无连字符 UUID（前端生成） |
+| type | String | 是 | 组件类型名 |
+| config | Map | 是 | 组件配置（含 `layout`/样式/属性/事件等） |
+| package | String | 否 | npm 包路径（序列化时映射为 `compPackage`） |
+| category / pid / refCompId | String | 否 | 分类 / 父组件 / 关联组件 |
+| refPluginPackageId / refPluginPackage | - | 否 | 插件包 |
+| refModule / refBusinessId | - | 否 | 关联模块/业务 |
+| prop / applyStyle | String | 否 | 属性标识 / 样式 ID 列表 |
+| styleCategoryCompKey / styleCategoryPackage | String | 否 | 样式分类 |
+| styles / customConfig | - | 否 | 自定义样式/配置 |
+| ecodeId / ecodeVersion | - | 否 | ecode 标识 |
+| isCustom / isLock | Boolean | 否 | 是否自定义/锁定 |
+| masterComponent / master | - | 否 | 母版 |
+| visibleScope | Enum | 否 | `ALL` / `OWNER` / `CUSTOM` |
+| isCover | int | 否 | `0`/`1` 是否覆盖母版 |
+| formComponent | Object | 否 | 表单组件 DTO（表单页才用） |
+
+### config 内部结构（以 Slide 为例——接口文档唯一给出的完整样例）
+
+| 子字段 | 类型 | 说明 |
+|------|------|------|
+| name | String | 组件显示名 |
+| title / titleEnabled | String / Boolean | 标题文本 / 是否启用 |
+| footerEnabled | Boolean | 是否启用页脚 |
+| pics | Array | 图片列表 |
+| imageMode | String | 图片填充模式 |
+| switchEffect | String | 切换效果 |
+| intervalTime | Object | 轮播间隔 `{type, value}` |
+| speed | Integer | 切换速度（ms） |
+| lazyLoad | Boolean | 是否懒加载 |
+| imgSourceType | String | 图片来源类型 |
+| eventGroup | Array | 事件配置列表 |
+| **filter** | **Object** | **数据过滤条件（HTTP 契约：filter 类型为 Object，传 `[]` 与契约不符）** |
+| showNum | Integer | 展示数量 |
+| layout | Object | 栅格布局 `{i, x, y, w, h, scope, moved, selected, offsetTop, hidden}` |
+| flow / disabled | Object | 流程 / 禁用配置 |
+
+> **⚠️ 需 inspect 真实页面查原始值**：上表是 Slide 一例。**其他组件类型（NList / NText / NButton / Calendar / Pie / Bar / Line / NavPanel / DigitalPanel 等）的 config 子字段集，接口文档未给出**——必须 `designer layout <pageId> --json` 导出真实已配置页面，查 `comps[].config` 字段名与取值，**勿凭空构造**（盲造触发 ERR-007/008）。具体 setter 取值枚举见 `guide-designer-components.md`。
+
+### LZ 压缩算法（CLI 内部使用，直接调 `designer save` 无需手压）
+
+`layouts` Body 是 LZW（Lempel-Ziv-Welch）压缩后的**逗号分隔数字串**，服务端 `EbuilderCommonUtil.decryptByLZ()` 解密。算法要点：
+1. 字典初始大小 **65536**（`2^16`，Unicode 字符最大值 +1）。
+2. 字典**不预初始化**单字符映射，运行时按需添加。
+3. `w` 为单字符且不在字典时，将其 Unicode 码点加入字典作为 code。
+4. 输出逗号分隔数字序列，每个数字为字典 code 或 Unicode 码点。
+
+> CLI `designer save` 内置该算法（JS/Java/Python 三语言实现见 layout-save 接口文档 §4.4），调用方传 `@layouts.json` 文件即可，**不要自己压**。
+>
+> **坑**：Body 直接传压缩后的数字串（`Content-Type: application/json`），**不要**再用 `JSON.stringify()` 包裹；保存前若 `isLock=1` 须先 unlock。
+>
+> **⚠️ 需 inspect 真实页面**：接口文档 §4.4 仅明示 `ebbusinessid` 请求头（=pageId）+ Cookie（`ETEAMSID`/`LOGIN_TYPE`/`langType`）。真实浏览器调用还带 `referer`、`timezoneoffset` 等头——**完整 header 集需样本确认，本骨架只列文档明示项**。CLI 已封装常用头，手调原始接口时按需补。
+
+### 返回与内部流程
+
+**返回**：`data.refreshComps`（Map<layoutId, Array<comp>>，仅 NList + 插件包 `933846626099339271` 时返，需前端刷新的组件）、`data.ecodeIds`（Map<layoutId, {ecodeId, ecodeVersion}>；`ecodeVersion` 为 2/3 时 `ecodeId` 取应用的而非布局自身的）。
+
+**保存内部流程**：解密 → updateLayouts → saveSourceCode → updatePageVersion →（异步）createPageVersionBySavingLayout →（异步）syncMultilingual。历史记录与多语言同步不阻塞保存成功。
+
+---
+
+## designer lock / unlock — 锁定/解锁
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/lock`，Query `pageId`（必填）、`isLock`（Boolean 必填，`true` 锁 / `false` 解锁），请求头 `ETEAMSID`，需 EDIT 权限。返回 `data: true`。
+
+> **坑**：
+> - 锁是**软约束**——`/save` 本身**不校验** `isLock`；实际编辑权由 `@Permission` 强制。锁主要用于多人协作防并发。
+> - 每次 lock/unlock 都触发 `updatePageVersion`，**版本号会递增**（即使幂等调用）。
+> - `isLock` 存储为 int（`lockType` 1/0）。
+
+---
+
+## designer theme — 设置主题
+
+**接口契约**：POST `/api/bs/ebuilder/designer/layout/refTheme`，**Query 参数** `themeId`（Long 必填）、`pageId`（Long 必填）、`terminalType`（`PC`/`MOBILE`，默认 `PC`；契约只列 themeId+pageId，CLI 样本发现带 terminalType），请求头 `ETEAMSID`，需 EDIT 权限。
+
+**返回**：`{ themeCss, styleConfig, themeId, themeVersion, refTheme, defTheme, refStyles[] }`。
+
+> **坑**：
+> - `themeId` 与当前一致且版本缓存一致时 `themeCss` 可为 `null` → 用缓存，不再注入 CSS。
+> - 主题已删除时不报错但 CSS 空，回落默认。
+> - 设置主题后**须再调 `designer save` 持久化** `refTheme` 到布局。
+> - 异步同步到发布端（`asyncTheme`）。
+>
+> **⚠️ 需 inspect 真实页面**：`themeId` 取值（可用主题清单）接口文档未给获取主题列表的接口——先用 `designer theme-list <pageId>` 查可选 themeId 清单，再 inspect 设计器主题面板核对；当前主题详情用 `designer theme-info <pageId>`。
+
+---
+
+## designer position — 调整栅格位置（PC）
+
+`designer position <pageId> <compId> --x --y --w --h` 是 save 的封装：`designer layout <pageId> --json` → 改目标 comp 的 `config.layout.x/y/w/h` → `designer save`。
+
+PC 端 12 列栅格（`config.style.layout.column=12`）；`--x` 列起点、`--y` 行起点、`--w` 宽（≤12）、`--h` 高（栅格行数）。
+
+> **⚠️ 需 inspect 真实页面**：Mobile 端 `config.layout` 字段（`adaptive`/`h` 等，见 layout-list 示例）与 PC 差异——接口文档示例可见但不完整，**需 inspect 两端真实布局对比**。`designer position` 默认只改 PC 端栅格。
+
+---
+
+## designer comp-add — 加组件
+
+加组件 = 读 `/layout/list` → 向对应 `terminalType` 的 `comps[]` push 一个新 `LayoutComponentEntity` → `designer save`。
+
+- **comp id**：前端生成的 32 位无连字符 UUID（接口文档 §4.3 comps id 字段约束）。
+- **config 完整性**：`config` 字段必须完整，缺失字段会崩页（ERR-007/008）。
+- **factory 模式（首选）**：`designer comp-add <pageId> --type <Type> --template @<file>`（**`--type` 是选项不是位置参数**）从本 skill 自带的 `assets/factory/factory-<name>.json`（28 组件均有，原8源 2ganjing/新增20源 0805yuanshi 平台初始态，见 `guide-designer-factory.md`）复制完整 comp（仅换 id/refCompId）。模板是平台拖拽初始态、绑定空——**greenfield 用户无任何已配页面也能开箱即用**，克隆后用组件子命令把数据绑到自己的表单（图表/列表/日历/导航/幻灯/数字面板有 setter；其余组件见 factory 指南"克隆后必做"节）。
+- **活页克隆模式**：`designer comp-add <pageId> --from <srcPage> --comp <srcCompId>` 从一个已配好的真实页面逐字克隆某 comp（连配置一起搬）。用于搬运已配好的复杂数据；会带入源页表单绑定，须逐个 remove+add 重指到自己的表单，不如 factory 干净。
+- **无模板凭空构造**：除 Slide 外的组件 config 字段集接口未给，**勿凭空拼装**（盲造 ERR-007/008）；始终走 factory 模式。
+
+> **新建 comp 对 PC/MOBILE `refCompId` 互连**：接口示例可见互指，factory 模板已内置两端互连规则，`comp-add --template` 自动生成新对并重连，无需手动处理。
+
+---
+
+## 版本与还原（速查）
+
+版本列表 / 版本还原见 `guide-designer-version.md`（GET `/page/version/list` + POST `/page/version/revert`）。
+
+---
+
+## 典型工作流
+
+```bash
+# 1. 拿 pageId（应用已建、页面已建；见 ref-cli-commands.md 页面管理节）
+e10-cli app list                       # 拿 appId
+e10-cli page list --app-id <appId>     # 拿 pageId
+e10-cli page create <页面名> <appId> --scope PC,MOBILE --layout-type GRID   # 建空页（参数顺序：名称在前、appId 在后）
+
+# 2. 进设计器前先看元信息
+e10-cli designer info <pageId>         # 看 allowEdit / isLock / module
+
+# 3. 读布局（作为编辑基础）—— --json 输出完整 PC+MOBILE 两端（save 必须两端，否则覆盖丢 MOBILE；CLI save 强校验）
+e10-cli designer layout <pageId> --json > layouts.json   # 导出 PC+MOBILE 组件树
+
+# 4. 锁定（多人协作防并发）
+e10-cli designer lock <pageId>
+
+# 5. 改 comps（加组件/改 config/调位置）→ 保存
+e10-cli designer comp-add <pageId> --template slide --x 0 --y 0 --w 12 --h 25   # 模板名直传（28 个内置），--h 按组件高度判断自行算，见 guide-designer-factory.md
+e10-cli designer position <pageId> <compId> --x 0 --y 0 --w 12 --h 25
+e10-cli designer auto-height <pageId>                    # 单列纵堆模式：按内容定高+重排 y（多列栅格勿用，手调 position）
+e10-cli designer save <pageId> --layouts @layouts.json   # 收尾显式保存
+
+# 6. 解锁
+e10-cli designer unlock <pageId>
+```
+
+> **关键**：save 入参直接取自 `/list` 导出值，只改 `comps`；元数据不动。组件具体 config 取值需 inspect 真实页面，不凭空造。
+
+> **⚠️ 收尾必做显式 save + unlock（否则"布局未保存"）**：`comp-add`/`position`/各组件 setter（chart dataset-set/measure-add 等）虽各自**封装 `/layout/save` 自动存盘**，但全部改完后**必须再跑一次显式 `designer save <pageId> --layouts @<fresh-layout.json>` + `designer unlock <pageId>`**（fresh layout 用 `designer layout <pageId> --terminal all --json` 现导）。否则页面留 `isLock=true`（浏览器开了设计器会自动上锁）或 draft 标志未清，**设计器/预览打开会弹"布局未保存"提示**（验证：未 unlock 的页 `isLock=true`，预览必弹）。`designer unlock` 是软锁释放，多人协作场景防并发；单人编辑也必须收尾 unlock 清态。`publish-menu` 前务必先 save+unlock。

package/skills/weaver-e10-builder/references/esb-interface/guide-import.md

@@ -0,0 +1,34 @@
+# 接口文档导入 ESB 系统接口
+
+当用户要求“从接口文档创建系统接口”“接口文档转 Postman 并导入 ESB”时，使用 e10-cli 的原生命令：
+
+```bash
+e10-cli interface import "<文档路径>" --out collection.json
+e10-cli interface import "<文档路径>" --system-pool-name "<连接器/系统池名称>" --apply --out collection.json
+```
+
+支持 `.docx`、`.pdf`、`.md`、`.txt`、`.xlsx`、`.xls`。默认只解析预览；只有用户明确要求创建时才加 `--apply`。PDF 解析依赖当前机器可用的 `pdftotext`（Poppler）。
+
+`.xlsx` 是表格版接口文档（按「接口目录」+ 每接口一个工作表组织）；`.xls` 是旧版二进制格式，客户/厂商的老文档里常见 —— **别把它当不支持、让用户先转格式**。
+
+## 处理规则
+
+1. 一份文档中的全部接口合并为一个 Postman Collection v2.1，统一调用平台的 `createSystemInterfaceByAi`。
+2. `--system-pool-name` 优先使用用户明确指定的连接器/系统池名称；未传时从本次文档文件名去扩展名、去尾部 `(1)`/`（1）` 推导。不能复用旧环境名称，也不能臆造名称。
+3. Collection 的 `info.name` 与请求体中的 `systemPoolName` 保持一致且不能为空。
+4. 每个接口必须有请求定义和至少一个 `response[]` 示例；平台输出参数来自响应示例的 `body`，不能只写到 description。
+5. 文档中的密码、token、Authorization、secret、apiKey 等敏感示例值在本地生成 Collection 时脱敏；不要把 Eteamsid 写进文件。
+6. 创建成功必须同时满足外层 `code=200` 和 `data.res=true`，并报告 `systemPk`、接口名称和接口 ID；不能只看 HTTP 200。
+7. 创建接口是新增语义，不提供更新/去重；格式校验先在本地完成，避免重复调用在线接口留下重复系统。
+8. Excel 文档按**不可信输入**对待，解析限额：单文件 ≤ 20 MB、工作表 ≤ 50 个、单表 ≤ 5000 行、单元格总数 ≤ 50 万。超限**直接报错中止**，**不会截断后继续解析** —— 截断会算出一份看不出错的接口清单，比直接失败坏得多。真遇到超限，先跟用户确认是不是拿错了文件（接口文档通常几行到几十行），再谈拆分。
+
+## 文档提取重点
+
+- 按“接口地址”切分接口区块，提取接口名称、请求方式、URL、请求 JSON 和返回 JSON。
+- 请求字段取参数表、请求示例和示例代码中的请求体字段并集，避免漏掉只出现在示例代码中的字段。
+- 返回字段取“返回结果/返回示例/响应结果”等示例，按原有嵌套结构写入 Postman `response[].body`，不得扁平化或额外编造字段。
+- 解析结果有缺失时，在预览输出的 `warnings` 中明确列出；不要静默按猜测补字段。
+
+## 与动作流 HTTP 组件的边界
+
+这里的 `interface import` 是“从文档创建连接器下的系统接口”；动作流里的 `Http` 是“调用当前租户已经存在的连接器 → 连接信息 → 执行接口”。两者可以串联使用，但不能把接口导入命令当成 HTTP 动作节点配置命令。

package/skills/weaver-e10-builder/references/form/guide-create-form.md

@@ -0,0 +1,248 @@
+# 新建 EBuilder 表单
+
+通过 `e10-cli form create` 在 EBuilder 应用中创建表单。本指南说明从需求整理、`fields.json` 编写到建后配置的完整顺序；字段参数和布局样表的详细规则按需读取专题参考。
+
+需求以已有 EB 表单、系统业务表或数据加工结果为实际数据源时，使用 [虚拟表创建与维护](guide-virtual-form.md) 的 `form virtual` 流程。
+
+## 标准创建流程
+
+1. 确认目标应用 `appId`。
+2. 确认布局类型：流式 `FLOW` 或表格式 `EXCEL`。布局类型在建表时确定。
+3. 从需求中整理字段、明细表、字段顺序和布局要求；遇到完整布局样表时，将空间结构写入 plan 的“表单布局蓝图”。
+4. 将建表时可以完成的配置写入 `fields.json`。
+5. 执行 `form create`，记录返回的 `objId` 和 `formId`。
+6. 使用 `form list-view` 查询并记录默认台账 `listId`。
+7. 按需求完成多语言、联动、校验、权限、视图和按钮等建后配置。
+8. 使用读取命令轻量核对字段、布局和默认台账。
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW|EXCEL
+e10-cli form list-view <objId> <appId>
+e10-cli form read <objId> --app-id <appId> --out fields-created.json
+```
+
+需要同时生成台账菜单入口时，在创建命令中增加 `--menu`；建成后也可使用 `menu add-table <appId> <objId>` 添加。默认台账视图与应用菜单入口是两个资源。
+
+### 自定义数据库表名
+
+不指定时表名按表单名拼音首字母加随机数生成（如 `uf_xsddb_4683`）。需要固定或对齐既有命名时用 `--table-name`：
+
+```bash
+e10-cli form create <appId> "客户信息表" --fields @fields.json --table-name cs_khxx
+```
+
+- **平台前缀由 CLI 自动补**：传 `cs_khxx` 与传 `uf_cs_khxx` 结果相同（`uf_cs_khxx`）。
+- **格式约束**：字母开头，只含字母、数字、下划线。前缀之外的部分受平台长度上限约束 —— 前缀 `uf_`、总长上限 30 时，自定义部分最多 27 位。越界会直接报错，不会建成一半。
+- **建成后回读校验**：实际表名与预期不一致会报错，不静默通过。
+- 仅对**物理表**应用有效；应用未启用物理表时该选项不适用（CLI 会先查存储设置并拒绝）。
+
+## 各阶段配置范围
+
+| 阶段 | 配置内容 |
+|---|---|
+| 需求与 plan | 表单名称、字段类型、顺序、明细结构、FLOW/EXCEL、布局蓝图及外围配置 |
+| `fields.json` | 字段、选项、默认值、精度、日期格式、关联、公式、明细、分组和显示属性 |
+| `form create` | 表单主体、字段、明细、布局、基础查看权限、默认台账及可选菜单 |
+| 建成后 | 字段多语言、联动、查重、进一步权限、视图名称与列、筛选、按钮及关联页签 |
+| 完成核对 | `objId`、`formId`、`listId`、字段结构和布局结果 |
+
+## 建表前整理需求
+
+### 布局类型
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+```
+
+- `FLOW`：流式布局。
+- `EXCEL`：表格式布局，也是 CLI 缺省值。
+- 需求未明确且布局选择会影响结果时，建表前向用户确认。
+- 需求提供完整表格、合并单元格、分组标题、标签与字段交替排布时，按布局样表处理，详见 [表单布局规划](guide-form-layout-planning.md)。
+
+### 字段定义
+
+字段按照需求顺序写入 `fields.json`。主表字段在前，`DetailTable` 明细表放在数组末尾。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"合同名称","required":true,"singleRow":true},
+  {"componentKey":"DateRange","fieldName":"合同有效期","format":"yyyy-MM-dd"},
+  {"componentKey":"Money","fieldName":"合同金额","precision":2},
+  {"componentKey":"Select","fieldName":"合同状态","fieldOptions":[{"name":"草稿"},{"name":"履行中"}]},
+  {"componentKey":"Employee","fieldName":"负责人"},
+  {"componentKey":"DetailTable","fieldName":"付款明细","formFields":[
+    {"componentKey":"Date","fieldName":"付款日期"},
+    {"componentKey":"Number","fieldName":"付款金额","precision":2}
+  ]}
+]
+```
+
+常用字段类型包括文本、数字、选项、日期、组织、关联、行政区域和其他类型。完整类型、关联码表及各类型属性见 [表单字段定义参考](ref-form-fields.md)；明细表通过表单结构配置创建。
+
+## 常用字段属性
+
+| 属性 | 作用 |
+|---|---|
+| `required:true` | 字段必填 |
+| `readOnly:true` | 禁止手工编辑 |
+| `hidden:true` | 布局中隐藏，字段仍可参与计算 |
+| `singleRow:true` | 独占一行 |
+| `group:"基本信息"` | 放入指定字段分组 |
+| `multiple:true` | 支持多选的字段设置为多选 |
+| `maxLen:500` | 文本最大长度 |
+| `precision:2` | 数字或金额小数位 |
+| `defaultValue` | 字段默认值 |
+
+### 字段分组
+
+以需求为准：只有需求明确要求字段分组时，才在 `fields.json` 中设置 `group`；需求未要求时保持不分组。
+
+```json
+[
+  {"componentKey":"Text","fieldName":"项目名称","group":"基本信息","required":true},
+  {"componentKey":"Employee","fieldName":"负责人","group":"基本信息"},
+  {"componentKey":"Number","fieldName":"项目金额","group":"财务信息","precision":2}
+]
+```
+
+同名 `group` 的字段进入同一个分组。分组内字段按字段顺序排列，需要整行展示的字段增加 `singleRow:true`。已有表单补充分组时使用：
+
+```bash
+e10-cli form group <objId> <appId> --groups '{"基本信息":["项目名称","负责人"]}'
+```
+
+### 日期区间
+
+字段本身包含开始与结束含义，如“项目周期、合同有效期、请假时间、活动时间”，优先使用 `DateRange`。明确要求两个独立字段，或开始、结束需要分别参与公式和联动时，再拆成两个日期字段。
+
+```json
+{"componentKey":"DateRange","fieldName":"项目周期","format":"yyyy-MM-dd"}
+```
+
+### 选项和多选
+
+```json
+{"componentKey":"Select","fieldName":"状态","fieldOptions":[{"name":"启用"},{"name":"停用"}]},
+{"componentKey":"Employee","fieldName":"项目成员","multiple":true}
+```
+
+`Select`、`RadioBox`、`CheckBox` 可在 `fieldOptions` 中定义选项。人员、部门、EBuilder、Browser 和 Select 等支持按字段能力设置多选。共享选项可使用 `optionTemplate`；详细结构见 [表单字段定义参考](ref-form-fields.md)。
+
+### 关联字段
+
+EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
+
+```json
+{
+  "componentKey":"EBuilder",
+  "fieldName":"关联客户",
+  "sformId":"<目标表单objId>",
+  "dataTitle":"客户名称",
+  "displayColumns":["客户名称","客户类型"]
+}
+```
+
+`Flow` 的 `sformId` 同样指向目标流程绑定的表单 `objId`。原生关联对象和通用浏览类型的配置码表见 [表单字段定义参考](ref-form-fields.md)；关联数据过滤和范围分别见 [EBuilder 过滤](guide-ebuilder-filter.md) 与 [关联浏览数据范围](guide-ebuilder-scope.md)。
+
+### 明细表与二级明细
+
+明细字段写入 `DetailTable.formFields`。二级明细关系配置在父明细表上，父明细每一行分别拥有对应的子明细数据：
+
+```json
+[
+  {"componentKey":"DetailTable","fieldName":"任务明细","enableSubDetail":true,
+   "subDetailConfig":[{"subForm":"工时明细","subField":"父任务标识"}],"formFields":[
+    {"componentKey":"Text","fieldName":"任务名称"}
+  ]},
+  {"componentKey":"DetailTable","fieldName":"工时明细","formFields":[
+    {"componentKey":"Text","fieldName":"父任务标识"},
+    {"componentKey":"Number","fieldName":"工时","precision":2}
+  ]}
+]
+```
+
+父级行标识缺省使用行 ID；子级行标识必须为单行文本。多父级复用、多子级和多级嵌套的规则，以及已有表单的查询、增加、删除、启停命令见 [二级明细表配置](guide-form-sub-detail.md)。
+
+### 表单结构与布局组件
+
+主表字段直接写在 `fields.json` 根数组中；明细表使用 `DetailTable` 配置，并通过 `formFields` 维护其字段。主表与明细表字段采用相同的字段类型和属性规则。
+
+布局初始化会根据表单结构生成相应的内部组件：
+
+| 组件 | 在创建流程中的作用 |
+| --- | --- |
+| `DetailTable` | 定义明细表及其字段 |
+| `DataTable` | 在布局中承载和展示明细表 |
+| `Fold` | 承载字段分组和折叠区域 |
+| `Placeholder` | 维护布局中的占位位置 |
+| `EbuilderAppTag` | 维护 EB 应用相关的布局标签 |
+
+业务字段从字段类型码表中选择；以上结构与内部组件由明细表、分组和布局配置生成与维护。
+
+### 字段公式
+
+可在目标字段中写 `formula`，由创建流程完成公式创建和字段绑定：
+
+```json
+{"componentKey":"Number","fieldName":"项目收益","formula":"{主表.已收款}-{主表.项目费用}"}
+```
+
+公式表达式、明细汇总和函数格式见 [字段公式函数参考](guide-form-formula-functions.md)。复杂编号属于建后配置，见 [表单复杂编号](guide-form-serial-mark.md)。
+
+## 执行创建
+
+```bash
+e10-cli form create <appId> "采购合同" --fields @fields.json --layout EXCEL
+```
+
+创建流程会依次完成表单主体、字段和明细、布局初始化、字段高级属性、关联关系、选项、公式、分组、基础查看权限及默认台账配置。传入 `--menu` 时同时添加台账菜单入口。
+
+记录命令返回的：
+
+- `objId`：EB 表单业务对象 ID，多数 `form` 命令使用它。
+- `formId`：底层表单 ID，布局和部分底层接口使用它。
+- `listId`：默认台账 ID，通过 `form list-view` 查询。
+
+## 建成后配置
+
+按需求执行，未提出的配置不额外增加：
+
+| 需求 | 命令或指南 |
+|---|---|
+| 字段中英文名称 | `form field-lang set` |
+| 字段显隐、只读、必填联动 | [表单联动](guide-form-linkage.md) |
+| 字段查重 | `form validate` |
+| 表单和数据权限 | `form permission` |
+| 默认台账改名、列、筛选和分组 | [表单视图](guide-form-view.md) |
+| 表单及视图按钮 | [表单按钮](guide-form-button.md) |
+| 关联页签 | [表单关联页签](guide-form-association.md) |
+| 复杂编号 | [表单复杂编号](guide-form-serial-mark.md) |
+
+需求写成 `中文/English`（如 `项目/project`）时，先以中文名称创建字段，再设置多语言：
+
+```bash
+e10-cli form field-lang set <objId> <appId> <fieldId> --zh "项目" --en "project"
+```
+
+## 完成核对
+
+使用与本次需求直接相关的读取命令核对即可：
+
+```bash
+e10-cli form read <objId> --app-id <appId> --out fields-created.json
+e10-cli form list-view <objId> <appId>
+e10-cli form layout read <objId>
+```
+
+重点确认字段数量与类型、明细结构、分组和显示属性、布局类型、默认台账名称与 `listId`。需要菜单时再确认菜单入口。
+
+`fields-created.json` 里的 `fieldName` **就是字段标题** —— 与设计器「字段管理」里看到的是同一个值，想核对标题建对没有看它即可。它为空就说明标题没写进去（`form add-field` 没给标题时会回落成字段名，所以正常不会空）。
+
+## 专题参考
+
+- [表单字段定义参考](ref-form-fields.md)：完整字段类型、属性、关联类型和 JSON 结构。
+- [表单布局规划](guide-form-layout-planning.md)：FLOW/EXCEL、布局样表、布局蓝图及建后调整。
+- [表单复杂编号](guide-form-serial-mark.md)：编号段、流水和代字配置。
+- [字段公式函数参考](guide-form-formula-functions.md)：公式表达式和函数。
+- [表单视图](guide-form-view.md)：默认台账、视图名称和列表配置。

package/skills/weaver-e10-builder/references/form/guide-ebuilder-filter.md

@@ -0,0 +1,73 @@
+# EBuilder 关联字段数据过滤
+
+用于配置表单中 EBuilder 关联字段的“数据过滤设置”。它决定关联弹窗里哪些目标表单数据可被选择，不是表格视图的常用搜索。
+
+## 命令
+
+```bash
+# 读取并解析当前规则
+e10-cli form ebuilder-filter get <源objId> <appId> <EBuilder字段fieldId>
+
+# 设置规则；rules 支持 JSON 字符串或 @文件
+e10-cli form ebuilder-filter set <源objId> <appId> <EBuilder字段fieldId> \
+  --rules @filter-rules.json \
+  --logic and
+
+# 清空规则
+e10-cli form ebuilder-filter clear <源objId> <appId> <EBuilder字段fieldId>
+```
+
+`--logic and|or` 表示满足全部或任一规则；`--fill-null 0|1` 控制关联值为空时是否填充。未传时保留原设置。
+
+## 规则格式
+
+每条规则统一使用目标字段的准确名称或 `fieldId`，不要手写 `filterParams`：
+
+```json
+[
+  {
+    "field": "合同名称",
+    "operator": "like",
+    "value": "测试合同"
+  },
+  {
+    "field": "合同金额",
+    "operator": "like",
+    "value": { "min": 100, "max": 500 }
+  },
+  {
+    "field": "合同状态",
+    "operator": "eq",
+    "value": ["已退回"]
+  }
+]
+```
+
+字段名重复时必须改用 `fieldId`。Select/RadioBox/CheckBox 的 `value` 可以写选项名称或 `valueKey`，CLI 会查询选项并转换；浏览类字段应写对象 ID。
+
+## 字段与条件
+
+| 目标字段 | operator | value |
+|---|---|---|
+| 固定标题 `name` | `like`、`eq`、`neq` | 单值 |
+| 固定创建者 `creator` | `eq`、`neq` | ID 或 ID 数组 |
+| 固定创建时间 `create_time` | `like` | `{"start":"...","end":"..."}` |
+| Text/TextArea/Email/Phone/Mobile | `like`、`eq`、`neq`、`null`、`notnull` | 单值；空值条件不传 value |
+| Money/Number | `like`、`null`、`notnull` | `like` 使用 `{"min":...,"max":...}` |
+| Date/DateComponent | `like`、`beq`、`seq`、`null`、`notnull` | 范围或单值 |
+| Select/RadioBox/CheckBox | `eq`、`neq`、`null`、`notnull` | 名称/valueKey 数组 |
+| Employee/Department 等浏览类 | `eq`、`neq`、`null`、`notnull` | ID 或 ID 数组 |
+
+条件来自当前设计器契约。未知组件或不支持的条件必须在写入前失败，禁止猜测。
+
+## 保存与验证
+
+CLI 会：
+
+1. 验证源字段确为已绑定目标表单的 EBuilder 字段。
+2. 从目标表单读取字段类型和选项，不按名称猜类型。
+3. 同时生成运行时 `filterParams` 和设计器回显 `filterQueryParams`。
+4. 通过字段布局接口保存，并保留其他字段布局设置。
+5. 从 `getFormLayout.fieldLayout` 独立回读；两份配置不一致即报错。
+
+当前只支持常量过滤。变量来源、未确认的新控件和无法取得选项契约的跨应用字段，不应强行写入。