weaver-e10-builder 1.6.8 → 1.6.10

package/skill-docs/references/coding/guide-page-code.md

@@ -223,6 +223,19 @@ export default function Items() {
 
 文本框、数字、日期、下拉框用原生 HTML，不要为了用组件而用组件。原型还原优先用原生 HTML + 原型 CSS，平台组件只用于人员/部门选择、上传、文件预览等必须能力。
 
+### 组件自带的数据，不要再自己查
+
+`Browser`（人员 / 部门 / 组织）、`Upload`、`FilePreview` 自带数据层：搜索、选择、回显都由组件去请求平台对应的组织、人员、文档接口。页面不要再自己调这些接口，也不要用 `formClient` 去查 —— 组织、人员、文档不属于表单数据，换了通道也拿不到同一份权限口径。
+
+分工是单向的：
+
+| 环节 | 归谁 |
+|---|---|
+| 选人 / 选部门 / 选组织、上传、预览 | 组件 |
+| 把选中的值写进表单字段、再读回来 | `formClient` |
+
+组件的 `value` 与 `onChange` 都是 `[{ id, name }]`。`onChange` 拿到后只把 `id` 写进 `values`（多值逗号串）；回显用行里的 `items[字段ID]`，见 `guide-edit-backfill.md`。
+
 ---
 
 ## 七、平台硬规则

package/skill-docs/references/common/capability-boundaries.md

@@ -1,10 +1,12 @@
 # 平台与 CLI 能力边界
 
-> 下列能力 **CLI 不支持、平台也不支持**。不要声称可以做，也不要输出操作步骤；直接告知用户「当前平台/CLI 不支持」。
+> 判「不支持」必须带证据（见下方证据等级）。**CLI 没暴露 ≠ 平台不支持**：命令表只能证明执行器没有，不能升级成平台结论。
 
-| 不支持的能力 | 说明 |
-|---|---|
-| H5 / 移动端菜单 | 移动端是独立体系（不同 URL + 不同 pageId），尚未整理，禁止编造 |
+## 已支持、容易误判为「不支持」的能力
+
+| 能力 | 结论 | 命令 |
+|---|---|---|
+| 移动端菜单（H5） | 支持。移动端与 PC 是**两套独立记录**（同一 `savePublishMenu`，只换 `terminalType`），可独立增删改；也能把 PC 端菜单整体同步到移动端 | 菜单类命令加 `--terminal mobile`；同步用 `menu sync <appId>` |
 
 ## 判断「CLI 支不支持」的正确方式
 

package/skill-docs/references/common/ref-cli-commands.md

@@ -229,8 +229,8 @@
 | `e10-cli form formula-linkage delete <appId> <objId> <ids...>` | 删除（批量）。`form field-linkage delete` 删不掉这类，会报错指路 |
 | `e10-cli form attachment-setting get <appId> <objId> [--field <字段>]` | 读取附件上传设置：不传 `--field` 看通用配置，传了看字段级覆盖。通用配置分上传目录、新建文档存储位置、新建方式、上传格式、大小限制；字段级空项表示继承通用 |
 | `e10-cli form attachment-setting set <appId> <objId> [--upload-dir] [--doc-dir] [--doc-types] [--formats] [--max-size] [--enable] [--display-tip]` | 修改通用配置。`--upload-dir` 附件/图片上传目录，`--doc-dir` 新建文档存储位置，`--doc-types` 新建方式（逗号分隔），`--formats` 上传格式（扩展名逗号串或 `@doc/@image/@video/@audio/@archive` 预设），写 `none` 清空。读—合并—写—回读校验 |
-| `e10-cli form attachment-setting set <appId> <objId> --field <字段> --upload-mode fixed\|option ...` | 修改字段级覆盖：`fixed` 配 `--upload-dir`，`option` 配 `--option-field`；`--doc-dir`/`--doc-types`/`--formats` 同样可用于字段级。字段级未写的项保持继承通用。详见 `form/guide-form-attachment-setting.md` |
-| `e10-cli form attachment-setting folders [--search <关键字>]` | 列出可用文档目录（系统知识库 + 公司/私有知识库）；`--upload-dir` / `--doc-dir` 可写目录 ID，也可写唯一名称或路径 |
+| `e10-cli form attachment-setting set <appId> <objId> --field <字段> ...` | 修改字段级覆盖，四类：上传目录（`--upload-mode fixed` + `--upload-dir`，或 `--upload-mode option` + `--option-field`）、上传格式 `--formats`、大小限制 `--max-size <MB>\|custom:<MB>\|none`、附件显示 `--show-uploader` / `--show-upload-time` / `--show-file-size` / `--forbid-batch-download` / `--display-tip`（`on`/`off`）。`--doc-dir` / `--doc-types` 只作用于通用层，带 `--field` 会报错。未写的项保持继承通用。详见 `form/guide-form-attachment-setting.md` |
+| `e10-cli form attachment-setting folders [--search <关键字>]` | 列出可用文档目录（系统知识库 + 公司/私有知识库，逐层遍历完整目录树）；`--upload-dir` / `--doc-dir` 可写目录 ID，也可写唯一名称或路径 |
 | `e10-cli form attachment-setting doc-types [--folder <目录ID>]` | 列出“新建方式设置”可选的文档类型（html / WORD / markdown / UPLOAD） |
 | `e10-cli form formula set <objId> <appId> --target <fieldId> --expression "<公式>"` | 给 eb 表字段**绑定**计算公式。`{主表.字段}` / `{明细表名.字段}`（平台存储格式）与设计器的 `[字段]` 两种写法都收，保存前归一化成花括号再下发。`--name`、`--return-type`（不传按目标字段类型推断）。**`--formula-id <id>` 原地更新已有公式**（平台认这个字段：不新建、返回 id 不变、字段绑定不受影响），不传才是新建；更新时不传 `--name` 会沿用原公式名，不会被改成「公式_&lt;时间戳&gt;」。另：`formula get <id>` / `list <objId> <appId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错**不报错**只是算不对，见 `references/form/guide-form-formula-functions.md` |
 
@@ -452,8 +452,9 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli menu list <appId> [--terminal pc\|mobile]` | 列出当前Ebuilder应用下的菜单。**递归展开嵌套菜单**（如「设置 → 个人设置 → 个人菜单设置」），列表即全量 —— 在这里没找到就是真没有，不必再怀疑被折叠。`--raw [菜单ID]` 打印菜单的**原始报文**（读侧记录与写侧报文形状不同，核对某一项到底存了什么时看它）。PC 与移动端是**两套独立菜单**，移动端要加 `--terminal mobile` |
+| `e10-cli menu sync <appId> [--force]` | **把 PC 端菜单整体同步到移动端**（平台原生能力）。同步**覆盖**移动端已配置的菜单：移动端单独加过、PC 上没有的会被清掉。范围是 PC 的**业务菜单**（目录/外链/嵌套都带过去，顺序与层级照搬），「设置」「回收站」等系统菜单不参与。命令保存后回读移动端，与 PC 逐条比对路径、层级与顺序，对不上直接报错并点名缺失/多余项。PC 端没有业务菜单时拒跑（等于清空移动端），确认清空才加 `--force` |
 | `e10-cli menu rename <appId> <菜单ID或名称> <新名> [--terminal pc\|mobile]` | 重命名已有菜单（含嵌套菜单）。名称在应用内重复时必须改用 ID，命令会列出候选让你选。平台系统菜单（回收站/设置等）不能改。**改父级用 `menu move`**；**改打开方式用 `menu open-mode`** |
-| `e10-cli menu add <name> <path> <appId> [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 将页面加入左侧导航（LINK 类型，URL path）。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。`--parent` 挂到父菜单下做子菜单（缺省 `0`=顶级）。**排序**：平台按同级 `showOrder` 升序显示，新建默认 1（落在最后）；`--first` 排到同级最前，`--show-order <n>` 指定任意排序号。**打开方式**：缺省「默认窗口」，`--open-mode new-window` 点击后在新窗口打开。**建完会回读确认**菜单 ID、层级、排序与打开方式；回读不到就报错退出，不谎报成功 |
+| `e10-cli menu add <name> <path> <appId> [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile] [--as-link]` | 将页面加入左侧导航（LINK 类型，URL path）。**对象页面地址默认拒绝**：`/sp/ebdfpage/viewport/<viewId>`（台账数据列表页）与 `/sp/ebdfpage/card/1/<objId>/0`（表单新建页）当外链写会降级成 LINK —— 设计器里「链接地址」只显示一串文本、移动端打开是空列表；台账入口用 `menu add-table`、表单发起入口用 `menu add-start`。确认就是外链才加 `--as-link`。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。`--parent` 挂到父菜单下做子菜单（缺省 `0`=顶级）。**排序**：平台按同级 `showOrder` 升序显示，新建默认 1（落在最后）；`--first` 排到同级最前，`--show-order <n>` 指定任意排序号。**打开方式**：缺省「默认窗口」，`--open-mode new-window` 点击后在新窗口打开。**建完会回读确认**菜单 ID、层级、排序与打开方式；回读不到就报错退出，不谎报成功 |
 | `e10-cli menu add-dir <appId> <name> [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--terminal pc\|mobile]` | 加**上级目录**菜单 —— **空链接**的纯分类节点，只用来给子菜单分组，点它不跳页面。设计器里建「上级目录」就是这个（存下来 `pageType=EMPTY`、`pageId/pageName` 空、**没有 `menuUrl`**、`menuType="0"`）。`--parent` 支持菜单 ID 或名称（缺省 `0`=顶级），排序参数同上。**建完回读确认**并核对层级与排序，另外**核对 `pageType` 确实是 `EMPTY`** —— 不是就说明链接没留空，直接报错而不是谎报成功。⚠ 与 `menu add` 的区别：要指向某个页面的父菜单（点得开）用 `menu add`，纯分组的用这条 |
 | `e10-cli menu add-table <appId> <objId> [name] [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 给表单加**台账菜单**（VIEWPORT，指向数据列表页）。`form create --menu` 才自动加（默认不加），此处用于事后补加。**`--parent` 挂到某个父菜单下做子菜单**（缺省 `0`=顶级；既收菜单 ID 也收名称，同名多条会报错并列 ID），`--first`/`--show-order` 控制同级顺序，`--open-mode` 选打开方式。**建完回读确认**，并**核对层级与排序** —— 只确认菜单存在不够，`pid` / `showOrder` 没生效时菜单照样建出来、只是跑到顶级或最后 |
 | `e10-cli menu add-start <appId> <formObjId> [name] [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 给流程绑定的表单加**发起菜单**（LAYOUT，指向表单新建页，点开触发流程）。`workflow create --menu` 才自动加（默认不加）。`--parent` / 排序参数同上，`--open-mode` 选打开方式。**建完回读确认**并核对层级与排序 |

package/skill-docs/references/form/guide-field-linkage.md

@@ -241,13 +241,21 @@ e10-cli form field-linkage add <appId> <objId> \
   --precondition "订单号:不为空"
 ```
 
+## 系统字段（数据ID / 标题 / 创建者等）
+
+- **可以带出**：`--query-fields 数据ID`、`--assign 数据ID=备注`、`--basis` 里的源字段都支持系统字段。
+- **不能当触发字段或赋值目标**：这两处写的是「表单数据」本身，系统字段只读；命令会直接报错并提示它只能用于带出。
+- **条件里不支持**：`--condition` / `--precondition` 只认业务字段，系统字段会明确报错。
+
+查询结果里的变量名由平台 ESB 数据源字段表给出：业务字段是 `field_<字段id>`，系统字段是裸 id（「数据ID」= `id`）。命令会自动取，不用手写变量名。
+
 ## 注意事项
 
 1. **三种明细模式**：添加/覆盖/更新由 `--detail-mode` 决定；「删除再添加 / 累计添加」是另一个开关 `--detail-add`。
 2. **明细行依据**决定行匹配：写入明细表时，依据值相同的行按模式处理。
 3. **赋值前提引用字段**：`@字段名` 先按查询结果字段解析（`source` = 查询节点），找不到再按本表字段（`source` = 触发事件）。
 4. **算子与动作流筛选同源**：按字段类型族校验，不支持的算子会直接报错。
-5. **FormData 引用格式**：本表字段 `FormData.<本表formId>.<字段id>`；查询结果 `FormData.<源表objId>[].field_<字段id>`。
+5. **FormData 引用格式**：本表字段 `FormData.<本表formId>.<字段id>`；查询结果业务字段 `FormData.<源表objId>[].field_<字段id>`，系统字段 `FormData.<源表objId>[].<裸id>`（如数据ID 为 `[].id`）。
 6. **--source-form 的 objId 是表单 objId**（不是 formId），CLI 内部自动解析。
 7. **联动名称**：不传 `--name` 时自动生成 `<本表名>.<触发字段>→<源表名>.<条件字段>`。
 8. **SQL 联动类型尚未覆盖**：只支持「动作流联动」（`linkageType=template`）；设计器里的「SQL可视化配置 / SQL联动」两条支路尚未实现。

package/skill-docs/references/form/guide-form-attachment-setting.md

@@ -2,15 +2,20 @@
 
 表单「附件设置」页控制附件文件存在哪里、能传什么、以及由附件创建文档时落在哪个目录。设置分**通用配置**和**字段级覆盖**两层：字段级未显式覆盖的项继承通用配置。
 
-## 三层对应关系
+## 两层对应关系
 
 | 界面 | 通用配置 | 字段级覆盖 |
 |---|---|---|
 | 附件/图片上传目录 | `folderId` + `folderIdBrowserValue` | 同名字段；`folderSelectType` 区分固定目录 / 选项关联 |
-| 关联文档 → 新建方式设置 | `addTypeConfig.types` | `docAddTypeConfig` |
-| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | `docFixedDirectoryConfig` |
-| 上传格式 | `customLimitFormat` | 同名字段 |
-| 大小限制 / 启用 / 提示语 | `attmentSizeLimit` / `enableState` / `displayTip` | 同名字段 |
+| 关联文档 → 新建方式设置 | `addTypeConfig.types` | **无字段级**，只作用于通用层 |
+| 关联文档 → 新建文档存储位置 | `fixedDirectory.folderValue` | **无字段级**，只作用于通用层 |
+| 上传格式 | `customLimitFormat` | 同名字段；需同时标记 `limitType=1` |
+| 大小限制 | `attmentSizeLimit` | 同名字段；需同时标记 `sizeType=1` |
+| 附件显示（上传人/上传时间/文件大小等） | `displayTip` / `enableState` | `attachUploadUser` / `attachUploadTime` / `attachFileSize` / `forbinBatchDownload`；需同时标记 `otherType=1` |
+
+字段级覆盖只有**四类**：上传目录、上传格式、大小限制、附件显示。命令会按类型逐个保存，并把其余类型的既有覆盖一起带上，改一项不会把其他覆盖抹掉。
+
+**大小限制的取值**：`9` = 未选择（继承通用），`6` = 自定义（数值在 `customAttmentSize`），其余数字就是 MB 数。看到 `9` 不要当成 9MB。
 
 两个目录不要混：
 
@@ -63,20 +68,34 @@ e10-cli form attachment-setting set <appId> <objId> \
 e10-cli form attachment-setting set <appId> <objId> \
   --field <附件字段> --upload-mode option --option-field <选项字段>
 
-# 字段级的新建方式 / 存储位置 / 上传格式
+# 字段级上传格式 / 大小限制 / 附件显示
 e10-cli form attachment-setting set <appId> <objId> \
-  --field <附件字段> --doc-dir <目录ID> --doc-types WORD,markdown --formats @image
+  --field <附件字段> --formats @doc --max-size 15 \
+  --show-uploader on --show-upload-time on
+
+# 自定义大小、恢复继承
+e10-cli form attachment-setting set <appId> <objId> --field <附件字段> --max-size custom:20
+e10-cli form attachment-setting set <appId> <objId> --field <附件字段> --max-size none --formats none
 ```
 
 - `--field` 给了才是字段级覆盖；不给就是通用配置。
 - 固定目录必须同时给 `--upload-dir`；选项关联必须同时给 `--option-field`。
 - 字段级只写给出的项，未给出的项保持继承通用。
-- `--max-size` / `--enable` / `--display-tip` 当前只支持通用配置。
+- `--doc-dir` / `--doc-types` **只在通用层生效**；带 `--field` 会直接报错，不会静默丢弃。
+- `--enable` 只作用于通用层。
+
+| 字段级参数 | 说明 |
+|---|---|
+| `--formats` | 上传格式；`none` 恢复继承 |
+| `--max-size` | MB 数（如 `15`）、`custom:<MB>` 自定义、`none` 恢复继承 |
+| `--show-uploader` / `--show-upload-time` / `--show-file-size` | 附件区显示上传人 / 上传时间 / 文件大小 `on` / `off` |
+| `--forbid-batch-download` | 禁止批量下载 `on` / `off` |
+| `--display-tip` | 提示语 `on` / `off` |
 
 ## 查询目录与新建方式
 
 ```bash
-# 列出可用文档目录（系统知识库 + 公司/私有知识库）
+# 列出全部文档目录（系统知识库 + 公司/私有知识库，逐层遍历）
 e10-cli form attachment-setting folders
 e10-cli form attachment-setting folders --search 合同
 
@@ -84,12 +103,12 @@ e10-cli form attachment-setting folders --search 合同
 e10-cli form attachment-setting doc-types
 ```
 
-`folders` 输出目录 ID、标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或路径。名称匹配到多个时命令会报错并要求改用 ID。
+`folders` 输出目录 ID、完整路径标题和类型；`--upload-dir` / `--doc-dir` 可以直接写 ID，也可以写唯一名称或完整路径。名称匹配到多个时命令会报错并要求改用 ID。
 
 ## 注意事项
 
 1. **目录 ID 是长数字**，按字符串处理，不要转成 Number。
-2. **读回形状与写入形状不同**：读回的上传目录只在 `folderIdBrowserValue[0]` 里，写报文才带顶层 `folderId`；命令内部会补齐，不要手工拼报文。
-3. **保存顺序**：先字段级列表，再通用配置；两条都成功后再回读校验。
+2. **读回形状与写入形状不同**：字段列表回读只给 `folderId`，标题在单字段回读的 `folderIdBrowserValue` 里；命令内部会补齐，不要手工拼报文。
+3. **字段级保存按类型分开**：上传目录、格式、大小、附件显示各是一次保存，每次都要带上当前完整状态与四类覆盖标记；只提交单项会把其他覆盖抹掉。命令已处理，不要用其它方式单独拼单类型报文。
 4. **字段级覆盖优先于通用配置**：字段级把上传目录设成固定目录但没选具体目录，会覆盖掉通用的有效目录。
 5. 命令在保存后会逐项回读；回读不一致会直接报错，不会静默成功。

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -76,7 +76,7 @@ e10-cli form layout save-as-template <objId> --view-id <布局ID> --name <模板
 e10-cli form layout save-as-template <流程表单formId> --module workflow --view-id <布局ID> --name <模板名>
 ```
 
-此操作从指定布局读取 `formStyle` 并创建流式样式模板，默认禁用；需要立即可选用时加 `--enabled`。业务字段和布局组件不会一起保存。表格式布局不能用这条命令直接另存；模板的其他操作见[布局样式模板总览](form-template/style-templates.md)。
+此操作从指定布局读取 `formStyle` 并创建流式样式模板，默认禁用；需要立即可选用时加 `--enabled`。业务字段和布局组件不会一起保存。表格式布局不能用这条命令直接另存；模板的其他操作见[布局样式模板总览](layout/template/template-guide.md)。
 
 ## 图片与 Excel 源样式还原
 

package/skill-docs/references/form/layout/code-block/code-block-guide.md

@@ -27,7 +27,7 @@
 
 | 需求范围 | 入口 | 特点 |
 |---|---|---|
-| 只对某个布局、某个终端生效 | 布局源码：`form code layout set` / `wf-form code layout set` | 随布局和终端加载；CSS 自动限定在 `#ebpage_<pageId>`；JS 带 `pageId` 生效条件 |
+| 只对某个布局、某个终端生效 | 布局源码：`form code layout set` / `wf-form code layout set` | 随布局和终端加载；CSS 默认以 `#ebpage_<pageId>` 为作用域，需要覆盖表头等页面根外元素时可显式选 `--css-scope form` 并限定目标布局；JS 带 `pageId` 生效条件 |
 | 同一表单的所有布局/终端都要生效 | 表单级 ecode：`form code ecode ...` | 不随布局切换；需要自己判断当前表单/数据上下文 |
 | 应用级或全局页面逻辑 | 全局 ecode / 页面入口 | 不在本指南的表单布局命令范围内；使用 `onFormReady` 等全局事件并按 formId/module 限定 |
 
@@ -127,16 +127,16 @@ recalculate();
 
 | 范围 | 读取 | 写入 |
 |---|---|---|
-| EB 表单布局 | `form code layout read <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE` | `form code layout set <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE --js <文件> [--css <文件>]` |
-| 原生工作流程表单布局 | `wf-form code layout read <formId> --layout-id <id> --terminal PC|MOBILE` | `wf-form code layout set <formId> --layout-id <id> --terminal PC|MOBILE --js <文件> [--css <文件>]` |
+| EB 表单布局 | `form code layout read <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE` | `form code layout set <objId> --app-id <appId> --layout-id <id> --terminal PC|MOBILE (--js <文件> 或 --css <文件>) [--css-scope page\|form]` |
+| 原生工作流程表单布局 | `wf-form code layout read <formId> --layout-id <id> --terminal PC|MOBILE` | `wf-form code layout set <formId> --layout-id <id> --terminal PC|MOBILE (--js <文件> 或 --css <文件>) [--css-scope page\|form]` |
 | EB 表单级 ecode | `form code ecode list <objId> --app-id <appId>`；`form code ecode read <objId> <ecodeId> --app-id <appId>` | `form code ecode add <objId> --app-id <appId> --name <名称> --js <文件> [--css <文件>]`；`form code ecode edit <objId> <ecodeId> --app-id <appId> --js <文件>`；`form code ecode status <objId> <ecodeId> --app-id <appId> --state on|off` |
 | 原生工作流程表单级 ecode | `wf-form code ecode list <formId>`；`wf-form code ecode read <formId> <ecodeId>` | `wf-form code ecode add <formId> --name <名称> --js <文件> [--css <文件>]`；`wf-form code ecode edit <formId> <ecodeId> --js <文件>`；`wf-form code ecode status <formId> <ecodeId> --state on|off` |
 
 `set`/`add`/`edit` 保存后会读回确认；`edit` 可单独提供 `--js` 或 `--css`，保留另一部分。先用 `read` 核对已有代码和作用范围。
 
-布局代码需要差异预览时，用独立的 `form code layout preview/apply` 或 `wf-form code layout preview/apply`。两步传相同的布局 ID、终端和 `--js`／`--css` 文件；预览使用 `--out <文件>` 保存完整报告，应用时传 `--preview @<文件>`。预览会编译候选代码并列出被替换的 JS/CSS 原文；应用会检查源文件和布局未变化，单次保存后独立回读。只传一种文件时另一种代码保持不变。无源码变化时不发送保存请求。表单级 ecode 仍使用上表的独立命令。
+布局代码需要差异预览时，用独立的 `form code layout preview/apply` 或 `wf-form code layout preview/apply`。两步传相同的布局 ID、终端、`--js`／`--css` 文件及 `--css-scope page|form`；预览使用 `--out <文件>` 保存完整报告，应用时传 `--preview @<文件>`。预览会编译候选代码并列出被替换的 JS/CSS 原文；应用会检查源文件和布局未变化，单次保存后独立回读。只传一种文件时另一种代码保持不变。无源码变化时不发送保存请求。表单级 ecode 仍使用上表的独立命令。
 
-布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件，并把 CSS 选择器限定在当前 `#ebpage_<pageId>` 内。需要由 JS 动态插入且使用布局 CSS 的元素，应挂在该页面容器内；挂到 `document.body` 的元素不受这份布局 CSS 修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果。
+布局源码写入时，CLI 按当前终端页面的 `pageId` 生成 JS 生效条件。CSS 默认为 `--css-scope page`，普通规则编译到 `#ebpage_<pageId>` 内；当表头等目标位于页面根外、表单根内时，可用 `--css-scope form`，但源码选择器还须限定当前布局或页面，不能把表单根范围误当成布局隔离。挂到表单根外（例如 `document.body`）的弹层不受这两种作用域修饰。写入后用 `layout read` 核对 JS/CSS 原文、页面条件和编译结果，再打开实际表单页面检查运行效果；固定类名和盒模型处理见[布局 CSS 指南](layout-css.md)。
 
 布局 CSS 的可设置内容、表格式与流式布局的选择器边界及完整写入示例，见[表单布局 CSS 编写指南](layout-css.md)。
 

package/skill-docs/references/form/layout/code-block/layout-css.md

@@ -2,6 +2,8 @@
 
 本篇用于**已创建的表单布局**：给指定布局的 PC 或移动端页面写 CSS。适用于表单引擎表单与流程表单的表格式、流式布局。表格式高级**模板**的 CSS 属于另一份配置，模板的网格和重复标记也不会由这里的 CSS 生成。
 
+按需求查阅：页面背景、表头或作用域见[作用范围和写入](#作用范围和写入)；已知组件类名见[固定类名索引](#固定类名索引)；填色不满、越框或层叠问题见[盒模型与背景层](#盒模型与背景层)；明细表见[流式 PC 明细表](#流式-pc-明细表标题格与单元格)和[表格式布局的明细表](#表格式布局的明细表)；不生效时按[检查顺序](#检查顺序)排查。
+
 ## 能设置什么
 
 | 目标 | CSS 可处理的内容 | 先确认的配置或结构 |
@@ -16,7 +18,9 @@ CSS 只改变已有元素的呈现。字段顺序、主表与明细表的迭代
 
 ## 作用范围和写入
 
-布局 CSS 按**布局 ID + 终端**保存。CSS 文件中写普通选择器，例如 `.ebpage`；CLI 会给普通规则加当前页面的 `#ebpage_<pageId>` 前缀。不要自己写这个页面 ID，也不要复制模板编译后的 `#widget_…`、`.cell_…` 等生成标识。`@media`、`@supports` 中的普通选择器同样会加作用域；`@keyframes` 保持原样。需要被这份 CSS 修饰的动态元素应放在布局页面容器内，挂在 `document.body` 下的弹层不在此作用域内。
+布局 CSS 按**布局 ID + 终端**保存。`--css-scope page` 为默认值：CLI 将普通规则编译为 `#ebpage_<pageId> <选择器>`，适合页面容器**内部**的元素。表头等元素若位于 `#ebpage_<pageId>` 的外部或与其同级，默认作用域无法选中；此时可明确使用 `--css-scope form`，编译为 `#form_<formId> <选择器>`。代码仍保存在指定布局和终端，但 `form` 根范围较宽，源码选择器必须再限定目标布局或页面，避免影响同一表单的其他布局。若 CSS 同时包含表头和内容区规则，切换作用域时应检查**整份文件**，不能只改一条规则。
+
+作用域前缀是祖先选择器，不会使后代规则反向选中祖先或兄弟元素，也不会命中挂到布局根之外的弹层。默认 `page` 模式下，源码应写页面根**内部**的普通选择器；不要把 `.ebpage`、`#ebpage_<pageId>` 作为后代选择器原样写入，因为编译后会形成 `#ebpage_<pageId> .ebpage` 或重复根 ID，无法匹配根元素本身。`form` 模式需要定位当前布局时，可以在这份专属 CSS 中使用从 `layout read` 和 DOM 获取的实际布局类或页面根 ID；这些动态标识不能写进可复用模板。`@media`、`@supports` 内的普通规则也会加前缀，`@keyframes` 保持原样。
 
 ```bash
 # 先读取当前 PC 布局代码，保存现有 CSS 供修改
@@ -25,29 +29,79 @@ e10-cli form code layout read <表单objId> --app-id <应用ID> --layout-id <布
 # 将 CSS 文件写入该 PC 布局；JS 保持原状
 e10-cli form code layout set <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC --css <CSS文件>
 
+# 当目标位于页面根之外、但仍在表单根内时，显式改用 form 作用域
+e10-cli form code layout set <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC --css <CSS文件> --css-scope form
+
 # 写入后回读
 e10-cli form code layout read <表单objId> --app-id <应用ID> --layout-id <布局ID> --terminal PC
 ```
 
-流程表单对应 `e10-cli wf-form code layout read/set <formId> --layout-id <布局ID> --terminal PC|MOBILE [--css <CSS文件>]`，不需要 `--app-id`。移动端把 `--terminal` 改为 `MOBILE`，并针对该终端另写一份 CSS。`set --css` **整份替换**该布局、该终端原有 CSS；写入前先读出现有内容并合并到文件中。只传 `--css` 时已有 JS 保留。回读会核对源码和编译结果，随后仍需打开实际表单检查视觉效果。
+流程表单对应 `e10-cli wf-form code layout read/set <formId> --layout-id <布局ID> --terminal PC|MOBILE [--css <CSS文件>] [--css-scope page|form]`，不需要 `--app-id`。移动端把 `--terminal` 改为 `MOBILE`，并针对该终端另写一份 CSS。`set --css` **整份替换**该布局、该终端原有 CSS；写入前先读出现有内容并合并到文件中。只传 `--css` 时已有 JS 保留。回读会核对源码和编译结果，随后仍需打开实际表单检查视觉效果。
 
 需要先审阅差异时，使用独立的 `preview/apply` 命令。先读出现有 CSS 并合并到候选文件，再生成预览；预览文件包含原文与候选全文、源码指纹及编译结果指纹。执行时沿用同一个 CSS 文件，布局或文件发生变化会阻断写入。只传 CSS 时 JS 保持原值；保存后独立回读源码与编译结果。
 
 ```bash
-e10-cli form code layout preview <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --out code-preview.json
-e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --preview @code-preview.json --out code-result.json
+e10-cli form code layout preview <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --css-scope page --out code-preview.json
+e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal PC --css layout.css --css-scope page --preview @code-preview.json --out code-result.json
+```
+
+两步必须使用相同的 `--css-scope`；若选 `form`，两步都改为 `--css-scope form`。流程表单把命令前缀换为 `wf-form code layout`，目标传 `formId`。两种方式都适用于表格式和流式布局；移动端改用 `--terminal MOBILE` 并单独预览。`read/set` 旧命令保持可用。
+
+`form` 模式的源码可以同时修饰表头和内容区，但每条规则需明确落点。下例的 `PAGE_ID` 必须替换成目标终端页面的真实 `pageId`，不是布局 ID；表头类的拼写以目标运行页为准：
+
+```css
+/* 表头在页面根外：用表头自带的布局类限定。 */
+.weapp-form-header.weapp-form-layout__PAGE_ID { background-color: #f3f7ff; }
+
+/* 内容区仍限定到该页面根，避免碰到同表单其他布局。 */
+#ebpage_PAGE_ID .weapp-form-widget__Collapse { border-radius: 6px; }
 ```
 
-流程表单把命令前缀换为 `wf-form code layout`，目标传 `formId`。两种方式都适用于表格式和流式布局；移动端改用 `--terminal MOBILE` 并单独预览。`read/set` 旧命令保持可用。
+## 固定类名索引
+
+以下是 PC 表单布局常见的运行页类名。同一字段在编辑、只读、必填和不同布局中可能增减内层节点；通常先用“组件类型外壳 + 内部类”限定目标。`#widget_<字段ID>`、`#ebpage_<pageId>`、`.weapp-form-layout__<pageId>` 中的数字由资源生成，不是固定类名。`--` 与 `__` 不可互换，例如字段列外壳是 `.weapp-form-widget--column`。
+
+| 想修改的区域 | 可直接查找的类名/层级 | 应修改的层与注意点 |
+| --- | --- | --- |
+| 页面与布局 | `.weapp-form`、`.weapp-form-header`、`.weapp-form-content`、`.weapp-de-flow-render`、`.ebdpage-content`、`.weapp-ebpv-styled-flow` | 表头可能在 `#ebpage` 外；页面底色先找实际绘制背景的层。`.ebdpage-content` 含字母 `d`。 |
+| 通用字段 | `.weapp-form-widget`、`.weapp-form-field`、`.weapp-form-widget--column`、`.weapp-form-has-custom-style` | 字段外壳可能自带不透明背景，覆盖上层分组底色；不要把列外壳写成 `__column`。 |
+| 字段标题与内容 | `.weapp-form-widget-title`、`.weapp-form-widget-content`、`.weapp-form-widget-content--FLOW`、`.weapp-form-widget-content-container` | 内容层可有左右 padding，内部容器还可能有上下 padding、边框；要填满可见框，应分别判断边框和内边距所在层。 |
+| 折叠分组 | `.weapp-form-widget__Collapse`、`.weapp-form-collapse-wrapper`、`.weapp-form-collapse`、`.ui-collapse-panel`、`.ui-collapse-panel__title`、`.ui-collapse-panel__content-box`、`.ui-collapse-panel__content` | 整卡片、标题和内容为不同盒子；若字段外壳有白底，还需单独处理字段外壳。 |
+| 单行文本／数值／金额 | `.weapp-form-widget__Text`、`.weapp-form-widget__Number`、`.weapp-form-widget__Money` 下的 `.weapp-form-input-wrapper` 与 `input` | 背景可被内部 input 覆盖；数字右对齐需作用到实际输入节点。 |
+| 多行文本 | `.weapp-form-widget__TextArea .weapp-form-textarea-wrapper textarea` | 内部 textarea 的背景、padding、高度与外层内容盒分别处理。 |
+| 日期／下拉 | `.weapp-form-widget__Date .weapp-form-date-wrapper`、`.weapp-form-widget__Select .weapp-form-select-wrapper`、`.ui-select-input` | 日期输入节点可能遮住 wrapper 底色；下拉可见边框也可能在 `.weapp-form-widget-content-container`。保留日历图标、下拉箭头。 |
+| 单选／复选 | `.weapp-form-widget__RadioBox`、`.weapp-form-widget__CheckBox`、`.weapp-form-option-wrapper` | 选项 wrapper 不一定撑满内容盒；要让整框填色，检查 wrapper 宽度和 `box-sizing`，不能只给单个选项上色。 |
+| 人员等浏览 | `.weapp-form-widget__Employee`、`.weapp-form-widget-content-container`、`.ui-browser` | 字段本体和弹窗可能不在同一作用域；不以字段底色规则改弹窗。 |
+| 附件／图片 | `.weapp-form-file-upload-wrapper`、`.weapp-form-image-upload`、`.weapp-form-image-upload-wrapper` | 文件区与图片缩略图是不同结构；图片上传可直接在页面作用域下定位 `.weapp-form-image-upload`，先检查图像字段是否真有该节点。 |
+| 流式明细 | `.weapp-form-detail-table--FLOW`、`.weapp-form-detail-table-title`、`.ui-table-grid-thead th.weapp-form-detail-table-column`、`.weapp-form-detail-table-field-header` | 整列表头背景在 `th`，文字在内层；滚动表头、数据行另核对。 |
+| 表格式明细 | `.weapp-form-detail-table-wrapper`、`.excelTableView-content-excel-table`、`.excelTableView-content-excel-table-fixed-first-row` | 普通内容表和固定表头可能分开；行色写到 `td`，同时看列宽与悬停。 |
+
+先按索引使用固定类名；只有目标页面不具备该节点、出现不同终端结构，或样式仍被其他盒子覆盖时，才沿 Elements 树定位新层。设计器的 `.weapp-formbuilder-*` 不直接当作运行页类名。更多组件类型的源码线索见[表格式高级模板 CSS 指南](../template/advanced-css.md)，但模板与布局源码不是同一配置。
+
+## 盒模型与背景层
+
+一个字段通常经过“分组卡片 → 字段外壳 → 内容层 → 内部容器 → 控件 wrapper → `input`/`textarea`”多层。`margin` 在边框外，`padding` 在元素边框内，元素的背景会绘制到自身 padding 区；子元素若有不透明背景，又会盖住父元素。想让颜色填满**可见框**，先确定画边框的元素，再检查它的 padding 和内部控件，而不是直接给整张字段外壳或内容层铺色。
+
+流式字段的 `.weapp-form-widget-content` 可带左右间距，`.weapp-form-widget-content-container` 可另有上下 padding 与边框。若目标布局确需取消框内留白，可只对目标字段类型调整对应层，不对所有字段一刀切。单选／复选的选项 wrapper 若只包裹文字，设 `width:100%; box-sizing:border-box` 才能让其底色覆盖整框；日期等控件则需核对内部 `input` 是否另有白底。修改 padding 后检查必填标记、图标、焦点边框、下拉与弹层的点击区域及控件高度。
+
+```css
+/* 下面只示范按组件类型限定层级；按目标页面的盒模型决定是否需要这些调整。 */
+.weapp-form-widget__Select .weapp-form-widget-content--FLOW { padding-inline: 0; }
+.weapp-form-widget__Select .weapp-form-widget-content-container { padding: 0; }
+.weapp-form-widget__RadioBox .weapp-form-option-wrapper,
+.weapp-form-widget__CheckBox .weapp-form-option-wrapper { width: 100%; box-sizing: border-box; }
+```
+
+若改色超出边框，通常是选中了比画边框的盒子更外侧的容器；撤回那层背景，改定位实际边框及其内部。若颜色只在底边露出，检查内部输入节点是否覆盖了 wrapper。若分组仅标题变色，沿 `.ui-collapse-panel` 到字段外壳逐层查不透明背景。不要靠不断追加 `!important` 猜测层级。
 
 ## 通用写法
 
 ### 主题与选择状态
 
-页面根节点存在 `.ebpage` 时，可集中设置主题变量；变量只对读取它的组件起作用。颜色和变量名称可参考表格式高级模板的 [CSS 指南](../template/advanced-css.md)，但应在目标布局验证实际状态。
+主题变量应设置在能包含目标控件的实际元素上，且只对读取它的组件起作用。默认 `page` 作用域不能用 `.ebpage` 去选中 `#ebpage_<pageId>` 本身；可将变量放在页面根**内部**的容器，或在 `form` 作用域下精确选中页面根。颜色和变量名称可参考表格式高级模板的 [CSS 指南](../template/advanced-css.md)，但应在目标布局核对变量是否被组件读取。
 
 ```css
-.ebpage {
+.ebdpage-content {
   --primary: #347fcb;
   --btn-primary-hover-bg: #286daf;
   --checkbox-active-border-color: var(--primary);
@@ -60,7 +114,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ### 字段输入区域
 
-先看实际元素是输入框自身画线，还是其外层包裹层画线。以下是**表格式 PC 页面已识别的组件路径**，仅在目标布局存在相同 DOM 时复用；流式布局先检查对应组件结构再写选择器。
+先看实际元素是输入框自身画线，还是其外层包裹层画线。以下是**表格式 PC 常用的组件路径**，仅在目标布局存在相同 DOM 时复用；流式布局优先查上面的固定类名索引。
 
 ```css
 /* 文字输入：只清除控件边框，保留表格单元格边线。 */
@@ -79,7 +133,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ### 流式 PC 布局：分组与下拉框
 
-已确认的流式 PC 页面以 `.weapp-ebpv-styled-flow` 标识布局容器。分组使用 `.weapp-form-widget__Collapse`；标题下方的蓝线是 `.weapp-form-collapse .ui-collapse-panel__title` 的 `border-bottom`，已观察到 `1px solid #1C69DB`。这条线也可由分组标题的布局样式设置产生；需要统一外观时优先检查分组标题配置，不要把设计器选中时的蓝色虚线框当成运行时边框。
+流式 PC 布局可从 `.weapp-ebpv-styled-flow` 定位内容容器。分组使用 `.weapp-form-widget__Collapse`；标题下方的线可由 `.weapp-form-collapse .ui-collapse-panel__title` 的 `border-bottom` 或分组标题的布局样式生成。需要统一外观时先检查内置分组标题设置，不要把设计器选中时的虚线框当成运行时边框。若要改变**整张分组卡片**，需区分外壳、面板、标题、内容和字段外壳；给标题着色不会自动改变卡片内容背景。
 
 下拉字段外层带 `.weapp-form-widget__Select`。实际画出灰色外框的是其 `.weapp-form-widget-content-container`：四侧计算样式均为 `1px solid #E2E2E2`。内部的 `.ui-select-input` 和 `.ui-input-wrap.ui-select-input` 四侧边框为 `none`；只修改内部节点的 `border` 无法替换可见外框。若目标布局需要给下拉外框单独配色，可在布局 CSS 中限定字段类型：
 
@@ -89,11 +143,37 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 }
 ```
 
-此选择器依据页面 DOM 和计算样式确定，写入后的覆盖效果仍需在目标布局检查。不要把具体 `#widget_…` 或 `.weapp-form-layout_…` 的生成 ID 写进可复用规则。流式明细表已观察到 `.weapp-form-detail-table--FLOW`、`.weapp-form-detail-table-field-header` 和 `td.weapp-form-detail-table-column`；表头和格线的绘制节点尚需分别核对，不能直接套用表格式的 `.excelTableView-content-excel-table` 规则。
+下拉外框可能由该层绘制，写入后仍需检查实际计算样式。不要把具体 `#widget_…` 或 `.weapp-form-layout_…` 的生成 ID 写进可复用规则。流式明细表应按运行页的表头结构选择 `th`，不要照搬设计器中的结构。
+
+### 流式 PC 明细表：标题格与单元格
+
+在流式明细的运行页，`.weapp-form-detail-table--FLOW` 限定明细表，`.weapp-form-detail-table-title` 是明细标题。表头整格通常由 `.ui-table-grid-thead` 中的 `th.weapp-form-detail-table-column` 绘制，标题文字位于其子元素 `.weapp-form-detail-table-field-header`。要设置整格背景和下沿色带，应改 `th`，不要只改内部文字层：
+
+```css
+.weapp-form-detail-table--FLOW .weapp-form-detail-table-title {
+  color: #154a78;
+  font-weight: 700;
+}
+
+.weapp-form-detail-table--FLOW .ui-table-grid-thead th.weapp-form-detail-table-column {
+  background-color: #dff3ea !important;
+  color: #145c43;
+  box-shadow: inset 0 -3px #168a61 !important;
+  border-left: 1px solid #8dcbb0;
+}
+
+.weapp-form-detail-table--FLOW .ui-table-grid-thead th.weapp-form-detail-table-column .weapp-form-detail-table-field-header {
+  background-color: transparent;
+  color: inherit;
+  border: 0;
+}
+```
+
+该规则针对字段表头，不改变左侧勾选列。使用到其他表单时，检查目标页面是否采用相同运行时结构；保存后检查表头和滚动区域。默认 `page` 模式会自动加 `#ebpage_<pageId>` 作用域；若已选 `form`，则在源码中自行限定页面根。
 
 ### 表格式布局的明细表
 
-以下规则针对已识别的表格式 PC 明细表结构。流式明细表只有在实际存在这些类和表格元素时才可复用。
+以下规则针对表格式 PC 明细表结构。流式明细表只有在实际存在这些类和表格元素时才可复用。
 
 ```css
 .weapp-form-detail-table-wrapper .excelTableView-content-excel-table tbody tr[data-id]:nth-child(even) > td {
@@ -113,7 +193,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 ## 常见样式场景
 
-以下按视觉目标选择写法。除了前文已识别的表格式组件路径，`.wea-form-*`、`.wea-detail-*` 等类名只作结构示意；使用前要从目标布局的实际 DOM 中取得选择器。优先用布局样式、排版、网格和字段属性完成平台已有的设置，CSS 负责其余视觉细节。
+以下按视觉目标选择写法。除了前文列出的固定组件路径，`.wea-form-*`、`.wea-detail-*` 等类名只作结构示意，不能直接作为 E10 表单运行页选择器。优先用布局样式、排版、网格和字段属性完成平台已有的设置，CSS 负责其余视觉细节。
 
 | 场景 | 写法与检查点 |
 | --- | --- |
@@ -125,7 +205,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 | 必填与错误提示 | 可强化已有必填标记和错误状态的颜色、边框；先确认平台是否已经绘制星号，避免用 `::before` 重复生成。CSS 不代替必填和校验规则。 |
 | 打印 | 用 `@media print` 隐藏实际页面的工具栏与操作按钮，并检查表头对比度、分页、固定表头及打印预览；不要假定屏幕上的按钮类名适用于打印页面。 |
 
-例如，已确认目标布局存在 `.wea-url > span > p` 时，可在该布局的 CSS 文件中加入：
+例如，目标布局确实存在 `.wea-url > span > p` 时，可在该布局的 CSS 文件中加入：
 
 ```css
 .wea-url > span > p {
@@ -142,7 +222,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 | 对象 | 表格式布局 | 流式布局 |
 | --- | --- | --- |
-| 页面主题变量 | 可从 `.ebpage` 开始，检查组件是否读取变量 | 同样从实际页面根节点检查 |
+| 页面主题变量 | 默认 `page` 作用域下从页面根内部容器设置；改页面根本体则使用 `form` 模式 | 同样先定位实际根及变量读取范围 |
 | 字段控件 | 核对 `.weapp-form-widget__…` 与内部包裹层 | 核对实际组件路径；相同 DOM 才复用 |
 | 字段与分组位置 | 改网格、标记和单元格配置 | 改流式布局配置 |
 | `table`、`td`、明细表规则 | 仅用于真实存在的表格与明细表 | 不把表格式选择器直接套到流式区域 |
@@ -151,7 +231,7 @@ e10-cli form code layout apply <表单objId> --layout-id <布局ID> --terminal P
 
 1. 读取目标布局和终端的原 CSS，确认页面上确有要修改的元素及类名。
 2. 明确样式应落在页面、区域、网格单元格、组件包裹层还是输入元素；优先使用对应的布局配置，再写需要补充的 CSS。
-3. 写入完整 CSS 文件，回读源码与编译结果；不要把编译后的页面 ID 写回源码。
+3. 写入完整 CSS 文件，回读源码与编译结果；默认 `page` 模式不要复制编译前缀，`form` 模式需要的页面标识须从目标布局获取并仅用于该布局专属文件。
 4. 在实际表单中检查普通、只读、悬停、聚焦、选中及明细表滚动状态；移动端单独检查。
 
 模板 CSS 指南提供更多 **PC 表格式**组件路径与状态写法；它们是选择器参考，并非流式布局的 DOM 保证。布局源码的其他规则见[表单代码块配置指南](code-block-guide.md)。

package/skill-docs/references/form/layout/template/advanced.md

@@ -320,6 +320,8 @@ e10-cli form-engine layout-template advanced style update <模板ID> --config @l
 
 更新命令只修改写出的设置，保留其他设置与组件关联；系统模板不可编辑。新建和更新都会保存后回读，并生成一次**不落库**的应用预览。输出中的 `id` 是已保存的模板 ID，`preview.persisted=false` 仅表示预览未保存。要将模板用于实际表单，按[总览中的应用步骤](template-guide.md)操作。
 
+同一视觉位置可能由网格单元格样式、`formStyle.styleConfig` 和 CSS 分别绘制；它们作用的 DOM 层不同，不能仅按属性名推断冲突。出现重复边线或背景时，分别读取 `advanced grid show <模板ID>`、`advanced style show <模板ID>`、`advanced css show <模板ID>`，确认目标元素与生效范围后只保留所需绘制层。`advanced export` 中的 `formStyle.styleConfig` 是 JSON 字符串，检查时需解析其内容；不要把字符串未展开误认为未配置。
+
 需要拆分已有合并区域时，在网格配置中写入 `"split":[{"row":8,"col":0}]`，坐标是该合并区域的左上角。`merge` 则写入 `row`、`col`、`rowCount`、`colCount`；两者都可以与 `cells`、`rowHeights`、`columns` 一起提交。
 
 ### 启用、禁用与删除

package/skill-docs/references/form/layout/workflow-layout.md

@@ -13,6 +13,10 @@ e10-cli wf-form layout init <formId> --layout-id <布局ID>
 
 `wf-form layout init` 按目标布局类型重建排版；不传 `--layout-id` 则处理默认布局。需要覆盖字段只读、必填或独占一行时，可按该命令的选项设置；只调整运行时字段属性可查看 `wf-form field-prop`，它同样会经初始化保存，应先核对当前分组、排版和目标布局。
 
+字段分组由 `wf-form group <formId> --groups @groups.json` 创建。EXCEL 向平台提交平铺字段和分组 ID，由平台生成 Collapse 与子网格；FLOW 按该表单全部已分配分组组装 Fold 容器，新增一组时保留其他分组。`wf-form group` 与 `wf-form field-prop` 都会重建默认布局。若当前布局不是系统默认模板效果，必须显式传 `--style-template <当前模板名称或ID>`；未传时命令会在写入前中止，避免静默覆盖样式。指定模板后仍要回读排版与样式，已有手工微调可能被重建覆盖。普通字段的 `required/readOnly/singleRow` 通过 `form layout inspect <formId> --module workflow --id-type form` 查看布局组件配置；`wf-form permission get` 查询的是另一层表单级权限，不能用它验证布局字段属性。
+
+`wf-form add-field`、`add-fields` 默认也会自动重建布局，`add-detail-table --init` 同理；已有自定义模板时需传 `--style-template <当前模板名称或ID>`，否则会在创建字段或明细表之前停止。建字段时可用 `--no-init` 只保存字段，再单独审阅并初始化；在此之前新增字段不会自动进入布局。自动重建失败时命令会以失败状态退出，并说明字段可能已创建、布局尚未确认。
+
 应用样式模板时，优先使用审阅式命令。它按目标 PC 布局的 `FLOW`／`EXCEL` 类型解析已启用的流式或高级表格式模板；表格式简易模板使用 `--easy-template`。预览不保存，执行前会重新核对布局、字段配置及模板样式，执行后独立回读组件和可核对的模板效果：
 
 ```bash
@@ -68,6 +72,12 @@ e10-cli wf-form layout add-system-field <formId> --all          # 目录里的
 
 原生流程表单与 eb 表关联流程的表单都适用：传 `--workflow-id`，命令按工作流自动判定走哪套接口。
 
+应用预览时须重复预览所用的布局、模板和字段选项；CLI 会指出不一致的选项名，避免执行与预览不同的重建。已有 EXCEL 折叠分组时不要传 `--no-generate-collapse`：它会使分组字段失去承载子网格，CLI 会在写入前阻断。表格式布局回读还会检查重复分组与字段父容器的 workbook 子网格；`saved:true` 说明这些可静态检查的结构通过，不等同浏览器视觉验收。
+
+读取原生流程表单布局使用 `form layout inspect <formId> --module workflow --id-type form`；`form layout read` 的参数是 EB 表单 `objId`，不能直接传流程 `formId`。
+
+`wf-form edit-field` 仅适用于普通字段 ID。明细表的 `subFormId` 是容器 ID，不能交给它修改标题；当前 CLI 尚无已验证的明细表标题修改命令，不要改写普通字段接口报文来猜测保存方式。
+
 删除指定流程表单布局使用：
 
 ```bash

package/skill-docs/references/menu/system-menus.md

@@ -5,6 +5,27 @@
 > **移动端菜单是另一套记录**：同一个 `savePublishMenu` 接口，只把 `terminalType` 换成 `H5`；页面绑定与 `menuUrl` 与 PC 相同。菜单命令统一用 `--terminal mobile` 指定移动端（缺省 PC），两端互不影响。
 > 移动端**内置系统页**的 URL 尚未整理，不要自行编造。
 
+## 别把对象页面加成外链
+
+`menu add` 写的是 LINK 菜单。平台自己的页面地址（`/sp/ebdfpage/viewport/<viewId>` 台账、`/sp/ebdfpage/card/1/<objId>/0` 表单新建页）当外链写进去只会存成一串 URL：设计器「链接地址」显示文本而不是「数据列表: 表单名」标签，移动端拿不到视图绑定，打开是空列表。
+
+- 台账（数据列表）入口 → `menu add-table <appId> <表单 objId>`
+- 表单发起入口 → `menu add-start <appId> <表单 objId>`
+
+`menu add` 遇到这两类地址会直接拒绝；确实要当外链才加 `--as-link`。
+
+## 把 PC 菜单同步到移动端
+
+```bash
+e10-cli menu sync <appId>
+```
+
+- 平台原生能力：「是否确认将PC端菜单同步至移动端？（此同步操作会覆盖已添加的菜单配置）」。
+- 同步会**整体覆盖**移动端菜单：移动端单独加过、PC 上没有的菜单会被清掉。
+- 同步范围是 PC 端的**业务菜单**（目录、外链、嵌套都带过去，顺序与层级照搬）；「设置」「回收站」这类系统菜单两端各管各的，不参与同步。
+- 命令保存后会回读移动端，与 PC 端逐条比对路径、层级与顺序；对不上会报错并点名缺失/多余项，不会把「没同步」说成成功。
+- PC 端一条业务菜单都没有时命令会拒跑（否则等于清空移动端）；确认要清空加 `--force`。
+
 ---
 
 ## PC 端菜单