@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,562 @@
+# 指标与指标树命令参考
+
+来源：语雀《guancli 指标能力使用文档》
+
+本文只记录当前 guancli 指标相关命令、参数和高频示例。使用时替换示例中的 ID 和 profile。
+
+## 全局参数
+
+适用于 `metric` 与 `metric_attribution` 命令：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--profile string` | 使用指定环境配置 |
+| `-f, --format string` | 输出格式：`auto`、`csv`、`expanded`、`table`、`json`，默认 `auto` |
+| `--raw` | 输出服务端原始 JSON，跳过 CLI 解析和格式化 |
+| `--brief` | 轻量输出模式，省略部分高 token 内容 |
+| `-v, --verbose` | 显示详细日志 |
+| `-h, --help` | 查看帮助 |
+
+## metric
+
+入口：
+
+```bash
+guancli metric [command]
+```
+
+子命令：
+
+| 子命令 | 功能 |
+| --- | --- |
+| `project` | 获取指标主题列表 |
+| `search` | 搜索指标 |
+| `get` | 获取指标详情 |
+| `accelerate` | 查询指标查询加速配置 |
+| `by-dataset` | 按数据集 ID 获取直接和下游关联指标 |
+| `query` | 查询指标数据 |
+| `tree` | 获取指标目录树 |
+
+### metric project
+
+获取指标主题列表；传关键词时按主题名称做模糊过滤。
+
+```bash
+guancli metric project [keyword] [flags]
+```
+
+输出中的 `全部指标数` 为主题根目录及其所有子目录累计指标数量。
+
+示例：
+
+```bash
+guancli metric project --profile default
+guancli metric project 经营 --profile default
+guancli metric project 经营 --profile default -f json
+guancli metric project 经营 --profile default --raw
+```
+
+### metric search
+
+搜索指标；传 `[keyword]` 时按指标名称模糊搜索，不传关键词返回所有指标。使用 `--fuzzy` 时，后台会同时按指标名称、业务口径和自定义业务属性值做 OR 模糊搜索。
+
+```bash
+guancli metric search [keyword] [flags]
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `-d, --dir-id string` | 限定搜索主题 ID |
+| `--fuzzy strings` | 名称、业务口径、自定义业务属性统一模糊搜索关键词，可多次指定，也支持逗号、中文逗号、顿号分隔；和 `[keyword]` 互斥 |
+| `--offset int` | 搜索结果分页偏移量，默认 `0` |
+| `--limit int` | 搜索结果数量，默认 `0` 表示全部 |
+| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；默认文本包含血缘，`--brief` 或 `-f json` 不请求血缘 |
+
+`--fuzzy` 语义：
+
+- 多个关键词之间是 OR，命中任意关键词即返回。
+- 对每个指标按优先级返回最高优先级命中：`matched by name` = 1，`matched by desc` = 2，`matched by bizAttr` = 3。
+- 自定义业务属性值统一模糊匹配；后端只匹配启用且可搜索的业务属性。
+- 结果会在原有指标字段基础上增加命中条件、命中优先级和命中关键词。
+- 非 `--raw` 输出会额外查询并返回每个指标关联的查询加速摘要，包括查询加速数量和加速指标 ID/优先级/字段摘要。
+- `--with-detail` 会为当前搜索结果中的每个指标补充与 `metric get <metric_id>` 相同的标准化详情；默认终端输出按指标追加详情，`-f json` 在 envelope 的 `data[]` 中直接返回 canonical 详情字段，不再嵌套中文 `指标详情`。
+- 默认文本详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。`-f json` 不包含且不请求血缘。结果较多时先用 `--limit` 收窄指标数量。
+- `--with-detail` 只补指标详情，不查询指标数据；指标取数仍使用 `metric query`。
+- `--with-detail` 需要组合多个接口的结果，因此不兼容 `--raw`、`-f csv` 和 `-f excel`。
+- `[keyword]` 走旧指标名称搜索接口；`--fuzzy` 走新的统一模糊搜索接口，二者不能同时使用。
+
+候选发现预算与停止条件：
+
+- 用户业务词不能直接命中指标时，一次性准备“原词 + 最多 4 个必要同义词/等价表达”。先 trim、合并连续空白，并按大小写不敏感语义去重；原词必须保留在首位。
+- 把整组关键词放进同一次 `metric search --fuzzy`，例如 `--fuzzy "复购金额,重复购买金额,回购金额"`。不要逐词调用 search，也不要在无结果后通过调换顺序、轻微改写或查询子集重复执行等价搜索。
+- Agent 候选发现预算默认最多 5 个关键词、1 个批量搜索轮次。后端硬上限是 10 个关键词，每个关键词最长 100 个字符；硬上限是接口保护，不是鼓励 Agent 扩大探索范围。
+- 如果单批搜索返回候选，按返回顺序和命中信息列出全部候选，不再发起另一轮同义词搜索；后续是否查询指标数据取决于候选是否唯一以及用户选择。
+- 如果单批搜索无候选，立即结束本轮候选发现。回答必须包含：`attempted_keywords`、`search_scope`、无结果原因“当前可见指标的名称、业务口径和可搜索业务属性均未命中”，以及 `stop_reason=no_candidate_within_budget`。
+- 只有请求本身因可识别的认证、网络或服务错误失败时，才按对应错误恢复流程处理；业务无命中不是重试理由。
+- 不缓存、不持久化、也不跨请求复用“未找到指标”的结论。每个新请求都必须基于当时的指标可见性、权限和指标内容重新判断。
+- 已知指标主题 ID 时用 `-d <metric_topic_id>` 缩小 `search_scope`；未知主题时要说明搜索覆盖当前用户可见的全部指标主题。一次 CLI 调用在未知主题时可能内部扫描多个主题，不能把它表述成一次 HTTP 请求。
+
+回答要求：
+
+- 必须逐条返回命中的指标，至少包含指标 ID、指标名称、状态、类型。
+- 必须明确说明每条结果是通过什么方式命中的：命中条件/字段、命中优先级、命中关键词。
+- 不要把用户输入默认解释为“指标名称精确匹配”。例如用户说“查询 api_test 主题下的啦啦啦指标”，应表述为“用 `--fuzzy 啦啦啦` 在 api_test 主题内搜索，以下指标命中”，再说明是命中名称、业务口径还是业务属性。
+- 如果同一关键词命中多个指标，必须列出所有命中指标，不要只挑一个继续做详情或数据查询，除非用户明确要求。
+
+示例：
+
+```bash
+guancli metric search --fuzzy 订购 --profile default -d <metric_topic_id>
+guancli metric search --fuzzy 订购 --profile default -f json
+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
+```
+
+#### 可复制模板：搜索并查看适用维度
+
+优先让 guancli 直接返回标准化详情，终端阅读不需要 jq：
+
+```bash
+guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief
+```
+
+确实需要机器处理 JSON 时，先保存成功输出再单独执行 jq，避免管道末端成功掩盖 guancli 失败：
+
+```bash
+guancli metric search --fuzzy <关键词> --profile <profile> --limit 5 --with-detail --brief -f json > metric_search.json &&
+  jq '.data[] | {id, name, dimensions, timeField}' metric_search.json
+```
+
+中文 key 必须使用 `.["字段名"]`，嵌套 key 必须逐级引用；不要写 `.指标详情.适用维度`。必要解析不要添加 `2>/dev/null`。如果命令失败，先保留 stderr 和非零退出码并查看 `guancli metric search --help`，不要继续猜参数。
+
+### metric get
+
+获取指标详情，包括元数据、数据口径、数据集、权限、统计信息、自定义属性、查询加速和血缘关系。
+
+非 `--raw` 输出会额外查询并返回该指标关联的查询加速列表；`--raw` 保持服务端指标详情接口原始响应。
+
+```bash
+guancli metric get <metric_id> [flags]
+```
+
+示例：
+
+```bash
+guancli metric get <metric_id> --profile default
+guancli metric get <metric_id> --profile default --brief
+guancli metric get <metric_id> --profile default -f json
+guancli metric get <metric_id> --profile default --raw
+```
+
+#### 可复制模板：单个指标详情与适用维度
+
+只供 Agent 阅读时直接使用 brief 输出：
+
+```bash
+guancli metric get <metric_id> --profile <profile> --brief
+```
+
+需要结构化提取时拆成两步：
+
+```bash
+guancli metric get <metric_id> --profile <profile> --brief -f json > metric_detail.json &&
+  jq '.data.dimensions' metric_detail.json
+```
+
+### metric accelerate
+
+查询指标的查询加速配置。后端取数时会按 `acceleratePriority` 从高到低尝试加速指标；只有当查询维度和筛选维度都能被加速指标适用维度覆盖时才会命中。
+
+`acceleratePriority` 是后端排序权重，数字越大越先尝试；页面上的“查询顺序”是按这个实际尝试顺序重新编号后的展示序号。因此 `acceleratePriority=4` 可能对应页面查询顺序 1。向用户解释命中计划时，优先使用页面查询顺序口径；如需换算，先执行 `metric accelerate list`，按 `acceleratePriority` 倒序排序后编号。
+
+```bash
+guancli metric accelerate list <metric_id> [flags]
+```
+
+示例：
+
+```bash
+guancli metric accelerate list <metric_id> --profile default
+guancli metric accelerate list <metric_id> --profile default -f json
+guancli metric accelerate list <metric_id> --profile default --raw
+```
+
+> 查询加速创建、编辑、删除和优先级调整使用 `guanmetric accelerate`。
+
+### metric by-dataset
+
+按数据集 ID 获取关联指标。命令会跨指标主题扫描指标，并结合指标详情和指标血缘判断该数据集关联的指标；结果包含直接使用该数据集的原子指标，也包含继续引用这些指标的复合指标和衍生指标。
+
+```bash
+guancli metric by-dataset <ds_id> [flags]
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `-d, --dir-id string` | 限定搜索主题 ID |
+
+示例：
+
+```bash
+guancli metric by-dataset <ds_id> --profile default
+guancli metric by-dataset <ds_id> --profile default -f json
+guancli metric by-dataset <ds_id> --profile default -d <metric_topic_id>
+guancli metric by-dataset <ds_id> --profile default --raw
+```
+
+### metric query
+
+查询指标数据，支持维度、筛选、排序、列筛选和行数限制。默认按指标配置的 `format` 输出数值；查询响应携带更具体的列级格式时优先使用列级格式。泛化查询参数见 `metric-generic-query.md`。
+
+格式化覆盖数值、货币、百分比、高级格式，以及小数位、千分位、数量级单位、前后缀等配置。没有有效指标格式时才使用 `--precision` 回退。需要保留原始数值时使用 `--value-format raw`；它与全局 `--raw` 不同：前者仍输出标准表格/JSON/CSV/Excel，只是不应用数值展示格式，后者直接返回后端原始响应。
+
+非 `--raw` 输出会展示本次查询是否命中查询加速：summary 中有 `查询加速`，数据行中有 `_queryAccelerate`。命中时展示源指标 ID、加速指标 ID 和后端排序权重，例如 `metric_xxx->acc_xxx(优先级4)`；未命中时显示 `否`。若后端版本尚未返回查询加速 metadata，则显示 `未知: 后端未返回`。
+
+注意：这里的 `优先级N` 是 `acceleratePriority` 原始值，不是页面“查询顺序”。向用户汇报时不要直接说“命中优先级第 N 个”，应在需要时结合 `metric accelerate list` 的完整列表，按 `acceleratePriority` 倒序换算成页面查询顺序。
+
+回答要求：
+
+- 必须单独说明本次查询加速命中情况。
+- 命中时必须明确列出命中的加速指标 ID、对应源指标 ID 和页面查询顺序；如果只拿到 `_queryAccelerate` 里的 `优先级N`，需说明这是后端排序权重，数字越大越先尝试。
+- 未命中时说明未命中查询加速。
+- 如果是 `未知: 后端未返回`，只能说明后端未返回命中 metadata，不能推断是否命中。
+
+```bash
+guancli metric query <metric_id> [flags]
+```
+
+专属参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--limit int` | `50` | 数据行数限制 |
+| `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔；日期子类型写作 `"订单日期 toMonth"` |
+| `--filter stringArray` | 无 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定；列名必须是该指标详情中的字段（适用维度 / 时间维度 / 指标字段名），未命中返回 `METRIC_UNSUPPORTED_DIMENSION`，不会静默忽略 |
+| `--filter-json stringArray` | 无 | 结构化筛选 JSON，可重复；与 --filter/--filter-file 互斥；支持嵌套 AND/OR 条件树；字段未命中该指标字段时在解析阶段返回 `FILTER_UNKNOWN_FIELD` |
+| `--filter-file string` | 无 | 从 JSON 文件读取一棵结构化条件树；与 `--filter`、`--filter-json` 互斥 |
+| `--combine-type string` | `AND` | 多条件组合方式：`AND` 或 `OR` |
+| `--dry-run` | `false` | 只返回规范化查询计划、字段类型和稳定错误码，不执行指标取数；必须同时使用 `-f json`，且不支持普通文件或 stderr 输出目标 |
+| `--explain-requests` | `false` | 只读解析真实执行链路及最终 method/path/body；调用真实 request builder，但不创建 edit session、不 POST、不取数；必须同时使用 `-f json` |
+| `--sort-asc string` | 无 | 按列升序排序；排序目标可以是适用维度 / 时间维度、指标名本身、保存卡片中真实存在的高级计算列，或泛化结果列名 `<指标名>_<后缀>`（`_yoy`/`_mom`/`_qoq`/`_wow`/`_dod`/`_ytd`/`_qtd`/`_mtd`/`_wtd`/`_dtd`/`_last`/`_recent_*`/`_percentage`/`_rank`）；日期子类型使用与 `--dim` 相同的粒度表达式；未命中返回 `METRIC_UNSUPPORTED_DIMENSION`；与 `--sort-desc` 互斥 |
+| `--sort-desc string` | 无 | 按列降序排序；合法排序目标与 `--sort-asc` 相同（适用维度 / 时间维度、指标名、泛化结果列名）；日期子类型使用与 `--dim` 相同的粒度表达式；未命中返回 `METRIC_UNSUPPORTED_DIMENSION`；与 `--sort-asc` 互斥 |
+| `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
+| `--precision int` | `6` | 没有有效指标格式时的数值最大小数位数；传 `-1` 保留原始精度 |
+| `--value-format string` | `formatted` | `formatted` 按指标格式输出；`raw` 保留原始数值 |
+| `-o, --output string` | 无 | 将查询结果写入文件；未指定且结果超过 1000 行时自动写入文件 |
+
+`metric search/get/tree/query -f json` 都返回带版本号的稳定 JSON envelope，当前 canonical 契约版本为 `1.0`，公共字段为 `schemaVersion`、`command`、`resultMode`、`rowCount`。内联结果在 `data`，文件结果在绝对 `path`；query 还返回 `columns`。版本演进读取响应体中的 `schemaVersion`，不会增加 `json-v2` 一类输出格式。旧对象/数组入口已移除，这是输出契约迁移，旧脚本必须同步适配，详见 [迁移清单](metric-json-migration.md)。未指定 `-o/--output` 且查询结果超过 1000 行时，默认模式仍自动写 CSV 并输出原中文提示；使用 `-f json` 时写 JSON 文件，stdout 返回 `resultMode=file` envelope。自动文件名带唯一后缀，避免同秒并发或重试覆盖已有结果。
+
+search/get 的 `data` 使用直接由后端字段构造的 canonical 模型：`id/name/status/type/description/projectId/directoryId/dataset/dimensions/timeField/measureFields/match/accelerations/statistics/permissions/customAttributes/updatedAt`。`status/type` 保留 `PUBLISHED/ATOMIC` 等机器枚举，不使用“在线/原子指标”等中文展示标签；`match.priority` 保留后端 `name=1/desc=2/bizAttr=3`，精确/模糊由 `match.mode` 单独表达。未知后端字段被忽略，`id/name` 缺失时明确返回契约错误。可选标量和对象的缺失或 `null` 统一省略；`dimensions/timeField/measureFields/customAttributes` 及 `accelerations[].priority` 区分缺失、`null`、空值或零值，`accelerations` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。tree 的节点固定使用 `id/name/type/children`，`--brief` 只省略计数和权限，不省略节点身份。中文展示字段只属于默认输出，不属于 envelope 契约。canonical 模型不包含血缘，因此 `--with-detail -f json` 不请求血缘；文本详情可查看血缘。query dry-run 不查询加速配置，此时省略 `metric.accelerations`，不能把省略解释成无加速配置。
+
+query dry-run 的 `dimensions` 保留用户输入的字符串数组，并额外返回 `resolvedDimensions`。后者是 CLI 最终发送给查询接口的维度对象，可用于确认日期子类型是否解析到了预期的 `fdId`、`fdType=SUB_DATE`、`parentFdName` 和 `granularity`。
+
+筛选字段通常必须使用指标详情中的原始字段名。例外是指标详情 `publicDimensionMap` 中能唯一映射到一个适用维度的公共维度名：维度、日期粒度、排序和筛选均可使用该名称，CLI 仍发送物理字段 `fdId`，并在维度 alias 中保留公共维度名；同名映射到多个物理字段时会拒绝猜测。指标名仅作为排序伪字段、没有对应真实字段 `fdId` 时不能筛选；若 `fdInfos` 本身存在同名原始字段和真实 `fdId`，该字段仍可筛选。排序目标只在来自指标详情、当前泛化参数，或保存卡片编辑配置中真实带 `advCalc` 的字段时通过；仅与指标名具有相同前缀不能证明字段有效。dry-run 只读取指标详情，因此不会猜测保存卡片高级计算列有效；真实执行会在修改隔离编辑会话前读取既有卡片编辑配置并校验。
+
+### 日期子类型维度
+
+日期维度可在字段名后增加粒度修饰符：
+
+| 用户意图 | 修饰符 | 粒度 |
+| --- | --- | --- |
+| 按年 | `toYear` | `YEAR` |
+| 按季度 | `toQuarter` | `QUARTER` |
+| 按月 | `toMonth` | `MONTH` |
+| 按周 | `toWeek` | `WEEK` |
+| 按星期 | `toDayOfWeek` | `DAYOFWEEK` |
+| 按日 | `toDate` / `toDay` | `DAY` |
+| 按小时 | `toHour` | `HOUR` |
+| 按分钟 | `toMinute` | `MINUTE` |
+| 按秒 | `toSecond` | `SECOND` |
+
+CLI 以指标详情返回的日期子字段为准；目标粒度不存在时返回 `METRIC_UNSUPPORTED_DATE_GRANULARITY`，不会伪造字段 ID。DATE 字段的 DAY 使用基础日期字段，TIMESTAMP 的 DAY 使用日期子字段。完整字段名精确匹配优先，因此不会破坏名称本身以 `toMonth` 等文本结尾的历史维度。
+
+Agent 生成命令时必须区分时间范围与分组粒度：
+
+- “本月/上月/某个月销售额”只表示筛选范围，不自动增加月维度。
+- “按月/每月/月度趋势/逐月销售额”表示分组粒度，使用 `--dim "<时间维度> toMonth"`。
+- “近 12 个月每月销售额”同时使用月维度和时间范围筛选。
+- 时间字段名从指标详情的 `timeField.name` 获取，不要默认写成“日期”。
+
+示例：
+
+```bash
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth"
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --sort-asc "订单日期 toMonth"
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --dry-run -f json
+```
+
+筛选操作符：
+
+| 类型 | 操作符 |
+| --- | --- |
+| 比较 | `EQ`、`NE`、`LT`、`LE`、`GT`、`GE` |
+| 区间 | `BT` |
+| 集合 | `IN` |
+| 空值 | `IS_NULL`、`NOT_NULL` |
+| 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |
+
+`--filter` 支持 `=`、`!=`/`<>`、`<`、`<=`、`>`、`>=`，分别归一为 `EQ`、`NE`、`LT`、`LE`、`GT`、`GE`；原枚举写法继续有效。优先写 `--filter '日期 >= 2026-01-01'`，保留操作符两侧空格并引用整个参数。`--filter-json`、`--filter-file` 和 batch-query 的 `operator` 同样支持符号，规范化输出及 BI 请求仍使用枚举。
+
+`BT` 接受逗号分隔的两个值，也接受两个不含空格的边界用空格分隔，例如 `--filter '日期 BT 20260101 20260131'`。边界本身含空格（如完整日期时间）时继续用逗号分隔；不推测三个或更多空格分段的边界。
+
+示例：
+
+```bash
+guancli metric query <metric_id> --profile default
+guancli metric query <metric_id> --profile default --dim 省份 --limit 10
+guancli metric query <metric_id> --profile default --dim "省份、城市" --limit 20
+guancli metric query <metric_id> --profile default --dim "订单日期 toMonth" --sort-asc "订单日期 toMonth"
+guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省"
+guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR --dry-run -f json
+guancli metric query <metric_id> --profile default --filter-json '{"field":"省份","operator":"IN","values":["河南省","青海省"]}' --dry-run -f json
+guancli metric query <metric_id> --profile default --filter-file filters.json --dry-run -f json
+guancli metric query <metric_id> --profile default --dim 省份 --sort-desc 订购数量 --explain-requests -f 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
+```
+
+多分支 OR 的 dry-run 会返回 `valid=true`、`executable=false`、`requestCount=0` 和错误码 `FILTER_OR_EXECUTION_UNSUPPORTED`。当前指标取数接口不能在单次请求中无损表达这类 OR，真实执行会在取数前拒绝，不会拆成多次聚合查询后拼接。
+
+参数模式、互斥/依赖关系、card 与 `metric-data/v2` 的完整请求体结构见 [指标查询参数模式与请求体](metric-query-recipes.md)。Agent 执行任意单条查询前都先使用同参数的 `--explain-requests -f json`，检查 `data.requestPlan.requests[]`；只有计划有效、可执行且 body 符合业务意图时才移除 explain。`batch-query` 使用独立批量契约且不支持 explain。
+
+#### 可复制模板：筛选并裁剪查询结果
+
+```bash
+guancli metric query <metric_id> --profile <profile> \
+  --dim <维度名> \
+  --filter "日期 GE 2026-01-01" \
+  --filter "地区 EQ 华东" \
+  --columns "日期,地区,<指标名>" \
+  --limit 100
+```
+
+出现筛选语法错误后，先执行 `guancli metric query --help` 并按帮助纠正；不要猜测未支持的操作符（例如 `==`）。`--columns` 已能在 Go 端稳定裁剪结果列，不要为这一步额外拼 jq。
+
+结构化条件树示例：
+
+```json
+{
+  "combineType": "AND",
+  "conditions": [
+    {"field": "省份", "operator": "IN", "values": ["浙江省", "江苏省"]},
+    {
+      "combineType": "OR",
+      "conditions": [
+        {"field": "销售额", "operator": "GE", "value": 100},
+        {"field": "销售额", "operator": "BT", "values": [200, 300]}
+      ]
+    }
+  ]
+}
+```
+
+CLI 会把条件树确定性展开为“组内 AND、组间 OR”的查询计划，并在 dry-run 的 `requestCount` 和 `normalizedQueries` 中展示。为避免组合爆炸，最多展开 64 个查询组；超过时返回 `FILTER_TOO_MANY_QUERY_GROUPS`。其他结构化校验错误同样使用稳定的 `FILTER_*` code。
+
+### metric tree
+
+获取指标目录树。默认输出树形结构，最外层展示指标主题。`-d / --dir-id <topic-id>` 仅读取所选主题的目录树：保留原主题列表的权限过滤和原始输出形状，不读取其他主题的目录树；主题不存在或不在当前身份的主题列表中时返回空结果。
+
+```bash
+guancli metric tree [flags]
+```
+
+示例：
+
+```bash
+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`。
+
+## metric_attribution
+
+入口：
+
+```bash
+guancli metric_attribution [command]
+```
+
+子命令：
+
+| 子命令 | 功能 |
+| --- | --- |
+| `tree` | 获取指标树目录树 |
+| `search` | 搜索指标树 |
+| `get` | 获取指标树详情 |
+| `subtree` | 获取指标树中指定指标的拆解子树 |
+| `query` | 查询指标树贡献数据 |
+
+### metric_attribution tree
+
+获取指标树目录树。
+
+```bash
+guancli metric_attribution tree --profile test43
+guancli metric_attribution tree --profile test43 --brief
+guancli metric_attribution tree --profile test43 -f json
+guancli metric_attribution tree --profile test43 --raw
+```
+
+### metric_attribution search
+
+搜索指标树；不传关键词返回所有指标树。
+
+```bash
+guancli metric_attribution search [keyword] [flags]
+```
+
+示例：
+
+```bash
+guancli metric_attribution search 贡献率 --profile test43
+guancli metric_attribution search --profile test43
+guancli metric_attribution search 贡献率 --profile test43 -f json
+guancli metric_attribution search 贡献率 --profile test43 --raw
+```
+
+### metric_attribution get
+
+获取指标树详情，包括指标树元数据、根指标、时间对比配置、维度拆解配置和指标拆解配置。
+
+```bash
+guancli metric_attribution get <resource_id> [flags]
+```
+
+示例：
+
+```bash
+guancli metric_attribution get <metric_tree_id> --profile test43
+guancli metric_attribution get <metric_tree_id> --profile test43 -f json
+guancli metric_attribution get <metric_tree_id> --profile test43 --raw
+```
+
+### metric_attribution subtree
+
+获取某棵指标树已保存配置中的指标拆解子树。该命令只裁剪 `metricRelationTree` 中已有的拆解关系，不会沿全局资源血缘动态推导额外下游指标。
+
+```bash
+guancli metric_attribution subtree [metric_tree_id] [metric_id] [flags]
+```
+
+专属参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `--tree-id string` | 指标树 ID |
+| `--tree-name string` | 指标树名称，需唯一匹配 |
+| `--metric-id string` | 指标拆解起点指标 ID；未指定时默认使用指标树根指标 |
+| `--metric-name string` | 指标拆解起点指标名称，需在该指标树拆解配置中唯一匹配 |
+
+示例：
+
+```bash
+guancli metric_attribution subtree --tree-id <metric_tree_id> --metric-id <metric_id> --profile test43
+guancli metric_attribution subtree <metric_tree_id> <metric_id> --profile test43
+guancli metric_attribution subtree --tree-name "销售额指标树" --metric-name "订单数" --profile test43
+guancli metric_attribution subtree --tree-id <metric_tree_id> -f json --profile test43
+guancli metric_attribution subtree --tree-id <metric_tree_id> --raw --profile test43
+```
+
+### metric_attribution query
+
+对指定指标树执行贡献分析，支持指标拆解、单维度拆解和全维扫描。
+
+```bash
+guancli metric_attribution query <metric_tree_id> [flags]
+```
+
+专属参数：
+
+| 参数 | 默认值 | 适用 target | 说明 |
+| --- | --- | --- | --- |
+| `--target string` | `index` | 全部 | 分析目标：`index`、`dim`、`scan` |
+| `--dim string` | 无 | `dim` | 指定维度名 |
+| `--scan-dim strings` | 无 | `scan` | 指定扫描维度，可多次传入 |
+| `--exclude-dim strings` | 无 | `scan` | 排除扫描维度，可多次传入 |
+| `--period string` | 使用指标树配置 | 全部 | 本期时间，格式 `YYYY-MM-DD` |
+| `--last-period string` | 使用指标树配置 | 全部 | 上期时间，格式 `YYYY-MM-DD` |
+| `--time-comparison-json string` | 无 | 全部 | 原始时间对比配置 JSON，优先级高于默认配置 |
+| `--sort string` | `desc` | 全部 | 排序方式：`asc` 或 `desc` |
+| `--limit int` | 无 | `index`、`dim` | 返回条数限制 |
+| `--group-limit int` | `5` | `scan` | scan 模式下每个维度返回 Top N |
+| `--filter stringArray` | 无 | 全部 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
+
+示例：
+
+```bash
+guancli metric_attribution query <metric_tree_id> --profile test43 --target index
+guancli metric_attribution query <metric_tree_id> --profile test43 --target index --limit 5
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --limit 10
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --scan-dim 业务员 --scan-dim 商品名称
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --exclude-dim 客户编号
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --group-limit 3
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --period 2023-07-01 --last-period 2023-06-01
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --filter "业务员 EQ Lela Kemmer"
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --sort asc
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 -f json
+guancli metric_attribution query <metric_tree_id> --profile test43 --target scan -f csv
+guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --raw
+```
+
+### 查询结果消费
+
+机器查询统一用 `-f json`。`query` 的 `data` 和文件载荷都是行对象数组；search 的 `data` 是指标数组，get/tree 的 `data` 是单个对象。`rowCount` 属于 stdout envelope，不能从行数组读取。query 的 `columns` 保留真实业务列名，可以是中文；search/get 的 `id/name/dimensions` 是 canonical 英文字段。
+
+下面示例在 Skill 目录执行；先确认 CLI 成功，再解析 stdout，stderr 单独保存：
+
+```bash
+# 成功后 query-rows.json 统一为行数组，不论原结果是 inline 还是 file。
+bash references/examples/metric-query.sh <metric_id> <profile> &&
+  jq '.[] | .["组织"]["名称"]' query-rows.json
+```
+
+`examples/metric-query-rows.py` 检查 schemaVersion、command、resultMode 和行数；file 模式只从 envelope 的绝对 `path` 读取，不无条件遍历 `data`。上例中文嵌套字段仅演示引用语法，实际字段以 `columns`/数据为准。每一个中文层级都使用 `["字段名"]`。
+
+#### 先发现列，再选择
+
+禁止在加工脚本中硬编码指标展示列名，或根据指标名称、高级计算后缀、列位置猜列。先检查 `columns` 和行对象 keys，并按当前业务意图确认候选；存在多个候选时不能自动选第一个。下面参数属于 Python recipe，不是 query 命令的新参数：
+
+```bash
+# 复用已成功查询的 envelope，不为发现列重复请求 BI。
+python3 references/examples/metric-query-rows.py query-envelope.json --list-columns
+# 阅读实际列集合并确认业务含义后，替换占位符；不要原样执行。
+python3 references/examples/metric-query-rows.py query-envelope.json --column "<已确认的实际列名>"
+```
+
+`--column` 可重复传入经过业务确认的备选名称；与实际列精确匹配后必须恰好剩一列。零匹配、多匹配、重复列名或某行缺少该列都会非零退出，stderr 返回实际列集合，stdout 不输出部分结果；不做近似匹配、不触发 KeyError、不把缺失当 null。真正的 null 保留为 null。选择成功仍输出行对象数组；不传新增参数时保持原有整行输出。空结果可发现声明列，但不能据此宣称存在业务数据。
+
+### 日期与 IN 使用同一种筛选输入
+
+先通过 get 确认日期、城市存在且类型相符。完整条件树见 `examples/metric-date-in.json`：
+
+```bash
+guancli metric query <metric_id> --profile <profile> --filter-file references/examples/metric-date-in.json --dry-run -f json
+# 或把两个条件都放入可重复的 filter-json，不要再混入普通 --filter：
+guancli metric query <metric_id> --profile <profile> \
+  --filter-json '{"field":"日期","operator":"BT","values":["2026-01-01","2026-01-31"]}' \
+  --filter-json '{"field":"城市","operator":"IN","values":["杭州","上海"]}' --dry-run -f json
+```
+
+普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一。dry-run 成功只表示计划校验通过，实际执行仍由 BI 决定。
+# 同轮独立查询
+
+多项已确定、彼此独立且参数能被 batch 完整表达的基础指标查询，使用 `metric batch-query --input queries.json`，禁止 Shell 循环逐条取数。同比、XTD、recent、占比、排名等高级计算继续使用单条 `metric query`；同轮其余基础查询仍单独组成 batch。详见 [批量协议与示例](metric-batch-query.md)。依赖结果的后续查询在下一轮提交。