weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/report/spec-build-schema.md

@@ -0,0 +1,294 @@
+# 声明式搭表 spec（一次性落库 · 推荐默认路径）
+
+> **CLI**：`e10-cli report build --spec <spec.json> [--dry-run] [--form-confirmed] [--source-id <id>] [--field-confirmed "标题1,标题2"]`
+> **脚本**：`e10-cli report build` · 公共库 `e10-cli report build`
+> **强制流程**：应用内定源 → **建表前字段预检**（`fieldsBySource`，**不建表**）→ **目标名** `baseInfo` → 本表 `addDataset`（同源只挂一次）→ `fieldsKey`（**再校验一次**）→ `saveReportDevInfo` → 回读。
+> **禁止**：`__build_*` / `__probe_*` 空壳、落库后再 rename、跨报表复用 datasetId、模糊表名未确认就搭表、**字段精确匹配失败时静默兜底（含回退系统字段）**。
+
+> ### ⚠ 两条「停下来问用户」规则（强制 · 2026-09-11 · `e10-cli report --help`）
+>
+> | 规则 | 触发 | 行为 |
+> |------|------|------|
+> | **A · 字段找不到** | 需求字段在当前数据集表单（`fieldsKey`/`fieldsBySource`）中**无精确命中** | **exit 4 · 不建表**，输出 `unmatched[]` + `allFields[]`，**请用户指定字段** |
+> | **B · 表没指明 / 非精确匹配** | 需求**未指出具体表**，或应用内检索**非完全精准匹配**（模糊/多命中/未命中） | **exit 3 · 不建表**，输出 `candidates[]`，**请用户指定表** |
+>
+> 核心：**不确定 → 停下问用户**；既不替用户猜，也不允许「先建表再回滚」。
+
+---
+
+## 一、顶层字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `appId` | ✅ | 应用 ID |
+| `name` | ✅ | **目标报表名**（直接写入 baseInfo + saveReportDevInfo） |
+| `form` | ＊ | 准确表单名；或与 `sourceId` 二选一 |
+| `sourceId` | | 已确认表单 ID；有则跳过模糊确认 |
+| `formConfirmed` | | `true` = 用户已确认当前 form/sourceId |
+| `formKeywords` | | **未指明表**时用于出候选的关键词（仅用于列候选，不代表已选表） |
+| `columns[]` | ✅ | 列定义，见 §二 |
+| `fieldMap` | | **字段兜底指定**：`{ "列标题": "字段显示名 | field_雪花 | 系统字段名" }`（列标题精确匹配失败时由用户指定，见 §二.1） |
+| `fieldConfirmed` | | 数组：**已确认「列文案 ≠ 字段真实显示名」**的列标题（用户认可自定义列名） |
+| `confirmDisplayMismatch` | | `true` = 全部列允许文案与字段显示名不同（等价 CLI `--field-confirmed`） |
+| `style` / `titleStyle` / `headerStyle` / `bodyStyle` | | 见 §三 / `default-header-style-guide.md` |
+| `layout` | | `title` / `freezeRows` / `showLocation`，见 §四 |
+| `datasetId` | | **仅本 report 已挂载的数据集**可复用；跨报表 ID 忽略并本表 addDataset |
+| `sourceType` | | 默认 `LOGIC`；共享表应用用 `form` |
+| `sourceGroup` | | 默认 `weaver-ebuilder-form-service`；共享表用 appId |
+| `sourceName` | | 数据集回显名；**缺后缀时自动补** `(业务模块)`/`(表单)`（裸表单名 → 面板缺后缀） |
+| `sources[]` | | **多数据源**。写了它就以它为准（`form`/`sourceId`/`sourceType` 等下沉到每一项）。见 `guide-report-multisource.md` |
+
+> **两个最常写错的键名**：列定义是 **`columns[]`**（不是 `fields`）；**`form` 是表单名字符串**（不是对象）——
+> 要用表单 id 就写 `sourceId`。写错时命令会回「spec 需要包含 appId / name(报表名) / columns[]」。
+
+### 1.0 多数据源 `sources[]` / `columns[].source`
+
+```json
+"sources": [
+  { "key": "customer", "form": "客户信息表" },
+  { "key": "order", "form": "销售订单表",
+    "link": { "parent": "customer", "parentField": "客户名称",
+              "childField": "客户名称", "type": "Equals" } }
+],
+"columns": [ { "source": "customer", "title": "客户名称", "field": "客户名称" },
+             { "source": "order",    "title": "订单编号", "field": "订单编号" } ]
+```
+
+- `sources[0]` = **父源**（不写 `link`）；`columns[].source` 缺省 = 父源 —— **不写 `sources` 时行为与单源完全一致**。
+- `link.parent` 必须是**左边紧邻**的源；`parentField`/`childField` 写显示名或 `field_xxx`，各自在本方表里解析（歧义即报错）。
+- `link.type` 用 **TitleCase** 白名单（`Equals`/`NotContain`/`Null`…）；`eq`/`contains` 这类简写平台不认。
+- 子源只能占**一段**连续区域；同区域**只有入口格**配父格筛选，其余格普通链式。
+- 多源时 `fieldMap`/`fieldConfirmed` 用 **`"源key.列标题"`** 限定同名不同源的列。
+- 跨源报表自动双保存并关预聚合；异常分支与限制见 `guide-report-multisource.md`。
+
+\* `form` 与 `sourceId` **均可省** → 走**规则 B**：exit **3**，列出应用内候选请用户指定表（**不会**按关键词猜、**不会**建表）。
+
+### 1.1 定源规则 · 规则 B（表没指明 / 非精确匹配 → 让用户指定）
+
+`resolveFormWithPrompt()` / `e10-cli report find` 统一语义：
+
+| 触发 | `reason` | 行为 |
+|------|----------|------|
+| **未指明具体表**（无 `form`/`sourceId`，或只给业务关键词） | `form_unspecified` | exit **3**，输出应用内候选 `candidates[]` |
+| **非完全精准匹配**：模糊包含 / 多条同名近名 | `form_fuzzy_match` | exit **3**，输出 `candidates[]`（带 `score`/`hits`） |
+| **未命中** | `form_not_found` | exit **3**，`action=need_exact_form_name` |
+| **exact 唯一** 或 已带 `--form-confirmed`/`sourceId` | `exact`/`confirmed` | 放行（`autoBind=true`） |
+
+确认后复跑（二选一）：
+
+```bash
+e10-cli report build --spec a.json --form-confirmed --source-id <id>
+```
+```json
+{ "formConfirmed": true, "sourceId": "<id>", "form": "<准确表名>" }
+```
+
+浏览候选（**不建表**）：
+
+```bash
+e10-cli report find <appId> --list
+e10-cli report find <appId> --suggest "关键词1,关键词2"
+```
+
+> **禁止**：按关键词自行挑一张「最像的」表；先建壳/试探表再判断对不对。
+> 输出字段：`action=confirm_form` · `rule:"B"` · `needConfirm:true` · `reportCreated:false`。
+
+### 1.2 数据集挂载规则（同源只挂一次）
+
+| 场景 | 行为 |
+|------|------|
+| 本报表已有同 `sourceId` 数据集 | **复用**（`datasetReused=true`），**禁止**再次 `addDataset` |
+| 同 `sourceId` 多于 1 条（存量脏数据） | 回传 `datasetDuplicates[]` 并 WARN → 按 `dataset-sidebar-ops-guide.md §5.3` 去重 |
+| 传了**别的报表**的 `datasetId` | 忽略并 WARN（禁止跨报表复用，本表重新解析） |
+
+---
+
+## 二、columns[]
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 表头文案（**也是字段匹配依据**，见 §二.1） |
+| `source` | 该列属于哪个源（`sources[].key`）；缺省 = 父源 |
+| `field` | 对应 fieldsKey 的 text/name（精确匹配） |
+| `fieldName` | **显式指定** fieldsKey.name（优先于 `field`/`title`） |
+| `confirmDisplayMismatch` | `true` = 该列允许「文案 ≠ 字段真实显示名」（用户认可自定义列名） |
+| `width` | 列宽，默认 120 |
+| `format` | 见下表；`huobi` 等 |
+| `formula` | 公式表达式（无 `=` 前缀；公式列不参与字段匹配） |
+| `groupType` | 日期分组等 |
+| `rule` | 条件格式，见 §五 |
+
+### 2.1 字段绑定门禁 · 规则 A（**字段找不到 → 让用户指定 · 禁止静默兜底 · 2026-09-11 强制**）
+
+匹配顺序（命中即止）：① `fieldName` / `fieldMap[列标题]` 显式指定 → ② 列标题 **精确等于** `fieldsKey[].text` → ③ `column.field` 精确等于 `text`/`name`。
+
+| `reason` | 情况 | 行为 |
+|------|------|------|
+| — | 精确命中 | 正常搭建 |
+| `no_exact_match` | **需求字段在当前数据集表单中找不到** | **exit 4**，输出 `unmatched` + `candidates` + `allFields`；**不建表** |
+| `explicit_not_found` | 显式指定的字段名不在该数据源 | **exit 4**，同上（禁止臆造字段） |
+| `display_mismatch` | 能绑到，但字段**真实显示名 ≠ 列文案**且用户未确认 | **exit 4**，确认后加 `fieldConfirmed` / `--field-confirmed "列标题"` |
+| — | 系统字段（`name`/`id`/`create_time`…） | **只能**通过列标题精确命中（如列标题就叫「标题」）或显式指定；**禁止**作为兜底 |
+
+输出（**原样交用户挑，不要自己猜**）：
+
+```json
+{
+ "action": "confirm_field", "rule": "A", "reportCreated": false,
+ "unmatched": [
+ { "column": "党组织", "reason": "no_exact_match",
+ "prompt": "需求字段「党组织」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
+ "candidates": [{ "name": "field_1475883017323040117", "text": "所属党委", "system": false }] }
+ ],
+ "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ],
+ "next": { "specFields": { "fieldMap": { "<列标题>": "<字段显示名 | field_雪花 | 系统字段名>" } } }
+}
+```
+
+用户指定后复跑：
+
+```bash
+e10-cli report build --spec a.json --field-confirmed "党组织,姓名"
+```
+```json
+{ "fieldMap": { "党组织": "field_1475883083739840137", "姓名": "发展人" },
+ "fieldConfirmed": ["党组织", "姓名"] }
+```
+
+> 事故：列「姓名」在表单无对应字段时被静默绑到系统字段 `name`（真实显示名「标题」）→ 列语义被改写且属性面板回显不符。
+> 详见 `field-bind-exact-match-guide.md §2.0`。
+
+### format 别名
+
+| 别名 | 说明 | formatter 示例 |
+|------|------|----------------|
+| `common` / 空 | 常规 | |
+| `huobi` | 货币 | `¥` 类目录值 |
+| `kuaiji` | 会计专用 | |
+| `percent` | 百分比 | `0.00%` |
+| `shortdate` / `longdate` / `time` / `text` / `fenshu` / `kexuejishu` | 见 `cell-config-echo-guide.md` §二 |
+
+---
+
+## 三、style（分层 · 默认表头）
+
+> 细则：`default-header-style-guide.md`。
+> **未指定样式且无效果图** → 自动套默认标题/表头；**用户指定或有效果图** → 完全按用户。
+
+```json
+"style": { "font": "微软雅黑", "fontSize": 12, "foreColor": "#333", "backColor": "#fff", "hAlign": "left" },
+"titleStyle": { },
+"headerStyle": { },
+"bodyStyle": { },
+"styleFromMockup": false,
+"applyDefaultHeader": true
+```
+
+| 场景 | 行为 |
+|------|------|
+| 无 style / *Style / 效果图 | 标题 `#B6D6FF`；列头 `#E6E6E6`；正文白底 |
+| 有用户样式或 `styleFromMockup:true` | 用户优先 |
+| `applyDefaultHeader:false` | 素色 |
+
+字号目录：`[8,9,11,12,14,16,18,20,22,24,26,28,36,48,72]`（无 10）；平台字号≈px 1:1。
+
+---
+
+## 四、layout
+
+```json
+"layout": { "title": "轻资产信息统计表", "freezeRows": 1, "showLocation": "left" }
+```
+
+- `title`：第 0 行合并标题
+- `freezeRows`：**冻结顶部几行**，锚点行就是 `freezeRows`（平台冻的是「锚点上方」的行）。
+  | 写法 | 锚点 | 实际冻结 |
+  |---|---|---|
+  | `0` / 不写 | 无 | 不冻结 |
+  | `1` | 表头首格 `(1,0)` | 只冻**标题行** |
+  | `2` | 数据首格 `(2,0)` | 冻**标题 + 表头**（与 `report fix freeze` 默认一致） |
+
+  锚点必须落在**真实存在的单元格**上，所以最多只能冻到首个数据行；写超了会直接报错，
+  不会静默按 1 处理。要冻更多行用 `report fix freeze --anchor <x,y>` 在已有报表上做。
+- `showLocation`：`left`=1；**禁止 0**
+
+---
+
+## 五、rule 条件格式
+
+落点 `style.cellType.conditionRule`（`highlightDatas` / `lineDatas` / `iconDatas`）。
+**禁止** sheet 级 `conditionalFormats`。
+
+---
+
+## 六、完整示例
+
+```json
+{
+ "appId": "770979194185342976",
+ "name": "资产信息统计",
+ "form": "轻资产信息",
+ "layout": { "title": "轻资产信息统计表", "freezeRows": 1 },
+ "columns": [
+ { "title": "资产名称", "field": "资产名称", "width": 160 },
+ { "title": "库存数量", "field": "库存数量", "width": 110 }
+ ]
+}
+```
+
+模糊表名确认后再搭：
+
+```bash
+e10-cli report build --spec a.json
+# exit 3 → 用户确认 sourceId
+e10-cli report build --spec a.json --form-confirmed --source-id 770981333078605824
+```
+
+---
+
+## 七、输出与退出码
+
+| code | 含义 |
+|------|------|
+| 0 | 成功；`noTempShell: true`（回读含 `fieldBindings` / `displayMismatch` / `datasetDuplicates`） |
+| 2 | 落库成功但存在告警：Field 绑定不在 fieldsKey / 文案与字段显示名不一致 / 同源重复挂载 |
+| 3 | **规则 B** 须确认表（`confirm_form` / `need_exact_form_name`）——**尚未建表** |
+| 4 | **规则 A** 须确认字段（`confirm_field`）：**建表前预检**未精确命中 → **未建表**；落库前 `fieldsKey` 再校验失败 → **已删除本表** |
+| 1 | 失败；已 `deleteReport` 删除未完成报表 |
+
+> **两规则共同点**：都**不会**留下列表垃圾；exit 3/4 时 `reportCreated:false`（或 `reportDeleted:true`）。
+
+成功输出含 `designerUrl`；按 `report-delivery-contract.md` **交链即停**。
+
+### 7.1 exit 4 的处理（**规则 A** · 给用户看，不要自己猜字段）
+
+```json
+{
+ "action": "confirm_field",
+ "rule": "A",
+ "reportCreated": false,
+ "unmatched": [
+ { "column": "姓名", "reason": "no_exact_match",
+ "message": "列「姓名」在该数据源 fieldsKey 中没有精确匹配的显示名…",
+ "prompt": "需求字段「姓名」在当前数据集表单中不存在：请用户从 allFields/candidates 中指定字段。",
+ "candidates": [{ "name": "field_1475883001898540109", "text": "培养人" }] }
+ ],
+ "allFields": [ { "name": "field_3505883017323279926", "text": "发展人", "system": false } ]
+}
+```
+
+1. 把 `candidates` / `allFields` **原样抛给用户**，请其指定字段（**不要**自己挑一个相近的顶上）；
+2. 用户指定后写 `spec.fieldMap = { "姓名": "发展人" }`（或 `field_xxx`）复跑；
+3. 若用户坚持「列名与字段显示名不同」（如列名写「党组织」绑字段「所属党委」）→ 加 `fieldConfirmed: ["党组织"]` 或 CLI `--field-confirmed "党组织"`。
+
+---
+
+## 八、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `app-datasource-lookup-guide.md` §2.0 | 未给表名 / 模糊确认 |
+| `default-header-style-guide.md` | 默认表头 |
+| `add-dataset-registration-guide.md` | LOGIC 注册 |
+| `failure-cleanup-and-nonblocking-guide.md` | 仅失败删未完成表，禁止故意建空壳 |
+| `report-delivery-contract.md` | 交链即停 |

package/skills/weaver-e10-builder/references/report/targeted-fix-guide.md

@@ -0,0 +1,97 @@
+# 定点修改 · 禁止整表重扫（强制）
+
+> **适用**：用户指出「某处不对 / 修某一格 / 改某条查询 / M4 父格」等**已定位**问题；以及「只改列宽 / 冻结 / 居左 / 分页 / 快照 / 打印」等**已列明范围**的调整；**改已有报表设计器内容**时一律适用。 
+> **目标**：少读配置、少调 API、少改无关格，避免整表重扫浪费时间与额度。 
+> **总闸（更高优先级）**：`user-request-scope-only-guide.md` — **仅改用户点名项**；未点名禁止改删、禁止额外命令。 
+> **硬约束**：用户说「只对提出的要求做调整，其他不要动」时，**样式/行高/字体/颜色/边框/未点名格一律禁止改写**——即便为写 workbook 必须整表回传，语义上也只能 patch 点名项。 
+> **禁止**：因编辑需求而重新走完整「需求分析 → 识别全部搭建配置 → 整表重建」。
+
+---
+
+## 一、硬原则
+
+| 原则 | 说明 |
+|------|------|
+| **仅用户点名（总闸）** | 见 `user-request-scope-only-guide.md`；CLI `e10-cli report fix --help` |
+| **听指定位置** | 用户点名单元格（如 M4）、查询条件名、字段名、dataset → **只处理该范围** |
+| **禁止整表重扫** | 不得因修一格而：全量 dump 所有 fields、重拉全部数据集元数据、重跑整表 verify、从参考表整表 clone 覆盖 |
+| **禁止顺手重构** | 未点名时禁止批量改其它 Field 父格、禁止重写全部查询条件、禁止「顺便」对齐整表样式 |
+| **禁止顺手改样式（强制）** | 用户未点名「改样式/行高/主题/字体/颜色」时：**禁止**重建 cell `style`、禁止改 `rows[].size`（行高）、禁止用默认模板覆盖已有外观。列宽/冻结/居左 ≠ 许可重做报表样式 |
+| **禁止拆合并（强制）** | **没有任何规则要求拆分合并单元格**。从 fields 重建 workbook 时必须带上原 `xCount`/`yCount` → `cell.rowCount`/`colCount` + `sheet.spans`；漏写 = 等价于取消合并。用户未要求「取消合并」时禁止丢 spans |
+| **禁止擅自删除** | 未点名删除时禁止 `deleteReport` / `lifecycle delete` / `cleanup shells` |
+| **最小读** | 只需 `getReportDevInfo` 时优先按坐标/条件 id **过滤后使用**；不要为定位一格打印全表 |
+| **最小写** | 查询 → 只 `saveQueryItem` 改目标条；父格/超链接 → 在**完整 workbook 保护**前提下只 patch 目标 cellType（见下） |
+
+---
+
+## 二、问题类型 → 动作范围
+
+| 用户说法（例） | 允许动作 | 禁止 |
+|----------------|----------|------|
+| 「M4 左/上父格不对」 | 只读 `(3,12)`（及占位依赖格如 `(3,11)`）；只改该 Const 的父格/`pcHreflink` | 重扫全部 Const/Field 父格；整表从兄弟报表覆盖 |
+| 「供应商等级没选项」 | 只读/改该条 `getQueryItem`；按 §3.2 拉该字段 options | 重配全部查询条件；重扫布局 |
+| 「查询显示方式不对」 | 只改目标条 `showWhere` | 新建一套条件 |
+| 「某 Field 绑错」 | 只改该格 `name`/`fieldKey` + workbook 对应 cell | 全表 remap |
+| 「整表父格都要默认」 | **仅当用户明确整表要求** 才批量；否则只更新 Skill 规则 | 把「规则说明」当成改线上表的许可 |
+| 「列宽 N / 冻结表头 / 居左」 | 只改 `width`+`columns`、冻结锚点、`showLocation`（见 `layout-showlocation-freeze-guide.md`） | 重建整表 style/行高；猜 `showLocation=0`；只写 `frozenRowCount` 不写 `fixed-cell-tag`；**丢掉 spans/合并** |
+
+---
+
+## 二点五、合并单元格（spans）保护
+
+服务端从 workbook **`spans`**（或 cell.`rowCount`/`colCount`>1）回写 `field.xCount`/`yCount`。 
+`safe_report_save.js` 的 `fieldToCell` / `buildWorkbookFromFields` **必须**把 `xCount`/`yCount` 写回 cell + `spans`。
+
+**反例（本次事故）**：只为改列宽/冻结，用无 `spans` 的 workbook 整表 `saveReportDevInfo` → 表头标题、表尾合计行合并被拆成 1×1。 
+**正例**：有原 workbook 时优先 `mergeWorkbookSafe` 原地 patch；无 workbook 时从 fields 重建也必须带 spans。
+
+---
+
+## 三、布局类定点改（仍须保护设计区）
+
+修**单格**父格/超链接时：
+
+1. **仍须**按 `safe-partial-save-guide.md` 提交**完整** `fields` + 从 fields 重建的 workbook（禁止空/残 workbook）。
+2. **语义上只改目标格**：其它格原样写回；禁止顺带改 Field 左父格链。
+3. **Const**：`ConstCellType` 必须显式带 `leftX/leftY/topX/topY` 与（若有）`pcHreflink`——服务端从 workbook 回写；缺 `leftX` → `0` → 伪 A1。见 `report-self-check-guide.md` §2.2。
+4. **保存后自检范围收窄**：只断言**被改格** + Field 总数不降；**不要**为修 M4 再跑全表字段遍历报告。
+
+```
+用户指 M4 →
+ GET getReportDevInfo（内存过滤 x,y）
+ patch fields 中该格 + 重建 workbook（全表 cell 保留，仅该格 ConstCellType 变）
+ saveReportDevInfo
+ 回读：仅检查该格 left/top/href/text + Field.count
+```
+
+---
+
+## 四、查询类定点改
+
+1. `getQueryItem` → 按显示名 / `asNameIndex` / `id` **定位一条**。
+2. 只改该条：`showWhere` / `displayType` / `selectOptions` / `relation` 等。
+3. 下拉选项：`selectKey`=选项 ID，`selectValue`=显示名；`fieldName` 用裸雪花 ID。见 `query-condition-api-guide.md` §3.2。
+4. 回读**只核对该条**，不必打印全部 queryItems。
+
+---
+
+## 五、列宽 / 冻结 / 居左（样式敏感）
+
+1. **必加载** `layout-showlocation-freeze-guide.md`。 
+2. 其它 cell 的 `style` JSON **原样**进入 workbook；禁止为省事用空白 style 重生。 
+3. 居左 = `showLocation: 1`（**不是 0**）；冻结表头 = `fixed-cell-tag` 锚点 + `tag.fixed` + `tag.fixedCell`，不能只设 `frozenRowCount`。 
+4. 回读只断言：目标列宽、`showLocation`、锚点 `(x,y)`/`fixed==1`；**不要**为调列宽去「优化」行高。
+
+---
+
+## 六、与其它文档关系
+
+| 文档 | 关系 |
+|------|------|
+| `user-request-scope-only-guide.md` | **总闸**：仅改用户点名项；禁止擅自改删 |
+| `safe-partial-save-guide.md` | 写布局时的 workbook 完整性（与「语义定点」不矛盾） |
+| `layout-showlocation-freeze-guide.md` | 居左枚举 + 冻结锚点；禁止伤样式 |
+| `report-self-check-guide.md` | 落库门禁；定点场景下**检查项可裁剪到改动面** |
+| `datasource-selection-and-parent-filter-guide.md` §〇 | 父格规则；「默认」≠ 批量改已有表 |
+| `query-condition-api-guide.md` | 查询/选项映射 |
+| `report-delivery-contract.md` | 仍可先交设计器链接；后台只验证改动面 |

package/skills/weaver-e10-builder/references/report/user-request-scope-only-guide.md

@@ -0,0 +1,82 @@
+# 仅改用户点名项 · 禁止擅自改删报表（最高优先级 · 强制）
+
+> **优先级**：高于一切「顺手优化 / 看起来更完整 / 方便下次」的冲动。
+> **必加载**：任何会 `saveReportDevInfo` / `deleteReport` / `lifecycle delete` / `rollbackReport` / 改查询·权限·快照·数据集 的任务开始前。
+> **CLI**：`e10-cli report fix --help`（打印本政策）；映射见 `e10-cli report -cli.md` §一。
+
+---
+
+## 〇、一句话
+
+**用户没点名的：不读全表乱改、不执行、不删除、不重建。**
+已搭建好的配置视为成品；Agent **只允许**调整用户**本轮明确说明**的点。
+
+---
+
+## 一、硬禁止（违反即事故）
+
+| 禁止 | 说明 |
+|------|------|
+| **禁止擅自删除报表** | 未明确说「删除 / 清理 / 删壳」时，禁止 `deleteReport`、`lifecycle delete`、`cleanup shells`（清理空壳仅当用户要求或失败删壳流程且目标确为空壳） |
+| **禁止擅自改未点名配置** | 未点名的单元格、合并、样式、行高、父格、公式、查询条件、数据集、权限、快照、分组、名称等 → **一律不动** |
+| **禁止「额外」命令** | 不为「验证方便」「对齐规范」「顺便修好」而主动跑改写类 API / 脚本；只读探测也须最小化 |
+| **禁止整表覆盖式「修复」** | 禁止为改一点而重做整张表、从兄弟报表 clone、无 spans 重建导致拆合并 |
+| **禁止扩大解释范围** | 「改列宽」≠ 改样式；「冻结」≠ 改布局；「居左」≠ 改主题；「某处不对」≠ 整表重扫 |
+
+---
+
+## 二、允许做什么
+
+| 条件 | 允许 |
+|------|------|
+| 用户本轮明确列出的项 | 仅这些项的最小 patch |
+| 写布局必须整表回传 workbook | **语义**只改点名项；其余 fields/style/spans **原样写回** |
+| 落库自检 | 裁剪到改动面；发现无关损坏 → **先问用户**再动，禁止自行扩大修复面 |
+| 失败删空壳 | 仅 `failure-cleanup` 定义的未落库空壳，且遵守该指南；**禁止**删用户已有正式报表 |
+
+---
+
+## 三、执行前自检（强制打勾）
+
+每次准备调用会改线上报表的 API / CLI / 脚本前：
+
+1. [ ] 用户原话点名的改动列表是什么？（写下来）
+2. [ ] 本次命令/脚本是否**严格落在该列表内**？
+3. [ ] 是否包含删除、重建、整表 save、改样式/合并/查询等**未点名**动作？→ 有则 **删掉该步骤**
+4. [ ] 若不确定是否在范围内 → **先问用户，禁止猜着改**
+
+---
+
+## 四、典型违规（已发生过 · 禁止再犯）
+
+| 用户只要 | Agent 错误加戏 | 后果 |
+|----------|----------------|------|
+| 列宽 + 冻结 + 居左 | 整表重建 workbook、丢 spans、压行高 | 合并拆开、样式变了 |
+| 修一个条件格式 | 重配整表 / 删其它报表 | 配置被破坏 |
+| 无明确删除指令 | `cleanup` / `deleteReport` | 报表进回收站 |
+
+---
+
+## 五、与其它文档
+
+| 文档 | 关系 |
+|------|------|
+| `targeted-fix-guide.md` | 定点改的细则（本文件是总闸） |
+| `safe-partial-save-guide.md` | 整表回传 ≠ 允许语义上乱改 |
+| `failure-cleanup-and-nonblocking-guide.md` | 唯一允许的「删壳」边界 |
+| `e10-cli report -cli.md` | CLI 映射；破坏性命令须用户点名才可跑 |
+| `layout-showlocation-freeze-guide.md` | 列宽/冻结/居左仍须保 spans/样式 |
+
+---
+
+## 六、CLI 对照
+
+```bash
+# 打印本政策（Agent 改配置前可先跑一遍提醒自己）
+e10-cli report fix --help
+
+# 破坏性命令 —— 仅当用户明确要求时使用
+e10-cli report lifecycle delete ...
+e10-cli report cleanup ...
+e10-cli report restore ...
+```

package/skills/weaver-e10-builder/references/workflow/guide-function-management.md

@@ -0,0 +1,154 @@
+# 工作流高级设置：功能管理
+
+适用位置：工作流设置 → 高级设置 → 功能管理。以下命令配置流程定义，不对流程实例执行撤回、加审或减审操作。加审与已有的加签 `workflow add-step` 是不同功能。
+
+## 命令与工作方式
+
+| 命令组 | get | create | update |
+|---|---|---|---|
+| `workflow withdraw` 撤回 | 查询当前配置 | 初始化/保存单份配置 | 局部修改单份配置 |
+| `workflow add-operator` 加审 | 基本设置+权限规则；`--rule-id` 查单条 | 新增权限规则 | `--rule-id` 改规则；不带则改基本/会签属性 |
+| `workflow minus-operator` 减审 | 权限规则；`--rule-id` 查单条 | 新增权限规则 | 必须 `--rule-id` |
+| `workflow receiver-range` 接收人范围 | 基础设置+普通模式明细 | 新增一条范围明细 | `--rule-id` 改明细；不带则改总开关 |
+| `workflow forward-circulate-back` 转发/传阅/抄送收回 | 查询当前配置 | 初始化/保存单份配置 | 局部修改单份配置 |
+
+每个命令的位置参数都是 `<workflowId>`。写入使用 `--data '{...}'` 或 `--data @配置文件.json`，只传用户明确要求的设置项。`get --schema` 返回本环境的字段、枚举和默认值；`--out 文件.json` 保存结果。长 ID 一律字符串，浏览字段使用 ID 数组。枚举既可用编码，也可用当前环境返回的选项中文原文。
+
+新增规则先读服务端新增表单，未指定项继承默认值；修改先查询现有值，合并补丁后保存并回读检查。撤回和收回属于流程级单份配置，create 不会新增第二份；已有配置也保留未指定字段。未知字段、无效枚举、错误节点/规则归属会拒绝，不自动重复发送新增请求。
+
+## 撤回管理
+
+```bash
+e10-cli workflow withdraw get <wf> --schema
+e10-cli workflow withdraw create <wf> --data '{}'
+e10-cli workflow withdraw update <wf> --data '{"remarkRequired":true,"allowRemind":false}'
+```
+
+| 字段 | 意义 / 可选值 |
+|---|---|
+| allowType | 能撤回的节点：`0` 选择，`1` 排除 |
+| allowNodes | 对应节点 ID 数组 |
+| beAllowType | 允许被撤回的节点：`0` 全部，`1` 选择，`2` 排除 |
+| beAllowNodes | 对应节点 ID 数组 |
+| allowRemind | 允许前台用户选择是否提醒，布尔值 |
+| remarkRequired | 撤回时意见必填，布尔值 |
+| doPreOperate | 启用节点前附加操作，布尔值；部分环境页面隐藏此项 |
+
+自然语言示例：“把流程【名称/ID】的撤回意见改为必填，其他设置保留。”
+
+## 加审 / 减审
+
+```bash
+# 查询实时默认值与当前规则
+e10-cli workflow add-operator get <wf> --schema
+# 新增仅针对这个审批节点的加审权限
+e10-cli workflow add-operator create <wf> --data '{"allowNode":["节点ID"],"operatorType":["1"]}'
+# 修改一条权限规则；不改节点范围或接收人范围引用
+e10-cli workflow add-operator update <wf> --rule-id <ruleId> --data '{"operatorType":["1","2"]}'
+# 加审基本设置
+e10-cli workflow add-operator update <wf> --data '{"todoAfterBackTodo":true,"allowModifyBackTodo":["1"]}'
+# 减审
+e10-cli workflow minus-operator create <wf> --data '{"allowNode":["节点ID"],"operatorType":["1"]}'
+e10-cli workflow minus-operator update <wf> --rule-id <ruleId> --data '{"operatorType":["1","2"]}'
+```
+
+权限规则字段：
+
+| 字段 | 意义 / 可选值 |
+|---|---|
+| allowNodeType | `0` 全部；`1` 选择；`2` 排除 |
+| allowNode | 节点 ID 数组；选择/排除时必填，按实时节点浏览范围校验 |
+| operatorType | 数组：`0` 上一节点操作者，`1` 当前节点未操作者，`2` 当前节点已操作者，`3` 指定节点操作者 |
+| operatorNode | 指定节点的 ID 数组；operatorType 包含 `3` 时必填 |
+
+加审基本设置：`todoAfterBackTodo`（全部加审人审批后回本人待办）、`allowModifyBackTodo`（允许修改为 `["1"]`，关闭为 `[]`）；会签属性 `todoSignAttr` 本节点待办、`todoNoSignAttr` 非本节点待办、`doneSignAttr` 已办，以及各自 `Def` 默认会签属性。选项以 `get --schema` 为准（一般 `1` 跟随操作者、`2` 用户选择、`3` 会签、`4` 非会签、`5` 依次处理，部分字段不允许 `1`）。减审不写与加审共用的基本设置。
+
+自然语言示例：
+
+- “流程【ID】增加一条加审权限：允许在【1级审批】加审，由当前节点未操作者操作，其他用系统默认。”
+- “把加审规则【ID】改为当前节点已操作和未操作人员均可操作，其余保持。”
+- “流程【ID】增加减审权限，只针对【节点】，可由指定节点【节点】操作者操作。”
+
+## 接收人范围：普通模式
+
+范围统一使用 `workflow receiver-range`，支持以下三个上下文；本次仅支持普通模式，高级模式已有配置会被拒绝，避免覆盖。
+
+| 页面位置 | 定位参数 | 后端场景 |
+|---|---|---|
+| 加审管理 → 权限行的限制接收人可选范围 | `--add-operator-id <加审权限规则ID>` | 10 |
+| 指定流转 → 目标节点通用设置 → 接收人范围 | `--scene assign-flow --node-id <源节点ID>` | 6 |
+| 指定流转 → 目标节点单独设置 → 接收人范围 | `--scene assign-flow-target --node-id <源节点ID> --target-node-id <目标节点ID>` | 7 |
+
+CLI 自动解析并回读核对真实范围引用，不需要传 mainId 或 receiverRangeKey。加审规则 ID 不是范围明细 ID；指定流转的源节点 ID 不是目标节点 ID。单独目标节点设置须已存在，可先用 `workflow node-assign-flow targets <wf> <源节点ID>` 查询，缺少时先 `add-target <wf> <源节点ID> <目标节点ID>`。
+
+```bash
+e10-cli workflow receiver-range get <wf> --add-operator-id <addOperatorId> --schema
+# 新增：指定部门；关系、安全级别未指定则沿用服务端默认
+e10-cli workflow receiver-range create <wf> --add-operator-id <addOperatorId> --data '{"objtype":"10","dept":["部门ID"]}'
+# 新增：指定分部
+e10-cli workflow receiver-range create <wf> --add-operator-id <addOperatorId> --data '{"objtype":"11","subDept":["分部ID"]}'
+# 修改一条明细，仅改变关系
+e10-cli workflow receiver-range update <wf> --add-operator-id <addOperatorId> --rule-id <rangeRuleId> --data '{"relationship":"1"}'
+# 启用限制（新增明细不会隐式打开总开关）
+e10-cli workflow receiver-range update <wf> --add-operator-id <addOperatorId> --data '{"isopen":true}'
+```
+
+指定流转使用相同的 `get/create/update` 和普通明细参数：
+
+```bash
+# 查询通用范围及当前环境默认值
+e10-cli workflow receiver-range get <wf> --scene assign-flow --node-id <源节点ID> --schema
+# 通用范围新增指定部门，仅适用于操作者；其他参数读取默认值
+e10-cli workflow receiver-range create <wf> --scene assign-flow --node-id <源节点ID> --data '{"objtype":"10","dept":["部门ID"],"suitableType":"1"}'
+# 启用限制，并限定在目标节点操作者范围内
+e10-cli workflow receiver-range update <wf> --scene assign-flow --node-id <源节点ID> --data '{"isopen":true,"limitOperatorRange":true}'
+# 单独目标节点范围：新增指定分部，仅适用于抄送人
+e10-cli workflow receiver-range create <wf> --scene assign-flow-target --node-id <源节点ID> --target-node-id <目标节点ID> --data '{"objtype":"11","subDept":["分部ID"],"suitableType":"2"}'
+# 局部修改单独范围某一条明细的适用类型，保留对象、安全级别和关系
+e10-cli workflow receiver-range update <wf> --scene assign-flow-target --node-id <源节点ID> --target-node-id <目标节点ID> --rule-id <明细ID> --data '{"suitableType":"全部"}'
+```
+
+指定流转额外支持：基础字段 `limitOperatorRange`（只能在目标节点操作者设置范围内选择）；明细字段 `suitableType`（`0` 全部、`1` 操作者、`2` 抄送人，也可传中文标签）。前者启用后与明细范围取交集，目标节点操作者无法计算时可选人员为空。新增明细不会自动启用限制或指定流转，须按需求分别设置。`workflow node-assign-flow` 仍负责指定流转基础/通用属性；原 `range` 子命令保留兼容，完整普通模式范围使用此统一命令。
+
+自然语言示例：“把流程【ID】源节点【ID】的指定流转通用接收人范围设为普通模式，新增指定部门【名称】，只适用于操作者，启用限制，其他设置不变。”单独设置请明确：“源节点【ID】到目标节点【ID】的单独范围”。先查询现有明细，已有匹配项用 update，避免重复新增。
+
+| objtype | 接收人类型 | 其他字段 |
+|---|---|---|
+| 0 / 1 / 2 / 3 / 4 | 本部门 / 直接上级部门 / 所有上级部门 / 下级部门 / 所有下级部门 | 无浏览值 |
+| 5 / 6 / 7 / 8 / 9 | 本分部 / 直接上级分部 / 所有上级分部 / 下级分部 / 所有下级分部 | 无浏览值 |
+| 10 | 指定部门 | `dept` ID 数组；安全级别 |
+| 11 | 指定分部 | `subDept` ID 数组；安全级别 |
+| 12 | 指定人员 | `person` ID 数组 |
+| 13 | 指定角色 | `role` ID 数组；`rolelevel` 成员级别；安全级别 |
+| 14 | 指定岗位 | `job` ID 数组；`joblevel` 岗位级别；`joblevelBrowser` 对应组织 ID 数组 |
+| 15 | 所有人 | 安全级别 |
+
+通用 `relationship`：`0` 包含、`1` 排除。安全级别 `seclevel` 为 `"最小值,最大值"`，如 `"0,100"`，合法边界 -999 至 999；只在组织已启用安全级别且该类型支持时可设置，默认从服务端读取。角色级别通常 `0` 总部、`1` 所有级别、`2` 分部及总部；岗位级别 `0` 总部、`1` 指定部门、`2` 指定分部，非总部时需要 joblevelBrowser。以实时选项为准。
+
+注意接口特性：
+
+- 第一次查询可能由服务端创建范围主记录并关联加审权限规则或目标节点单独配置，行为与打开页面弹窗一致。
+- `enableSecurityLevel`、`isUpgrade` 是服务端能力信息，不能通过此命令修改。
+- 后端没有按 ID 修改明细的接口。CLI 先新增并回读核对，验证通过才删除旧明细，再检查其他明细未变。结果返回 `previousRuleId` 与新的 `ruleId`，后续必须使用新 ID。
+- 新项校验失败会尝试清理新项并保留旧项；清理/删除失败会报告相关 ID，应先查询现状，不要重复新增。替换不是服务端事务，请避免同时编辑同一范围。
+
+自然语言示例：“给流程【ID】的加审规则【ID】限制接收人范围，普通模式，包含本部门和指定分部【名称】，启用限制，其他不变。”执行时先查询规则、解析真实分部 ID，再分别新增范围明细、启用总开关。
+
+## 转发 / 传阅 / 抄送收回
+
+```bash
+e10-cli workflow forward-circulate-back get <wf> --schema
+e10-cli workflow forward-circulate-back update <wf> --data '{"forwardBackCondition":["1"],"forwardAllowBack":false}'
+```
+
+| 字段前缀 | 功能 | 后缀 BackCondition | 后缀 AllowBack |
+|---|---|---|---|
+| forward | 转发 | 收回条件数组：`1` 查看前、`2` 查看后；`[]` 清空 | 接收人批注后允许收回 |
+| circulate | 传阅 | 同上 | 接收人批示后允许收回 |
+| cc | 抄送 | 同上 | 接收人批注后允许收回 |
+
+自然语言示例：“流程【ID】的转发只允许查看前收回，批注后不允许收回，传阅和抄送保持原样。”
+
+## 源码验证入口
+
+修改后在 CLI 项目内运行 `npm run build`，随后可直接用 `node dist/index.js workflow ...` 测试，不需要先打包或全局安装。开发时也可用 `node --import tsx src/index.ts workflow ...`。自然语言测试依赖执行方加载此文档；CLI 本身接收结构化命令，不直接解析整句自然语言。