@guandata/guancli 1.0.35 → 1.0.36

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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` 增强数据集下游指标查询，并补充指标创建/编辑参考说明。

package/README.md

@@ -39,6 +39,13 @@ 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` 增强数据集下游指标查询，并补充指标创建/编辑参考说明。

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.35",
+  "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,6 +133,8 @@ guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的
 关键规则：
 
 - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
+- 创建指标主题用 `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>`。

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-mutation.md

@@ -55,6 +55,8 @@
 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`。