@guandata/guancli 1.0.29 → 1.0.31

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guancli 1.0.31 - 2026-06-03
+
+- `card preview` 会按卡片值格式设置输出展示值，支持小数位、百分比、千分位、前后缀等常见格式。
+- `card preview` 保留 raw 原始值，避免展示格式影响排序、Excel/JSON 输出或后续处理。
+- `ds execute-sql` 能力要求提示更清晰；认证请求默认不再额外发送 `X-AUTH-TOKEN`，提升部分环境兼容性。
+- `install-skill` 增加 WorkBuddy skill 安装路径支持。
+
+## @guandata/guancli 1.0.30 - 2026-05-29
+
+- `card preview --dynamic-field` 支持当前卡片自身的多选动态维度覆盖，可用逗号分隔字段或重复传参合并。
+- `card preview` 动态维度参数校验与输出诊断增强，便于确认实际预览使用的动态维度选择。
+- 简版资源详情减少非必要血缘明细加载，提升资源信息查询速度和稳定性。
+
 ## @guandata/guancli 1.0.29 - 2026-05-28
 
 - `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
@@ -9,8 +22,8 @@
 
 ## @guandata/guancli 1.0.28 - 2026-05-26
 
-- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。
-- 增强动态字段配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
+- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态维度选择。
+- 增强动态维度配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
 - 卡片信息输出补充动态参数相关摘要，便于排查筛选器和图表联动配置。
 
 ## @guandata/guancli 1.0.27 - 2026-05-26

package/README.md

@@ -23,7 +23,7 @@ guancli etl tree
 guancli etl get <resource_id>
 guancli ds search <keyword>
 guancli ds preview <ds_id>
-guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 需目标 BI 支持该接口并开启高级 SQL 查询
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' -f json
 guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' --raw
 # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。
@@ -38,6 +38,19 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.31
+
+- `card preview` 会按卡片值格式设置输出展示值，支持小数位、百分比、千分位、前后缀等常见格式。
+- `card preview` 保留 raw 原始值，避免展示格式影响排序、Excel/JSON 输出或后续处理。
+- `ds execute-sql` 能力要求提示更清晰；认证请求默认不再额外发送 `X-AUTH-TOKEN`，提升部分环境兼容性。
+- `install-skill` 增加 WorkBuddy skill 安装路径支持。
+
+### 1.0.30
+
+- `card preview --dynamic-field` 支持当前卡片自身的多选动态维度覆盖，可用逗号分隔字段或重复传参合并。
+- `card preview` 动态维度参数校验与输出诊断增强，便于确认实际预览使用的动态维度选择。
+- 简版资源详情减少非必要血缘明细加载，提升资源信息查询速度和稳定性。
+
 ### 1.0.29
 
 - `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
@@ -47,8 +60,8 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ### 1.0.28
 
-- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态字段选择。
-- 增强动态字段配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
+- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态维度选择。
+- 增强动态维度配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
 - 卡片信息输出补充动态参数相关摘要，便于排查筛选器和图表联动配置。
 
 ### 1.0.27

package/bin/run.js

@@ -5,6 +5,7 @@
 const { execFileSync, execSync, spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
+const os = require("os");
 
 const PLATFORM_MAP = {
   "darwin-arm64": "guancli-darwin-arm64",
@@ -35,6 +36,38 @@ function getBinaryPath() {
   return binaryPath;
 }
 
+function copyDirectory(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      fs.symlinkSync(fs.readlinkSync(srcPath), destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installCodeBuddySkill(pkgRoot, skill) {
+  try {
+    const srcDir = path.join(pkgRoot, "skills", skill);
+    if (!fs.existsSync(path.join(srcDir, "SKILL.md"))) {
+      console.warn(`Warning: skipping CodeBuddy/WorkBuddy install; skill not found: ${srcDir}`);
+      return;
+    }
+
+    const configDir = process.env.CODEBUDDY_CONFIG_DIR || path.join(os.homedir(), ".codebuddy");
+    const destDir = path.join(configDir, "skills", skill);
+    copyDirectory(srcDir, destDir);
+    console.log(`Installed ${skill} to CodeBuddy/WorkBuddy: ${destDir}`);
+  } catch (err) {
+    console.warn(`Warning: CodeBuddy/WorkBuddy install failed for ${skill}: ${err.message}`);
+  }
+}
+
 if (process.argv[2] === "version" && process.argv.length === 3) {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
   console.log(pkg.version);
@@ -57,7 +90,9 @@ if (process.argv[2] === "install-skill") {
   console.log("Installing guancli to AI coding assistants...");
   const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
   if (result.error) throw result.error;
-  process.exit(result.status || 0);
+  const status = result.status || 0;
+  if (status === 0) installCodeBuddySkill(pkgRoot, "guancli");
+  process.exit(status);
 }
 
 const binary = getBinaryPath();

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
   },
+  "scripts": {
+    "build": "node scripts/build.js && node scripts/sync-skill.js",
+    "changelog": "node ../../scripts/generate-release-changelog.js .",
+    "check-changelog": "node ../../scripts/check-release-changelog.js .",
+    "prepublishOnly": "npm run check-changelog && npm run build && node scripts/preflight.js"
+  },
   "files": [
     "bin/",
     "binaries/",
@@ -29,6 +35,7 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   }
 }

package/skills/guancli/SKILL.md

@@ -153,7 +153,7 @@ guancli page get <resource_id>         # 页面详情（含卡片列表、血缘
 guancli ds preview <ds_id>              # 预览数据集数据 (表格格式)
 guancli ds preview <ds_id> --limit 20   # 限制预览行数
 guancli ds preview <ds_id> --raw        # 输出原始 JSON
-guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 用 SQL 查询数据集（需目标 BI 支持该接口并开启高级 SQL 查询）
+guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 用 SQL 查询数据集（需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
 # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
 `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
 ```
@@ -234,12 +234,13 @@ guancli card preview <cd_id> --limit 20 # 限制预览行数
 guancli card preview <cd_id> -f csv     # 导出 CSV 到 stdout
 guancli card preview <cd_id> -f csv -o card.csv # 导出 CSV 到文件
 guancli card preview <cd_id> -f excel -o card.xls # 导出 Excel 可打开文件
+guancli card preview <cd_id> --value-format raw -f csv # 保留原始数值，适合 AI 后续计算
 ```
 
 卡片 ID (cdId) 可通过 `page get` 命令查看页面详情获取。
-图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
+图表卡片内部会按 BI 预览接口的分页能力自动取数；选择器/树状选择器仍使用服务端单次返回。图表卡片数值默认使用 `--value-format formatted`，按卡片返回的数值格式输出（小数位、千分位、货币、百分比、单位等）；需要保留原始数值用于 AI 后续计算时，使用 `--value-format raw`。无卡片格式时 `--precision` 作为兜底最大精度，默认 6 位。任意卡片预览结果在未指定 `-o/--output` 且超过 1000 行时，默认写入 `card_<cdId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。该能力不对接 BI 导出任务接口。
 
-复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、动态参数和动态字段。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
+复杂报表 Pro 卡片会自动切换为 xlsx 下载模式，只支持写入文件，不支持 `--raw`、`-f/--format`、`--limit`、排序、列筛选、精度、数值输出格式、动态参数和动态维度。未指定 `-o/--output` 时默认写入 `complex_report_pro_<cdId>_<timestamp>.xlsx`。
 
 #### 带筛选条件预览卡片
 
@@ -269,6 +270,25 @@ guancli card preview <cd_id> --dynamic-param "品类=鞋,服,包"
 guancli card preview <cd_id> --dynamic-param "DATE_RANGE_PARAM_LEFT=2026-05-01" --dynamic-param "DATE_RANGE_PARAM_RIGHT={{{today}}}"
 ```
 
+#### 带动态维度预览图表卡片
+
+图表卡片 preview 支持通过 `--dynamic-field` 覆盖当前卡片自身的动态维度选择；参数名沿用历史/API 命名，语义上表示动态维度。
+格式为 `动态维度名=字段名`、`dzId=fdId`、`dzId=key`，也兼容旧写法 `dzId:key`。
+动态维度名、dzId、字段名、fdId、key 先用 `card get <cd_id>` 查看；如果动态维度没有配置名称，只能使用 dzId。
+单选动态维度只能指定一个字段；`multiSelect: true` 的动态维度可用英文逗号传多个字段，或重复指定同一个动态维度，CLI 会合并去重。
+字段名本身包含英文逗号时，CLI 会优先按完整字段名匹配；也可用 CSV 引号写法，例如 `"维度=\"门店,二店\""`。
+该能力仅支持当前卡片自身的动态维度，不支持带 `sourceDzIds` 的来源动态维度；参数只影响本次运行态取数，不修改卡片配置。
+
+```bash
+guancli card get <cd_id> # 查看动态维度配置、dzId、可选字段、fdId、key
+guancli card preview <cd_id> --dynamic-field "维度=区域"
+guancli card preview <cd_id> --dynamic-field "维度=区域,门店" --dynamic-field "数值=销售额,利润"
+guancli card preview <cd_id> --dynamic-field "维度=区域" --dynamic-field "维度=门店"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_fd,city_fd"
+guancli card preview <cd_id> --dynamic-field "dz_region=province_key,city_key"
+guancli card preview <cd_id> --dynamic-field "dz_region:city_key"
+```
+
 ### 6. 表单填报操作 (Form CRUD)
 
 类似 Airtable 风格的表单数据 CRUD，用户始终用**字段名**操作，CLI 内部自动映射到 fdId。