@guandata/guancli 1.0.39 → 1.0.40

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.40 - 2026-07-15
+
+- 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
+- 卡片自带筛选字段元数据时不再强制读取数据集字段，权限受限场景也能正确应用筛选并完成预览。
+- 表单更新说明明确要求携带全部业务主键字段，帮助 Agent 在修改数据前准备完整且可执行的更新载荷。
+
 ## @guandata/guancli 1.0.39 - 2026-07-08
 
 - `etl get` 可读输出新增有效调度状态，综合 `config.enableSchedule`、`triggerType`、CRON 和上游级联开关判断真实自动触发状态，避免 `schedule --disable` 后底层触发字段残留造成误判。

package/README.md

@@ -39,6 +39,12 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.40
+
+- 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
+- 卡片自带筛选字段元数据时不再强制读取数据集字段，权限受限场景也能正确应用筛选并完成预览。
+- 表单更新说明明确要求携带全部业务主键字段，帮助 Agent 在修改数据前准备完整且可执行的更新载荷。
+
 ### @guandata/guancli 1.0.39
 
 - `etl get` 可读输出新增有效调度状态，综合 `config.enableSchedule`、`triggerType`、CRON 和上游级联开关判断真实自动触发状态，避免 `schedule --disable` 后底层触发字段残留造成误判。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/references/form-chatbi.md

@@ -46,11 +46,12 @@ echo '[{"字段名":"a"},{"字段名":"b"}]' | go run ./cmd/guancli form add <fm
 ### 更新数据
 
 ```bash
-go run ./cmd/guancli form update <fmId> <rowId> --data '{"字段名": "新值"}'
-go run ./cmd/guancli form update <fmId> <rowId> --set "字段名=新值"
+go run ./cmd/guancli form update <fmId> <rowId> --data '{"主键字段": "当前主键值", "字段名": "新值"}'
+go run ./cmd/guancli form update <fmId> <rowId> --set "主键字段=当前主键值" --set "字段名=新值"
 ```
 
-`rowId` 通过 `form query` 获取。
+`rowId` 和未编辑主键的当前值通过 `form query` 获取。更新载荷必须包含表单配置的全部业务主键字段（内置
+`c_uid` 除外）；CLI 只负责字段名映射和请求透传，不读取当前行、不补齐主键，也不在本地重复后端校验。
 
 ### 删除数据
 
@@ -115,8 +116,8 @@ go run ./cmd/guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
 # 4. 查询并获取 rowId
 go run ./cmd/guancli form query <fmId> -f json
 
-# 5. 更新
-go run ./cmd/guancli form update <fmId> <rowId> --set "值=99"
+# 5. 更新（同时携带业务主键）
+go run ./cmd/guancli form update <fmId> <rowId> --set "名称=当前名称" --set "值=99"
 
 # 6. 删除
 go run ./cmd/guancli form delete <fmId> <rowId>

package/skills/guancli/references/preview-and-output.md

@@ -93,6 +93,8 @@ guancli card preview <cd_id> --value-format raw -f csv # 保留原始数值，
 卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
 图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。图表卡片数值默认使用 `--value-format formatted`，按卡片返回的数值格式输出（小数位、千分位、货币、百分比、单位等）；需要保留原始数值用于 AI 后续计算时，使用 `--value-format raw`。无卡片格式时 `--precision` 作为兜底最大精度，默认 6 位。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
 
+当图表卡片返回同环比、日期层级或其他多层列表头时，默认输出和 `-f table` 会逐层显示完整表头。JSON、CSV、Excel 等结构化输出使用 `父级 > 子级 > 叶子` 形式的完整路径作为列名，避免只保留末级标题后出现重名或含义丢失。标题自身包含的每个 `>` 会编码为 `\>`，从而与层级分隔符区分；完整路径仍重复时，后续列会追加稳定后缀（如 ` [2]`），保证结构化键唯一且可被筛选、排序。`--columns` 和 `--sort-*` 优先接受大小写精确的完整路径；为了兼容旧命令，末级标题唯一时仍可使用末级标题，存在同名末级标题时会明确提示改用完整路径。
+
 复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、数值输出格式、动态参数和动态维度。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
 
 ### 带筛选条件预览卡片