weaver-e10-builder 1.6.15 → 1.7.0

package/skill-docs/references/form/guide-form-view.md

@@ -150,9 +150,19 @@ e10-cli --json form table-view style <objId> <appId> <listId> <style>
 | `horizontal-list` | 横向列表式 | `4` |
 | `above` | 上图式 | `5` |
 | `grid` | 网格列表式 | `7` |
+| `editable-data` | 可编辑表格（数据态） | `8` |
+| `editable-readonly` | 可编辑表格（只读态） | `9` |
 | `editable` | 可编辑表格（编辑态） | `11` |
 
-可编辑表格内部还有数据态 `8` 和只读态 `9`；用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成。
+可编辑表格内部有数据态 `8`、只读态 `9`、编辑态 `11`。用户要求“改成可编辑表格”时必须使用编辑态 `11`，不得把只读态 `9` 当成完成；反过来，视图原本是 `9` 时可以用 `editable-readonly` 精确回滚，不会再被静默改成别的形态。
+
+平台以后新增、映射表里还没有的 `mode`，用逃生口直接写：
+
+```bash
+e10-cli form table-view style <objId> <appId> <listId> --raw-mode 10
+```
+
+命令会回显原 `mode`；原值不在已知映射表里时给出提示，并告诉你回滚该用哪个 `--raw-mode`。
 
 命令先确认 `listId` 属于目标 `objId`，读取目标终端的完整配置后只修改其顶层 `mode`，保存后重新读取该终端配置核对。
 
@@ -296,9 +306,11 @@ e10-cli form list-hierarchy <objId> <appId> <listId> --enable --parent-field "
 e10-cli form list-hierarchy <objId> <appId> <listId> --disable  # 关闭但保留字段及展开设置
 
 # 台账视图权限（查阅/查看权限）：谁能查看这个台账（走 list/permission/save + getList，专用端点，full-replace 语义 omit即删）
-# selectedType: all(所有人) / user(人员,带--name) / role(角色,--name 缺省自动查) / matrix(矩阵,用 --add-raw 传整对象)
+# selectedType: all(所有人) / user(人员) / dept(部门) / role(角色) / matrix(矩阵)
 e10-cli form list-permission <objId> <appId> <listId> --add-all
 e10-cli form list-permission <objId> <appId> <listId> --add-user <userId> --name <人员名>
+e10-cli form list-permission <objId> <appId> <listId> --add-dept <deptId>                 # --name 缺省自动取部门名
+e10-cli form list-permission <objId> <appId> <listId> --add-dept <deptId> --name "AI研发团队"
 e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId>                # --name 缺省自动从角色树查名
 e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId> --share-level 2 # 加同一角色另一个共享级别
 e10-cli form list-permission <objId> <appId> <listId> --add-role <roleId> --seclevel 30-80 # 安全级别范围
@@ -430,20 +442,63 @@ e10-cli form list-config set <objId> <appId> <listId> --set-top 1 --set-top-rule
 
 | 分组 | 选项 → 落库键 |
 |---|---|
-| 基本信息 | `--show-title` → `showTitle`（显示头部，关闭后表头区域隐藏）<br>`--hide-checkbox` → `hideCheckbox`（隐藏 check 框）<br>`--default-display-edit-modal` → `defaultDisplayEditModal`（默认显示编辑模式；人员范围 `defaultDisplayEditModalPermission` 形状未确认，暂不开放写入）<br>`--operate-column-fixed` → `operatColumnFixation`（操作按钮固定）<br>`--spread-top-button` → `enableSpreadTop`（显示展开至顶部按钮）<br>`--prefix-column` → `enablePrefixColumn`（前置列）<br>`--field-choose-width-fixed` → `fieldChooseWidthFixation`<br>`--quick-search-textarea` → `quickSearchTextArea`（快捷搜索支持富文本）<br>`--sub-form-main` / `--sub-form-show-empty` → `subFormMain` / `subFormMainShowEmpty`<br>`--page-size` → `pageSize`（1–100，落库为字符串） |
+| 基本信息 | `--show-title` → `showTitle`（显示头部，关闭后表头区域隐藏）<br>`--hide-checkbox` → `hideCheckbox`（隐藏 check 框）<br>`--default-display-edit-modal` → `defaultDisplayEditModal`（默认显示编辑模式；**单独开启 = 全体成员默认编辑**，命令会给出警示）<br>`--default-display-edit-modal-permission '<json>'` → `defaultDisplayEditModalPermission`（落库为 **JSON 字符串**，实测值 `{"hideSwitchButton":true,"includeViewPermissionData":true}`；它只含行为开关，不含人员/部门范围）<br>`--operate-column-fixed` → `operatColumnFixation`（操作按钮固定）<br>`--spread-top-button` → `enableSpreadTop`（显示展开至顶部按钮）<br>`--prefix-column` → `enablePrefixColumn`（前置列）<br>`--field-choose-width-fixed` → `fieldChooseWidthFixation`<br>`--quick-search-textarea` → `quickSearchTextArea`（快捷搜索支持富文本）<br>`--sub-form-main` / `--sub-form-show-empty` → `subFormMain` / `subFormMainShowEmpty`<br>`--page-size` → `pageSize`（1–100，落库为字符串） |
 | 网格 | `--grid-row` / `--grid-col` → `gridRow` / `gridCol`<br>`--grid-width-type` / `--grid-width` → `gridWidthType` / `gridWidth`<br>`--grid-height-type` / `--grid-height` → `gridHeightType` / `gridHeight` |
-| 显示数据 | `--permission-scope`（`isNoPermissionList`，无权限数据展示方式）/ `--data-range-type` / `--list-data-range`（数据范围）<br>`--show-follow` → `isShowFollow`（关注图标）<br>`--read-state` → `readState`（未读、反馈标识）<br>`--set-top` / `--set-top-type` / `--set-top-rule`（置顶；type 1=规则 2=手动） |
-| 批量操作 | `--batch-add` / `--batch-add-fields`<br>`--batch-edit` / `--batch-edit-fields`<br>`--batch-edit-value`；另有 `--can-delete` |
+| 显示数据 | **数据范围**统一落 `dataset.ebuilderDataConfig.dataSetup`：`--data-permission ALL\|HAVE_PERMISSION_DATA`（所有数据 / 有权限数据）、`--data-type ALL\|FORM\|APPROVE`、`--list-data-range <值>`（与 dataType 对应）、`--data-setup '<整对象 JSON>'`（推荐）<br>`--show-follow` → `isShowFollow`（关注图标）<br>`--read-state` → `readState`（未读、反馈标识）<br>`--set-top` / `--set-top-type` / `--set-top-rule`（置顶；type 1=规则 2=手动） |
+| 批量操作 | `--batch-add` / `--batch-add-fields`<br>`--batch-edit` / `--batch-edit-fields`<br>`--batch-edit-value`；另有 `--can-delete`。字段数组最小对象 `{"fieldId","fieldName","fieldType","componentKey"}`，平台补全的键（width/otherProperties/index…）不参与回读比对 |
 | 数据列表插件 | `--title` → `title`（表格名称）<br>`--hide-table-header` → `hideTableHeader`（隐藏表头，仅表格式）<br>`--table-header-operation` → `tableHeaderOperation`（表头快捷操作模式，仅表格式）<br>`--operate-btn-fixed` → `buttonConfig.operateBtnFixed`（操作按钮固定）<br>`--group '<json>'` → 整个 `enableGroup`（`enable` 分组开关 / `groupField` / `groupSize` / `expandFirstFew` 默认展开 / `isDelay` 延迟加载 / `hasDataGroupsOnly` 只显示有数据的分组 / `groupFieldQuery`）<br>`--superior '<json>'` → 整个 `superiorField`（`enable` 启用上下级 / `field` 关联字段 / `expandLevel` 默认展开级数 / `levelSelection` 层级选择限制 / `levelRange`） |
-| 展示模式 | `--open-child-list` → `openChildList`（上下级）<br>`--sup-field`（上下级关联字段 ID）<br>`--expand-level`（0–3 级）/ `--expand-num-limit`（0–500 行）<br>`--expand-page-type`（1=分页 0=更多加载）<br>`--enable-group` / `--group-field` / `--group-enable-count` / `--only-display-data-group` |
+| 展示模式 | `--open-child-list` → `superiorField.enable`（只改开关，其余子键保留）<br>`--sup-field`（顶层 `supField`，上下级关联字段 ID）<br>`--expand-level` → `superiorField.expandLevel`（0–3 级）/ `--expand-num-limit` → `superiorField.maxExpandNumLimit`（0–500 行）<br>`--expand-page-type`（1=分页 0=更多加载）<br>`--group-field` / `--group-enable-count` / `--only-display-data-group`<br>**分组一律用 `--group '<整对象 JSON>'`**（布尔写法 `--enable-group` 已删除，写布尔会覆盖对象并导致平台拒绝） |
 
 - `buttonConfig`（操作按钮的启用/位置）本版**只读展示、不提供写入**：样本里 `enable:0` 的极性未确认，避免写反。
 - 已是目标值时零写入；值没变不发保存请求。
 - 布尔键写 `true/false`；个别键平台可能落成 0/1，回读不一致时命令会直接点名报错（此时改用对应数值写法，不要硬重试）。
-- `--enable-group` 单独打开时平台会返回「系统错误」——先 `--group-field <字段ID>` 再开分组；分组字段只支持下拉框 / 关联 e-Builder 单选 / 关联浏览单选。
+- **`--default-display-edit-modal on` 单独开启 = 全体成员默认编辑。** 该开关只决定“是否默认进编辑模式”，谁算有权查看由**台账视图权限**（`form list-permission`）决定；`defaultDisplayEditModalPermission` 只是行为配置（`hideSwitchButton` / `includeViewPermissionData`），不含人员/部门范围。命令检测到“开关开、权限配置空”时会输出警示。要限定部门：先用 `form list-permission --add-dept` 配查看权限，再按需写 `--default-display-edit-modal-permission`。
+- **分组与上下级可以同时开启**，平台不互斥。平台要求 `enableGroup` 必须是对象（`enable` / `groupField` / `groupSize` / …），所以分组一律用 `--group '<整对象>'`；旧的 `--enable-group` 布尔写法已删除。先 `get` 拿现值改完再写，避免丢子键。
+- `--open-child-list` 现在只改 `superiorField.enable`，不会再写一个平台不读的顶层 `openChildList`。上下级的完整配置仍可用 `--superior '<整对象>'`。
 - `--head-merge`（`headMerge`）在平台「视图设置」面板里没有对应开关；「隐藏表头」分两种实现：台账视图用 `--show-title off`（`showTitle`），数据列表插件用 `--hide-table-header on`（`hideTableHeader`）。
-- 数据列表插件（`mode:"12"`、`_plugins` 里 `resourceType:"ebList"`）把分组/上下级存成嵌套对象，台账视图存成平铺键；两种都支持，按视图实际落库形态选。`--group` / `--superior` 是整对象写入，先 `get` 拿现值改完再写，避免丢子键。
-- `--set-top-type 2`（手动置顶）时 `setTopRule` 是字段 ID 串（如 `123,125`），`--set-top-rule` 两种形态都接受。
+- 数据列表插件（`mode:"12"`、`_plugins` 里 `resourceType:"ebList"`）把分组/上下级存成嵌套对象，台账视图存成平铺键；两种都支持，按视图实际落库形态选。
+
+### 数据范围（数据权限）
+
+真实存储位是 **`dataset.ebuilderDataConfig.dataSetup`**，不是配置顶层。旧版的 `--data-range-type` / `--permission-scope` 写的是平台不读取的游离键（全租户只有被 CLI 写过的视图有），已废弃并会直接报错给迁移提示。
+
+```bash
+# 推荐：整对象写
+e10-cli form list-config set <objId> <appId> <listId> \
+  --data-setup '{"dataPermission":"ALL","dataType":"ALL","listDataRange":"ALL"}'
+
+# 或逐项写
+e10-cli form list-config set <objId> <appId> <listId> --data-permission ALL
+e10-cli form list-config set <objId> <appId> <listId> --data-permission HAVE_PERMISSION_DATA --data-type FORM
+```
+
+`dataPermission`：`ALL`=所有数据 / `HAVE_PERMISSION_DATA`=有权限数据。
+
+### 规则置顶（setTopRule）
+
+`setTopRule` 必须是**平台标准条件树**（与「视图数据条件」`filter` 同构：顶层 `key/relationship/datas/rootStr/...`，叶子带 `objId/compType/formInfo` 等）。平台**不校验**这个键，乱写也会 200，但界面不识别。
+
+`--set-top-rule` 支持三种形态：
+
+1. **简化入参**（推荐）：给 `conditions` 数组，CLI 复用 `form list-filter` 的构造器生成标准树：
+
+```bash
+cat > rule.json <<'EOF'
+{"conditions":[
+  {"fieldId":"1326481253473714177","func":"eq","value":"{date}","text":"计划开始日期"}
+]}
+EOF
+
+e10-cli form list-config set <objId> <appId> <listId> \
+  --set-top 1 --set-top-type 1 --set-top-rule @rule.json
+```
+
+2. **标准树**：已经是 `datas + rootStr` 的对象，原样写入；缺 `rootStr` 时命令会补渲染。
+3. **手动置顶字段 ID 串**（`--set-top-type 2`）：如 `123,125`，原样写入。
+
+`get` 会检查 `setTopRule`：`setTopType=1` 但缺 `datas/rootStr` 时给出“平台可能不识别”的警示。日期条件里的 `{date}` 等系统参数占位符会原样存储、运行时求值（清单见 `ref-list-filter-date-params.md`）。
+
+> 平台实测：`saveNListConfig` 把**空字符串 / 空对象**当成“未提供”，因此 `setTopType`、`setTopRule` 一旦写过就无法通过该接口清回空值。关闭置顶用 `--set-top 0` 即可（运行时不再置顶）；不要为了清空反复重试，命令会如实报回读不一致。
 
 ## 卡片视图（cardView）
 
@@ -455,9 +510,11 @@ e10-cli form view rename <objId> <appId> <cardViewId> "新名称"
 e10-cli form view delete <objId> <appId> <cardViewId>   # ⚠ 不可逆
 ```
 
-- 改名 / 删除走 `viewlist/buttonEvent`，报文里 `viewType:"cardView"`（台账是 `nListView`，行为不变）。
+- 改名 / 删除按**视图族**路由：只有 `formView` 走 `layout/rename|delete`；cardView / 台账 / 看板 / 日历 / 思维导图 / 多维等**全部**走 `viewlist/buttonEvent`。`viewType` 的取值注意两套词汇：台账在 `getViewlist` 里是 `NList`，但 `buttonEvent` 只认 `nListView`（命令会自动归一）；其余视图族原样透传真实类型（日历、看板传成 `nListView` 会 500）。
+- 删除后回读会做有限次重试：平台删除是异步的，第一次读仍在不算失败。
 - 卡片视图**没有表单布局**：`form view populate` 会明确拒绝，不要拿它填字段。
-- 创建走 `viewlist/createView` + `viewType:"cardView"`，创建后必须在 `cardView.detail` 里回读到。
+- **卡片视图不能挂设计器组件**（数字面板、图表等）：它的 `pageId` 不是设计器页面，`designer layout/page/info` 会报 500。需要「卡片样式 + 数字面板」时，载体应是 **EB 页面**，或台账的**列表式/卡片布局**（`config.mode="12"`，走 `form nlist`），不是 `--type cardView`。
+- 创建走 `viewlist/createView` + `viewType:"cardView"`，**不能带 `terminalType`**（实测会 500），创建后必须在 `cardView.detail` 里回读到。
   若平台拒绝，命令会停下并提示「抓一次设计器新建卡片视图的 createView 报文」，不要改参数硬试。
 
 ## 显示字段落在哪一层（重要）
@@ -466,11 +523,18 @@ e10-cli form view delete <objId> <appId> <cardViewId>   # ⚠ 不可逆
 
 | 视图形态 | 显示字段所在层 | 用什么命令 |
 |---|---|---|
-| 表格式（nListView 默认） | `config.tableField` | `form list-columns` |
-| 列表式 / 卡片视图（NList） | `config.listField` + `config.cardLayout` | `form nlist add-field / remove-field / apply` |
+| 表格式 / 可编辑表格（`tableField` 非空） | `config.tableField` | `form list-columns` |
+| 列表式 / 卡片布局（`listField` 非空） | `config.listField` + `config.cardLayout` | `form nlist add-field / remove-field / apply` |
+
+层判定规则：**非空 `listField` 优先**；否则 `tableField` 非空就是表格式；两边都空时按 `mode` 兜底（`2` 列表式 / `12` 卡片布局 → `listField`，其余含可编辑表格 8/9/11 → `tableField`）。注意 `type:"NList"` 不能单独作为“列表式”的判据——可编辑表格同样是 `NList`，但显示列在 `tableField`。
 
 在列表式视图上执行 `form list-columns --add` 会**直接报错并给指引**（不会再写进不生效的 tableField，这是 2026-11 清单里「切列表式后加字段异常」的根因）。
 
+另有两层容易混淆：
+
+- `form list-columns` 读的是 **`getNListConfig.tableField`**（显示列清单）；
+- `form list-columns attr` 读的是 **`getListFields.pc[]`**（列属性，宽度/对齐/冻结等）。两者是**两层**：平台建表自动铺的列可能只有前者，`pc[]` 为空。这种情况下 `attr show` 会明确提示 0 条，`attr set` 会报错并说明“本命令只改列属性层，不会重建显示列”，不会静默把列清空。
+
 ```bash
 # 增量追加 / 移除列表式显示字段（只动点名字段，已有卡片布局原样保留）
 e10-cli form nlist add-field <objId> <appId> <listId> <fieldId1> <fieldId2>

package/skill-docs/references/form/guide-list-columns.md

@@ -12,6 +12,14 @@ e10-cli form list-columns <objId> <appId> <listId> --remove <字段ID1> <字段I
 
 `--add` 按输入顺序追加到隐藏主键之前，已存在的列复用原配置；重复执行且无变化时返回 `unchanged:true`，不保存。`--remove` 可与 `--add` 同时使用，但不能对同一字段同时增删。移除不存在的列会报错；数据主键禁止移除。
 
+## 显示列落在哪一层
+
+- **非空 `listField` 优先**：列表式 / 卡片布局的显示列在 `config.listField` + `cardLayout`，请改用 `form nlist add-field|remove-field|apply`；在列表式视图上执行本命令会直接报错给指引。
+- 否则 `tableField` 非空就是表格式：**可编辑表格（`mode` 8/9/11）的 `type` 也是 `NList`，但显示列在 `tableField`**，本命令正常可用。
+- 两边都空才按视图类型兜底。
+
+> 注意 `getNListConfig.tableField`（显示列清单）与 `getListFields.pc[]`（列属性：宽度/对齐/冻结…）是**两层**。平台自动铺出来的台账可能只有前者、`pc[]` 为空——这时 `form list-columns attr show` 会明确显示 0 条，`attr set` 会报错并说明“本命令只改列属性层，不会重建显示列”，不会把已有列清空。
+
 ## 一次设置顺序、宽度和格式
 
 先读取当前列，按需求生成 UTF-8 的 `columns.json`。数组表示**完整业务列清单**：未列入的业务列会移除；数组顺序就是显示顺序。字段 ID 使用字符串，支持 `fieldId` 或 `id`，也支持仅填 ID 字符串。

package/skill-docs/references/hrm/guide-matrix.md

@@ -274,3 +274,19 @@ e10-cli matrix config-edit <矩阵ID> \
 
 CLI 自动查 config 判断 `conditionAble` 标记并展开为完整格式；改过的行保存后会回读比对，平台回 200 但没按提交落库会直接报错。
 
+
+## 人员矩阵（只读）
+
+组织架构里的「人员矩阵」与上面的条件矩阵是两套独立实现（人员矩阵走 `/api/bs/hrm/matrix/*`，数据结构是「矩阵 → 字段 → 行/人员值」），不能套用本指南前面的条件矩阵命令。
+
+```bash
+e10-cli matrix person list [--keyword <关键词>]
+e10-cli matrix person fields <matrixId>
+e10-cli matrix person data <matrixId>
+```
+
+- `list` 返回矩阵 id、名称、启用状态和描述；
+- `fields` 返回字段（列）的名称、类型和排序；
+- `data` 返回平台当前页的行数据，人员类单元格按姓名展开（多值用、分隔）。
+
+当前 CLI 只做只读。新建/编辑矩阵、字段维护和数据维护的保存报文尚未纳入，需要时按界面保存抓包后再补。

package/skill-docs/references/report/cell-transform-guide.md

@@ -2,7 +2,7 @@
 
 > **UI**：设计器右侧 **单元格 → 转换**（选中 Field 格时）
 > **源码**：`AnalysisFieldCellType` · `Trans.getTransInstance` · 设计器 `route_ReportDesigner`
-> **CLI**：`e10-cli report validate transform --map "人员"` / `--file cell.json`
+> **CLI**：`e10-cli report cell-transform set/show/list/clear …`（写入 + 回读）；纯校验用 `e10-cli report validate transform`
 > **落库**：须同时写入 `fields[]` 与 workbook `style.cellType`（`fieldToCell` 已透传）
 
 ---
@@ -119,13 +119,27 @@
 ## 七、Agent / CLI
 
 ```bash
+# 校验（不落库）
 e10-cli report validate transform --map "人员"
-e10-cli report validate transform --map "部门全路径"
-e10-cli report validate transform --map "二维码"
 e10-cli report validate transform --file cell-transform.json
 e10-cli report validate transform --list
+
+# 写入 + 回读（report cell transform 是等价别名）
+e10-cli report cell-transform show <reportId> --app-id <id> --cell 1,0
+e10-cli report cell-transform list <reportId> --app-id <id>
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 --map "人员"
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 \
+  --trans browser --browser HrmEmployeeComInfo --prefix "[" --suffix "]"
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 \
+  --html on --qrcode barcode --hidden off --direction 竖排
+e10-cli report cell-transform set  <reportId> --app-id <id> --cell 1,0 --file cell-transform.json
+e10-cli report cell-transform clear <reportId> --app-id <id> --cell 1,0
 ```
 
+`--html` / `--hidden` 接受 `on|off`、`1|0`、`是|否`。只改点名的键，其余保持原值；
+显式切 `transType` 时会清掉不再适配的 `browserType` / `transSelectOptions`。保存后回读
+`fields[]` 逐键比对，不一致直接报错。
+
 定点改转换时：改 `fields[]` 对应键 → `safe_report_save` / `fieldToCell` 透传到 workbook → 回读核对。
 
 ---

package/skill-docs/references/report/code-block-guide.md

@@ -0,0 +1,54 @@
+# 报表「代码块」（设计器 开始 → 代码块）
+
+> **UI**：报表设计器 → 开始 → 代码块（自定义 JS/HTML 片段，**按 sheet 存储**）
+> **CLI**：`e10-cli report code-block get|set|clear <reportId> --app-id <id> [--sheet-id <id>|--sheet-index <n>]`
+> **别名**：`report code block …` 与上面等价
+
+---
+
+## 一、接口与落库
+
+| 动作 | 方法 | 路径 | 参数 |
+|------|------|------|------|
+| 读 | GET | `/api/bs/edc/report/queryCustomCodeById` | `sheetId` |
+| 写 | POST | `/api/bs/edc/report/saveCustomCode` | form：`cusCode` + `sheetId` |
+
+- 请求头 `ebbusinessid` = 应用 ID（`report code-block` 的 `--app-id` 已带）。
+- `cusCode` = **代码文本的 UTF-8 base64**，等价前端：
+  ```js
+  btoa(unescape(encodeURIComponent(code)))
+  ```
+- `sheetId` 取 `getReportDevInfo.sheetProps[].sheetId`（**不是** `sheetProps[].id`）。
+- 保存接口回 200 不代表内容已落库：CLI 写完会回读比对，不一致直接报错。
+- 设计器新建代码块时的默认模板：
+  ```html
+  <script type="text/javascript">
+  /*
+  * 请在下面编写JS代码
+  */
+
+  </script>
+  ```
+
+## 二、命令
+
+```bash
+# 读（默认第一张 sheet）
+e10-cli report code-block get <reportId> --app-id <appId>
+e10-cli report code-block get <reportId> --app-id <appId> --sheet-index 1
+e10-cli report code-block get <reportId> --app-id <appId> --out code.js
+
+# 写（--code / --file / --template 三选一；含中文或换行建议用 --file）
+e10-cli report code-block set <reportId> --app-id <appId> --file code.js
+e10-cli report code-block set <reportId> --app-id <appId> --code '<script>console.log(1)</script>'
+e10-cli report code-block set <reportId> --app-id <appId> --template
+
+# 清空（保存空文本并回读确认；设计器再次打开会显示默认模板）
+e10-cli report code-block clear <reportId> --app-id <appId>
+```
+
+## 三、注意
+
+- 代码块按 sheet 独立：多 sheet 报表必须用 `--sheet-index` / `--sheet-id` 选对页。
+- 代码在预览/运行页执行，写入前确认脚本来源与用途；CLI 不做 JS 语义校验。
+- 不要把代码块和「单元格事件 → 执行 js 代码」（`cell-event`）混淆：前者按 sheet 一段，后者挂在单个单元格上。

package/skill-docs/references/report/dataset-sidebar-ops-guide.md

@@ -78,6 +78,8 @@ e10-cli report dataset rename --dataset-id <id> --name "轻资产主表" [--name
 
 - 须同时有维度 + 度量，或两者皆空（清空聚合）
 - 保存后 `fieldsAndOriginFields` 可见字段变为「分组字段 + 度量别名」
+- 行内不能同时出现 `groupBy` 和 `fieldId`；度量 `countType` 不得为 `none`
+- **保存是全量替换，接口 200 ≠ 落库**：CLI 写入后会回读并按 `groupBy` / `fieldId+countType` 比对，缺行/多行直接报错
 
 ### 2.3 ≠ 页面「数据预聚合」
 
@@ -92,9 +94,15 @@ e10-cli report dataset rename --dataset-id <id> --name "轻资产主表" [--name
 ```bash
 e10-cli report dataset agg get --dataset-id <id>
 e10-cli report dataset agg save --dataset-id <id> --file aggre.json
+e10-cli report dataset agg save --dataset-id <id> --inline '[{"groupBy":"…"},{"fieldId":"…","countType":"sum","showName":"金额合计"}]'
+e10-cli report dataset agg add --dataset-id <id> --inline '{"fieldId":"…","countType":"count","showName":"条数"}'
+e10-cli report dataset agg remove --dataset-id <id> --field-id '…'      # 或 --group-by / --index
 e10-cli report dataset agg clear --dataset-id <id>
 ```
 
+写接口在部分租户会校验应用上下文，报「无报表的编辑权限」时补 `--app-id <id>`。
+`add` 只校验单行结构，合并后的整体仍须满足「维度 + 度量」成对规则。
+
 ---
 
 ## 三、数据排序

package/skill-docs/references/report/ref-report-commands.md

@@ -55,7 +55,7 @@
 | `report dataset preview --dataset-id` | 预览数据 |
 | `report dataset check-used --report-id --dataset-id` | 是否仍被引用 |
 | `report dataset delete --report-id --dataset-id [--force]` | 移除数据集 |
-| `report dataset agg get\|save\|clear --dataset-id [--file]` | 左侧数据集菜单里的「数据聚合」（不是解析优化的预聚合） |
+| `report dataset agg get\|save\|add\|remove\|clear --dataset-id [--file\|--inline] [--app-id]` | 左侧数据集菜单里的「数据聚合」（不是解析优化的预聚合）；本地校验结构，保存后回读比对 |
 | `report dataset sort get\|save\|clear --dataset-id [--file]` | 排序 |
 | `report dataset replace --file <f>` | 整表换源（含 fieldMap） |
 | `report dataset heal [<reportId>] --app-id [--purge] [--apply]` | 修复数据集形态：`type=LOGIC` 大写原地换型（单元格引用自动重映射），`--purge` 顺带删 `sourceId` 为空的脏数据集。默认预演；落库后提示跑 `fix field-binding` |
@@ -84,6 +84,12 @@
 | `report cell-event list <reportId> --app-id` | 列出配置了链接的单元格 |
 | `report cell-event set <reportId> --app-id --cell <行,列> (--pc <链接> \| --h5 <链接>) [--open 弹出页\|当前页\|执行js代码]` | 写入单元格事件链接；`--pc` 可写 URL 或 JS（`--open 执行js代码`）；`--open` 缺省**保持原值**（新链接为弹出页）。全角 `？＆＝` 会直接报错 |
 | `report cell-event clear <reportId> --app-id --cell <行,列> [--pc\|--h5]` | 清链接（缺省 PC+H5 都清，打开方式复位为弹出页） |
+| `report cell-transform show\|list <reportId> --app-id [--cell <行,列>]` | 读取单元格「转换」配置 / 列出非默认转换 |
+| `report cell-transform set <reportId> --app-id --cell <行,列> [--map <中文类型>] [--trans <transType>] [--browser <ids>] [--options <json>] [--html on\|off] [--qrcode no\|barcode\|qrcode] [--prefix <s>] [--suffix <s>] [--hidden on\|off] [--direction <方向>] [--inline\|--file <json>]` | 写转换：只改点名键，双写 `fields[]` + workbook `style.cellType`，回读逐键比对 |
+| `report cell-transform clear <reportId> --app-id --cell <行,列>` | 恢复「无转换」并回读确认 |
+| `report code-block get <reportId> --app-id [--sheet-id\|--sheet-index] [--out <file>]` | 读报表代码块（按 sheet；`cusCode` 为 UTF-8 base64，CLI 自动解码） |
+| `report code-block set <reportId> --app-id [--sheet-id\|--sheet-index] (--code <text>\|--file <file>\|--template)` | 写代码块，写后回读比对 |
+| `report code-block clear <reportId> --app-id [--sheet-id\|--sheet-index]` | 清空代码块（保存空串并回读确认） |
 
 > **落库契约**：两组的写入都会改 `fields[]` 与 workbook `style.cellType`，双保存后**回读比对**，不一致即报错。
 > `saveReportDevInfo` 在 `designKey` 过期时会返回 **code=200 + `data:"您当前的数据不是最新的…"`**（静默失败）；命令会识别该文案并自动重读重写一次。

package/skill-docs/references/report/report-designer-feature-map.md

@@ -71,7 +71,7 @@ flowchart TB
 | **预览** | 右上角 | `GET checkSave?sheetId=` 后跳转 `/sp/edc/report/view/{reportId}` | Live §11.2 |
 | **历史版本** | 开始区 | `POST getVersionWithPage` · `GET rollbackReport` | 本文 §七 |
 | **数据分析** | 开始区 | 侧栏分析图表配置（workbook 扩展） | `report-help-guide.md` §十一 |
-| **代码块** | 开始区 | 自定义 JS/HTML 块（高级） | — |
+| **代码块** | 开始区 | 自定义 JS/HTML 块（高级），按 sheet 存储：`queryCustomCodeById` / `saveCustomCode`（`cusCode`=UTF-8 base64） | `code-block-guide.md` |
 
 ### 3.2 字体与对齐（SpreadJS 工具栏）
 

package/skill-docs/references/report/report-list-page-ops-guide.md

@@ -102,6 +102,8 @@ e10-cli report group delete --app-id <appId> --group-id <id>
 ### 1.3 禁令
 
 - 禁止把 `-1/-2/-3` 当自建分组写入 save
+- 禁止把 `id:''` 的新建项当哨兵过滤掉：空 id 正是新建标记，过滤后保存接口仍回 200，但分组不落库。保存前只剔 `-1/-2/-3`
+- 新建/删除后必须回读列表：新建要有新增 id，删除后目标 id 必须消失，否则按失败处理
 - 禁止未读 list 就臆造整表 groups（丢分组）
 - 删除分组前若组内有报表，先 `move` 走或告知用户（产品侧行为以页面为准）