@guandata/guancli 1.0.55 → 1.0.56

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guancli 1.0.56 - 2026-09-03
+
+- 指标查询默认按指标或查询列的格式配置展示数值，支持数值、货币、百分比、小数位、千分位、数量级和前后缀等格式。
+- 新增 `--value-format raw`，可在表格、JSON、CSV 和 Excel 等标准输出中保留原始数值，不与直接返回后端响应的 `--raw` 混用。
+- 登录和加载 Profile 时会校验 `base_url`，提前拦截 Windows 引号转义等问题造成的无效地址并给出明确错误。
+
 ## @guandata/guancli 1.0.55 - 2026-09-01
 
 - 新增 `analyze normalize/align/calculate/topn` 本地分析命令，支持 CSV/JSON 规范化、结果集对齐、安全四则运算、分组 TopN 与占比，并统一输出 `analysis/v1` 结构。

package/README.md

@@ -43,6 +43,12 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.56
+
+- 指标查询默认遵循指标或查询列的数值格式，覆盖货币、百分比、精度、千分位、数量级和前后缀。
+- 新增 `--value-format raw`，可在标准表格、JSON、CSV 和 Excel 输出中保留原始数值。
+- 登录和 Profile 加载会提前校验 BI 地址，减少 Windows 引号转义等配置问题造成的连接失败。
+
 ### @guandata/guancli 1.0.55
 
 - 新增本地 CSV/JSON 规范化、对齐、安全计算和分组 TopN 分析命令。

package/package.json

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

package/skills/guancli/SKILL.md

@@ -151,7 +151,7 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 - 复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树，并先加 `--dry-run --json-envelope`；dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件树节点使用 `combineType: AND|OR`，叶子使用 `field/operator/value|values`；`IN` 至少一个值，`BT` 恰好两个值。当前指标取数接口不能无损表达多分支 OR，真实执行会在取数前返回 `FILTER_OR_EXECUTION_UNSUPPORTED`，不得拆成多次聚合查询后拼接。失败时按稳定错误码修正，不猜错误文本。
 - 搜索并同时查看业务口径、数据集和适用维度等详情时，优先使用 `guancli metric search --fuzzy <keyword> --limit <N> --with-detail --brief -f json`，不要先 search 再逐个 get，也不要为终端阅读额外拼 jq。只查单个指标详情时优先使用 `guancli metric get <metric_id> --brief`；只裁剪指标查询结果列时使用 `metric query --columns`。可复制模板见 `references/metric-commands.md`。
 - 业务词不能直接命中指标时，候选发现必须遵守单批预算：一次性生成“原词 + 最多 4 个必要同义词/等价表达”，按 trim、空白归一化和大小写不敏感语义去重，保留原词在首位，然后只执行一次 `metric search --fuzzy`。不得把同义词拆成多次查询，不得通过调换顺序、改写等价词或查询子集重复搜索；如果单批无候选，立即结束本轮候选发现并说明已尝试关键词、搜索范围、无结果原因和 `stop_reason=no_candidate_within_budget`。后端最多接受 10 个模糊关键词，但 Agent 候选发现预算默认最多 5 个；不要缓存或跨请求复用“未找到指标”的结论。完整协议见 `references/metric-commands.md`。
-- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等；使用 `--json-envelope` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。未启用该参数的默认和 `-f json` 输出保持兼容。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
+- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等。数值默认按指标配置的 `format` 输出（查询响应有更具体的列级格式时优先），没有有效格式时才按 `--precision` 回退；需要标准表格/JSON/CSV/Excel 中保留原始数值时传 `--value-format raw`，不要和直接返回后端响应的全局 `--raw` 混淆。使用 `--json-envelope` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。未启用该参数的默认和 `-f json` 输出保持兼容。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
 - 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。需要同时查看每个命中指标的 `metric get` 详情时加 `--with-detail`；旧格式默认包含血缘，加 `--brief` 可跳过血缘。`--json-envelope` 不包含且不请求血缘，需要血缘时使用旧 `-f json`。此模式不兼容 `--raw`、CSV 和 Excel 输出，结果很多时先用 search 的 `--limit` 收窄指标数量。指标取数仍单独使用 `metric query`。
 - 回答指标搜索结果时，必须逐条说明“命中的指标”和“命中方式”：至少包含指标 ID、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
 - 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；如果已知指标主题，可加 `-d <metric_topic_id>` 缩小范围；需要结构化结果时用 `-f json`。
@@ -201,6 +201,18 @@ GUANCLI_DOWNLOAD_TIMEOUT=1200 guancli app download <appId>   # 大包/慢网络
 - 已知 caveat：`settings.json` 在远端是独立对象，如果经 app settings 接口改过，zip 里的那份可能仍是旧版本。
 - `-f` 只支持 `auto`（默认）和 `json`。
 
+## 请求转发路由
+
+请求转发能力通过 `gateway invoke` 调用 BI 网关，CLI 不会直接访问配置中的目标服务地址。当前 PAT 仅开放已配置路由的转发调用，路由管理和调试接口未开放，因此不提供 `route`、`debug` 等管理类子命令；路由需预先在 BI 中配置：
+
+```bash
+guancli gateway invoke orders --method GET --path 2026/detail --query tenant=cn
+```
+
+`invoke` 支持重复 `--query key=value`、`--header key=value`，以及互斥的 `--body` / `--body-file`。默认直接输出解析后的响应 JSON body；排查请求时增加 `--verbose`，可额外查看 `statusCode` 和脱敏后的 `headers`。`--raw` 只输出原始响应体。
+
+为避免覆盖 CLI 到 BI 的认证上下文，`Cookie`、`Authorization`、`token`、`X-Auth-Token`、`X-Personal-Token`、`x-dom-id` 和 `user-id` 等保留 Header 不能通过 `--header` 传入；目标服务鉴权应配置在路由模板或 Secret 中。
+
 ## 仪表板、卡片智能洞察
 
 ```bash

package/skills/guancli/references/metric-commands.md

@@ -215,7 +215,9 @@ guancli metric by-dataset <ds_id> --profile default --raw
 
 ### metric query
 
-查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。
+查询指标数据，支持维度、筛选、排序、列筛选和行数限制。默认按指标配置的 `format` 输出数值；查询响应携带更具体的列级格式时优先使用列级格式。泛化查询参数见 `metric-generic-query.md`。
+
+格式化覆盖数值、货币、百分比、高级格式，以及小数位、千分位、数量级单位、前后缀等配置。没有有效指标格式时才使用 `--precision` 回退。需要保留原始数值时使用 `--value-format raw`；它与全局 `--raw` 不同：前者仍输出标准表格/JSON/CSV/Excel，只是不应用数值展示格式，后者直接返回后端原始响应。
 
 非 `--raw` 输出会展示本次查询是否命中查询加速：summary 中有 `查询加速`，数据行中有 `_queryAccelerate`。命中时展示源指标 ID、加速指标 ID 和后端排序权重，例如 `metric_xxx->acc_xxx(优先级4)`；未命中时显示 `否`。若后端版本尚未返回查询加速 metadata，则显示 `未知: 后端未返回`。
 
@@ -247,7 +249,8 @@ guancli metric query <metric_id> [flags]
 | `--sort-asc string` | 无 | 按列升序排序，与 `--sort-desc` 互斥 |
 | `--sort-desc string` | 无 | 按列降序排序，与 `--sort-asc` 互斥 |
 | `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
-| `--precision int` | `6` | 数值最大小数位数；传 `-1` 保留原始精度 |
+| `--precision int` | `6` | 没有有效指标格式时的数值最大小数位数；传 `-1` 保留原始精度 |
+| `--value-format string` | `formatted` | `formatted` 按指标格式输出；`raw` 保留原始数值 |
 | `-o, --output string` | 无 | 将查询结果写入文件；未指定且结果超过 1000 行时自动写入文件 |
 
 `metric search/get/tree/query --json-envelope` 都返回带版本号的稳定 JSON envelope，当前 canonical 契约版本为 `1.0`，公共字段为 `schemaVersion`、`command`、`resultMode`、`rowCount`。内联结果在 `data`，文件结果在绝对 `path`；query 还返回 `columns`。版本演进读取响应体中的 `schemaVersion`，不会增加 `json-v2` 一类输出格式。原 `-f json` 保持旧版对象/数组结构，避免破坏 Decidex 等既有调用方。未指定 `-o/--output` 且查询结果超过 1000 行时，默认模式仍自动写 CSV 并输出原中文提示；启用 `--json-envelope` 时写 JSON 文件，stdout 返回 `resultMode=file` envelope。自动文件名带唯一后缀，避免同秒并发或重试覆盖已有结果。显式非 JSON `-f` 与 `--json-envelope` 不兼容。
@@ -279,6 +282,7 @@ guancli metric query <metric_id> --profile default --filter-file filters.json --
 guancli metric query <metric_id> --profile default --dim 省份 --sort-desc 订购数量
 guancli metric query <metric_id> --profile default --dim 省份 --columns "省份,订购数量"
 guancli metric query <metric_id> --profile default --dim 省份 -f csv
+guancli metric query <metric_id> --profile default --value-format raw -f json
 guancli metric query <metric_id> --profile default --dim 省份 --limit 10000 -f csv -o metric.csv
 guancli metric query <metric_id> --profile default --dim 省份 --raw
 ```