@guandata/guanmetric 0.1.0 → 0.1.2

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

@@ -0,0 +1,300 @@
+# 指标 Excel 标准化与批量创建前置流程
+
+当用户提供 Excel/CSV，或提供一段文字、需求描述、粘贴的半结构化表格、截图转写内容等其它信息，希望批量创建指标时，不要直接生成指标 payload。必须先把用户输入标准化为本工具可识别的模板，并把处理后的 Excel 返回给用户确认。当前标准模板支持原子指标、衍生指标和复合指标。
+
+客户原始 Excel 的语义理解由 agent/大模型完成，不在 CLI 中穷举各种客户列名和业务表达。CLI 保留标准模板能力：固定 sheet/字段结构、必填项红色 `*` 标记、当前环境业务属性配置读取、默认值和 ID 自动填充、`自动填充说明`、`行状态`、`问题说明`、问题字段高亮、列宽自适应、基础字段校验和报告输出。
+
+对于客户原始 Excel/CSV，agent 必须先读取原表并生成语义映射中间表（建议命名为 `*.ai_mapped.xlsx`），把应创建的原子、复合、同比/环比、最近 N、累计、期末值、业务限定、组合衍生分别写入标准 sheet 后，再执行 `guanmetric template normalize`。不要直接对客户原始 Excel 执行 normalize 后交付结果；如果 report 的 `notes` 提示疑似业务语义列被丢弃但复合/衍生 sheet 为空，必须回到语义映射步骤重做。
+
+如果 report 的 `notes` 提示疑似存在衍生语义但对应衍生 sheet 为空，也必须回到语义映射步骤重做。检查按类型进行：同比/环比语义对应 `同比环比衍生模板`，最近 N/昨日/本周/本月等时间窗口语义对应 `最近N衍生模板`，累计/历史累计语义对应 `累计衍生模板`，期末/末次有值语义对应 `期末值衍生模板`，业务限定/筛选限定语义对应 `业务限定衍生模板`。agent 需要重新判断这些语义是普通筛选能力、时间维度能力，还是应单独创建对应衍生指标；确认不是衍生指标时，应在交付摘要中说明判断依据。
+
+对于非 Excel/CSV 输入，agent 也必须先生成 `*.ai_mapped.xlsx` 中间表，不能因为输入不是文件就跳过标准模板。处理规则：
+
+- 从文字中抽取指标名称、指标类型、业务口径、数据集、字段、聚合方式、计算公式、衍生类型、衍生自、适用维度、时间维度、保存位置、责任人和业务属性等信息。
+- 能判断为原子/复合/衍生的，放入对应标准 sheet；不能完全判断的，放入最接近的 sheet，并在 `问题说明` 写明需要用户确认的点。
+- 对复合指标公式引用的基础指标、衍生指标的 `衍生自`，如果看起来是本批要创建，也要在 `ai_mapped.xlsx` 阶段补到原子或复合模板中。
+- 信息不足时不要凭空发明 ID、字段或公式；可留空并让 normalize 在 `问题说明` 中暴露缺失项，最终由用户在返回的标准模板 Excel 中修改后重新上传。
+
+标准化流程是可反复执行的：用户收到标准 Excel 后可能会修改并再次传回，agent 应继续执行 `metric template normalize`，直到所有行都是 `可创建` 后，才进入创建计划和真实创建校验。
+
+## 标准化命令
+
+```bash
+guanmetric template normalize <input.xlsx> \
+  --out standard_metrics.xlsx \
+  --report standard_metrics_report.json
+```
+
+可选覆盖参数：
+
+```bash
+guanmetric template normalize <input.xlsx> \
+  --project-id <metric_project_id> \
+  --parent-dir-id <metric_dir_id> \
+  --ds-id <ds_id>
+```
+
+覆盖参数优先级高于 Excel 中的同名列；适合整批指标属于同一主题、目录或数据集的场景。若这些信息在 Excel 中逐行提供，则不需要传覆盖参数。
+
+离线调试时可用 `--skip-biz-attrs` 跳过当前环境业务属性配置读取；正式处理客户批量创建任务时不要跳过。
+
+默认会自动解析并填充已有资源的 `指标主题ID`、`指标目录ID`、`数据集ID`：
+
+- Excel 已提供 ID 时，保留原值，不覆盖。
+- Excel 只有名称且能唯一命中现有资源时，自动回填 ID。
+- `保存至` 为空且主题 ID 已确定时，自动使用主题根目录 ID。
+- 找不到或多候选时不自动创建、不自动选择，标记为 `待确认`，并在 `问题说明` 中写清楚原因。
+- 指标主题名称找不到时，`问题说明` 要说明：若用户确认使用该名称，创建计划将默认新建该指标主题。
+- `保存至` 找不到时，`问题说明` 要说明：若用户确认使用该路径，创建计划将默认在目标主题下新建该目录。
+- 原始文件没有提供指标目录 ID/路径时，不要写成“目录未找到”；应提示“未提供目录，确认主题后创建计划将默认保存到指标主题根目录”。
+- 后续如果确实需要新建主题/目录，应在所有标准化问题收敛后，由 agent 在创建计划中明确列出将创建的主题/目录，等待用户确认后再执行 `metric project-create` / `metric dir-create`。
+
+## 标准模板字段
+
+标准化输出固定为 Excel，并按指标类型拆分工作表：
+
+- `汇总`：放在第一张 sheet，列出本次模板中待创建指标总数、按类型计数，以及每个指标的名称、指标类型、所在模板、关键来源、行状态和问题说明。该 sheet 仅用于用户总览，不作为创建 payload 的事实源。
+- `原子指标模板`：只包含原子指标行和原子指标相关列。
+- `复合指标模板`：只包含复合指标行和复合指标相关列。放在原子指标后面，便于按“先创建基础原子，再创建复合”的顺序检查。
+- `同比环比衍生模板`：只包含同比/环比类衍生指标行。
+- `最近N衍生模板`：只包含最近 N 天/周/月等窗口类衍生指标行。
+- `累计衍生模板`：只包含累计类衍生指标行。
+- `期末值衍生模板`：只包含期末值类衍生指标行。
+- `业务限定衍生模板`：只包含业务筛选/业务限定类衍生指标行。
+- `组合衍生模板`：只包含组合衍生指标行。
+
+用户修改标准 Excel 后再次传回时，工具会读取所有工作表，不只读取第一张表。
+
+基础列包括：
+
+必填列会在表头使用红色 `*` 标注。用户修改后再次传回标准 Excel 时，工具会自动忽略表头中的 `*`，不影响下一轮识别。对于可以由名称解析 ID 的字段，不把 ID 单列标成强必填，并在输出 Excel 中默认隐藏 ID 列，避免干扰普通用户。隐藏列不会删除数据；agent/创建流程仍可读取 `指标主题ID`、`指标目录ID`、`数据集ID`、`公式来源数据集ID`、`衍生自指标ID` 等字段。创建流程应优先使用 ID，没有 ID 时用名称或路径解析。
+
+标准化输出会根据表头和内容长度自动调整列宽。`问题说明`、`自动填充说明`、`业务口径`、`适用维度` 等长文本列会设置更大的上限并保留换行，避免内容被过度截断；普通列会限制最大宽度，避免少数超长值把整张表撑得难以浏览。
+
+`自动填充说明`、`行状态`、`问题说明` 三列会使用浅黄色高亮，用于提示用户重点查看。对于 `问题说明` 中明确指出存在问题的字段，标准化输出会把对应业务字段单元格标为浅红色，例如缺失 `业务属性:归属部门` 时高亮该业务属性列，多时间维度时高亮 `时间维度` 列，主题/目录问题时高亮对应主题/目录列。
+
+重要配置列会写入表头批注，解释字段含义和填写场景，例如 `本期偏移`、`本期区间`、`对比偏移`、`上期时间范围`。
+
+| 列名 | 说明 |
+| --- | --- |
+| `指标类型` | `原子指标`、`衍生指标` 或 `复合指标` |
+| `名称` | 指标中文名 |
+| `英文名称` | 可选 |
+| `业务口径` | 指标描述 |
+| `指标主题ID` / `指标主题名称` | 创建目标主题；ID 优先 |
+| `指标目录ID` / `保存至` | 创建目标目录；ID 优先 |
+| `数据集ID` / `数据集` | 原子指标来源数据集；ID 优先 |
+| `来源字段` | 原子指标来源字段名 |
+| `聚合方式` | 原子指标聚合方式，标准化为 `SUM`、`CNT`、`CNT_DISTINCT`、`AVG`、`MAX`、`MIN`、`NUL` |
+| `字段表达式` | 原子指标表达式，对应 `formulaField.fdFormula`；与 `来源字段` / `聚合方式` 二选一 |
+| `计算公式` | 复合指标公式，如 `[销售额] / [订单数]` |
+| `引用指标` | 可选辅助列 |
+| `公式来源数据集ID` / `公式来源数据集` | 当计算公式中的 token 来自数据集字段时使用；ID 优先 |
+| `公式字段映射` | 当计算公式中的 token 来自数据集字段时，说明 token 对应字段和聚合方式 |
+| `沿用表达式中指标的共用维度` | 复合指标默认 `是` |
+| `适用维度` | 字段名列表 |
+| `时间维度` | 时间字段名 |
+| `数据格式` | 默认、数值、货币、百分比等 |
+| `责任人` | 业务负责人 |
+| `保存方式` | `草稿` 或 `上线`，缺省自动填 `草稿` |
+| `业务属性:<属性名>` | 当前环境启用的指标自定义业务属性 |
+| `自动填充说明` | 记录工具自动填充的字段 |
+| `行状态` | `可创建`、`待确认`、`错误` |
+| `问题说明` | 需要用户处理的问题 |
+
+### 衍生指标模板字段
+
+衍生指标模板会复用基础列、格式责任人列、业务属性列、`自动填充说明`、`行状态`、`问题说明`。不同衍生类型的业务参数不同，因此拆成不同 sheet，并输出各自专属字段。
+
+所有普通衍生 sheet 都包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `衍生自指标ID` / `衍生自` | 前端“衍生自”；ID 优先，普通用户可只填写名称 |
+| `衍生大类` | 系统列，普通衍生固定为 `普通衍生`，默认隐藏 |
+| `衍生类型` | 前端“衍生类型”：`同比/环比`、`最近 N 天/周/月/季度/年`、`累计计算`、`期末值`、`业务限定` |
+| `衍生配置JSON` | 工具会根据可见配置列自动生成；用户也可手填完整 JSON 覆盖，用作复杂配置兜底 |
+| `业务限定` | 前端“业务限定”，可选；填写筛选条件 JSON，对应创建接口顶层 `filter` |
+
+`同比环比衍生模板` 额外包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `时间粒度` | 如 `日`、`周`、`月`、`季度`、`年`，创建时映射为 `DAY/WEEK/MONTH/QUARTER/YEAR` |
+| `默认本期时间范围` | 页面上的默认本期时间范围，对应 `advValue.window`；如 `今天`、`本周`、`本月`、`本季度`、`今年`、`相对日期`、`固定区间`、`时间宏` |
+| `本期偏移` | `默认本期时间范围=相对日期` 时填写 X，对应 `window.offset=X` |
+| `本期区间` | 固定区间或时间宏时填写本期区间，如 `2026-07-01~2026-07-10` 或时间宏表达式 |
+| `对比方式` | 页面上的对比方式；默认 `同环比`，也可填 `自定义偏移`、`自定义时间范围` |
+| `对比类型` | `对比方式=同环比` 时填写，如 `日环比`、`周同比`、`月同比`、`季同比`、`年同比`、`年同比(按周)` |
+| `对比偏移` | `对比方式=自定义偏移` 时填写 X；同环比默认偏移 1 |
+| `上期时间范围` | `对比方式=自定义时间范围` 时填写指定日期或区间，对应 `fixedBase.period` |
+| `数值设置` | `增长值`、`增长率`、`对比值`、`自定义公式`，创建时映射为 `VALUE/RATE/RAWDATA/CUSTOM` |
+| `计算方式` | `数值设置=增长率` 时必填：`(本期数据-上期数据)/上期数据 %` 或 `(本期数据-上期数据)/abs(上期数据) %` |
+| `自定义公式` | `数值设置=自定义公式` 时必填，对应 `formulaSetting` |
+
+同环比和期末值所需的时间字段来自衍生自指标的时间维度，不在模板中展示 `时间字段ID` / `时间字段名称`。创建阶段应读取衍生自指标详情自动填充 `dateFdId/dateFdName`；如果衍生自指标没有唯一时间维度，创建计划必须在 `问题说明` 中提示用户先补齐或调整衍生自指标。`衍生配置JSON` 也默认隐藏，由工具根据可见配置列自动生成，普通用户无需查看。
+
+`最近N衍生模板` 额外包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `时间粒度` | 页面“时间粒度”，如 `日`、`周`、`月`、`季度`、`年` |
+| `计算范围` | 页面“计算范围”，如 `最近7天`、`最近30天`、`最近3月`；标准化时转为接口起止偏移 |
+| `基准日期` | 页面“基准日期”，如 `基于日期筛选: 开始日期`、`基于日期筛选: 结束日期`，默认结束日期 |
+| `开始日期 相对于基准日期前 X 日/周/月/季度/年` | 前端“开始日期 相对于基准日期前 X 日/周/月/季度/年”，通常由 `计算范围` 自动推导 |
+| `结束日期 相对于基准日期前 X 日/周/月/季度/年` | 前端“结束日期 相对于基准日期前 X 日/周/月/季度/年”，通常由 `计算范围` 自动推导 |
+| `计算方式` | 页面“计算方式”，如 `求和`、`平均`、`最大`、`最小`、`计数`、`去重计数`、`无处理` |
+
+最近 N 的开始/结束日期列对齐前端文案，普通用户优先填写 `计算范围`；工具会根据 `计算范围` 自动生成接口所需的 `baselineOffset`，也允许高级场景直接覆盖开始/结束日期偏移。`动态参数JSON` 是隐藏系统列。
+
+`累计衍生模板` 额外包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `计算范围` | 页面“计算范围”，如日累计、周累计、月累计、季度累计、年累计、历史数据、近2年累计 |
+| `基准日期` | 页面“基准日期”，如 `基于日期筛选: 开始日期`、`基于日期筛选: 结束日期`，默认结束日期 |
+| `开始日期` | 页面“开始日期”。仅自定义近 N 个粒度累计时填写 N-1；例如近2年累计填写 `1` |
+| `结束日期` | 页面“结束日期”。填写是否包含基准日期当前值，默认 `是` |
+
+`期末值衍生模板` 不额外展示时间字段列；创建阶段继承衍生自指标时间维度。额外包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `计算逻辑` | 页面“计算逻辑”，可填 `自然最后一天` 或 `末次有值`，默认 `自然最后一天` |
+
+`业务限定衍生模板` 额外包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `业务限定` | 页面“业务限定”，必填筛选条件 JSON，对应创建接口顶层 `filter` |
+
+`组合衍生模板` 包含：
+
+| 列名 | 说明 |
+| --- | --- |
+| `衍生大类` | 系统列，组合衍生固定为 `组合衍生` |
+| `计算公式` | 页面“计算公式”，组合衍生公式 |
+| `引用指标` | 公式中引用的指标映射 |
+| `动态参数JSON` | 可选，动态参数配置 |
+
+`问题说明` 中存在多个问题时，必须按 `问题1：`、`问题2：`、`问题3：` 编号，并使用换行分隔，便于用户逐项修改。
+
+## 原子指标计算方式
+
+原子指标支持两种计算方式，标准模板必须二选一：
+
+- 字段聚合：填写 `来源字段` 和 `聚合方式`，后续创建 payload 写入 `fdId` 和 `aggrType`。
+- 字段表达式：填写 `字段表达式`，后续创建 payload 写入 `formulaField.fdFormula`。
+
+不要在同一行同时填写 `字段表达式` 和 `来源字段` / `聚合方式`。如果客户给的是可拆分的最终计算口径，例如销售额 / 订单数，agent 应先判断是否更适合创建基础原子指标和复合指标；只有用户明确需要数据集字段表达式原子指标，才使用 `字段表达式`。
+
+## 创建阶段读取规则
+
+agent 根据标准模板生成创建 payload 时，必须识别这些成组字段：
+
+| 模板字段组 | 创建参数 | 读取规则 |
+| --- | --- | --- |
+| `指标主题ID` / `指标主题名称` | `projectId` | ID 优先；无 ID 时按名称查询唯一主题；不存在时在创建计划中列出待新建主题 |
+| `指标目录ID` / `保存至` | `parentDirId` | ID 优先；无 ID 时按主题和路径解析目录；目录为空时默认主题根目录 |
+| `数据集ID` / `数据集` | `dsId` | ID 优先；无 ID 时按名称查询唯一数据集 |
+| `来源字段` | `fdId` | 按 `dsId` 的 schema 解析字段 ID |
+| `字段表达式` | `formulaField.fdFormula` | 原子表达式模式；表达式里的字段名也要转换为 `[fdId]` |
+| `适用维度` | `applicableDims` | 按数据集 schema 或引用指标共有维度解析字段 ID 数组 |
+| `时间维度` | `timeDim` | 按字段名解析一个时间字段 ID |
+| `计算公式` + `引用指标` | `formula` | 计算公式最终改写为 `[metricId]` |
+| `业务属性:<属性名>` | `bizAttrs` | 按当前环境属性配置转成 `{id, values}` |
+
+创建阶段不要因为 ID 列为空就直接失败；只有名称/路径也无法唯一解析，或确实缺少整组字段时，才在创建计划中标为待补齐。
+
+## 复合计算公式引用处理
+
+复合指标最终创建时，`计算公式` 必须转换为 `[metricId]` 形式。客户 Excel 中的 `repr / total_buyer` 这类裸 token 不能直接提交给后端。
+
+标准化模板通过以下列收集必要映射：
+
+- `引用指标`：token 对应已有指标时填写，必须使用 `token=指标名称/ID` 形式，例如 `repr=复购人数; total_buyer=总购买人数` 或 `repr=metric_xxx; total_buyer=metric_yyy`。只写 `repr; total_buyer` 不够，因为无法知道它们对应哪个指标。
+- `公式来源数据集ID` / `公式来源数据集`：token 对应数据集字段、需要先创建或复用基础原子指标时填写。
+- `公式字段映射`：token 对应字段和聚合方式，必须使用 `token=字段,聚合方式` 形式，例如 `repr=repr,SUM; total_buyer=buyer_id,CNT_DISTINCT`。
+
+如果 `计算公式` 中存在未用 `[]` 包裹的裸 token，但没有提供 `引用指标` 或 `公式字段映射`，该行必须标记为 `错误`。如果只提供了部分映射，也要在 `问题说明` 中指出缺失的 token。agent 不要猜测 `repr`、`total_buyer` 对应哪个已有指标或字段。
+
+## 客户 Excel 语义理解
+
+当客户 Excel 同时包含原子指标、衍生指标和复合指标时，agent 应按行理解并产出标准字段：
+
+- `原子指标模板` 行必须明确 `指标类型=原子指标`，并尽量填写数据集、计算方式、适用维度等原子指标字段。计算方式可以是 `来源字段` + `聚合方式`，也可以是 `字段表达式`，但不能同时填写两种。
+- 各衍生指标模板行必须明确 `指标类型=衍生指标`，并根据用户语义放入对应衍生 sheet；例如同比/环比放入 `同比环比衍生模板`，最近 N 天/周/月放入 `最近N衍生模板`，累计放入 `累计衍生模板`，期末值放入 `期末值衍生模板`，业务筛选限定放入 `业务限定衍生模板`，组合衍生放入 `组合衍生模板`。
+- `复合指标模板` 行必须明确 `指标类型=复合指标`，并尽量填写计算公式、引用指标、公式来源数据集和公式字段映射等复合指标字段。
+- 复合指标计算公式中的 `[指标名]` 必须能对应到已有指标或本次将创建的基础指标。若公式引用的指标名不在 `原子指标模板` 中，agent 应在 `原子指标模板` 中补充同名原子指标行，保证后续创建顺序为先创建基础原子指标，再创建复合指标。无法确定数据集、来源字段、聚合方式时先留空或写入最保守默认值，并让 CLI 在 `问题说明` 中暴露需要用户补齐的字段。
+- 衍生指标的 `衍生自` 也必须能对应到已有指标或本次将创建的指标。如果 `衍生自` 是本批也要创建的指标，必须在标准模板阶段就把它列入 `原子指标模板` 或 `复合指标模板`；创建计划阶段只核对和排序，不临时新增模板外基础指标。若该基础指标线上不存在且模板中也没有对应行，agent 必须回到模板补充基础指标行；补充所需信息不足时，在基础指标行或衍生指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、复合公式、引用指标映射、适用维度或时间维度。
+- 客户表中的“表达式”“统计口径”“分子/分母”“达成率”“同比/环比”“最近 N”“累计”“期末值”“业务限定”“维度勾选”等语义，不应靠 CLI 写死列名猜测；agent 应结合整张表和上下文理解后写入标准字段。
+- 标准模板生成后必须检查 `汇总` sheet 的指标总数和衍生指标数，并结合 report.notes 检查是否存在衍生类型缺类。如果业务口径或用户输入中出现明显衍生语义，而对应衍生 sheet 为空，需要回到 `ai_mapped.xlsx` 重做或在交付摘要中明确说明这些语义为什么不创建衍生指标。
+- 如果 agent 无法确定指标类型或关键字段，应仍放入最接近的标准 sheet，并在 `问题说明` 写明需要用户确认的内容；不再生成单独的待确认 sheet。
+
+## 业务属性处理
+
+标准化时会读取当前环境：
+
+```bash
+guanmetric fetch GET /api/metric-attr-config
+```
+
+处理规则：
+
+- 只输出 `enabled=true` 的业务属性列。
+- `required=true` 的业务属性列必须存在。
+- 只在客户 Excel 明确提供同名业务属性列，或当前环境配置存在默认值/唯一枚举值时填充业务属性。不要把含义相近但非同名的客户列臆测成业务属性，例如不要把 `业务域` 自动映射为 `业务属性:归属部门`。
+- 如果客户 Excel 缺失必填业务属性：
+  - 有 `defaultValue` 时自动填充。
+  - 没有默认值但枚举选项只有一个时自动填充该选项。
+  - 无法确定时，该行标记为 `错误`，并在 `问题说明` 写明缺失项。
+- 自动填充内容必须写入 `自动填充说明`，例如 `业务属性:指标域=经营分析`。
+
+## 责任人处理
+
+责任人是必填项。客户 Excel 未填写时，标准化阶段自动填充为 `当前登录用户`，并在 `自动填充说明` 和 `问题说明` 中同时标注：`责任人未填写，需确认；创建计划默认使用当前登录用户`。这类问题属于 `待确认`；如果同一行还存在缺失业务属性、多时间维度等硬错误，则该行仍标记为 `错误`。
+
+## 时间维度处理
+
+时间维度只能有一个字段。客户 Excel 如果提供多个时间维度候选，例如 `date、month、ctime`，标准化结果必须标记为 `错误`，并在 `问题说明` 中提示用户只保留一个时间维度。agent 不要替用户猜选。
+
+## 性能规则
+
+标准化阶段按整张表处理，不逐行访问远程接口。
+
+- Excel/CSV 解析、列映射、默认值填充和行级校验均在本地内存完成。
+- 环境级业务属性配置只读取一次。
+- 主题列表只读取一次；目录树按唯一主题读取；数据集按唯一名称查询。
+- 标准化阶段不创建主题、目录或指标。
+- 标准化报告中的 `remoteLookups` 用于记录远程查询次数。
+- 对上千行文件，转换阶段的远程请求数应接近环境配置数量，而不是指标行数。
+
+后续接入批量创建时，应继续遵守：
+
+- 先从标准模板收集唯一 `projectId`、`parentDirId`、`dsId`、引用指标名，再批量查询和缓存。
+- 相同数据集 schema 只读取一次。
+- 真实创建分批执行并限制并发。
+- 保存成功/失败状态写入断点文件，支持失败续跑。
+
+## 标准流程
+
+1. 用户给 Excel/CSV 要批量创建指标。
+2. 执行 `guanmetric template normalize` 生成标准 Excel 和 report。
+3. 把标准 Excel 返回给用户确认，摘要说明：
+   - 映射了哪些列。
+   - 剔除了哪些冗余列。
+   - 自动填充了哪些字段和业务属性。
+   - 哪些行可创建、待确认或有错误。
+4. 如果存在 `错误` 或 `待确认` 行，把标准 Excel 返回给用户修改；用户改完再次传回后，重复执行本流程。
+5. 只有当所有行都是 `可创建` 时，才基于标准 Excel 按 `metric-mutation.md`、`metric-atomic-mutation.md`、`metric-composite-mutation.md` 生成指标创建计划。
+6. 用户确认创建计划后，才执行 dry-run/precheck/真实创建。
+
+## 示例
+
+```bash
+guanmetric template normalize 客户指标清单.xlsx \
+  --out /tmp/standard_metrics.xlsx \
+  --report /tmp/standard_metrics_report.json
+```
+
+命令完成后，返回 `/tmp/standard_metrics.xlsx` 给用户确认。只有用户确认后，才进入创建计划和创建校验流程。

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

@@ -0,0 +1,144 @@
+# 指标表达式 / 计算公式支持范围
+
+本文件用于创建或编辑指标时约束 AI 生成公式的形态，覆盖：
+
+- 原子指标 `formulaField.fdFormula`
+- 复合指标 `formula`
+- 衍生指标选择“组合衍生”时的 `deriveSetting.formula`
+
+## 总体原则
+
+- 用户给出中文字段名或指标名时，最终 payload 必须替换成 ID 引用：数据集字段写 `[fdId]`，指标写 `[metricId]`。
+- 优先生成 Web 编辑器明确支持的简单表达式；复杂函数、嵌套函数、窗口函数、自定义 SQL 函数不要主动生成。
+- 公式中使用英文半角符号：`+ - * / ( ) [ ]`。
+- 不要把指标中文名直接提交到后端；中文名只用于向用户展示“可读公式”。
+- 条件表达式优先使用 `CASE WHEN ... THEN ... ELSE ... END`。虽然底层数据集公式解析能识别部分 `IF(condition, trueValue, falseValue)` 写法，但 AI 生成指标表达式时默认转成 `CASE WHEN`，兼容性更稳定。
+- 如果用户坚持使用本文件未列出的公式形态，先提示可能被前端/后端校验拦截，建议用户在 Web 公式编辑器中校验或先保存草稿验证。
+
+## 原子指标表达式 `formulaField.fdFormula`
+
+原子指标选择“使用表达式”时，表达式走数据集公式编辑器和后端数据集派生字段校验。后端会把公式当成数据集计算字段检查，并要求最终字段是聚合表达式；没有聚合函数会报“原子指标表达式必须包含聚合函数”。
+
+遇到计算表达式时，先询问用户是否希望创建复合指标。用户确认创建复合指标后，再创建或复用表达式中的基础原子指标，并用 `[metricId]` 生成复合指标公式。用户选择原子表达式或明确要求数据集字段表达式时，才在 `formulaField.fdFormula` 中使用 `[fdId]`。
+
+### 推荐支持形态
+
+| 形态 | 示例 | 说明 |
+| --- | --- | --- |
+| 单聚合 | `SUM([fd_amount])` | 最常用 |
+| 计数 | `COUNT([fd_order_id])` | 计数类表达式 |
+| 聚合项加减 | `SUM([fd_amount]) - SUM([fd_refund])` | 多个聚合结果加减 |
+| 聚合内部加减 | `SUM([fd_price] + [fd_tax] - [fd_discount])` | 字段先加减再聚合 |
+| 条件聚合 | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` | 支持 `CASE WHEN`、比较、`AND/OR/NOT` |
+| 条件计数 | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE 0 END)` | 条件计数 |
+| 动态参数 | `SUM(CASE WHEN [fd_amount] > [DYNAMIC_PARAMS.N] THEN [fd_amount] ELSE 0 END)` | 同时在顶层 `dynamicParameters` 写默认值 |
+
+### 避免生成
+
+- 无聚合表达式：`[fd_amount] + [fd_tax]`。
+- 乘法：`SUM([fd_price] * [fd_qty])`、`SUM([fd_a]) * SUM([fd_b])`。
+- 在未询问用户前，直接把可拆分的最终计算指标写成原子表达式。应先确认是否改用基础原子指标 + 复合指标。
+- 非顶层除法：`SUM([fd_a]) + SUM([fd_b]) / SUM([fd_c])`。
+- 多重除法：`SUM([fd_a]) / SUM([fd_b]) / SUM([fd_c])`。
+- `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 等聚合函数表达式；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType=AVG/MAX/MIN`”。
+- 窗口函数、子查询、跨数据集字段、字段中文名直接入参。
+
+## `IF` 语法转 `CASE WHEN`
+
+当用户用自然语言或公式写出 `if` / `IF` 条件语法时，不要照抄 `IF(...)` 到指标 payload，默认转换为 `CASE WHEN`：
+
+| 用户写法 | 生成写法 |
+| --- | --- |
+| `IF(condition, trueValue, falseValue)` | `CASE WHEN condition THEN trueValue ELSE falseValue END` |
+| `SUM(IF([fd_status] = 'paid', [fd_amount], 0))` | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` |
+| `COUNT(IF([fd_status] = 'paid', 1, NULL))` | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE NULL END)` |
+| `IF(SUM([fd_a]) > 0, SUM([fd_b]), 0)` | `CASE WHEN SUM([fd_a]) > 0 THEN SUM([fd_b]) ELSE 0 END` |
+
+嵌套 `IF` 转多分支 `CASE WHEN`：
+
+```text
+IF(c1, v1, IF(c2, v2, v3))
+```
+
+转换为：
+
+```text
+CASE
+  WHEN c1 THEN v1
+  WHEN c2 THEN v2
+  ELSE v3
+END
+```
+
+转换注意事项：
+
+- 必须保留原条件里的比较、`AND/OR/NOT`、字符串字面量和动态参数。
+- 三个参数分别是条件、命中值、未命中值；遇到逗号嵌套在括号或字符串中时，不要错误拆分。
+- 原子指标表达式仍必须满足聚合要求：最终表达式要包含 `SUM` 或 `COUNT` 等聚合上下文。
+- 如果用户给出的 `IF` 结构无法可靠拆分，先向用户确认条件、命中值和未命中值，再生成 `CASE WHEN`。
+
+## 复合指标公式 `formula`
+
+复合指标公式组合已有指标。Web 公式编辑器会把 `[指标名称]` 转成 `[metricId]`；CLI 生成 payload 时必须直接使用 `[metricId]`。
+
+### 推荐支持形态
+
+| 形态 | 示例 |
+| --- | --- |
+| 单指标引用 | `[metric_sales]` |
+| 加减乘除 | `[metric_sales] / [metric_orders]` |
+| 数字常量 | `[metric_sales] * 2 + 100` |
+| 括号分组 | `([metric_sales] - [metric_refund]) / [metric_orders]` |
+
+### 引用限制
+
+- 可引用已上线且当前用户可使用的原子指标、复合指标。
+- 不要引用当前正在编辑的指标本身。
+- 不要引用快捷引用指标（有 `linkMetricId` 的指标）。
+- 公式中的 `[xxx]` 会被后端识别为上游指标 ID，并参与循环引用校验。
+- 复合指标适用维度必须来自公式中引用指标的共有维度；没有共有维度时会报错。
+
+### 避免生成
+
+- 指标中文名入参：`[销售额] / [订单数]` 只能用于展示，payload 必须替换成 `[metricId] / [metricId]`。
+- 数据集字段引用：`[fd_amount]`。
+- 复杂函数、窗口函数、SQL 片段、字符串拼接。
+
+## 衍生指标：组合衍生 `deriveSetting.formula`
+
+组合衍生公式也是指标公式，但引用范围比复合指标更窄。
+
+### 推荐支持形态
+
+同复合指标：`+ - * / ( )`、数字常量、`[metricId]`。
+
+示例：
+
+```text
+[metric_recent_sales] / [metric_recent_orders]
+([metric_xtd_sales] - [metric_xtd_refund]) / [metric_last_inventory]
+```
+
+### 引用限制
+
+- 可引用原子指标。
+- 可引用普通衍生指标中 `RECENT_X`（最近 N）、`XTD`（累计计算）、`LAST`（期末值）。
+- 不要引用组合衍生指标。
+- 不要引用复合指标、快捷引用指标或当前正在编辑的指标。
+- 公式引用的指标必须存在共有时间维度；没有共有时间维度时 Web 会提示“源指标没有共有时间维度，不可配置衍生指标”。
+
+### 避免生成
+
+- 任意数据集字段引用。
+- 函数、窗口函数、SQL 片段。
+- 引用同比/环比、业务限定、组合衍生等不在允许范围内的衍生指标。
+
+## 后端公式合法性校验的安全子集
+
+部分场景（例如指标树归因的贡献分析）会使用更严格的后端公式合法性校验。为了让新建指标后尽量兼容这些场景，AI 默认按以下安全子集生成：
+
+- 原子表达式：`SUM`、`COUNT`、加减、条件表达式；如果有除法，整个表达式必须是一个顶层 `分子 / 分母`，且分子分母分别满足前述规则。
+- 复合指标：最终展开到原子指标后，也应能落到上述安全子集。
+- 衍生组合：优先只做指标间的四则运算；需要参与归因时，优先避免乘法和非顶层除法。
+
+如果用户明确不需要归因/贡献分析，可以按 Web 创建表单的基础限制放宽，但仍应先保存草稿或 dry-run/校验。

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

@@ -0,0 +1,145 @@
+# 指标新建 / 编辑 / 删除指引
+
+本文是指标写操作的入口索引，用于指导 AI 选择应加载的细分文档，避免一次性读取所有指标类型的长配置。当前覆盖原子指标、复合指标、衍生指标的创建/编辑预检查；删除的完整交互流程后续补充。
+
+## 读取顺序
+
+处理指标写操作时按需读取：
+
+1. 先读本文，判断指标类型和整体保存流程。
+2. 如果用户提供 Excel/CSV 批量创建指标，先读取 `metric-excel-template.md`，执行标准化并返回标准 Excel 给用户确认；用户确认前停止在转换阶段。
+3. 始终读取 `metric-common-fields.md`，获取当前环境、通用字段、业务属性 `bizAttrs`、发布/校验规则。
+4. 只读取目标类型文档：
+   - 原子指标：`metric-atomic-mutation.md`
+   - 复合指标：`metric-composite-mutation.md`
+   - 衍生指标：`metric-derived-mutation.md`
+   - 删除指标：`metric-delete-mutation.md`
+5. 如果用户意图不明确，先按“类型判断”问清楚，再加载对应类型文档。
+
+## 类型判断
+
+| 用户意图 | 指标类型 | 读取文档 |
+| --- | --- | --- |
+| 基于一个数据集字段求和、计数、平均、最大、最小、去重计数，或用数据集字段公式生成指标 | 原子指标 `ATOMIC` | `metric-atomic-mutation.md` |
+| 用已有指标做公式，例如销售额 / 订单数、A + B、多个指标组合计算 | 复合指标 `COMPOSITE` | `metric-composite-mutation.md` |
+| 同比、环比、最近 N 天/周/月、累计、期末值、业务限定、组合衍生 | 衍生指标 `DERIVED` | `metric-derived-mutation.md` |
+| 删除、移除某个指标 | 通用删除流程 | `metric-delete-mutation.md` |
+
+常见含混说法：
+
+- “新建一个指标，基于某数据集/某字段”：通常是原子指标。
+- “客单价 = 销售额 / 订单数”：通常是复合指标。
+- “用数据集字段计算一个表达式指标”：先按下方“表达式建模确认”询问用户是否改为复合指标。
+- “给销售额做月环比/最近 7 天/本月累计/华东限定”：通常是衍生指标。
+
+## 表达式建模确认
+
+只要用户要创建的是计算表达式指标，不要直接替用户决定用原子表达式还是复合指标。先向用户确认：
+
+```text
+这个指标需要计算表达式。是否希望我先创建/复用表达式中的基础原子指标，再创建一个复合指标？
+如果选择否，我会按数据集字段表达式创建原子指标。
+```
+
+用户选择“是”时：
+
+1. 拆出表达式中的基础度量。
+2. 先搜索是否已有对应基础原子指标；已有则复用。
+3. 缺失基础指标时，先按 `metric-atomic-mutation.md` 创建基础原子指标。
+4. 再按 `metric-composite-mutation.md` 创建复合指标，公式使用 `[metricId]`，不要使用 `[fdId]`。
+
+用户选择“否”或明确要求数据集字段表达式时，才走原子指标 `formulaField.fdFormula`。
+
+## 总体流程
+
+1. 使用当前已登录环境，不主动询问 profile；写操作前可执行 `guancli auth status`。
+2. 若输入是客户 Excel/CSV，先执行：
+
+```bash
+guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <report.json>
+```
+
+   把生成的标准 Excel 返回给用户确认，并摘要列映射、剔除列、自动填充字段、ID 自动解析结果、可创建/待确认/错误行数。标准化阶段不自动创建主题、目录或指标；找不到或多候选的主题/目录写入 `问题说明`。用户确认标准 Excel 前，不生成最终创建 payload，不执行 dry-run/precheck，不真实提交。若用户修改标准 Excel 后再次传回，重复执行标准化流程，直到所有行都是 `可创建`。
+3. 信息不全时先查 ID，不凭空猜：
+   - 指标主题：`guancli metric project [keyword] -f json`
+   - 指标目录：`guancli metric tree -f json`
+   - 新建指标主题：`guanmetric project-create <name> --dry-run`，确认后去掉 `--dry-run`
+   - 新建指标目录：`guanmetric dir-create <name> --project-id <metric_topic_id> --dry-run`，也可用 `--project-name <metric_topic_name>`；确认后去掉 `--dry-run`。创建子目录可传 `--parent-dir-id`，也可传 `--parent-dir-name`。若主题名称重复必须让用户指定主题 ID；若父目录名称重复必须让用户指定目录 ID
+   - 指标详情：`guancli metric search <keyword> -f json`、`guancli metric get <metric_id> --brief`
+   - 数据集字段：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`
+4. 如果输入来自标准模板，按 `metric-excel-template.md` 的“创建阶段读取规则”生成 payload：
+   - `指标主题ID/名称`、`指标目录ID/路径`、`数据集ID/名称` 都按 ID 优先、名称或路径兜底解析；不要因为 ID 列为空就直接失败。
+   - 原子指标如果填写 `字段表达式`，生成 `formulaField.fdFormula`，且不要同时传 `fdId/aggrType`。
+   - 原子指标如果填写 `来源字段` + `聚合方式`，解析为 `fdId` + `aggrType`。
+   - 复合指标必须把 `复合公式` 结合 `公式引用指标` 或前置创建结果改写成 `[metricId]` 形式。
+   - `适用维度`、`时间维度`、业务属性列都需要解析成接口字段，不要把中文名原样提交给后端。
+5. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
+6. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
+7. 用户确认计划后，生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
+8. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
+9. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
+10. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
+
+不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
+
+## 指标创建计划
+
+创建指标前必须先输出一个计划供用户 review，尤其是一个需求会创建多个基础原子指标和复合指标时。计划确认前不得提交真实创建请求。
+
+计划至少包含：
+
+- 当前环境和目标主题。
+- 目标目录路径和目录 ID。
+- 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
+- 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
+- 衍生指标的 `衍生自` 解析结果：必须先检查标准模板中是否已有同名原子/复合指标行，再查询现有指标。若该 `衍生自` 是本批也要创建的指标，标准模板阶段就必须已经列出对应基础指标行；创建计划阶段只负责核对、排序和暴露缺失信息，不临时新增模板外指标。
+- 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
+- 数据格式、业务负责人、必填业务属性。
+- 将复用的已有指标和将新建的基础指标。
+- 后续会执行的校验：dry-run、save-precheck、validate-update-impact 或本地引用检查。
+
+衍生指标依赖核对顺序：
+
+1. 建立标准模板内将创建的指标索引，至少包含原子指标和复合指标名称，也包含会先创建的普通衍生指标名称。
+2. 处理每个普通衍生指标的 `衍生自指标ID / 衍生自`：有 ID 时读取并校验；无 ID 时先在标准模板索引中按名称唯一匹配。
+3. 如果标准模板没有匹配，再用 `guancli metric search <名称> -f json` 在现有指标中查找，并用 `guancli metric get <metric_id> --brief` 核对类型、状态、适用维度、时间维度。
+4. 如果标准模板和现有指标都没有匹配，说明标准模板缺少基础指标行；不要直接生成提交 payload。必须回到标准模板补充对应原子/复合指标行，或在相关行 `问题说明` 中列出缺失的数据集、字段、聚合方式、公式、适用维度或时间维度，让用户补齐后重新标准化。
+5. 依赖顺序必须保证基础原子/复合指标先创建并取得 ID，再创建衍生指标；计划里使用临时引用名，真实提交前替换为返回的 `metricId`。
+
+计划示例：
+
+```markdown
+### 指标创建计划
+
+环境：demo-guandata
+主题：跨境电商指标体系 (ida4...)
+目录：广告分析 / 投放效果 (dir_xxx)
+
+| 步骤 | 动作 | 指标名称 | 类型 | 核心口径 | 时间维度 | 保存方式 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | 复用 | 归因销售额 | 原子指标 | SUM(attributed_sales) | updated_at | 在线 |
+| 2 | 复用 | 广告花费 | 原子指标 | SUM(spend_amount) | updated_at | 在线 |
+| 3 | 新建 | ROAS | 复合指标 | [归因销售额] / [广告花费] | updated_at | 草稿 |
+
+确认后我会生成 JSON、执行 dry-run/必要校验，再提交创建。
+```
+
+## 校验入口速查
+
+| 操作 | 校验规则 |
+| --- | --- |
+| 原子创建，`publish=true` | 先 `POST /api/metric-platform/metrics/atomic-metrics/save-precheck` |
+| 原子创建，`publish=false` | Web 跳过 save-precheck，可在用户确认后创建草稿 |
+| 原子编辑，`publish=true` | 先 atomic `save-precheck`，请求体带 `metricId`；再跑 `validate-update-impact` |
+| 原子编辑，`publish=false` | 跑 `validate-update-impact` |
+| 复合创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 复合编辑 | 修改 `formula` 或 `filter` 时跑 `validate-update-impact` |
+| 衍生创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 衍生编辑 | 修改 `baseMetricId`、`deriveSetting` 或 `filter` 时跑 `validate-update-impact` |
+| 删除指标 | 先 `GET /api/metric-platform/metrics/{id}/validate-delete-impact`；有下游资源时阻断删除 |
+
+## 命令能力边界
+
+- `guanmetric create` 和 `guanmetric edit` 当前是原子指标专用命令。
+- 复合指标和衍生指标创建/编辑使用 `guanmetric fetch POST ... --stdin < payload.json`。
+- 指标删除使用 `guanmetric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。