@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guancli/SKILL.md

@@ -0,0 +1,342 @@
+---
+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 整包”，或要根据第三方接口文档创建、配置、调用“请求转发 / 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.
+---
+
+# guancli
+
+guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建、发布与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
+
+## 何时优先使用
+
+- 用户希望分析观远 BI 项目的 ETL 逻辑、数据集结构、页面/仪表板内容。
+- 用户提供了 BI 系统 URL，需要连接并获取数据。
+- 用户要快速拿到 ETL 清单、节点 SQL、输入输出数据集血缘。
+- 用户在排查 BI 资源配置、页面卡片定义、接口返回或 lineage 关系。
+- 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
+- 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
+- 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
+- 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
+- 用户要创建、发布或更新超级应用 / SuperApp，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户给出第三方接口文档，希望转换成观远 BI 请求转发配置、创建路由或生成调用代码。
+- 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
+- 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
+- 用户已经取得本地 CSV/JSON，需要稳定处理 BOM/null/嵌套字段、对齐两个结果集、执行安全四则运算，或做通用分组 TopN/占比；不再临时生成 Python 拼接脚本。
+
+如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
+
+## 能力边界
+
+guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建、发布与整包下载。其他写入类任务由专用 skill 负责：
+
+| 任务 | 应使用的工具 |
+|---|---|
+| ETL 新建 / 编辑 / 保存 / 执行 | `guanetl` |
+| 数据源 / 数据集 CRUD / 增量 / 调度 | `guands` |
+| 看板 / 卡片构建 / 页面**内容**修改 / 页面发布 / 截图 | `guanvis` |
+| 页面**本身**的删除 / 改名 / 移动 | `guanvis page` |
+| 页面目录（PAGE 目录树）创建 / 改名 / 移动 / 删除 | `guanvis dir` |
+| 指标创建 / 编辑 / 删除、指标主题 / 目录创建、公共维度管理、指标 Excel 标准化 | `guanmetric` |
+
+> guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
+>
+> 页面的**内容**（卡片、布局、筛选器）和页面**本身**的删除、改名、移动都归 `guanvis`（见「页面写操作不在 guancli」）。页面所在的**目录**归 `guanvis dir`——guancli 只提供只读的 `page get/search/tree`。
+
+**编辑红线（编辑 ≠ 删除重建）**：用户要求编辑/重命名已有 BI 资源（账号、数据集、表单、ETL、页面、卡片、指标等）时，必须使用**原地更新**能力：页面的改名和移动路由到 guanvis（`guanvis page rename` / `guanvis page move`，硬约束见 guanvis skill），其余路由到对应专用 skill；对应能力不存在时直接告知用户 CLI 暂不支持。**禁止**用"删除旧资源 + 新建同名资源"来模拟编辑——资源 ID 变化会导致下游引用断链，权限配置、调度、历史数据会静默丢失。改名不要用"删页面 + 重新发布"，换目录不要用"删掉再发到新目录"。表单**数据行**更新用 `form update`，不要用"删行 + 插行"代替（除非用户明确要求）。
+
+## 先做判断
+
+1. 认证检查和 BI 查询都会联网，密码 profile 或服务端轮换 token 时可能更新本地 token；只在当前任务允许认证刷新时执行。
+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` 再按需加深）。
+8. 用户给的是业务目录名而不是数据集名时，先 `ds tree` 定位目录，再在目录内按真实表名搜索，或从已有 `page/card` 反查 `dsId`。
+9. 用户要查看/分析某个页面（仪表板）上的卡片数据时，默认所见即所得：用 `card preview <cd_id> --with-default-filters` 应用页面筛选器默认值（含 FIRST_PICK / 日历 MAX 的运行态求值和级联），并把结果页脚 `筛选:` 行（stderr 也有同样说明）里的生效条件原样带进结论，标明数据是筛选后的而非全量；`筛选: 无（未应用页面筛选器默认值…）` 表示裸取数。用户明确不要页面筛选、或已自行给出筛选条件时才裸取数；报错“暂不支持”时如实告知该筛选器未生效，不要静默改成裸取数。卡片属于多个页面时，根据报错列出的候选页面请用户确认，再传 `--page-id <pg_id>`。
+
+## 按需读取资料
+
+| 场景 | 先读 |
+|---|---|
+| 首次登录、PAT、profile、Token、配置文件 | `references/auth-and-config.md` |
+| ETL / 数据集 / 页面搜索、get、血缘、输出说明、故障排查 | `references/resource-query.md` |
+| 数据集 preview、card preview、筛选、日期粒度、排序、动态参数、动态维度、输出格式 | `references/preview-and-output.md` |
+| 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` |
+
+## 常用查询入口
+
+**同轮指标查询规则**：本轮已确定、彼此互不依赖，且参数能被 `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)。复用已确认的输入契约，缺少信息或遇到参数错误时再读取该参考，不固定增加帮助查询。
+
+用户明确要求比较两组指标数值是否一致时，不能把两次查询默认返回的前 50 行按数组位置直接比较。新旧指标必须使用相同的显式维度/日期粒度、筛选范围、排序、分页和 `valueFormat=raw`；结果按维度组合键对齐后再比较指标值。任一查询失败、结果可能截断、维度键不唯一或覆盖范围不一致时，结论只能是 `inconclusive`，不能写成 `different`。这属于显式的数值对比任务，不是每次指标创建都要执行的默认验收；完整 recipe 见 [metric-batch-query.md](references/metric-batch-query.md) 的“指标数值等价对比”。
+
+**减少模型往返**：同一授权和查询轮次内，已确认的指标口径、字段与能力直接复用。将确定性的文件读取、状态检查、裁剪和计算合并成一次本地执行，返回需要判断的摘要；仅在结果引入新决策时再规划下一轮。只读查询可与结果保存、检查和摘要合并执行；确认查询成功后再消费，不为补齐运行轨迹拆分命令或重跑查询。
+
+```bash
+guancli etl tree --max-depth 2
+guancli ds tree --max-depth 2
+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 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>
+# 卡片 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 -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
+guancli insight page <page_id>
+guancli insight card <cd_id> --page-id <page_id>
+```
+
+> `ds get` / `page get` / `etl get` 拉取完整资源详情（默认还会附血缘），在大环境上
+> 可能明显偏慢甚至超时。只想了解数据集字段结构（做卡片/仪表板前的探查）时，
+> 优先用 `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
+
+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`。
+
+## 指标关键规则
+
+- **先按下面的命令契约生成，不要猜 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` 单独返回后端原始协议。
+  - 比较筛选优先用带空格的符号写法，例如 `--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 解码器。不要用会让末端命令成功掩盖上游失败的管道；允许组合执行时用 `&&` 衔接“输出到文件 → 解析摘要”，不为读取文件另起一轮推理，必须使用管道时先启用 `set -o pipefail`。
+  - 同类语法错误只允许出现一次；第一次失败后先执行对应命令的 `--help` 或读取本 Skill 的参考文档，再按真实契约纠正，不连续尝试相近写法。
+- 普通 `--filter`、可重复 `--filter-json`、单个 `--filter-file` 三选一，禁止混用。复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树。Agent 执行任意单条 `metric query`（包括无参数的基础查询）前都必须先用同一组查询参数追加 `--explain-requests -f json`，核对真实接口顺序和最终 request body；只有 `valid=true`、`executable=true` 且 body 符合业务意图时，才移除 explain 执行真实查询。`batch-query` 是独立批量契约，不支持 explain，不套用这条单条查询门禁；它仍按上文同轮批量规则使用。只需人工快速检查维度/筛选时可用 `--dry-run -f json`，但不能替代 Agent 的 explain-first 门禁。explain 会调用与真实执行相同的 request builder：泛化查询给出最终 `metric-data/v2` body，基础查询只读保存的 card edit meta 后给出完整 session/modify/data 计划；它不创建 edit session、不执行 POST、不取数。完整模式矩阵见 `references/metric-query-recipes.md`。dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标；保存卡片高级计算列不在指标详情中，因此这类排序候选在 dry-run 中不会被猜测为有效，explain/真实执行会读取既有 card 配置校验。不支持的 `--dim`、普通 `--filter` 的字段、`--sort-asc`/`--sort-desc` 的字段都按指标详情中的字段（适用维度 / 时间维度 / 指标字段名）校验，未命中返回 `METRIC_UNSUPPORTED_DIMENSION`；结构化 `--filter-json`/`--filter-file` 在解析阶段按同一份字段集合校验，未命中返回 `FILTER_UNKNOWN_FIELD`。两类错误都不会静默忽略条件或透传未知字段。普通展示别名只对 `--dim` 与排序生效；若指标详情的 `publicDimensionMap` 把唯一公共维度名映射到一个适用维度，则 `--dim`、排序和筛选也可使用该公共维度名，CLI 会保留物理 `fdId` 并把公共维度名作为 alias；同名映射到多个物理字段时拒绝猜测。仅由 CLI 为排序注入、以指标 ID 充当 `fdId` 的“指标名伪字段”不能用于筛选，若指标详情的 `fdInfos` 本身含同名原始字段和真实 `fdId`，仍可正常筛选。`--sort-asc`/`--sort-desc` 额外接受保存卡片中真实存在的高级计算列，以及泛化查询的结果列名 `<指标名>_<后缀>`（`_yoy`/`_mom`/`_qoq`/`_wow`/`_dod`/`_ytd`/`_qtd`/`_mtd`/`_wtd`/`_dtd`/`_last`/`_recent_*`/`_percentage`/`_rank`）。遇到这些错误时先用 `guancli metric get` 读取适用维度再改字段。条件组使用 `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、指标名称、命中条件/字段、命中优先级、命中关键词；不要把用户输入默认解释为指标名称精确匹配。如果结果中有“命中条件”“命中优先级”“命中关键词”列，必须原样纳入结论。
+- 按数据集反查指标用 `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 模板初始化项目时，使用：
+
+```bash
+guancli app create --name <project_name> --path <parent_dir>
+```
+
+- `--name` 是项目名称，`--path` 是项目所在的父目录；信息不全时先确认项目名称和目标目录。
+- 该命令会下载 SuperApp 模板并创建项目目录，随后尝试复制 `.env.template`、更新 `package.json` 名称、初始化 git，并根据模板情况执行 `setup.sh` 或 `npm install` + 启动本地 dev server。
+- 如果用户只是要创建本地 SuperApp 模板项目，不需要先做 BI 资源查询；直接给出或执行 `guancli app create`。
+
+当用户要发布或更新 SuperApp 时，使用：
+
+```bash
+guancli app publish --path <project_dir> --app-id <appId>
+guancli app publish --path <project_dir> --update-if-exists
+guancli app publish --path <project_dir> --app-id <appId> --overwrite-settings
+```
+
+- 更新已有 SuperApp 时，CLI 会在构建后检查实际 `dist/settings.json`。交互终端会询问：“是否覆盖线上 `settings.json`？”发布应用的授权不等于覆盖线上设置的授权。
+- 只有用户明确回答要覆盖时才传 `--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，不能把缺少确认当作同意。
+
+当用户要把平台上已有的 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`。
+
+## 请求转发路由
+
+创建请求转发、查找已有路由或生成 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` 只输出原始响应体。非 2xx 响应会先完成上述输出，再返回错误并使进程退出码非零；脚本既要保留输出用于诊断，也必须检查退出码。
+
+为避免覆盖 CLI 到 BI 的认证上下文，`Cookie`、`Authorization`、`token`、`X-Auth-Token`、`X-Personal-Token`、`x-dom-id` 和 `user-id` 等保留 Header 不能通过 `--header` 传入；目标服务鉴权应配置在路由模板或 Secret 中。
+
+## 仪表板、卡片智能洞察
+
+```bash
+guancli insight inspect <page_id>
+guancli insight page <page_id>
+guancli insight page <page_id> --selector "<selector_id>=<value>" --locale zh-CN
+guancli insight page <page_id> --analysis-id <analysis_id>
+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 或 OIDC Access Token，当前等待完整非流式结果。
+- `insight inspect` 输出洞察开关、分析思路 ID/名称和页面关联的 LLM 配置；不输出提示词正文，筛选器继续通过 `page get` / `card get` 查看。
+- 页面洞察仅支持已开启智能洞察的普通仪表板（`pgType=PAGE`）；数据大屏、智能归因、分析报告等页面类型不支持。
+- 卡片洞察必须同时提供卡片所属页面 ID，且仅支持 `cdType=INTELLIGENT_INSIGHT` 的智能洞察卡片。
+- `--selector` 使用页面筛选器 ID；同一 ID 需要多个值时重复传入。CLI 会先确认该 ID 是页面筛选器，再生成洞察。
+- 页面洞察可通过 `--analysis-id` 或 `--analysis-name` 指定分析，两者不能同时使用。
+- CLI 会先校验页面权限与类型、洞察开关、卡片归属与类型、筛选器和指定分析，预检通过后才发起生成请求。
+- 页面或卡片智能洞察 `/generate` 接口明确返回 404/405 时，CLI 会提示升级 BI。
+- 默认只输出洞察正文；需要完整响应时使用 `--raw`。
+
+主流程：
+
+1. 先执行 `guancli auth status`；认证失效时重新登录。
+2. 没有页面 ID 时执行 `guancli page search <页面关键词>` 确定页面。
+3. 执行 `guancli insight inspect <page_id>` 查看洞察开关、分析思路和 LLM 配置。
+4. 需要筛选器或卡片 ID 时，执行 `guancli page get <page_id> --brief` 查看页面资源 ID。
+5. 调用页面或卡片洞察命令；需要指定输出语言时增加 `--locale`。
+
+## 仪表板智能体（Dashboard Agent）
+
+```bash
+guancli insight agent list
+guancli insight agent get <agent_id>
+guancli --raw insight agent ask <agent_id> --expert-id <expert_id> --message "分析本月销售额下降的原因"
+guancli insight agent sessions <agent_id>
+guancli insight agent messages <session_id>
+guancli --raw insight agent ask <agent_id> --session-id <session_id> --expert-id <expert_id> --message "继续分析华东区域"
+```
+
+- 与 `chatbi insight` 基于数据集主题的洞察能力相互独立。
+- Agent 和专家均使用 ID 调用；guancli 不负责按名称选择 Agent 或专家。
+- `ask` 会创建消息、等待任务并返回最终回答；默认只输出正文，使用 `--raw` 可取得 `sessionId` 等完整信息。
+- 追问时复用已有 `sessionId`，可以继续使用原专家，也可以指定其他专家。
+
+流程：
+
+1. 用 `list` 获取 Agent，再用 `get <agent_id>` 获取专家并选择对应 ID。
+2. 用 `ask` 发起提问并等待结果；需要继续追问时，使用 `--raw` 保存返回的 `sessionId`。
+3. 用 `sessions` 和 `messages` 查找、查看已有会话。
+4. 携带已有 `sessionId` 再次执行 `ask` 继续追问。
+
+## 回答风格要求
+
+- 用中文输出，优先给“可执行结论”。
+- 不只贴原始命令结果，必须做逻辑归纳（按链路/主题）。
+- 对 `guancli metric query` 的结果，必须在结论中单独交代查询加速命中情况；如果命中，必须点名具体加速指标 ID，并用页面查询顺序表述命中的是第几个加速计划；不能只说“用了加速”。输出里的 `优先级N` 是后端排序权重，数字越大越先尝试，不等同于页面查询顺序。
+- 涉及时间相关信息时给出明确日期。
+- 如果用户给的是模糊对象名，先说明你是如何定位到具体资源 ID 的。
+
+
+---
+
+## VM 环境差异（观远 BI 工作站）
+
+本技能在 MCP 虚拟工作站中运行，与本地 CLI 有以下差异：
+
+- 命令名直接可用：在工作站里直接执行 `guancli` / `guanetl` / `guanvis` / `guands` / `guanmetric` / `guanwf`（无需安装）。
+- 认证：BI 凭证由网关注入，**不要**执行 `auth login` 或设置 token，直接运行业务命令即可。
+- 文件路径一律用以 `/` 开头的绝对路径（`/` 即工作区根，跨会话持久）。
+- 本技能的参考文档在 `/skills/<技能名>/references/` 下、示例工程在 `/skills/<技能名>/evals/` 下（均只读），用 read_file 工具或 `cat` 按需阅读；正文引用 `references/xxx` / `evals/xxx` 时按此路径解析。
+- 图片文件（png/jpg/gif/webp）用 read_file 工具读取，**不要**用 `cat`/`head` 读图片。默认部署下图片以图像内容返回、模型可直接查看；若 read_file 返回"当前部署已关闭图像内容返回"的提示（部署方接入的模型不支持图像理解），则只有文本元信息，此时不要做任何依赖看图的验证，改用数据类命令核对。
+- 不支持 `cd`、`$VAR` 展开、命令替换 `$(...)`、glob 展开；需要组合时把中间结果写入文件。
+- 文本搜索用 `rg`（工作站内无独立 grep 二进制，`grep`/`egrep`/`fgrep` 会自动转成 `rg` 执行，无需绕路）。
+- `install-skill` / profile 切换 / npm 相关步骤在工作站内不适用，忽略即可。
+
+### guancli 工作站命令面与已知坑（必读）
+
+<!-- guanvm:guancli-face:begin 本段由 build-guanvm-skills-bundle.sh 从 guancli.wasm 实测生成，勿手改 -->
+工作站内的 guancli 与本地完整版命令面不同。以下清单在构建时从工作站实际装载的 guancli.wasm 实测生成：
+
+- 可用顶级子命令（均可直接执行）：`auth`、`card`、`ds`、`etl`、`form`、`gateway`、`metric`、`metric_attribution`、`page`、`server-version`、`task`、`version`、`workflow`
+- 本技能文档（含 references/）提到但工作站内**不存在**的子命令：`analyze`、`app`、`chatbi`、`insight`、`project`、`search`、`so`、`url`。遇到相关需求直接告知用户工作站内暂不支持，**不要**尝试执行。
+<!-- guanvm:guancli-face:end -->
+
+已知坑：
+
+- `--brief` 仅对 `ds get` 是轻量摘要；`etl get` / `page get` **不要加 `--brief`**（会退化为体积更大的原始 JSON，默认输出才是 AI 友好的 Markdown 摘要）。
+- `-f excel` 会把 SpreadsheetML XML 直接打到 stdout：必须重定向到文件（如 `> /export.xls`）；批量取数优先 `-f csv` / `-f json` 重定向落盘后分页读取。
+- `ds execute-sql` 依赖 BI 8.2.0-hf12+ 且需开启"高级 SQL 查询"开关；报 `API 404` 说明当前环境不支持，改用 `ds preview` / `card preview` 取数。
+- `form` 系列依赖目标环境启用表单（SurveyEngine）模块；报 `API 423` 表示该环境未开通表单。

package/skills-bundle/guancli/evals/evals.json

@@ -0,0 +1,156 @@
+{
+  "skill_name": "guancli",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我查销售额指标。先搜索指标并告诉我适用维度，再按订单日期大于等于 2026-01-01、地区等于华东查询，只保留日期、地区和销售额三列。",
+      "expected_output": "代理应优先用 metric search --with-detail --brief 获取搜索结果及适用维度，metric query 的筛选分别使用 GE 和 EQ，并用 --columns 裁剪结果，不为已有稳定能力额外拼 jq。",
+      "files": [],
+      "expectations": [
+        "搜索命令使用 --with-detail --brief；需要结构化输出时使用 -f json",
+        "日期筛选使用 GE，不使用 >=",
+        "地区筛选使用 EQ，不使用 = 或 ==",
+        "结果列裁剪使用 metric query --columns"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "附件 metric-consumption-metadata.json 包含成功的 metric search/get -f json 返回。请用 jq 分别提取搜索结果每个指标的 ID、名称，以及单个指标详情的适用维度。先检查实际结构，不使用旧展示字段。",
+      "expected_output": "读取 schemaVersion/resultMode；search 访问 .search.data[] 的 id/name/dimensions，get 访问 .get.data.dimensions。canonical 元数据与中文业务列分开处理。",
+      "files": [
+        "fixtures/metric-consumption-metadata.json"
+      ],
+      "expectations": [
+        "search 使用 envelope.data[] 中的 id/name/dimensions；get 使用 envelope.data 中的 dimensions",
+        "不猜测指标ID、指标详情、适用维度等旧展示 JSON key",
+        "先确认 CLI 成功，错误时保留 stderr 并停止解析"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "我刚执行 guancli metric query metric_xxx --filter \"日期 >= 2026-01-01\" 失败了。继续帮我查，但不要反复猜语法。",
+      "expected_output": "代理应先查看 metric query --help 或指标命令参考，识别符号操作符应改为 GE，然后只重试正确写法。",
+      "files": [],
+      "expectations": [
+        "失败后先执行 guancli metric query --help 或读取 references/metric-commands.md",
+        "纠正后的筛选为 日期 GE 2026-01-01",
+        "不继续尝试 =、==、> 或 >= 等相近符号写法"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "用 guancli 搜索指标后通过 jq 解析结果。命令或 jq 失败时必须让我看到真实错误，不能把失败当成功。",
+      "expected_output": "代理应保留 stderr 和非零退出码，优先把 guancli JSON 输出保存到文件并确认成功后再运行 jq；若使用管道则启用 pipefail。",
+      "files": [],
+      "expectations": [
+        "必要解析不使用 2>/dev/null",
+        "优先拆开执行 guancli 和 jq 并检查前一步是否成功",
+        "若使用管道，先启用 set -o pipefail",
+        "不会因 jq 或管道末端成功而宣称上游 guancli 成功"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "帮我找‘复购成交贡献’相关指标。附件给出了本轮可重复的指标搜索返回，请展示你会执行的候选发现命令和最终答复。",
+      "expected_output": "代理应一次性生成原词和少量必要同义词，去重后放进同一次 metric search --fuzzy；消费附件中的确定性空结果后，报告尝试关键词、搜索范围、无结果原因和固定 stop_reason，并结束本轮发现。",
+      "files": [
+        "fixtures/metric-candidate-empty-search.json"
+      ],
+      "expectations": [
+        "原词保留在首位，原词加扩展词总数不超过 5 个",
+        "输出的调用序列中恰好出现一次 metric search --fuzzy，所有关键词都在这一次调用中",
+        "消费空结果后，调用序列中不再出现调换顺序、等价改写或查询子集的第二次 search",
+        "无结果说明包含 attempted_keywords、search_scope 和 stop_reason=no_candidate_within_budget",
+        "不把附件中的直接名称搜索计入候选发现 fuzzy 轮次"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "上一请求曾按附件记录搜索‘复购成交贡献’且没有候选。现在这是一个新的用户请求：再帮我找一次‘复购成交贡献’相关指标。请给出本次请求的下一条候选发现命令；不要沿用附件发生时的指标可见性。",
+      "expected_output": "代理不能复用上一请求的无结果结论，必须基于当前可见指标重新执行一次单批 metric search --fuzzy；关键词仍以原词为首并遵守 5 词预算。",
+      "files": [
+        "fixtures/metric-candidate-prior-request.json"
+      ],
+      "expectations": [
+        "即使附件记录上一请求无结果，本次仍生成一条新的 metric search --fuzzy 命令",
+        "本次调用序列中恰好出现一次 metric search --fuzzy",
+        "原词复购成交贡献保留在首位，去重后总关键词不超过 5 个",
+        "不把上一请求的 stop_reason 当成本次请求的搜索结果"
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "附件是成功的指标 query 返回，请检查结构后用 jq 提取区域和组织名称。给出可执行表达式。",
+      "expected_output": "使用 .data[] | {region: .[\"区域\"], organization: .[\"组织\"][\"名称\"]}；每一个中文层级都安全引用。",
+      "files": [
+        "fixtures/metric-consumption-query.json"
+      ],
+      "expectations": [
+        "先区分 envelope 和行数组",
+        "顶层区域和组织、嵌套名称都用括号加引号，不出现点号直连中文字段",
+        "canonical 英文字段说明不覆盖 query 中文字段规则"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "附件是本次销售额泛化查询的三个独立返回样本，请分别决定如何读取金额，展示你的检查和选择过程；不要重新请求 BI。",
+      "expected_output": "先检查各样本 columns/data keys；renamed 按业务意图确认后读取销售净额，missing 和 ambiguous 明确停止并报告实际列集合，不能猜旧展示列或近似名称。",
+      "files": [
+        "fixtures/metric-consumption-columns.json"
+      ],
+      "expectations": [
+        "读取实际列集合后再编写选择表达式，不预设销售额_recent_7d等展示名",
+        "renamed 选择来自实际 columns 的销售净额",
+        "missing 没有金额列时停止；ambiguous 存在销售额和销售净额时停止并询问业务口径",
+        "不抛 KeyError，不用缺失字段默认零或第一列掩盖歧义"
+      ]
+    },
+    {
+      "id": 9,
+      "prompt": "帮我查销售额指标按订单日期逐月的同比增长率，只看华东。这个 query 参数比较多，先确认最终会请求哪个接口、body 里的日期字段和高级计算是否正确，再执行真实查询。",
+      "expected_output": "代理先用 metric get 确认真实时间字段和地区字段，再构造唯一 compare 模式命令，使用 --explain-requests -f json 检查 metric-data/v2 的 dimensions、filters 和 advCalc；确认 valid/executable 后才移除 explain 执行。",
+      "files": [],
+      "expectations": [
+        "先用 metric get 确认时间字段和筛选字段，不默认字段名",
+        "查询组合使用 --dim \"订单日期 toMonth\" --compare yoy --compare-value rate，并只选择一个主模式",
+        "真实查询前使用 --explain-requests -f json，检查 data.requestPlan.requests 中的 metric-data/v2 body",
+        "只有 valid=true、executable=true 且 body 符合意图时才移除 --explain-requests"
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "我想把 --compare yoy 和 --adv-calc-json '{\"advType\":\"XTD\",\"advValue\":{\"advType\":\"XTD\",\"granularity\":\"YEAR\"}}' 一起传给 metric query，顺便看看最终请求体。",
+      "expected_output": "代理识别 adv-calc-json 是完整主计算定义，不能与 compare 组合；不要执行含歧义的查询，要求二选一，并分别说明可用 explain 查看请求体。",
+      "files": [],
+      "expectations": [
+        "明确指出 --adv-calc-json 与 compare/xtd/last/recent/percentage/rank 主模式互斥",
+        "不生成同时包含 --compare 和 --adv-calc-json 的可执行命令",
+        "建议选定一种模式后使用 --explain-requests -f json，而不是直接真实取数"
+      ]
+    },
+    {
+      "id": 11,
+      "prompt": "把 guancli metric query 的所有参数组合和最终 API 请求体都告诉我，我要避免 Agent 以后乱用。",
+      "expected_output": "代理不做无限参数笛卡尔积，而是按 base、compare、xtd、last、recent、percentage、rank、adv-calc-json 八类语义模式说明互斥/依赖，并把公共修饰参数单列；真实指标请求体通过 --explain-requests 解析。",
+      "files": [],
+      "expectations": [
+        "解释重复维度、筛选、recent 数值、rank-top 和任意 adv JSON 使字面上的全部组合无法穷举",
+        "完整列出八类主模式，并把筛选三选一、排序二选一和客户端输出参数作为公共矩阵",
+        "区分 card 链路与 metric-data/v2 链路",
+        "给出 --explain-requests -f json 作为真实 body 的权威入口"
+      ]
+    },
+    {
+      "id": 12,
+      "prompt": "帮我查一下销售额指标现在的值，没有维度和筛选。",
+      "expected_output": "即使是无参数的基础单指标查询，代理也先执行同一 metric_id 的 --explain-requests -f json，检查 valid/executable 以及 session/data 请求计划，再移除 explain 执行真实查询。",
+      "files": [],
+      "expectations": [
+        "无参数基础 metric query 也遵守 explain-first，不因参数简单而直接取数",
+        "检查 data.requestPlan 中 valid、executable 以及 card session/data 请求",
+        "只有计划有效、可执行且请求体符合意图时才执行真实查询",
+        "不把 batch-query 的独立批量契约误写成支持 --explain-requests"
+      ]
+    }
+  ]
+}

package/skills-bundle/guancli/evals/fixtures/metric-candidate-empty-search.json

@@ -0,0 +1,13 @@
+{
+  "scenario": "current-request-empty-candidate-search",
+  "searchScope": "当前用户可见的全部指标主题",
+  "directNameSearch": {
+    "keyword": "复购成交贡献",
+    "count": 0,
+    "contents": []
+  },
+  "fuzzySearchFixture": {
+    "count": 0,
+    "contents": []
+  }
+}

package/skills-bundle/guancli/evals/fixtures/metric-candidate-prior-request.json

@@ -0,0 +1,13 @@
+{
+  "scenario": "prior-request-negative-result-must-not-be-reused",
+  "requestId": "prior-request",
+  "searchedAt": "2026-08-27T17:51:18+08:00",
+  "attemptedKeywords": [
+    "复购成交贡献",
+    "重复购买贡献",
+    "回购贡献"
+  ],
+  "searchScope": "当时用户可见的全部指标主题",
+  "candidateCount": 0,
+  "stopReason": "no_candidate_within_budget"
+}

package/skills-bundle/guancli/evals/fixtures/metric-consumption-columns.json

@@ -0,0 +1,46 @@
+{
+  "renamed": {
+    "schemaVersion": "1.0",
+    "resultMode": "inline",
+    "rowCount": 1,
+    "command": "metric.query",
+    "columns": [
+      "销售净额"
+    ],
+    "data": [
+      {
+        "销售净额": 12
+      }
+    ]
+  },
+  "missing": {
+    "schemaVersion": "1.0",
+    "resultMode": "inline",
+    "rowCount": 1,
+    "command": "metric.query",
+    "columns": [
+      "地区"
+    ],
+    "data": [
+      {
+        "地区": "华东"
+      }
+    ]
+  },
+  "ambiguous": {
+    "schemaVersion": "1.0",
+    "resultMode": "inline",
+    "rowCount": 1,
+    "command": "metric.query",
+    "columns": [
+      "销售额",
+      "销售净额"
+    ],
+    "data": [
+      {
+        "销售额": 12,
+        "销售净额": 10
+      }
+    ]
+  }
+}