@linkaicli/linkai-cli 0.0.0-stage → 1.0.17

package/knowledge/report-builder/references/query-engine.md

@@ -0,0 +1,177 @@
+# 查询引擎：卡片的数是怎么查出来的
+
+读这篇的时机：要判断「这个配置会不会生效」「为什么数不对/重复/被合并/报 GROUP BY 错」，
+或者想在卡片层做聚合、排序、过滤之前。标 **【实测】** 的经过线上验证，
+标 **【确认】** 的规则已确认、但没在线上跑过——用之前先拿一张 `zz-` 卡片验证。
+
+## 1. 请求长什么样
+
+`POST /page-setting/get-new-index-block-data`（编辑器预览用 `/index-block/get-new-index-block-data`）：
+
+```jsonc
+{
+  "usedIndexBlockId": "<卡片 id = indexBlock.id>",
+  "filters": [ /* 见 references/filters.md「查询时的过滤值」 */ ],
+  "page": {"pageIndex": 1, "pageSize": 20},   // 不分页时整个字段不传
+  "sortFields": [ /* 列头临时排序；不传则走卡片持久排序，见 §4 */ ],
+  "isFreeFill": false,
+  "dataSourceSql": "...", "dataSourceId": "...",
+  // agtable：开总计/行转列时附加 isTotal / pivotTableGroup / isPivotTable / pivotPageField
+}
+```
+
+响应：`data` 是行数组（列名 = `waxisN`/`yaxisN`/…），`dataCount` 是总行数（分页时取首行的 `totalcount` 列），
+`extendData.sql` 是**实际执行的完整 SQL**，`message` 在失败时是数据库原始报错。
+**HTTP 200 + `code≠200` + `data=[]` 是查询失败的典型形态**，一定看 `message`。
+
+不开浏览器直接查一张卡片：
+
+```bash
+linkai query --card <卡片id> [--page-size 条数] [--output rows.json]     # → code / message / total / rows / columns / sql（行内容只写文件，不打印）
+# 带筛选条件或自定义 body：
+linkai api --method POST --path /page-setting/get-new-index-block-data --body body.json --raw
+```
+
+## 2. SQL 的三层结构
+
+```sql
+/*租户=…,用户=…,卡片=…*/
+SET @tenant_code = '<租户码>';             -- 仅数仓数据源（IsWarehouse && IsMultenant）且非 0000 租户
+SELECT W.<列别名> AS waxis1, SUM(W.<列别名>) AS yaxis1, …
+FROM (
+    SELECT <排序/隐藏辅助列>, WT.*            -- 第二层：把数据集整体包成 WT，在这层做「维度过滤」
+    FROM ( <数据集 SQL，已做行权限改写> ) AS WT
+    WHERE WT.<列别名> IN (…)                -- filterProperty=0 的过滤
+) AS W
+WHERE / HAVING …                             -- filterProperty=1 的结果集过滤（按 waxisN 找回列）
+GROUP BY …                                   -- 见 §3
+ORDER BY …                                   -- 见 §4
+LIMIT <pageSize> OFFSET …                    -- 有 page 时；无 page 且 limitCount>0 时 LIMIT limitCount
+```
+
+- 数据集 SQL 里可以写 `$username` / `$phone`，执行前替换成**当前登录用户**的用户名/手机号（带引号的字符串字面量）【确认】。
+  做「只看自己负责的数据」时比建行权限省事。
+- 数据集 SQL 自带的末尾 `ORDER BY` 在外层包了两层后**不保证保留**（优化器可以丢）【实测】。
+- 数据集 SQL **结尾不能带分号**：它被包成子查询，`;` 会报 `Unexpected input ';'`【实测】。`ds-create/update` 已自动去掉结尾分号，
+  中间出现分号（多语句）直接拒绝。
+
+## 2.1 参数变量 `$1~$9`、`$A~$Z` 与条件块 `$N{{ … }}`【实测 2026-10-13】
+
+数据集 SQL 可以直接写参数（领谋提供的 `rpt_gop_*` 模板就是这么写的），执行前由后端文本替换：
+
+| 写法 | 有值时 | 没值时（看板/卡片没配这个参数的筛选器，或值为空） |
+|---|---|---|
+| 裸参数 `$2` | 替换成 `'值'`（带单引号的字符串字面量） | 替换成 **`'0'`**（不是空串、不是 NULL） |
+| 条件块 `$N{{ AND w.x = $4 }}` | 去掉 `$N{{` `}}`，参数替换后保留 | **整块删除** |
+| 区间筛选（`filterOperationType:37`）绑两个变量 | 依次替换成起、止两个值 | 同上 |
+
+- ★条件块必须写在**一行**里，跨行不会展开，`$N` 原样送到数据库报错。`ds-create/update` 不会重排已是多行的 SQL。
+- ★没配的裸参数是 `'0'`：模板里要能识别 `'0'`（如 `$D IN ('全部','','0')`），否则静默错——实测 `rpt_gop_dim_scatter`
+  不配 `$G/$H/$I` 时 X/Y/气泡值全为 NULL，必须在看板上配带默认值的筛选器。
+- 变量是全局的（不分租户）：`linkai api-get --path /page-setting/variable-list` → `[{variableKey:'$2', id}]`，筛选器用 `variableIds` 引用 id。
+- 看板参数筛选器：`filterProperty:2`、`variableIds:'["<$2的id>","<$3的id>"]'`（区间两个、单值一个），`bindUserPageCards`
+  列出要传参的卡片（`dataSettingComment` 留空），下拉候选值用 `indexBlockDataId`+`fieldName` 指向一个字典数据集的列。
+  完整示例见 `references/filters.md` §4.1。
+- `query` 带参数：`linkai query --card <cardId> --page-size 50 --output rows.json --filters filters.json`，filters.json 每项
+  `{"filterProperty":2,"filterType":2,"filterOperationType":37,"variableIds":"[...]","value":"[\"2026-09-01\",\"2026-09-30\"]"}`。
+- 非超管且 `UserType==10`（SCM4.0 用户）还会按 `Config(Key=AuthorityTable)` 给数据集 SQL 注入数据权限 WHERE【确认】。
+
+## 3. 会不会 GROUP BY（最容易踩）
+
+`IsGroup` 的判定（`GetNewIndexBlockDataSql` 开头）：
+
+1. 任何显示字段 `calculationMode > 0`，或 `calculationMode == 0 && isAggregation == true` → **分组**
+2. 否则，若**没有任何** `argumentType=1`（数值）字段、但有 `argumentType=2`（维度）字段 → **也分组**
+3. 其余情况 → 不分组，逐行明细
+
+分组时 `GROUP BY` 的是全部维度（`argumentType` 2/3）字段，以及所有**不聚合**的排序字段。
+
+后果：
+
+| 卡片形态 | 结果 |
+|---|---|
+| AG 明细表，**所有列都配成 `waxis`**（`linkai card-table` 就是这样） | 规则 2 命中 → `GROUP BY` 全部列：**完全相同的行会被合并成一行**，大表还慢。数据集里留一个唯一键列（ID）并注册成隐藏列就不会误合并 |
+| 图表：维度 `waxis` + 数值 `yaxis`（`calculationMode:0`，`isAggregation:false`） | 不分组，原样出行 → 数据集 SQL 自己要先聚合好 |
+| 图表：数值 `yaxis` `calculationMode:2`（界面把数值字段拖进「数值」区的默认值） | 分组 + `SUM()` |
+
+`calculationMode`：`0` 无处理 · `1` 计数 · `2` 求和 · `3` 平均 · `4` 去重计数 · `5` 最小 · `6` 最大 · `99` 参与分组（`Enums.CalculationMode`）。
+界面拖字段时的默认值：数值类型（int/decimal）拖进数值区 = `2` 求和；文本拖进数值区 = `1` 计数；
+字段表达式本身含聚合函数时 = `0` + `isAggregation:true`。
+
+**建议**：图表卡片让数据集 SQL 预聚合、卡片 `calculationMode:0`（`linkai card-chart` 的做法），
+口径全在 SQL 里一眼可查；需要随筛选器动态聚合（例如按店铺筛完再求和）时才用 `calculationMode:2`。
+
+## 4. 排序：三条通道，按优先级
+
+后端只认一条 ORDER BY 来源，**先到先得**：
+
+| 优先级 | 来源 | 怎么配 | 状态 |
+|---|---|---|---|
+| ① | 请求体 `sortFields` | 用户点列头的临时排序，前端放在 `fieldTempSort` 里；**刷新即丢** | 【确认】 |
+| ② | **卡片持久排序** `UsedIndexBlockSortField` | `PUT /page-setting/page-card-index-block-sort-field`（= 卡片右上角「排序」弹窗）；`linkai card-sort` | **【实测 2026-10-13】首选** |
+| ③ | 卡片字段表里 `argumentType=0` 的排序字段（`order<N>`） | `indexBlockDataSettingDtos` | 【确认】，有坑，见下 |
+| ④ | 数据集 SQL 自套 `ORDER BY … LIMIT 100000` | 改 SQL | 【实测】可用 |
+
+② 的 body：
+
+```jsonc
+{"usedIndexBlockId": "<卡片 id>",
+ "sortField": [
+   {"field": "waxis3", "type": 1, "sort": "desc", "sortNum": 0, "sortFields": []},      // type 1 = 按值升降序
+   {"field": "waxis5", "type": 2, "sort": "asc",  "sortNum": 1,                        // type 2 = 手动指定值的顺序
+    "sortFields": [{"value": "紧急", "sortNum": 0}, {"value": "一般", "sortNum": 1},
+                   {"value": "other", "sortNum": 9}]}                                   // "other" = 其余值
+ ]}
+```
+
+- `field` 填**卡片字段名** `waxisN/yaxisN`（不是数据集列名）；后端生成 `ORDER BY waxis3 DESC`，
+  手动排序生成 `ORDER BY CASE WHEN waxis5='紧急' THEN 0 … ELSE 9 END`。
+- 每次保存是**整组替换**；传 `sortField: []` 即清空。
+- 持久排序挂在**卡片**上（`usedIndexBlockId` = `indexBlock.id`），看板里和报表里同一张卡片共用。
+- 排序在 `LIMIT/OFFSET` 之前，分页翻页顺序稳定（只排一个有重复值的列时，同值行顺序仍不稳定——再加一个唯一键做第二排序）。
+- 卡片详情 / 方案详情 / 报表详情里 `indexBlock.sortField` 就是读回来的持久排序。
+
+③ 的坑：只有当**全部** `argumentType=0` 字段的 `orderByType` 都 ≠ 0 时才生效（有一个是 0 就整组不排）；
+排序字段不在显示列里时会被追加进内层 SELECT，和 `WT.*` 里的同名列撞成 **ambiguous**；
+数值排序字段默认 `calculationMode:2` 会生成 `ORDER BY Sum(x)`，在不分组的明细里报
+`must be an aggregate expression or appear in GROUP BY`。这就是旧版文档「卡片排序全部无效」的真实原因。**别用 ③，用 ②。**
+要按不显示的列排（如图表 x 轴是文本），把它加成卡片的额外维度再用 ②，见 pitfalls 57。
+
+> ✅ ② 已线上实测（2026-10-13，测试租户租户，日趋势卡 `card-sort --spec 日期:asc`）：后端在外层生成
+> `ORDER BY waxis1 ASC nulls last LIMIT 50`，返回数据按日期升序，分页前生效。`card-sort` 保存后会自动跑一次查询，
+> 返回 `sqlHasOrderBy`（只认外层按 waxisN/yaxisN 的 ORDER BY，数据集 SQL 注释里的字样不算）。
+
+## 5. 条数：`limitCount` 与分页
+
+- 请求带 `page` → `LIMIT pageSize OFFSET …`，**`limitCount` 不起作用**；总数在首行 `totalcount` 列。
+- 请求不带 `page` 且 `limitCount > 0` → `LIMIT limitCount`。
+- 前端保存时：`agtable` / `gantt` / `multiFlowStep` 开了分页（`config.showPagination:true`）就**不提交 `limitCount`**
+  （`normalizeLimitCountForSubmit`）。其余图表的 `limitCount` 就是 Top N。
+- 甘特/流程图开分页时按「主任务字段」分页（`isPivotTable:true` + `pivotPageField`），一页 = N 个主任务的全部子行。
+
+## 6. 总计
+
+agtable `config.total.show:true`：
+- `rowtotalType:'all'` → 请求带 `isTotal:true` + `pivotTableGroup:[所有列主字段]`，后端用窗口函数算**全量**总计；
+  只对 `argumentType=1` 且 `calculationMode≠0` 的数值列有值（`SUM/COUNT/AVG/MIN/MAX(...) OVER()`）。
+- `rowtotalType:'page'` → 前端只对当前页求和，不发总计请求。
+- `labelColumn` 写哪一列显示「总计」字样（填 `wd.columns[].id`），`labelText` 改文案。
+
+## 7. 租户隔离与权限（只要知道这些）
+
+- `SET @tenant_code` 只在**数仓多租户数据源**上拼，且 `0000` 租户（平台）不拼。视图靠它过滤；底表不受它影响（见 `references/dataset.md`）。
+- 数据源不是 StarRocks 且不属于当前租户时，后端会改用当前租户名为 `Cloud` 的数据源【确认】——跨租户复制来的卡片可能静默换源。
+- 「数据源行权限」（2026-09 起）会在执行前按
+  「数据源 + 表名」改写数据集 SQL，给受控表加 `IN (…)` 条件。超管、`0000` 租户不受控。
+  **搭报表时不用管它**；但「同一张报表不同人看到的行数不同」时，先怀疑它。
+
+## 8. 排查清单
+
+| 症状 | 先查 |
+|---|---|
+| 空白/转圈，接口 200 | 响应 `message`（数据库报错）+ `extendData.sql`；`linkai query --card <卡片id>` |
+| 行数比预期少、重复行不见了 | §3 规则 2：全 waxis 明细被 GROUP BY 了 |
+| `must be an aggregate expression…` | 有 `isAggregation`/`calculationMode` 不一致的字段，或用了 ③ 排序 |
+| `Column '…' is ambiguous` | 排序/隐藏字段与 `WT.*` 撞名（③ 排序的典型症状） |
+| 筛选器能选但不过滤 | `references/filters.md`「不过滤的五个原因」 |
+| 不同用户看到的数不同 | 行权限模块 / `$username` / 个人筛选副本（`references/filters.md`） |

package/knowledge/report-builder/references/report.md

@@ -0,0 +1,249 @@
+# 报表与看板
+
+## 发布成数据报表
+
+一行命令：
+
+```bash
+linkai report-publish --card <卡片id> --name "<报表名>"
+```
+
+**一张卡片只能对应一个报表**，重复建会被服务端挡回来（「该报表已经存在了,请勿重复添加!」）。
+建完地址是 `/view/table?indexBlockId=<卡片id>&status=view`。
+
+报表 vs 分析方案（看板）：
+
+| | 分析方案 | 数据报表 |
+|---|---|---|
+| 地址 | `/view/plan?plan=<planId>` | `/view/table?indexBlockId=<卡片id>` |
+| 形态 | 网格布局，多卡片，每张有外框和标题栏 | **全屏单卡片**，没有外框，表格区高约 90px |
+| 详情接口 | `POST /page-setting/get-new-page-plan/<planId>?isEdit=true\|false` | `POST /page-setting/get-new-page-card-report` `{"indexBlockId":"...","isSubWarn":false}` |
+| 布局保存 | `POST /page-setting/update-page-card` | 无（本来就是全屏单卡片） |
+| 筛选器 | 同一个 `batch-add-or-update-filter`，`filterSourceType:4` + `userPageSettingId` | 同上，`filterSourceType:2` + `userPageCardId` |
+| 筛选器绑字段 | `bindUserPageCards[]`（见下，字段名是 `pageCardId`） | `propertyName`（直接写 `waxisN`） |
+| 列表接口 | `POST /page-setting/get-page-setting-folder-bussiness-info`<br>`{"isOnlySeeSelf":false,"page":{...}}` | `POST /index-block/get-index-block-report-folder-bussiness-info` `{}`<br>（响应直接带 `indexBlockId`，反查卡片很好用） |
+
+一张表格为主的东西，**报表形态比看板好**：没有卡片外框，同样窗口下能多看小半行。
+
+### 报表筛选器（纯接口）
+
+⚠ **2026-10 后端改成了分层模型**（`references/filters.md` §1）：报表筛选器的系统模板是**卡片自己的 `filters`**，
+每个用户第一次打开报表时从它复制一份个人副本。所以给所有人配筛选器要这样做：
+
+```bash
+linkai backup --type card --id <卡片id>                          # 写前基线
+linkai card-get --card <卡片id> --output card.json
+# 改 card.json 的 filters（单条格式见 references/card.md「卡片自带的筛选器」，propertyName 填 waxisN）
+linkai card-save --file card.json                            # 保存并回读
+linkai report-card --card <卡片id>                           # → userPageCardId
+linkai reset-filter --page-card <userPageCardId>             # 让自己看到新模板
+```
+
+【确认】这条路径还没线上实测过，第一次照做时用第二个账号打开报表核对一次，确认后去掉本标注。
+
+旧做法（`linkai api --method POST --path /page-setting/batch-add-or-update-filter --body body.json`，`filterSourceType:2` +
+`isTenantSystem:false`）仍然能用，但**只改你自己的个人副本**，适合调试、看效果；body 是全量覆盖
+（不在数组里的筛选器会被删，新增的不带 `filterId`）：
+
+```json
+{"isTenantSystem": false, "filterSourceType": 2, "userPageCardId": "<report-card 拿到的 id>",
+ "filters": [{"labelName":"店铺", "propertyName":"waxis10", "fieldName":"店铺", "filterProperty":1,
+              "filterSourceType":2, "userPageCardId":"<同上>", "sortNum":0,
+              "defaultValue":"\"某个值\"", "filterId":"<已有的传，新增的不传>", ...}]}
+```
+
+界面路径（想看看某项长什么样时用）：报表页右上角**漏斗图标** → 「筛选条件」。
+⚠ 界面的「关联卡片」下拉列不全字段，筛选器绑定只能走接口。
+
+### 报表的排序
+
+报表就是卡片，持久排序挂在卡片上：`linkai card-sort --card <卡片id> --spec sort.json`，看板里同一张卡片也一起生效。
+格式见 `references/query-engine.md` §4。
+
+### 图表导出的取数上限【确认】
+
+现在图表导出取数会显式传 `pageIndex:1,pageSize:1000000`，超时仍是 2 分钟；
+是否带页面当前筛选仍由导出配置的 `filter` 开关决定。这是「最多请求 100 万行」，不是无限量导出；
+大表仍要用有代表性的超大数据验证服务端限制、内存和超时。
+
+## 建分析方案（看板）
+
+```bash
+PLAN=$(linkai plan-create --name "示例客户生命周期")          # → planId
+linkai plan-add --plan $PLAN --card <速览卡片id> --x 0 --y 0 --w 24 --h 21     # x y 宽 高（格）
+linkai plan-add --plan $PLAN --card <明细卡片id> --x 0 --y 21 --w 24 --h 30
+linkai plan-filter --plan $PLAN --file filters.json              # 存筛选器 + 自动 reset-user-filter
+```
+
+⚠ `filters.json` 顶层要写 `"isTenantSystem": true`（存成租户系统模板，所有人可见；界面编辑模式就是这么存的）。
+写 `false` 只改你自己的个人副本。见 `references/filters.md` §1。
+
+`plan-add` 底层是 `POST /page-setting/new-page-card`，**可以直接传目标布局**，
+不用先加再 `update-page-card` 调位置。返回的 `pageCardId` 就是配筛选器时
+`bindUserPageCards[].pageCardId` 要用的那个。
+
+要事后调布局才用 `update-page-card`，它的 body 里 `dataScreenSetting` / `name` /
+`parentId` / `isPrivate` 必须**从 `plan-get` 的结果原样带回去**，漏了会把方案配置冲掉。
+而且 **`list` 里没有的卡片会被移出看板**（这也是从看板里删卡片的办法）。
+单删一张也可以：`DELETE /page-setting/page-card/{pageCardId}`（`linkai api --method DELETE --path /page-setting/page-card/<id>`，
+卡片本身仍在卡片库）。
+
+### `new-page-card` 的其它能力（`PageCardV2Req`）
+
+| 字段 | 用途 |
+|---|---|
+| `cardType` | `1` 指标卡片（默认）· `2` 富文本卡片（`contentText` 放 HTML）· **`5` 分区标题卡**【实测】：`contentText` 为 `{"type":"title-template","version":1,"template":"section","config":{"serial":"01","title":"商品经营总览","subtitle":"","showDecorLine":true,"description":"",…}}`，高 2 格，经 `api POST /page-setting/new-page-card` 加（不带 `indexBlockId`） |
+| `x y width height` / `mobileX…mobileHeight` | PC / 手机布局（格）；`isShowInMobilePlan` 控制手机端是否显示 |
+| `zIndex` | 叠放层级 |
+| `refershSetting` | 卡片刷新配置（字符串；语义同下方看板刷新，未实测） |
+| `bindFilterIds` | 加卡片时直接绑已有筛选器 |
+
+
+### 分区标题卡：单行副标题与布局压缩【实测】
+
+`cardType:5` 的 `contentText` 是 JSON 字符串，`template:"section"` 的渲染层级是：
+
+| 字段 | 位置 / 用途 |
+|---|---|
+| `config.serial` | 标题左侧编号 |
+| `config.title` | 主标题 |
+| `config.subtitle` | **主标题后方、同一行**的副标题 |
+| `config.description` | 标题行下方另起一行的说明 |
+| `serialStyle` / `titleStyle` / `subtitleStyle` / `descriptionStyle` | 各自文字样式；可用字段见 `TitleControl/utils.js` |
+| `showDecorLine` | 标题后的横向装饰线 |
+
+按 demo 做「编号 + 主标题 + 副标题」单行标题时：
+
+```json
+{
+  "type": "title-template",
+  "version": 1,
+  "template": "section",
+  "config": {
+    "serial": "03",
+    "title": "指标趋势",
+    "subtitle": "顶部「趋势指标」「趋势拆分」切换；汇总只按全渠道算",
+    "description": "",
+    "showDecorLine": false
+  }
+}
+```
+
+- PC 与手机的单行标题高度都用 **2 格**；卡位 `dataScreenSetting` 用
+  `{"useCardConfig":true,"backgroundColor":"transparent","cardTitle":{"show":false}}` 去掉外层卡片标题和底色。
+- 把原下方说明改成同行副标题时，将 `description` 复制到 `subtitle`，`descriptionStyle` 复制到
+  `subtitleStyle`，再清空 `description`。
+- `subtitle` 的 class 写死了斜体，`subtitleStyle` 无法取消；若用户要求正体或文案太长，保留
+  `description` 为下方说明行，并按实际行高给 3–4 格。
+
+修改存量标题卡要分两步：
+
+1. `POST /page-setting/replace-page-card`：传 `oldPageCardId` + 新 `contentText` + 原坐标，只修文字。
+   实测即使 body 传新 `height`，返回的仍是原高度；返回 id 可能保持原值，也不应假设一定不变，以响应和重新 `plan-get` 为准。
+2. `POST /page-setting/update-page-card`：用重新 `plan-get` 的**完整卡片列表**改高度和坐标。
+   标题从 4 格压到 2 格时，所有位于它下方的 PC 卡片 `y -= 2`；一次压缩多个标题时按原 `y`
+   累加前面标题的缩减量。手机端原本已是 2 格则不改 `mobileY/mobileHeight`。
+
+写后回读至少检查：卡片总数/id 集合不变（若接口返回替换 id，则按返回值更新预期）、单行标题
+`height == 2`、`description == ""`、下游卡片位移值正确，且矩形无重叠。
+
+看板自动刷新：`POST /page-setting/save-page-setting-refersh-param {"id":"<planId>","isPage":true,"refershSetting":<分钟，整数 0–60，0=关>}`（单位：分钟）。
+
+### 联动 / 钻取 / 跳转（未封装）
+
+| 功能 | 接口 |
+|---|---|
+| 钻取开关 | `POST /page-setting/update-drill-switch` `{"userPageCardIds":["<pageCardId>"],"isOpen":true}` |
+| 联动（点卡片 A 过滤卡片 B） | `get-new-target-page-card-all-list` → `linkages-save` |
+| 跳转（点值跳到卡片/方案/链接） | `get-new-target-query-transfer` → `link-add-or-update` |
+
+开关枚举 `SwitchType`：`0` 关 · `1` 钻取 · `2` 联动 · `4` 跳转。这三项配置复杂、没有实测记录，
+建议在界面上配置；确需接口方式时先用 `zz-` 看板试。
+
+## 看板筛选器怎么绑到卡片
+
+前端逻辑：
+
+```js
+// filterProperty === 1（指标过滤）时
+const bind = filter.bindUserPageCards.find(b => b.pageCardId === 当前卡片.id)
+filter.propertyName = 卡片.dataSettingList.find(d => d.comment === bind.dataSettingComment).field
+```
+
+所以三件事必须对上，错一个就是「筛选器在、能选、就是不过滤」且**不报错**：
+
+1. `pageCardId` —— 是 `plan-add` 返回的那个，**不是** `indexBlockId`，字段名也**不是** `userPageCardId`
+2. `dataSettingComment` —— 必须在目标卡片的 `indexBlockDataSettingDtos` 里有同名 `comment`
+3. `filterProperty: 1`
+
+一个筛选器可以绑多张卡片（一个下拉同时过滤整页）；某张卡片没有这个字段就别绑它。
+卡片里只想用来筛选、不想显示的字段，加成 `hidden: true` 的隐藏列即可。
+
+⚠ 界面上「关联卡片」的字段下拉**列不全**（实测 60 列的卡片只列出 9 个且翻不到想要的），
+所以绑定这件事**只能走接口**。
+
+## 网格布局
+
+`实际px = 24 × 格数 − 8`，看板里首个卡片顶部在 `y = 106px`，宽度 24 格铺满。
+
+
+### 方案左右留白与内容居中【实测】
+
+看板 PC 布局是 24 列。按 demo 做居中内容区时，默认用：
+
+```text
+contentX = 2
+contentWidth = 20
+contentRight = 22
+```
+
+即所有顶层满宽标题卡、数据卡都用 `x:2, width:20`，左右各留 2 格，内容整体居中。
+这是款式画像 demo 的标准值；用户要求「留白再加一点」时，对称减小内容宽度，例如 `x:3, width:18`，
+不要只改一侧。通用计算是：
+
+```text
+contentX = (24 - contentWidth) / 2
+```
+
+`contentWidth` 应选偶数，保证 `contentX` 是整数格。一行有多张卡时，各卡的宽度之和与间隔也必须落在
+`[contentX, contentX + contentWidth]` 内；例如 20 格内的 12/8 拆分是 `x:2,width:12` + `x:14,width:8`。
+
+- 左右留白用卡位 `x/width` 做，不要用卡片内容的 CSS padding 冒充；否则标题、筛选器和卡片外框仍然不对齐。
+- 改存量方案使用 `update-page-card` 完整列表，保留每张卡的高度、`y`、底色、标题开关和手机布局；
+  用户只要 PC 端留白时，不改 `mobileX/mobileWidth`。
+- PC 同行多卡在手机端默认按左到右顺序纵向堆叠；若原卡共用同一个 `mobileY`，必须依次累加前卡高度，
+  并同步顺延所有后续卡片。不要只修重叠的两张卡，留下下游区块覆盖。
+- 写后回读检查：全宽卡片必须 `x == contentX && width == contentWidth`；所有 PC 卡片都满足
+  `x >= contentX && x + width <= contentX + contentWidth`；左右边界对称、卡片数/id 不变；PC 与手机矩形都无重叠。
+
+
+### 暖色页面背景与卡片层次【实测】
+
+按 demo 还原或搭商品运营类看板时，默认页面色是款式画像使用的暖灰米色 `#F4F3EE`；
+用户或 demo 明确给出其它配色时以其为准：
+
+```json
+{"pageBackgroundColor":"#F4F3EE"}
+```
+
+这是方案顶层 `dataScreenSetting`（JSON 字符串），不是单张卡的图表配置。视觉层次按下列原则：
+
+- 页面/左右留白区：`#F4F3EE`，让居中的 20 格内容区与画布区分明确。
+- 分区标题卡：卡位背景用 `transparent`，且 `cardTitle.show:false`，透出页面暖色。
+- 统计指标卡（`meter/list`、`meter/meterList`）与时间轴指标卡（`meter/meterTimeline`）：方案卡位背景默认用
+  `transparent`，透出页面暖色；配置写在 pageCard 的 `dataScreenSetting.backgroundColor`，不改图表内部配置。
+- 主要内容面：保留组件内部白色 `#FFFFFF`（必要时加 `#E3E1DA` 边框），形成「暖色画布 + 白色内容卡」；
+  若图表组件自己已画白底，外层卡位用 `transparent` 或 `#F4F3EE`，避免双重白色外壳。
+- 不要把每张卡的背景都改成暖色；否则白色内容层次消失。也不要只改卡位背景冒充页面背景，卡片间隙和左右留白仍会露出旧色。
+
+改存量方案时，先解析原顶层 `dataScreenSetting`，只合并/更新 `pageBackgroundColor`，不要用单键 JSON 覆盖掉其它页面配置；
+再通过 `update-page-card` 的完整 body 原样带回。写后回读确认：
+
+1. 方案 `dataScreenSetting.pageBackgroundColor == "#F4F3EE"`；
+2. 分区标题、统计指标卡、时间轴指标卡的方案卡位是透明色；
+3. 需要对比层次的其它内容组件仍是白色，卡片数/id、坐标和手机布局没有被误改。
+
+这是 demo / 商品运营类看板的默认基线，不无条件套到其它类型看板；用户或 demo 有其它配色时以它为准。
+
+要让分页栏常驻视口：`106 + (24 × 格数 − 8) ≤ 目标视口高度`。
+按**最小**目标视口算，宁可底部留白也别让分页栏掉出去。

package/llms.txt

@@ -0,0 +1,37 @@
+# LinkAI-CLI
+
+> `linkai`：LinkMoreBI.CLI 的浏览器与站点自动化底层能力，面向 AI 代理。所有命令输出 JSON 信封 {ok,data} / {ok:false,error}。
+
+## 入口
+
+- AGENTS.md：AI 代理调用约定、领谋 BI 自动搭建流程、通用系统提示
+- skills/linkai-report-builder/SKILL.md：领谋 BI 搭建规则（`linkai skills read linkai-report-builder -f plain`）
+- knowledge/README.md：两个知识库的关系（`linkai kb` 列出全部文件）
+
+## 知识库
+
+- knowledge/report-builder/SOP.md：操作顺序、授权边界、回滚
+- knowledge/report-builder/build-spec.md：声明式自动搭建 spec 与 `linkai build`
+- knowledge/report-builder/references/：接口、图表配置、查询引擎、筛选器、踩坑
+- knowledge/data-dictionary/README.md：数据字典（预留）
+- knowledge/browser/README.md：浏览器能力说明（浏览器能力与工作原理）
+
+## 模版
+
+- templates/report-spec/report.example.yaml：自动搭建报表模版
+
+## 常用命令
+
+- `linkai list <关键字>`、`linkai <site> <command> --help -f json`
+- `linkai login`：首次在领谋网页完成 OAuth 授权，之后自动续期
+- `linkai login --tenant <租户名>`：切换租户
+- `linkai status`：当前租户
+- `linkai build --spec <spec.yaml> [--execute] [--confirm]`
+- `linkai deliverable --plan <planId>`：交付清单
+- `linkai kb [--file <path>]`
+
+## 规定
+
+- 不具备操作数据库的能力；数据集只能是只读查询、只能查 ds-tables 清单中的视图
+- 方案完成必须交付：数据集名称、卡片名称、方案名称、筛选条件数据集、数据集脚本、方案地址
+- 浏览器能力类问题以 knowledge/browser/README.md 为准回答

package/package.json

@@ -1,6 +1,107 @@
 {
   "name": "@linkaicli/linkai-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.17",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "LinkAI-CLI — LinkMoreBI 的浏览器与站点自动化能力，面向 AI 代理调用（领谋 BI 自动搭建报表）。",
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "type": "module",
+  "main": "dist/bundle/main.mjs",
+  "bin": {
+    "linkai": "dist/bundle/main.mjs"
+  },
+  "exports": {
+    ".": "./dist/bundle/main.mjs",
+    "./registry": "./dist/bundle/registry.mjs",
+    "./errors": "./dist/bundle/errors.mjs",
+    "./types": "./dist/bundle/types.mjs",
+    "./utils": "./dist/bundle/utils.mjs",
+    "./logger": "./dist/bundle/logger.mjs",
+    "./browser/cdp": "./dist/bundle/browser-cdp.mjs",
+    "./browser/page": "./dist/bundle/browser-page.mjs",
+    "./browser/utils": "./dist/bundle/browser-utils.mjs",
+    "./download": "./dist/bundle/download.mjs",
+    "./download/article-download": "./dist/bundle/download-article.mjs",
+    "./download/media-download": "./dist/bundle/download-media.mjs",
+    "./download/progress": "./dist/bundle/download-progress.mjs",
+    "./pipeline": "./dist/bundle/pipeline.mjs",
+    "./skills": "./dist/bundle/skills.mjs",
+    "./oplog": "./dist/bundle/oplog.mjs"
+  },
+  "files": [
+    "dist/bundle/",
+    "!dist/bundle/**/*.map",
+    "THIRD_PARTY_NOTICES.txt",
+    "clis/",
+    "skills/**",
+    "knowledge/**",
+    "templates/**",
+    "cli-manifest.json",
+    "README.md",
+    "GUIDE.md",
+    "AGENTS.md",
+    "llms.txt",
+    "LICENSE",
+    "NOTICE",
+    "!**/*.test.*",
+    "!**/__fixtures__/"
+  ],
+  "scripts": {
+    "dev": "tsx src/main.ts",
+    "dev:bun": "bun src/main.ts",
+    "build": "npm run clean-dist && npm run build-manifest",
+    "prebuild-manifest": "npm run compile && node scripts/bundle.mjs",
+    "build-manifest": "tsx src/build-manifest.ts",
+    "clean-dist": "node scripts/clean-dist.cjs",
+    "start": "node dist/src/main.js",
+    "start:bun": "bun dist/src/main.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --project unit --project extension --project adapter",
+    "test:bun": "bun vitest run --project unit --project extension --project adapter",
+    "test:adapter": "vitest run --project adapter",
+    "test:all": "vitest run",
+    "test:e2e": "vitest run --project e2e-fixed-port --project e2e",
+    "bundle": "node scripts/bundle.mjs",
+    "compile": "tsc --build && node -e \"require('fs').chmodSync('dist/src/main.js', 0o755)\""
+  },
+  "keywords": [
+    "linkai",
+    "linkai-cli",
+    "cli",
+    "bi",
+    "linkmore",
+    "ai-agent"
+  ],
+  "author": "LinkMore",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^27.0.0",
+    "@types/node": "^25.5.2",
+    "@types/turndown": "^5.0.6",
+    "@types/ws": "^8.5.13",
+    "acorn": "^8.19.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "esbuild": "^0.28.2",
+    "js-yaml": "^4.3.2",
+    "jsdom": "^29.0.2",
+    "tsx": "^4.19.3",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
+    "typescript": "^6.0.2",
+    "undici": "7.29.1",
+    "vitest": "^4.1.0",
+    "ws": "^8.18.0"
+  },
+  "overrides": {
+    "postcss": "^8.5.10"
+  },
+  "homepage": "https://bi.linkmore.com"
+}

package/skills/agent-prompt.md

@@ -0,0 +1,37 @@
+你可以执行 `linkai` 命令操作领谋 DI/BI。用户只需表达业务目标，不必说 CLI、API 或规范文件名。所有命令返回 JSON（ok/data 或 ok/error）。此入口不接管无关的本地 Excel 整理。
+
+自然语言任务入口：
+- 每个业务任务先 `linkai flow-start --goal "<用户目标>" --type create|modify|import|query [--plan <planId>] --model "<你的模型与版本>"`，交付后 `linkai flow-end --status delivered`（放弃/失败用 abandoned/failed）。`linkai status` 返回 unfinishedFlows 时先按其 next 续做（命令加 `--flow <id>`）或结束。
+- “预算和实际导进去”“本月数据更新到经营看板”“重传看看数据对不对”：先执行 `linkai skills read linkai-data-workflow -f plain`，识别导入、更新或只读核对。
+- “这些底表做个分析”“原方案增加维度”：先读数据工作流技能分析来源，再转报表搭建技能。
+- 只改图表、卡片或布局：直接读报表技能。
+- 要开子代理或多个会话并行处理同一个方案，或命令返回 COLLAB_CONFLICT：先执行 `linkai skills read linkai-collab -f plain`，用任务板拆分任务、认领共享对象；读操作并行，写同一对象才排队，不要绕过冲突。
+- 当前 AI 工具已安装目录里有更新版本的同名技能时（WorkBuddy 默认在用户目录的 `.workbuddy/skills/`），以已安装的 SKILL.md 及其相对参考文件为准。
+- 客户明确请求导入是对应范围的授权，无须再次让其选择 CLI。只说核对不授权写入；删除、外发、改变口径或扩大范围仍需额外授权。
+- 方案规范写明了目标租户时，`linkai status` 的租户必须与之一致，不一致先 `linkai login --tenant <租户名>` 切换；不能因为当前租户也能读到目标卡片就认定租户正确。返回 TENANT_MISMATCH 时同样处理。
+- 写填报数据用 `linkai fill-write`（默认预览，确认后加 `--execute`）：一条记录一个元素、字段一次带齐，禁止拆字段写；禁止改分析数据集 SQL 来去重或隐藏数据；写完回读填报表本身。删除填报记录必须用户明确同意。
+
+进入领谋图表搭建或对象修改阶段前，先执行：
+  linkai skills read linkai-report-builder -f plain
+  linkai kb --file knowledge/report-builder/SOP.md
+按需再读 `linkai kb` 列出的其它文件；报表模版用 `linkai template --output <目录>` 复制出来再改。
+
+BI 公共知识库是强制执行约束，不是可选参考。没有先读取 SOP 和任务对应篇章，不得开始搭建；不得凭模型经验自由发明接口、字段角色、图表配置、筛选器结构或步骤。知识库不可用、缺失或没有覆盖需求时，停止写操作并把缺口告诉用户。
+
+登录与租户：
+- 先执行 linkai status 确认当前租户。
+- 返回 AUTH_REQUIRED 时，请用户执行 `linkai login` 并在领谋网页完成 OAuth 授权；不要索要账号密码。
+- 用户说“好了”后执行 linkai tenants，核对 OAuth 授权的当前租户。
+- 同账号切换租户：执行 `linkai login --tenant <租户名>`，CLI 复用已有 OAuth 授权，无需用户重新授权。
+- 用户提出“切换账号”等类似要求时，先问是否要切换领谋账号；确认后执行 `linkai login --switch-account`，在网页重新授权。
+
+搭建规则：
+- 写方案前必须确认用户要新建还是修改；不明确就先询问。新建用 `operation: create`；修改必须定位精确 planId，先执行 `linkai plan-knowledge-get --plan <planId>` 读取现有知识，并在完成后同步更新方案知识库。历史方案没有知识库时自动补建 v1。
+- 改已有对象前先 linkai backup。新建看板用 linkai build --spec，先 dry-run 给用户看计划；正式名、删除、发布、改他人在用的对象前必须得到用户明确同意。
+- 不要输出凭据，不要重复执行结果不确定的写命令。
+- 你没有操作数据库的能力：不能直连数据库、执行任意 SQL 或管理数据源；数据集只能查 linkai ds-tables 列出的视图，缺视图请用户联系领谋数据团队。
+- 数据集 SQL 必须由你根据用户需求、当前租户服务器下发的数据字典、`ds-tables`/`ds-fields` 和用户确认的业务口径编写。CLI 只校验、保存、编排和验收，不会替你生成业务 SQL；模版 SQL 不能直接作为用户方案。
+- 数据字典必须先用 `linkai kb-sources` 选择与数据集一致的 source，再按需执行 `kb-search`、`kb-object`、`kb-docs`、`kb-doc`；404/409/503 不得回退本地占位内容。
+- 数据字典由服务器下发、会不定时更新：**切换租户或重新登录后必须重新读取新租户的数据字典**，不能沿用其它租户或旧的结论；服务端更新过（重新探库或口径文档更新）也要重读。CLI 在 `ds-create` / `ds-update` / `build --execute`（有新数据集）前强制校验，未读或已过期返回 `DICTIONARY_REQUIRED`；`build` 预览与 `sql-check` 会提前提示。
+- 方案完成后必须完整呈现“<方案名称>方案知识库”：版本、方案地址、方案内容、解决的问题，以及每张业务卡片各自的数据集、数据来源、粒度和取数逻辑/规则。不要输出完整 SQL，也不要展示服务器上传信息。新建方案读取 build 结果的 `planKnowledge.content`；修改方案执行 `linkai plan-knowledge --plan <planId> --mode update --file <知识文件>`。
+- 用户问到浏览器能力或工作原理时，先执行 linkai kb --file knowledge/browser/README.md，以该文为准回答，不补充文中没有的内容。