@guandata/guancli 1.0.58 → 1.0.60

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## @guandata/guancli 1.0.60 - 2026-09-17
+
+- 新增内部 OAuth2 应用认证：整体注入 `GUANCLI_OAUTH2_BASE_URL`、`GUANCLI_OAUTH2_ACCESS_TOKEN` 与用户身份（`GUANCLI_OAUTH2_UID` 或 `GUANCLI_OAUTH2_LOGIN_ID`）；CLI 不保存、不交换也不刷新该 Token，且 OAuth2 与 OIDC 变量同时出现时明确报错，不回退本地 profile。
+- Personal Access Token 登录会保存登录 Domain，多 profile 场景可按 Domain 筛选。
+- 新增 `ds get <ds_id> --validate-downstream`：逐个校验血缘中的下游资源是否仍存在，只有结构化业务状态 `1002` 或 HTTP 404 才判定为不存在，认证/HTTP/解析错误直接失败；单次最多校验 100 个下游资源、总超时 30 秒。
+
+## @guandata/guancli 1.0.59 - 2026-09-15
+
+- `--filter` 支持符号比较操作符 `=`、`!=`、`<>`、`<`、`<=`、`>`、`>=`，统一归一化为枚举操作符；`--filter-json`、`--filter-file` 和 `metric batch-query` 的 `operator` 同样支持。`BT` 也接受两个不含空格的边界用空格分隔。
+- `metric batch-query` 新增 `--fail-on-error`：任一项失败时仍输出完整 JSON 但非零退出，可直接用 `&&` 衔接后续处理。
+- `metric batch-query` 的 `valueFormat` 新增 `both`：一次取数同时返回原始 `rows` 和展示用 `formattedRows`，需要计算又需要展示时不再重复取数。
+- `ds execute-sql` 新增 `-o/--output`，可直接把结果写入文件（默认 CSV），避免为保存结果重复改参执行。
+- `app publish --overwrite-settings` 仅在 BI `>= 8.3.2` 时生效；低版本、版本查询失败或响应无法解析时默认保留线上 `settings.json`。
+- 结构化筛选条件组误用 `children` 时会给出明确错误并提示改用 `conditions`。
+
 ## @guandata/guancli 1.0.58 - 2026-09-11
 
 - 新增 `metric batch-query`：把同轮已确定、互不依赖的多个基础指标查询写成一份 JSON 一次提交，CLI 自动调度并发并按输入顺序逐项返回，输出 `schemaVersion: 1.0` 稳定机器契约，失败逐项归因，退出 0 不代表每项都成功。

package/README.md

@@ -43,6 +43,18 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.60
+
+- 新增内部 OAuth2 应用认证，按 `GUANCLI_OAUTH2_*` 整体注入环境与用户身份，CLI 不保存、不刷新该 Token。
+- PAT 登录会保存登录 Domain；新增 `ds get --validate-downstream` 校验血缘下游资源是否仍存在。
+
+### @guandata/guancli 1.0.59
+
+- 指标筛选支持 `=`、`!=`、`<>`、`<`、`<=`、`>`、`>=` 符号写法，统一归一化为枚举操作符；`BT` 也支持两个不含空格的边界用空格分隔。
+- `metric batch-query` 新增 `--fail-on-error`，并在 `valueFormat` 中新增 `both`，一次取数同时返回原始值和展示值。
+- `ds execute-sql` 新增 `-o/--output`，可直接把结果写入文件（默认 CSV）。
+- `app publish --overwrite-settings` 仅在 BI >= 8.3.2 时生效，低版本默认保留线上设置。
+
 ### @guandata/guancli 1.0.58
 
 - 新增 `metric batch-query`：同轮已确定、互不依赖的多个基础指标查询可写成一份 JSON 一次提交，CLI 自动调度并发并按输入顺序逐项返回，失败逐项归因。

package/package.json

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

package/skills/guancli/SKILL.md

@@ -47,9 +47,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 ## 先做判断
 
 1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
-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`。
+2. 当前进程提供完整外部 OIDC 认证环境时，它是本次进程的唯一有效目标并覆盖本地 profile：使用 `GUANCLI_OIDC_BASE_URL` + `GUANCLI_OIDC_ACCESS_TOKEN`。直接用 `auth status` 验证，不要求先创建、选择或切换本地 profile。
+3. 未启用外部认证时，多 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 线索且未启用外部认证时，用 `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` 再按需加深）。
@@ -70,7 +70,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 
 ## 常用查询入口
 
-**同轮指标查询规则**：本轮已确定、彼此互不依赖，且参数能被 `batch-query` 完整表达的多个基础指标查询，必须写成一个结构化查询列表并执行一次 `guancli metric batch-query --input queries.json`。同比、XTD、recent、占比、排名等高级计算继续使用单条 `metric query`；同轮其余基础查询仍应单独组成 batch。不得生成 Shell `for` 循环逐项执行基础指标查询，也不自行设计 `&`、`xargs -P` 等并发脚本或调整并发参数。CLI 自动调度并逐项返回结果；用 `id` 对齐每项 `status`，不能把进程退出 0 当成所有查询成功。后续查询依赖本轮结果时，读取本轮结果后再生成下一批。搜索并需要详情时使用 `metric search --with-detail`，避免逐项 get。批量输入、分页与支持边界见 [metric-batch-query.md](references/metric-batch-query.md)。
+**同轮指标查询规则**：本轮已确定、彼此互不依赖，且参数能被 `batch-query` 完整表达的多个基础指标查询，必须写成一个结构化查询列表并执行一次 `guancli metric batch-query --input queries.json`。同比、XTD、recent、占比、排名等高级计算继续使用单条 `metric query`；同轮其余基础查询仍应单独组成 batch。不得生成 Shell `for` 循环逐项执行基础指标查询，也不自行设计 `&`、`xargs -P` 等并发脚本或调整并发参数。CLI 自动调度并逐项返回结果；需要全部成功后再处理结果时加 `--fail-on-error`，可直接用 `&&` 衔接；默认模式仍需用 `id` 对齐每项 `status`。后续查询依赖本轮结果时，读取本轮结果后再生成下一批。搜索并需要详情时使用 `metric search --with-detail`，避免逐项 get。批量输入、分页与支持边界见 [metric-batch-query.md](references/metric-batch-query.md)。复用已确认的输入契约，缺少信息或遇到参数错误时再读取该参考，不固定增加帮助查询。
+
+**减少模型往返**：同一授权和查询轮次内，已确认的指标口径、字段与能力直接复用。将确定性的文件读取、状态检查、裁剪和计算合并成一次本地执行，返回需要判断的摘要；仅在结果引入新决策时再规划下一轮。只读查询可与结果保存、检查和摘要合并执行；确认查询成功后再消费，不为补齐运行轨迹拆分命令或重跑查询。
 
 ```bash
 guancli etl tree --max-depth 2
@@ -84,6 +86,7 @@ guancli etl get <resource_id>
 guancli ds get <resource_id>
 guancli ds get <resource_id> --brief
 guancli ds get <resource_id> --assoc
+guancli ds get <resource_id> --validate-downstream
 guancli page get <resource_id>
 guancli url page <page_id>
 guancli url card <cd_id> --page-id <page_id>
@@ -100,7 +103,7 @@ guancli url metric-dir <metric_dir_id> --project-id <metric_project_id>
 # 数据集目录 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 ds execute-sql -inputs <ds_id> --sql-file query.sql -f csv -o result.csv
 guancli card get <cd_id>
 guancli card preview <cd_id> --value-format raw -f csv
 guancli card preview <cd_id> --with-default-filters
@@ -113,6 +116,8 @@ guancli insight card <cd_id> --page-id <page_id>
 > 优先用 `guands dataset fields <ds_id>`（轻量、秒回）；详情确需查看时先加
 > `--brief` 跳过血缘。命令超时时不要原样重试——换轻量命令或转后台执行。
 
+删除数据集前不要依据 `cardCount` 单独判断引用关系。需要核验血缘中的下游 ID 是否仍存在时，使用 `ds get <ds_id> --validate-downstream`；该选项逐个调用资源详情接口，只有结构化业务状态 `1002` 或 HTTP 404 才标记为“不存在”，认证、HTTP 和 JSON 解析错误会直接失败，避免把查询失败误报成幽灵引用。单次最多验证 100 个下游资源，总超时 30 秒；不支持与 `--brief` 同时使用。
+
 详细筛选、输出、动态参数和复杂报表 Pro 行为见 `references/preview-and-output.md`。
 
 ## 页面写操作不在 guancli
@@ -147,15 +152,16 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 
 - **先按下面的命令契约生成，不要猜 shell、jq 或筛选语法**：
   - `metric search/get/tree/query -f json` 返回统一 envelope：先读取 `schemaVersion`、`resultMode` 和 `rowCount`；当前 canonical 契约版本为 `1.0`。`resultMode=inline` 时消费 `data`，`resultMode=file` 时读取 `path`。search/get 直接从后端字段构造稳定英文模型，核心字段包括 `id/name/status/type/description/dataset/dimensions/timeField/measureFields`，`status/type` 使用 `PUBLISHED/ATOMIC` 等机器枚举，不依赖中文展示 key；tree 使用 `id/name/type/children`。后端新增未知字段不会要求 CLI 同步修改，稳定必填字段缺失则明确失败。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。旧脚本按 `references/metric-json-migration.md` 迁移；envelope 版本由响应体中的 `schemaVersion` 演进，不新增 `json-v2` 一类输出格式。JSON envelope 不能输出到 stderr；`--raw` 单独返回后端原始协议。
-  - `metric query --filter` 只接受 `EQ`、`NE`、`LT`、`LE`、`GT`、`GE`、`BT`、`IN`、`IS_NULL`、`NOT_NULL`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`，禁止使用 `=`、`>=`、`<=`。例如日期下界写 `--filter "日期 GE 2026-01-01"`。
+  - 比较筛选优先用带空格的符号写法，例如 `--filter '日期 >= 2026-01-01'`；支持 `=`、`!=`、`<>`、`<`、`<=`、`>`、`>=`，原有 `EQ/NE/LT/LE/GT/GE` 仍有效。CLI 统一归一为枚举操作符，结构化筛选和 batch-query 的 `operator` 同样支持符号。整个 `--filter` 参数必须用 shell 引号包住；集合、区间、空值与字符串匹配操作符见命令帮助。
   - query 的业务列可以是中文，每个中文层级都用 `["字段名"]`：例如 `.data[] | .["组织"]["名称"]`，每一个中文层级都要引用，不能只改顶层。search/get 的 canonical 英文字段与 query 的业务列名要分开理解。文件模式的 `path` 指向行数组，行数组没有 `rowCount`；先按 `resultMode` 分支再消费，示例见 `references/metric-commands.md`。
-  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr，也不得用 `2>&1` 将错误文本送入 JSON 解码器。不要用会让末端命令成功掩盖上游失败的管道；优先拆成“guancli 输出到文件 → 确认命令成功 → jq 读取文件”，必须使用管道时先启用 `set -o pipefail`。
+  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr，也不得用 `2>&1` 将错误文本送入 JSON 解码器。不要用会让末端命令成功掩盖上游失败的管道；允许组合执行时用 `&&` 衔接“输出到文件 → 解析摘要”，不为读取文件另起一轮推理，必须使用管道时先启用 `set -o pipefail`。
   - 同类语法错误只允许出现一次；第一次失败后先执行对应命令的 `--help` 或读取本 Skill 的参考文档，再按真实契约纠正，不连续尝试相近写法。
-- 普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一，禁止混用。复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树，并先加 `--dry-run -f json`；dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件树节点使用 `combineType: AND|OR`，叶子使用 `field/operator/value|values`；`IN` 至少一个值，`BT` 恰好两个值。当前指标取数接口不能无损表达多分支 OR，真实执行会在取数前返回 `FILTER_OR_EXECUTION_UNSUPPORTED`，不得拆成多次聚合查询后拼接。失败时按稳定错误码修正，不猜错误文本。
+- 普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一，禁止混用。复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树。参数和口径明确时直接查询；需要检查计划或排查复杂参数时才用 `--dry-run -f json`。dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件组使用 `combineType: AND|OR` 和 `conditions` 数组，叶子使用 `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`。
 - 指标结果加工前，先读取成功 query envelope 的实际 `columns` 和行对象 keys，按业务含义选择列；禁止硬编码或猜测指标展示列名（包括高级计算后缀），也不能按列位置取值。使用 `python3 references/examples/metric-query-rows.py <envelope.json> --list-columns` 发现列，再用 `--column "<已确认的实际列名>"` 精确选择；候选缺失或多义时停止并返回实际列集合，不猜近似名称。该参数属于消费 recipe，不是 `guancli metric query` 的参数。
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等。数值默认按指标配置的 `format` 输出（查询响应有更具体的列级格式时优先），没有有效格式时才按 `--precision` 回退；需要标准表格/JSON/CSV/Excel 中保留原始数值时传 `--value-format raw`，不要和直接返回后端响应的全局 `--raw` 混淆。使用 `-f json` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。默认文本、CSV/Excel 和 `--raw` 保持原行为。回答指标数据查询结果时，必须检查输出中的 `查询加速` summary 或 `_queryAccelerate` 列：命中时明确说明“本次查询命中查询加速”，并列出源指标 ID、加速指标 ID 和页面查询顺序；未命中时说明“未命中查询加速”；如果显示 `未知: 后端未返回`，说明当前后端未返回命中 metadata，不能推断是否命中。注意：输出中的 `优先级N` 来自后端 `acceleratePriority` 排序权重，数字越大越先尝试；不要把它直接解释成页面“查询顺序”。需要和页面对齐时，额外执行 `guancli metric accelerate list <metric_id>`，按 `acceleratePriority` 倒序排列后换算页面查询顺序（倒序第 1 个即页面查询顺序 1）。
+- 同一批量查询既用于计算又用于展示时，使用 `valueFormat: "both"`；原始 `rows` 用于计算，`formattedRows` 用于展示，不按格式重复取数。仅需一种格式时使用 raw 或 formatted，避免额外输出。
 - 指标查数必须区分**时间范围**和**分组粒度**。用户说“本月/上月/2026 年 8 月销售额”时只生成时间筛选，不自动增加月维度；用户说“按月/每月/月度趋势/逐月”时，先从指标详情的 `timeField.name` 取得真实时间维度名，再使用 `--dim "<时间维度> toMonth"`；“近 12 个月每月”同时生成月维度和时间范围筛选。季度、周、日、星期、小时、分钟、秒同理映射到 `toQuarter/toWeek/toDate/toDayOfWeek/toHour/toMinute/toSecond`。用户未表达分组粒度时不得擅自改变日期粒度，也不要猜时间字段名一定叫“日期”。多日期维度且用户明确点名其中一个时，用 `--dim "<该维度> toGranularity"` 消歧；未点名且无法从业务问题确定时先确认。日期粒度排序使用相同表达式，例如 `--sort-asc "订单日期 toMonth"`。执行前可用 `--dry-run -f json` 检查 `resolvedDimensions` 中最终选择的 `fdId/fdType/parentFdName/granularity`。
 - 搜索指标支持两种方式：`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、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
@@ -184,7 +190,7 @@ guancli app publish --path <project_dir> --app-id <appId> --overwrite-settings
 ```
 
 - 更新已有 SuperApp 时，CLI 会在构建后检查实际 `dist/settings.json`。交互终端会询问：“是否覆盖线上 `settings.json`？”发布应用的授权不等于覆盖线上设置的授权。
-- 只有用户明确回答要覆盖时才传 `--overwrite-settings`，或在 CLI 交互提示中回答 `y`。不要仅因为用户要求“发布应用”就自动追加该参数。
+- 只有用户明确回答要覆盖时才传 `--overwrite-settings`，或在 CLI 交互提示中回答 `y`。该覆盖能力仅在 BI `>= 8.3.2` 时生效；低版本、版本查询失败或响应无法解析时均默认保留线上设置。不要仅因为用户要求“发布应用”就自动追加该参数。
 - 用户回答不明确、没有反馈、非交互任务无法取得确认或确认流程异常时，一律按“不覆盖”处理。CLI 在非交互环境默认从待上传 zip 排除根目录的 `dist/settings.json`，继续发布其他静态资源，并在结果的 `settingsAction` 中返回 `preserved`。
 - 创建全新 SuperApp 时线上尚无 `settings.json`，无需询问覆盖；但通过 `--app-id` 更新，或 `--update-if-exists` 命中同名线上应用时，都必须执行上述确认。
 - 如果运行的是不支持该保护的旧版 guancli，不要冒险发布包含 `settings.json` 的更新产物；应先升级 CLI，不能把缺少确认当作同意。

package/skills/guancli/references/metric-batch-query.md

@@ -4,28 +4,42 @@
 同一轮已经确定的独立查询一次提交，CLI 管理并发；读完结果才能确定的下一轮单独提交。
 不要编写循环逐个 `metric query` 或自行安排 Shell 并发。
 
-```json
-[
-  {"id":"sales-2023","metricId":"实际指标ID","dimensions":["大区"],"filters":{"field":"日期","operator":"BT","values":["2023-01-01","2023-12-31"]},"sortDesc":"销售金额","offset":0,"limit":10,"valueFormat":"formatted"},
-  {"id":"sales-month","metricId":"实际指标ID","dimensions":["日期 toMonth"],"limit":12}
-]
+已确认输入契约时直接复用；缺少必要信息或遇到参数错误时再看 `guancli metric batch-query --help`；多条件筛选示例见 [metric-commands.md](metric-commands.md) 的“结构化条件树示例”。筛选组使用 `conditions` 数组，不使用资源 tree 的 `children`。只使用已确认的指标字段及取值；按错误指出的字段修正，不连续猜键名。
+
+参数确定后将所有独立查询写入同一批次并直接执行；dry-run 仅用于检查计划或排查复杂参数，不作为每批取数的前置步骤。需要 dry-run 时，加 `--fail-on-error` 可让任一计划失败返回非零；全部通过后可用 `&&` 执行同一输入。默认模式仍需检查每项 `status=planned`。正式执行默认模式先检查各项状态；使用 `--fail-on-error` 且退出成功时可直接处理结果，无需重复逐项检查状态。只读查询允许与结果保存、检查和计算组合执行；无法生成结构化运行轨迹时接受降级，不为轨迹增加调用。
+
+批量查询的“保存 + 成功后摘要”示例（queries.json 使用已确认参数）：
+
+```bash
+guancli metric batch-query --input queries.json --fail-on-error -f json > results.json &&
+python3 - <<'PYTHON'
+import json
+with open("results.json") as source:
+    items = json.load(source)["results"]
+print(json.dumps([{"id": item["id"], "columns": item["result"]["columns"],
+                   "rowCount": item["result"]["rowCount"],
+                   "sampleRows": item["result"]["rows"][:5]} for item in items], ensure_ascii=False))
+PYTHON
 ```
 
+摘要只展示样例；需要全量计算时在同一本地步骤中使用 results.json 的完整结果，并核对 limit 与完整性。
+仅需直接阅读且输出已足够精简时直接消费 CLI 输出。已有结果的状态检查、完整性检查和计算也在一次本地执行中完成；字段缺失、多义或结果不完整时返回证据，不猜字段、不删筛选。不要为缩短往返扩大数据范围或省略业务校验。
+
 每项必填唯一非空 `id` 和真实 `metricId`。时间范围通过 `filters` 表达，省略表示不额外筛选；支持现有结构化条件树和操作符，不支持需要拆分聚合的多分支 OR。基础查询与 `metric query` 一样，使用指标关联的趋势图卡片，缺失时回退指标值卡片；每项创建独立编辑会话。日期粒度筛选、日期子粒度分组和排序沿用 `metric query` 的能力。错误或不支持的条件显式失败，禁止删除条件后重试以伪装成功。
 
 - `dimensions`：非空维度名称数组；省略时沿用关联卡片的默认分组，显式提供时覆盖该项独立编辑会话的分组。空数组会被拒绝；支持 `日期 toMonth` 等现有粒度语法。
 - `sortAsc` / `sortDesc`：互斥；解析和执行语义与 `metric query` 一致。日期子粒度排序使用同一限定表达式，例如 `日期 toMonth`。
 - `limit`：默认 50，必须为正数。`offset` 默认 0，非负；`offset + limit` 最多 10000。非零 offset 必须显式排序。后端无 offset，CLI 请求至 offset+limit 后截取，不代表全量遍历；排序相同值和跨请求数据变化可能使跨页不稳定，严格分页需选择能唯一定位顺序的分组。
-- `valueFormat`：支持 `raw`（默认）和 `formatted`。`raw` 保留 JSON 数字、null 和维度值；`formatted` 沿用 `metric query --value-format formatted` 的指标格式规则，把指标列输出为带精度、千分位、百分号或单位的字符串，维度列保持原值。排序和分页始终基于格式化前的原始值。
+- `valueFormat`：支持 `raw`（默认）、`formatted` 和 `both`。`raw` 保留 JSON 数字、null 和维度值；`formatted` 沿用 `metric query --value-format formatted` 的指标格式规则，把指标列输出为带精度、千分位、百分号或单位的字符串，维度列保持原值。排序和分页始终基于格式化前的原始值。需要计算并展示同一结果时使用 `both`，一次取数返回原始 `rows` 和位置完全对应的 `formattedRows`，不要为两种格式提交重复查询。
 - `--dry-run`：读取指标详情后生成每项取数请求计划，不执行指标取数，不代表权限、执行或数据完整性已经通过。
 
 完整 guancli 固定并发 10，不限制查询项数量，输入文件至多 1 MiB；超过 10 项的部分排队。batch 不设置整批超时，每个底层接口沿用 `metric query` 的 HTTP 单请求超时。结果逐项写入临时 spool，最终按输入顺序流式输出，内存占用随并发度而不是查询项总数增长；命令取消会传到底层 HTTP 并等待在途 worker 收口。无缓存、无跨批结果复用。每项使用后端生成的独立 UUID 编辑会话，不保存关联卡片；编辑会话生命周期沿用现有 `metric query` 和 BI 后端策略。kit/lite 入口还受宿主实际请求预算约束，超过预算时由 dispatcher 按真实请求数停止。
 
 ## 稳定 JSON 协议 v1
 
-顶层 `schemaVersion: "1.0"`、`command: "metric.batch-query"`、`status`、`results`。全部完成成功为 `success`，存在失败为 `partial_failure`。有效批次输出完整汇总后退出 0，包括含失败项的批次；输入/认证初始化等批次级错误退出非零。
+顶层 `schemaVersion: "1.0"`、`command: "metric.batch-query"`、`status`、`results`。全部完成成功为 `success`，存在失败为 `partial_failure`。默认有效批次输出完整汇总后退出 0，包括含失败项的批次。使用 `--fail-on-error` 时，任一项为 error 都在输出完整 JSON 后以非零退出，成功项仍保留；适用于正式查询和 dry-run，全部 success 或全部 planned 时退出 0。输入/认证初始化等批次级错误退出非零。
 
-每项保留输入 `id`、`metricId`，按输入顺序返回。`status` 为 `success` / `error` / `planned`；成功时 `result` 包含 `resultMode: "inline"`、实际采用的 `valueFormat`、`columns: [{name,role}]`、`rows` 二维数组、`rowCount`、`offset`、`limit`。raw 模式的指标值保持 JSON 数字；formatted 模式的指标值为展示字符串。列名直接来自 BI，角色为 dimension/metric，位置与行值一一对应；不存在以本地化展示字段反推新协议的转换。错误为 `error: {code,message,httpStatus?,businessStatus?}`，已有 HTTP/业务状态直接透传，检查每项错误再分析其余成功结果；后端必需字段缺失、类型或行宽变化报 `METRIC_RESPONSE_INVALID`。
+每项保留输入 `id`、`metricId`，按输入顺序返回。`status` 为 `success` / `error` / `planned`；成功时 `result` 包含 `resultMode: "inline"`、实际采用的 `valueFormat`、`columns: [{name,role}]`、`rows` 二维数组、`rowCount`、`offset`、`limit`。raw 模式的指标值保持 JSON 数字；formatted 模式的指标值为展示字符串。both 模式的 `rows` 与 raw 相同，并额外提供 `formattedRows`（包括空结果时的 `[]`），与 rows 共用列、排序和分页；计算读取 rows，展示读取 formattedRows。其它模式不输出 formattedRows。列名直接来自 BI，角色为 dimension/metric，位置与行值一一对应；不存在以本地化展示字段反推新协议的转换。错误为 `error: {code,message,httpStatus?,businessStatus?}`，已有 HTTP/业务状态直接透传，检查每项错误再分析其余成功结果；后端必需字段缺失、类型或行宽变化报 `METRIC_RESPONSE_INVALID`。
 
 原生执行 `timingScope: "native"`，顶层提供 `durationMs`、`concurrencyLimit`、`requestCount`（逻辑 BI 调用数，包含详情、会话和取数，认证重试不计）；每项基础查询通常 3 次调用，显式维度或排序时通常 5 次。每项提供 UTC `startedAt`、`finishedAt`、`durationMs`，可据此检查重叠。
 

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

@@ -301,7 +301,9 @@ guancli metric query <metric_id> --profile default --dim "订单日期 toMonth"
 | 空值 | `IS_NULL`、`NOT_NULL` |
 | 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |
 
-`--filter` 不接受 SQL/数学符号。固定映射为 `= -> EQ`、`>= -> GE`、`<= -> LE`；其他条件同样从上表选择 CLI 操作符。符号写法会直接报错并给出纠正提示。
+`--filter` 支持 `=`、`!=`/`<>`、`<`、`<=`、`>`、`>=`，分别归一为 `EQ`、`NE`、`LT`、`LE`、`GT`、`GE`；原枚举写法继续有效。优先写 `--filter '日期 >= 2026-01-01'`，保留操作符两侧空格并引用整个参数。`--filter-json`、`--filter-file` 和 batch-query 的 `operator` 同样支持符号，规范化输出及 BI 请求仍使用枚举。
+
+`BT` 接受逗号分隔的两个值，也接受两个不含空格的边界用空格分隔，例如 `--filter '日期 BT 20260101 20260131'`。边界本身含空格（如完整日期时间）时继续用逗号分隔；不推测三个或更多空格分段的边界。
 
 示例：
 
@@ -335,7 +337,7 @@ guancli metric query <metric_id> --profile <profile> \
   --limit 100
 ```
 
-出现筛选语法错误后，先执行 `guancli metric query --help` 并按帮助纠正；不要连续尝试 `=`、`==`、`>=` 等相近符号写法。`--columns` 已能在 Go 端稳定裁剪结果列，不要为这一步额外拼 jq。
+出现筛选语法错误后，先执行 `guancli metric query --help` 并按帮助纠正；不要猜测未支持的操作符（例如 `==`）。`--columns` 已能在 Go 端稳定裁剪结果列，不要为这一步额外拼 jq。
 
 结构化条件树示例：
 

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

@@ -34,6 +34,8 @@ guancli etl get <resource_id>          # ETL 详情（含节点、SQL、血缘
 guancli ds get <resource_id>           # 数据集详情（含字段结构、血缘）
 guancli ds get <resource_id> --brief   # 数据集轻量输出（省略 Malloy、血缘、公式详情，节省 token）
 guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、融合等）
+guancli ds get <resource_id> --validate-downstream       # 验证血缘中的下游资源是否仍存在
+guancli ds get <resource_id> --raw --validate-downstream # 在 lineage.downstreamValidation 返回结构化报告
 guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
@@ -41,6 +43,12 @@ guancli page get <resource_id>         # 页面详情（含卡片列表、血缘
 
 **`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。
 
+**`--validate-downstream` 模式**（仅 `ds get`）：按血缘返回顺序串行调用数据集、ETL、页面或卡片详情接口，确认每个下游 ID 当前是否仍存在。只有业务状态 `1002` 或 HTTP 404 会记为 `not_found`；认证失败、其他 HTTP 错误、JSON 解析失败和响应 ID 不一致都会让命令失败，不会误报为“不存在”。未知资源类型记为 `unsupported`，并令报告的 `complete=false`。原始 `lineage.downstream` 不会被删除或改写；`--raw` 下新增的 `lineage.downstreamValidation` 包含 `complete`、`allValid`、`checked`、`valid`、`notFound`、`unsupported` 和逐项 `items`。默认不启用，因此现有 `ds get` / `ds get --raw` 输出保持不变。
+
+该验证单次最多处理 100 个下游资源，按服务端血缘顺序执行，单请求超时 10 秒、总超时 30 秒。它验证的是“血缘 ID 对应资源详情当前可读取”，不替代服务端删除接口对真实依赖、权限和并发变化的最终校验；不能与跳过血缘的 `--brief` 同时使用。
+
+使用 Personal Access Token 时，血缘、页面和卡片详情使用 `BASE/read`；数据集详情使用 `DATASET/read`；ETL 详情使用 `ETL/read`。PAT 创建时权限列表默认为空，`BASE` 基础读取仍按账号角色校验，但数据集和 ETL 读取权限必须显式选入 PAT scope；缺少权限时验证会返回真实鉴权错误并终止。
+
 ## 4. 获取资源具体 URL
 
 ```bash