@guandata/guanmetric 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.13 - 2026-09-03
+
+- 复合指标创建和编辑会校验公式上游类型，只允许原子指标或复合指标，阻止衍生指标、快捷引用指标和自身引用进入公式。
+- 标准模板会按引用对象的真实类型补充原子或复合指标，不再把缺失引用一律补成原子指标；涉及衍生语义时提示改模并要求确认。
+- 改进 Windows npm 全局安装环境下的 CLI 执行器定位。
+
+## @guandata/guanmetric 0.1.12 - 2026-09-01
+
+- 新增业务字典目录树、查询、新建、原地编辑和删除能力，支持业务属性筛选、dry-run 和关联指标影响确认。
+- 指标模板新增机器 schema、原子/复合最小模板、无副作用 `--check-only` 预检及稳定单元格诊断，创建前可按错误码精确修正。
+- 统一指标定义与查询加速的 WebFilterData 规范化和字段元数据校验，修复业务限定筛选保存后无法回显的问题。
+- 查询加速筛选条件新增兼容别名转换、空值和嵌套组合校验，无法无损转换时会在提交前明确拒绝。
+
 ## @guandata/guanmetric 0.1.11 - 2026-08-27
 
 - 拼错二级子命令时会明确报错并返回非零退出，不再静默忽略无效输入。

package/README.md

@@ -13,20 +13,43 @@ npm install -g --foreground-scripts @guandata/guanmetric
 ## 常用命令
 
 ```bash
+guanmetric template schema --type atomic
+guanmetric template init --type atomic --out atomic_metrics.xlsx
+guanmetric template normalize 客户指标.xlsx --check-only --output json-v1
 guanmetric template normalize 客户指标.xlsx --out standard.xlsx --report report.json
+guanmetric template explain-error report.json --json
 guanmetric project-create 经营指标 --dry-run
 guanmetric dir-create 广告分析 --project-id <project_id> --dry-run
 guanmetric create --file atomic_metric.json --dry-run
 guanmetric edit <metric_id> --file patch.json --dry-run
 guanmetric delete <metric_id>
 guanmetric public-dim create --file public_dim.json --dry-run
+guanmetric business-dict list 销售 -f table
+guanmetric business-dict get <business_dict_id>
+guanmetric business-dict create --file business_dict.json --dry-run
+guanmetric business-dict edit <business_dict_id> --set desc=新口径 --dry-run
+guanmetric business-dict delete <business_dict_id>
 guanmetric accelerate create <metric_id> --ds-id <dsId> --fd-id <fdId> --aggr-type SUM --filter-file filter.json --dry-run
 guanmetric metric-tree create 销售额指标树 --metric-id <metric_id> --parent-dir-id <metric_tree_dir_id> --dry-run
 guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.json --dry-run
 ```
 
+指标模板命令提供机器可读 schema、原子/复合指标最小模板和无副作用预检。`--check-only` 不写 Excel/report，也不创建或修改指标；失败结果通过稳定的 `TEMPLATE_*` 错误码以及 Sheet、行、列、期望值和修正示例定位。
+
 ## 版本更新
 
+### @guandata/guanmetric 0.1.13
+
+- 复合指标公式会校验上游类型，阻止衍生指标、快捷引用指标和自身引用。
+- 标准模板按真实类型补充原子或复合指标；涉及衍生结果时会提示改模并要求确认。
+- 改善 Windows npm 全局安装场景下的 CLI 执行器定位。
+
+### @guandata/guanmetric 0.1.12
+
+- 新增业务字典目录树及增删改查，支持业务属性筛选、dry-run 和删除影响确认。
+- 指标模板新增机器 schema、最小模板、`--check-only` 预检和稳定单元格诊断。
+- 规范指标与查询加速筛选条件，修复业务限定保存后无法回显并强化提交前校验。
+
 ### @guandata/guanmetric 0.1.11
 
 - 拼错二级子命令会明确报错并非零退出。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanmetric",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "观远 BI 指标写操作工具 - 指标创建编辑删除、指标目录、公共维度、Excel 标准化",
   "bin": {
     "guanmetric": "bin/run.js"

package/skills/guanmetric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guanmetric
-description: 当用户要创建、编辑、删除观远 BI 指标，创建指标主题/指标目录，创建或配置指标树（含维度拆解、指标拆解公式、复合指标公式展开），批量标准化 Excel 指标模板，或管理指标公共维度时使用本 skill。查询指标详情、搜索指标、指标数据查询仍使用 guancli。
+description: 当用户要创建、编辑、删除观远 BI 指标，创建指标主题/指标目录，创建或配置指标树（含维度拆解、指标拆解公式、复合指标公式展开），批量标准化 Excel 指标模板，管理指标公共维度，或查询目录树及增删改查业务字典时使用本 skill。查询指标详情、搜索指标、指标数据查询仍使用 guancli。
 compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts (local) or npm install -g --foreground-scripts @guandata/guanmetric (from internal Nexus registry) so the AI skill refresh result is visible. CLI command: guanmetric."
 ---
 
@@ -11,17 +11,27 @@ compatibility: "Requires Node.js 14+. Install via npm link --foreground-scripts
 常用命令：
 
 ```bash
+guanmetric template schema --type atomic
+guanmetric template init --type atomic --out atomic_metrics.xlsx
+guanmetric template init --type composite --out composite_metrics.xlsx
+guanmetric template normalize 客户指标.xlsx --check-only --output json-v1 --skip-biz-attrs --skip-id-resolve
 guanmetric template normalize 客户指标.xlsx --out standard.xlsx --report report.json
+guanmetric template explain-error report.json --json
 guanmetric project-create 经营指标 --dry-run
 guanmetric dir-create 广告分析 --project-id <project_id> --dry-run
 guanmetric create --file atomic_metric.json --dry-run
 guanmetric edit <metric_id> --file patch.json --dry-run
 guanmetric delete <metric_id>
 guanmetric public-dim create --file public_dim.json --dry-run
+guanmetric business-dict list 销售 -f table
+guanmetric business-dict get <business_dict_id>
+guanmetric business-dict create --file business_dict.json --dry-run
+guanmetric business-dict edit <business_dict_id> --set desc=新口径 --dry-run
+guanmetric business-dict delete <business_dict_id>
 guanmetric accelerate create <metric_id> --ds-id <dsId> --fd-id <fdId> --aggr-type SUM --dim 省份 --dry-run
 guanmetric accelerate create <metric_id> --ds-id <dsId> --fd-id <fdId> --aggr-type SUM --filter-file filter.json --dry-run
 guanmetric accelerate edit <accelerate_metric_id> --file accelerate_query.json --dry-run
-guanmetric accelerate edit <accelerate_metric_id> --filter-json '{"type":"condition","not":false,"value":{"fdId":"fd_province","filterType":"IN","filterValue":[["浙江"]]}}' --dry-run
+guanmetric accelerate edit <accelerate_metric_id> --filter-json '{"type":"condition","not":false,"value":{"dsId":"ds_sales","fdId":"fd_province","name":"省份","fdType":"STRING","metaType":"DIM","filterType":"IN","filterValue":["浙江"]}}' --dry-run
 guanmetric accelerate priority <metric_id> --priority <accelerate_metric_id>=2 --dry-run
 guanmetric accelerate delete <accelerate_metric_id> --confirm
 guanmetric metric-tree create 销售额指标树 --metric-id <metric_id> --parent-dir-id <metric_tree_dir_id> --dry-run
@@ -31,10 +41,12 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file comp
 
 ## 编辑红线：编辑 ≠ 删除重建
 
-用户要求**编辑/重命名/修改**已有指标时，必须用 `guanmetric edit <metric_id>` 原地更新（默认按线上详情合并 patch，改名用 `--set name=新名`）；公共维度用 `public-dim edit`；查询加速用 `accelerate edit <accelerate_metric_id>` 原地更新或 `accelerate priority <metric_id>` 调整顺序；指标树用 `metric-tree rename`、`metric-tree move` 或 `metric-tree update-config` 原地更新。**严禁**用"delete 后重新 create 一个同名指标/指标树/查询加速"来模拟编辑或改名：指标 ID 被复合指标、衍生指标、指标卡片和指标树引用，删除重建会让这些引用全部断链，指标上的权限和历史配置也会丢失且无法恢复。指标树删除重建还会改变指标树 ID，导致归因入口、目录引用和外部链接失效。`delete` 只用于用户明确要求删除该指标本身。指标主题/目录目前只支持创建，不支持改名或删除；用户要求时直接说明 CLI 暂不支持，不要新建一个新主题/目录来替代。无论通过哪个命令或接口，都不得把"编辑"拆成"删除 + 重建"的组合来绕过这条红线。只有用户明确指示"先新建替代、再删除旧的"时才允许该流程，且执行前必须列出会断链和丢失的内容并获得确认。
+用户要求**编辑/重命名/修改**已有指标时，必须用 `guanmetric edit <metric_id>` 原地更新（默认按线上详情合并 patch，改名用 `--set name=新名`）；业务字典用 `business-dict edit`；公共维度用 `public-dim edit`；查询加速用 `accelerate edit <accelerate_metric_id>` 原地更新或 `accelerate priority <metric_id>` 调整顺序；指标树用 `metric-tree rename`、`metric-tree move` 或 `metric-tree update-config` 原地更新。**严禁**用"delete 后重新 create 一个同名指标/业务字典/指标树/查询加速"来模拟编辑或改名：资源 ID 被其他对象引用，删除重建会导致引用、权限或历史配置丢失。业务字典删除时，服务端会先解除正式指标和草稿的 `bizMetricId`，并把字典的业务口径和业务属性保留到指标，再逻辑删除字典；因此删除前必须先查看关联指标并取得明确确认。指标树删除重建还会改变指标树 ID，导致归因入口、目录引用和外部链接失效。`delete` 只用于用户明确要求删除资源本身。指标主题/目录目前只支持创建，不支持改名或删除；用户要求时直接说明 CLI 暂不支持，不要新建一个新主题/目录来替代。无论通过哪个命令或接口，都不得把"编辑"拆成"删除 + 重建"的组合来绕过这条红线。只有用户明确指示"先新建替代、再删除旧的"时才允许该流程，且执行前必须列出会断链和丢失的内容并获得确认。
 
 批量创建指标时，必须先生成固定结构的标准 Excel 返回给用户确认；确认前不生成最终 payload，不提交真实创建。
 
+生成或校验原子/复合指标输入前，先执行 `guanmetric template schema --type atomic|composite` 获取机器契约；没有现成输入时用 `template init --type atomic|composite` 生成带合法示例的最小模板。进入正式 normalize 前优先运行 `template normalize <file> --check-only --output json-v1`：该命令不写 Excel/report，也不创建、修改或上线指标；`valid=false` 时按 diagnostics 中的稳定 code、Sheet、row、column、expected 和 example 修正。code/column 由校验规则直接产生，不从中文 message 推断；修改展示文案不会改变机器诊断。`TEMPLATE_NEEDS_REVIEW` 不属于真实错误，只有 severity=error 才使命令非零退出。已有普通 normalize report 可用 `template explain-error <report.json> --json` 提取同一诊断契约。
+
 如果用户提供的是客户原始 Excel/CSV，而不是已经接近标准模板的文件，agent 必须先自行读取并理解表格语义，产出一个语义映射中间表（建议命名为 `*.ai_mapped.xlsx`），再执行 `guanmetric template normalize` 生成最终标准模板。不要直接把客户原始 Excel 丢给 CLI 后交付结果；CLI 不负责穷举客户列名或业务表述。CLI 继续负责固定模板结构、必填项标记、业务属性配置读取、自动填充说明、行状态、问题说明、高亮样式、列宽自适应、基础校验和 report 输出。
 
 如果用户没有提供 Excel/CSV，而是给出一段文字、需求描述、粘贴的半结构化表格、截图转写内容或其它非文件信息，也必须先由 agent 理解语义并整理成同样的 `*.ai_mapped.xlsx` 中间表，再执行 `guanmetric template normalize` 生成标准模板。信息不足时不要直接放弃；应尽量补出可判断的指标行，并在标准模板的 `问题说明` 中列出缺失的主题、目录、数据集、字段、聚合方式、公式、衍生自、适用维度、时间维度或业务属性，让用户在返回的标准模板中修改后重新上传。
@@ -45,20 +57,22 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file comp
 
 标准 Excel 第一张固定为 `汇总` sheet，用于给用户总览本次待创建指标总数、按类型计数、指标名称、指标类型、所在模板、关键来源、行状态和问题说明；创建 payload 仍以各指标类型模板 sheet 为事实源，不从 `汇总` sheet 创建。
 
-生成复合指标模板时，如果 `计算公式` 引用的 `[指标名]` 不在原子指标模板中，agent 必须补充同名原子指标行，保证创建时先有基础原子指标，再创建复合指标。
+生成复合指标模板时，`计算公式` 的每个引用都必须解析为已上线或本批先创建的原子指标/复合指标。复合指标不能引用衍生指标或快捷引用指标；如果引用对象不在模板中，先判断它应建为原子指标还是复合指标并补充对应行，不要一律补成原子指标。若业务公式确实要组合最近 N、累计、期末值等衍生结果，按 `metric-derived-mutation.md` 评估组合衍生，并向用户说明改模后的业务语义。
 
 生成衍生指标模板时，如果 `衍生自` 指标不是已明确存在的线上指标，而是本批也要创建的指标，必须在标准模板中补充对应的原子指标或复合指标行；信息不足时先补行并在该基础指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、计算公式、适用维度等。不要等到创建计划阶段才临时新增基础指标。
 
-`fetch` 只用于指标平台写入接口尚未封装为专用命令的场景，例如复合指标/衍生指标创建、编辑和影响校验；常规原子指标、主题、目录、公共维度优先使用专用命令。
-查询加速写操作已封装为 `accelerate` 专用命令；查询加速列表查询使用 `guancli metric accelerate list <metric_id>`。查询加速筛选条件使用和指标定义一致的 `WebFilterData` 结构，可放在完整请求体的 `filter` 字段，也可通过 `--filter-json` 或 `--filter-file` 传入；`not: true` 表示对该条件或条件组取反，清空筛选条件可传 `--filter-json null`。
+`fetch` 只用于指标平台写入接口尚未封装为专用命令的场景，例如复合指标/衍生指标创建、编辑和影响校验；常规原子指标、主题、目录、公共维度优先使用专用命令。指标定义写入时，`fetch` 会规范化并校验顶层 `filter`：将兼容别名和 `not: true` 转成 Web 编辑器可识别的明确筛选类型，为空值筛选补 `filterValue: []`，并从当前指标或基础指标的 `applicableDims` 补齐字段元数据；无法无损转换时拒绝提交。业务限定衍生指标还会确认每个条件的 `fdId` 都存在于基础指标 `applicableDims`。
+查询加速写操作已封装为 `accelerate` 专用命令；查询加速列表查询使用 `guancli metric accelerate list <metric_id>`。查询加速筛选条件使用和指标定义一致的 `WebFilterData` 结构，可放在完整请求体的 `filter` 字段，也可通过 `--filter-json` 或 `--filter-file` 传入；合法节点仅为 `condition/operator/composition`，禁止使用 `group/combineType/conditions`。查询加速无法从指标适用维度自动补齐另一数据集的字段元数据，因此条件必须显式提供 `dsId/fdId/name/fdType/metaType`；清空筛选条件可传 `--filter-json null`。完整契约和嵌套示例见 `metric-common-fields.md`。
 指标树创建和修改已封装为 `metric-tree` 专用命令，优先使用专用命令，不要再用裸 `fetch` 直接调用指标树写接口。指标树父目录来自 `METRIC_TREE` 目录树，可用 `guancli metric_attribution tree -f json` 查询；不要把 `guancli metric tree` 返回的 `METRIC_PLATFORM` 指标目录 ID 当作指标树目录 ID。用户给出指标拆解公式时，按 `metric-tree-mutation.md` 解析成 `metricRelationTree`；遇到复合指标时读取指标详情中的 `formula`，按规则递归展开或在计划中标注不能无损展开的原因。
 
 参考文档见本 skill 的 `references/` 目录：
 
 - `metric-excel-template.md`
 - `metric-mutation.md`
+- `metric-common-fields.md`
 - `metric-atomic-mutation.md`
 - `metric-composite-mutation.md`
 - `metric-derived-mutation.md`
 - `metric-public-dimension.md`
+- `metric-business-dictionary.md`
 - `metric-tree-mutation.md`

package/skills/guanmetric/references/metric-business-dictionary.md

@@ -0,0 +1,72 @@
+# 业务字典管理
+
+业务字典在后端接口和代码中也称 `BusinessMetric`，CLI 使用面向产品语义的命令名 `business-dict`，并兼容 `business-metric`、`biz-dict` 别名。
+
+## 查询
+
+```bash
+guanmetric business-dict list
+guanmetric business-dict list 销售 --order-by utimeDesc
+guanmetric business-dict list --desc 收入 --dir-id <dir_id>
+guanmetric business-dict list --associated
+guanmetric business-dict list --associated=false
+guanmetric business-dict list --biz-attr region=华东,华南 --biz-attr channel=直营
+guanmetric business-dict list -f table
+guanmetric business-dict get <business_dict_id>
+guanmetric business-dict tree
+```
+
+搜索接口无分页，`list` 返回全部匹配项。支持的排序为 `nameAsc`、`nameDesc`、`ctimeAsc`、`ctimeDesc`、`utimeAsc`、`utimeDesc`。`--associated` 仅查已关联指标的字典，显式传 `--associated=false` 仅查未关联字典；不传时不按关联状态过滤。
+
+业务属性搜索中，文本类属性由服务端执行不区分大小写的包含匹配，枚举类属性执行精确匹配。禁用或不存在的属性由服务端返回业务错误；不可搜索的属性不会匹配结果，通常表现为空列表。
+
+## 新建
+
+请求体字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 名称；trim 后不能为空、同域唯一、最长 250 字符 |
+| `desc` | 是 | 业务口径 |
+| `dirId` | 否 | `BUSINESS_METRIC` 目录 ID；用 `business-dict tree` 查询 |
+| `bizAttrs` | 否 | `[{"id":"<attr_id>","values":["<value>"]}]` |
+
+```bash
+guanmetric business-dict create --file business_dict.json --dry-run
+guanmetric business-dict create --file business_dict.json
+```
+
+示例请求体：
+
+```json
+{
+  "name": "销售额",
+  "desc": "订单实付金额汇总，不含退款",
+  "dirId": "dir_xxx",
+  "bizAttrs": [
+    {"id": "attr_region", "values": ["华东"]}
+  ]
+}
+```
+
+## 编辑
+
+```bash
+guanmetric business-dict edit <business_dict_id> --set name=含税销售额 --dry-run
+guanmetric business-dict edit <business_dict_id> --file patch.json
+guanmetric business-dict edit <business_dict_id> --file full.json --replace
+```
+
+默认会先读取线上详情，只保留 `name`、`desc`、`dirId`、`bizAttrs` 四个可提交字段，再合并 patch 并原地更新。`--replace` 仅用于调用方已经提供完整请求体的场景。严禁通过删除后新建同名字典模拟编辑。
+
+## 删除
+
+```bash
+guanmetric business-dict delete <business_dict_id>
+guanmetric business-dict delete <business_dict_id> --confirm
+guanmetric business-dict delete <business_dict_id> --confirm --dry-run
+```
+
+第一次执行只读取详情，展示是否存在 `associatedMetric`，不提交删除。追加 `--confirm` 后才调用删除接口。
+
+删除采用逻辑删除。如果字典已关联指标，服务端会先清空正式指标与草稿中的 `bizMetricId`，并把字典的 `desc` 和 `bizAttrs` 留存在指标上，再删除字典。该行为不同于“有依赖即阻断删除”，所以确认提示必须明确说明解除关联和保留字段的影响。

package/skills/guanmetric/references/metric-common-fields.md

@@ -32,6 +32,80 @@
 | `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
 | `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |
 
+## 筛选条件 `filter`（WebFilterData）
+
+原子指标筛选、复合指标筛选、衍生指标业务限定和查询加速筛选共用同一套 `WebFilterData` 协议。合法节点只有：
+
+| `type` | `value` | 说明 |
+| --- | --- | --- |
+| `condition` | 字段筛选对象 | 规范化后必须包含 `dsId`、`fdId`、`name`、`fdType`、`metaType`、`filterType`；按筛选类型提供 `filterValue` |
+| `operator` | `and` 或 `or` | 只能出现在 `composition.value` 的两个条件节点之间 |
+| `composition` | WebFilterData 数组 | 按“条件、运算符、条件”交替排列；同一 composition 内运算符必须一致，可递归嵌套 |
+
+CLI 接受可无损转换的 `not: true` 作为兼容输入，但提交前会将其改写成明确的反向筛选类型，例如 `IN` 改为 `NI`、`CONTAINS` 改为 `NOT_CONTAINS`；组合节点按德摩根定律展开。Web 编辑器不会可靠读取节点上的 `not` 字段，因此规范化后的请求始终使用 `not: false`。遇到没有明确反向类型的条件（例如区间 `BT`）时，CLI 会拒绝提交，避免保存后语义与回显不一致。
+
+单条件示例：
+
+```json
+"filter": {
+  "type": "condition",
+  "not": false,
+  "value": {
+    "dsId": "ds_sales",
+    "fdId": "fd_region",
+    "name": "区域",
+    "fdType": "STRING",
+    "metaType": "DIM",
+    "filterType": "IN",
+    "filterValue": ["华东"]
+  }
+}
+```
+
+嵌套条件示例，表示“区域属于华东，并且（城市为空或城市包含杭州）”：
+
+```json
+"filter": {
+  "type": "composition",
+  "not": false,
+  "value": [
+    {
+      "type": "condition",
+      "not": false,
+      "value": { "dsId": "ds_sales", "fdId": "fd_region", "name": "区域", "fdType": "STRING", "metaType": "DIM", "filterType": "IN", "filterValue": ["华东"] }
+    },
+    { "type": "operator", "value": "and" },
+    {
+      "type": "composition",
+      "not": false,
+      "value": [
+        {
+          "type": "condition",
+          "not": false,
+          "value": { "dsId": "ds_sales", "fdId": "fd_city", "name": "城市", "fdType": "STRING", "metaType": "DIM", "filterType": "IS_NULL", "filterValue": [] }
+        },
+        { "type": "operator", "value": "or" },
+        {
+          "type": "condition",
+          "not": false,
+          "value": { "dsId": "ds_sales", "fdId": "fd_city", "name": "城市", "fdType": "STRING", "metaType": "DIM", "filterType": "CONTAINS", "filterValue": ["杭州"] }
+        }
+      ]
+    }
+  ]
+}
+```
+
+禁止使用下面这类其它系统的分组结构：
+
+```json
+{ "type": "group", "value": { "combineType": "AND", "conditions": [] } }
+```
+
+后端可能宽松接收这类 JSON，但 Web 指标编辑器只识别 `condition/operator/composition`，保存后会出现业务限定不回显。条件的 `fdId` 还必须存在于当前可筛选字段中：原子指标使用数据集字段；业务限定衍生指标使用基础指标 `applicableDims`。指标编辑和业务限定写入会优先从指标详情补齐缺少的字段元数据；查询加速条件必须自行提供完整元数据。
+
+兼容输入会在提交前规范化：`EMPTY -> IS_NULL`、`NOT_EMPTY -> NOT_NULL`、`LIKE -> CONTAINS`、`NOT_LIKE -> NOT_CONTAINS`。`IS_NULL/NOT_NULL` 必须携带空数组 `filterValue: []`；其它普通筛选类型必须携带非空数组。不要把这些兼容别名直接写进最终请求。
+
 ## 数据格式 `format`
 
 `format` 是指标数值的展示格式，创建和编辑原子指标、复合指标、衍生指标时都可设置。保存指标时写入 Web 表单使用的 UI 配置，不要写转换后的 d3 `specifier`、Excel format 或预览接口返回值。

package/skills/guanmetric/references/metric-composite-mutation.md

@@ -46,7 +46,7 @@
 - 先用 `guancli metric search <关键词> -d <projectId> -f json` 查询公式中的指标，再用 `guancli metric get <metric_id> --brief` 核对名称、类型、状态和适用维度。
 - 如果用户只提供数据集字段级公式，先询问是否要创建复合指标。用户确认后，再识别公式里的基础度量，创建或复用基础原子指标，并把公式改写为 `[metricId]`。
 - 如果输入来自标准 Excel，字段级公式需要读取 `公式来源数据集ID` / `公式来源数据集名称` 和 `公式字段映射`。没有这些映射时，不要根据 `repr / total_buyer` 这类裸 token 猜测字段或指标；应要求用户补齐或确认。
-- 公式只能引用数值型指标；不要引用当前正在编辑的指标本身。
+- 公式只能引用数值型原子指标或复合指标；不要引用衍生指标、快捷引用指标或当前正在编辑的指标本身。创建计划和提交前都要读取引用指标详情并核对 `subType`。
 - 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
 - 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
 - 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
@@ -58,7 +58,13 @@
 | `SUM([销售额字段]) / COUNT([订单ID字段])` | 先建“销售额”“订单数”原子指标，再建复合指标 `[metric_sales] / [metric_order_count]` |
 | `SUM([归因销售额字段]) / SUM([广告花费字段])` | 先建“归因销售额”“广告花费”原子指标，再建复合指标 ROAS |
 | `SUM([点击量字段]) / SUM([曝光量字段])` | 先建“点击量”“曝光量”原子指标，再建复合指标 CTR |
-| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 先判断分子是否应建为条件计数原子指标或业务限定衍生指标，再创建复合比率指标 |
+| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 优先把分子建为条件计数原子指标，再创建复合比率指标；业务限定衍生指标不能作为复合指标上游 |
+
+如果用户给出的公式依赖衍生指标，不要把它直接提交为复合指标：
+
+- 组合“最近 N、累计、期末值”等受支持衍生结果时，评估改建为组合衍生指标。
+- 表达“某个复合口径的同比/环比”时，通常先创建原子/复合基础口径，再基于该复合指标创建普通衍生指标。
+- 两种改写可能改变业务语义，例如“比率的同比”不等于“两个同比增长率相除”；创建计划必须展示改模方案并让用户确认。
 
 ## 适用维度
 
@@ -117,7 +123,7 @@
 
 1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
 2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
-3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
+3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性；逐个读取引用指标详情，确认 `subType` 仅为 `ATOMIC` 或 `COMPOSITE`。`guanmetric fetch` 也会在提交前执行同一类型检查。
 4. 按 `metric-common-fields.md` 向用户摘要并确认。
 5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
 6. 提交真实创建：

package/skills/guanmetric/references/metric-derived-mutation.md

@@ -263,7 +263,7 @@
 
 ## 业务限定 `BIZ_CONDITION`
 
-业务限定必须提供顶层 `filter`。标准模板使用 `业务限定` 列承载筛选条件 JSON；普通用户可通过页面配置后复制 payload，复杂筛选不建议凭空拼。
+业务限定必须提供顶层 `filter`。标准模板使用 `业务限定` 列承载筛选条件 JSON。`filter` 必须遵循 `metric-common-fields.md` 的 `WebFilterData` 契约；不要使用 `group/combineType/conditions`，该结构即使被后端保存，Web 编辑页也无法正确回显。
 
 ```json
 "deriveSetting": {
@@ -274,12 +274,21 @@
   }
 },
 "filter": {
-  "combineType": "AND",
-  "conditions": []
+  "type": "condition",
+  "not": false,
+  "value": {
+    "dsId": "<base_metric_ds_id>",
+    "fdId": "<applicable_dimension_fd_id>",
+    "name": "<dimension_name>",
+    "fdType": "STRING",
+    "metaType": "DIM",
+    "filterType": "IN",
+    "filterValue": ["华东"]
+  }
 }
 ```
 
-`filter` 结构复杂时，优先参考同环境已有指标详情或由 Web 配置后复制 payload，不凭空拼复杂筛选。
+`filter.value.fdId` 必须来自基础指标的 `applicableDims`，CLI 会据此补齐缺少的 `dsId/name/fdType/metaType`。复杂条件按 `composition.value` 中“条件、运算符、条件”交替排列；优先参考同环境已有指标详情或由 Web 配置后复制 payload，不凭空拼复杂筛选。
 
 ## 组合衍生 `COMPOSITE`
 
@@ -406,7 +415,7 @@
 
 1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、基础指标或组合衍生引用指标、衍生配置、时间维度、格式、业务属性和保存方式。
 2. 用户确认计划后，生成 `/tmp/derived_metric.json`。
-3. 本地/人工检查 JSON、衍生自指标或公式引用指标、时间维度、衍生配置、必填业务属性。
+3. 本地/人工检查 JSON、衍生自指标或公式引用指标、时间维度、衍生配置、必填业务属性。业务限定写入时，CLI 会自动读取 `baseMetricId` 详情并校验 `filter.fdId` 是否属于基础指标 `applicableDims`。
 4. 按 `metric-common-fields.md` 向用户摘要并确认。
 5. 用户确认后，不调用原子指标 `save-precheck`；衍生指标 Web 创建没有 save-precheck。
 6. 提交真实创建：

package/skills/guanmetric/references/metric-excel-template.md

@@ -4,6 +4,59 @@
 
 客户原始 Excel 的语义理解由 agent/大模型完成，不在 CLI 中穷举各种客户列名和业务表达。CLI 保留标准模板能力：固定 sheet/字段结构、必填项红色 `*` 标记、当前环境业务属性配置读取、默认值和 ID 自动填充、`自动填充说明`、`行状态`、`问题说明`、问题字段高亮、列宽自适应、基础字段校验和报告输出。
 
+## 机器 schema、模板生成与创建前校验
+
+不要从长文档或历史 Excel 猜 Sheet、列名和枚举。原子/复合指标的当前机器契约由以下命令提供：
+
+```bash
+guanmetric template schema --type atomic
+guanmetric template schema --type composite
+```
+
+输出 schema version `1.1`。顶层 `sources` 给出本次契约核对使用的 `guandata-core` / `guandata-web` commit、源码路径和 symbol；每列除 `name/type/required` 外，还标明：
+
+- `role=api-input`：最终进入创建接口；`apiField/apiType/apiRequired` 对应实际请求字段。
+- `role=resolver-input`：项目名、目录路径、数据集名等 CLI 辅助输入，先解析为 API 所需 ID，本身不是接口字段。
+- `role=formula-helper`：指标名称或数据集字段的 token 映射，先转换为后端公式中的 `[metricId]`，本身不是接口字段。
+- `sourceRefs`：该列约束所依据的 source ID；`requiredWhen`、`enum`、`format`、`referenceFormat`、`maxLength`、`pattern`、`transform`、`default` 和 `example` 按需输出。
+
+其中：
+
+- 原子指标聚合方式仅支持 `SUM/CNT/CNT_DISTINCT/AVG/MAX/MIN/NUL`；来源字段+聚合方式与字段表达式二选一。
+- 名称最多 50 个字符且只允许中文、英文字母、数字、下划线；英文名称最多 50 个字符且只允许英文字母、数字、下划线；业务口径最多 1000 个字符。
+- 原子和复合创建请求都包含 `applicableDims`。原子模板必须填写；复合模板选择“不沿用表达式中指标的共用维度”时必须填写，沿用模式由创建 payload 发送空数组并由公式引用指标计算共有维度。
+- `useExpressionMetricCommonDims` 在 core 缺省为 `true`，Web 创建请求仍将它作为必传 boolean；模板缺省“是”，创建时显式转换为 `true`。
+- 适用维度包含时间类型字段时，后端要求填写一个时间维度且该字段必须属于适用维度。本地 check-only 没有数据集字段类型元数据，不会根据字段名称猜测它是否为时间类型；实际创建前仍需由数据集 schema/后端校验。
+- 数据格式模板枚举只支持 `默认/数值/货币/百分比`。
+- 筛选格式是 WebFilterData JSON，合法节点为 `condition/operator/composition`。
+- 复合指标公式使用 token；`引用指标` 格式为 `token=指标名称或指标ID`，多个映射用分号分隔。
+- 责任人填写明确用户，或使用 `当前登录用户`；保存方式为 `草稿/上线`。
+
+没有现成输入时直接生成最小模板：
+
+```bash
+guanmetric template init --type atomic --out atomic_metrics.xlsx
+guanmetric template init --type composite --out composite_metrics.xlsx
+```
+
+模板包含当前 schema 的列和一行合法示例。正式生成标准 Excel 前先执行无副作用校验：
+
+```bash
+guanmetric template normalize metrics.xlsx \
+  --check-only \
+  --output json-v1 \
+  --skip-biz-attrs \
+  --skip-id-resolve
+```
+
+`--check-only` 不写 xlsx/report，不创建、修改或上线指标。需要按当前 BI 环境补业务属性和解析主题/目录/数据集时去掉两个 `--skip-*`，这些步骤也只读。输出包含 `valid`、`errorCodes`、`diagnostics` 和 `summary`；每条 diagnostic 给出稳定 code、severity、Sheet、行、列、期望和修正示例。code/column 在校验发生处直接赋值，message 仅用于展示，文案变化不会改变机器分类。只有 `severity=error` 导致非零退出，`TEMPLATE_NEEDS_REVIEW` 保持成功但要求后续确认。
+
+普通 normalize 生成的 report 同样包含 diagnostics，可单独解释：
+
+```bash
+guanmetric template explain-error standard_metrics.report.json --json
+```
+
 对于客户原始 Excel/CSV，agent 必须先读取原表并生成语义映射中间表（建议命名为 `*.ai_mapped.xlsx`），把应创建的原子、复合、同比/环比、最近 N、累计、期末值、业务限定、组合衍生分别写入标准 sheet 后，再执行 `guanmetric template normalize`。不要直接对客户原始 Excel 执行 normalize 后交付结果；如果 report 的 `notes` 提示疑似业务语义列被丢弃但复合/衍生 sheet 为空，必须回到语义映射步骤重做。
 
 如果 report 的 `notes` 提示疑似存在衍生语义但对应衍生 sheet 为空，也必须回到语义映射步骤重做。检查按类型进行：同比/环比语义对应 `同比环比衍生模板`，最近 N/昨日/本周/本月等时间窗口语义对应 `最近N衍生模板`，累计/历史累计语义对应 `累计衍生模板`，期末/末次有值语义对应 `期末值衍生模板`，业务限定/筛选限定语义对应 `业务限定衍生模板`。agent 需要重新判断这些语义是普通筛选能力、时间维度能力，还是应单独创建对应衍生指标；确认不是衍生指标时，应在交付摘要中说明判断依据。
@@ -20,6 +73,8 @@
 ## 标准化命令
 
 ```bash
+guanmetric template normalize <input.xlsx> --check-only --output json-v1
+
 guanmetric template normalize <input.xlsx> \
   --out standard_metrics.xlsx \
   --report standard_metrics_report.json
@@ -94,7 +149,7 @@ guanmetric template normalize <input.xlsx> \
 | `沿用表达式中指标的共用维度` | 复合指标默认 `是` |
 | `适用维度` | 字段名列表 |
 | `时间维度` | 时间字段名 |
-| `数据格式` | 默认、数值、货币、百分比等 |
+| `数据格式` | `默认`、`数值`、`货币`、`百分比` |
 | `责任人` | 业务负责人 |
 | `保存方式` | `草稿` 或 `上线`，缺省自动填 `草稿` |
 | `业务属性:<属性名>` | 当前环境启用的指标自定义业务属性 |
@@ -225,7 +280,7 @@ agent 根据标准模板生成创建 payload 时，必须识别这些成组字
 - `原子指标模板` 行必须明确 `指标类型=原子指标`，并尽量填写数据集、计算方式、适用维度等原子指标字段。计算方式可以是 `来源字段` + `聚合方式`，也可以是 `字段表达式`，但不能同时填写两种。
 - 各衍生指标模板行必须明确 `指标类型=衍生指标`，并根据用户语义放入对应衍生 sheet；例如同比/环比放入 `同比环比衍生模板`，最近 N 天/周/月放入 `最近N衍生模板`，累计放入 `累计衍生模板`，期末值放入 `期末值衍生模板`，业务筛选限定放入 `业务限定衍生模板`，组合衍生放入 `组合衍生模板`。
 - `复合指标模板` 行必须明确 `指标类型=复合指标`，并尽量填写计算公式、引用指标、公式来源数据集和公式字段映射等复合指标字段。
-- 复合指标计算公式中的 `[指标名]` 必须能对应到已有指标或本次将创建的基础指标。若公式引用的指标名不在 `原子指标模板` 中，agent 应在 `原子指标模板` 中补充同名原子指标行，保证后续创建顺序为先创建基础原子指标，再创建复合指标。无法确定数据集、来源字段、聚合方式时先留空或写入最保守默认值，并让 CLI 在 `问题说明` 中暴露需要用户补齐的字段。
+- 复合指标计算公式中的 `[指标名]` 必须能对应到已有或本批先创建的原子指标/复合指标，不能对应衍生指标或快捷引用指标。同批模板发现复合公式引用衍生指标时会把该行标为 `错误`；线上已有指标则在创建计划和 `guanmetric fetch` 提交前读取详情核对 `subType`。缺失依赖应按真实语义补到原子指标模板或复合指标模板，不要一律补成原子指标；无法确定建模方式或必要字段时，在 `问题说明` 中列出待确认项。
 - 衍生指标的 `衍生自` 也必须能对应到已有指标或本次将创建的指标。如果 `衍生自` 是本批也要创建的指标，必须在标准模板阶段就把它列入 `原子指标模板` 或 `复合指标模板`；创建计划阶段只核对和排序，不临时新增模板外基础指标。若该基础指标线上不存在且模板中也没有对应行，agent 必须回到模板补充基础指标行；补充所需信息不足时，在基础指标行或衍生指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、复合公式、引用指标映射、适用维度或时间维度。
 - 客户表中的“表达式”“统计口径”“分子/分母”“达成率”“同比/环比”“最近 N”“累计”“期末值”“业务限定”“维度勾选”等语义，不应靠 CLI 写死列名猜测；agent 应结合整张表和上下文理解后写入标准字段。
 - 标准模板生成后必须检查 `汇总` sheet 的指标总数和衍生指标数，并结合 report.notes 检查是否存在衍生类型缺类。如果业务口径或用户输入中出现明显衍生语义，而对应衍生 sheet 为空，需要回到 `ai_mapped.xlsx` 重做或在交付摘要中明确说明这些语义为什么不创建衍生指标。
@@ -279,7 +334,7 @@ guanmetric fetch GET /api/metric-attr-config
 ## 标准流程
 
 1. 用户给 Excel/CSV 要批量创建指标。
-2. 执行 `guanmetric template normalize` 生成标准 Excel 和 report。
+2. 先执行 `guanmetric template normalize --check-only --output json-v1`，按单元格 diagnostics 修正真实错误；确认预检通过后再执行普通 normalize 生成标准 Excel 和 report。
 3. 把标准 Excel 返回给用户确认，摘要说明：
    - 映射了哪些列。
    - 剔除了哪些冗余列。

package/skills/guanmetric/references/metric-expression-rules.md

@@ -93,10 +93,12 @@ END
 ### 引用限制
 
 - 可引用已上线且当前用户可使用的原子指标、复合指标。
+- 不要引用任何衍生指标；这类依赖需要按业务语义改建为组合衍生，或先创建复合基础口径再做普通衍生。
 - 不要引用当前正在编辑的指标本身。
 - 不要引用快捷引用指标（有 `linkMetricId` 的指标）。
 - 公式中的 `[xxx]` 会被后端识别为上游指标 ID，并参与循环引用校验。
 - 复合指标适用维度必须来自公式中引用指标的共有维度；没有共有维度时会报错。
+- `guanmetric fetch` 会在创建/编辑复合指标前读取每个引用指标详情，只放行 `ATOMIC`/`COMPOSITE`；无法确认类型时停止提交。
 
 ### 避免生成
 

package/skills/guanmetric/references/metric-mutation.md

@@ -56,10 +56,11 @@
 2. 若输入是客户 Excel/CSV，先执行：
 
 ```bash
+guanmetric template normalize <input.xlsx> --check-only --output json-v1
 guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <report.json>
 ```
 
-   把生成的标准 Excel 返回给用户确认，并摘要列映射、剔除列、自动填充字段、ID 自动解析结果、可创建/待确认/错误行数。标准化阶段不自动创建主题、目录或指标；找不到或多候选的主题/目录写入 `问题说明`。用户确认标准 Excel 前，不生成最终创建 payload，不执行 dry-run/precheck，不真实提交。若用户修改标准 Excel 后再次传回，重复执行标准化流程，直到所有行都是 `可创建`。
+   check-only 不写文件也不执行指标写操作；先按 diagnostics 的 Sheet/行/列和稳定错误码修正。通过后把普通 normalize 生成的标准 Excel 返回给用户确认，并摘要列映射、剔除列、自动填充字段、ID 自动解析结果、可创建/待确认/错误行数。标准化阶段不自动创建主题、目录或指标；找不到或多候选的主题/目录写入 `问题说明`。用户确认标准 Excel 前，不生成最终创建 payload，不执行 dry-run/precheck，不真实提交。若用户修改标准 Excel 后再次传回，重复执行标准化流程，直到所有行都是 `可创建`。
 3. 信息不全时先查 ID，不凭空猜：
    - 指标主题：`guancli metric project [keyword] -f json`
    - 指标目录：`guancli metric tree -f json`
@@ -72,6 +73,7 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
    - 原子指标如果填写 `字段表达式`，生成 `formulaField.fdFormula`，且不要同时传 `fdId/aggrType`。
    - 原子指标如果填写 `来源字段` + `聚合方式`，解析为 `fdId` + `aggrType`。
    - 复合指标必须把 `复合公式` 结合 `公式引用指标` 或前置创建结果改写成 `[metricId]` 形式。
+   - 复合指标的每个引用必须解析并核对为 `ATOMIC`/`COMPOSITE`；发现 `DERIVED`/快捷引用指标时停止计划，按业务语义改建为组合衍生或“先复合、后衍生”。
    - `适用维度`、`时间维度`、业务属性列都需要解析成接口字段，不要把中文名原样提交给后端。
 5. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
 6. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
@@ -92,6 +94,7 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
 - 目标目录路径和目录 ID。
 - 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
 - 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
+- 复合指标依赖核对结果：逐个列出引用指标的 ID、名称和 `subType`，只允许原子/复合指标。若原口径依赖衍生指标，必须展示替代建模及语义差异，确认前不生成提交 payload。
 - 衍生指标的 `衍生自` 解析结果：必须先检查标准模板中是否已有同名原子/复合指标行，再查询现有指标。若该 `衍生自` 是本批也要创建的指标，标准模板阶段就必须已经列出对应基础指标行；创建计划阶段只负责核对、排序和暴露缺失信息，不临时新增模板外指标。
 - 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
 - 数据格式、业务负责人、必填业务属性。