@guandata/guancli 1.0.51 → 1.0.53

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## @guandata/guancli 1.0.53 - 2026-08-25
+
+- 新增 OIDC 登录与安全凭据管理，提升企业统一身份认证、多环境切换和登录状态恢复的稳定性。
+- SuperApp 支持列出应用和整包下载；创建应用时可识别重名资源并给出可继续处理的信息。
+- `ds execute-sql` 支持从文件或标准输入读取多行 SQL，并完整保留后端 SQL 解析错误，复杂查询更易编写和排查。
+- 改进下载原子写入、超时和服务端错误解析，避免失败下载留下不完整文件。
+- 自动关联卡片可继承筛选条件，卡片预览和联动结果更符合页面实际配置。
+
+## @guandata/guancli 1.0.52 - 2026-08-20
+
+- 新增资源全局搜索与资源 URL 获取能力，便于快速定位并访问 BI 资源。
+- `metric search` 支持返回指标详情，并优化查询加速命中优先级说明、兼容性探测及请求预算控制。
+- 修复 `form query --filter` 被忽略及多类筛选条件误切、字段元信息丢失和列名歧义问题，提升筛选准确性与错误可见性。
+- 文件上传超时支持通过 `GUANCLI_UPLOAD_TIMEOUT` 配置，适配大文件或较慢网络环境。
+- 优化交互式登录和并发自动重登恢复机制，移除废弃的 AdminToken 认证链路。
+- 改进 npm 自动安装 Skill 的反馈、删除确认及 Windows CLI 兼容性。
+
 ## @guandata/guancli 1.0.51 - 2026-08-13
 
 - 优化指标查询结果的排序逻辑，支持按查询优先级更合理地返回指标，提升指标检索与选择体验。

package/README.md

@@ -5,10 +5,10 @@
 ## 安装
 
 ```bash
-npm install -g @guandata/guancli
+npm install -g --foreground-scripts @guandata/guancli
 ```
 
-> 全局安装/升级时会通过 postinstall 自动执行一次 `guancli install-skill` 刷新 AI skill；CI 等无需 skill 的环境可设 `GUAN_SKIP_INSTALL_SKILL=1` 跳过。
+> 全局安装/升级时会通过 postinstall 自动执行一次 `guancli install-skill` 刷新 AI skill。`--foreground-scripts` 用于显示明确的成功、失败或跳过结果；失败时按提示手动运行 `guancli install-skill`。CI 等无需 skill 的环境可设 `GUAN_SKIP_INSTALL_SKILL=1` 跳过。
 
 也可以直接使用：
 
@@ -26,6 +26,8 @@ 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 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql    # 从文件读取多行 SQL，避免 Shell 多层引号
+guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读取 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 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。
@@ -41,6 +43,20 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.53
+
+- 新增 OIDC 登录与安全凭据管理，企业统一身份认证和多环境切换更稳定。
+- SuperApp 支持列出应用和整包下载，重名应用也能得到明确的后续处理提示。
+- `ds execute-sql` 支持从文件或标准输入读取多行 SQL，并改进解析错误展示。
+- 改进文件下载的完整性、超时和错误处理，并支持自动关联卡片继承筛选条件。
+
+### @guandata/guancli 1.0.52
+
+- 新增资源全局搜索与资源 URL 获取能力，定位和访问 BI 资源更便捷。
+- 指标搜索可返回指标详情，并优化登录、自动重登和查询稳定性。
+- 修复表单与卡片筛选条件被忽略、误切或字段信息丢失等问题。
+- 文件上传超时可通过 `GUANCLI_UPLOAD_TIMEOUT` 配置。
+
 ### @guandata/guancli 1.0.51
 
 - 指标查询结果会按查询优先级合理排序，指标检索与选择更准确。

package/bin/install-env.js

@@ -0,0 +1,73 @@
+"use strict";
+
+const { spawnSync } = require("child_process");
+
+const SANITIZED_MARKER = "GUAN_INSTALL_ENV_SANITIZED";
+const SAFE_DELETE_TARGET = String.raw`(?:"(?:[^"]*[\\/])?genie-safe-delete\.cjs"|'(?:[^']*[\\/])?genie-safe-delete\.cjs'|(?:[^\s"']*[\\/])?genie-safe-delete\.cjs)`;
+
+function envKey(env, expected) {
+  return Object.keys(env).find((key) => key.toLowerCase() === expected.toLowerCase());
+}
+
+function stripWorkBuddySafeDelete(nodeOptions) {
+  const pattern = new RegExp(
+    String.raw`(^|\s)(?:--require|-r)(?:=|\s+)${SAFE_DELETE_TARGET}(?=\s|$)(?:\s+|$)`,
+    "gi"
+  );
+  let removed = false;
+  const value = String(nodeOptions || "").replace(pattern, (_, prefix) => {
+    removed = true;
+    return prefix ? " " : "";
+  }).trim();
+  return { value, removed };
+}
+
+function hasWorkBuddySafeDelete(env = process.env) {
+  const key = envKey(env, "NODE_OPTIONS");
+  return Boolean(key && stripWorkBuddySafeDelete(env[key]).removed);
+}
+
+function createInstallChildEnv(env = process.env) {
+  const childEnv = { ...env };
+  for (const key of Object.keys(childEnv)) {
+    if (key.toLowerCase() === "npm_config_global") {
+      delete childEnv[key];
+    }
+  }
+
+  const nodeOptionsKey = envKey(childEnv, "NODE_OPTIONS");
+  if (nodeOptionsKey) {
+    const cleaned = stripWorkBuddySafeDelete(childEnv[nodeOptionsKey]);
+    if (cleaned.removed) {
+      if (cleaned.value) childEnv[nodeOptionsKey] = cleaned.value;
+      else delete childEnv[nodeOptionsKey];
+      childEnv[SANITIZED_MARKER] = "1";
+    }
+  }
+  return childEnv;
+}
+
+function reexecInstallCommand(scriptPath, args, options = {}) {
+  const env = options.env || process.env;
+  if (env[SANITIZED_MARKER] === "1" || !hasWorkBuddySafeDelete(env)) {
+    return false;
+  }
+
+  const spawn = options.spawn || spawnSync;
+  const exit = options.exit || process.exit;
+  const nodePath = options.nodePath || process.execPath;
+  const result = spawn(nodePath, [scriptPath, ...args], {
+    stdio: "inherit",
+    env: createInstallChildEnv(env),
+    shell: false,
+  });
+  if (result.error) throw result.error;
+  exit(result.status == null ? 1 : result.status);
+  return true;
+}
+
+module.exports = {
+  createInstallChildEnv,
+  hasWorkBuddySafeDelete,
+  reexecInstallCommand,
+};

package/bin/postinstall.js

@@ -41,18 +41,21 @@ function main() {
   );
   if (result.error || result.status !== 0) {
     console.warn(
-      `[${CLI_NAME}] postinstall: automatic skill install did not complete` +
+      `[${CLI_NAME}] postinstall: AI skill update FAILED` +
         (result.error ? ` (${result.error.message})` : ` (exit ${result.status})`) +
         `; run \`${CLI_NAME} install-skill\` manually to refresh SKILL.md.`
     );
+    return;
   }
+  console.log(`[${CLI_NAME}] postinstall: AI skill updated successfully.`);
 }
 
 try {
   main();
 } catch (err) {
   console.warn(
-    `[${CLI_NAME}] postinstall: ${err.message}; run \`${CLI_NAME} install-skill\` manually.`
+    `[${CLI_NAME}] postinstall: AI skill update FAILED (${err.message}); ` +
+      `run \`${CLI_NAME} install-skill\` manually.`
   );
 }
 process.exit(0);

package/bin/run.js

@@ -6,6 +6,7 @@ const { execFileSync, execSync, spawnSync } = require("child_process");
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
+const { createInstallChildEnv, reexecInstallCommand } = require("./install-env");
 
 const PLATFORM_MAP = {
   "darwin-arm64": "guancli-darwin-arm64",
@@ -111,6 +112,7 @@ function resolveNpxInvocation() {
 }
 
 if (process.argv[2] === "install-skill") {
+  reexecInstallCommand(__filename, process.argv.slice(2));
   const pkgRoot = path.join(__dirname, "..");
   const extraArgs = process.argv.slice(3);
   const args = [
@@ -128,8 +130,11 @@ if (process.argv[2] === "install-skill") {
   console.log("Installing guancli to AI coding assistants...");
   const npxInvocation = resolveNpxInvocation();
   const result = spawnSync(npxInvocation.command, [...npxInvocation.argsPrefix, ...args], {
+    // Avoid leaking project-only Agent markers (for example PromptScript) from
+    // the caller's cwd into this global installation.
+    cwd: pkgRoot,
     stdio: "inherit",
-    env: process.env,
+    env: createInstallChildEnv(process.env),
     shell: false,
   });
   if (result.error) throw result.error;

package/package.json

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

package/skills/guancli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: guancli
-description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据，或要为已有仪表板/智能洞察卡片生成智能洞察结果时，主动使用这个 skill。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”时，也要使用这个 skill，并引导使用 `guancli app create`。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
-compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据，或要为已有仪表板/智能洞察卡片生成智能洞察结果时，主动使用这个 skill。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”“下载 SuperApp 整包”时，也要使用这个 skill，并引导使用 `guancli app create` / `guancli app download`。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个超级应用""把这个页面挪到 XX 目录""删掉这个页面""刚删的页面能找回来吗"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标查询分析 + SuperApp 模板项目创建与整包下载。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
+compatibility: Requires Node.js 14+. Install via npm install -g --foreground-scripts @guandata/guancli so the AI skill refresh result is visible.
 ---
 
 # guancli
 
-guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建。
+guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
 
 ## 何时优先使用
 
@@ -18,36 +18,42 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
-- 用户要创建超级应用 / SuperApp / SuperApp 模板项目。
+- 用户要创建超级应用 / SuperApp / SuperApp 模板项目，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
 - 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
 
 如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建与整包下载。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |---|---|
 | ETL 新建 / 编辑 / 保存 / 执行 | `guanetl` |
 | 数据源 / 数据集 CRUD / 增量 / 调度 | `guands` |
-| 看板 / 卡片构建 / 页面发布 / 截图 | `guanvis` |
+| 看板 / 卡片构建 / 页面**内容**修改 / 页面发布 / 截图 | `guanvis` |
+| 页面**本身**的删除 / 改名 / 移动 | `guanvis page` |
+| 页面目录（PAGE 目录树）创建 / 改名 / 移动 / 删除 | `guanvis dir` |
 | 指标创建 / 编辑 / 删除、指标主题 / 目录创建、公共维度管理、指标 Excel 标准化 | `guanmetric` |
 
 > guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
+>
+> 页面的**内容**（卡片、布局、筛选器）和页面**本身**的删除、改名、移动都归 `guanvis`（见「页面写操作不在 guancli」）。页面所在的**目录**归 `guanvis dir`——guancli 只提供只读的 `page get/search/tree`。
 
-**编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须路由到对应专用 skill 的**原地更新**能力；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
+**编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须使用**原地更新**能力：页面的改名和移动路由到 guanvis（`guanvis page rename` / `guanvis page move`，硬约束见 guanvis skill），其余路由到对应专用 skill；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。改名不要用"删页面 + 重新发布"，换目录不要用"删掉再发到新目录"。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
 
 ## 先做判断
 
 1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
-2. 多 profile 且已知登录 Domain 或 BI/页面 URL 时，先用 `auth list --domain <domain>` 或 `auth list --url <url>` 找候选；0 个候选时报告无匹配，并让用户明确现有 profile 或授权新建/更新哪个 profile，不能自动登录。多个候选时让用户按 profile 名称明确选择。选定 profile 后，用 `guancli --profile <name> auth status` 验证，并在后续查询中保留同一 `--profile <name>`；只有用户明确要求切换机器级默认环境时才用 `auth use`。
-3. 未指定 profile 线索时，用 `auth status` 确认当前默认环境的认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
-4. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
-5. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
-6. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
-7. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
-8. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
+2. 当前进程同时提供 `GUANCLI_OIDC_BASE_URL` 和 `GUANCLI_OIDC_ACCESS_TOKEN` 时，外部 OIDC 环境是本次进程的唯一有效目标，会覆盖本地 profile；直接用 `auth status` 验证，不要求先创建、选择或切换本地 profile。CLI 不接收外部 RefreshToken，也不刷新这组上游托管 Token。
+3. 未启用外部 OIDC 时，多 profile 且已知登录 Domain 或 BI/页面 URL，先用 `auth list --domain <domain>` 或 `auth list --url <url>` 找候选；0 个候选时报告无匹配，并让用户明确现有 profile 或授权新建/更新哪个 profile，不能自动登录。多个候选时让用户按 profile 名称明确选择。选定 profile 后，用 `guancli --profile <name> auth status` 验证，并在后续查询中保留同一 `--profile <name>`；只有用户明确要求切换机器级默认环境时才用 `auth use`。
+4. 未指定 profile 线索且未启用外部 OIDC 时，用 `auth status` 确认当前默认环境的认证是否有效；首次配置、PAT、profile 和配置文件细节见 `references/auth-and-config.md`。
+5. 如果 Token 过期，密码登录方式会自动刷新；Token 方式需重新登录。
+6. 先判断资源类型：ETL 用 `etl`，数据集用 `ds`，页面/仪表板用 `page`，卡片用 `card`，表单填报用 `form`。
+7. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`；目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。三棵 `tree` 都支持 `--max-depth N` / `--keyword 词`（客户环境目录树可达数千节点，全量输出会被截断，默认先 `--max-depth 2` 再按需加深）。
+8. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+9. 用户要求查询卡片数据，但没有说明是否沿用页面筛选上下文时，主动询问“是否应用该卡片关联筛选器的默认筛选条件”。用户确认后使用 `card preview <cd_id> --with-default-filters`；用户明确不要、已经给出筛选条件或已明确要求使用默认条件时，不重复询问。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
 
 ## 按需读取资料
 
@@ -69,12 +75,28 @@ guancli page tree --max-depth 2
 guancli etl search 关键词
 guancli ds search 关键词
 guancli page search 关键词
+guancli search 资源名 --limit 50 --offset 0
 guancli etl get <resource_id>
 guancli ds get <resource_id>
 guancli ds get <resource_id> --brief
 guancli ds get <resource_id> --assoc
 guancli page get <resource_id>
+guancli url page <page_id>
+guancli url card <cd_id> --page-id <page_id>
+# 卡片 Web URL 格式为 /page/<page_id>?anchor=<card_id>
+guancli url ds <ds_id>                              # 自动反查父目录并生成数据集详情页 URL
+guancli url ds <ds_id> --parent-id <dataset_dir_id>
+guancli url ds-dir <dataset_dir_id>                 # 数据集目录 URL
+guancli url etl <etl_id>
+guancli url etl <etl_id> --parent-id <parent_dir_id>  # 通常无需手填，CLI 会从 ETL 详情自动获取父目录；自动失败时再传
+guancli url metric-dir <metric_dir_id>                # 自动反查指标主题并生成指标目录 URL
+guancli url metric-dir <metric_dir_id> --project-id <metric_project_id>
+# 指标目录 Web URL 格式为 /metrics-store/project/<metric_project_id>/<metric_dir_id>
+# 数据集详情 Web URL 格式为 /data-center/data-sets/<dataset_dir_id>/<ds_id>/details/overview?limit=50
+# 数据集目录 Web URL 格式为 /data-center/data-sets/<dataset_dir_id>
 guancli ds preview <ds_id> --limit 20
+# 多行或含复杂引号的 SQL 优先写入文件并使用 --sql-file；需要管道输入时显式使用 --sql-file -。
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql
 guancli card get <cd_id>
 guancli card preview <cd_id> --value-format raw -f csv
 guancli card preview <cd_id> --with-default-filters
@@ -89,16 +111,44 @@ guancli insight card <cd_id> --page-id <page_id>
 
 详细筛选、输出、动态参数和复杂报表 Pro 行为见 `references/preview-and-output.md`。
 
+## 页面写操作不在 guancli
+
+guancli 的 `page` 只有 `get` / `search` / `tree` 三个**只读**子命令，没有任何页面写命令。
+用户要删除、改名、移动页面时不要在 guancli 里找命令，直接路由到 guanvis skill 的
+`guanvis page delete` / `guanvis page rename` / `guanvis page move`；确认闸门、`--force`
+语义和目录 ID 要求写在 guanvis 的 SKILL.md，这里不复述，以免两处漂移。
+
+**被删页面没有任何命令行恢复入口**：页面删除是软删，页面会进 BI 网页端的回收站，但要
+还原只能人工登录网页端操作。用户问"刚删的页面能找回来吗"时如实这么回答，不要编造恢复命令。
+
+guancli 在这条链路上只出只读的那一环：`guancli page search` / `page get` 确认目标 pgId，
+`guancli page tree --type dir` 查 `guanvis page move` 要传的目标目录 ID。
+
+## Form 关键规则
+
+- `form query --filter` 在**服务端**执行，格式 `"列名 操作符 [值]"`，可重复；多条件默认
+  `AND`，用 `--combine-type OR` 改成 `OR`。操作符可用性取决于字段控件类型：比较和区间
+  操作符（`GT`/`GE`/`LT`/`LE`/`BT` 系列）只支持 `NUMBER` 和 `DATE_TIME`，
+  `CONTAIN_ALL`/`CONTAIN_ANY` 只支持多选字段，`IN` 只支持文本类字段。先用
+  `form schema <fmId>` 确认字段的 `type` 再选操作符；用错类型会直接报错。
+- **不支持 `STARTSWITH` / `ENDSWITH`**（后端无实现），请用 `CONTAINS`（语义更宽，匹配任意
+  位置的子串）。
+- `form query --sort-asc/--sort-desc` **只对当前页取回的行排序，不是全表排序**（后端接口不
+  接受排序参数）。**不要把 `--limit N --sort-desc 列` 当作全表 Top-N**——它得到的是「这 N
+  行里最大的」。要回答"最大/最小/前几名"这类问题，先用 `--filter` 把范围收敛到能一次取回，
+  或取回全部数据后再排序；并在结论中说明排序范围。
+- 完整操作符表、子表 ID 映射规则见 `references/form-chatbi.md`。
+
 ## 指标关键规则
 
-- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等；未指定 `-o/--output` 且结果超过 1000 行时会自动写入 `metric_<metricId>_<timestamp>.<ext>`。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和优先级；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。
-- 搜索指标支持两种方式：`guancli metric search <keyword>` 按指标名称模糊搜索；`guancli metric search --fuzzy <keyword>` 同时按指标名称、业务口径、自定义业务属性值做 OR 模糊搜索，可多次传参，命中优先级为 name=1、desc=2、bizAttr=3。`[keyword]` 和 `--fuzzy` 互斥。
+- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等；未指定 `-o/--output` 且结果超过 1000 行时会自动写入 `metric_<metricId>_<timestamp>.<ext>`。回答指标数据查询结果时，必须检查输出中的 `查询加速` 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` 可跳过血缘，结构化详情优先使用 `-f json`。此模式不兼容 `--raw`、CSV 和 Excel 输出，结果很多时先用 search 的 `--limit` 收窄指标数量。指标取数仍单独使用 `metric query`。
 - 回答指标搜索结果时，必须逐条说明“命中的指标”和“命中方式”：至少包含指标 ID、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
 - 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；如果已知指标主题，可加 `-d <metric_topic_id>` 缩小范围；需要结构化结果时用 `-f json`。
 - 只要传入 `--compare`、`--compare-value`、`--xtd`、`--last`、`--recent`、`--recent-base`、`--percentage`、`--percentage-dim`、`--rank-top`、`--rank-order`、`--rank-dim`、`--adv-calc-json` 任一参数，就进入指标泛化查询模式。泛化查询要求 BI 版本 `>= 8.2.1`；如需确认环境版本，先执行 `guancli server-version --profile <profile>`。
 - 当用户要创建、编辑、删除指标，创建指标主题/目录，批量标准化指标 Excel，或管理公共维度时，切换到 `guanmetric`。
 
-## SuperApp 项目创建
+## SuperApp 项目创建与整包下载
 
 当用户提到创建超级应用、创建 SuperApp、新建 SuperApp 项目或基于 SuperApp 模板初始化项目时，使用：
 
@@ -110,6 +160,23 @@ guancli app create --name <project_name> --path <parent_dir>
 - 该命令会下载 SuperApp 模板并创建项目目录，随后尝试复制 `.env.template`、更新 `package.json` 名称、初始化 git，并根据模板情况执行 `setup.sh` 或 `npm install` + 启动本地 dev server。
 - 如果用户只是要创建本地 SuperApp 模板项目，不需要先做 BI 资源查询；直接给出或执行 `guancli app create`。
 
+当用户要把平台上已有的 SuperApp 取回本地（备份、比对、排查线上产物）时，使用：
+
+```bash
+guancli app list --name <名称片段>              # 用户只给名称时先拿 appId
+guancli app download <appId>                    # 默认写到 ./<appId>.zip
+guancli app download <appId> --output ./build/app.zip
+guancli app download <appId> --output ./build/  # 传目录则在目录下生成 <appId>.zip
+guancli app download <appId> -f json            # {appId,appName,version,output,bytes,entries,sha256}
+GUANCLI_DOWNLOAD_TIMEOUT=1200 guancli app download <appId>   # 大包/慢网络时调大下载超时
+```
+
+- **权限**：该端点要求 `STATIC_OPEN_APP` 的 **UPDATE**（不是 READ），只读账号用不了。返回 401/403 时命令会直接点明是登录态失效或缺这项更新权限，不要当成 appId 写错反复重试。
+- **超时**：下载默认超时 600 秒（区别于普通请求和 `GUANCLI_UPLOAD_TIMEOUT`）。大包在慢网络上仍可能超时，用 `GUANCLI_DOWNLOAD_TIMEOUT=<整数秒>` 调大后重试。
+- 命令会先用 `app list` 预检 appId 是否在本环境存在（顺带取回 appName/version），下载完再校验产物确实是非空 zip 并给出条目数与 sha256——认证失效时静态层可能回 200 + HTML，只看字节数分辨不出来。
+- 已知 caveat：`settings.json` 在远端是独立对象，如果经 app settings 接口改过，zip 里的那份可能仍是旧版本。
+- `-f` 只支持 `auto`（默认）和 `json`。
+
 ## 仪表板、卡片智能洞察
 
 ```bash
@@ -121,7 +188,7 @@ guancli insight card <cd_id> --page-id <page_id>
 guancli insight card <cd_id> --page-id <page_id> --selector "<selector_id>=<value>" --locale zh-CN
 ```
 
-- 复用当前 profile 的 uIdToken，当前等待完整非流式结果。
+- 复用当前 profile 的 uIdToken 或 OIDC Access Token，当前等待完整非流式结果。
 - `insight inspect` 输出洞察开关、分析思路 ID/名称和页面关联的 LLM 配置；不输出提示词正文，筛选器继续通过 `page get` / `card get` 查看。
 - 页面洞察仅支持已开启智能洞察的普通仪表板（`pgType=PAGE`）；数据大屏、智能归因、分析报告等页面类型不支持。
 - 卡片洞察必须同时提供卡片所属页面 ID，且仅支持 `cdType=INTELLIGENT_INSIGHT` 的智能洞察卡片。
@@ -166,6 +233,6 @@ guancli --raw insight agent ask <agent_id> --session-id <session_id> --expert-id
 
 - 用中文输出，优先给“可执行结论”。
 - 不只贴原始命令结果，必须做逻辑归纳（按链路/主题）。
-- 对 `guancli metric query` 的结果，必须在结论中单独交代查询加速命中情况；如果命中，必须点名具体加速指标 ID，不能只说“用了加速”。
+- 对 `guancli metric query` 的结果，必须在结论中单独交代查询加速命中情况；如果命中，必须点名具体加速指标 ID，并用页面查询顺序表述命中的是第几个加速计划；不能只说“用了加速”。输出里的 `优先级N` 是后端排序权重，数字越大越先尝试，不等同于页面查询顺序。
 - 涉及时间相关信息时给出明确日期。
 - 如果用户给的是模糊对象名，先说明你是如何定位到具体资源 ID 的。

package/skills/guancli/references/auth-and-config.md

@@ -2,7 +2,23 @@
 
 ## 首次配置（认证）
 
-### 方式一：用户名密码登录（推荐）
+### 方式一：浏览器 OIDC 登录（推荐）
+
+```bash
+guancli auth login --url https://bi.example.com --oidc
+```
+
+CLI 自主执行浏览器 OIDC 登录前，必须先在 BI 管理后台注册 Confidential Client 应用，再把生成的 Client ID 和 Client Secret 输入 CLI（也可分别使用 `--client-id` / `GUANCLI_OIDC_CLIENT_ID` 与 `--client-secret` / `GUANCLI_OIDC_CLIENT_SECRET`）。当前仅支持 Confidential Client，不提供客户端类型选择。交互登录会显示当前回调地址，直接回车保持不变，也可输入新地址；非交互场景使用 `--redirect-uri`。回调地址当前仅支持 HTTP loopback，默认登记地址为 `http://127.0.0.1/auth/oidc/callback`；CLI 会保留登记地址的 host/path，并始终将端口替换成本次本地 listener 的随机端口。回调地址必须存在于 BI OIDC 应用的回调地址配置中，否则授权请求会被拒绝。Token 默认与 Client ID、Client Secret 一起写入权限为 `0600` 的配置文件；使用 `--token-store keyring` 时，Token、Client ID 和 Client Secret 会一起保存到 macOS Keychain、Windows Credential Manager 或 Linux Secret Service，配置文件只保留凭据引用和非敏感 OIDC 元数据。已有 profile 重新登录时会沿用原存储方式，只有显式传入 `--token-store` 才切换。
+
+Access Token 到期后自动使用 Refresh Token 刷新。Refresh Token 不可用时，macOS 和 Windows 会自动输出新的登录 URL、尝试打开系统默认浏览器并等待回调；Linux 和尚未适配的平台不会让普通 CLI 请求突然进入浏览器交互，而是明确提示执行 `guancli auth login --profile <name> --oidc`。用户在 Linux 主动执行 `auth login --oidc` 时仍会尝试通过 `xdg-open` 打开浏览器，失败后可复制终端中的 URL。当前 callback listener 仅支持本机 loopback，不支持公开 HTTPS 回调或跨设备 callback relay。
+
+OIDC Base URL 支持 HTTP 和 HTTPS。传入 BI Web 根地址时，若根路径没有返回有效 Discovery，CLI 会兼容尝试 `/backend/.well-known/openid-configuration`；传入带路径的 URL 时则严格使用该路径。HTTPS 环境的 Discovery 不允许把 authorization/token/JWKS 等端点降级到 HTTP；测试环境可以直接使用 HTTP Base URL。CLI 不提供忽略自签名 HTTPS 证书校验的开关。浏览器打开前，CLI 会用一个不会成功兑换 Token 的占位授权码向 token endpoint 预检 Confidential Client 凭据：`invalid_grant` 表示 client_id/client_secret 已通过认证并继续登录；错误 client_id 或 client_secret 返回的 `invalid_client` 会立即结束，不再打开浏览器等待 callback；其他未覆盖的 OAuth 错误原样返回。
+
+如果 BI 对 Discovery 返回业务状态 `5001` 且提示 `No static resource .well-known/openid-configuration`，CLI 会明确提示“目标 BI 环境不支持 OIDC”，并建议管理员开启 OIDC 功能或升级 BI 版本，不再只暴露底层 HTTP 500。对于已部署 OIDC 但当前用户域或应用在功能层面禁用登录的环境，兼容版本服务端会通过 loopback callback 立即返回 `access_denied`；CLI 将该稳定错误转换为同一“不支持 OIDC”提示，不再等待 callback 超时。其他未覆盖的 OAuth 授权错误保留服务端返回的 `error` 和 `error_description`，不静默改写。
+
+上游 Agent 平台只需通过 `GUANCLI_OIDC_BASE_URL` 和 `GUANCLI_OIDC_ACCESS_TOKEN` 注入目标 BI 环境和托管 Token。Base URL 与 Access Token 是不可拆分的一组配置，缺少任意一个都会明确报错，不会回退或混用本地 profile。检测到完整配置后，普通业务命令可直接使用这组环境变量，不要求本地预先存在 profile；执行 `auth login` 或 `auth login --oidc` 时也会直接创建 external OIDC profile，不再要求 client_id/client_secret，不打开浏览器，并以环境变量 Base URL 覆盖已有 profile URL。完整 external OIDC 配置与 `--token`、`--pat`、账密参数不能同时使用，CLI 会立即提示参数冲突，避免保存一个实际不会被当前请求使用的本地身份。未检测到 Access Token 时才进入正常浏览器认证流程。命中上游 Token 后 guancli 只消费 Access Token，不接收外部 RefreshToken、不保存任何 Token，Access Token 过期或收到 401 时也不会回退到本地身份或触发浏览器登录，只提示由上游更新 AccessToken 后重试。
+
+### 方式二：用户名密码登录
 
 ```bash
 guancli auth login
@@ -11,20 +27,20 @@ guancli auth login
 交互式输入：
 1. 环境名称（默认 `default`，可自定义如 `staging`、`prod`）
 2. BI 系统 URL（如 `https://bi.example.com`）
-3. 选择登录方式：`1` 用户名密码
+3. 选择登录方式：`2` 用户名密码
 4. Domain（如 `demo`）
 5. 用户名（邮箱）
 6. 密码
 
-登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`。密码方式支持 Token 过期后自动刷新。
+账号或密码错误时，交互式登录会保留已输入的环境、URL、Domain 和 Login ID，直接提示重新输入密码。登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`，并自动切换到刚登录的环境；无需再执行 `auth use`。密码方式支持 Token 过期后自动刷新。
 
-### 方式二：直接输入 uIdToken
+### 方式三：直接输入 uIdToken
 
 ```bash
 guancli auth login
 ```
 
-选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
+选择登录方式 `3`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
 
 如需按登录 Domain 筛选这个 profile，可在非交互式登录时同时保存：
 
@@ -32,21 +48,21 @@ guancli auth login
 guancli auth login --url https://bi.example.com --domain demo --token <uid-token>
 ```
 
-### 方式三：Personal Access Token
+### 方式四：Personal Access Token
 
 ```bash
 guancli auth login --url https://bi.example.com --pat <pat>
 ```
 
-交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
+交互式登录时选择登录方式 `4`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token`，`X-Guandata-Client` 沿用请求来源（默认 `guancli`；高层 skill 经内部请求通道调用时保留其自身来源），`auth status` 会通过 `/api/pat/introspect` 做自检，且仅在响应明确返回 `usable: true`（兼容历史 `active: true`）时判定有效。
 
-`chatbi` 子命令仍要求 uIdToken 登录。
+`chatbi` 子命令支持 uIdToken 或 OIDC Access Token；PAT 仍不支持。
 
 ### 多环境管理
 
 ```bash
-guancli auth login --profile staging            # 添加 staging 环境
-guancli auth login --profile prod --default     # 添加 prod 并设为默认
+guancli auth login --profile staging            # 添加 staging 并切换为当前环境
+guancli auth login --profile prod               # 添加 prod 并切换为当前环境
 guancli auth list                                # 列出所有环境
 guancli auth list --domain demo                  # 按登录 Domain 筛选
 guancli auth list --url https://bi.example.com/page/123  # 按页面 URL 筛选
@@ -55,6 +71,7 @@ guancli auth use staging                         # 切换默认环境为 staging
 guancli auth use --domain demo                   # 按登录 Domain 切换
 guancli auth use --url https://bi.example.com/page/123  # 按页面 URL 切换
 guancli auth remove staging                      # 删除 staging 环境
+guancli auth logout staging                      # 吊销并清理 OIDC 自管 Token，保留 profile
 ```
 
 `auth list` 可用 `--domain` 或 `--url` 只读筛选 profile；`auth use` 使用相同筛选条件切换默认 profile。`--domain` 只匹配 profile 保存的登录 Domain，忽略大小写；`--url` 必须为不含 userinfo 的 HTTP(S) URL，且编码路径不得把 `/`、`.` 或 `..` 作为 path segment；它按相同协议、主机和最长的 `base_url` 路径前缀匹配，因此可直接传页面深链。`auth use` 遇到多个候选会拒绝切换，需改用 profile 名称明确选择。
@@ -72,7 +89,7 @@ GUANCLI_PROFILE=staging guancli etl tree
 
 ### ChatBI 配置
 
-ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
+ChatBI 统一复用当前 profile 的 `base_url` 和 uIdToken/OIDC Access Token。
 
 - 不需要单独配置 ChatBI URL
 - 不需要第二套 token / cookie
@@ -81,6 +98,8 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 ## Token 管理
 
 - 密码登录方式：Token 过期后自动调用 sign-in API 刷新。
+- OIDC 自管 Token：请求前主动刷新；Refresh Token 失效时 macOS/Windows 自动进行浏览器登录，Linux/未适配平台提示手动执行 `auth login --oidc`。读请求遇到 401 最多刷新并重试一次，写请求只刷新不重放。
+- OIDC 上游 Token：环境变量优先于上游钥匙串和本地凭据；过期或 401 时提示上游刷新，不使用上游 Refresh Token。
 - 每次 API 响应中如果包含新 Token，且距上次签发超过可配置间隔（默认 10 分钟），会自动更新缓存。
 - Token 的签发时间和过期时间记录在配置文件中。
 - 可通过修改 `config.json` 中的 `token_refresh_interval_seconds` 调整刷新间隔。

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

@@ -24,14 +24,67 @@ guancli form schema <fmId> -f json      # JSON 格式
 ```bash
 guancli form query <fmId>                          # 查询数据（默认 50 行）
 guancli form query <fmId> --limit 100              # 指定行数
-guancli form query <fmId> --filter "姓名 EQ 张三"  # 筛选
-guancli form query <fmId> --sort-asc 值            # 按值升序
+guancli form query <fmId> --filter "姓名 EQ 张三"  # 筛选（服务端执行）
+guancli form query <fmId> --sort-asc 值            # 按值升序（仅当前页）
 guancli form query <fmId> --columns "姓名,值"      # 只显示指定列
 guancli form query <fmId> -f json                  # JSON 格式（rowId 完整）
 guancli form query <fmId> -f expanded              # PG 风格竖排
 ```
 
-筛选操作符：`EQ`（等于）、`CONTAINS`（包含）、`STARTSWITH`、`ENDSWITH`、`IS_NULL`、`NOT_NULL`。
+#### 筛选（`--filter`，服务端执行）
+
+格式 `"列名 操作符 [值]"`，可重复指定；多个条件默认 `AND` 组合，用 `--combine-type OR`
+改成 `OR`。多值操作符（`IN`、`BT` 系列、`CONTAIN_ALL`/`CONTAIN_ANY`，以及多选字段上的 `EQ`）的值用**逗号**
+分隔；单值操作符的值原样保留其中的空格和逗号（`"姓名 EQ 张 三"` 匹配 `张 三`，`"姓名 EQ a,b"`
+匹配字面量 `a,b`，都不会被拆开）。
+
+操作符可用性取决于字段的控件类型（用 `form schema` 查看 `type` 列）：
+
+| 操作符 | 含义 | 适用字段类型 |
+|--------|------|-------------|
+| `EQ` | 等于；多选字段上是**集合相等**（`标签 EQ 红,黄` 匹配恰好选了这两项的行） | 全部 |
+| `NE` | 不等于 | 除多选外 |
+| `IN` | 属于给定值之一（逗号分隔） | 仅文本类（STRING/TEXT/VALUE_CHOOSER…） |
+| `CONTAINS` | 包含子串 | 全部 |
+| `NOT_CONTAINS` | 不包含子串 | 仅 NUMBER / DATE_TIME |
+| `GT` / `GE` / `LT` / `LE` | 大于 / 大于等于 / 小于 / 小于等于 | 仅 NUMBER / DATE_TIME |
+| `BT` | 闭区间 `lo,hi`（lo ≤ x ≤ hi） | 仅 NUMBER / DATE_TIME |
+| `OPEN_BT_OPEN` | 开区间（lo < x < hi） | 仅 NUMBER / DATE_TIME |
+| `OPEN_BT_CLOSE` | 左开右闭（lo < x ≤ hi） | 仅 NUMBER / DATE_TIME |
+| `CLOSE_BT_OPEN` | 左闭右开（lo ≤ x < hi） | 仅 NUMBER / DATE_TIME |
+| `CONTAIN_ALL` | 多选包含全部给定选项 | 仅 MULTI_VALUE_CHOOSER |
+| `CONTAIN_ANY` | 多选包含任一给定选项 | 仅 MULTI_VALUE_CHOOSER |
+| `IS_NULL` | 为空 | 全部 |
+| `NOT_NULL` | 不为空 | 除多选外 |
+
+```bash
+guancli form query <fmId> --filter "姓名 CONTAINS 张"                  # 子串匹配
+guancli form query <fmId> --filter "金额 BT 100,200"                   # 数值区间
+guancli form query <fmId> --filter "创建时间 GE 2026-01-01"            # 日期比较
+guancli form query <fmId> --filter "标签 CONTAIN_ANY 红,黄"            # 多选
+guancli form query <fmId> --filter "状态 IN 待审,已审"                 # 文本 IN
+guancli form query <fmId> --filter "姓名 EQ 张三" --filter "金额 GT 100"        # AND
+guancli form query <fmId> --filter "姓名 EQ 张三" --filter "姓名 EQ 李四" --combine-type OR
+```
+
+注意：
+
+- **不支持 `STARTSWITH` / `ENDSWITH`**（后端无对应实现）。CLI 会直接报错并提示改用
+  `CONTAINS`——注意 `CONTAINS` 语义更宽，匹配任意位置的子串。历史版本会把这两个操作符
+  发给后端并**静默返回未筛选的全量数据**。
+- 操作符用在不支持的字段类型上会**直接报错**，不会静默返回未筛选的数据。
+- `DATE_TIME` 的比较由后端按「天」截断（忽略时分秒），`BT` 两端都含端点。
+- 子表（`TABLE` / `MATRIX_TABLE`）字段不能作为筛选列，请直接查询子表。
+
+#### 排序（`--sort-asc` / `--sort-desc`）
+
+**只对当前页已取回的行排序，不是全表排序。** 后端 `form query` 接口不接受排序参数
+（固定按更新时间倒序返回），排序在 Go 端完成。因此
+`--limit 50 --sort-desc 金额` 得到的是「这 50 行里金额最大的」，**不是**「全表金额最大的
+50 行」——**不要把它当 Top-N 用**。命中总行数超过本页时 CLI 会在 stderr 输出警告。
+
+需要全表 Top-N 时，先用 `--filter` 把结果收敛到能一次取回的范围，或用 `--limit` /
+`--offset` 取回全部数据后再排序。
 
 **重要**：`rowId` 在 auto 表格格式中可能被截断，使用 `-f json` 或 `-f expanded` 获取完整 rowId。
 

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

@@ -70,6 +70,9 @@ guancli metric search [keyword] [flags]
 | --- | --- |
 | `-d, --dir-id string` | 限定搜索主题 ID |
 | `--fuzzy strings` | 名称、业务口径、自定义业务属性统一模糊搜索关键词，可多次指定，也支持逗号、中文逗号、顿号分隔；和 `[keyword]` 互斥 |
+| `--offset int` | 搜索结果分页偏移量，默认 `0` |
+| `--limit int` | 搜索结果数量，默认 `0` 表示全部 |
+| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；默认包含血缘，加 `--brief` 跳过血缘 |
 
 `--fuzzy` 语义：
 
@@ -78,6 +81,10 @@ guancli metric search [keyword] [flags]
 - 自定义业务属性值统一模糊匹配；后端只匹配启用且可搜索的业务属性。
 - 结果会在原有指标字段基础上增加命中条件、命中优先级和命中关键词。
 - 非 `--raw` 输出会额外查询并返回每个指标关联的查询加速摘要，包括查询加速数量和加速指标 ID/优先级/字段摘要。
+- `--with-detail` 会为当前搜索结果中的每个指标补充与 `metric get <metric_id>` 相同的标准化详情；默认终端输出按指标追加详情，`-f json` 则在每条搜索结果的 `指标详情` 中嵌套返回。
+- 默认详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。结果较多时先用 `--limit` 收窄指标数量。
+- `--with-detail` 只补指标详情，不查询指标数据；指标取数仍使用 `metric query`。
+- `--with-detail` 需要组合多个接口的结果，因此不兼容 `--raw`、`-f csv` 和 `-f excel`。
 - `[keyword]` 走旧指标名称搜索接口；`--fuzzy` 走新的统一模糊搜索接口，二者不能同时使用。
 
 回答要求：
@@ -96,6 +103,8 @@ guancli metric search 订购 --profile default -d <metric_topic_id>
 guancli metric search 订购 --profile default -f json
 guancli metric search --fuzzy "收入,GMV" --profile default -d <metric_topic_id>
 guancli metric search --fuzzy 收入 --fuzzy GMV --profile default -f json
+guancli metric search 销售 --profile default --limit 5 --with-detail
+guancli metric search --fuzzy 收入 --profile default --limit 5 --with-detail --brief -f json
 guancli metric search --fuzzy 订购 --profile default --raw
 ```
 
@@ -122,6 +131,8 @@ guancli metric get <metric_id> --profile default --raw
 
 查询指标的查询加速配置。后端取数时会按 `acceleratePriority` 从高到低尝试加速指标；只有当查询维度和筛选维度都能被加速指标适用维度覆盖时才会命中。
 
+`acceleratePriority` 是后端排序权重，数字越大越先尝试；页面上的“查询顺序”是按这个实际尝试顺序重新编号后的展示序号。因此 `acceleratePriority=4` 可能对应页面查询顺序 1。向用户解释命中计划时，优先使用页面查询顺序口径；如需换算，先执行 `metric accelerate list`，按 `acceleratePriority` 倒序排序后编号。
+
 ```bash
 guancli metric accelerate list <metric_id> [flags]
 ```
@@ -163,12 +174,14 @@ guancli metric by-dataset <ds_id> --profile default --raw
 
 查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。
 
-非 `--raw` 输出会展示本次查询是否命中查询加速：summary 中有 `查询加速`，数据行中有 `_queryAccelerate`。命中时展示源指标 ID、加速指标 ID 和优先级，例如 `metric_xxx->acc_xxx(优先级1)`；未命中时显示 `否`。若后端版本尚未返回查询加速 metadata，则显示 `未知: 后端未返回`。
+非 `--raw` 输出会展示本次查询是否命中查询加速：summary 中有 `查询加速`，数据行中有 `_queryAccelerate`。命中时展示源指标 ID、加速指标 ID 和后端排序权重，例如 `metric_xxx->acc_xxx(优先级4)`；未命中时显示 `否`。若后端版本尚未返回查询加速 metadata，则显示 `未知: 后端未返回`。
+
+注意：这里的 `优先级N` 是 `acceleratePriority` 原始值，不是页面“查询顺序”。向用户汇报时不要直接说“命中优先级第 N 个”，应在需要时结合 `metric accelerate list` 的完整列表，按 `acceleratePriority` 倒序换算成页面查询顺序。
 
 回答要求：
 
 - 必须单独说明本次查询加速命中情况。
-- 命中时必须明确列出命中的加速指标 ID、对应源指标 ID 和优先级。
+- 命中时必须明确列出命中的加速指标 ID、对应源指标 ID 和页面查询顺序；如果只拿到 `_queryAccelerate` 里的 `优先级N`，需说明这是后端排序权重，数字越大越先尝试。
 - 未命中时说明未命中查询加速。
 - 如果是 `未知: 后端未返回`，只能说明后端未返回命中 metadata，不能推断是否命中。
 

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

@@ -7,10 +7,14 @@ 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 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关）
+guancli ds execute-sql -inputs <ds_id> --sql-file query.sql     # 从文件读取 SQL
+guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读取 SQL
 # SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。可先执行 `ds get <ds_id> --brief` 查看数据集名称和字段列表。
 `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
 ```
 
+`--sql` 与 `--sql-file` 二选一。SQL 较长、包含多层引号或由模型生成时，优先写入 `.sql` 文件再传 `--sql-file`；传 `--sql-file -` 时从 stdin 读取，不会把终端中的普通空输入当作 SQL。
+
 数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
 
 如果用户给的是业务目录名而不是数据集名，优先先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
@@ -114,7 +118,7 @@ guancli card preview <complex_report_pro_cd_id> --filter "周 toWeek EQ 2026-W01
 
 ### 应用页面关联筛选器的默认条件
 
-图表卡片默认只按卡片自身配置取数，不会隐式继承页面筛选上下文。需要得到与页面首次打开时一致的结果，可显式传入 `--with-default-filters`。CLI 会读取卡片所属页面，找出通过 `asFilter.columnMappings` 关联到该卡片的选择器，并将默认字段筛选或动态参数一并传给卡片数据接口；整个过程只依赖卡片和页面元信息，不会查询需要数据集管理权限的全局动态参数接口。
+图表卡片默认只按卡片自身配置取数，不会隐式继承页面筛选上下文。需要得到与页面首次打开时一致的结果，可显式传入 `--with-default-filters`。CLI 会读取卡片所属页面，优先找出通过 `asFilter.columnMappings` 关联到该卡片的选择器；若选择器启用 `autoLink`（或 `asFilter` 未显式关闭 autoLink），则按选择器源字段与目标卡片字段的同名匹配推断目标字段，并将默认字段筛选或动态参数一并传给卡片数据接口；整个过程只依赖卡片和页面元信息，不会查询需要数据集管理权限的全局动态参数接口。
 
 ```bash
 guancli card preview <cd_id> --with-default-filters
@@ -126,7 +130,7 @@ guancli card preview <cd_id> --with-default-filters --dynamic-param "结束日
 - 卡片元信息只关联一个页面时自动使用该页面；关联多个页面时必须用 `--page-id` 明确上下文。
 - 显式 `--filter` 或 `--dynamic-param` 会覆盖相同 `fdId` 或 `dpId` 的页面默认值，其他默认条件仍然保留。
 - 首版支持普通固定值、多选、日期范围、后端已经解析出实际区间的时间宏，以及动态参数选择器。
-- 树、组合、`FIRST_PICK`、`autoLink`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。
+- 树、组合、`FIRST_PICK`、聚合/结果级映射、依赖其他选择器的级联运行态、必填但无默认值，以及无法从页面元信息确定实际值或目标映射的默认条件均 fail closed：CLI 在查询卡片数据前明确报错，不会静默忽略后继续执行。`autoLink` 会先按同名字段推断目标字段，推断不到时才 fail closed。
 - 多个选择器写入同一字段或动态参数、时间宏目标形态不明确、动态参数默认值包含逗号等可能产生歧义的情况同样会停止查询。
 - 该参数仅适用于 CHART 图表卡片；复杂报表 Pro、选择器和其他卡片类型暂不支持。
 

package/skills/guancli/references/resource-query.md

@@ -19,10 +19,14 @@ guancli ds search --limit 500 --offset 500  # 分页扫描数据集
 guancli ds search --id <dsId>          # 按数据集 ID 精确查找并返回单个数据集详情
 guancli ds search 关键词 --id <dsId>   # 按名称 + ID 组合查找
 guancli page search 关键词             # 搜索页面
+guancli search 资源名                  # 全局搜索，默认每种资源类型返回前 50 条
+guancli search 资源名 --limit 100 --offset 100  # 按每种资源类型分页
 ```
 
 `ds search` 默认返回前 500 条，环境数据集较多时用 `--limit` 和 `--offset` 分页扫描；`ds search --id` 会直接按数据集 ID 获取单个数据集详情，`--limit` 和 `--offset` 在 `--id` 模式下忽略。
 
+`guancli search <资源名>` 调用 `/api/global-search` 并传 `{"keyword":"<资源名>","resourceType":"ALL","isMobile":false,"limit":50,"offset":0}` 做全局搜索，适合资源类型不确定、需要像 MCP `global_search` 一样先定位资源 ID 的场景。`--limit` 和 `--offset` 在 `ALL` 模式下分别作用于每种资源类型；如果某一类型的匹配数超过当前窗口，继续增加 `--offset` 翻页。已知类型时仍优先用 `ds/page/etl search` 获取类型专属字段。
+
 ## 3. 获取详情（含血缘）
 
 ```bash
@@ -37,6 +41,25 @@ guancli page get <resource_id>         # 页面详情（含卡片列表、血缘
 
 **`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
 
+## 4. 获取资源具体 URL
+
+```bash
+guancli url page <page_id>                         # 仪表板页面前端 URL + API URL
+guancli url card <cd_id> --page-id <page_id>       # 卡片所在页面 anchor URL + 卡片 API URL
+guancli url ds <ds_id>                             # 自动反查父目录并生成数据集详情页 URL
+guancli url ds <ds_id> --parent-id <dataset_dir_id>
+guancli url ds-dir <dataset_dir_id>                # 数据集目录 URL
+guancli url etl <etl_or_dir_id>                    # ETL/数据流基础前端 URL + API URL
+guancli url etl <etl_id>                           # 普通 ETL 会自动从详情接口获取父目录并生成详情页 URL
+guancli url etl <etl_id> --parent-id <dir_id>      # 自动获取失败时手动指定父目录
+guancli url metric-dir <metric_dir_id>             # 自动反查指标主题并生成指标目录 URL
+guancli url metric-dir <metric_dir_id> --project-id <metric_project_id>
+guancli url metric-tree <metric_tree_id>           # 指标树编辑页面 URL
+guancli -f json url page <page_id>                 # 结构化输出，便于自动提取 webUrl/apiUrl
+```
+
+`url` 命令读取本地 profile 的 `base_url`。页面 URL 是稳定前端直达链接；卡片没有独立页面，但传 `--page-id` 后会生成 `/page/<pageId>?anchor=<cardId>` 定位具体卡片；数据集会优先读取详情中的 `parentDirId`，自动生成 `/data-center/data-sets/<parentDirId>/<dsId>/details/overview?limit=50`，自动获取失败时再手动传 `--parent-id`；数据集目录使用 `/data-center/data-sets/<dataset_dir_id>`；ETL/数据流会优先读取 ETL 详情中的 `parentDirId`，普通 ETL 自动生成 `/data-center/data-flow/<parentDirId>/<etlId>/details/datasets?limit=50`；详情接口不可用时回退查询 ETL 目录树，目录节点使用 `/data-center/data-flow/<id>`；自动获取失败时再手动传 `--parent-id`。
+
 ## 输出说明
 
 - **目录树**：树形结构（├── └──），包含名称和 ID