@guandata/guancli 1.0.53 → 1.0.55

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## @guandata/guancli 1.0.55 - 2026-09-01
+
+- 新增 `analyze normalize/align/calculate/topn` 本地分析命令，支持 CSV/JSON 规范化、结果集对齐、安全四则运算、分组 TopN 与占比，并统一输出 `analysis/v1` 结构。
+- 指标查询新增 `--json-envelope` 稳定机器契约，以及 `--filter-json`、`--filter-file` 和 dry-run 筛选校验，复杂条件的字段、类型与错误码更明确。
+- 指标搜索候选发现采用单批关键词预算，避免同义词反复搜索造成额外请求和不稳定结果。
+- 强化本地分析输出的精度、空值、重复键、除零与原子写入保护，失败时保留原输出文件并给出可定位错误。
+
+## @guandata/guancli 1.0.54 - 2026-08-26
+
+- `app publish` 新增 `--skip-build`，可直接发布可信、已验证的 `dist`，避免服务端重复执行项目构建脚本。
+- SuperApp 发布会在覆盖线上 `setting.json` 前明确确认，未确认时保留线上配置；发布包同时携带预构建产物。
+- 改进指标问数命令说明和资源筛选解析，减少参数生成不稳定、列名未命中却返回全量结果等误导行为。
+- `page get --brief` 会真正省略较大的模型定义；非法输出格式和拼错的二级子命令会明确报错并非零退出。
+- 统一结构化错误输出，保留请求方法、路径、状态码和后端业务错误，自动化流程更容易准确判断失败原因。
+
 ## @guandata/guancli 1.0.53 - 2026-08-25
 
 - 新增 OIDC 登录与安全凭据管理，提升企业统一身份认证、多环境切换和登录状态恢复的稳定性。

package/README.md

@@ -43,6 +43,19 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.55
+
+- 新增本地 CSV/JSON 规范化、对齐、安全计算和分组 TopN 分析命令。
+- 指标查询提供稳定 JSON envelope、结构化筛选文件和 dry-run 校验，复杂筛选更易自动化处理。
+- 限制指标候选发现的搜索轮次，并强化精度、空值、重复键和输出文件保护。
+
+### @guandata/guancli 1.0.54
+
+- SuperApp 发布支持复用可信、已验证的 `dist`，避免服务端因缺少项目本地构建工具而发布失败。
+- 覆盖线上 SuperApp 配置前会明确确认，未确认时保留线上 `setting.json`。
+- 指标问数命令、筛选与列选择更稳定，非法格式或拼错子命令会明确失败。
+- 结构化错误会保留请求位置、状态码和后端业务原因，排障更直接。
+
 ### @guandata/guancli 1.0.53
 
 - 新增 OIDC 登录与安全凭据管理，企业统一身份认证和多环境切换更稳定。

package/package.json

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

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 模板项目”“下载 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。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric 查询、指标树归因 metric_attribution、指标泛化查询参数，或要对本地 CSV/JSON 做通用规范化、字段对齐、安全基础计算、分组 TopN/占比时，主动使用这个 skill。用户给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据，或要为已有仪表板/智能洞察卡片生成智能洞察结果时也触发。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”“发布 SuperApp”“下载 SuperApp 整包”时，也要使用这个 skill，并引导使用 `guancli app create` / `guancli app publish` / `guancli app download`。用户要删除、重命名、移动页面时，本 skill 只负责把用户路由到 guanvis（`guanvis page delete/rename/move`），这些命令不在 guancli；被删页面没有任何命令行恢复入口，只能人工登录 BI 网页端还原。创建/编辑/删除指标、指标主题、指标目录或公共维度走 guanmetric；修改 ETL 走 guanetl；页面**内容**（卡片、布局、筛选器）的新建与修改、以及页面**本身**的删除/改名/移动都走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot。
 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`。
+guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、指标查询分析和 SuperApp 模板项目创建、发布与整包下载。页面本身的删除/改名/移动在 `guanvis page`。
 
 ## 何时优先使用
 
@@ -18,15 +18,16 @@ guancli 是 BI 资源的查询分析入口，并支持 Form 表单填报 CRUD、
 - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
-- 用户要创建超级应用 / SuperApp / SuperApp 模板项目，或要把平台上的 SuperApp 整包下载成本地 zip。
+- 用户要创建、发布或更新超级应用 / SuperApp，或要把平台上的 SuperApp 整包下载成本地 zip。
 - 用户要删除、重命名、移动页面（本 skill 只负责把用户路由到 `guanvis page`，命令不在 guancli）。
 - 用户要为已有仪表板或智能洞察卡片生成智能洞察结果。
+- 用户已经取得本地 CSV/JSON，需要稳定处理 BOM/null/嵌套字段、对齐两个结果集、执行安全四则运算，或做通用分组 TopN/占比；不再临时生成 Python 拼接脚本。
 
 如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建与整包下载。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRUD 和 SuperApp 模板项目创建、发布与整包下载。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |---|---|
@@ -65,6 +66,7 @@ guancli 是 BI 资源的**查询分析入口**，并支持 Form 表单填报 CRU
 | Form CRUD、子表、ChatBI 主题问数/洞察 | `references/form-chatbi.md` |
 | 指标与指标树全量命令 | `references/metric-commands.md` |
 | 指标泛化查询参数与示例 | `references/metric-generic-query.md` |
+| 本地 CSV/JSON 规范化、对齐、基础计算、TopN | `references/analysis-primitives.md` |
 
 ## 常用查询入口
 
@@ -141,14 +143,22 @@ guancli 在这条链路上只出只读的那一环：`guancli page search` / `pa
 
 ## 指标关键规则
 
-- 普通指标数据查询用 `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`。
+- **先按下面的命令契约生成，不要猜 shell、jq 或筛选语法**：
+  - `metric search/get/tree/query --json-envelope` 返回统一 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` 区分未查询与已知空数组，调用方不要把省略解释成已知为空。原 `-f json` 保持旧版对象/数组结构，供已有调用方兼容；envelope 版本由响应体中的 `schemaVersion` 演进，不新增 `json-v2` 一类输出格式。该参数不能与 `--raw`、非 JSON `-f` 或 stderr 输出目标同时使用。
+  - `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"`。
+  - 必须解析的命令不得用 `2>/dev/null` 隐藏 stderr。不要用会让末端命令成功掩盖上游失败的管道；优先拆成“guancli 输出到文件 → 确认命令成功 → jq 读取文件”，必须使用管道时先启用 `set -o pipefail`。
+  - 同类语法错误只允许出现一次；第一次失败后先执行对应命令的 `--help` 或读取本 Skill 的参考文档，再按真实契约纠正，不连续尝试相近写法。
+- 复杂筛选优先使用 `--filter-json`（可重复）或 `--filter-file` 条件树，并先加 `--dry-run --json-envelope`；dry-run 只读取指标详情做查询维度、筛选字段和类型校验，不执行指标取数，也不支持普通文件或 stderr 输出目标。不支持的 `--dim` 返回 `METRIC_UNSUPPORTED_DIMENSION`。条件树节点使用 `combineType: AND|OR`，叶子使用 `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`。
+- 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、筛选、排序、列筛选、输出格式等；使用 `--json-envelope` 时，未指定 `-o/--output` 且结果超过 1000 行会自动写入 `metric_<metricId>_<timestamp>_<unique>.json`，stdout 返回 `resultMode=file` 和绝对 `path`，不得再从中文提示猜文件名。唯一后缀用于避免同秒并发或重试覆盖已有结果。未启用该参数的默认和 `-f json` 输出保持兼容。回答指标数据查询结果时，必须检查输出中的 `查询加速` 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` 可跳过血缘。`--json-envelope` 不包含且不请求血缘，需要血缘时使用旧 `-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 模板初始化项目时，使用：
 
@@ -160,6 +170,20 @@ 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 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`。不要仅因为用户要求“发布应用”就自动追加该参数。
+- 用户回答不明确、没有反馈、非交互任务无法取得确认或确认流程异常时，一律按“不覆盖”处理。CLI 在非交互环境默认从待上传 zip 排除根目录的 `dist/settings.json`，继续发布其他静态资源，并在结果的 `settingsAction` 中返回 `preserved`。
+- 创建全新 SuperApp 时线上尚无 `settings.json`，无需询问覆盖；但通过 `--app-id` 更新，或 `--update-if-exists` 命中同名线上应用时，都必须执行上述确认。
+- 如果运行的是不支持该保护的旧版 guancli，不要冒险发布包含 `settings.json` 的更新产物；应先升级 CLI，不能把缺少确认当作同意。
+
 当用户要把平台上已有的 SuperApp 取回本地（备份、比对、排查线上产物）时，使用：
 
 ```bash

package/skills/guancli/evals/evals.json

@@ -0,0 +1,80 @@
+{
+  "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_search.json 是 guancli metric search --with-detail --brief -f json 的结果。请用 jq 提取每个指标的指标 ID、指标名称和指标详情里的适用维度。",
+      "expected_output": "代理生成的 jq 应对所有中文 JSON key 使用方括号加引号的访问方式，并逐级访问指标详情和适用维度。",
+      "files": [],
+      "expectations": [
+        "使用 .[\"指标ID\"] 和 .[\"名称\"]",
+        "嵌套字段使用 .[\"指标详情\"][\"适用维度\"]",
+        "不出现 .指标ID、.名称、.指标详情 或 .适用维度"
+      ]
+    },
+    {
+      "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 当成本次请求的搜索结果"
+      ]
+    }
+  ]
+}

package/skills/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/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/guancli/references/analysis-primitives.md

@@ -0,0 +1,95 @@
+# 本地分析原语
+
+`guancli analyze` 是无网络、无业务语义的本地表格处理入口。输入必须是明确的 CSV/JSON 文件，输出统一为 `analysis/v1` JSON envelope：
+
+```json
+{
+  "schemaVersion": "analysis/v1",
+  "operation": "normalize",
+  "columns": ["区域", "金额"],
+  "rowCount": 1,
+  "rows": [{"区域": "华东", "金额": "10"}],
+  "metadata": {"input": "raw.csv"}
+}
+```
+
+## 适用边界
+
+- CLI 只提供 loader、字段对齐、安全四则运算、分组排序、TopN 和占比。
+- “本期/同期/预算”“同比/达成率”“毛利贡献”“价格/成本效应”等属于上层分析 recipe。调用方应显式选择字段并组合通用原语，禁止假设 CLI 内置这些业务口径。
+- 每一步都写到明确文件再进入下一步。命令失败后读取错误并修正字段或策略，不用临时 Python 脚本绕过契约。
+
+## 规范化
+
+```bash
+guancli analyze normalize raw.csv -o normalized.json
+guancli analyze normalize raw.json --input-format json -o normalized.json
+```
+
+- 自动识别 CSV/JSON，也可以用 `--input-format` 明确指定。
+- 去除 UTF-8 BOM；JSON 嵌套对象扁平化为 `父字段.子字段`。
+- CSV 按记录读取，JSON 对象数组以及 `rows`/`data` 数组按元素读取；最终规范化表仍会保留在内存中，超大结果应在上游先过滤。
+- JSON 数字按原始十进制文本解析并原样写回，超过 JavaScript 安全整数范围的 ID 不会先转成浮点数而丢失精度。
+- CSV/JSON 字符串中的空字符串、`null`、`None`、`<nil>` 默认转成 JSON `null`。需要其他契约时可重复传 `--null-value`；一旦显式传入，就只使用调用方给出的集合。
+- JSON 顶层支持对象数组、单个对象、`rows` 数组或 `data` 数组。
+- 使用 `-o` 时先写同目录临时文件并同步，成功后再原子替换目标；写入、同步或关闭失败时保留原输出文件。
+
+## 对齐
+
+```bash
+guancli analyze align \
+  --left current.json \
+  --right reference.json \
+  --key 区域 --key 产品 \
+  --join full \
+  --left-prefix current \
+  --right-prefix reference \
+  -o aligned.json
+```
+
+- `--join` 支持 `full`、`inner`、`left`、`right`。
+- 键字段只输出一份，非键字段统一加左右前缀；缺失的一侧显式输出 `null`。
+- 任一输入出现重复组合键时直接失败。CLI 不猜测聚合方式，也不静默执行多对多连接；调用方必须先按明确口径聚合。
+
+## 安全基础计算
+
+```bash
+guancli analyze calculate aligned.json \
+  --operator subtract \
+  --left-field current.金额 \
+  --right-field reference.金额 \
+  --output-field difference \
+  --null-policy propagate \
+  -o calculated.json
+
+guancli analyze calculate aligned.json \
+  --operator divide \
+  --left-field current.金额 \
+  --right-field reference.金额 \
+  --output-field ratio \
+  --zero-divisor null \
+  -o ratio.json
+```
+
+- `--operator` 支持 `add`、`subtract`、`multiply`、`divide`。
+- `--null-policy propagate` 保留空值；只有调用方明确要求时才使用 `zero`。
+- 除数为 0 默认输出 `null`；需要严格失败时使用 `--zero-divisor error`。
+- 非空但不可解析为有限数值的字段（包括 `NaN`/`Inf`）直接报错并定位行号，不使用默认值吞错。
+
+## 分组 TopN 与占比
+
+```bash
+guancli analyze topn calculated.json \
+  --group-by 区域 \
+  --value-field difference \
+  --limit 10 \
+  --order desc \
+  --rank-field rank \
+  --share-field share \
+  -o topn.json
+```
+
+- `--group-by` 是分区字段，不指定时对全表排序。
+- 占比分母是该分区全部非空行的数值之和，不是 TopN 截断后的合计。
+- 空值排在有效数值之后，占比为 `null`；分区合计为 0 时占比同样为 `null`。
+- `topn` 不做隐式聚合。存在重复粒度时，先使用具备明确聚合口径的上游查询或工具处理。

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

@@ -72,7 +72,7 @@ guancli metric search [keyword] [flags]
 | `--fuzzy strings` | 名称、业务口径、自定义业务属性统一模糊搜索关键词，可多次指定，也支持逗号、中文逗号、顿号分隔；和 `[keyword]` 互斥 |
 | `--offset int` | 搜索结果分页偏移量，默认 `0` |
 | `--limit int` | 搜索结果数量，默认 `0` 表示全部 |
-| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；默认包含血缘，加 `--brief` 跳过血缘 |
+| `--with-detail` | 同时返回每个命中指标的 `metric get` 详情；旧格式默认包含血缘，`--brief` 或 `--json-envelope` 不请求血缘 |
 
 `--fuzzy` 语义：
 
@@ -82,11 +82,22 @@ guancli metric search [keyword] [flags]
 - 结果会在原有指标字段基础上增加命中条件、命中优先级和命中关键词。
 - 非 `--raw` 输出会额外查询并返回每个指标关联的查询加速摘要，包括查询加速数量和加速指标 ID/优先级/字段摘要。
 - `--with-detail` 会为当前搜索结果中的每个指标补充与 `metric get <metric_id>` 相同的标准化详情；默认终端输出按指标追加详情，`-f json` 则在每条搜索结果的 `指标详情` 中嵌套返回。
-- 默认详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。结果较多时先用 `--limit` 收窄指标数量。
+- 旧格式默认详情包含血缘；批量搜索只需业务口径、数据集、字段、权限、统计、自定义属性和查询加速等信息时，加 `--brief` 跳过血缘。`--json-envelope` 不包含且不请求血缘，需要血缘时使用旧 `-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、指标名称、状态、类型。
@@ -108,6 +119,23 @@ guancli metric search --fuzzy 收入 --profile default --limit 5 --with-detail -
 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 --json-envelope > metric_search.json &&
+  jq '.data[] | {id, name, dimensions, timeField}' metric_search.json
+```
+
+中文 key 必须使用 `.["字段名"]`，嵌套 key 必须逐级引用；不要写 `.指标详情.适用维度`。必要解析不要添加 `2>/dev/null`。如果命令失败，先保留 stderr 和非零退出码并查看 `guancli metric search --help`，不要继续猜参数。
+
 ### metric get
 
 获取指标详情，包括元数据、数据口径、数据集、权限、统计信息、自定义属性、查询加速和血缘关系。
@@ -127,6 +155,21 @@ 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 --json-envelope > metric_detail.json &&
+  jq '.data.dimensions' metric_detail.json
+```
+
 ### metric accelerate
 
 查询指标的查询加速配置。后端取数时会按 `acceleratePriority` 从高到低尝试加速指标；只有当查询维度和筛选维度都能被加速指标适用维度覆盖时才会命中。
@@ -196,14 +239,20 @@ guancli metric query <metric_id> [flags]
 | `--limit int` | `50` | 数据行数限制 |
 | `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔 |
 | `--filter stringArray` | 无 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
+| `--filter-json stringArray` | 无 | 结构化筛选 JSON，可重复；支持嵌套 AND/OR 条件树 |
+| `--filter-file string` | 无 | 从 JSON 文件读取一棵结构化条件树；与 `--filter`、`--filter-json` 互斥 |
 | `--combine-type string` | `AND` | 多条件组合方式：`AND` 或 `OR` |
+| `--dry-run` | `false` | 只返回规范化查询计划、字段类型和稳定错误码，不执行指标取数；必须同时使用 `--json-envelope`，且不支持普通文件或 stderr 输出目标 |
+| `--json-envelope` | `false` | 输出带 `schemaVersion` 的稳定 JSON envelope；`--dry-run` 必须启用此参数，且不能与 `--raw`、非 JSON `-f` 或 stderr 输出目标同时使用 |
 | `--sort-asc string` | 无 | 按列升序排序，与 `--sort-desc` 互斥 |
 | `--sort-desc string` | 无 | 按列降序排序，与 `--sort-asc` 互斥 |
 | `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
 | `--precision int` | `6` | 数值最大小数位数；传 `-1` 保留原始精度 |
 | `-o, --output string` | 无 | 将查询结果写入文件；未指定且结果超过 1000 行时自动写入文件 |
 
-未指定 `-o/--output` 且查询结果超过 1000 行时，默认写入 `metric_<metricId>_<timestamp>.<ext>` 文件，避免把大结果直接塞入上下文。默认 `-f auto` 在写文件时会切换为 CSV；显式指定 `-f json/csv/table/expanded/excel` 时按指定格式写入。
+`metric search/get/tree/query --json-envelope` 都返回带版本号的稳定 JSON envelope，当前 canonical 契约版本为 `1.0`，公共字段为 `schemaVersion`、`command`、`resultMode`、`rowCount`。内联结果在 `data`，文件结果在绝对 `path`；query 还返回 `columns`。版本演进读取响应体中的 `schemaVersion`，不会增加 `json-v2` 一类输出格式。原 `-f json` 保持旧版对象/数组结构，避免破坏 Decidex 等既有调用方。未指定 `-o/--output` 且查询结果超过 1000 行时，默认模式仍自动写 CSV 并输出原中文提示；启用 `--json-envelope` 时写 JSON 文件，stdout 返回 `resultMode=file` envelope。自动文件名带唯一后缀，避免同秒并发或重试覆盖已有结果。显式非 JSON `-f` 与 `--json-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` 只省略计数和权限，不省略节点身份。中文展示字段只属于默认输出和旧 `-f json`，不属于 envelope 契约。canonical 模型不包含血缘，因此 `--with-detail --json-envelope` 不请求血缘；确实需要血缘时使用原 `-f json`。query dry-run 不查询加速配置，此时省略 `metric.accelerations`，不能把省略解释成无加速配置。
 
 筛选操作符：
 
@@ -215,6 +264,8 @@ guancli metric query <metric_id> [flags]
 | 空值 | `IS_NULL`、`NOT_NULL` |
 | 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |
 
+`--filter` 不接受 SQL/数学符号。固定映射为 `= -> EQ`、`>= -> GE`、`<= -> LE`；其他条件同样从上表选择 CLI 操作符。符号写法会直接报错并给出纠正提示。
+
 示例：
 
 ```bash
@@ -222,7 +273,9 @@ 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 省份 --filter "省份 EQ 河南省"
-guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR
+guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR --dry-run --json-envelope
+guancli metric query <metric_id> --profile default --filter-json '{"field":"省份","operator":"IN","values":["河南省","青海省"]}' --dry-run --json-envelope
+guancli metric query <metric_id> --profile default --filter-file filters.json --dry-run --json-envelope
 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
@@ -230,6 +283,41 @@ guancli metric query <metric_id> --profile default --dim 省份 --limit 10000 -f
 guancli metric query <metric_id> --profile default --dim 省份 --raw
 ```
 
+多分支 OR 的 dry-run 会返回 `valid=true`、`executable=false`、`requestCount=0` 和错误码 `FILTER_OR_EXECUTION_UNSUPPORTED`。当前指标取数接口不能在单次请求中无损表达这类 OR，真实执行会在取数前拒绝，不会拆成多次聚合查询后拼接。
+
+#### 可复制模板：筛选并裁剪查询结果
+
+```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
 
 获取指标目录树。默认输出树形结构，最外层展示指标主题。

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

@@ -37,7 +37,7 @@ guancli ds get <resource_id> --assoc   # 附加显示关联关系摘要（ETL、
 guancli page get <resource_id>         # 页面详情（含卡片列表、血缘）
 ```
 
-**`--brief` 模式**：省略 Malloy 数据源定义、血缘关系、计算字段公式等高 token 内容，只保留基本信息和字段名/类型列表。适合 AI 在上下文受限时快速了解数据集结构。所有 `get` 子命令均支持此选项。
+**`--brief` 模式**：省略 Malloy 定义、血缘关系、计算字段公式等高 token 内容。`ds get` 省略 Malloy/血缘/公式详情；`page get` 省略各卡片的 Malloy 定义与血缘；`etl get` 仅省略血缘；`card get` 输出本身已精简，该选项无额外效果。
 
 **`--assoc` 模式**（仅 `ds get`）：在详情末尾追加数据集关联关系摘要，显示关联的 ETL、数据融合等资源。