@guandata/guanmetric 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.2 - 2026-07-20
+
+- 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
+- 随包提供完整的指标管理说明和参考资料。
+
+## @guandata/guanmetric 0.1.1 - 2026-07-10
+
+- 增强指标 Excel 标准化能力，支持按原子、复合和多类衍生指标拆分标准模板。
+- 新增汇总 sheet，便于用户总览待创建指标、行状态和问题说明。
+- 优化批量创建前的校验和下一步提示，帮助 Agent 引导用户补齐缺失信息后再创建指标。
+
 ## @guandata/guanmetric 0.1.0 - 2026-07-08
 
 - 新增指标写操作 CLI，承接指标创建、编辑、删除、指标主题、指标目录和公共维度管理能力。

package/README.md

@@ -9,6 +9,8 @@ npm install -g @guandata/guanmetric
 guanmetric install-skill
 ```
 
+> `npm install -g` / `npm link` 全局安装时会通过 postinstall 自动执行一次 skill 安装/刷新；上述命令用于手动重装或排查。CI 等无需 skill 的环境可设 `GUAN_SKIP_INSTALL_SKILL=1` 跳过。
+
 ## 常用命令
 
 ```bash
@@ -23,6 +25,17 @@ guanmetric public-dim create --file public_dim.json --dry-run
 
 ## 版本更新
 
+### @guandata/guanmetric 0.1.2
+
+- 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
+- 随包提供完整的指标管理说明和参考资料。
+
+### @guandata/guanmetric 0.1.1
+
+- 增强指标 Excel 标准化能力，支持按原子、复合和多类衍生指标拆分标准模板。
+- 新增汇总 sheet，便于用户总览待创建指标、行状态和问题说明。
+- 优化批量创建前的校验和下一步提示，帮助 Agent 引导用户补齐缺失信息后再创建指标。
+
 ### @guandata/guanmetric 0.1.0
 
 - 新增指标写操作 CLI，承接指标创建、编辑、删除、指标主题、指标目录和公共维度管理能力。

package/bin/postinstall.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * Best-effort post-install hook: refresh the installed AI skill right after
+ * a global npm install/upgrade, so users cannot forget to run
+ * `guanmetric install-skill` and end up with a stale SKILL.md.
+ *
+ * Constraints:
+ * - MUST never fail the npm install: every failure path still exits 0.
+ * - Only runs for global installs (`npm install -g` / `npm link`); a local
+ *   `npm install` inside a project never touches the user's home dirs.
+ * - Escape hatch: GUAN_SKIP_INSTALL_SKILL=1 skips entirely (e.g. CI images
+ *   that install the CLI but never run an AI agent are skipped by default).
+ */
+
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const CLI_NAME = "guanmetric";
+
+function skipReason() {
+  if (process.env.GUAN_SKIP_INSTALL_SKILL === "1") return "GUAN_SKIP_INSTALL_SKILL=1";
+  if (process.env.npm_config_global !== "true") return "not a global install";
+  if (process.env.CI) return "CI environment";
+  return "";
+}
+
+function main() {
+  const reason = skipReason();
+  if (reason) {
+    console.log(`[${CLI_NAME}] postinstall: skipping automatic install-skill (${reason}).`);
+    return;
+  }
+  console.log(`[${CLI_NAME}] postinstall: refreshing AI skill (${CLI_NAME} install-skill)...`);
+  const result = spawnSync(
+    process.execPath,
+    [path.join(__dirname, "run.js"), "install-skill"],
+    { stdio: "inherit", env: process.env, timeout: 180000 }
+  );
+  if (result.error || result.status !== 0) {
+    console.warn(
+      `[${CLI_NAME}] postinstall: automatic skill install did not complete` +
+        (result.error ? ` (${result.error.message})` : ` (exit ${result.status})`) +
+        `; run \`${CLI_NAME} install-skill\` manually to refresh SKILL.md.`
+    );
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.warn(
+    `[${CLI_NAME}] postinstall: ${err.message}; run \`${CLI_NAME} install-skill\` manually.`
+  );
+}
+process.exit(0);

package/bin/run.js

@@ -86,10 +86,36 @@ if (process.argv[2] === "version" && process.argv.length === 3) {
   process.exit(0);
 }
 
+
+// 定位 npm 自带的 npx-cli.js 并用 node 直接执行（与 guanskill 保持一致），
+// 避免 Windows 上 spawn npx.cmd 的两类问题：shell:true 不做参数 quoting
+// （全局安装路径含空格时会被拆参），以及新版 Node 禁止无 shell 的 .cmd
+// spawn（CVE-2024-27980）。postinstall 场景下 npm_execpath 必然可用。
+function resolveNpxInvocation() {
+  const executableDir = path.dirname(process.execPath);
+  const candidates = [];
+  if (process.env.npm_execpath) {
+    candidates.push(path.join(path.dirname(process.env.npm_execpath), "npx-cli.js"));
+  }
+  candidates.push(path.join(executableDir, "node_modules", "npm", "bin", "npx-cli.js"));
+  candidates.push(path.resolve(executableDir, "..", "node_modules", "npm", "bin", "npx-cli.js"));
+  candidates.push(path.resolve(executableDir, "..", "lib", "node_modules", "npm", "bin", "npx-cli.js"));
+  const npxCliPath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (npxCliPath) {
+    return { command: process.execPath, argsPrefix: [npxCliPath] };
+  }
+  if (process.platform === "win32") {
+    throw new Error("Cannot locate npm/bin/npx-cli.js for safe Windows execution");
+  }
+  return { command: "npx", argsPrefix: [] };
+}
+
 if (process.argv[2] === "install-skill") {
   const pkgRoot = path.join(__dirname, "..");
   const extraArgs = process.argv.slice(3);
   const args = [
+    // --yes: postinstall 等非交互环境下 npx 需要免确认下载 skills CLI
+    "--yes",
     "skills",
     "add",
     pkgRoot,
@@ -100,7 +126,12 @@ if (process.argv[2] === "install-skill") {
     ...extraArgs,
   ];
   console.log("Installing guanmetric to AI coding assistants...");
-  const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
+  const npxInvocation = resolveNpxInvocation();
+  const result = spawnSync(npxInvocation.command, [...npxInvocation.argsPrefix, ...args], {
+    stdio: "inherit",
+    env: process.env,
+    shell: false,
+  });
   if (result.error) throw result.error;
   const status = result.status || 0;
   if (status === 0) installBuddySkills(pkgRoot, "guanmetric");

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@guandata/guanmetric",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "观远 BI 指标写操作工具 - 指标创建编辑删除、指标目录、公共维度、Excel 标准化",
   "bin": {
     "guanmetric": "bin/run.js"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "build": "node scripts/build.js && node scripts/sync-skill.js",
     "changelog": "node ../../scripts/generate-release-changelog.js .",
     "check-changelog": "node ../../scripts/check-release-changelog.js .",

package/skills/guanmetric/SKILL.md

@@ -21,7 +21,21 @@ guanmetric public-dim create --file public_dim.json --dry-run
 guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file composite_metric.json
 ```
 
-批量创建指标时，必须先执行 `guanmetric template normalize`，把标准 Excel 返回给用户确认；确认前不生成最终 payload，不提交真实创建。
+批量创建指标时，必须先生成固定结构的标准 Excel 返回给用户确认；确认前不生成最终 payload，不提交真实创建。
+
+如果用户提供的是客户原始 Excel/CSV，而不是已经接近标准模板的文件，agent 必须先自行读取并理解表格语义，产出一个语义映射中间表（建议命名为 `*.ai_mapped.xlsx`），再执行 `guanmetric template normalize` 生成最终标准模板。不要直接把客户原始 Excel 丢给 CLI 后交付结果；CLI 不负责穷举客户列名或业务表述。CLI 继续负责固定模板结构、必填项标记、业务属性配置读取、自动填充说明、行状态、问题说明、高亮样式、列宽自适应、基础校验和 report 输出。
+
+如果用户没有提供 Excel/CSV，而是给出一段文字、需求描述、粘贴的半结构化表格、截图转写内容或其它非文件信息，也必须先由 agent 理解语义并整理成同样的 `*.ai_mapped.xlsx` 中间表，再执行 `guanmetric template normalize` 生成标准模板。信息不足时不要直接放弃；应尽量补出可判断的指标行，并在标准模板的 `问题说明` 中列出缺失的主题、目录、数据集、字段、聚合方式、公式、衍生自、适用维度、时间维度或业务属性，让用户在返回的标准模板中修改后重新上传。
+
+如果 report 的 `notes` 提示“疑似业务语义列被丢弃但复合/衍生 sheet 为空”，说明 agent 跳过了语义映射步骤，必须返回重新读取原始 Excel、拆分原子/复合/衍生后再标准化，不要把全原子模板交给用户。
+
+如果 report 的 `notes` 提示“疑似衍生语义”、某个衍生 sheet 为空，或“所有衍生指标 sheet 均为空”，说明用户输入或业务口径中可能包含同比/环比、最近 N/时间窗口、累计/历史累计、期末值、业务限定等衍生语义，但 agent 没有产出对应衍生模板行。必须回到语义映射步骤重新识别并补充对应类型的衍生指标；不要把衍生指标缺类的模板直接交付给用户。
+
+标准 Excel 第一张固定为 `汇总` sheet，用于给用户总览本次待创建指标总数、按类型计数、指标名称、指标类型、所在模板、关键来源、行状态和问题说明；创建 payload 仍以各指标类型模板 sheet 为事实源，不从 `汇总` sheet 创建。
+
+生成复合指标模板时，如果 `计算公式` 引用的 `[指标名]` 不在原子指标模板中，agent 必须补充同名原子指标行，保证创建时先有基础原子指标，再创建复合指标。
+
+生成衍生指标模板时，如果 `衍生自` 指标不是已明确存在的线上指标，而是本批也要创建的指标，必须在标准模板中补充对应的原子指标或复合指标行；信息不足时先补行并在该基础指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、计算公式、适用维度等。不要等到创建计划阶段才临时新增基础指标。
 
 `fetch` 只用于指标平台写入接口尚未封装为专用命令的场景，例如复合指标/衍生指标创建、编辑和影响校验；常规原子指标、主题、目录、公共维度优先使用专用命令。
 

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

@@ -0,0 +1,225 @@
+# 原子指标创建与编辑
+
+原子指标用于在单个数据集字段或数据集字段表达式上定义指标口径，例如“订购金额 = SUM(订单金额)”。
+
+## 触发场景
+
+- 用户说“创建原子指标”“基于数据集建指标”“用某个字段求和/计数/平均”。
+- 用户给出数据集、字段、聚合方式。
+- 用户要编辑一个 `subType=ATOMIC` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `ATOMIC` |
+| `dsId` | 数据集 ID | 指标来源数据集 |
+| `name` | 指标名称 | 最长 50 |
+| `desc` | 业务口径 | 最长 1000 |
+| `applicableDims` | 适用维度 | 数据集字段 ID 数组，不能为空 |
+| `parentDirId` | 保存至/所属文件夹 | 指标目录 ID |
+| `businessOwner` | 责任人 | 用户 ID |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+计算方式二选一：
+
+| 模式 | 必填字段 | 说明 |
+| --- | --- | --- |
+| 来源字段 + 聚合方式 | `fdId` + `aggrType` | 最常见；标准 Excel 填 `来源字段` 和 `聚合方式`；来源字段是数据集字段 ID |
+| 表达式 | `formulaField.fdFormula` | 标准 Excel 填 `字段表达式`；例如 `SUM([fd_amount]) + SUM([fd_tax])`；不要同时传 `fdId/aggrType`；支持范围见 `metric-expression-rules.md` |
+
+## 原子专属可选字段
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `timeDim` | 时间维度 | 如果适用维度中包含时间字段，优先让用户指定一个时间维度字段 ID |
+| `sourceMetricId` | 来源指标 ID | 复制/快捷等高级场景才传 |
+
+通用可选字段见 `metric-common-fields.md`。
+
+## 聚合方式
+
+| `aggrType` | 中文 |
+| --- | --- |
+| `SUM` | 求和 |
+| `MIN` | 最小值 |
+| `MAX` | 最大值 |
+| `AVG` | 平均值 |
+| `CNT` | 计数 |
+| `CNT_DISTINCT` | 去重计数 |
+| `NUL` | 无处理 |
+
+字段判断：
+
+- 用户只给字段中文名时，先用 `guancli ds get <dsId> --brief` 查字段和 `fdId`。
+- 来源字段是维度字段时，常用计数、去重计数、最大值、最小值、无处理。
+- 来源字段是指标/数值字段时，常用求和、平均值、最大值、最小值、计数、去重计数。
+
+## 表达式限制
+
+当用户选择“使用表达式”时，先读取 `metric-expression-rules.md`。默认只生成当前前后端明确支持的聚合表达式形态：
+
+- `SUM([fd_id])`、`COUNT([fd_id])`
+- 多个聚合项加减：`SUM([fd_a]) - SUM([fd_b])`
+- 条件聚合：`SUM(CASE WHEN ... THEN ... ELSE ... END)`
+
+不要把 `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 主动写进 `formulaField.fdFormula`；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType`”。表达式中字段必须写 `[fdId]`，不要提交字段中文名。
+
+### 计算表达式确认
+
+遇到计算表达式时，不要直接替用户决定创建原子表达式还是复合指标。先说明两种方案并询问：
+
+- 原子表达式：直接在当前数据集字段上生成 `formulaField.fdFormula`。
+- 复合指标：先创建或复用表达式中的基础原子指标，再用 `[metricId]` 公式创建复合指标。
+
+用户选择复合指标后，再拆解基础度量。例如 `SUM([attributed_sales_fd]) / SUM([spend_amount_fd])` 可先创建或复用“归因销售额”“广告花费”两个原子指标，再创建复合指标：
+
+```text
+[metric_attributed_sales] / [metric_ad_spend]
+```
+
+用户选择原子表达式，或明确要求“数据集字段表达式原子指标”时，才使用 `formulaField.fdFormula`。
+
+## 信息收集
+
+如果用户只说“帮我创建一个原子指标”，先收集：
+
+1. 指标主题和保存目录。
+2. 来源数据集和来源字段。
+3. 计算方式：来源字段 + 聚合方式，还是表达式；如果是表达式，先询问用户是否改用复合指标。用户选择原子表达式时，再按 `metric-expression-rules.md` 校验支持形态。
+4. 指标名称、业务口径、适用维度、时间维度、是否保存并上线。
+5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
+6. 责任人是否用当前登录用户。
+7. 指标业务属性中启用且必填的 `bizAttrs`。
+
+## JSON 模板：字段聚合
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "ATOMIC",
+  "dsId": "<ds_id>",
+  "name": "订购金额",
+  "engName": "order_amount",
+  "fdId": "<source_fd_id>",
+  "aggrType": "SUM",
+  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
+  "timeDim": "<time_dim_fd_id>",
+  "format": {
+    "formatType": "CURRENCY",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefix": "￥",
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "suffix": ""
+  },
+  "desc": "统计订单明细中的订购金额总和，用于分析销售规模。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+没有时间维度时删除 `timeDim`；没有英文名称时删除 `engName`；未指定数据格式时删除 `format` 或传 `{}`。
+
+## JSON 模板：表达式
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "ATOMIC",
+  "dsId": "<ds_id>",
+  "name": "含税销售额",
+  "formulaField": {
+    "fdFormula": "SUM([fd_amount]) + SUM([fd_tax])"
+  },
+  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
+  "format": {
+    "formatType": "NUMBER",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "prefix": "",
+    "suffix": ""
+  },
+  "desc": "销售金额与税额之和。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## 创建步骤
+
+1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、来源数据集/字段、聚合方式或表达式、适用维度/时间维度、格式、业务属性和保存方式。
+2. 用户确认计划后，生成 `/tmp/atomic_metric.json`。
+3. 先 dry-run：
+
+```bash
+guanmetric create --file /tmp/atomic_metric.json --dry-run
+```
+
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 如果 `publish=true`，先跑 save-precheck：
+
+```bash
+guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric.json
+```
+
+6. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
+7. 校验通过或二次确认后提交：
+
+```bash
+guanmetric create --file /tmp/atomic_metric.json -f json
+```
+
+8. 响应返回指标 ID 后回读：
+
+```bash
+guancli metric get <metric_id> --brief
+```
+
+## 编辑步骤
+
+编辑原子指标时复用 Web 顺序：必要时先口径冲突校验，再影响校验，最后提交。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> -f json
+```
+
+2. 生成 patch 或完整 payload，先 dry-run：
+
+```bash
+guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json --dry-run
+```
+
+3. 如果 `publish=true`，调用 save-precheck。编辑态请求体需要带 `metricId`：
+
+```bash
+guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric_update_precheck.json
+```
+
+其中 precheck JSON 等于编辑 payload 加：
+
+```json
+{ "metricId": "<metric_id>" }
+```
+
+4. 如果存在 `conflicts`，展示后等待二次确认。
+5. 调用编辑影响校验：
+
+```bash
+guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/<metric_id>/validate-update-impact --stdin < /tmp/atomic_metric_update.json
+```
+
+6. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示影响并等待二次确认。
+7. 提交真实编辑：
+
+```bash
+guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
+```

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

@@ -0,0 +1,168 @@
+# 指标通用配置
+
+本文记录原子指标、复合指标、衍生指标共享的写操作规则、通用字段和业务属性处理方式。处理任一指标创建/编辑任务时，都应先读取本文，再读取对应类型文档。
+
+## 环境与查询
+
+- 默认使用用户当前已登录环境，不询问“创建到哪个 profile”。可先执行 `guancli auth status` 确认登录态。
+- 只有用户明确指定其它环境时，才统一追加 `--profile <profile>`。
+- 用户只给中文名称时，先查询并展示候选；查不到或有多个候选再向用户确认。
+- 常用查询：
+  - 指标主题：`guancli metric project [keyword] -f json`
+  - 指标目录：`guancli metric tree -f json`
+  - 指标：`guancli metric search <keyword> -f json`
+  - 指标详情：`guancli metric get <metric_id> --brief`
+  - 数据集：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`
+
+## 通用字段
+
+| 字段 | 中文 | 适用范围 | 说明 |
+| --- | --- | --- | --- |
+| `projectId` | 主题 ID | 创建/编辑 | 指标所属主题 |
+| `subType` | 指标类型 | 创建/编辑 | `ATOMIC`、`COMPOSITE`、`DERIVED` |
+| `name` | 指标名称 | 创建/编辑 | 最长 50；仅中文、字母、数字、下划线 |
+| `engName` | 英文名称 | 可选 | 最长 50；仅字母、数字、下划线 |
+| `desc` | 业务口径 | 创建/编辑 | 最长 1000；必须能解释业务含义 |
+| `format` | 数据格式 | 可选 | 指标数值展示格式；省略或传 `{}` 表示默认格式 |
+| `parentDirId` | 保存至/所属文件夹 | 创建必填 | 指标目录 ID |
+| `businessOwner` | 责任人 | 创建必填 | 用户 ID，默认可用当前登录用户 |
+| `publish` | 保存方式 | 创建/编辑 | `true` 保存并上线；`false` 保存为草稿 |
+| `bizMetricId` | 关联业务字典 ID | 可选 | 关联后业务口径/业务属性通常会同步 |
+| `bizAttrs` | 业务属性 | 条件必填 | 由环境中的指标属性配置决定 |
+| `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
+| `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |
+
+## 数据格式 `format`
+
+`format` 是指标数值的展示格式，创建和编辑原子指标、复合指标、衍生指标时都可设置。保存指标时写入 Web 表单使用的 UI 配置，不要写转换后的 d3 `specifier`、Excel format 或预览接口返回值。
+
+省略 `format` 或传 `{}` 表示使用默认格式。用户没有明确要求时，不要为了补全字段强行设置格式；用户提到“保留两位小数”“显示百分比”“人民币”“万元”“不要千分位”“加后缀”等，再按下面字段生成。
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `formatType` | 格式类型 | `NUMBER` 数值、`CURRENCY` 货币、`PERCENTAGE` 百分比、`ADVANCED` 高级自定义 |
+| `decimalPlaces` | 小数位数 | `null` 表示 0 位；也可传 `1` 到 `15` |
+| `useThousandsSeparator` | 是否使用千分位 | `true/false` |
+| `prefix` | 前缀/货币符号 | 货币常用 `￥`、`$`、`€`、`£`；后端兼容旧字段 `currencySymbol`，新建优先写 `prefix` |
+| `suffix` | 后缀 | 如 `元`、`人`、`单`、`次`；没有则省略或传空字符串 |
+| `prefixUnit` | 数量级单位 | `null` 无，`K`、`M`、`万`、`亿` 或 `auto` 自动 |
+| `showPrefixUnit` | 是否展示数量级单位 | 数值/货币格式可用；`prefixUnit=auto` 时应为 `true` |
+| `divideDataBy` | 百分比是否除以 100 | 百分比格式可用；`1` 适合底层值是比例小数如 `0.85`，`100` 适合底层值已是百分数如 `85` |
+| `customFormat` | 高级自定义格式 | `formatType=ADVANCED` 时使用；除非用户给出现成格式串，否则不要主动生成 |
+| `suffixSizePercent` | 后缀字号比例 | 部分卡片展示场景使用，指标创建/编辑通常不需要 |
+
+常用模板：
+
+```jsonc
+// 默认格式：省略 format 或传 {}
+"format": {}
+
+// 数值：千分位，保留 2 位小数
+"format": {
+  "formatType": "NUMBER",
+  "decimalPlaces": 2,
+  "useThousandsSeparator": true,
+  "prefixUnit": null,
+  "showPrefixUnit": true,
+  "prefix": "",
+  "suffix": ""
+}
+
+// 货币：人民币，千分位，保留 2 位小数
+"format": {
+  "formatType": "CURRENCY",
+  "decimalPlaces": 2,
+  "useThousandsSeparator": true,
+  "prefix": "￥",
+  "prefixUnit": null,
+  "showPrefixUnit": true,
+  "suffix": ""
+}
+
+// 百分比：底层值为 0.85 时展示为 85.00%
+"format": {
+  "formatType": "PERCENTAGE",
+  "decimalPlaces": 2,
+  "divideDataBy": 1,
+  "useThousandsSeparator": false,
+  "prefix": "",
+  "suffix": ""
+}
+
+// 百分比：底层值为 85 时展示为 85.00%
+"format": {
+  "formatType": "PERCENTAGE",
+  "decimalPlaces": 2,
+  "divideDataBy": 100,
+  "useThousandsSeparator": false,
+  "prefix": "",
+  "suffix": ""
+}
+
+// 数值：按万元展示
+"format": {
+  "formatType": "NUMBER",
+  "decimalPlaces": 2,
+  "useThousandsSeparator": true,
+  "prefixUnit": "万",
+  "showPrefixUnit": true,
+  "prefix": "",
+  "suffix": "元"
+}
+```
+
+## 业务属性 `bizAttrs`
+
+`bizAttrs` 是管理员配置的指标自定义业务属性，不是固定字段。创建或编辑指标前读取当前环境配置：
+
+```bash
+guanmetric fetch GET /api/metric-attr-config
+```
+
+响应关键字段：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `id` | 属性 ID | 写入 `bizAttrs[].id` |
+| `name` | 属性名称 | 用于向用户提问 |
+| `description` | 属性描述 | 可作为输入提示 |
+| `valueType` | 属性值类型 | `ENUM_SINGLE`、`ENUM_MULTIPLE`、`TEXT`、`TEXT_AREA` |
+| `defaultValue` | 默认值 | 用户未指定且允许默认时可采用 |
+| `optionValue` | 枚举选项 | 枚举单选/多选必须从这里选择 |
+| `required` | 是否必填 | `true` 且 `enabled=true` 时必须收集 |
+| `enabled` | 是否启用 | 只处理启用的属性 |
+
+处理规则：
+
+- 只展示和写入 `enabled=true` 的属性；其中 `required=true` 是必填项。
+- `ENUM_SINGLE`：`values` 只能有一个值，且必须来自 `optionValue`。
+- `ENUM_MULTIPLE`：`values` 可以有多个值，且都必须来自 `optionValue`。
+- `TEXT`：写入 `values[0]`，Web 单项最大 50 个字符。
+- `TEXT_AREA`：写入 `values[0]`，Web 单项最大 200 个字符。
+- 如果关联了业务字典 `bizMetricId`，业务口径和业务属性通常由业务字典同步；仍需确认最终 payload 中 `desc` 和 `bizAttrs` 已有值。
+
+示例：
+
+```json
+"bizAttrs": [
+  { "id": "attr_region", "values": ["华东"] },
+  { "id": "attr_tags", "values": ["销售", "核心"] },
+  { "id": "attr_owner_note", "values": ["用于经营分析月报"] }
+]
+```
+
+## 保存与确认
+
+- 先输出“指标创建计划”让用户 review；计划确认前不生成最终提交 JSON，不执行真实创建。
+- 用户确认计划后，再生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
+- 计划/摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、依赖顺序、复用/新建指标、适用维度/时间维度、数据格式、业务属性、保存方式。
+- 如果适用维度中存在时间字段但时间维度为空，计划必须标记为待确认，不能继续提交。
+- 用户确认后按类型执行 save-precheck 或 validate-update-impact。
+- 如果校验返回冲突或影响下游资源，展示冲突指标、受影响指标、受影响卡片，并等待二次确认。
+- 写入成功后回读 `guancli metric get <metric_id> --brief`。
+
+## 发布状态判断
+
+- 用户说“先别上线”“保存草稿”：`publish=false`。
+- 用户说“直接上线”“发布”：`publish=true`，提交前提醒会创建或更新在线指标。
+- 不要把 `publish=true` 自动当成用户已经确认所有冲突；冲突/影响校验仍需要单独二次确认。