weaver-e10-builder 1.6.15 → 1.6.16

package/skill-docs/references/report/build-resilience-guide.md

@@ -1,99 +1,99 @@
-# Agent 执行韧性（空壳清理 · 失败不卡死）（强制）
-
-> **适用**：API/脚本搭建或改报表全程。
-> **目标**：失败不留垃圾空壳；单点报错不拖死整单，先交可用结果、再提示用户、最后可后台补救。
-
----
-
-## 一、失败 / 终止必须清理空壳报表（强制）
-
-### 1.1 什么叫「空壳 / 无用报表」
-
-满足**任一**即视为应删的空壳：
-
-| 情形 | 说明 |
-|------|------|
-| 仅 `baseInfo` 建壳，**从未**成功 `saveReportDevInfo`（无 Field / 设计区空） | 临时名 `__build_*` / `__probe_*` / `__bench_*` |
-| 布局保存失败 / 脚本异常退出 / 用户中止，留下未改目标名或不可用壳 | 列表里出现但点开空白或全 Const |
-| 探测用临时报表（找表、压测） | 用完即删，禁止留在应用报表列表 |
-
-**不要删**：已成功落库且已向用户交付设计器地址的正式报表（如「测试BBB报表-chl」「议题A」）。
-
-### 1.2 何时必须删除
-
-- 命令 / 脚本 **抛错退出**
-- Agent **中止**当前建表任务（含用户叫停）
-- 同一任务内 **重建**前：旧失败 `reportId` 先 `deleteReport`
-- `finally` / 收尾逻辑：扫描本会话创建的临时壳并清理
-
-```
-POST/GET /api/bs/edc/report/deleteReport?id={reportId}
-（或 multipart ids=；进回收站即可，见 report-lifecycle-api-guide.md §删除）
-```
-
-Header 须带 `ebBusinessId`=appId。可批量：`id=id1,id2`。
-
-### 1.3 实现纪律
-
-1. 建壳成功后立刻记下 `reportId`（变量 / 日志）；**禁止**只记名字。
-2. 成功改名并交付前，临时名壳仍算「进行中」；**失败路径必须 delete**。
-3. 向用户说明：「已删除失败产生的空报表 xxx」，避免列表残留。
-4. 禁止留下多个 `__build_*` 占列表。
-
----
-
-## 二、单点失败不卡死（强制 · 失败前进）
-
-### 2.1 步骤分级
-
-| 级别 | 步骤例 | 失败策略 |
-|------|--------|----------|
-| **阻断** | 登录、找 app/表（预算内）、建壳、绑数据集、**布局 saveReportDevInfo** | 修 1 次或删壳重建 1 次；仍失败 → **提示用户**并停止交付假链接；清理空壳 |
-| **可降级** | `saveQueryItem`、`saveQueryConfig`、数据集筛选、权限、快照；**用户点名的** verify/HTML | **最多重试 1 次** → **提示用户** → **结束**（禁无限轮） |
-
-### 2.2 禁止卡死
-
-- 同一 API / 同一报错 **连续尝试 > 2 次**（含重试）仍失败 → **必须停手**，向用户说明原因与需确认项。
-- **禁止**为 `saveQueryItem` 500 等可降级项循环试参、开浏览器接口返回、阻塞不交布局链接。
-- **禁止**在「获取查询条件失败」上耗尽会话；布局已成功则**先交付设计器地址**。
-
-### 2.3 对用户提示模板（可降级失败）
-
-```markdown
-⚠️ **查询条件未写入**（`saveQueryItem` 返回 …）
-- 报表主体已保存，可先打开设计器查看布局。
-- 请确认：是否仍需高级搜索条件「议题名称 / 申请人 / …」？
-- 也可在设计器：页面 → 查询设置 → 手动添加。
-- 我将在收尾再自动重试一次；若仍失败以你确认为准。
-```
-
-同类可替换：数据集筛选、权限、字段绑定抽检等。
-
-### 2.4 推荐执行序（建表）
-
-```
-找表 → 建壳 → 布局落库 → 【立刻可交设计器地址】
-  → 查询条件（失败则提示+跳过）
-  → 其它可降级项（失败则提示+跳过）
-  → 收尾：对失败的可降级项自动补救 1 次
-  → 汇总：成功项 / 需用户确认项
-  → finally：删除本任务产生的空壳
-```
-
-### 2.5 与交付合同
-
-- 布局成功 → 遵守 `report-delivery-contract.md` §〇 **先交地址**。
-- 可降级失败 → **不阻塞**首轮链接；在回复中列出「未完成项 + 请用户确认」。
-- 阻断失败 → 不交假链接 + **删空壳** + 说明卡点。
-
----
-
-## 三、相关文档
-
-| 文档 | 关系 |
-|------|------|
-| `api-report-build-fast-path.md` | 建表主流程；引用本节清理与失败前进 |
-| `query-condition-api-guide.md` §二点五 | 查询 500 形态；失败后按本节降级 |
-| `report-delivery-contract.md` | 先交地址 |
-| `report-lifecycle-api-guide.md` | deleteReport |
-| `app-datasource-lookup-guide.md` §六 | 找表预算用尽则询问，不盲扫 |
+# Agent 执行韧性（空壳清理 · 失败不卡死）（强制）
+
+> **适用**：API/脚本搭建或改报表全程。
+> **目标**：失败不留垃圾空壳；单点报错不拖死整单，先交可用结果、再提示用户、最后可后台补救。
+
+---
+
+## 一、失败 / 终止必须清理空壳报表（强制）
+
+### 1.1 什么叫「空壳 / 无用报表」
+
+满足**任一**即视为应删的空壳：
+
+| 情形 | 说明 |
+|------|------|
+| 仅 `baseInfo` 建壳，**从未**成功 `saveReportDevInfo`（无 Field / 设计区空） | 临时名 `__build_*` / `__probe_*` / `__bench_*` |
+| 布局保存失败 / 脚本异常退出 / 用户中止，留下未改目标名或不可用壳 | 列表里出现但点开空白或全 Const |
+| 探测用临时报表（找表、压测） | 用完即删，禁止留在应用报表列表 |
+
+**不要删**：已成功落库且已向用户交付设计器地址的正式报表（如「测试BBB报表-chl」「议题A」）。
+
+### 1.2 何时必须删除
+
+- 命令 / 脚本 **抛错退出**
+- Agent **中止**当前建表任务（含用户叫停）
+- 同一任务内 **重建**前：旧失败 `reportId` 先 `deleteReport`
+- `finally` / 收尾逻辑：扫描本会话创建的临时壳并清理
+
+```
+POST/GET /api/bs/edc/report/deleteReport?id={reportId}
+（或 multipart ids=；进回收站即可，见 report-lifecycle-api-guide.md §删除）
+```
+
+Header 须带 `ebBusinessId`=appId。可批量：`id=id1,id2`。
+
+### 1.3 实现纪律
+
+1. 建壳成功后立刻记下 `reportId`（变量 / 日志）；**禁止**只记名字。
+2. 成功改名并交付前，临时名壳仍算「进行中」；**失败路径必须 delete**。
+3. 向用户说明：「已删除失败产生的空报表 xxx」，避免列表残留。
+4. 禁止留下多个 `__build_*` 占列表。
+
+---
+
+## 二、单点失败不卡死（强制 · 失败前进）
+
+### 2.1 步骤分级
+
+| 级别 | 步骤例 | 失败策略 |
+|------|--------|----------|
+| **阻断** | 登录、找 app/表（预算内）、建壳、绑数据集、**布局 saveReportDevInfo** | 修 1 次或删壳重建 1 次；仍失败 → **提示用户**并停止交付假链接；清理空壳 |
+| **可降级** | `saveQueryItem`、`saveQueryConfig`、数据集筛选、权限、快照；**用户点名的** verify/HTML | **最多重试 1 次** → **提示用户** → **结束**（禁无限轮） |
+
+### 2.2 禁止卡死
+
+- 同一 API / 同一报错 **连续尝试 > 2 次**（含重试）仍失败 → **必须停手**，向用户说明原因与需确认项。
+- **禁止**为 `saveQueryItem` 500 等可降级项循环试参、开浏览器接口返回、阻塞不交布局链接。
+- **禁止**在「获取查询条件失败」上耗尽会话；布局已成功则**先交付设计器地址**。
+
+### 2.3 对用户提示模板（可降级失败）
+
+```markdown
+⚠️ **查询条件未写入**（`saveQueryItem` 返回 …）
+- 报表主体已保存，可先打开设计器查看布局。
+- 请确认：是否仍需高级搜索条件「议题名称 / 申请人 / …」？
+- 也可在设计器：页面 → 查询设置 → 手动添加。
+- 我将在收尾再自动重试一次；若仍失败以你确认为准。
+```
+
+同类可替换：数据集筛选、权限、字段绑定抽检等。
+
+### 2.4 推荐执行序（建表）
+
+```
+找表 → 建壳 → 布局落库 → 【立刻可交设计器地址】
+  → 查询条件（失败则提示+跳过）
+  → 其它可降级项（失败则提示+跳过）
+  → 收尾：对失败的可降级项自动补救 1 次
+  → 汇总：成功项 / 需用户确认项
+  → finally：删除本任务产生的空壳
+```
+
+### 2.5 与交付合同
+
+- 布局成功 → 遵守 `report-delivery-contract.md` §〇 **先交地址**。
+- 可降级失败 → **不阻塞**首轮链接；在回复中列出「未完成项 + 请用户确认」。
+- 阻断失败 → 不交假链接 + **删空壳** + 说明卡点。
+
+---
+
+## 三、相关文档
+
+| 文档 | 关系 |
+|------|------|
+| `api-report-build-fast-path.md` | 建表主流程；引用本节清理与失败前进 |
+| `query-condition-api-guide.md` §二点五 | 查询 500 形态；失败后按本节降级 |
+| `report-delivery-contract.md` | 先交地址 |
+| `report-lifecycle-api-guide.md` | deleteReport |
+| `app-datasource-lookup-guide.md` §六 | 找表预算用尽则询问，不盲扫 |

package/skill-docs/references/report/card-report-guide.md

@@ -1,110 +1,110 @@
-# 卡片式报表 · 直构指南（e10-cli report card build）
-
-> 场景：**每条记录 = 一张卡片**（增值税发票、设备卡、工单卡、资产卡…），纵向堆叠**同页不分页**。
-> 首次打通：2026-09-15 「合同收票发票卡片-20260915」，落库 686ms / 20 格。
-> 固化为命令：**`e10-cli report card build`** —— 同类需求不再写脚本。
-
-## 0. 三条铁律
-
-1. **先查 CLI 再动手**：`e10-cli report card example` 出模板 spec，改字段即可；**禁止**重写建表脚本。
-2. **字段锚点唯一**：锚点格必须是 Field 且 `expandType: Vertical` + `isActiveParent: true` + 左父格 `-1,-1`；
-   卡片内**其余全部格子**（含 Const 文本）左父格一律显式指向锚点坐标 → 随记录整块复制。
-3. **字段精确预检**：`spec.cells[].field` 用**字段中文显示名**，精确命中失败 → exit 4 + 候选（禁止模糊兜底/系统字段回退）。
-
-## 1. 快速用法
-
-```bash
-e10-cli report card example > card.json                # 导出模板（含发票卡片示例）
-e10-cli report card example paragraph > card.json      # 导出「段落明细表」模板（多信息区块版式）
-# 改 spec：appId / reportName / sourceId / sourceName / cells
-e10-cli report card build --spec card.json       # dry-run（默认）
-e10-cli report card build --spec card.json --apply
-```
-
-## 2. spec 字段表
-
-| 字段 | 必填 | 说明 |
-|---|---|---|
-| `appId` | ✅ | 目标应用 |
-| `reportName` | ✅ | 报表名（建议带日期戳） |
-| `reportId` | ✖ | 缺省则**自动建壳**（`baseInfo`）；给了则覆盖该报表 |
-| `sourceId` | ✅ | 表单 sourceId（跨应用用 `find form-global` 找） |
-| `sourceName` | ✅ | 表单名 → 规范数据集名 `X(业务模块)` |
-| `sourceType` | ✖ | `logic`(默认) / `form` |
-| `tableName` | ✖ | 缺省 = `normalizeDatasetName(sourceName, sourceType)` |
-| `anchor` | ✖ | `{x,y}` 默认 `{1,1}`（B2），必须落在 Field 格上 |
-| `rowSizes` / `colSizes` | ✖ | 行高 / 列宽（隐藏列写 `0`） |
-| `sheetConfig` | ✖ | 默认 `{dataPreAgg:false, simpleList:false}`（卡片式字段常含 TextArea，默认关预聚合） |
-| `pageSetting` | ✖ | 默认 `{rowHeader:0,colHeader:0,gridLine:0,pagination:false}` → **不分页同页展示** |
-| `showLocation` | ✖ | 默认 `1`（居左）；`2` 居中。**改它会动全表显示位置**，非用户点名勿改 |
-| `cells[]` | ✅ | `{x,y,text \| field, fmt, span, style}`；`x`=行(0基)，`y`=列(0基)，`span`=向右跨列数 |
-
-`fmt`：`common`(默认) / `value`(0.00) / `int` / `percent` / `shortdate`
-`style`：`{fore, back, bold, size, hAlign, border}`；`border:NOBORDER` 用于卡片间距行（`border:{color:'#FFFFFF',style:0}`）
-
-## 3. 卡片排版约定（发票类参考）
-
-- 卡片行结构：标题行（跨列合并）→ 字段行（标签在左、值合并跨列）→ 内表头行 → 值行 → 单位行 → **间距行（空文本格，必须随块复制）**
-- 标题：`fore:'#E36C09'` + `bold` + `size:16` + `hAlign:1`
-- 合并用 `span`（脚本自动生成 `spans[]` + `cell.colCount`），**不要**手写 spans
-- 无对应字段的格（如效果图里的「税额」）用 Const 文本占位（`--`），不要硬凑字段
-
-## 3.1 段落明细表（段落式卡片 · 2026-10-29 固化）
-
-> 形态：**每条记录 = 一个规则段落块**，块内再分**多个信息区**（如「订单基本信息 / 货主信息 / 运货信息」），
-> 每区一行**绿色区块标题条** + 若干**标签/值网格行**；记录间留空行；纵向堆叠随记录数复制。
-> 与发票卡片**同一机制**（锚点格纵向扩展 + 全格左父格跟随），仅版式约定不同 —— 直接复用 `card build`。
-
-**与发票卡片的版式差异**：
-
-| 要素 | 发票卡片 | 段落明细表 |
-|---|---|---|
-| 块内分区 | 单一信息面 | 多个信息区，每区一条**区块标题条**（整行跨列 Const + 底色 `#C9E7D2` + bold） |
-| 网格 | 标签左·值右合并 | 规则**标签/值交替网格**（6 列：标签|值|标签|值|标签|值），值一般不跨列 |
-| 间距行 | 卡片间 1 行 | 段落间 1 行（空文本 + `border:NOBORDER`，必须随块复制） |
-| 锚点 | 卡片首格 Field | 段落内**任一 Field 格**均可（建议第一区首行值格） |
-
-**要点**：
-- 区块标题条是 **Const**（不是数据字段），`span` 到全宽；锚点机制会让它随记录整块复制。
-- 所有 Field 值格 `expandType:'Vertical'` 由脚本自动写入；**只有锚点格** `isActiveParent:true`，
-  其余格（含标签 Const、区块标题条、间距行）左父格全部指向锚点 → 回读验证 `misParent=0`。
-- 字段仍走**精确预检**（exit 4 + 候选）；表单没有的格用 Const 占位，不硬凑。
-- `pageSetting.pagination:false` 同页堆叠；要按记录分页 → 交用户在设计器选（能力边界见 §5）。
-
-**搭建提示语句（用户可直接照此提需求 / AI 照此执行）**：
-
-> 按段落明细表格式搭一张报表：每条记录一个段落块，块内分「XX信息 / YY信息 / ZZ信息」三个信息区，
-> 每区一条整行底色标题条 + 标签/值网格；数据源表 `<sourceName>`（sourceId `<id>`，appId `<appId>`）；
-> 字段映射：区块1 用字段 A/B/C，区块2 用字段 D/E/F……；记录间空一行，同页堆叠不分页；
-> 用 `e10-cli report card example paragraph` 导出模板改字段后 `card build`，dry-run 通过再 `--apply`，落库后回读验收（格数/锚点/全格左父格）并交设计器地址。
-
-## 4. 落库通道（脚本内置，勿改）
-
-1. `saveReportDevInfo` —— `form` 里 **`designKey` 传空串**（构建态公式/结构存活路径），workbook gzip+base64
-2. `saveReportWithCacheConfig` —— 同 workbook + `dataset` 清单 + `pageSetting`（**不分页只在这里生效**）
-3. 回读 `getReportDevInfo` 六项验证：格数 / Field 数 / 锚点 `isActiveParent` / 全格左父格→锚点 / 合并跨度 / `sheetProps.sheetConfig`
-   ⚠️ 环境兼容（2026-10-29 yunteams 实证）：① 部分环境 fields 回读**不含 `isActiveParent` 键** → 锚点判据退化为
-   `expandType=Vertical + left=-1,-1`；② `sheetProps` 可能是**数组**且 `sheetConfig` 为 **JSON 字符串**
-   （`sheetProps[0].sheetConfig`）→ 两种形状都已兼容（e10-cli report card build 内置）。
-
-## 5. 能力边界（无 API 写法，交设计器并**明确告知用户**）
-
-| 效果 | 结论 |
-|---|---|
-| 发票编号条形码/二维码 | 单元格不支持 → 默认文本；需设计器配条码属性 |
-| 价税合计(大写/小写) | 表单无字段 → 不放该行，或设计器内加公式 |
-| 一条记录按记录数**真实分页** | 与「不分页堆叠」互斥；`pageSetting.pagination` 由用户选择 |
-
-## 6. 验证与交付
-
-- dry-run 会打印：格数 / 形状(x行 y列) / 字段数 / 锚点 / 预聚合开关
-- `--apply` 后脚本自报 `VERIFY OK|FAIL`（FAIL → exit 2），并打印**纯文本**设计器地址
-- 交付：纯文本地址，交链即停（见 `report-delivery-contract.md`）
-
-## 7. 历史耗时教训（14 分钟那次）
-
-| 白烧点 | 对策 |
-|---|---|
-| 建壳不知有命令 → 读源码反推 6~7 次 | 规则：「确定性动作先查 CLI」（pitfalls `PERF-7`） |
-| 表不在应用内 → 手工循环探测，失败 2 次 | `e10-cli report find form-global`（pitfalls `FIND-2`），验证 3.5s 命中 |
-| 卡片式无固化命令 → 每轮重写脚本 | 本指南 + `card build`（pitfalls `BUILD-24`） |
+# 卡片式报表 · 直构指南（e10-cli report card build）
+
+> 场景：**每条记录 = 一张卡片**（增值税发票、设备卡、工单卡、资产卡…），纵向堆叠**同页不分页**。
+> 首次打通：2026-09-15 「合同收票发票卡片-20260915」，落库 686ms / 20 格。
+> 固化为命令：**`e10-cli report card build`** —— 同类需求不再写脚本。
+
+## 0. 三条铁律
+
+1. **先查 CLI 再动手**：`e10-cli report card example` 出模板 spec，改字段即可；**禁止**重写建表脚本。
+2. **字段锚点唯一**：锚点格必须是 Field 且 `expandType: Vertical` + `isActiveParent: true` + 左父格 `-1,-1`；
+   卡片内**其余全部格子**（含 Const 文本）左父格一律显式指向锚点坐标 → 随记录整块复制。
+3. **字段精确预检**：`spec.cells[].field` 用**字段中文显示名**，精确命中失败 → exit 4 + 候选（禁止模糊兜底/系统字段回退）。
+
+## 1. 快速用法
+
+```bash
+e10-cli report card example > card.json                # 导出模板（含发票卡片示例）
+e10-cli report card example paragraph > card.json      # 导出「段落明细表」模板（多信息区块版式）
+# 改 spec：appId / reportName / sourceId / sourceName / cells
+e10-cli report card build --spec card.json       # dry-run（默认）
+e10-cli report card build --spec card.json --apply
+```
+
+## 2. spec 字段表
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `appId` | ✅ | 目标应用 |
+| `reportName` | ✅ | 报表名（建议带日期戳） |
+| `reportId` | ✖ | 缺省则**自动建壳**（`baseInfo`）；给了则覆盖该报表 |
+| `sourceId` | ✅ | 表单 sourceId（跨应用用 `find form-global` 找） |
+| `sourceName` | ✅ | 表单名 → 规范数据集名 `X(业务模块)` |
+| `sourceType` | ✖ | `logic`(默认) / `form` |
+| `tableName` | ✖ | 缺省 = `normalizeDatasetName(sourceName, sourceType)` |
+| `anchor` | ✖ | `{x,y}` 默认 `{1,1}`（B2），必须落在 Field 格上 |
+| `rowSizes` / `colSizes` | ✖ | 行高 / 列宽（隐藏列写 `0`） |
+| `sheetConfig` | ✖ | 默认 `{dataPreAgg:false, simpleList:false}`（卡片式字段常含 TextArea，默认关预聚合） |
+| `pageSetting` | ✖ | 默认 `{rowHeader:0,colHeader:0,gridLine:0,pagination:false}` → **不分页同页展示** |
+| `showLocation` | ✖ | 默认 `1`（居左）；`2` 居中。**改它会动全表显示位置**，非用户点名勿改 |
+| `cells[]` | ✅ | `{x,y,text \| field, fmt, span, style}`；`x`=行(0基)，`y`=列(0基)，`span`=向右跨列数 |
+
+`fmt`：`common`(默认) / `value`(0.00) / `int` / `percent` / `shortdate`
+`style`：`{fore, back, bold, size, hAlign, border}`；`border:NOBORDER` 用于卡片间距行（`border:{color:'#FFFFFF',style:0}`）
+
+## 3. 卡片排版约定（发票类参考）
+
+- 卡片行结构：标题行（跨列合并）→ 字段行（标签在左、值合并跨列）→ 内表头行 → 值行 → 单位行 → **间距行（空文本格，必须随块复制）**
+- 标题：`fore:'#E36C09'` + `bold` + `size:16` + `hAlign:1`
+- 合并用 `span`（脚本自动生成 `spans[]` + `cell.colCount`），**不要**手写 spans
+- 无对应字段的格（如效果图里的「税额」）用 Const 文本占位（`--`），不要硬凑字段
+
+## 3.1 段落明细表（段落式卡片 · 2026-10-29 固化）
+
+> 形态：**每条记录 = 一个规则段落块**，块内再分**多个信息区**（如「订单基本信息 / 货主信息 / 运货信息」），
+> 每区一行**绿色区块标题条** + 若干**标签/值网格行**；记录间留空行；纵向堆叠随记录数复制。
+> 与发票卡片**同一机制**（锚点格纵向扩展 + 全格左父格跟随），仅版式约定不同 —— 直接复用 `card build`。
+
+**与发票卡片的版式差异**：
+
+| 要素 | 发票卡片 | 段落明细表 |
+|---|---|---|
+| 块内分区 | 单一信息面 | 多个信息区，每区一条**区块标题条**（整行跨列 Const + 底色 `#C9E7D2` + bold） |
+| 网格 | 标签左·值右合并 | 规则**标签/值交替网格**（6 列：标签|值|标签|值|标签|值），值一般不跨列 |
+| 间距行 | 卡片间 1 行 | 段落间 1 行（空文本 + `border:NOBORDER`，必须随块复制） |
+| 锚点 | 卡片首格 Field | 段落内**任一 Field 格**均可（建议第一区首行值格） |
+
+**要点**：
+- 区块标题条是 **Const**（不是数据字段），`span` 到全宽；锚点机制会让它随记录整块复制。
+- 所有 Field 值格 `expandType:'Vertical'` 由脚本自动写入；**只有锚点格** `isActiveParent:true`，
+  其余格（含标签 Const、区块标题条、间距行）左父格全部指向锚点 → 回读验证 `misParent=0`。
+- 字段仍走**精确预检**（exit 4 + 候选）；表单没有的格用 Const 占位，不硬凑。
+- `pageSetting.pagination:false` 同页堆叠；要按记录分页 → 交用户在设计器选（能力边界见 §5）。
+
+**搭建提示语句（用户可直接照此提需求 / AI 照此执行）**：
+
+> 按段落明细表格式搭一张报表：每条记录一个段落块，块内分「XX信息 / YY信息 / ZZ信息」三个信息区，
+> 每区一条整行底色标题条 + 标签/值网格；数据源表 `<sourceName>`（sourceId `<id>`，appId `<appId>`）；
+> 字段映射：区块1 用字段 A/B/C，区块2 用字段 D/E/F……；记录间空一行，同页堆叠不分页；
+> 用 `e10-cli report card example paragraph` 导出模板改字段后 `card build`，dry-run 通过再 `--apply`，落库后回读验收（格数/锚点/全格左父格）并交设计器地址。
+
+## 4. 落库通道（脚本内置，勿改）
+
+1. `saveReportDevInfo` —— `form` 里 **`designKey` 传空串**（构建态公式/结构存活路径），workbook gzip+base64
+2. `saveReportWithCacheConfig` —— 同 workbook + `dataset` 清单 + `pageSetting`（**不分页只在这里生效**）
+3. 回读 `getReportDevInfo` 六项验证：格数 / Field 数 / 锚点 `isActiveParent` / 全格左父格→锚点 / 合并跨度 / `sheetProps.sheetConfig`
+   ⚠️ 环境兼容（2026-10-29 yunteams 实证）：① 部分环境 fields 回读**不含 `isActiveParent` 键** → 锚点判据退化为
+   `expandType=Vertical + left=-1,-1`；② `sheetProps` 可能是**数组**且 `sheetConfig` 为 **JSON 字符串**
+   （`sheetProps[0].sheetConfig`）→ 两种形状都已兼容（e10-cli report card build 内置）。
+
+## 5. 能力边界（无 API 写法，交设计器并**明确告知用户**）
+
+| 效果 | 结论 |
+|---|---|
+| 发票编号条形码/二维码 | 单元格不支持 → 默认文本；需设计器配条码属性 |
+| 价税合计(大写/小写) | 表单无字段 → 不放该行，或设计器内加公式 |
+| 一条记录按记录数**真实分页** | 与「不分页堆叠」互斥；`pageSetting.pagination` 由用户选择 |
+
+## 6. 验证与交付
+
+- dry-run 会打印：格数 / 形状(x行 y列) / 字段数 / 锚点 / 预聚合开关
+- `--apply` 后脚本自报 `VERIFY OK|FAIL`（FAIL → exit 2），并打印**纯文本**设计器地址
+- 交付：纯文本地址，交链即停（见 `report-delivery-contract.md`）
+
+## 7. 历史耗时教训（14 分钟那次）
+
+| 白烧点 | 对策 |
+|---|---|
+| 建壳不知有命令 → 读源码反推 6~7 次 | 规则：「确定性动作先查 CLI」（pitfalls `PERF-7`） |
+| 表不在应用内 → 手工循环探测，失败 2 次 | `e10-cli report find form-global`（pitfalls `FIND-2`），验证 3.5s 命中 |
+| 卡片式无固化命令 → 每轮重写脚本 | 本指南 + `card build`（pitfalls `BUILD-24`） |