weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/report/ref-report-commands.md

@@ -0,0 +1,122 @@
+# 报表命令速查
+
+> 全部挂在 `e10-cli report` 下。全局加 `--profile <名>` 切环境、`--json` 出结构化结果。
+> 破坏性命令（`delete` / `lifecycle recycle purge` / `cleanup --apply`）必须用户本轮明确要求才执行。
+
+---
+
+## 建表
+
+| 命令 | 用途 |
+|---|---|
+| `report build --spec <file>` | 声明式一步建表（**首选**）。spec 最小形状 `{"appId":"…","name":"报表名","columns":[{"title":"列标题"}]}` —— 列定义的键名是 **`columns[]`（不是 `fields`）**，**`form` 是表单名字符串（不是对象）**，写错会回「spec 需要包含 appId / name(报表名) / columns[]」；完整 schema 见 `spec-build-schema.md`。spec 写 `sources[]` 即**多数据源**，见 `guide-report-multisource.md` |
+| `report render <reportId> --app-id <id> [--page-row-count <n>] [--condition <json>] [--dump <file>]` | **渲染回读**：真跑一遍拿展开后的行列数，是「关联/公式/条件格式真的生效」的唯一证据 |
+| `report build --spec <file> --dry-run` | 只做定源与字段预检 |
+| `report build ... --form-confirmed --source-id <id>` | 用户已确认表 |
+| `report build ... --field-confirmed "列A,列B"` | 确认文案与显示名不同 |
+| `report find <appId> [表名]` / `--list` / `--suggest <kw>` | 应用内定源 |
+| `report create blank --app-id --name` | 空白报表 |
+| `report create template --app-id --name --model-id` | 按模板建 |
+| `report create quick --app-id --name --quickly-file <f>` | 快速构建（列表式） |
+| `report create models` | 列出可用模板 |
+
+## 读取
+
+| 命令 | 用途 |
+|---|---|
+| `report read <reportId> [--fields]` | 基础信息 + 数据集 + 字段记录 |
+| `report list --app-id <id>` | 应用内报表列表 |
+| `report app-search --name <kw>` | 搜应用 |
+
+## 数据集侧栏
+
+| 命令 | 用途 |
+|---|---|
+| `report dataset add <reportId> --app-id (--form <名>\|--source-id <id>)` | 给已有报表**再挂一个数据源**（同源只挂一次） |
+| `report dataset list <reportId> --app-id` | 已挂载数据集 |
+| `report dataset rename --dataset-id --name` | 改显示名 |
+| `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 sort get\|save\|clear --dataset-id [--file]` | 排序 |
+| `report dataset replace --file <f>` | 整表换源（含 fieldMap） |
+
+## 查询条件
+
+| 命令 | 用途 |
+|---|---|
+| `report query list <reportId> --app-id` | 列出条件 |
+| `report query save <reportId> --app-id --item <f> [--show-where 高级搜索\|筛选]` | 保存一条 |
+| `report query type <reportId> --app-id [--show-where]` | 设显示方式（**报表级批量覆盖**） |
+| `report query check-echo <reportId> --app-id` | 回显体检 |
+| `report query fix-echo <reportId> --app-id` | 短码化修复 |
+| `report query verify <reportId> --app-id [--fix]` | Q1~Q10 合规体检 |
+| `report fix query-default <reportId> --app-id [--set ...] [--all] [--apply]` | 补默认值三件套 |
+| `report fix query-style <reportId> --app-id [--id ...] [--delete-id ...] [--apply]` | 清未点名的展示样式 |
+| `report validate query --map-show-where "顶部筛选"` | 显示方式说法映射 |
+
+## 权限
+
+| 命令 | 用途 |
+|---|---|
+| `report scope list <reportId> --app-id` | 读共享范围 |
+| `report scope set <reportId> --app-id --scope "all"` / `"部门:销售部,人员:张三"` | 设共享范围（全量替换 viewRight） |
+| `report scope matrix list\|save\|delete <reportId> --app-id [--type 1\|-1]` | 权责矩阵 |
+
+## 分组 / 生命周期 / 版本
+
+| 命令 | 用途 |
+|---|---|
+| `report group list\|add\|delete --app-id [--name] [--group-id]` | 报表分组 |
+| `report lifecycle copy-and-menu --app-id --source-name` | 复制 + 授权 + 挂菜单 |
+| `report lifecycle add-menu --app-id --report-id --menu-name` | 挂菜单 |
+| `report lifecycle move --app-id --report-id --group-id` | 移到分组 |
+| `report lifecycle transfer --report-id <ids> (--app-id \| --app-name)` | 转移到别的应用 |
+| `report lifecycle recycle list\|restore\|purge --app-id / --report-id` | 回收站 |
+| `report version save\|list <reportId>` | 版本 |
+| `report snapshot set\|list <reportId> [--cron] [--snapshot-name]` | 定时快照 |
+| `report restore <reportId> --version <versionId>` | 从版本回滚 |
+| `report cleanup --app-id [--prefix] [--apply]` | 空壳报表清理 |
+
+## 校验 / 体检 / 修复
+
+| 命令 | 用途 |
+|---|---|
+| `report validate base --name ...` | 报表名等基础字段规范 |
+| `report validate condition (--file\|--inline\|--map\|--report-id)` | 条件格式白名单 |
+| `report validate format (--map\|--file\|--list)` | 数字格式 / 日期分组 / 字号 |
+| `report validate transform (--map\|--file\|--list)` | 转换面板 |
+| `report validate href (--map\|--file\|--list) [--fix]` | 事件超链接 |
+| `report validate gridline\|blank (--file\|--inline)` | 网格线 / 空白风险 |
+| `report validate style [--list\|--inline]` | 默认分层样式 |
+| `report verify bind\|all\|meta\|condition\|format\|blank\|gridline\|contract\|limit <reportId>` | 线上体检 |
+| `report verify parents <reportId> --app-id <id>` | 跨数据源父格体检（入口格唯一 / fieldKey 三段式 / id=currentField / 算子白名单 / 锚点） |
+| `report fix table-name <reportId> [--apply]` | 补 tableName |
+| `report fix freeze <reportId> [--anchor x,y] [--apply]` | 冻结单元格 |
+| `report fix echo <reportId> --app-id` | 同 `query fix-echo` |
+
+## 分析
+
+| 命令 | 用途 |
+|---|---|
+| `report join-suggest --app-id (--parent-source\|--parent-form) (--child-source\|--child-form)` | 推断两表关联字段（须用户确认） |
+| `report py preagg (--fields <f> \| --report-id <id>) [--layout <f>]` | 预聚合可用性判定 |
+| `report py left-filter --parent-ds/--parent-src/--parent-field --child-ds/--child-src/--child-field [--type]` | 算跨数据集父格筛选（输出 `subordination` + `leftFilterField`），定点修复时手工拼配置用 |
+
+---
+
+## 退出码约定
+
+| 码 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1 | 失败（校验不通过 / 接口报错） |
+| 2 | 成功但有警告；或 `--strict` 下有「待用户确认」项；预聚合建议关闭 |
+| 3 | `report build` / `join-suggest`：需要用户指定表，未建表 |
+| 4 | `report build`：需要用户指定字段，未建表或已删未完成报表 |
+
+## 默认只读、要 `--apply` 才写的命令
+
+`fix table-name`、`fix freeze`、`fix query-default`、`fix query-style`、`cleanup`。
+不带 `--apply` 时只预演并打印将要做的改动。

package/skills/weaver-e10-builder/references/report/ref-report-pitfalls.md

@@ -0,0 +1,226 @@
+# 报表踩坑清单
+
+> 动手前扫一遍。每条都是「写进去不报错，但设计器上表现不对」的那一类。
+
+---
+
+## 一、请求层
+
+### 1.1 `ebbusinessid` 只能发一次，且必须全小写
+
+多发一个 `ebBusinessId`（驼峰）时，HTTP 头名大小写不敏感，运行时会把它和小写那个**归并成同一个头**，
+值被拼成 `"<appId>, <appId>"`。
+
+**症状**：`POST /api/bs/edc/report/addDataset` 与 `GET .../deleteReport` 恒返回
+`HTTP 200` + `{"code":500,"msg":"报表内部错误"}`，响应头里 `responsetime` 只有十几毫秒
+（服务端一进来就抛，没走到下游）。而同一时刻 `baseInfo` / `saveReportDevInfo` / `fieldsBySource` 全部正常。
+
+**排查要点**：这类「HTTP 200 + 业务 500」优先怀疑**自己多发了什么**，而不是先怀疑服务。
+二分时从「能通的那一份请求」逐项摘，比从「不通的那一份」逐项加收敛快得多。
+
+### 1.2 建报表撞名时不报错，返回哨兵字符串
+
+`baseInfo` 遇到同名报表**不回错误码**，而是把 `data` 写成字符串 `SAME_NAME`。
+
+后果：不识别这个哨兵，就会拿着 `"SAME_NAME"` 当 reportId 一路往下跑，
+最后错报在 `addDataset` 上，把人往完全错误的方向带。
+
+CLI 已识别并给出明确提示。
+
+### 1.3 `addDataset` 不返回 datasetId
+
+它只回一个空的成功体，必须回查 `dataset/list` 才能拿到新数据集 id。
+查询与 `addDataset` 之间**不要加 sleep** —— 命中即返回，轮询几次就够。
+
+### 1.4 写接口不重试
+
+建表、落库都不是幂等操作。网络层失败后重放会直接多出一张报表或一份重复配置，
+所以 CLI 对报表接口固定 `retries=1`。
+
+---
+
+## 二、字段绑定
+
+### 2.1 禁止系统字段兜底（历史事故）
+
+列标题匹配不上时，**绝不能**回退到 `name` / `id` / `create_time` 等系统字段。
+事故：需求写「姓名」，被静默绑到系统字段 `name`（真实显示名「标题」），报表能用但数据全错。
+
+无精确命中 → 停下让用户指定（见 `field-bind-exact-match-guide.md`）。
+
+### 2.2 `field_` 前缀不能加也不能去
+
+平台业务字段的技术名形如 `field_1315401474786910245`。
+写成裸雪花（去掉 `field_`）或凭空造一个 `field_xxx`，`fields` 记录都对不上。
+`report verify bind` 会给出「应为 field_xxx」或「不要加前缀」的提示。
+
+### 2.3 两个字段接口的信封不一样
+
+| 接口 | `data` 形状 | `dataSetId` |
+|---|---|---|
+| `dataset/fieldsBySource` | **裸数组** | 恒为 `"0"`（还没落库） |
+| `dataset/fieldsAndOriginFields` | `{fieldsKey, originFieldsKey}` | 真实值 |
+
+字段元素本身同形，只有 `dataSetId` 不同。所以 `fieldsBySource` 的结果**必须**用本报表真实
+datasetId 覆盖后再落库，否则单元格会绑到错误的数据集上。
+详见 `dataset-table-field-contract-guide.md`。
+
+### 2.4 `tableName` 缺失 → 数据源不显示模块类型
+
+Field 单元格的 `tableName`（数据集显示名，含 `(业务模块)` / `(表单)` 后缀）与
+`fieldId`/`fieldName`/`fieldText` 三件套缺一不可，否则属性面板回显不全。
+
+补齐：`e10-cli report fix table-name <reportId> --apply`。
+
+---
+
+## 三、数据集
+
+### 3.1 同源只挂一次
+
+同一张表在一个报表里挂两次，左侧会出现**重复数据源分组**。
+`resolveDataset` 会先查已有挂载再决定是否新建；发现存量重复会报 `duplicates` 提示用户清理。
+
+清理前必须先摘掉画布上游离单元格对它的引用，否则删不掉。
+
+### 3.2 报表自带一个系统数据集
+
+每张报表都会带一个 `dataUpdateTime` 数据集（`sourceId` 是另一个雪花）。
+它不在画布上，**不是重复挂载**，别当脏数据清掉。
+
+### 3.3 `delDataset` 的参数名是历史包袱
+
+它收的字段叫 `sourceIds`，但**值是 datasetId**，不是 sourceId。
+
+### 3.4 数据集不能跨报表复用
+
+拿 A 报表的 `datasetId` 去 B 报表用会被忽略（CLI 会警告并重新解析）。
+
+---
+
+## 四、布局与空白
+
+### 4.1 `gridline` 键一出现就 500
+
+workbook 的 sheet 上**禁止**出现 `gridline` / `gridLine` / `__gridline` 任何一个。
+存在即 `saveReportDevInfo` 返回「报表内部错误」。
+
+网格线只写在 `sheetProps` / 分页设置的 `gridLine`（`0|1`）上。
+校验：`e10-cli report validate gridline --file wb.json`。
+
+### 4.2 `showLocation` 不能是 0
+
+只允许 `1`（居左）/ `2`（居中）。写 `0` 会被前端当成缺失，表现为设计区空白/布局异常。
+
+### 4.3 `(0,0)` 的空 Const 是幽灵格
+
+`Const` 的父格缺省时，服务端 Java `int` 会当 0，变成「伪自定义 A1」父格关系。
+父格必须显式落到 `-1`。
+
+### 4.4 合并只认 `spans`
+
+`rows[].size = 0` **不会隐藏行**，合并单元格也只认 `spans` 数组。
+详见 `hidden-row-and-header-merge-guide.md`。
+
+### 4.5 链接格的父格规则
+
+超链接格的上父格必须留 `-1,-1`（写了会把超链接文案冲掉）；
+链接里含 `{坐标}` 占位符时，左父格必须指向依赖的数据格，且不能是 `(0,0)`。
+
+---
+
+## 五、查询条件
+
+### 5.1 `queryType` 必须是数组短码
+
+`'["advance"]'` / `'["filter"]'`。写成 `"advancedSearch"` 这种长码，服务端也收，
+但设计器「显示方式」**不会勾选**。修复：`report query fix-echo`。
+
+### 5.2 `updateQueryType` 是报表级批量覆盖
+
+它会把入参的 `queryType` 写到**所有**条件上。所以只在用户明确点名要改显示方式时才调用，
+绝不能顺手带一脚 —— 否则会把混合的筛选/高级搜索一键抹平。
+
+### 5.3 绝不能静默注入 `advancedSearchType`
+
+写 `'openCondition'` 等于把报表页查询区从「默认样式」改成「展开条件」，属于擅改用户的展示样式。
+入参没有这个键就不写。存量清理：`report fix query-style --apply`。
+
+### 5.4 默认值三件套必写
+
+`defaultValueType` / `defaultValue`（+ `type1DefaultValue` / `type2DefaultValue`）。
+漏写 → 设计器弹窗「默认值类型」= 请选择、默认值区把**所有**控件变体炸开，
+其后的「日期类型 / 显示位置 / 条件必填」被顶出可视区，看着像被改坏了。
+
+补齐：`report fix query-default --apply`。
+
+### 5.5 不带 `id` 保存会变成「新增」
+
+`saveQueryItem` 必须带 `id` 才是原地更新；不带就新增出重复条件。
+`report query verify` 的 Q6 会拦这一条。
+
+### 5.6 `queryItems` 只收单条对象
+
+传数组会 500。且 `conditions[]` 不能为空，否则服务端 NPE。
+
+### 5.7 条件格式的「介于」是 `interval`
+
+引擎只认 `highlight:interval`，写 `between` 不会报错但**规则静默不生成**。
+且多条规则是**或**不是**且** —— 「大于 5 且小于 10」要写成一条 `interval`，
+写成 `greater` + `less` 两条会命中并集。
+
+---
+
+## 六、并发与权限
+
+### 6.1 `designKey` 是乐观锁
+
+已有报表保存前必须**回读最新的** `designKey`。用旧值会「数据不是最新」或偶发 500。
+新建的空壳传空串即可。
+
+### 6.2 权限接口是全量替换
+
+`savePermissions` 的 `viewRight` 传空数组 = 谁都不给看。
+只改共享范围时，必须先把 `disableRight` / `viewMatrixRight` 读回来原样带回，
+否则会把「不可见」矩阵一起清掉。
+
+### 6.3 复制出来的报表默认没人能看
+
+`copySheet` 复制后权限是空的，必须单独授权，否则用户点菜单会看到无权限。
+`report lifecycle copy-and-menu` 已把「复制 + 授权所有人 + 挂菜单」串起来了。
+
+---
+
+## 六补充、环境相关
+
+### 6.4 `saveAsVersion` 在部分环境不可用
+
+**现象**：保存版本返回 `HTTP 200` + `{"code":500,"msg":"报表内部错误"}`，
+而同一张报表的 `getVersionWithPage`（读版本列表）完全正常，只是列表恒为空。
+
+**已确认是环境问题，不是用法问题**：
+
+- 同一个请求在**另一个环境**返回 `{"code":200,...,"data":{"id":...}}`，功能正常；
+- 在报错的环境里，**用浏览器设计器自带的「保存版本」按钮操作，同样报「报表内部错误」**。
+
+**排查时已经排除的**（不用重走）：权限（`appRight` 的 EDIT 为 true）、
+请求格式（multipart 与 urlencoded 都试）、字段名（换 `id` 会返回 400，说明确实是 `sheetId`）、
+`designKey`（带最新值照样 500）、版本名格式（带不带 `{date}-{time}` 占位符都一样）、
+请求头（逐字节复刻浏览器请求仍 500）。
+
+**请求格式备忘**：`saveAsVersion` 走 **multipart**（不是 urlencoded），两个字段
+`sheetId`（报表 id）+ `versionName`；`versionName` 通常形如 `{报表名}-{date}-{time}`。
+
+**处置**：如实告诉用户该环境的版本功能不可用；需要留档时可改用快照
+（`e10-cli report snapshot set`）。**不要**为此在客户端反复试错。
+`report version list` 仍可正常读取。
+
+---
+
+## 七、雪花 ID
+
+19 位 id 一旦被 `Number()` 过就会截断，写回去指向不存在的记录，
+表现为**设计区空白**，而且极难反推。
+
+凡是 `reportId` / `sheetId` / `datasetId` / `snapshot.id` / `snapshot.jobId`，
+一律保持字符串。详见 `snowflake-id-precision-guide.md`。

package/skills/weaver-e10-builder/references/report/report-baseinfo-defaults-guide.md

@@ -0,0 +1,117 @@
+# 报表基础字段默认值与命名规范（强制）
+
+> **权威来源**：`EdcReportDevBaseController.saveReportBaseInfo`（`@RequestParam defaultValue`） 
+> + `EdcReportDevBaseServiceImpl.buildNewReportDto` / `buildEmptySheetProp` / `resetReportListI18nName` 
+> **原则**：**对齐平台内置默认值**；禁止凭感觉改空、改哨兵值、或往 `name`/`nameLabelId` 塞特殊字符。
+
+---
+
+## 一、baseInfo 内置默认值（设计器新建 API）
+
+`POST /api/bs/edc/report/baseInfo`（`weaver-edcreportd` · `EdcReportDevBaseController`）：
+
+| 参数 | 源码 `defaultValue` / 行为 | Agent / CLI **必须** |
+|------|---------------------------|----------------------|
+| `groupId` | **`"0"`** | 未指定分组时传 **`0`**。会出现在页面「全部」（`list?groupid=-1` 哨兵=查全部） |
+| `showOrder` | **`"1"`** | 未指定时传 **`1`**；勿传空 |
+| `name` | **必填**（无 default） | 非空；见 §二 |
+| `nameLabelId` | 可选（无 default） | **无多语言时显式传 `"-1"`**（与线上正常报表一致）；勿传空串、勿省略后写成脏值 |
+| `id` | `"0"` = 新建 | 新建用 `0`；更新用真实 reportId |
+| `appId` | `"0"`（须改为真实应用） | **必须**真实 appId |
+| `reportModel` | `"0"` | 无模板时保持 `0`；**模版创建**时传模板报表 ID（见 `report-create-modes-guide.md`） |
+| `quicklyParam` | 无（省略） | **快速构建-列表式**时传 QuicklyParam **JSON 字符串**；与 `reportModel>0` 互斥（模板优先） |
+| `systemType`（新建分支） | 服务端置 **`1`** | 普通 EB 报表勿擅自改成空/其它 |
+
+`buildNewReportDto` 其它落库默认：
+
+| 字段 | 默认 |
+|------|------|
+| `version` | `"1"` |
+| `enable` | `1` |
+| `configurable` | `0` |
+| `frontView` | `0` |
+| `enableInsight` | `0` |
+| `deleteType` | `0` |
+
+空 Sheet（`buildEmptySheetProp`）：`gridLine=0`、`rowHeaderVisible=0`、`colHeaderVisible=0`（与「页面布局默认关闭」一致）。
+
+### 1.1 哨兵值 ≠ 入库默认值（强制）
+
+| 值 | 用途 | Agent 行为 |
+|----|------|------------|
+| **`groupid=-1`（list 查询参数）** | 「查全部报表」哨兵 | 仅查询用 |
+| **`baseInfo.groupId=-1`** | 部分租户/应用下**默认分组展示值**（ 常见） | **原样保留**，禁止擅自改成其它 ID |
+| **`groupId=0`（Controller 新建 defaultValue）** | 新建 API 未指定分组时的入参默认 | 新建可显式传 `0`；**不要**事后乱改已有报表分组 |
+
+> **强制**：已有报表的 `groupId` **只认 `baseInfo` 回读**。保存 `saveReportDevInfo` 时把 `baseInfo.groupId` **原样写入 multipart**，禁止脚本硬编码 `0`/`-1`/臆造 ID。 
+> 改分组只能用户明确要求后走 `removeReport` 等换组接口。
+
+### 1.2 禁止随便改空 / 乱设分组
+
+| 禁止 | 说明 |
+|------|------|
+| 把 `groupId` / `showOrder` / `nameLabelId` 改成 `""` / `null` 指望「用默认」 | multipart 空串可能覆盖或落脏；应**显式传**上表默认值或 baseInfo 原值 |
+| **擅自改已有报表 `groupId`** | 以参考报表/`baseInfo` 为准；「默认分组」可能是 `0` 或展示为 `-1`，勿凭记忆改写 |
+| 更新 baseInfo 时清空已有合法默认字段 | `updateReportBase` 本就不改 `group_id`；改分组用 `removeReport` |
+| 为「好看」改 `frontView`/`configurable`/`gridLine` 等 | 未需求点名则保持平台默认 |
+
+---
+
+## 二、name / nameLabelId 规范（强制）
+
+### 2.1 `name`（报表名称）
+
+| 规则 | 说明 |
+|------|------|
+| 非空 | 去掉首尾空白后长度 ≥ 1 |
+| **禁止**控制字符 | 不得含 `\r` `\n` `\t` 及其它 ISO 控制符（`\u0000-\u001F`、`\u007F`） |
+| 禁止首尾异常空白 | 写入前 `trim()`；勿保留仅空白名 |
+| 同名校验 | 服从平台 `checkReportName`（如 SAME_NAME） |
+
+### 2.2 `nameLabelId`（多语言标识）
+
+源码 `resetReportListI18nName`：
+
+```java
+if (StringUtils.isNotBlank(nameLabelId) && !"-1".equals(nameLabelId)) {
+ Long.parseLong(nameLabelId); // 脏字符 → NumberFormatException →「报表内部错误」
+}
+```
+
+| 规则 | 说明 |
+|------|------|
+| 无多语言 | **必须** `"-1"`（字符串） |
+| 有多语言 | **纯数字**雪花 ID 字符串，无空白、无 `\r\n` |
+| **禁止** | `"-1\r\n"`、空串、`"null"`、带空格数字、任意非数字（除精确 `"-1"`） |
+
+### 2.3 事故对照
+
+`BBB` + `nameLabelId="-1\r\n"` → 应用报表页 `list?groupid=-1` 整页 500「报表内部错误」。
+
+---
+
+## 三、CLI（优先）
+
+```bash
+# 落库前本地校验（不访问网络）
+e10-cli report validate base --name "资产信息统计" --name-label-id -1 --group-id 0
+
+# 线上报表元数据巡检
+e10-cli report verify meta <reportId> [appId]
+```
+
+校验失败 exit ≠ 0；Agent **禁止**跳过继续 save。
+
+内部错误根因与修复全流程：`report-internal-error-guide.md`。
+
+
+---
+
+## 四、与其它文档
+
+| 文档 | 关系 |
+|------|------|
+| `api-report-build-fast-path.md` §2.1 | 建壳命名 + groupId/name 纪律 |
+| `e10-cli report -cli.md` | CLI 映射 |
+| `failure-cleanup-and-nonblocking-guide.md` | 失败空壳清理 |
+| `report-self-check-guide.md` | 布局/父格自检（本篇只管 base 元数据） |