@guandata/guancli 1.0.40 → 1.0.42

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 (15) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +13 -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/SKILL.md +2 -0
  12. package/skills/guancli/references/auth-and-config.md +11 -11
  13. package/skills/guancli/references/form-chatbi.md +38 -38
  14. package/skills/guancli/references/preview-and-output.md +22 -22
  15. package/skills/guancli/references/resource-query.md +17 -17
package/CHANGELOG.md CHANGED
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## @guandata/guancli 1.0.42 - 2026-07-20
4
+
5
+ - 密码登录环境执行连接或认证状态检查时，token 过期或失效会自动重新登录并再次验证，减少 Agent 因会话过期而中断。
6
+ - 状态输出会明确区分自动恢复成功、凭证失效和暂时无法验证，便于快速判断下一步处理方式。
7
+
8
+ ## @guandata/guancli 1.0.41 - 2026-07-20
9
+
10
+ - 增强复杂报表 Pro 子卡片的元数据读取与筛选支持，复杂报表分析结果更完整。
11
+ - 精简页面、数据集和 ETL 的可读输出，便于 Agent 直接定位关键信息。
12
+ - 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。
13
+
3
14
  ## @guandata/guancli 1.0.40 - 2026-07-15
4
15
 
5
16
  - 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
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,17 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
39
41
 
40
42
  ## 版本更新
41
43
 
44
+ ### @guandata/guancli 1.0.42
45
+
46
+ - 密码登录环境执行连接或认证状态检查时，token 过期或失效会自动重新登录并再次验证，减少 Agent 因会话过期而中断。
47
+ - 状态输出会明确区分自动恢复成功、凭证失效和暂时无法验证，便于快速判断下一步处理方式。
48
+
49
+ ### @guandata/guancli 1.0.41
50
+
51
+ - 增强复杂报表 Pro 子卡片的元数据读取与筛选支持，复杂报表分析结果更完整。
52
+ - 精简页面、数据集和 ETL 的可读输出，便于 Agent 直接定位关键信息。
53
+ - 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。
54
+
42
55
  ### @guandata/guancli 1.0.40
43
56
 
44
57
  - 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
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.40",
3
+ "version": "1.0.42",
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/SKILL.md CHANGED
@@ -35,6 +35,8 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
35
35
 
36
36
  > guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
37
37
 
38
+ **编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须路由到对应专用 skill 的**原地更新**能力；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
39
+
38
40
  ## 先做判断
39
41
 
40
42
  1. 先用 `auth status` 确认认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
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,16 +38,16 @@ 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 "主键字段=当前主键值" --set "字段名=新值"
49
+ guancli form update <fmId> <rowId> --data '{"主键字段": "当前主键值", "字段名": "新值"}'
50
+ guancli form update <fmId> <rowId> --set "主键字段=当前主键值" --set "字段名=新值"
51
51
  ```
52
52
 
53
53
  `rowId` 和未编辑主键的当前值通过 `form query` 获取。更新载荷必须包含表单配置的全部业务主键字段（内置
@@ -56,9 +56,9 @@ go run ./cmd/guancli form update <fmId> <rowId> --set "主键字段=当前主键
56
56
  ### 删除数据
57
57
 
58
58
  ```bash
59
- go run ./cmd/guancli form delete <fmId> <rowId> # 删除单行
60
- go run ./cmd/guancli form delete <fmId> <rowId1> <rowId2> # 删除多行
61
- 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 # 删除全部（需确认）
62
62
  ```
63
63
 
64
64
  ### 子表操作
@@ -67,23 +67,23 @@ go run ./cmd/guancli form delete <fmId> --all --yes # 删除全部
67
67
 
68
68
  ```bash
69
69
  # 1. 查看主表 schema，找到 TABLE 字段的 subFmId
70
- go run ./cmd/guancli form schema <mainFmId>
70
+ guancli form schema <mainFmId>
71
71
  # 输出中 TABLE 字段的备注列显示 "子表 subFmId=..."
72
72
 
73
73
  # 2. 查看子表字段结构
74
- go run ./cmd/guancli form schema <subFmId>
74
+ guancli form schema <subFmId>
75
75
 
76
76
  # 3. 查询子表数据（返回结果包含主表字段，rowId 为主表行 ID，subId 为子行 ID）
77
- go run ./cmd/guancli form query <subFmId>
77
+ guancli form query <subFmId>
78
78
 
79
79
  # 4. 向子表插入行（需指定主表行的 rowId）
80
- go run ./cmd/guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
80
+ guancli form add <subFmId> --parent-row <主表rowId> --set "字段名=值"
81
81
 
82
82
  # 5. 更新子表行（使用 subId 作为 rowId）
83
- go run ./cmd/guancli form update <subFmId> <subId> --set "字段名=新值"
83
+ guancli form update <subFmId> <subId> --set "字段名=新值"
84
84
 
85
85
  # 6. 删除子表行
86
- go run ./cmd/guancli form delete <subFmId> <subId>
86
+ guancli form delete <subFmId> <subId>
87
87
  ```
88
88
 
89
89
  **子表 ID 映射规则**（AI 调用时注意区分）：
@@ -105,22 +105,22 @@ go run ./cmd/guancli form delete <subFmId> <subId>
105
105
 
106
106
  ```bash
107
107
  # 1. 找到表单
108
- go run ./cmd/guancli form list 测试
108
+ guancli form list 测试
109
109
 
110
110
  # 2. 查看结构
111
- go run ./cmd/guancli form schema <fmId>
111
+ guancli form schema <fmId>
112
112
 
113
113
  # 3. 插入数据
114
- go run ./cmd/guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
114
+ guancli form add <fmId> --data '{"测试1": "hello", "值": 42}'
115
115
 
116
116
  # 4. 查询并获取 rowId
117
- go run ./cmd/guancli form query <fmId> -f json
117
+ guancli form query <fmId> -f json
118
118
 
119
119
  # 5. 更新（同时携带业务主键）
120
- go run ./cmd/guancli form update <fmId> <rowId> --set "名称=当前名称" --set "值=99"
120
+ guancli form update <fmId> <rowId> --set "名称=当前名称" --set "值=99"
121
121
 
122
122
  # 6. 删除
123
- go run ./cmd/guancli form delete <fmId> <rowId>
123
+ guancli form delete <fmId> <rowId>
124
124
  ```
125
125
 
126
126
  ## 7. ChatBI 主题问数 / 洞察
@@ -128,12 +128,12 @@ go run ./cmd/guancli form delete <fmId> <rowId>
128
128
  先列主题，再执行问数或洞察；如果用户没有指定主题，不要猜。
129
129
 
130
130
  ```bash
131
- go run ./cmd/guancli chatbi list-theme
132
- go run ./cmd/guancli chatbi list-theme --insight
133
- go run ./cmd/guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
134
- go run ./cmd/guancli chatbi query --theme-id "<theme_id>" --message "最近30天营业收入是多少？"
135
- go run ./cmd/guancli chatbi insight --theme-name "经营主题" --message "分析最近30天营业收入变化原因"
136
- 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
137
137
  ```
138
138
 
139
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。
@@ -149,18 +149,18 @@ guancli card preview <cd_id> --dynamic-field "dz_region:city_key"
149
149
  `--format` / `-f` 控制 preview 命令的输出格式：
150
150
 
151
151
  ```bash
152
- go run ./cmd/guancli ds preview <ds_id> # auto: 对齐表格，列>10 或行>20 时自动截断
153
- go run ./cmd/guancli ds preview <ds_id> -f csv # CSV 格式
154
- go run ./cmd/guancli ds preview <ds_id> -f excel # Excel 2003 XML 格式
155
- go run ./cmd/guancli ds preview <ds_id> -f expanded # PG 风格竖排
156
- go run ./cmd/guancli ds preview <ds_id> -f table # 对齐表格
157
- go run ./cmd/guancli ds preview <ds_id> -f json # JSON 行记录数组
158
- 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
159
159
  ```
160
160
 
161
161
  `--raw` 输出 API 原始 JSON（不经过解析）：
162
162
 
163
163
  ```bash
164
- go run ./cmd/guancli --raw etl tree
165
- go run ./cmd/guancli --raw etl get <id>
164
+ guancli --raw etl tree
165
+ guancli --raw etl get <id>
166
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
  ```