@guandata/guancli 1.0.39 → 1.0.41

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.
Files changed (14) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +14 -0
  3. package/bin/postinstall.js +58 -0
  4. package/bin/run.js +32 -1
  5. package/binaries/guancli-darwin-arm64 +0 -0
  6. package/binaries/guancli-darwin-x64 +0 -0
  7. package/binaries/guancli-linux-arm64 +0 -0
  8. package/binaries/guancli-linux-x64 +0 -0
  9. package/binaries/guancli-win32-x64.exe +0 -0
  10. package/package.json +2 -1
  11. package/skills/guancli/references/auth-and-config.md +11 -11
  12. package/skills/guancli/references/form-chatbi.md +41 -40
  13. package/skills/guancli/references/preview-and-output.md +24 -22
  14. package/skills/guancli/references/resource-query.md +17 -17
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## @guandata/guancli 1.0.41 - 2026-07-20
4
+
5
+ - 增强复杂报表 Pro 子卡片的元数据读取与筛选支持，复杂报表分析结果更完整。
6
+ - 精简页面、数据集和 ETL 的可读输出，便于 Agent 直接定位关键信息。
7
+ - 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。
8
+
9
+ ## @guandata/guancli 1.0.40 - 2026-07-15
10
+
11
+ - 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
12
+ - 卡片自带筛选字段元数据时不再强制读取数据集字段，权限受限场景也能正确应用筛选并完成预览。
13
+ - 表单更新说明明确要求携带全部业务主键字段，帮助 Agent 在修改数据前准备完整且可执行的更新载荷。
14
+
3
15
  ## @guandata/guancli 1.0.39 - 2026-07-08
4
16
 
5
17
  - `etl get` 可读输出新增有效调度状态，综合 `config.enableSchedule`、`triggerType`、CRON 和上游级联开关判断真实自动触发状态，避免 `schedule --disable` 后底层触发字段残留造成误判。
package/README.md CHANGED
@@ -8,6 +8,8 @@
8
8
  npm install -g @guandata/guancli
9
9
  ```
10
10
 
11
+ > 全局安装/升级时会通过 postinstall 自动执行一次 `guancli install-skill` 刷新 AI skill；CI 等无需 skill 的环境可设 `GUAN_SKIP_INSTALL_SKILL=1` 跳过。
12
+
11
13
  也可以直接使用：
12
14
 
13
15
  ```bash
@@ -39,6 +41,18 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
39
41
 
40
42
  ## 版本更新
41
43
 
44
+ ### @guandata/guancli 1.0.41
45
+
46
+ - 增强复杂报表 Pro 子卡片的元数据读取与筛选支持，复杂报表分析结果更完整。
47
+ - 精简页面、数据集和 ETL 的可读输出，便于 Agent 直接定位关键信息。
48
+ - 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。
49
+
50
+ ### @guandata/guancli 1.0.40
51
+
52
+ - 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
53
+ - 卡片自带筛选字段元数据时不再强制读取数据集字段，权限受限场景也能正确应用筛选并完成预览。
54
+ - 表单更新说明明确要求携带全部业务主键字段，帮助 Agent 在修改数据前准备完整且可执行的更新载荷。
55
+
42
56
  ### @guandata/guancli 1.0.39
43
57
 
44
58
  - `etl get` 可读输出新增有效调度状态，综合 `config.enableSchedule`、`triggerType`、CRON 和上游级联开关判断真实自动触发状态，避免 `schedule --disable` 后底层触发字段残留造成误判。
package/bin/postinstall.js ADDED
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Best-effort post-install hook: refresh the installed AI skill right after
5
+ * a global npm install/upgrade, so users cannot forget to run
6
+ * `guancli install-skill` and end up with a stale SKILL.md.
7
+ *
8
+ * Constraints:
9
+ * - MUST never fail the npm install: every failure path still exits 0.
10
+ * - Only runs for global installs (`npm install -g` / `npm link`); a local
11
+ * `npm install` inside a project never touches the user's home dirs.
12
+ * - Escape hatch: GUAN_SKIP_INSTALL_SKILL=1 skips entirely (e.g. CI images
13
+ * that install the CLI but never run an AI agent are skipped by default).
14
+ */
15
+
16
+ "use strict";
17
+
18
+ const { spawnSync } = require("child_process");
19
+ const path = require("path");
20
+
21
+ const CLI_NAME = "guancli";
22
+
23
+ function skipReason() {
24
+ if (process.env.GUAN_SKIP_INSTALL_SKILL === "1") return "GUAN_SKIP_INSTALL_SKILL=1";
25
+ if (process.env.npm_config_global !== "true") return "not a global install";
26
+ if (process.env.CI) return "CI environment";
27
+ return "";
28
+ }
29
+
30
+ function main() {
31
+ const reason = skipReason();
32
+ if (reason) {
33
+ console.log(`[${CLI_NAME}] postinstall: skipping automatic install-skill (${reason}).`);
34
+ return;
35
+ }
36
+ console.log(`[${CLI_NAME}] postinstall: refreshing AI skill (${CLI_NAME} install-skill)...`);
37
+ const result = spawnSync(
38
+ process.execPath,
39
+ [path.join(__dirname, "run.js"), "install-skill"],
40
+ { stdio: "inherit", env: process.env, timeout: 180000 }
41
+ );
42
+ if (result.error || result.status !== 0) {
43
+ console.warn(
44
+ `[${CLI_NAME}] postinstall: automatic skill install did not complete` +
45
+ (result.error ? ` (${result.error.message})` : ` (exit ${result.status})`) +
46
+ `; run \`${CLI_NAME} install-skill\` manually to refresh SKILL.md.`
47
+ );
48
+ }
49
+ }
50
+
51
+ try {
52
+ main();
53
+ } catch (err) {
54
+ console.warn(
55
+ `[${CLI_NAME}] postinstall: ${err.message}; run \`${CLI_NAME} install-skill\` manually.`
56
+ );
57
+ }
58
+ process.exit(0);
package/bin/run.js CHANGED
@@ -86,10 +86,36 @@ if (process.argv[2] === "version" && process.argv.length === 3) {
86
86
  process.exit(0);
87
87
  }
88
88
 
89
+
90
+ // 定位 npm 自带的 npx-cli.js 并用 node 直接执行（与 guanskill 保持一致），
91
+ // 避免 Windows 上 spawn npx.cmd 的两类问题：shell:true 不做参数 quoting
92
+ // （全局安装路径含空格时会被拆参），以及新版 Node 禁止无 shell 的 .cmd
93
+ // spawn（CVE-2024-27980）。postinstall 场景下 npm_execpath 必然可用。
94
+ function resolveNpxInvocation() {
95
+ const executableDir = path.dirname(process.execPath);
96
+ const candidates = [];
97
+ if (process.env.npm_execpath) {
98
+ candidates.push(path.join(path.dirname(process.env.npm_execpath), "npx-cli.js"));
99
+ }
100
+ candidates.push(path.join(executableDir, "node_modules", "npm", "bin", "npx-cli.js"));
101
+ candidates.push(path.resolve(executableDir, "..", "node_modules", "npm", "bin", "npx-cli.js"));
102
+ candidates.push(path.resolve(executableDir, "..", "lib", "node_modules", "npm", "bin", "npx-cli.js"));
103
+ const npxCliPath = candidates.find((candidate) => fs.existsSync(candidate));
104
+ if (npxCliPath) {
105
+ return { command: process.execPath, argsPrefix: [npxCliPath] };
106
+ }
107
+ if (process.platform === "win32") {
108
+ throw new Error("Cannot locate npm/bin/npx-cli.js for safe Windows execution");
109
+ }
110
+ return { command: "npx", argsPrefix: [] };
111
+ }
112
+
89
113
  if (process.argv[2] === "install-skill") {
90
114
  const pkgRoot = path.join(__dirname, "..");
91
115
  const extraArgs = process.argv.slice(3);
92
116
  const args = [
117
+ // --yes: postinstall 等非交互环境下 npx 需要免确认下载 skills CLI
118
+ "--yes",
93
119
  "skills",
94
120
  "add",
95
121
  pkgRoot,
@@ -100,7 +126,12 @@ if (process.argv[2] === "install-skill") {
100
126
  ...extraArgs,
101
127
  ];
102
128
  console.log("Installing guancli to AI coding assistants...");
103
- const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
129
+ const npxInvocation = resolveNpxInvocation();
130
+ const result = spawnSync(npxInvocation.command, [...npxInvocation.argsPrefix, ...args], {
131
+ stdio: "inherit",
132
+ env: process.env,
133
+ shell: false,
134
+ });
104
135
  if (result.error) throw result.error;
105
136
  const status = result.status || 0;
106
137
  if (status === 0) installBuddySkills(pkgRoot, "guancli");
package/binaries/guancli-darwin-arm64 CHANGED
Binary file
package/binaries/guancli-darwin-x64 CHANGED
Binary file
package/binaries/guancli-linux-arm64 CHANGED
Binary file
package/binaries/guancli-linux-x64 CHANGED
Binary file
package/binaries/guancli-win32-x64.exe CHANGED
Binary file
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@guandata/guancli",
3
- "version": "1.0.39",
3
+ "version": "1.0.41",
4
4
  "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
5
5
  "bin": {
6
6
  "guancli": "bin/run.js"
7
7
  },
8
8
  "scripts": {
9
+ "postinstall": "node bin/postinstall.js",
9
10
  "build": "node scripts/build.js && node scripts/sync-skill.js",
10
11
  "changelog": "node ../../scripts/generate-release-changelog.js .",
11
12
  "check-changelog": "node ../../scripts/check-release-changelog.js .",
package/skills/guancli/references/auth-and-config.md CHANGED
@@ -5,7 +5,7 @@
5
5
  ### 方式一：用户名密码登录（推荐）
6
6
 
7
7
  ```bash
8
- go run ./cmd/guancli auth login
8
+ guancli auth login
9
9
  ```
10
10
 
11
11
  交互式输入：
@@ -21,7 +21,7 @@ go run ./cmd/guancli auth login
21
21
  ### 方式二：直接输入 uIdToken
22
22
 
23
23
  ```bash
24
- go run ./cmd/guancli auth login
24
+ guancli auth login
25
25
  ```
26
26
 
27
27
  选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
@@ -29,7 +29,7 @@ go run ./cmd/guancli auth login
29
29
  ### 方式三：Personal Access Token
30
30
 
31
31
  ```bash
32
- go run ./cmd/guancli auth login --url https://bi.example.com --pat <pat>
32
+ guancli auth login --url https://bi.example.com --pat <pat>
33
33
  ```
34
34
 
35
35
  交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 通过 `fetch` 调用时保留其自身来源），`auth status` 会通过 `/pat/introspect` 做自检。
@@ -39,19 +39,19 @@ go run ./cmd/guancli auth login --url https://bi.example.com --pat <pat>
39
39
  ### 多环境管理
40
40
 
41
41
  ```bash
42
- go run ./cmd/guancli auth login --profile staging # 添加 staging 环境
43
- go run ./cmd/guancli auth login --profile prod --default # 添加 prod 并设为默认
44
- go run ./cmd/guancli auth list # 列出所有环境
45
- go run ./cmd/guancli auth status # 查看当前认证状态
46
- go run ./cmd/guancli auth use staging # 切换默认环境为 staging
47
- go run ./cmd/guancli auth remove staging # 删除 staging 环境
42
+ guancli auth login --profile staging # 添加 staging 环境
43
+ guancli auth login --profile prod --default # 添加 prod 并设为默认
44
+ guancli auth list # 列出所有环境
45
+ guancli auth status # 查看当前认证状态
46
+ guancli auth use staging # 切换默认环境为 staging
47
+ guancli auth remove staging # 删除 staging 环境
48
48
  ```
49
49
 
50
50
  使用特定环境（不切换默认）：
51
51
 
52
52
  ```bash
53
- go run ./cmd/guancli --profile staging etl tree
54
- go run ./cmd/guancli --profile staging chatbi list-theme
53
+ guancli --profile staging etl tree
54
+ guancli --profile staging chatbi list-theme
55
55
  ```
56
56
 
57
57
  ### ChatBI 配置
package/skills/guancli/references/form-chatbi.md CHANGED
@@ -7,28 +7,28 @@
7
7
  ### 列出表单
8
8
 
9
9
  ```bash
10
- go run ./cmd/guancli form list # 列出所有表单
11
- go run ./cmd/guancli form list 关键词 # 搜索表单
12
- go run ./cmd/guancli form list --tree # 目录树形式展示
10
+ guancli form list # 列出所有表单
11
+ guancli form list 关键词 # 搜索表单
12
+ guancli form list --tree # 目录树形式展示
13
13
  ```
14
14
 
15
15
  ### 查看表单结构
16
16
 
17
17
  ```bash
18
- go run ./cmd/guancli form schema <fmId> # 查看字段结构（LLM 消费核心）
19
- go run ./cmd/guancli form schema <fmId> -f json # JSON 格式
18
+ guancli form schema <fmId> # 查看字段结构（LLM 消费核心）
19
+ guancli form schema <fmId> -f json # JSON 格式
20
20
  ```
21
21
 
22
22
  ### 查询数据
23
23
 
24
24
  ```bash
25
- go run ./cmd/guancli form query <fmId> # 查询数据（默认 50 行）
26
- go run ./cmd/guancli form query <fmId> --limit 100 # 指定行数
27
- go run ./cmd/guancli form query <fmId> --filter "姓名 EQ 张三" # 筛选
28
- go run ./cmd/guancli form query <fmId> --sort-asc 值 # 按值升序
29
- go run ./cmd/guancli form query <fmId> --columns "姓名,值" # 只显示指定列
30
- go run ./cmd/guancli form query <fmId> -f json # JSON 格式（rowId 完整）
31
- go run ./cmd/guancli form query <fmId> -f expanded # PG 风格竖排
25
+ guancli form query <fmId> # 查询数据（默认 50 行）
26
+ guancli form query <fmId> --limit 100 # 指定行数
27
+ guancli form query <fmId> --filter "姓名 EQ 张三" # 筛选
28
+ guancli form query <fmId> --sort-asc 值 # 按值升序
29
+ guancli form query <fmId> --columns "姓名,值" # 只显示指定列
30
+ guancli form query <fmId> -f json # JSON 格式（rowId 完整）
31
+ guancli form query <fmId> -f expanded # PG 风格竖排
32
32
  ```
33
33
 
34
34
  筛选操作符：`EQ`（等于）、`CONTAINS`（包含）、`STARTSWITH`、`ENDSWITH`、`IS_NULL`、`NOT_NULL`。
@@ -38,26 +38,27 @@ go run ./cmd/guancli form query <fmId> -f expanded # PG 风格竖
38
38
  ### 插入数据
39
39
 
40
40
  ```bash
41
- go run ./cmd/guancli form add <fmId> --data '{"字段名": "值", "数字字段": 42}'
42
- go run ./cmd/guancli form add <fmId> --set "字段名=值" --set "数字字段=42"
43
- echo '[{"字段名":"a"},{"字段名":"b"}]' | go run ./cmd/guancli form add <fmId> --stdin
41
+ guancli form add <fmId> --data '{"字段名": "值", "数字字段": 42}'
42
+ guancli form add <fmId> --set "字段名=值" --set "数字字段=42"
43
+ echo '[{"字段名":"a"},{"字段名":"b"}]' | guancli form add <fmId> --stdin
44
44
  ```
45
45
 
46
46
  ### 更新数据
47
47
 
48
48
  ```bash
49
- go run ./cmd/guancli form update <fmId> <rowId> --data '{"字段名": "新值"}'
50
- go run ./cmd/guancli form update <fmId> <rowId> --set "字段名=新值"
49
+ guancli form update <fmId> <rowId> --data '{"主键字段": "当前主键值", "字段名": "新值"}'
50
+ guancli form update <fmId> <rowId> --set "主键字段=当前主键值" --set "字段名=新值"
51
51
  ```
52
52
 
53
- `rowId` 通过 `form query` 获取。
53
+ `rowId` 和未编辑主键的当前值通过 `form query` 获取。更新载荷必须包含表单配置的全部业务主键字段（内置
54
+ `c_uid` 除外）；CLI 只负责字段名映射和请求透传，不读取当前行、不补齐主键，也不在本地重复后端校验。
54
55
 
55
56
  ### 删除数据
56
57
 
57
58
  ```bash
58
- go run ./cmd/guancli form delete <fmId> <rowId> # 删除单行
59
- go run ./cmd/guancli form delete <fmId> <rowId1> <rowId2> # 删除多行
60
- go run ./cmd/guancli form delete <fmId> --all --yes # 删除全部（需确认）
59
+ guancli form delete <fmId> <rowId> # 删除单行
60
+ guancli form delete <fmId> <rowId1> <rowId2> # 删除多行
61
+ guancli form delete <fmId> --all --yes # 删除全部（需确认）
61
62
  ```
62
63
 
63
64
  ### 子表操作
@@ -66,23 +67,23 @@ go run ./cmd/guancli form delete <fmId> --all --yes # 删除全部
66
67
 
67
68
  ```bash
68
69
  # 1. 查看主表 schema，找到 TABLE 字段的 subFmId
69
- go run ./cmd/guancli form schema <mainFmId>
70
+ guancli form schema <mainFmId>
70
71
  # 输出中 TABLE 字段的备注列显示 "子表 subFmId=..."
71
72
 
72
73
  # 2. 查看子表字段结构
73
- go run ./cmd/guancli form schema <subFmId>
74
+ guancli form schema <subFmId>
74
75
 
75
76
  # 3. 查询子表数据（返回结果包含主表字段，rowId 为主表行 ID，subId 为子行 ID）
76
- go run ./cmd/guancli form query <subFmId>
77
+ guancli form query <subFmId>
77
78
 
78
79
  # 4. 向子表插入行（需指定主表行的 rowId）
79
- go run ./cmd/guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
80
+ guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
80
81
 
81
82
  # 5. 更新子表行（使用 subId 作为 rowId）
82
- go run ./cmd/guancli form update <subFmId> <subId> --set "字段名=新值"
83
+ guancli form update <subFmId> <subId> --set "字段名=新值"
83
84
 
84
85
  # 6. 删除子表行
85
- go run ./cmd/guancli form delete <subFmId> <subId>
86
+ guancli form delete <subFmId> <subId>
86
87
  ```
87
88
 
88
89
  **子表 ID 映射规则**（AI 调用时注意区分）：
@@ -104,22 +105,22 @@ go run ./cmd/guancli form delete <subFmId> <subId>
104
105
 
105
106
  ```bash
106
107
  # 1. 找到表单
107
- go run ./cmd/guancli form list 测试
108
+ guancli form list 测试
108
109
 
109
110
  # 2. 查看结构
110
- go run ./cmd/guancli form schema <fmId>
111
+ guancli form schema <fmId>
111
112
 
112
113
  # 3. 插入数据
113
- go run ./cmd/guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
114
+ guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
114
115
 
115
116
  # 4. 查询并获取 rowId
116
- go run ./cmd/guancli form query <fmId> -f json
117
+ guancli form query <fmId> -f json
117
118
 
118
- # 5. 更新
119
- go run ./cmd/guancli form update <fmId> <rowId> --set "值=99"
119
+ # 5. 更新（同时携带业务主键）
120
+ guancli form update <fmId> <rowId> --set "名称=当前名称" --set "值=99"
120
121
 
121
122
  # 6. 删除
122
- go run ./cmd/guancli form delete <fmId> <rowId>
123
+ guancli form delete <fmId> <rowId>
123
124
  ```
124
125
 
125
126
  ## 7. ChatBI 主题问数 / 洞察
@@ -127,12 +128,12 @@ go run ./cmd/guancli form delete <fmId> <rowId>
127
128
  先列主题，再执行问数或洞察；如果用户没有指定主题，不要猜。
128
129
 
129
130
  ```bash
130
- go run ./cmd/guancli chatbi list-theme
131
- go run ./cmd/guancli chatbi list-theme --insight
132
- go run ./cmd/guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
133
- go run ./cmd/guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
134
- go run ./cmd/guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
135
- go run ./cmd/guancli chatbi insight --theme-id "<theme_id>" --message "分析最近30天营业收入变化原因" --agent-mode single_agent
131
+ guancli chatbi list-theme
132
+ guancli chatbi list-theme --insight
133
+ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
134
+ guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
135
+ guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
136
+ guancli chatbi insight --theme-id "<theme_id>" --message "分析最近30天营业收入变化原因" --agent-mode single_agent
136
137
  ```
137
138
 
138
139
  规则：
package/skills/guancli/references/preview-and-output.md CHANGED
@@ -3,10 +3,10 @@
3
3
  ## 4. 预览数据集数据
4
4
 
5
5
  ```bash
6
- go run ./cmd/guancli ds preview <ds_id> # 预览数据集数据 (表格格式)
7
- go run ./cmd/guancli ds preview <ds_id> --limit 20 # 限制预览行数
8
- go run ./cmd/guancli ds preview <ds_id> --raw # 输出原始 JSON
9
- go run ./cmd/guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' # 用 SQL 查询数据集（需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
6
+ guancli ds preview <ds_id> # 预览数据集数据 (表格格式)
7
+ guancli ds preview <ds_id> --limit 20 # 限制预览行数
8
+ guancli ds preview <ds_id> --raw # 输出原始 JSON
9
+ guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' # 用 SQL 查询数据集（需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
10
10
  # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
11
11
  `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
12
12
  ```
@@ -21,11 +21,11 @@ go run ./cmd/guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据
21
21
  列名中包含空格时无需特殊处理，解析器会智能定位操作符。
22
22
 
23
23
  ```bash
24
- go run ./cmd/guancli ds preview <ds_id> --filter "name EQ 张三"
25
- go run ./cmd/guancli ds preview <ds_id> --filter "age GT 18" --filter "city IN 北京,上海,广州"
26
- go run ./cmd/guancli ds preview <ds_id> --filter "score BT 60,100"
27
- go run ./cmd/guancli ds preview <ds_id> --filter "status IS_NULL"
28
- go run ./cmd/guancli ds preview <ds_id> --filter "销售 金额 GT 100" --combine-type OR
24
+ guancli ds preview <ds_id> --filter "name EQ 张三"
25
+ guancli ds preview <ds_id> --filter "age GT 18" --filter "city IN 北京,上海,广州"
26
+ guancli ds preview <ds_id> --filter "score BT 60,100"
27
+ guancli ds preview <ds_id> --filter "status IS_NULL"
28
+ guancli ds preview <ds_id> --filter "销售 金额 GT 100" --combine-type OR
29
29
  ```
30
30
 
31
31
  支持的操作符：
@@ -69,10 +69,10 @@ guancli card preview <cd_id> --filter "日期字段 toDate EQ 2026-01-15"
69
69
  所有 preview 命令（ds/card）都支持排序和列筛选：
70
70
 
71
71
  ```bash
72
- go run ./cmd/guancli ds preview <ds_id> --sort-asc name # 按 name 升序 (API 层面排序)
73
- go run ./cmd/guancli ds preview <ds_id> --sort-desc id # 按 id 降序 (API 层面排序)
74
- go run ./cmd/guancli ds preview <ds_id> --columns "id,name,status" # 只显示指定列
75
- go run ./cmd/guancli ds preview <ds_id> --filter "status EQ FAILED" --sort-desc id --columns "id,task_name"
72
+ guancli ds preview <ds_id> --sort-asc name # 按 name 升序 (API 层面排序)
73
+ guancli ds preview <ds_id> --sort-desc id # 按 id 降序 (API 层面排序)
74
+ guancli ds preview <ds_id> --columns "id,name,status" # 只显示指定列
75
+ guancli ds preview <ds_id> --filter "status EQ FAILED" --sort-desc id --columns "id,task_name"
76
76
  ```
77
77
 
78
78
  - `--sort-asc` / `--sort-desc`: 互斥，只能指定一个列。ds preview 的排序通过 API 在数据库层面执行；card preview 的排序在 Go 端对本次取数范围执行，排序取数下限为 10000 行，若卡片总行数超过本次取数范围，不承诺全量 Top N。
@@ -93,6 +93,8 @@ guancli card preview <cd_id> --value-format raw -f csv # 保留原始数值，
93
93
  卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
94
94
  图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。图表卡片数值默认使用 `--value-format formatted`，按卡片返回的数值格式输出（小数位、千分位、货币、百分比、单位等）；需要保留原始数值用于 AI 后续计算时，使用 `--value-format raw`。无卡片格式时 `--precision` 作为兜底最大精度，默认 6 位。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
95
95
 
96
+ 当图表卡片返回同环比、日期层级或其他多层列表头时，默认输出和 `-f table` 会逐层显示完整表头。JSON、CSV、Excel 等结构化输出使用 `父级 > 子级 > 叶子` 形式的完整路径作为列名，避免只保留末级标题后出现重名或含义丢失。标题自身包含的每个 `>` 会编码为 `\>`，从而与层级分隔符区分；完整路径仍重复时，后续列会追加稳定后缀（如 ` [2]`），保证结构化键唯一且可被筛选、排序。`--columns` 和 `--sort-*` 优先接受大小写精确的完整路径；为了兼容旧命令，末级标题唯一时仍可使用末级标题，存在同名末级标题时会明确提示改用完整路径。
97
+
96
98
  复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、数值输出格式、动态参数和动态维度。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
97
99
 
98
100
  ### 带筛选条件预览卡片
@@ -147,18 +149,18 @@ guancli card preview <cd_id> --dynamic-field "dz_region:city_key"
147
149
  `--format` / `-f` 控制 preview 命令的输出格式：
148
150
 
149
151
  ```bash
150
- go run ./cmd/guancli ds preview <ds_id> # auto: 对齐表格，列>10 或行>20 时自动截断
151
- go run ./cmd/guancli ds preview <ds_id> -f csv # CSV 格式
152
- go run ./cmd/guancli ds preview <ds_id> -f excel # Excel 2003 XML 格式
153
- go run ./cmd/guancli ds preview <ds_id> -f expanded # PG 风格竖排
154
- go run ./cmd/guancli ds preview <ds_id> -f table # 对齐表格
155
- go run ./cmd/guancli ds preview <ds_id> -f json # JSON 行记录数组
156
- go run ./cmd/guancli ds preview <ds_id> -f json | jq '.[0]' # 配合 jq
152
+ guancli ds preview <ds_id> # auto: 对齐表格，列>10 或行>20 时自动截断
153
+ guancli ds preview <ds_id> -f csv # CSV 格式
154
+ guancli ds preview <ds_id> -f excel # Excel 2003 XML 格式
155
+ guancli ds preview <ds_id> -f expanded # PG 风格竖排
156
+ guancli ds preview <ds_id> -f table # 对齐表格
157
+ guancli ds preview <ds_id> -f json # JSON 行记录数组
158
+ guancli ds preview <ds_id> -f json | jq '.[0]' # 配合 jq
157
159
  ```
158
160
 
159
161
  `--raw` 输出 API 原始 JSON（不经过解析）：
160
162
 
161
163
  ```bash
162
- go run ./cmd/guancli --raw etl tree
163
- go run ./cmd/guancli --raw etl get <id>
164
+ guancli --raw etl tree
165
+ guancli --raw etl get <id>
164
166
  ```
package/skills/guancli/references/resource-query.md CHANGED
@@ -3,22 +3,22 @@
3
3
  ## 1. 拉取目录树
4
4
 
5
5
  ```bash
6
- go run ./cmd/guancli etl tree
7
- go run ./cmd/guancli ds tree
8
- go run ./cmd/guancli page tree
6
+ guancli etl tree
7
+ guancli ds tree
8
+ guancli page tree
9
9
  ```
10
10
 
11
11
  ## 2. 搜索资源
12
12
 
13
13
  ```bash
14
- go run ./cmd/guancli etl search # 搜索所有 ETL
15
- go run ./cmd/guancli etl search 关键词 # 按关键词搜索
16
- go run ./cmd/guancli etl search 关键词 -d <dir_id> # 在指定目录中搜索
17
- go run ./cmd/guancli ds search 关键词 # 搜索数据集
18
- go run ./cmd/guancli ds search --limit 500 --offset 500 # 分页扫描数据集
19
- go run ./cmd/guancli ds search --id <dsId> # 按数据集 ID 精确查找并返回单个数据集详情
20
- go run ./cmd/guancli ds search 关键词 --id <dsId> # 按名称 + ID 组合查找
21
- go run ./cmd/guancli page search 关键词 # 搜索页面
14
+ guancli etl search # 搜索所有 ETL
15
+ guancli etl search 关键词 # 按关键词搜索
16
+ guancli etl search 关键词 -d <dir_id> # 在指定目录中搜索
17
+ guancli ds search 关键词 # 搜索数据集
18
+ guancli ds search --limit 500 --offset 500 # 分页扫描数据集
19
+ guancli ds search --id <dsId> # 按数据集 ID 精确查找并返回单个数据集详情
20
+ guancli ds search 关键词 --id <dsId> # 按名称 + ID 组合查找
21
+ guancli page search 关键词 # 搜索页面
22
22
  ```
23
23
 
24
24
  `ds search` 默认返回前 500 条，环境数据集较多时用 `--limit` 和 `--offset` 分页扫描；`ds search --id` 会直接按数据集 ID 获取单个数据集详情，`--limit` 和 `--offset` 在 `--id` 模式下忽略。
@@ -26,11 +26,11 @@ go run ./cmd/guancli page search 关键词 # 搜索页面
26
26
  ## 3. 获取详情（含血缘）
27
27
 
28
28
  ```bash
29
- go run ./cmd/guancli etl get <resource_id> # ETL 详情（含节点、SQL、血缘）
30
- go run ./cmd/guancli ds get <resource_id> # 数据集详情（含字段结构、血缘）
31
- go run ./cmd/guancli ds get <resource_id> --brief # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
32
- go run ./cmd/guancli ds get <resource_id> --assoc # 附加显示关联关系摘要（ETL、融合等）
33
- go run ./cmd/guancli page get <resource_id> # 页面详情（含卡片列表、血缘）
29
+ guancli etl get <resource_id> # ETL 详情（含节点、SQL、血缘）
30
+ guancli ds get <resource_id> # 数据集详情（含字段结构、血缘）
31
+ guancli ds get <resource_id> --brief # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
32
+ guancli ds get <resource_id> --assoc # 附加显示关联关系摘要（ETL、融合等）
33
+ guancli page get <resource_id> # 页面详情（含卡片列表、血缘）
34
34
  ```
35
35
 
36
36
  **`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
@@ -66,5 +66,5 @@ go run ./cmd/guancli page get <resource_id> # 页面详情（含卡片
66
66
  密码登录方式会自动刷新。如果仍然失败，重新登录：
67
67
 
68
68
  ```bash
69
- go run ./cmd/guancli auth login
69
+ guancli auth login
70
70
  ```