weaver-e10-builder 1.5.16 → 1.6.4

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

@@ -0,0 +1,67 @@
+# 表单布局使用总览
+
+本篇用于选择表单布局的操作路径。布局可以单独查询、编辑、初始化、设置代码块或应用样式模板；图片／Excel 还原则是一条独立工作流。确定要做的事后，再读相应的专题指南。
+
+## 先确认目标
+
+1. **表单和布局类型**：新建 EB 表单时选择流式 `FLOW` 或表格式 `EXCEL`；已有表单可以有多套不同类型的表单视图布局。不能把一套表格式布局的网格位置直接当成流式布局位置使用。
+2. **具体布局与用途**：确认操作默认布局，还是某个视图布局 ID。新建、显示、编辑可以分别指定用途布局；`all` 是单独的用途档位，不是 FLOW/EXCEL 布局类型。
+3. **终端与模块**：确认 PC 或移动端，以及 EB 表单或原生工作流程表单。布局代码按布局 ID 和终端保存；查询和编辑命令在非默认模块或布局时要明确指定目标。
+4. **现有内容**：修改前读取布局和字段。已有手工排版、合并、配色、模板样式或 JS/CSS 时，先导出完整底稿，再决定做局部调整还是整套重建。
+
+建表时如何从需求提取布局蓝图，见[布局规划](planning.md)；表单及字段的创建顺序见[新建 EB 表单](../guide-create-form.md)。
+
+## 按任务选择能力
+
+| 要完成的事 | 使用方法 | 阅读位置 |
+| --- | --- | --- |
+| 创建表单时确定 FLOW/EXCEL、字段同排关系、分组和布局蓝图 | 先整理字段与布局要求，再创建表单 | [布局规划](planning.md) |
+| 给已有表单新增一套流式或表格式视图布局 | 创建 `formView`，再将已有字段填入；后续可只补缺失字段 | [视图与布局管理](management.md) |
+| 复制布局、指定新建／显示／编辑用途、删除布局 | 按视图布局 ID 操作并回读结果 | [视图与布局管理](management.md) |
+| 给流程表单新增布局，或让某个流程节点使用独立布局 | 先管理表单布局，再按节点和终端绑定 | [流程表单与节点布局](workflow-layout.md) |
+| 看清字段、分组、明细及网格位置 | `form layout describe`；需要完整原生底稿时用 `read --raw` 或 `document export` | [布局查询与局部编辑](inspect-edit.md) |
+| 改少量表格式行高、列宽、已有单元格样式或同网格字段位置 | `layout diff` 预览，随后 `layout edit` 应用 | [布局查询与局部编辑](inspect-edit.md) |
+| 同时修改多个区域、组件、合并关系、页面样式等完整布局内容 | `layout document export` → 编辑草稿 → `diff` → `apply` | [完整布局文档编辑](document.md) |
+| 根据当前字段重建布局，或将样式模板应用到实际表单 | `layout init-reviewed` 先生成计划，再按同一配置执行 | [初始化与模板应用](initialization.md)、[模板总览](template/template-guide.md) |
+| 给已有表单增量加字段、放入明细表或调整布局组件属性 | 使用对应增量命令，避免无意重建已有排版 | [已有表单增量修改](incremental.md) |
+| 为某套布局写 JS 交互逻辑或 CSS 外观 | 按布局 ID、终端读取原代码，预览并应用候选源码 | [代码块指南](code-block/code-block-guide.md)、[布局 CSS](code-block/layout-css.md) |
+| 创建、维护和选择可复用的样式模板 | 按简易表格式、高级表格式、流式及终端选择模板 | [模板总览](template/template-guide.md) |
+| 按图片或 XLSX 精确还原网格、字段位置和可支持的样式 | 独立执行源文件观察／提取、编译、审阅、保存与验证 | [图片／Excel 源样式还原](source-restoration.md) |
+
+这些能力可分别使用。改一处单元格不需要初始化；写 CSS 不需要重建模板；维护模板也不要求立即应用到表单。
+
+## 选择编辑范围
+
+**局部编辑**适合已存在的表格式网格：行高、列宽、已有单元格样式、字段标题和值组件在同一网格内的移动。先用 `describe` 找真实位置，再用同一份配置执行 `diff/edit`。它不创建新单元格、不修改合并关系，也不用于流式排版。
+
+**完整文档编辑**适合需要同时调整多个布局区域或原生结构的情况。先导出带目标和快照指纹的底稿，只编辑其中的 `formLayout`，再审阅完整差异。业务字段的创建、删除和业务属性仍走表单命令。布局代码块优先使用专门的代码命令写入，避免手工拼装源码编码。
+
+**初始化**按现有字段重新生成一套布局，可同时应用匹配布局类型的样式模板和字段显示属性。它会重新排列字段、分组、明细组件，已有精细网格样式、页面样式和代码块都应在执行前核对影响。`init-reviewed` 的预览记录目标及覆盖范围，执行后回读；只改一个已有字段时，先考虑局部属性命令或增量路径。
+
+**图片／Excel 还原**用于必须保留源文件的合并、尺寸、留白、静态文字及样式时。先建立业务字段，再把观察或提取结果绑定到已有字段。编译产物可用 `source-review` 只读核对与当前布局的差异；实际保存仍使用源布局的 `apply/verify`，不能直接换成普通完整文档 `apply`。
+
+## 样式写在哪里
+
+| 需求 | 配置位置 |
+| --- | --- |
+| 反复用于多套布局的外观 | 样式模板；按布局类型和终端选用，应用时通过初始化生成实际布局 |
+| 实际表格式布局的尺寸、合并和单元格样式 | 当前布局的网格；少量已有单元格用局部编辑，结构性调整用完整文档 |
+| 某套布局、某个终端的交互和外观 | 布局代码块 JS/CSS；JS 处理运行逻辑，CSS 处理已有元素的呈现 |
+| 同一表单跨布局生效的代码 | 表单级 ecode；作用范围与布局代码块不同，先按[代码块指南](code-block/code-block-guide.md)选择层级 |
+| 表单字段的类型、公式、关联和业务属性 | 字段及表单配置；布局模板和 CSS 不创建业务字段 |
+
+高级表格式模板的网格、模板 CSS 与实际布局 CSS 是不同的保存对象。模板被应用后，仍需回读实际布局并检查页面效果。当前 PC 流式模板的独立编辑、启停及删除不作为可用能力；按[流式模板指南](template/flow.md)中已经确认的能力操作。
+
+## 通用核对顺序
+
+1. 查询目标表单、布局 ID、布局类型、终端及字段；已有精细布局先导出底稿。
+2. 选择最小合适的操作范围，准备配置或草稿。修改代码时先读出现有 JS/CSS，保留未修改的一项。
+3. 使用对应能力的只读预览核对目标、前后差异与影响范围。源还原按自己的观察及编译流程核对。
+4. 按原配置与预览结果应用，随后独立回读。布局代码还须在实际页面检查运行效果；CSS 还须检查 PC／移动端和组件状态。
+5. 若目标布局或字段在预览后发生变化，重新读取并预览，不沿用旧报告。
+
+各命令的完整参数见[CLI 命令参考](../../common/ref-cli-commands.md)。
+
+## 相关能力
+
+布局设置完成后，仍可能需要其他独立配置：[显示属性联动](../guide-form-linkage.md)按条件改变字段或布局组件的显示状态；[表单按钮](../guide-form-button.md)可以打开指定表单布局；[附属物理表](../guide-form-physical-table.md)的字段创建与放入布局要分别核对；流程节点的字段权限和布局绑定见[流程节点独立布局](../../workflow/guide-workflow-node-layout.md)。这些能力各有自己的保存对象，按需求进入对应专题。

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

@@ -0,0 +1,64 @@
+# 表单视图布局管理
+
+本篇用于给已有 EB 表单增加一套表单视图布局、补齐该布局中的字段，以及复制、指定用途或删除一套布局。台账、看板、日历、搜索和显示列属于[视图功能](../guide-form-view.md)，不按本篇的表单布局命令配置。布局内容的查询、局部与完整编辑见[布局总览](layout-overview.md)。
+
+原生流程表单的多套布局及节点引用使用另一组命令，见[流程表单与节点布局](workflow-layout.md)。
+
+## 确认要管理的布局
+
+先列出当前表单的视图，取得真实的视图布局 ID。创建表单时的初始 FLOW/EXCEL 类型，与给已有表单新增一套 `formView` 是不同操作；一张表单可以有多套不同类型的表单视图布局。
+
+```bash
+e10-cli form view list <objId> <appId>
+```
+
+涉及布局 ID 的命令使用视图列表中的 ID。不要把表单 `formId`、视图 `versionId` 或页面 `pageLayoutId` 互相替代。指定新建、显示、编辑用途时，还应分清用途档位与 FLOW/EXCEL 布局类型。
+
+## 新增一套表单视图布局
+
+给已有表单新增流式或表格式视图布局，先创建空 `formView`，再填入现有字段：
+
+```bash
+e10-cli form view create <objId> <appId> "新增-流式视图" --type formView --layout-type FLOW
+e10-cli form view create <objId> <appId> "新增-表格式视图" --type formView --layout-type EXCEL
+e10-cli form view populate <objId> <appId> <viewId>
+```
+
+`--layout-type` 决定新视图使用 FLOW 或 EXCEL。创建只得到空视图；`populate` 才按目标布局类型生成已有字段组件。不能把表格式坐标直接复制到流式布局。`populate` 以原表单 `formId` 读取字段，以新视图 `viewId` 定位目标布局，保存后独立回读。
+
+视图已有字段时，`populate` 只补后来新增而当前视图缺少的字段；现有组件的排版和属性保持原值，重复执行不会重复放置。表单存在附属物理表时，字段组件仍应保留每个字段的物理表归属。表单加字段后只需让某套视图显示它，也使用 `populate` 补齐，不必删除视图重建。
+
+### 创建后的核对
+
+`view create` 的响应不是最终验收。创建后读取视图列表，以返回的 `viewId` 定位目标；服务端没有返回 ID 时，才按名称、类型和终端唯一匹配，出现多个候选时停止。`populate` 回读应确认 `success=true`、`componentCount>0`、`fieldComponentCount>0`；重复执行应返回 `alreadyPopulated=true`。随后打开设计页，检查既有字段、字段名称与特殊配置确实出现，而非空画布。仅完成服务端回读时，记录为“待前端确认”。
+
+## 复制一套布局
+
+```bash
+e10-cli form layout copy <objId> <appId> --from <源布局ID> [--name <新名>]
+```
+
+`--from` 使用视图布局 ID；布局类型跟随源布局，名称缺省沿用源名称。平台复制响应不直接给新布局 ID，CLI 通过复制前后的视图列表反查并报告新 ID。复制出来的布局不会自动成为默认布局；需要指定用途时继续设置默认档位。
+
+## 指定布局用途
+
+```bash
+e10-cli form layout set-default <objId> <appId> <布局ID> [--for all|add|view|edit]
+```
+
+`--for` 表示用途档位：`all` 全部布局、`add` 新建、`view` 显示、`edit` 编辑，缺省 `all`。它不是 FLOW/EXCEL 类型。同一套布局同时只承担一个档位；若希望新建、显示、编辑分别使用不同版式，需要三套布局各占相应档位。只有 `all` 会使视图列表中的 `default` 为 `true`。设置后重新读取视图列表，核对布局 ID 和 `defaultType`。
+
+## 删除一套布局
+
+```bash
+e10-cli form layout delete <objId> <appId> <布局ID>
+```
+
+删除不可逆。命令应在删除后回读视图列表，确认目标 ID 已消失，不能仅凭保存响应认定成功；若该布局原来占用用途档位，结果会报告其档位。删除正占 `all` 档位的布局后的平台行为尚未独立验证，应先确定替代布局和用途安排。
+
+## 与其他能力衔接
+
+- 新建布局后要调整字段位置或网格样式，先[查询当前布局](inspect-edit.md)；大范围改动使用[完整布局文档](document.md)。
+- 要按当前字段重新排版并应用样式模板，使用[初始化](initialization.md)。这会重建目标布局，不等同于复制或 `populate` 补缺。
+- 要为指定布局和终端设置 JS/CSS，先读[布局代码块指南](code-block/code-block-guide.md)。
+- 看板、日历、思维导图等非表单视图的创建与验收范围，仍按[视图指南](../guide-form-view.md)执行；不能因为视图实体创建成功，就认为其页面组件已可用。

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

@@ -0,0 +1,76 @@
+# 建表前规划表单布局
+
+本篇用于从需求和布局样表确定 EB 表单的布局类型、字段顺序与空间蓝图，再把可直接创建的字段属性写入 `fields.json`。表单创建的完整顺序见[新建 EB 表单](../guide-create-form.md)；已有表单的编辑与初始化按[布局总览](layout-overview.md)选择专题。
+
+## 确定布局类型
+
+| 类型 | 含义 | 创建时的选项 |
+| --- | --- | --- |
+| `FLOW` | 流式布局，按容器和组件组织 | `--layout FLOW` |
+| `EXCEL` | 表格式布局，可表达网格、行列尺寸与合并 | `--layout EXCEL` |
+
+`form create` 缺省使用 `EXCEL`，但仍应根据需求明确选择。建表时确定的是该表单初始布局类型；已有表单可另外创建不同类型的表单视图布局。若需求没有说明类型，而两种类型会产生不同效果，应在建表前确认。不能把 EXCEL 的网格坐标直接用于 FLOW。
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout FLOW
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL
+```
+
+## 从需求识别布局样表
+
+在读取需求文档后、编写 `plan.md` 前，先整理字段定义，再扫描布局章节和表格。出现下列线索时，将表格视为布局样表：
+
+- 上下文明确要求“表格式布局”“Excel 样式”或“按照如下布局”；
+- 单元格使用 `[字段名]` 等占位，或标题与字段组件交替排列；
+- 存在表单标题、分组标题、合并单元格或有意义的留白；
+- 表格表达字段在页面上的位置，而非重复列举字段名称、类型和说明。
+
+逐行记录表单标题、分组标题、字段标题、字段组件、空白占位、同排字段、合并及跨列关系，并标明必填、只读、隐藏和独占一行等要求。DOCX 来源优先用 `e10-cli docx read` 的 Markdown 表格；合并关系不清晰时查看原 DOCX 对应表格结构。不要把字段清单误当成空间布局，也不要把图片中未识别的尺寸或样式编造成确定值。
+
+## 在计划中分开记录字段和布局
+
+同一表单的计划至少有两个部分：
+
+1. **字段定义**：字段类型、顺序、主表／明细归属和可直接创建的属性。
+2. **表单布局蓝图**：按原样表顺序记录标题、分组、同行关系、空白、跨列和原文说明。
+
+例如：
+
+```markdown
+##### 表单布局蓝图
+
+| 行 | 区域/分组 | 左侧 | 右侧 | 布局说明 |
+| --- | --- | --- | --- | --- |
+| 1 | 标题 | 项目信息表 | — | 合并整行 |
+| 2 | 基本信息 | 项目名称 | 项目编号 | 同排两列 |
+| 3 | 基本信息 | 项目简介 | — | 独占整行 |
+```
+
+逐项核对原样表中的每个业务字段，确保它既在字段定义中，也在布局蓝图中；保留同排关系、分组顺序和不能丢弃的静态内容。蓝图是实施依据，不是可直接提交的原生布局 JSON。
+
+## 写入 `fields.json`
+
+- 数组顺序表示字段的初始展示顺序；主表字段在前，`DetailTable` 明细表按表单结构配置。
+- 需求明确要求分组时设置 `group`；没有分组要求时不主动加分组。同名 `group` 的字段属于同一组。
+- 独占一行的字段设置 `singleRow:true`。
+- 需求明确的显示属性可写 `required:true`、`readOnly:true`、`hidden:true`；这些属性最终体现在布局组件中，创建后应核对实际布局。
+
+```json
+[
+  { "componentKey": "Text", "fieldName": "项目名称", "group": "基本信息", "required": true },
+  { "componentKey": "Text", "fieldName": "项目编号", "group": "基本信息", "readOnly": true },
+  { "componentKey": "TextArea", "fieldName": "项目简介", "group": "基本信息", "singleRow": true }
+]
+```
+
+字段类型、明细结构及各字段特有参数见[字段定义参考](../ref-form-fields.md)。`fields.json` 可以表达顺序、分组和部分显示属性，不能单靠它保证样表的精确格位、合并、行高、列宽和配色。
+
+## 创建后如何落实蓝图
+
+创建后先读取布局，确认类型、字段、分组与明细。若只需调整现有表格式网格的少量尺寸、单元格样式或字段位置，使用[布局总览](layout-overview.md)中的局部编辑路径；复杂结构使用完整布局文档路径。若必须按原图片或 XLSX 保留网格几何、静态文字和样式，使用[源样式还原](source-restoration.md)的独立流程，先建立业务字段，再绑定源网格。
+
+```bash
+e10-cli form layout read <objId>
+```
+
+建表后再新增一套流式或表格式视图布局，属于[视图与布局管理](management.md)；对当前布局重新初始化则会重排已有组件。两者均不属于本篇的建表前规划步骤。

package/skill-docs/references/form/layout/source-restoration.md

@@ -0,0 +1,388 @@
+# 图片与 Excel 源布局完整还原
+
+本指南按使用顺序说明图片或 XLSX 样式到表格式布局的完整还原方法，并给出源网格、字段绑定、样式、普通明细、保存和验收规则。先按“使用顺序”操作，再查对应规则；已有布局只需少量调整时，见[布局总览](layout-overview.md)。
+
+字段类型、选项、关联、公式、默认值和主明细创建继续由现有 CLI 完成。本功能只把已有字段放入源布局，生成原生 pageLayouts 和 workbook，再保存和独立回读。运行不依赖 Form Engine 或 Python。
+
+## 使用顺序
+
+1. 确认目标布局、现有字段和源文件。Excel 走下文的[Excel 路径](#excel-路径)；图片先实际观察，再走[图片路径](#图片路径)及样式确认。
+2. 提取源网格并编写字段绑定，核对标题、明细归属、合并和未支持项；再 `compile` 生成产物。
+3. 用 `source-review` 核对产物与当前布局的差异及前置条件，需要时生成结构预览。确认后使用源布局的 `apply` 保存，并以 `verify` 或样式诊断复核。
+4. 需要与 `form create` 连续执行时看[与创建命令衔接](#与创建命令衔接)；目标模块、视图布局和离线编译看[布局目标和离线编译](#布局目标和离线编译)。
+
+源还原的保存与回读有自己的组件身份适配规则；普通完整布局文档 `apply` 不替代这里的 `apply/verify`。
+
+## 与布局蓝图衔接
+
+明确要求保留原样表的合并、留白、尺寸、静态文字和样式时，使用本篇的源样式还原流程。字段解析、创建及业务配置仍由 CLI 完成；布局模块在全部字段补写和归组结束后，将源网格绑定到已存在的字段与组件，编译 pageLayouts，再单次保存并独立回读。
+
+Plan 中的文字蓝图不直接作为保存请求。必须产出版本化 LayoutSpec，分别绑定 TITLE、VALUE 和普通明细。图片由 Agent 实际观察形成源网格，Excel 使用确定性提取。未知或冲突位置会阻断，不生成手写原生组件 JSON，也不自动转为默认两字段一行。
+
+## 当前范围
+
+支持已有单个 PC EXCEL 页面、普通主表、多个普通明细、XLSX 网格、合并、行列尺寸、静态文字及可支持的字体、颜色、边框和对齐。复用当前值组件、标题组件、明细系统控件及其 ID，保留字段业务配置。
+
+FLOW 转换、嵌套容器、二级明细、移动端、多页、宏和旧 XLS 文件不属于当前源还原范围。已有这些布局的普通命令继续保留；源还原遇到它们会明确阻断，不会降级为 Text 或默认两字段一行。
+
+源标题要与现有字段标题一致。字段重名时用真实 fieldId，主明细归属不同不能混绑。图片星号若与已有必填设置冲突，应先通过字段业务路径处理，不能在样式编译中推断并修改。
+
+## Excel 路径
+
+```bash
+e10-cli form layout extract 样表.xlsx --out layout-source.json
+```
+
+提取结果保留所有 Sheet，由 layout-spec 显式选择一个。行列坐标从零开始，合并控件绑定左上角。检查源文件哈希、静态说明、合并、字段位置和未支持项，再产出 LayoutSpec。
+
+```json
+{
+  "schemaVersion": "e10.layout-spec/v1",
+  "sourceHash": "<复制 extract 输出的 sourceHash>",
+  "sheet": "样表",
+  "fields": [
+    {"fieldName":"金额","title":{"row":1,"col":0},"value":{"row":1,"col":1}},
+    {"fieldId":"<真实字段ID>","title":{"row":2,"col":0},"value":{"row":2,"col":1}}
+  ]
+}
+```
+
+Schema 随 CLI 发布在 `assets/layout-spec.schema.json`，可通过 `skill root` 定位文档，通过 npm 包 assets 获取。名称可唯一匹配时允许 fieldName；fieldId 始终使用字符串。该描述不接受 componentKey、required、options、formula 或关联创建指令。
+
+```bash
+e10-cli form layout compile <objId> --source @layout-source.json --spec @layout-spec.json --out layout-artifact.json
+e10-cli form layout source-review <objId> --artifact @layout-artifact.json --out layout-review.json
+```
+
+compile 仅查询当前字段和布局，不写业务系统，不分配 ID。输出包含原生前置快照、目标和输入指纹、完整保存请求及验证条件。source-review 重新读取当前布局，用完整布局差异展示源产物将修改的内容，并核对目标、快照、字段和图片样式确认状态；不保存布局。报告中的 `genericDiff` 是预览差异，`documentExcludedPaths` 列出完整文档不允许编辑、由源还原流程单独处理的页面元数据。`canProceedToSourceApply` 为 true 后，结合源文件和字段映射核对结果执行：
+
+```bash
+e10-cli form layout apply <objId> --artifact @layout-artifact.json --out layout-result.json
+e10-cli form layout verify <objId> --artifact @layout-artifact.json --out layout-verification.json
+```
+
+apply 会单次保存并自动独立回读。verify 可单独再次验证。旧快照或字段配置变化需要重新 compile；写响应丢失时先查询，不盲目重试，不执行 initLayout。
+
+Excel 证据在 compile/apply 时会从真实文件重新提取比对；只填一个哈希或修改源 JSON 的样式不能通过。XLSX 到 Native 是兼容投影，字体使用 pt×96/72、列宽按兼容算法转换，并不证明浏览器像素完全一致。
+
+空白行尺寸及网格范围内的行列继承样式也参与提取。源 JSON 只接受约定的单元格、行列、合并和样式属性，不接收原生 cellType、脚本或回调，行列尺寸数组必须完整。主 workbook 保留原有其他配置；冻结范围超出新网格时阻断。Excel 和旧图片产物的 VALUE 前景色使用配对 TITLE；新图片 imageStyles 模式保留分别观察到的标题/值颜色，不把标题红字自动传播成输入值红字。
+
+公式保留在源证据中，字段绑定后移除源输入占位和源公式，计算仍使用已有字段配置。未绑定的静态公式默认阻断；有缓存显示值且明确设置 allowUnsupported=true 时，只投影缓存值并报告遗漏，不创建计算规则。没有缓存值不能继续。
+
+## 图片路径
+
+```bash
+e10-cli form layout image-context 样图.png --out image-context.json
+```
+
+Agent 必须实际查看原图，在此哈希下输出结构化观察。只记录可见网格、合并、尺寸、标题、控件区域和样式；不根据灰色、星号或控件外观改变字段类型、只读、默认值和关联。没有独立 OCR/模型 API。
+
+观察 JSON 使用以下形状；该例为结构示意，内容必须来自本次原图：
+
+```json
+{
+  "schemaVersion":"e10.layout-source/v1",
+  "sourceType":"image",
+  "sourceHash":"<本次 image-context 返回的哈希>",
+  "observations":{"confidence":"HIGH","confirmed":false},
+  "unsupported":[],
+  "sheets":[{
+    "name":"图片观察","rowCount":2,"columnCount":2,
+    "rows":[{"size":40,"visible":true},{"size":30,"visible":true}],
+    "columns":[{"size":100,"visible":true},{"size":180,"visible":true}],
+    "spans":[],
+    "cells":[
+      {"row":"1","col":"0","value":"金额","style":{"foreColor":"#000000"}},
+      {"row":"1","col":"1","value":"[金额]","style":{"backColor":"#FFFFFF"}}
+    ]
+  }]
+}
+```
+
+HIGH 可以进入可审阅草稿；MEDIUM 必须经用户确认后将 confirmed 记为 true；低置信度或无法表示的结构不能猜测。对观察稿的确认不自动授权远程写入。
+
+```bash
+e10-cli form layout extract 样图.png --observation @image-observation.json --out layout-source.json
+```
+
+然后使用与 Excel 相同的 compile/apply/verify。图片不会进入默认两字段一行模板，也不会伪装成确定性 Excel 证据。`sourceStyleVerified` 对图片保持 false，表示没有确定性 Excel 源样式证明；`pixelVerified` 单独表示像素验收，两者不能混为一谈。新图片模式用 imageStyleReport 报告观察样式的原生投影与回读，不代表原图像素相同。
+
+### 图片样式确认与修改
+
+图片提取后，Agent 必须主动展示识别出的样式并等待用户确认。按主标题、字段标题、输入内容等分组列出字体、字号及单位、颜色（色名与十六进制值）、粗细、水平和垂直对齐；不同样式不能混成一套。字体与字号是视觉估计，未知值显示“未识别”，不能把默认 sans-serif、12px 或左对齐冒充图片识别结果。字段标题必须逐个观察居中/居左/居右和垂直对齐；不能只识别页面大标题的对齐。
+
+```bash
+e10-cli form layout style-review --source @layout-source.json --spec @layout-spec.json --out layout-review-source.json --report style-review.json
+```
+
+报告同时提供 recognized（图片原识别值）、effective（本次最终配置）、accepted/rejected（用户调整成功/失败项）及 missingAttributes（标题未识别属性）。MEDIUM 观察尚未能 extract 时，可将 image-context 的真实 sourceFile 写入观察稿，先对观察稿运行 style-review，用户确认后再 extract。HIGH 只允许先编译草稿，不表示用户已同意样式。`observations.confirmed` 只可反映本次用户真实确认，不能为了通过命令自行置 true。
+
+用户可直接说“来文单位改为微软雅黑、小四、蓝色并居中”。Agent 负责将自然语言定位到已创建字段或静态单元格，CLI 不调用另一套模型。将调整写成以下 JSON（示意 fieldId 必须替换为真实值），而不是修改已签名产物或原生保存请求：
+
+```json
+{
+  "fields": [{"fieldId":"<真实字段ID>","title":{
+    "fontFamily":"微软雅黑","fontSize":"小四","color":"蓝色",
+    "textAlign":"居中","verticalAlign":"垂直居中"
+  }}],
+  "cells": [{"sheet":"图片观察","row":0,"col":0,"style":{"fontFamily":"方正小标宋简体","fontSize":"22pt","color":"#FF0000"}}]
+}
+```
+
+fields 只接受 title/content 文字样式，cells 指向源网格合并区域左上角，page 仅支持 backgroundColor。字段必须已在图片样式或 LayoutSpec 中唯一定位，不新建字段、不修改必填/只读/默认值。原生字体选项中文名映射为字体配置值；未知字体、模糊字号、无效颜色等逐项拒绝，保留该项原图片识别配置，其他有效项照常采用。常见中文字号、小四=12pt=16px，显式 pt/磅 按 96/72 转 px，裸数字默认 px。映射可编码不等于目标电脑已安装字体，最终字形需运行态核对。
+
+收到用户确认或明确修改指令后，告知采用项与回退项，使用同一最终配置标记确认并重新编译：
+
+```bash
+e10-cli form layout style-review --source @layout-source.json --spec @layout-spec.json --overrides @style-overrides.json --confirm --out layout-confirmed-source.json --report style-confirmed.json
+e10-cli form layout compile <id> --module workflow --source @layout-confirmed-source.json --spec @layout-spec.json --context @layout-context.json --out layout-artifact.json
+```
+
+用户接受原识别样式时省略 --overrides。最后一个命令的 module 按真实目标选择，示例 workflow 不是自动切换规则。未带 --confirm 只生成待确认源文件及报告，输出不能覆盖原观察；确认后改了样式需重新确认、重新 compile，不能沿用之前的已签名请求。新 v4 图片 apply 在任何远程查询/保存前检查确认状态，form create 的图片源选项也在建表前检查；Excel 与旧编译产物保留既有行为。
+
+v4 将几何区域、单元格规则和字段规则形成的最终文字样式同步到 config.styles.title/content，包含水平 text-align 与垂直 align-items；单元格仍保存 hAlign/vAlign。明确的字段规则优先于单元格规则，单元格规则优先于区域规则。不推定所有标题均居中，也不将纵向排字等同于居中；平台未核对的排字效果仍需报告遗漏。v3 及更旧产物按原版本重编译校验，修复不会改变它们的摘要；要获得新修复需要重新观察/确认并 compile。
+
+### 图片样式观察与诊断
+
+观察 JSON 可以增加 imageStyles（完整 Schema 在 `assets/schemas/image-style-observation.schema.json`；CLI 包 assets 内也提供）。图片 extract 自动规范化旧单元格 align/bold 键，并启用新图片样式模式；旧的已编译产物保留原编译版本校验；新编译的图片和 Excel 布局使用下文的留白及列宽规则。
+
+```json
+{
+  "imageStyles": {
+    "schemaVersion": "e10.image-styles/v1",
+    "page": {"backgroundColor":"white"},
+    "cells": [
+      {"sheet":"图片观察","row":0,"col":0,"style":{
+        "color":"#F00","fontSize":18,"fontUnit":"pt","fontFamily":"SimSun",
+        "bold":true,"align":"center",
+        "border":{"color":"red","width":1,"line":"solid"}
+      }}
+    ],
+    "fields": [
+      {"fieldId":"<真实字段ID>","title":{"color":"red","fontSize":16,"bold":true},
+       "content":{"color":"black"},
+       "input":{"height":40,"backgroundColor":"white","border":{"color":"red","width":1,"line":"solid"}}}
+    ],
+    "issues": []
+  }
+}
+```
+
+cells 的位置相对于源 Sheet，必须是合并区域锚点；这里的静态标题示例需要在源网格中另留一行，不能与业务字段 TITLE/VALUE 共用同一单元格。fields 支持精确 fieldId/fieldName 和 subFormId，不能携带 required、options、公式或其他业务属性。issues 记录字体无法判断、水印、未知控件等遗漏；默认阻断，有明确接受时才用 allowUnsupported。
+
+颜色支持 #RGB/#RRGGBB/rgb 与有限常用色名；pt 转 px。align 是 textAlign 别名，bold 对应字体粗细 700/400，**不是 textDecoration=1**（下划线）。字号和字体家族不能仅凭 bold 推定；静态文字缺少必要字号时阻断。单元格的 font/hAlign/vAlign/wordWrap 与分边边框继续保留。
+
+编译同时处理单元格样式、关联值组件的原生 config.styles（title/content/inputStyle）、页面 formStyle.styleConfig.formLayout.background。只使用已有 applyStyle 分类，不重分配类别、不切换模板。缺失或未核对的样式分类明确报告。TextArea 不接受 inputStyle.height；使用字段样式的 textArea.rows、fitCell、autoHeight，对应原生 config.height、fullHeight、disableAutoHeight。fitCell=true 时优先撑满单元格，v3 不额外写 rows 高度；autoHeight 仍独立校验，不能因 fullHeight 已落库就忽略该属性。仅支持普通 TextArea，不转换富文本、只读和字段业务配置。
+
+保存请求的 formStyle 是对象，但内部 styleConfig 必须是 **JSON 字符串**，与后端 FormStyle 的 String 字段一致。CLI 内部解析为对象修改后会编码回字符串；不能因为前端展示时将其解析成对象，就把对象原样发给 saveFormAndLayout。2026-10-13 fix1 已修复此序列化错误，旧版本含页面样式的编译产物应重新 inspect/compile，不手工修改已签名请求。
+
+附件/FileComponent 的 UploadStyleConfig 不支持 inputStyle。附件的标题、内容使用 title/content，不能借用单行输入框的样式属性；这属于正确的原生类型限制。
+
+图片样式只覆盖明确观察的属性，保留其他原生展示配置和业务属性。标题/内容区域宽高通过 rows/columns/spans 表达，单行输入框尺寸使用 input。不能只写单元格颜色并忽略已有组件 customStyle 的覆盖，也不能用一套默认红色模板代替观察。
+
+```bash
+e10-cli form layout style-audit <objId> --artifact @layout-artifact.json --out style-report.json
+### 离线核对与当前布局上下文
+e10-cli form layout style-audit <objId> --artifact @layout-artifact.json \
+  --context @current-context.json --out style-report.json
+```
+
+imageStyleReport 分别报告 COMPILED、VERIFIED、MISMATCH、INCOMPLETE 或 NOT_OBSERVED，包含比较属性数、匹配数及 cell/component/page 差异。VERIFIED 表示投影属性回读一致；整体 verified 还要求字段、布局身份及结构一致。没有观察样式或未闭合属性不能自动宣称还原完成，更不能转默认布局继续执行。
+
+### 整行、快照与认证诊断
+
+- 独占整行通过 TITLE 与 VALUE 各自的合并跨度完成；例如 4 列的一整行用标题第 0 列和值第 1～3 列，绑定各自锚点。不要将二者绑同坐标，也不要为通过校验改 singleRow 业务配置。
+- LAYOUT_SNAPSHOT_CHANGED 表示 updateTime/pageVersion 或其他布局内容变化：重新 inspect → compile → apply。不能只改时间戳来绕过并发检查；LAYOUT_FIELDS_CHANGED 单独表示字段配置变化。
+- 认证处理沿用现有 CLI。登录态缺失时使用当前入口重新认证，不手工修改 enc/data 或复制其他工具的密钥；离线 compile 不迁移登录态。
+- 源布局保存使用单次请求，认证恢复或响应未知仍先独立回读，不因登录恢复盲目重复保存。
+
+源布局 JSON 与原生回读使用专用解析器：裸长整数保留为精确字符串，网格尺寸及字号小数保留为数值。原客户端默认解析保持基线行为；仅源布局命令、带 layout-source 的创建及 read --raw/--out 启用专用解析，不改变其他命令的数据类型。
+
+## 普通明细
+
+LayoutSpec 可增加 details，必须使用真实 subFormId。anchor 是主表中明细容器的源位置；sourceRegion 是迁入独立明细 workbook 的源矩形，必须与 anchor 分开。fields 的 title/value 坐标仍相对于原源 Sheet。
+
+```json
+{
+  "subFormId":"<真实subFormId>",
+  "anchor":{"row":4,"col":0},
+  "sourceRegion":{"row":5,"col":0,"rowCount":2,"colCount":4},
+  "fields":[
+    {"fieldId":"<真实明细字段ID>","title":{"row":5,"col":0},"value":{"row":6,"col":0}}
+  ]
+}
+```
+
+迁移按完整行处理，区域外的主表字段或静态说明也不能占这些行。未绑定的明细静态内容、跨界合并、相互重叠的明细区域均会阻断。原生明细需要既有完整子 workbook、五个结构行、至少二十个逻辑行和八类标准系统控件；不生成只有一行的表壳。
+
+保留明细系统配置、按钮和结构行。只把源字段标题和值样式投影到既有明细列，并按源尺寸调整业务列及相关行；字段 ID、dataKey 和业务选项等保持原样。
+
+明细的 `columnCount` 表示逻辑列容量，`columns` 表示显式列配置，平台可能省略尾部默认列，因此两者不必相等。例如 6 个业务字段加 2 个系统列，允许 `columnCount=10`、`columns.length=8`；原生容量与默认列表示原样保留，不增加业务字段凑数，也不擅自填充无引用的列配置。数字字符串容量可兼容读取；单元格和合并范围必须位于容量内，实际承载业务字段的列必须有可用的列配置。缺系统控件、越界、业务列配置缺失仍会阻断，不能简单放开校验或缩小容量绕过。
+
+“八类标准系统控件”指按钮、勾选、序号等不同系统控件类型，不是要求 8 个业务字段。明细值区域是可重复展示数据的模板，不限制运行态只能一条记录。截图中的多条示例数据需与字段/布局分开确认；未绑定静态内容的保护继续保留，真实业务记录应另外处理数据，不能直接删除或新增字段冒充。
+
+## 与创建命令衔接
+
+独立建好字段后执行还原，是推荐的可审阅路径。需要串联时，form create 支持：
+
+```bash
+e10-cli form create <appId> "<表单名>" --fields @fields.json --layout EXCEL \
+  --layout-source @layout-source.json --layout-spec @layout-spec.json \
+  --layout-artifact-out layout-artifact.json
+```
+
+源输入、产物和报告路径在建表前检查；字段、高级属性、公式和归组重排完成后才精确保存。失败返回已创建的 objId/formId 和 layoutRestoration，不删除表单，也不重新创建。先检查差异，后续针对同一 objId 编译和重试。保存已回读通过但报告落盘失败时，明确返回 saved=true 与 reportWriteError，并以非零退出码提醒补存报告。
+
+不要在源布局保存后运行会整体重排的 group/init 等命令。后续增量 add-field 和 move 保持现有行为，但将改变已验收的源布局；应按变更范围重新验收。
+
+## 布局目标和离线编译
+
+默认使用 eBuilder objId。Workflow 和 Business 传 `--module workflow|biaoge --id-type form`；这些请求适配已提供，仍需在对应环境独立验收。已创建的视图或节点布局使用 `--view-id`，视图原生路由按需要显式加 `--target-kind view`。不自动创建布局记录或改节点绑定。
+
+```bash
+e10-cli form layout inspect <objId> --out layout-context.json
+e10-cli form layout compile <objId> --context @layout-context.json \
+  --source @layout-source.json --spec @layout-spec.json --out layout-artifact.json
+e10-cli form layout read <objId> --raw --out native-layout.json
+```
+
+inspect 仅查询并导出完整原生数据。带 context 的 compile 完全离线，无须登录；apply 仍会读取真实当前状态，无法用伪造上下文跳过目标和快照核对。read --json 的简化输出不能替代完整上下文。
+
+## 验收与差异
+
+报告分别输出 verified、structureVerified、sourceStyleVerified、fieldsPreserved、pixelVerified 和 differences。API 200 不代表通过，必须独立回读。服务端换组件 ID 时按 fieldId/associatedId/subFormId 一对一适配；身份缺失、重复或类型变化仍失败。
+
+unsupported 包括源中的浮动图片、冻结、筛选、行列分组、富文本局部样式、条件格式、部分数值格式、链接、数据验证等尚未投影的内容。默认阻断；用户明确接受这些遗漏时可在 spec 中设置 allowUnsupported=true，报告仍列出遗漏，完整 sourceStyleVerified 不得为 true。
+
+编译产物包含原始快照，保持到验收及故障处理结束。当前没有自动回滚；结果未知先回读，发现其他人修改后重新编译，不能盲目覆盖。产物及报告以私有权限保存到指定路径，禁止输出覆盖源文件、描述或产物本身。
+
+### 图片几何与保存前结构核对
+
+图片视觉理解仍由 Agent 完成。image-context 返回真实 imageWidth/imageHeight；禁止按默认模板臆造列宽、行高和合并。新图片观察应提供 imageStyles.geometry，按原图像素记录边界和完整区域分割，CLI 据此计算 rows/columns/spans。区域边框沿整段合并边缘投影，不能只给左标签画框。标题在表格外时应独立留一行且无表格边框。
+
+```json
+{
+  "geometry": {
+    "imageWidth": 400, "imageHeight": 100,
+    "sheets": [{
+      "sheet": "图片观察",
+      "xLines": [0, 40, 200, 240, 400], "yLines": [0, 40, 70, 100],
+      "regions": [
+        {"row":0,"col":0,"rowCount":1,"colCount":4},
+        {"row":1,"col":0,"rowCount":1,"colCount":1,"style":{"border":{"color":"red","width":1,"line":"solid"}}},
+        {"row":1,"col":1,"rowCount":1,"colCount":3,"style":{"border":{"color":"red","width":1,"line":"solid"}}},
+        {"row":2,"col":0,"rowCount":1,"colCount":1},
+        {"row":2,"col":1,"rowCount":1,"colCount":1},
+        {"row":2,"col":2,"rowCount":1,"colCount":1},
+        {"row":2,"col":3,"rowCount":1,"colCount":1}
+      ]
+    }]
+  }
+}
+```
+
+以上仅是 Schema 示意，坐标必须换成本次原图观察值，不是默认模板。边界严格递增且位于真实图片内，边界数为行/列数加一；regions 必须完整覆盖网格（含空白区），不重叠。尺寸、合并、区域边框以 geometry 为依据，独立 cells/fields 样式可细化颜色和字体。不能将星号、业务值、水印转成默认值。合并覆盖其他文字、字段坐标落在非锚点、遗漏区域都会阻断。旧观察与已编译产物未携带 geometry 时仍兼容，但只能证明观察稿被编译和保存，不能证明几何符合原图。
+
+多行文本外观示例：
+
+```json
+{"fieldId":"<真实字段ID>","textArea":{"rows":1,"fitCell":false,"autoHeight":false}}
+```
+
+rows 是原生显示行数（1～50），不能填像素。不得看到源图空值或只读展示就自动改字段类型或 readOnly。
+
+compile 后生成结构预览，并实际查看原图与预览；核对标签/值列比例、单字段行的值区域是否跨列、正文等行高、标题是否在表格外、整张网格边框与文字颜色，再进入 apply：
+
+```bash
+e10-cli form layout preview --artifact @layout-artifact.json --out layout-preview.html
+```
+
+preview 完全离线，不鉴权、不写业务系统；显示原图及原生 workbook 结构，字段值用占位符，不能把它当 E10 控件运行态截图。imageStyleReport.verificationScope 固定为 OBSERVATION_TO_NATIVE_READBACK、sourceImageCompared=false。VERIFIED 只代表观察投影的属性回读一致；还原完成必须补充 E10 浏览器实际视觉核对，pixelVerified 保持 false。
+
+### 原生样式清理与输入层选择
+
+EXCEL 前端同时消费单元格与组件样式，组件 customStyle 会覆盖从单元格派生的内容样式。没有组件 styles 的基准样本，只能证明该样本不依赖自定义组件样式，不能推导所有组件样式无效。
+
+imageStyles.componentStyles 的默认值 merge 保持原行为。replace 在编译副本中删除已绑定标题和值的旧 config.styles，再写入本次观察的组件样式；workbookOnly 则清理这些组件样式并仅保留 workbook 样式。范围外组件与原始 context 保持不变。清理不允许修改 inspect 导出的 context，更不能从 snapshotHash 中排除 config.styles：并发修改仍会被阻断。
+
+字段 inputTarget 默认 component，描述输入控件自身边框、背景、宽高；显式 cell 描述整个值单元格边框与背景，写入 workbook 值格，不写新的 inputStyle。cell 不接受输入框宽高（网格尺寸使用 geometry）。workbookOnly 下有 input 的字段必须显式选择 cell，避免静默丢弃控件样式。不要把原图蓝色小输入框边框当成红色表格值区域边框。
+
+字段 displayTitle 只能绑定真实 fieldId，内容是原图可见纯文本；通过原生 enableDisplayName/displayName.nameAlias 修改布局展示标题，保留字段名称与 ID。源 TITLE 必须与该显式展示标题相符。未指定时仍严格要求源标题与已有标题一致，不猜测别名、不给字段自动改名。
+
+平台源网格的 parentName 仅接受原生 Normal，未解析的命名样式仍拒绝；locked 只接受布尔值，保留为网格单元格属性，不转换成字段 readOnly、权限或业务配置。未知属性、字符串形式 locked 均拒绝。
+
+报告新增 projectionVerified（只有投影属性独立回读一致才为 true）；COMPILED 和 NOT_OBSERVED 均为 false。它与 pixelVerified 分开，不能将 true 翻译为“已按原图还原完成”。
+
+### 空白边列与列宽
+
+新编译的图片和 Excel 主布局按全部可见列（包括留白）合计100%处理。缺少空白边列的一侧补一列4%；两侧都缺少时正文分配92%。已有空白边列时复用其原有比例，不再补该侧，不强制改成4%。隐藏列保持隐藏且百分比为0。
+
+空白边列必须不含字段、正文文字、公式、区域横边框、外侧边框或非白色填充；仅与正文共用的内侧竖边框不妨碍复用。跨整页的静态标题允许跨原边距识别，编译后标题限定在正文列范围。无字段但含说明的边列不是留白列，不能丢弃。原字段、合并、静态内容和必要冻结位置同步调整；明细子 workbook 保持原生系统结构，不额外补左右空白列。
+
+列宽以0.01%整数单位计算，总量10000。已有边距比例保留至两位小数，新增边距固定4%；正文列在相对理想比例偏差不超过0.25个百分点时优先整数，否则使用最多两位小数。尾差按比例误差分配，不让所有误差积到最后一列。不要使用浮点数直接相加相等作为100%的验算，应对每列乘100取整后合计10000。
+
+compile 输出 presentation，包含补充/复用边距、最终列宽及合计100%的结果。v2 引入留白规则，v3 产物增加合并锚点边框、坐标归一和有效高度投影，当前新产物为 v5（见下文）。此前无标记/v2 的产物仍按原规则重编译校验。采用新规则时重新 inspect → compile → preview → apply，不手工改旧产物。
+
+### 工作流模块与初始化
+
+工作流表单使用 formId，inspect 或在线 compile 必须传 --module workflow；eBuilder 默认使用 objId，已有 eBuilder formId 使用 --id-type form。模块缺失时只给出明确提示，不自动跨模块查询或切换。apply/verify 从编译产物继承目标模块，无需重复指定；preview 完全离线，不接收模块参数。
+
+```bash
+e10-cli form layout inspect <流程表单formId> --module workflow --out context.json
+e10-cli form layout compile <流程表单formId> --module workflow \
+  --source @source.json --spec @spec.json --context @context.json --out artifact.json
+e10-cli form layout preview --artifact @artifact.json --out preview.html
+e10-cli form layout apply <流程表单formId> --artifact @artifact.json --out result.json
+```
+
+新字段必须先生成完整原生组件，源布局不负责补造组件。推荐批量 wf-form add-fields，默认在末尾初始化一次，再 inspect。多次 add-field 可以在中间使用 --no-init，但全部字段完成后必须执行最后一次 layout init，再 inspect/compile。不能统一建议建字段加 --no-init 后直接还原；原布局中没有新字段组件时会阻断。源布局保存后不得再自动 initLayout。
+
+图片 geometry 区域的跨行底边、跨列右边同时写入合并锚点与原外围单元格，以适配当前 E10 合并区域绘制。仅给覆盖格写边框可能导致运行态断线；额外边框计入投影和回读。workbook cells 的 row/col 统一为字符串，组件 excel.row/col 仍按原生数值契约保存。
+
+保存后验收只从比较副本排除 pageLayouts 页级 updateTime/updateTimeStamp/pageVersion，并在 ignoredPageMetadata 列出。保存前 snapshotHash 仍保留完整版本及 config.styles；不得手工清理 context 或从摘要忽略样式来绕过并发保护。
+
+apply 的 saveAccepted=true 表示接口接受请求；null 表示没有发送请求或响应未知，结合 mutationStarted 判断。saved/verified 表示独立回读符合目标，styleComplete 表示观察投影无遗漏且回读一致。接口接受与回读失败可以同时出现，不能把它解释成接口未保存，也不能据此自动重发。
+
+若 TextArea 的高度/自动高度被字段元数据覆盖，报告会在 platformNotPersisted 列出，但有效展示差异仍保留在 differences。disableAutoHeight 被运行态使用，不能统一忽略。需要修改字段层配置时走字段配置路径，本模块不自动更新业务字段。fitCell=true 时 rows 不再独立投影，报告 notes 说明原因。
+
+观察中的说明、识别依据、业务示例值不写默认值等放入 imageStyles.notes；真正未还原的虚线框、未知控件或样式属性放入 issues。notes 不导致 INCOMPLETE，issues 仍表示遗漏；不自动按关键词把历史 issues 改成 notes，也不因为 workbook 逐格一致就宣称像素还原完成。
+
+## 表格边线完整性与粗细确认
+
+图片必须逐个观察表格正文范围及四侧外框。范围使用源 Sheet 的零起始行列，不包含新增的 4% 留白，不把表格上方标题、编号或控件蓝框包进正文外框。贴着图片边缘的细线也要检查。边线存在时记录颜色、粗细与线型；明确没有边线填 none，不能判断填 unknown。只有原图明确没有表格时才能使用空数组；缺失 tableBorders 表示尚未观察，不等于没有外框。
+
+```json
+{
+  "imageStyles": {
+    "schemaVersion": "e10.image-styles/v1",
+    "tableBorders": [{
+      "sheet": "图片观察", "row": 2, "col": 0, "rowCount": 7, "colCount": 5,
+      "top": {"color":"#000000", "width":2, "line":"solid"},
+      "right": {"color":"#000000", "width":2, "line":"solid"},
+      "bottom": {"color":"#000000", "width":2, "line":"solid"},
+      "left": {"color":"#000000", "width":2, "line":"solid"}
+    }],
+    "issues": []
+  }
+}
+```
+
+该范围只为示意，须按本次原图填写；不能套成所有图片的默认范围或默认 2px。内部边线继续通过 geometry.regions.style 或 cells.style 记录。外框观察最后作用于正文边缘，覆盖冲突的旧外框样式；none 同时清除对应相邻格的共享边线，unknown 不补画。外框切断合并区、穿越源明细迁移行或多个声明冲突时阻断并要求修正观察。
+
+v5 几何投影只清除合并内部的无效边线；区域没有声明某条外围边线时，保留源单元格已有的边线。明确区域样式优先于源单元格，最后采用 tableBorders 的外框声明。合并区域的外边线同时写入外围单元格和必要锚点，再整体平移以保留边距；不将边框画到新增空白列。Excel 不使用图片外框观察。
+
+style-review 展示 tableBorders（四侧外框）和 gridBorderStyles（网格内已有线型、粗细、颜色清单），issues/notes 也必须向用户说明。字体、字号、对齐、几何比例、分行和竖排等仍要对照原图核对，已知遗漏不得以 API 回读通过替代视觉验收。
+
+线宽按真实源图像素及缩放估计，不能把所有边线统一识别为 width=1。原生实线 1/2/3px 分别编码为 style=1/2/5；虚线 1/2px 为 style=3/8。原生点线与双线以 2px 绘制；旧观察中的 width=1 点线/双线仍保留历史编码，预览和清单如实显示原生宽度，不声称其为精确 1px。不能通过同时给相邻格画线模拟加粗。
+
+用户明确要求表格线加粗或改色时，Agent 可整理如下 overrides；只修改已声明表格正文内已有边线及已识别外框，不新增 none/unknown 边线，不改变控件输入框边框、编号区或页标题：
+
+```json
+{"gridBorderStyle":{"width":"2px","color":"黑色","line":"实线"}}
+```
+
+使用已有 style-review --source ... --spec ... --overrides ... --confirm --out ... 命令，前提是用户已确认或明确给出修改指令；无法转换的粗细/线型逐项保留原值并列入 rejected，其他有效项继续采用。默认不修改内部线宽；用户仅调整外框时应修改观察稿的对应外框声明，不能使用全表格 gridBorderStyle。
+
+compile 可对旧观察生成待审草稿并提示 IMAGE_BORDER_OBSERVATION_REQUIRED；新 v5 图片在确认、form create 前置检查和 apply 前要求明确 tableBorders。unknown 默认阻断，只有用户已明确接受缺失并使用 allowUnsupported 时才可继续，报告保持 INCOMPLETE。style-audit/verify/apply 结果增加 imageBorderReport，逐项核对已声明边线及明确无边线（含合并锚点），变细、缺失、错色和多画都能定位。此报告证明观察到原生回读的投影，不证明原图像素完全一致。
+
+v5 承接 v4 的标题对齐和样式二次确认；无标记、v2、v3、v4 产物仍按对应版本重编译校验。采用本次修复需要重新观察边框、用户确认并 compile，不能直接修改旧产物中的保存请求。