weaver-e10-builder 1.1.9 → 1.2.3

package/skill-docs/references/report/spec-build-schema.md

@@ -0,0 +1,291 @@
+# 声明式搭表 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` |
+
+### 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/skill-docs/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/skill-docs/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/skill-docs/references/workflow/guide-workflow-auth-resp.md

@@ -0,0 +1,198 @@
+# 权责表与权责表方式流程
+
+权责表把多个条件场景及其审批路径维护为“节点列 × 分支行”。它属于工作流公用流转资源，与 HRM 矩阵、普通公共片段和流程图布局分别管理。
+
+## 一、选择方式
+
+- 需要独立维护、供多个流程复用：先创建独立权责表，再由流程引用并映射变量。
+- 只服务于当前流程，且表单已经确定：创建权责表方式流程时选择新建权责表，条件直接引用表单字段。
+- 需要插入另一张权责表的审批路径中：创建中间片段型权责表，首尾位置使用审批等中间节点类型，再由宿主权责表按分支引用。
+- 普通顺序、分支流程继续使用流程图方式；只有需求明确要求权责表时才使用本指南。
+
+## 二、独立权责表搭建顺序
+
+1. `workflow auth-resp create` 创建权责表并记录 `authRespId`。
+2. `workflow auth-resp variable add` 创建条件需要的变量；条件只能引用已创建变量。变量还必须在某个分支条件里**真正被引用**，否则复用该权责表建流程时它不会进变量映射列表（见 §五）。
+3. 建立发起、结束设置和多个中间审批节点。中间节点统一作为列创建，操作者规则沿用工作流节点操作者规则。
+4. 为每个有效分支填写分支场景说明并创建条件。
+5. 每个分支从已有中间节点中选择自己的路径，通过顺序号表达串行或并行。
+6. `workflow auth-resp save-design --config @design.json` 保存并回读。
+
+从零完整搭建优先使用：
+
+```bash
+e10-cli workflow auth-resp configure <authRespId> --config @auth-resp.json
+```
+
+`auth-resp.json` 使用业务结构描述变量、节点、操作者、分支条件及路径：
+
+```json
+{
+  "baseId": "创建权责表返回的baseId",
+  "name": "合同分级审批权责表",
+  "workflowId": "-99999999",
+  "usage": "workflow",
+  "variables": [
+    { "id": "-自定义稳定ID", "name": "合同金额", "type": "wf_number" }
+  ],
+  "start": { "name": "开始节点", "operator": { "type": "all" } },
+  "end": { "name": "结束节点", "operator": { "type": "initiator" } },
+  "nodes": [
+    { "key": "manager", "name": "部门负责人审批", "type": "approve", "operator": { "type": "user", "keyword": "张三" } },
+    { "key": "finance", "name": "财务审批", "type": "approve", "operator": { "type": "user", "keyword": "李四" } }
+  ],
+  "branches": [
+    {
+      "scenario": "合同金额不超过5万元",
+      "condition": {
+        "relation": "AND",
+        "childrens": [
+          {
+            "selectType": "4",
+            "formField": [{ "id": "-自定义稳定ID", "name": "合同金额", "fieldType": "NumberComponent", "variable": true, "varFirstType": "wf_number" }],
+            "NumberCompareOptionLeft": "4",
+            "NumberValueOptionLeft": "1",
+            "NumberTextValueLeft1": 50000,
+            "elementValue1Id": "",
+            "elementValue2Id": "",
+            "expressionBaseId": "",
+            "dataValueId": ""
+          }
+        ]
+      },
+      "path": [
+        { "node": "manager", "order": 1 },
+        { "node": "finance", "order": 2 }
+      ]
+    }
+  ]
+}
+```
+
+流程内新建权责表时，`workflowId` 写真实流程 ID，条件 `formField` 使用该流程实际表单字段；独立权责表使用 `workflowId=-99999999`，条件引用 `variables` 中的变量。操作者类型直接支持 `all`、`user`、`initiator`；其他已有操作者类型使用 `raw` 并提供平台 `itemDatas`，结构与普通流程操作者一致。
+
+`usage=workflow` 表示完整流转，首尾默认使用发起和结束节点。`usage=fragment` 表示供其他权责表路径引用的中间片段，`start.type` 与 `end.type` 均配置为 `approve`、`confirm` 等中间节点类型；首尾位置不能使用 `start` 或 `end`。
+
+```bash
+e10-cli workflow auth-resp create "合同分级审批权责表"
+e10-cli workflow auth-resp variable add <authRespId> "合同金额" wf_number
+e10-cli workflow auth-resp variable list <authRespId>
+e10-cli workflow auth-resp read <authRespId> --base-id <baseId> > design.json
+e10-cli workflow auth-resp save-design <authRespId> --config @design.json
+```
+
+变量类型码当前已确认：
+
+| 类型码 | 含义 | 补充配置 |
+|---|---|---|
+| `wf_string` | 字符串 | — |
+| `wf_number` | 数值 | — |
+| `wf_select` | 选项 | `--option-template '{"id":"...","name":"..."}'` |
+| `wf_browser` | 浏览 | `--second-type` |
+| `wf_browser_relate` | 关联浏览 | `--relate-browser @browser.json` |
+
+## 三、表格设计结构
+
+`read` 返回的设计以 `columns` 和 `rows` 为核心：
+
+- 固定列：发起设置 `creator`、分支场景说明 `eventColumn`、条件 `condition`、结束设置 `endOperator`。
+- 动态节点列：名称为 `pubNode-<节点ID>`，`pubNodeInfo` 保存节点类型和操作者摘要。
+- 嵌套权责表列：名称为 `pubNode-<权责表sourceId>`，`addMethod=2`，同时保存被引用表的 `baseId` 和版本。
+- 分支行：保存场景说明、`conditionKey`、发起/结束配置及选中的节点单元格。
+- 节点单元格：`nodeInfo` 表示该分支经过此节点；`approveNum` 是执行顺序，相同值表示并行。
+
+每个有效分支必须有非空 `eventColumn` 和 `conditionKey`。界面用于继续录入的空白占位行不进入 CLI 保存数据。
+
+操作者和条件的业务规则与普通工作流一致，具体语法读取 [流程指南](guide-workflow.md) 和 [流程条件指南](guide-workflow-condition.md)。权责表条件的上下文标识由权责表命令负责，不把独立权责表变量当作表单字段创建。
+
+## 四、在分支中引用权责表
+
+先查询当前宿主权责表可以引用的中间型权责表：
+
+```bash
+e10-cli workflow auth-resp reference list <宿主baseId> --name "金额复核"
+```
+
+平台按首尾节点类型过滤可引用项，并排除自身和循环引用。添加时指定被引用权责表的具体版本，以及它出现在哪些分支和对应执行顺序：
+
+```bash
+e10-cli workflow auth-resp reference add <宿主sourceId> --base-id <宿主baseId> --workflow-id <流程ID> --reference @reference.json
+```
+
+```json
+{
+  "id": "被引用权责表sourceId",
+  "name": "金额复核权责表【V1】",
+  "baseId": "被引用权责表baseId",
+  "versionNum": 1,
+  "paths": [
+    { "branch": "金额超过50万元", "order": 2 }
+  ]
+}
+```
+
+相同顺序号表示并行，不同顺序号表示串行。移除引用时，同时删除节点列和各分支中的对应路径单元格：
+
+```bash
+e10-cli workflow auth-resp reference remove <宿主sourceId> <被引用sourceId> --base-id <宿主baseId> --workflow-id <流程ID>
+```
+
+## 五、权责表方式创建流程
+
+权责表是流程的搭建方式，流程表单来源仍按原生工作流程规则选择：自建流程表单、绑定已有流程表单或绑定 EB 表单。基础表单参数写入 `base.json`，其字段与 `workflow create-workflow` 的创建结构一致。
+
+### 随流程新建权责表
+
+```bash
+e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --new-table "合同审批权责表"
+```
+
+服务端在创建流程时生成并返回 `workflowId`、`formId` 和 `newAuthRespId`。这种方式已确定实际表单，分支条件直接选择表单字段，不做变量映射；发起和结束位置直接设置操作者。
+
+### 复用已有权责表
+
+```bash
+e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --reuse-table <authRespId> --mappings @mappings.json
+```
+
+也可以对已经创建的流程分步执行：
+
+```bash
+e10-cli workflow auth-resp-flow bind <workflowId> <authRespId>
+e10-cli workflow auth-resp-flow mapping-read <workflowId>
+e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
+```
+
+复用模式把独立权责表变量映射为当前流程表单字段。先用 `mapping-read` 取得平台返回的变量项和可用字段结构，在对应项补全 `fieldBrowser` 后整体保存；变量类型必须与表单字段匹配。
+
+> **前置条件：只有「已被分支条件引用」的变量才会出现在映射列表里。**
+>
+> `mapping-read` 返回的 `variableMappingList` 由平台按「该变量是否被本权责表的条件引用」筛出，未被引用的变量**不会出现**，因而无从映射 —— 列表为空不一定是故障。
+>
+> 自查：`e10-cli workflow auth-resp variable list <authRespId>` 里的 `referred` 字段，为 `false` 的变量不进映射列表。
+>
+> 由此推出搭建顺序：**变量 → 用条件引用它 → 再建/绑流程 → 映射**。反过来（先建流程、后补变量）不会自动补进列表，且 `auth-resp-flow bind` 对已引用过权责表的流程会拒绝重复绑定，只能重建流程。
+
+## 六、已有权责表流程的维护
+
+权责表方式流程的节点、分支条件、流转路径和生成出口统一通过绑定的权责表设计维护：
+
+```bash
+e10-cli workflow auth-resp-flow design-read <workflowId> --auth-resp-id <sourceId> --base-id <baseId> > design.json
+e10-cli workflow auth-resp-flow design-apply <workflowId> --auth-resp-id <sourceId> --config @design.json
+```
+
+权责表设计保存后，平台生成流程节点和出口。流程的出口列表用于查看生成结果及继续配置出口附加能力；改变分支、条件、经过节点和执行顺序时修改权责表设计。
+
+变量映射是独立的流程功能。复用权责表时，将权责表变量映射到当前流程实际表单字段：
+
+```bash
+e10-cli workflow auth-resp-flow mapping-read <workflowId>
+e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
+```
+
+映射项保留变量的 `varId`、`varName`、`varType` 和筛选参数，在 `fieldBrowser` 中写入实际字段；变量类型、主表或明细位置应与字段匹配。流程内新建权责表并直接使用表单字段时无需变量映射。
+
+## 七、Plan 记录
+
+流程计划中写清搭建方式、新建或复用的权责表、变量及字段映射、每个分支的场景说明与条件、经过节点和顺序、中间节点类型及操作者。执行时按“表单确定 → 权责表/流程创建 → 变量或字段条件 → 中间节点 → 分支路径 → 映射 → 其他流程设置”的顺序逐项销号。