@guandata/guancli 1.0.34 → 1.0.36

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guancli 1.0.36 - 2026-06-24
+
+- `metric` 增加指标主题和指标目录创建能力，便于直接准备指标管理结构。
+- 补充 SuperApp 创建指导，帮助 Agent 按应用和页面场景组织 BI 配置。
+- 页面资源搜索和结果展示增强，按名称或 ID 查找页面时结果更稳定、更易读。
+- `install-skill` 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。
+
+## @guandata/guancli 1.0.35 - 2026-06-17
+
+- `metric by-dataset` 增强数据集下游指标查询，并补充指标创建/编辑参考说明。
+- `login status` 使用服务端 profile 校验登录状态，减少本地缓存状态误判。
+- 数据集字段输出增加 raw name、alias/displayName 疑似误用提示，便于 ETL 和指标配置前排查字段引用。
+
 ## @guandata/guancli 1.0.34 - 2026-06-15
 
 - `metric by-dataset` 支持按数据集 ID 反查直接原子指标，并沿指标血缘展开下游复合指标和衍生指标。

package/README.md

@@ -39,9 +39,22 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.36
+
+- `metric` 增加指标主题和指标目录创建能力，便于直接准备指标管理结构。
+- 补充 SuperApp 创建指导，帮助 Agent 按应用和页面场景组织 BI 配置。
+- 页面资源搜索和结果展示增强，按名称或 ID 查找页面时结果更稳定、更易读。
+- `install-skill` 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。
+
+### @guandata/guancli 1.0.35
+
+- `metric by-dataset` 增强数据集下游指标查询，并补充指标创建/编辑参考说明。
+- `login status` 使用服务端 profile 校验登录状态，减少本地缓存状态误判。
+- 数据集字段输出增加 raw name、alias/displayName 疑似误用提示，便于 ETL 和指标配置前排查字段引用。
+
 ### @guandata/guancli 1.0.34
 
-- `metric by-dataset` 支持按数据集 ID 反查直接原子指标，并沿指标血缘展开下游复合指标和衍生指标。
+- `metric by-dataset` 优先使用后端批量接口按数据集 ID 反查直接原子指标和下游复合/衍生指标，旧版 BI 会自动回退到本地扫描逻辑。
 
 ### @guandata/guancli 1.0.33
 

package/bin/run.js

@@ -51,20 +51,32 @@ function copyDirectory(src, dest) {
   }
 }
 
-function installCodeBuddySkill(pkgRoot, skill) {
-  try {
-    const srcDir = path.join(pkgRoot, "skills", skill);
-    if (!fs.existsSync(path.join(srcDir, "SKILL.md"))) {
-      console.warn(`Warning: skipping CodeBuddy/WorkBuddy install; skill not found: ${srcDir}`);
-      return;
-    }
+function installBuddySkills(pkgRoot, skill) {
+  const srcDir = path.join(pkgRoot, "skills", skill);
+  if (!fs.existsSync(path.join(srcDir, "SKILL.md"))) {
+    console.warn(`Warning: skipping buddy install; skill not found: ${srcDir}`);
+    return;
+  }
 
-    const configDir = process.env.CODEBUDDY_CONFIG_DIR || path.join(os.homedir(), ".codebuddy");
-    const destDir = path.join(configDir, "skills", skill);
-    copyDirectory(srcDir, destDir);
-    console.log(`Installed ${skill} to CodeBuddy/WorkBuddy: ${destDir}`);
-  } catch (err) {
-    console.warn(`Warning: CodeBuddy/WorkBuddy install failed for ${skill}: ${err.message}`);
+  const targets = [
+    {
+      name: "CodeBuddy",
+      configDir: process.env.CODEBUDDY_CONFIG_DIR || path.join(os.homedir(), ".codebuddy"),
+    },
+    {
+      name: "WorkBuddy",
+      configDir: process.env.WORKBUDDY_CONFIG_DIR || path.join(os.homedir(), ".workbuddy"),
+    },
+  ];
+
+  for (const target of targets) {
+    try {
+      const destDir = path.join(target.configDir, "skills", skill);
+      copyDirectory(srcDir, destDir);
+      console.log(`Installed ${skill} to ${target.name}: ${destDir}`);
+    } catch (err) {
+      console.warn(`Warning: ${target.name} install failed for ${skill}: ${err.message}`);
+    }
   }
 }
 
@@ -91,7 +103,7 @@ if (process.argv[2] === "install-skill") {
   const result = spawnSync("npx", args, { stdio: "inherit", env: process.env, shell: true });
   if (result.error) throw result.error;
   const status = result.status || 0;
-  if (status === 0) installCodeBuddySkill(pkgRoot, "guancli");
+  if (status === 0) installBuddySkills(pkgRoot, "guancli");
   process.exit(status);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guancli",
-  "version": "1.0.34",
+  "version": "1.0.36",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"

package/skills/guancli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: guancli
-description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric、公共维度 public dimension、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID、公共维度 ID 想看现有内容/查询数据时，主动使用这个 skill。用户要创建、新建、编辑、删除指标或公共维度，尤其是“创建原子指标”“创建复合指标”“创建衍生指标”“新增 metric”“基于数据集建指标”“用两个指标算一个指标”“做同比/环比/最近N天/累计/期末值指标”“新建公共维度”“把几个数据集字段关联成公共维度”时，也要使用这个 skill 并读取对应写操作指引。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个原子指标""帮我创建一个复合指标""帮我创建一个同比指标""帮我创建一个公共维度"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标/公共维度写操作引导。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
+description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric、公共维度 public dimension、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID、公共维度 ID 想看现有内容/查询数据时，主动使用这个 skill。用户要创建、新建、编辑、删除指标或公共维度，或创建指标主题/指标目录，尤其是“创建原子指标”“创建复合指标”“创建衍生指标”“新增 metric”“基于数据集建指标”“用两个指标算一个指标”“做同比/环比/最近N天/累计/期末值指标”“新建指标主题”“新建指标目录”“新建公共维度”“把几个数据集字段关联成公共维度”时，也要使用这个 skill 并读取对应写操作指引。用户提到“创建超级应用”“创建 SuperApp”“新建 SuperApp 项目”“SuperApp 模板项目”时，也要使用这个 skill，并引导使用 `guancli app create`。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令""帮我创建一个原子指标""帮我创建一个复合指标""帮我创建一个同比指标""帮我创建一个指标主题""帮我创建一个指标目录""帮我创建一个公共维度""帮我创建一个超级应用"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是 BI 查询分析 + 表单填报 CRUD + 指标/公共维度写操作引导 + SuperApp 模板项目创建。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
 compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
 ---
 
@@ -17,9 +17,11 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
 - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
 - 用户给出数据集 ID，想查看该数据集创建或影响到的所有指标，包括直接原子指标以及下游复合指标、衍生指标。
 - 用户要创建、新建、编辑或删除指标；当前指标写操作指引先覆盖原子指标、复合指标、衍生指标的创建和编辑前校验。
+- 用户要创建指标主题或指标目录。
 - 用户要查询、新建、编辑、转移责任人或删除指标公共维度。
+- 用户要创建超级应用 / SuperApp / SuperApp 模板项目。
 
-如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。页面截图不要再走 `guanexport`；移动端页面/卡片导出仍暂用 `guanexport` legacy 功能。
+如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。
 
 ## 数据获取方式
 
@@ -81,7 +83,7 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的写操作（Form 表单填报 CRUD、指标写操作引导）。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的写操作（Form 表单填报 CRUD、指标写操作引导）和 SuperApp 模板项目创建。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |------|-------------|
@@ -91,6 +93,20 @@ guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的
 
 > guancli 能显示 ETL 的节点定义和 SQL，但 ETL 的新建、修改、保存、执行闭环应通过 `guanetl` 完成。
 
+## SuperApp 项目创建
+
+当用户提到创建超级应用、创建 SuperApp、新建 SuperApp 项目或基于 SuperApp 模板初始化项目时，使用 `guancli app create`。
+
+```bash
+guancli app create --name <project_name> --path <parent_dir>
+```
+
+关键规则：
+
+- `--name` 是项目名称，`--path` 是项目所在的父目录；信息不全时先确认项目名称和目标目录。
+- 该命令会下载 SuperApp 模板并创建项目目录，随后尝试复制 `.env.template`、更新 `package.json` 名称、初始化 git，并根据模板情况执行 `setup.sh` 或 `npm install` + 启动本地 dev server。
+- 如果用户只是要创建本地 SuperApp 模板项目，不需要先做 BI 资源查询；直接给出或执行 `guancli app create`。
+
 ## 先做判断
 
 1. 先用 `auth status` 确认认证是否有效。
@@ -117,7 +133,9 @@ guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的
 关键规则：
 
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
-- 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；该命令会先定位使用该数据集的原子指标，再沿指标下游血缘展开复合指标和衍生指标，适合回答“这个数据集关联了哪些指标 / 改这个数据集会影响哪些指标”。如果已知指标主题，可加 `-d <metric_topic_id>` 缩小搜索范围；需要结构化结果时用 `-f json`。
+- 创建指标主题用 `guancli metric project-create <name>`；创建后后端会同步创建主题根目录。默认图标与 Web 新建主题一致，可用 `--icon`、`--icon-color` 覆盖；真实提交前可加 `--dry-run` 查看请求体。
+- 创建指标目录用 `guancli metric dir-create <name> --project-id <metric_topic_id>`，也可用 `--project-name <name>` 按主题名称解析；默认创建在该主题根目录下。创建子目录优先传 `--parent-dir-id <dir_id>`，也可用 `--parent-dir-name <name>` 按父目录名称解析；真实提交前可加 `--dry-run` 查看请求体。信息不全时先用 `guancli metric project` 和 `guancli metric tree` 定位主题 ID、目录 ID。若用户只给主题名称且当前环境下有重复主题名，必须让用户从候选主题 ID 中指定一个；若用户只给父目录名称且同一主题下有重复目录名，必须让用户从候选目录 ID 中指定一个，不要自行猜测。
+- 按数据集反查指标用 `guancli metric by-dataset <ds_id>`；新版 BI 会走后端批量接口直接返回直接指标和下游指标，旧版 BI 会兼容回退为先定位使用该数据集的原子指标、再沿指标下游血缘展开复合指标和衍生指标。适合回答“这个数据集关联了哪些指标 / 改这个数据集会影响哪些指标”。如果已知指标主题，可加 `-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>`。
 - 当用户要创建或编辑原子指标、复合指标、衍生指标时，先读取 `references/metric-mutation.md` 判断类型，再读取 `references/metric-common-fields.md`，最后只读取对应类型文件：原子指标读 `references/metric-atomic-mutation.md`，复合指标读 `references/metric-composite-mutation.md`，衍生指标读 `references/metric-derived-mutation.md`。如果涉及原子指标表达式 `formulaField.fdFormula`、复合指标 `formula` 或组合衍生 `deriveSetting.formula`，必须同时读取 `references/metric-expression-rules.md`，按当前前后端支持的表达式形态生成。默认使用当前已登录环境，不询问 profile；按必填项、数据格式 `format` 和启用的指标业务属性配置逐步查询/确认，生成 JSON 文件并先做 dry-run/人工摘要。用户确认后仍需按 Web 同款保存前校验执行：原子指标上线前跑 save-precheck，编辑态跑 validate-update-impact；复合指标和衍生指标编辑态跑 validate-update-impact。校验通过或二次确认后才真实提交。

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

@@ -63,17 +63,31 @@
 - `SUM([fd_id])`、`COUNT([fd_id])`
 - 多个聚合项加减：`SUM([fd_a]) - SUM([fd_b])`
 - 条件聚合：`SUM(CASE WHEN ... THEN ... ELSE ... END)`
-- 一个顶层比值：`SUM([fd_a]) / COUNT([fd_b])` 或 `(SUM([fd_a]) + SUM([fd_b])) / SUM([fd_c])`
 
 不要把 `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` 校验支持形态。
+3. 计算方式：来源字段 + 聚合方式，还是表达式；如果是表达式，先询问用户是否改用复合指标。用户选择原子表达式时，再按 `metric-expression-rules.md` 校验支持形态。
 4. 指标名称、业务口径、适用维度、时间维度、是否保存并上线。
 5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
 6. 责任人是否用当前登录用户。
@@ -140,28 +154,29 @@
 
 ## 创建步骤
 
-1. 生成 `/tmp/atomic_metric.json`。
-2. 先 dry-run：
+1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、来源数据集/字段、聚合方式或表达式、适用维度/时间维度、格式、业务属性和保存方式。
+2. 用户确认计划后，生成 `/tmp/atomic_metric.json`。
+3. 先 dry-run：
 
 ```bash
 guancli metric create --file /tmp/atomic_metric.json --dry-run
 ```
 
-3. 按 `metric-common-fields.md` 向用户摘要并确认。
-4. 如果 `publish=true`，先跑 save-precheck：
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 如果 `publish=true`，先跑 save-precheck：
 
 ```bash
 guancli fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric.json
 ```
 
-5. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
-6. 校验通过或二次确认后提交：
+6. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
+7. 校验通过或二次确认后提交：
 
 ```bash
 guancli metric create --file /tmp/atomic_metric.json -f json
 ```
 
-7. 响应返回指标 ID 后回读：
+8. 响应返回指标 ID 后回读：
 
 ```bash
 guancli metric get <metric_id> --brief

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

@@ -35,6 +35,8 @@ guancli metric [command]
 | `by-dataset` | 按数据集 ID 获取直接和下游关联指标 |
 | `query` | 查询指标数据 |
 | `tree` | 获取指标目录树 |
+| `project-create` | 创建指标主题 |
+| `dir-create` | 创建指标目录 |
 | `create` | 新建原子指标（JSON 文件驱动） |
 | `edit` | 编辑原子指标（JSON patch / replace） |
 | `delete` | 删除指标（先执行删除影响校验） |
@@ -59,6 +61,30 @@ guancli metric project 经营 --profile default -f json
 guancli metric project 经营 --profile default --raw
 ```
 
+### metric project-create
+
+创建指标主题。主题创建成功后，后端会同步创建该主题根目录。默认图标和颜色与 Web 新建主题一致，可按需覆盖。
+
+```bash
+guancli metric project-create <name> [flags]
+```
+
+专属参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--icon string` | `finance_subject` | 主题图标 |
+| `--icon-color string` | `#1A827F` | 主题图标颜色 |
+| `--dry-run` | `false` | 只输出请求方法和请求体，不提交 |
+
+示例：
+
+```bash
+guancli metric project-create 经营指标 --profile default --dry-run
+guancli metric project-create 经营指标 --profile default
+guancli metric project-create 经营指标 --profile default --icon finance_subject --icon-color '#1A827F'
+```
+
 ### metric search
 
 搜索指标；传关键词时后台用 `%keyword%` 模糊匹配，不传关键词返回所有指标。
@@ -183,6 +209,36 @@ guancli metric tree --profile default -f json
 guancli metric tree --profile default --raw
 ```
 
+### metric dir-create
+
+创建指标目录。默认在指定主题根目录下创建；可用 `--project-id` 指定主题 ID，也可用 `--project-name` 按主题名称解析。创建子目录时可用 `--parent-dir-id` 指定父目录 ID，也可用 `--parent-dir-name` 按父目录名称解析。
+如果当前环境下存在多个同名主题，CLI 会阻断创建并列出候选 ID，此时应让用户指定 `--project-id`。
+如果同一主题下存在多个同名父目录，CLI 会阻断创建并列出候选路径和 ID，此时应让用户指定 `--parent-dir-id`。
+
+```bash
+guancli metric dir-create <name> (--project-id <metric_topic_id> | --project-name <metric_topic_name>) [flags]
+```
+
+专属参数：
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `--project-id string` | 无 | 指标主题 ID；与 `--project-name` 二选一 |
+| `--project-name string` | 无 | 指标主题名称；同名主题重复时改用 `--project-id` |
+| `--parent-dir-id string` | 无 | 父目录 ID；为空时 CLI 自动使用主题根目录 |
+| `--parent-dir-name string` | 无 | 父目录名称；同名目录重复时改用 `--parent-dir-id` |
+| `--dry-run` | `false` | 只输出请求方法和请求体，不提交 |
+
+示例：
+
+```bash
+guancli metric dir-create 广告分析 --profile default --project-id <metric_topic_id> --dry-run
+guancli metric dir-create 广告分析 --profile default --project-id <metric_topic_id>
+guancli metric dir-create 广告分析 --profile default --project-name 经营指标
+guancli metric dir-create 投放效果 --profile default --project-id <metric_topic_id> --parent-dir-id <dir_id>
+guancli metric dir-create 投放效果 --profile default --project-name 经营指标 --parent-dir-name 广告分析
+```
+
 ### metric create
 
 新建原子指标。写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，原子字段、问询流程和 JSON 模板见 `metric-atomic-mutation.md`。复合指标和衍生指标创建当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics --stdin`，分别见 `metric-composite-mutation.md` 和 `metric-derived-mutation.md`。

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

@@ -153,8 +153,10 @@ guancli fetch GET /api/metric-attr-config
 
 ## 保存与确认
 
-- 先生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
-- 摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、适用维度/时间维度、数据格式、业务属性、保存方式。
+- 先输出“指标创建计划”让用户 review；计划确认前不生成最终提交 JSON，不执行真实创建。
+- 用户确认计划后，再生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
+- 计划/摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、依赖顺序、复用/新建指标、适用维度/时间维度、数据格式、业务属性、保存方式。
+- 如果适用维度中存在时间字段但时间维度为空，计划必须标记为待确认，不能继续提交。
 - 用户确认后按类型执行 save-precheck 或 validate-update-impact。
 - 如果校验返回冲突或影响下游资源，展示冲突指标、受影响指标、受影响卡片，并等待二次确认。
 - 写入成功后回读 `guancli metric get <metric_id> --brief`。

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

@@ -6,6 +6,7 @@
 
 - 用户说“创建复合指标”“基于多个指标算一个指标”。
 - 用户描述的口径是已有指标之间的四则运算。
+- 用户给出数据集字段计算表达式后，确认希望先创建/复用基础原子指标，再创建复合指标。
 - 用户要编辑一个 `subType=COMPOSITE` 的指标。
 
 ## 创建必填信息
@@ -43,11 +44,21 @@
 
 - 涉及复合指标 `formula` 时，先读取 `metric-expression-rules.md`。
 - 先用 `guancli metric search <关键词> -d <projectId> -f json` 查询公式中的指标，再用 `guancli metric get <metric_id> --brief` 核对名称、类型、状态和适用维度。
+- 如果用户只提供数据集字段级公式，先询问是否要创建复合指标。用户确认后，再识别公式里的基础度量，创建或复用基础原子指标，并把公式改写为 `[metricId]`。
 - 公式只能引用数值型指标；不要引用当前正在编辑的指标本身。
 - 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
 - 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
 - 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
 
+用户确认创建复合指标后的字段公式改写示例：
+
+| 用户口径 | 建模方式 |
+| --- | --- |
+| `SUM([销售额字段]) / COUNT([订单ID字段])` | 先建“销售额”“订单数”原子指标，再建复合指标 `[metric_sales] / [metric_order_count]` |
+| `SUM([归因销售额字段]) / SUM([广告花费字段])` | 先建“归因销售额”“广告花费”原子指标，再建复合指标 ROAS |
+| `SUM([点击量字段]) / SUM([曝光量字段])` | 先建“点击量”“曝光量”原子指标，再建复合指标 CTR |
+| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 先判断分子是否应建为条件计数原子指标或业务限定衍生指标，再创建复合比率指标 |
+
 ## 适用维度
 
 复合指标的适用维度来自公式中引用指标的共有维度：
@@ -103,17 +114,18 @@
 
 `guancli metric create` 当前是原子指标专用 endpoint；复合指标创建使用 `guancli fetch`。
 
-1. 生成 `/tmp/composite_metric.json`。
-2. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
-3. 按 `metric-common-fields.md` 向用户摘要并确认。
-4. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
-5. 提交真实创建：
+1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
+2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
+3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
+6. 提交真实创建：
 
 ```bash
 guancli fetch POST /api/metric-platform/metrics/composite-metrics --stdin < /tmp/composite_metric.json
 ```
 
-6. 响应返回指标 ID 后回读：
+7. 响应返回指标 ID 后回读：
 
 ```bash
 guancli metric get <metric_id> --brief

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

@@ -345,17 +345,18 @@
 
 `guancli metric create` 当前是原子指标专用 endpoint；衍生指标创建使用 `guancli fetch`。
 
-1. 生成 `/tmp/derived_metric.json`。
-2. 本地/人工检查 JSON、基础指标或公式引用指标、时间维度、衍生配置、必填业务属性。
-3. 按 `metric-common-fields.md` 向用户摘要并确认。
-4. 用户确认后，不调用原子指标 `save-precheck`；衍生指标 Web 创建没有 save-precheck。
-5. 提交真实创建：
+1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、基础指标或组合衍生引用指标、衍生配置、时间维度、格式、业务属性和保存方式。
+2. 用户确认计划后，生成 `/tmp/derived_metric.json`。
+3. 本地/人工检查 JSON、基础指标或公式引用指标、时间维度、衍生配置、必填业务属性。
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 用户确认后，不调用原子指标 `save-precheck`；衍生指标 Web 创建没有 save-precheck。
+6. 提交真实创建：
 
 ```bash
 guancli fetch POST /api/metric-platform/metrics/derived-metrics --stdin < /tmp/derived_metric.json
 ```
 
-6. 响应返回指标 ID 后回读确认。
+7. 响应返回指标 ID 后回读确认。
 
 ## 编辑步骤
 

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

@@ -19,6 +19,8 @@
 
 原子指标选择“使用表达式”时，表达式走数据集公式编辑器和后端数据集派生字段校验。后端会把公式当成数据集计算字段检查，并要求最终字段是聚合表达式；没有聚合函数会报“原子指标表达式必须包含聚合函数”。
 
+遇到计算表达式时，先询问用户是否希望创建复合指标。用户确认创建复合指标后，再创建或复用表达式中的基础原子指标，并用 `[metricId]` 生成复合指标公式。用户选择原子表达式或明确要求数据集字段表达式时，才在 `formulaField.fdFormula` 中使用 `[fdId]`。
+
 ### 推荐支持形态
 
 | 形态 | 示例 | 说明 |
@@ -29,14 +31,13 @@
 | 聚合内部加减 | `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([fd_amount]) / COUNT([fd_order_id])` | 只建议一个顶层 `/` |
-| 分子/分母加减后相除 | `(SUM([fd_a]) + SUM([fd_b])) / (SUM([fd_c]) + COUNT([fd_d]))` | 分子、分母内部仅用加减和推荐聚合 |
 | 动态参数 | `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`”。

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

@@ -28,24 +28,79 @@
 
 - “新建一个指标，基于某数据集/某字段”：通常是原子指标。
 - “客单价 = 销售额 / 订单数”：通常是复合指标。
+- “用数据集字段计算一个表达式指标”：先按下方“表达式建模确认”询问用户是否改为复合指标。
 - “给销售额做月环比/最近 7 天/本月累计/华东限定”：通常是衍生指标。
 
+## 表达式建模确认
+
+只要用户要创建的是计算表达式指标，不要直接替用户决定用原子表达式还是复合指标。先向用户确认：
+
+```text
+这个指标需要计算表达式。是否希望我先创建/复用表达式中的基础原子指标，再创建一个复合指标？
+如果选择否，我会按数据集字段表达式创建原子指标。
+```
+
+用户选择“是”时：
+
+1. 拆出表达式中的基础度量。
+2. 先搜索是否已有对应基础原子指标；已有则复用。
+3. 缺失基础指标时，先按 `metric-atomic-mutation.md` 创建基础原子指标。
+4. 再按 `metric-composite-mutation.md` 创建复合指标，公式使用 `[metricId]`，不要使用 `[fdId]`。
+
+用户选择“否”或明确要求数据集字段表达式时，才走原子指标 `formulaField.fdFormula`。
+
 ## 总体流程
 
 1. 使用当前已登录环境，不主动询问 profile；写操作前可执行 `guancli auth status`。
 2. 信息不全时先查 ID，不凭空猜：
    - 指标主题：`guancli metric project [keyword] -f json`
    - 指标目录：`guancli metric tree -f json`
+   - 新建指标主题：`guancli metric project-create <name> --dry-run`，确认后去掉 `--dry-run`
+   - 新建指标目录：`guancli metric 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`
 3. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
-4. 生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
-5. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
-6. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
-7. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
+4. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
+5. 用户确认计划后，生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
+6. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
+7. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
+8. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
 
 不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
 
+## 指标创建计划
+
+创建指标前必须先输出一个计划供用户 review，尤其是一个需求会创建多个基础原子指标和复合指标时。计划确认前不得提交真实创建请求。
+
+计划至少包含：
+
+- 当前环境和目标主题。
+- 目标目录路径和目录 ID。
+- 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
+- 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
+- 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
+- 数据格式、业务负责人、必填业务属性。
+- 将复用的已有指标和将新建的基础指标。
+- 后续会执行的校验：dry-run、save-precheck、validate-update-impact 或本地引用检查。
+
+计划示例：
+
+```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/必要校验，再提交创建。
+```
+
 ## 校验入口速查
 
 | 操作 | 校验规则 |