@guandata/guancli 1.0.63 → 1.0.65

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## @guandata/guancli 1.0.65 - 2026-10-12
+
+- 子表行更新前校验分页总数与行标识；读取不完整时停止操作，避免误删现有行。
+- 认证请求拒绝跨源重定向，防止 BI 凭据被转发到其他站点。
+- 平台包发布校验兼容 npm 12 的元数据格式。
+
+## @guandata/guancli 1.0.64 - 2026-10-12
+
+- 补齐请求转发 / API Gateway 的 CLI 支持与使用文档，支持通过观远 BI 调用外部接口。
+- `ds execute-sql -f json` 新增 `--typed` 选项，支持输出 `null` 和 JSON 数字。
+- 支持按主题读取指标目录树。
+- 修复 `etl get` 的上游刷新配置读取与展示，所有上游均开启时显示“全部开启”。
+- 优化 `npm link` 开发场景提示：缺少本地构建时，引导执行 `npm run build`。
+
 ## @guandata/guancli 1.0.63 - 2026-09-24
 
 - 指标查询新增 `--explain-requests -f json`，只读展示实际请求顺序与请求体，方便检查参数组合；不会执行取数。

package/README.md

@@ -45,6 +45,19 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.65
+
+- 子表行更新前校验分页总数与行标识；读取不完整时停止操作，避免误删现有行。
+- 认证请求拒绝跨源重定向，防止 BI 凭据被转发到其他站点。
+- 平台包发布校验兼容 npm 12 的元数据格式。
+
+### @guandata/guancli 1.0.64
+
+- 指标目录树支持 `-d / --dir-id <topic-id>`，只读取所选主题的目录树，保留原有权限和输出格式。
+- 新增请求转发路由的创建、查找、详情和调用命令；创建前可用 `--dry-run` 查看请求配置与访问范围。
+- `ds execute-sql -f json --typed` 可保留空值及数值类型；ETL 调度详情能正确识别全部上游更新后触发。
+- 从源码目录运行但尚未构建时，启动器会提示先执行 `npm run build`。
+
 ### @guandata/guancli 1.0.63
 
 - 指标查询新增 `--explain-requests -f json`，只读展示实际请求顺序与请求体，方便检查参数组合；不会执行取数。

package/bin/run.js

@@ -60,11 +60,24 @@ function resolvePlatformBinaries(options = {}) {
     // Local development fallback. The generated directory is excluded from
     // the published main package, so installed users always use the optional
     // platform dependency above.
-    const localBinDir = path.join(__dirname, "..", "platforms", target.suffix, "bin");
+    const pkgRoot = path.join(__dirname, "..");
+    const localBinDir = path.join(pkgRoot, "platforms", target.suffix, "bin");
     const binaryPaths = {};
     for (const binary of target.binaries) {
       const binaryPath = path.join(localBinDir, binary);
       if (!exists(binaryPath)) {
+        // scripts/ is not published, so this is a source checkout (npm link).
+        // npm link never installs the optional platform package; reinstalling
+        // from the registry would not help, the local build is missing.
+        if (exists(path.join(pkgRoot, "scripts", "build.js"))) {
+          throw new Error(
+            `Missing local build for ${key}: ${binaryPath}\n` +
+              `This ${PACKAGE_PREFIX} is a source checkout (npm link), which runs the ` +
+              `binaries built into platforms/ instead of the optional platform package.\n` +
+              `Build them first:\n` +
+              `  cd "${pkgRoot}" && npm run build`
+          );
+        }
         throw new Error(
           `Missing optional platform package ${target.packageName} for ${key}.\n` +
             `Reinstall without disabling optional dependencies:\n` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.63",
+  "version": "1.0.65",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
@@ -42,11 +42,11 @@
     "node": ">=14"
   },
   "optionalDependencies": {
-    "@guandata/guancli-darwin-arm64": "1.0.63",
-    "@guandata/guancli-darwin-x64": "1.0.63",
-    "@guandata/guancli-linux-x64": "1.0.63",
-    "@guandata/guancli-linux-arm64": "1.0.63",
-    "@guandata/guancli-win32-x64": "1.0.63"
+    "@guandata/guancli-darwin-arm64": "1.0.65",
+    "@guandata/guancli-darwin-x64": "1.0.65",
+    "@guandata/guancli-linux-x64": "1.0.65",
+    "@guandata/guancli-linux-arm64": "1.0.65",
+    "@guandata/guancli-win32-x64": "1.0.65"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或要对本地 CSV/JSON 做通用规范化、字段对齐、安全基础计算、分组 TopN/占比时，主动使用这个 skill。用户给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据，或要为已有仪表板/智能洞察卡片生成智能洞察结果时也触发。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”“发布 SuperApp”“下载 SuperApp 整包”时，也要使用这个 skill，并引导使用 `guancli app create` / `guancli app publish` / `guancli app download`。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或要对本地 CSV/JSON 做通用规范化、字段对齐、安全基础计算、分组 TopN/占比时，主动使用这个 skill。用户给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据，或要为已有仪表板/智能洞察卡片生成智能洞察结果时也触发。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”“发布 SuperApp”“下载 SuperApp 整包”，或要根据第三方接口文档创建、配置、调用“请求转发 / API Gateway”时，也要使用这个 skill。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。
 compatibility: Requires Node.js 14+. Install via npm install -g --foreground-scripts @guandata/guancli so the AI skill refresh result is visible.
 ---
 
@@ -19,6 +19,7 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
 - 用户要创建、发布或更新超级应用 / SuperApp，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户给出第三方接口文档，希望转换成观远 BI 请求转发配置、创建路由或生成调用代码。
 - 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
 - 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
 - 用户已经取得本地 CSV/JSON，需要稳定处理 BOM/null/嵌套字段、对齐两个结果集、执行安全四则运算，或做通用分组 TopN/占比；不再临时生成 Python 拼接脚本。
@@ -66,6 +67,7 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 | Form CRUD、子表、ChatBI 主题问数/洞察 | `references/form-chatbi.md` |
 | 指标与指标树全量命令 | `references/metric-commands.md` |
 | 指标泛化查询参数与示例 | `references/metric-generic-query.md` |
+| 请求转发配置生成、创建、调用与安全边界 | `references/gateway.md` |
 | 指标 query 参数模式、互斥矩阵与真实请求体 | `references/metric-query-recipes.md` |
 | 本地 CSV/JSON 规范化、对齐、基础计算、TopN | `references/analysis-primitives.md` |
 
@@ -217,13 +219,33 @@ GUANCLI_DOWNLOAD_TIMEOUT=1200 guancli app download <appId>   # 大包/慢网络
 
 ## 请求转发路由
 
-请求转发能力通过 `gateway invoke` 调用 BI 网关，CLI 不会直接访问配置中的目标服务地址。当前 PAT 仅开放已配置路由的转发调用，路由管理和调试接口未开放，因此不提供 `route`、`debug` 等管理类子命令；路由需预先在 BI 中配置：
+创建请求转发、查找已有路由或生成 SuperApp 调用代码时，先读 `references/gateway.md`。创建主流程是：整理配置草案 → 用户确认敏感数据引用、权限范围和启用状态 → `--dry-run` → 真实创建。不要把真实 token、密码、AK/SK 或 client secret 写入配置文件或对话；只引用 BI 中已保存的 `${SECRET.xxx}`。
+
+```bash
+guancli gateway create gateway.json --dry-run
+guancli gateway create gateway.json
+```
+
+创建接口要求当前用户拥有请求转发 `UPDATE` 权限，环境还需开通超级应用商业授权。`--dry-run` 只验证本地 JSON 结构并展示请求，不证明权限、授权或服务端创建一定成功。
+
+用户用自然语言描述要调用的业务接口、但不知道识别符时，先用业务名或系统名搜索，再读取候选路由的稳定调用契约：
+
+```bash
+guancli gateway search CRM --enabled
+guancli gateway get 42
+```
+
+`search` 只按名称或识别符匹配，返回当前分页；无结果时可缩短关键词或省略关键词，不能把单页结果当作全量。多个候选无法可靠区分时，向用户确认，不要猜路由。`get` 默认输出脱敏后的 v1.0 调用契约，包括 BI 网关路径、方法、追加路径、Query/Header/Body 映射、访问约束、文档说明和调用示例；不得根据 `--raw` 中的目标 URL 生成应用代码。
+
+生成代码前检查 `enabled`、`gatewayMethod`、`loginRequired`、允许用户/用户组、`allowedCallerHosts` 和所有 `required` 入参。POST 路由即使 `bodyRequired=false` 也必须保留可选的透传 body 支持；该字段只决定是否强制要求 body。响应解析必须保留上游类型：空的 204/205 返回 `null`，再按 Content-Type 选择 `json()`、`text()` 或 `blob()`，不得固定执行 `response.json()`。代码只能访问 `gatewayPath` / `gatewayUrlTemplate` 指向的 BI 网关。路由未启用、方法不匹配、来源不允许或必填参数缺失时，明确指出修复动作，不能改为直连第三方地址。
+
+需要实际调试已有路由时使用 `gateway invoke`：
 
 ```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` 只输出原始响应体。
+`invoke` 支持重复 `--query key=value`、`--header key=value`，以及互斥的 `--body` / `--body-file`。默认直接输出解析后的响应 JSON body；排查请求时增加 `--verbose`，可额外查看 `statusCode` 和脱敏后的 `headers`。`--raw` 只输出原始响应体。非 2xx 响应会先完成上述输出，再返回错误并使进程退出码非零；脚本既要保留输出用于诊断，也必须检查退出码。
 
 为避免覆盖 CLI 到 BI 的认证上下文，`Cookie`、`Authorization`、`token`、`X-Auth-Token`、`X-Personal-Token`、`x-dom-id` 和 `user-id` 等保留 Header 不能通过 `--header` 传入；目标服务鉴权应配置在路由模板或 Secret 中。
 

package/skills/guancli/references/form-chatbi.md

@@ -152,6 +152,7 @@ guancli form delete <subFmId> <subId>
 **注意**：
 - 子表 add 内部通过主表 update API 间接完成（后端限制），CLI 自动保留已有子行
 - add 会分页读取已有子行并通过主表 update 全量回写以保留已有行；非并发安全
+- 旧子行查询必须包含有效 `data` 数组、`count` 总数和行标识；缺失、分页不完整或总数变化时停止，不提交全量替换。协议依据为 SurveyEngine `d4f37aca` 的 `DataController.get` / `DataService.getSubData`，短页本身不能证明读取完成。
 - `--stdin` 批量插入部分失败时 CLI 返回非零退出码，summary 中显示成功/失败计数
 
 ### 典型工作流

package/skills/guancli/references/gateway.md

@@ -0,0 +1,148 @@
+# 请求转发创建与调用辅助
+
+用于把第三方或客户内部接口文档转换为观远 BI 请求转发配置，并通过 `guancli gateway create` 创建。产品语义以[请求转发 / API Gateway](https://docs.guandata.com/product/bi/api-gateway)为准。
+
+## 从接口文档生成配置
+
+先提取并向用户展示配置草案，至少标明每项来自文档的哪一段：
+
+- 目标方法、URL、超时时间。
+- Header、Query、Body 入参及必填性。
+- 鉴权方式；需要登录或换 token 时转成前置请求。
+- 前置响应 JSONPath 与主请求 `${PRE_REQ.xxx}` 引用。
+- 网关入口方法、路由识别符、登录要求、用户/用户组、调用方 Host 和日志脱敏 Header。
+- 文档地址与调用说明 `usageMarkdown`。
+
+不确定的权限范围、Host 白名单、Secret key 和启用状态必须列为待确认项。不要猜用户 ID、用户组 ID 或把凭据明文放入 JSON。用户确认后再生成配置文件。
+
+## JSON 契约
+
+```json
+{
+  "basicInfo": {
+    "name": "CRM 查询用户",
+    "routes": "crm-query-user",
+    "gatewayMethod": "GET",
+    "targetMethod": "GET",
+    "documentUrl": "https://docs.example.com/crm/users",
+    "usageMarkdown": "Query: keyword；返回 CRM 用户列表。",
+    "enabled": true,
+    "loginRequired": true,
+    "allowedUsers": [{"id": "user-id"}],
+    "allowedUserGroups": [{"id": "group-id"}],
+    "targetUrl": "https://crm.example.com/api/users",
+    "allowedCallerHosts": ["app.example.com"],
+    "maskHeaders": ["Authorization", "Cookie", "X-Auth-Token"]
+  },
+  "config": {
+    "request": {
+      "timeoutSeconds": 120,
+      "headers": [
+        {
+          "paramName": "Authorization",
+          "paramValueOrExpr": "Bearer ${PRE_REQ.accessToken}",
+          "paramDescription": "前置登录返回的 token"
+        }
+      ],
+      "query": [
+        {
+          "paramName": "keyword",
+          "paramValueOrExpr": "${REQUEST.query.keyword}",
+          "paramDescription": "搜索关键词"
+        }
+      ]
+    },
+    "preRequestList": [
+      {
+        "name": "获取 CRM Token",
+        "requestMethod": "POST",
+        "url": "https://crm.example.com/oauth/token",
+        "timeoutSeconds": 30,
+        "documentUrl": "https://docs.example.com/crm/auth",
+        "headers": [{"paramName": "Content-Type", "paramValueOrExpr": "application/json"}],
+        "query": [],
+        "body": "{\"clientId\":\"${SECRET.crm_client_id}\",\"clientSecret\":\"${SECRET.crm_client_secret}\"}",
+        "responseExtractors": [{"name": "accessToken", "jsonPath": "$.accessToken"}]
+      }
+    ]
+  }
+}
+```
+
+规则：
+
+- `routes` 只能包含字母、数字和中划线；创建后不要修改识别符。
+- `gatewayMethod` 只支持 `GET`、`POST`；`targetMethod` 支持 `GET`、`POST`、`PUT`、`DELETE`、`PATCH`。
+- 主请求及前置请求超时为 1–300 秒。
+- `allowedUsers`、`allowedUserGroups` 传资源 ID，不传名称代替 ID。登录开启但两者为空时，所有已登录用户可访问。
+- Header 和 Query 只有显式配置的参数才转发；Body 由调用方整体透传并执行占位符替换。
+- Header 和 Query 配置通过 `required: true|false` 保留原接口的必填性；省略时按可选处理。`gateway get` 只对必填入参生成缺失检查，可选 Query/Header 未传时不会被序列化为 `undefined`。
+- CLI 会在输出 dry-run 计划前检查 Header、Query、前置请求 Body、目标/前置请求 URL 的 query 与 userinfo。`Authorization`、`token`、`password`、`AK/SK`、`API Key`、`client secret` 等敏感参数只能由 `${SECRET.xxx}` 或 `${PRE_REQ.xxx}` 服务端引用组成；明文及 `${REQUEST.xxx}` 会被拒绝，且不会回显配置。自定义 Header 固定值默认拒绝；只有确认为公开非凭据值时才在该参数上显式设置 `allowPlaintext: true`，例如 `X-API-Version: 2026-09`、`X-Client-Type: superapp`、`Prefer: return=representation`。敏感 Header 名或 Bearer/Basic/API-key/JWT 等凭据形式不允许用 `allowPlaintext` 绕过。`allowPlaintext` 只是 CLI 本地确认字段，dry-run 的 `request` 和真实 POST body 都会在提交投影中剔除它，两者保持一致。
+- JSON Body 任意层级出现重复字段时会在 dry-run 和真实创建前直接拒绝，避免校验器只检查最后一个值、却把未规范化的原始 Body 提交给 BI。
+- `enabled`、`loginRequired` 省略时服务端默认 `true`，配置草案中仍应显式写出，便于用户确认。
+
+常用占位符：`${REQUEST.path.n}`、`${REQUEST.query.xxx}`、`${REQUEST.header.xxx}`、`${REQUEST.body.xxx}`、`${CURRENT_USER.xxx}`、`${PRE_REQ.xxx}`、`${SECRET.xxx}`、`${SYSTEM.xxx}`。
+
+## 创建流程
+
+```bash
+guancli auth status
+guancli gateway create ./gateway.json --dry-run
+guancli gateway create ./gateway.json
+```
+
+先检查 dry-run 输出中的目标地址、权限、Secret key、参数映射和 `enabled`。真实创建是外部写操作；只有用户确认草案后才执行。dry-run 计划和创建结果均使用 `schemaVersion: "1.0"`；创建成功返回 `id`、`name`、`routeCode`、`gatewayPath` 和 `enabled`。
+
+服务端仍会最终校验权限、商业授权、路由重名、用户/用户组、Secret 与配置合法性。创建端点为 `POST /api/gateway/manage/routes`，权限资源为 `GATEWAY_ROUTE.UPDATE`；自 2026-09-01 起还需要超级应用商业授权。
+
+## 查找路由并读取调用契约
+
+当用户只给出自然语言需求（例如“调用 CRM 查询客户信息接口”），不要要求用户预先提供识别符，也不要从创建文件或历史对话猜测：
+
+```bash
+guancli gateway search CRM --enabled --limit 20
+guancli gateway get 42
+```
+
+- `search [keyword]` 调用 `POST /api/gateway/manage/routes/query`，关键词由服务端匹配名称或识别符；支持 `--enabled=true|false`、`--offset`、`--limit`。输出为 `schemaVersion: "1.0"` 的脱敏摘要，包含路由 ID、名称、识别符、BI 网关路径、方法、启用状态、访问约束、文档地址和业务说明。
+- 查询结果只代表当前分页。`total` 大于 `items` 数量时仍有后续页；无候选时缩短关键词或省略关键词继续查询。多个候选的名称、说明和方法不足以唯一判断时，列出候选并请用户确认。
+- `get <id>` 调用 `GET /api/gateway/manage/routes/{id}`，默认把后端详情投影成 `schemaVersion: "1.0"` 的稳定调用契约：`gatewayUrlTemplate`、网关方法、追加路径占位符、Query/Header/Body 输入映射、是否必填、访问约束、原始文档/业务说明、CLI 与 SuperApp 示例。
+- 默认输出不包含第三方目标 URL、前置请求 URL 或 `${SECRET.xxx}` 引用。`--raw` 只用于管理员诊断，会原样显示后端详情；不要把 raw 输出放进对话、日志或 SuperApp 代码。
+
+管理查询需要 `GATEWAY_ROUTE.READ`。使用 PAT 时，还需 BI 环境已提供“请求转发”权限点，并在创建 PAT 时选择对应的 `read` / `update` 权限；已有 PAT 不会自动增加新权限。CLI 的本地契约测试只能验证请求构造和字段投影；最终权限、资源存在性和当前配置仍由 BI 服务端裁决。
+
+## 生成 SuperApp 调用
+
+必须先以 `gateway get` 的返回值为事实源。生成前逐项检查：
+
+- `route.enabled` 必须为 `true`；否则提示管理员启用。
+- 调用方法必须等于 `invocation.method`，不可用目标请求方法代替网关请求方法。
+- 按 `appendPathPlaceholders` 顺序追加并 URL 编码路径；`${REQUEST.path.1}` 对应第一段。若配置引用 `${REQUEST.path.3}`，前两段也必须提供，即使第二段没有被目标模板直接引用。
+- 为所有 `inputMappings[].required=true` 的 Query、Header、Body 输入组装值；缺少时在调用前报出具体参数名。
+- POST 路由的 `bodyMode=passthrough` 表示调用方提供请求体时应原样透传；`bodyRequired=false` 只表示请求体可省略，不得据此从生成代码中删除 body 支持。字符串请求体直接发送，对象请求体再做 JSON 序列化。
+- 响应保持上游语义：204/205 返回 `null`；JSON Content-Type（`application/json` 或 `+json`）调用 `json()`；文本、XML、JavaScript 和表单响应调用 `text()`；其余文件或二进制响应调用 `blob()`。不得无条件执行 `response.json()`。
+- `loginRequired`、`allowedUsers`、`allowedUserGroups` 和 `allowedCallerHosts` 是访问约束。当前用户或来源不满足时提示申请权限或调整白名单。
+- 代码只调用 `/api/gateway/routes/{routeCode}`，不得出现目标服务 URL、前置请求 URL 或敏感凭据。
+
+示例：
+
+```js
+const response = await fetch(
+  `/api/gateway/routes/crm-query-user?keyword=${encodeURIComponent(keyword)}`,
+  { method: "GET", credentials: "include" },
+);
+if (!response.ok) {
+  throw new Error(`请求转发调用失败：${response.status}`);
+}
+const data = await response.json();
+```
+
+追加路径按顺序映射为 `${REQUEST.path.1}`、`${REQUEST.path.2}`。CLI 调试调用示例：
+
+```bash
+guancli gateway invoke crm-query-user --method GET --query keyword=张三 --verbose
+```
+
+出现未授权、路由停用、方法不匹配或参数缺失时，结合返回状态和错误体说明具体修复动作，不要改为绕过网关直连目标服务。
+
+`gateway invoke` 无论成功或失败都会先输出目标响应体；`--verbose` 还会输出状态码和脱敏响应头。HTTP 4xx/5xx 等非 2xx 响应在完成输出后返回错误，进程退出码非零，脚本必须同时保留输出并检查退出码。

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

@@ -367,7 +367,7 @@ CLI 会把条件树确定性展开为“组内 AND、组间 OR”的查询计划
 
 ### metric tree
 
-获取指标目录树。默认输出树形结构，最外层展示指标主题。
+获取指标目录树。默认输出树形结构，最外层展示指标主题。`-d / --dir-id <topic-id>` 仅读取所选主题的目录树：保留原主题列表的权限过滤和原始输出形状，不读取其他主题的目录树；主题不存在或不在当前身份的主题列表中时返回空结果。
 
 ```bash
 guancli metric tree [flags]
@@ -380,6 +380,7 @@ guancli metric tree --profile default
 guancli metric tree --profile default --brief
 guancli metric tree --profile default -f json
 guancli metric tree --profile default --raw
+guancli metric tree -d <topic-id> --profile default --raw
 ```
 
 > 指标创建、编辑、删除、指标主题/目录创建、公共维度管理、Excel 标准化已迁移到 `guanmetric`。

package/skills/guancli/references/preview-and-output.md

@@ -13,6 +13,8 @@ guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读
 `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
 ```
 
+程序比对结果时用 `-f json --typed`：NULL 输出 `null`，数值列（按后端 `columns[].fdType`）输出 JSON 数字（原样保留后端的数字文本，长整数和小数位不丢）。不加 `--typed` 的 `-f json` 保持旧格式：所有值都是字符串、NULL 为空串 `""`，分不清 NULL、空串与数字。
+
 `--sql` 与 `--sql-file` 二选一。SQL 较长、包含多层引号或由模型生成时，优先写入 `.sql` 文件再传 `--sql-file`；传 `--sql-file -` 时从 stdin 读取，不会把终端中的普通空输入当作 SQL。
 
 数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。