@guandata/guancli 1.0.66 → 1.0.67
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +4 -0
- package/README.md +4 -0
- package/package.json +6 -6
- package/skills/guancli/SKILL.md +8 -0
- package/skills/guancli/references/form-chatbi.md +8 -0
package/CHANGELOG.md
CHANGED
package/README.md
CHANGED
|
@@ -45,6 +45,10 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
|
|
|
45
45
|
|
|
46
46
|
## 版本更新
|
|
47
47
|
|
|
48
|
+
### @guandata/guancli 1.0.67
|
|
49
|
+
|
|
50
|
+
- 表单写入后明确提示刷新目标数据集，并区分数据刷新与字段结构同步。
|
|
51
|
+
|
|
48
52
|
### @guandata/guancli 1.0.66
|
|
49
53
|
|
|
50
54
|
- 新增本地 `analyze` 表格处理与 `report` 排名分析入口，可对 CSV/JSON 结果进行字段对齐、计算、分组排名和占比输出。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guandata/guancli",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.67",
|
|
4
4
|
"description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
|
|
5
5
|
"bin": {
|
|
6
6
|
"guancli": "bin/run.js"
|
|
@@ -42,11 +42,11 @@
|
|
|
42
42
|
"node": ">=14"
|
|
43
43
|
},
|
|
44
44
|
"optionalDependencies": {
|
|
45
|
-
"@guandata/guancli-darwin-arm64": "1.0.
|
|
46
|
-
"@guandata/guancli-darwin-x64": "1.0.
|
|
47
|
-
"@guandata/guancli-linux-x64": "1.0.
|
|
48
|
-
"@guandata/guancli-linux-arm64": "1.0.
|
|
49
|
-
"@guandata/guancli-win32-x64": "1.0.
|
|
45
|
+
"@guandata/guancli-darwin-arm64": "1.0.67",
|
|
46
|
+
"@guandata/guancli-darwin-x64": "1.0.67",
|
|
47
|
+
"@guandata/guancli-linux-x64": "1.0.67",
|
|
48
|
+
"@guandata/guancli-linux-arm64": "1.0.67",
|
|
49
|
+
"@guandata/guancli-win32-x64": "1.0.67"
|
|
50
50
|
},
|
|
51
51
|
"publishConfig": {
|
|
52
52
|
"registry": "https://registry.npmjs.org/",
|
package/skills/guancli/SKILL.md
CHANGED
|
@@ -140,6 +140,14 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
|
|
|
140
140
|
|
|
141
141
|
## Form 关键规则
|
|
142
142
|
|
|
143
|
+
**表单与数据集同步边界**：SurveyEngine 表单是数据源，BI 仅在主动更新或已配置的调度运行时抽取。`guancli form add/update/delete` 的成功回执只针对表单操作，不证明关联 GUAN_FORM 数据集已更新；CLI 不会自动刷新。刷新以整个业务任务为边界，不以接口批次或 CLI 调用次数为边界。分批写入或修改结构期间，禁止因每次成功提示逐批刷新或同步结构；提示本身不构成立即更新数据集的指令。全部批次及结构修改完成、核对成功与失败结果后，仅当用户需要下游 ETL/卡片使用最新结构或数据时，对每个关联数据集统一更新一次；只要求写入表单时，不主动刷新。比如 1 万条拆成 100 批写入，应全部完成后按需刷新一次，不能每批刷新。数据更新使用 `guands dataset refresh <dsId> --overwrite --wait`。新建填报数据集默认不开启定时更新。使用已确认关联该 fmId 的 dsId，不能按同名猜测。
|
|
144
|
+
|
|
145
|
+
字段新增、删除、改名或类型变化且需要更新下游时，等本次业务任务的全部结构修改与数据写入完成后，统一先执行 `guands dataset sync-schema plan <dsId> --out plan.json`，检查字段映射与删除项，再执行 `guands dataset sync-schema apply <dsId> --plan plan.json --mode schema-only --dry-run`，核对后移除 `--dry-run` 执行；结构同步完成后再主动执行 `guands dataset refresh <dsId> --overwrite --wait`。默认使用 `schema-only`；只有用户明确授权重置数据集时才使用 `reset`，该模式更新结构并全量抽取。普通 refresh（含 --overwrite）不替代模型结构同步。结构编辑是 `guands form update <fmId> form.js`，数据行更新是 `guancli form update <fmId> <rowId>`。
|
|
146
|
+
|
|
147
|
+
**刷新等待超时**：`guands dataset refresh <dsId> --wait` 默认等待 300 秒，可在首次触发时用 `--timeout <秒数>` 调整（如 `--timeout 1800`）。等待超时或调用工具停止等待只表示结果尚未确认，不等于服务端更新失败，也不会取消已提交的更新。遇到超时，先执行只读命令 `guands dataset get <dsId>` 查看当前更新状态，结合本次提交回执、任务标识（若返回）及执行时间确认是否为本次更新：仍在更新时继续只读查询状态；确认本次已成功时直接回读数据验证，不再刷新；只有确认本次已失败或取消、排除其他正在执行的更新并查明原因后，才按原授权范围决定是否重试。状态读取失败、信息不足或无法确认本次结果时，报告“更新结果待确认”，不得推断失败并重发 refresh。不要把再次执行 `refresh --wait` 当作纯等待接口：若原任务已结束，该命令可能提交新的更新；`--overwrite` 同样不能用于超时后盲目重试。
|
|
148
|
+
|
|
149
|
+
`form query` 回读表单数据，`ds preview` 回读 BI 数据集；两者不是同一个读取阶段。确认刷新失败且决定重试时，只重试刷新，不重复已成功的表单写入。`--overwrite` 遇到已有更新会拒绝，应等其结束后重新提交；不能只等待写入前已启动的旧任务就认定本次写入已被抽取。开启审批时应先确认审批通过及数据实际生效，再更新数据集。
|
|
150
|
+
|
|
143
151
|
- `form query --filter` 在**服务端**执行，格式 `"列名 操作符 [值]"`，可重复；多条件默认
|
|
144
152
|
`AND`，用 `--combine-type OR` 改成 `OR`。操作符可用性取决于字段控件类型：比较和区间
|
|
145
153
|
操作符（`GT`/`GE`/`LT`/`LE`/`BT` 系列）只支持 `NUMBER` 和 `DATE_TIME`，
|
|
@@ -4,6 +4,14 @@
|
|
|
4
4
|
|
|
5
5
|
类似 Airtable 风格的表单数据 CRUD，用户始终用**字段名**操作，CLI 内部自动映射到 fdId。
|
|
6
6
|
|
|
7
|
+
**表单与数据集同步边界**：SurveyEngine 表单是数据源，BI 仅在主动更新或已配置的调度运行时抽取。`guancli form add/update/delete` 的成功回执只针对表单操作，不证明关联 GUAN_FORM 数据集已更新；CLI 不会自动刷新。刷新以整个业务任务为边界，不以接口批次或 CLI 调用次数为边界。分批写入或修改结构期间，禁止因每次成功提示逐批刷新或同步结构；提示本身不构成立即更新数据集的指令。全部批次及结构修改完成、核对成功与失败结果后，仅当用户需要下游 ETL/卡片使用最新结构或数据时，对每个关联数据集统一更新一次；只要求写入表单时，不主动刷新。比如 1 万条拆成 100 批写入，应全部完成后按需刷新一次，不能每批刷新。数据更新使用 `guands dataset refresh <dsId> --overwrite --wait`。新建填报数据集默认不开启定时更新。使用已确认关联该 fmId 的 dsId，不能按同名猜测。
|
|
8
|
+
|
|
9
|
+
字段新增、删除、改名或类型变化且需要更新下游时，等本次业务任务的全部结构修改与数据写入完成后，统一先执行 `guands dataset sync-schema plan <dsId> --out plan.json`，检查字段映射与删除项，再执行 `guands dataset sync-schema apply <dsId> --plan plan.json --mode schema-only --dry-run`，核对后移除 `--dry-run` 执行；结构同步完成后再主动执行 `guands dataset refresh <dsId> --overwrite --wait`。默认使用 `schema-only`；只有用户明确授权重置数据集时才使用 `reset`，该模式更新结构并全量抽取。普通 refresh（含 --overwrite）不替代模型结构同步。结构编辑是 `guands form update <fmId> form.js`，数据行更新是 `guancli form update <fmId> <rowId>`。
|
|
10
|
+
|
|
11
|
+
**刷新等待超时**：`guands dataset refresh <dsId> --wait` 默认等待 300 秒，可在首次触发时用 `--timeout <秒数>` 调整（如 `--timeout 1800`）。等待超时或调用工具停止等待只表示结果尚未确认，不等于服务端更新失败，也不会取消已提交的更新。遇到超时，先执行只读命令 `guands dataset get <dsId>` 查看当前更新状态，结合本次提交回执、任务标识（若返回）及执行时间确认是否为本次更新：仍在更新时继续只读查询状态；确认本次已成功时直接回读数据验证，不再刷新；只有确认本次已失败或取消、排除其他正在执行的更新并查明原因后，才按原授权范围决定是否重试。状态读取失败、信息不足或无法确认本次结果时，报告“更新结果待确认”，不得推断失败并重发 refresh。不要把再次执行 `refresh --wait` 当作纯等待接口：若原任务已结束，该命令可能提交新的更新；`--overwrite` 同样不能用于超时后盲目重试。
|
|
12
|
+
|
|
13
|
+
`form query` 回读表单数据，`ds preview` 回读 BI 数据集；两者不是同一个读取阶段。确认刷新失败且决定重试时，只重试刷新，不重复已成功的表单写入。`--overwrite` 遇到已有更新会拒绝，应等其结束后重新提交；不能只等待写入前已启动的旧任务就认定本次写入已被抽取。开启审批时应先确认审批通过及数据实际生效，再更新数据集。
|
|
14
|
+
|
|
7
15
|
### 列出表单
|
|
8
16
|
|
|
9
17
|
```bash
|