@guandata/guancli 1.0.35 → 1.0.37

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guancli 1.0.37 - 2026-07-01
+
+- 新增 Personal Access Token 登录方式，支持在自动化、CI 或无浏览器环境中使用 PAT 完成认证。
+- `auth` 相关命令增强 PAT profile 的状态展示和修改保护，避免把 PAT 配置误当普通登录配置处理。
+- API 调用会根据当前认证上下文选择合适的身份信息，提升 PAT 场景下调用 ChatBI、指标和资源接口的稳定性。
+
+## @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/LICENSE

@@ -0,0 +1,133 @@
+Guandata Developer Tools Free Evaluation License
+
+Copyright (c) Hangzhou Guandata Co., Ltd.
+
+This software and its related source code, documentation, examples, packages,
+configuration files, command-line tools, MCP servers, SDKs, plugins, and tool
+integrations are proprietary software of Hangzhou Guandata Co., Ltd. or its
+licensors.
+
+This license applies to Guandata developer tools, including but not limited to
+Guandata CLI, Guandata MCP Server, related npm packages, source code,
+documentation, examples, configuration files, and tool integrations.
+
+1. Free Personal Evaluation Use
+
+Hangzhou Guandata Co., Ltd. grants you a limited, non-exclusive,
+non-transferable, revocable license to use this software free of charge solely
+for personal learning, local testing, technical evaluation, and non-production
+experiments.
+
+This free license does not permit enterprise, commercial, production, internal
+business, team, organizational, hosted, customer-facing, or revenue-generating
+use.
+
+2. Enterprise and Commercial Use
+
+Any use by or for a company, organization, institution, government entity, team,
+client, or other non-individual entity requires a separate commercial license
+from Hangzhou Guandata Co., Ltd.
+
+Enterprise or commercial use includes, but is not limited to:
+
+- use in production, staging, shared, or hosted environments;
+- use for internal business operations or automated business workflows;
+- use by employees, contractors, consultants, service providers, or
+  representatives on behalf of an organization;
+- integration into commercial products, services, platforms, workflows, AI
+  agents, MCP clients, or customer deliverables;
+- connection to, access to, processing of, exposure of, or operation on
+  enterprise data, business systems, customer data, or production data;
+- redistribution, hosting, resale, sublicensing, or provision of this software
+  as part of a paid or unpaid service.
+
+To obtain an enterprise or commercial license, please contact Hangzhou Guandata
+Co., Ltd. through its official sales, support, or business channels.
+
+3. MCP Server and Agent Integration
+
+For Guandata MCP Server or any MCP-compatible tool integration, the free license
+is limited to local personal testing, learning, and non-production evaluation.
+
+The free license does not permit use of the MCP Server in enterprise agent
+platforms, production AI applications, shared team environments,
+customer-facing systems, hosted services, automated business workflows, or
+integrations that access, process, expose, or operate on enterprise data.
+
+Any organizational, commercial, hosted, production, or data-connected use of the
+MCP Server requires a separate commercial license from Hangzhou Guandata Co., Ltd.
+
+4. Restrictions
+
+Unless expressly permitted by this license, reasonably necessary to install and
+use the software as allowed by this license, or expressly permitted by a
+separate written agreement with Hangzhou Guandata Co., Ltd., you may not:
+
+- copy, distribute, sublicense, sell, lease, host, or provide this software to
+  third parties;
+- modify, adapt, translate, create derivative works of, or otherwise alter this
+  software;
+- reverse engineer, decompile, disassemble, or attempt to derive the source
+  code, structure, sequence, organization, or underlying ideas of this software,
+  except to the extent such restriction is prohibited by applicable law;
+- remove or alter copyright, trademark, license, or proprietary notices;
+- use Guandata names, logos, trademarks, product names, or brand assets without
+  permission;
+- use this software in violation of applicable laws, regulations, or third-party
+  rights;
+- circumvent license, access control, usage limitation, telemetry, audit, or
+  security mechanisms, if any.
+
+5. Ownership
+
+Hangzhou Guandata Co., Ltd. and its licensors retain all rights, title, and
+interest in and to this software. No rights are granted except as expressly
+stated in this license.
+
+6. Third-Party Components
+
+Third-party open source components, if any, are licensed under their respective
+licenses. This license applies only to software owned by Hangzhou Guandata Co., Ltd.
+and does not modify any third-party license terms.
+
+7. No Warranty
+
+This software is provided "as is" and "as available", without warranties of any
+kind, whether express, implied, statutory, or otherwise, including but not
+limited to warranties of merchantability, fitness for a particular purpose,
+accuracy, availability, security, and non-infringement.
+
+8. Limitation of Liability
+
+To the maximum extent permitted by applicable law, Hangzhou Guandata Co., Ltd.
+shall not be liable for any indirect, incidental, special, consequential,
+exemplary, or punitive damages, or for any loss of profits, revenue, data,
+goodwill, business opportunity, or business interruption arising from or related
+to this software, even if Hangzhou Guandata Co., Ltd. has been advised of the
+possibility of such damages.
+
+9. Termination
+
+Your rights under this license terminate automatically if you violate any term of
+this license. Upon termination, you must stop using the software and delete all
+copies in your possession or control.
+
+10. Governing Law and Dispute Resolution
+
+This license shall be governed by the laws of the People's Republic of China,
+without regard to its conflict of laws principles.
+
+Any dispute arising from or related to this license or the software shall be
+submitted to the competent court with jurisdiction in Hangzhou, Zhejiang
+Province, China, unless otherwise required by applicable law.
+
+11. Contact
+
+For enterprise licensing, commercial authorization, partnership, procurement, or
+other questions, please contact Hangzhou Guandata Co., Ltd. through its official
+website or official business channels.
+
+12. Language
+
+If this license is provided in multiple languages, the English version controls
+unless Hangzhou Guandata Co., Ltd. expressly states otherwise in writing.

package/LICENSE.zh-CN

@@ -0,0 +1,82 @@
+观远开发者工具免费评估许可协议
+
+版权所有 (c) 杭州观远数据有限公司。
+
+本软件及其相关源代码、文档、示例、软件包、配置文件、命令行工具、MCP Server、SDK、插件和工具集成，属于杭州观远数据有限公司或其授权方的专有软件。
+
+本协议适用于观远开发者工具，包括但不限于观远 CLI、观远 MCP Server、相关 npm 包、源代码、文档、示例、配置文件和工具集成。
+
+1. 免费个人评估使用
+
+杭州观远数据有限公司授予你一项有限的、非独占的、不可转让的、可撤销的许可，允许你免费使用本软件，但仅限于个人学习、本地测试、技术评估和非生产环境实验。
+
+本免费许可不允许企业使用、商业使用、生产环境使用、内部业务使用、团队使用、组织使用、托管使用、面向客户的使用，或任何直接或间接产生商业收益的使用。
+
+2. 企业及商业使用
+
+任何由公司、组织、机构、政府单位、团队、客户或其他非个人主体进行的使用，或代表上述主体进行的使用，均需事先取得杭州观远数据有限公司的单独商业授权。
+
+企业或商业使用包括但不限于：
+
+- 在生产环境、预发布环境、共享环境或托管环境中使用；
+- 用于内部业务运营或自动化业务流程；
+- 由员工、承包商、顾问、服务商或代理人代表组织使用；
+- 集成到商业产品、服务、平台、工作流、AI 智能体、MCP 客户端或客户交付物中；
+- 连接、访问、处理、暴露或操作企业数据、业务系统、客户数据或生产数据；
+- 对本软件进行分发、托管、转售、再许可，或作为任何付费或免费的服务的一部分提供。
+
+如需企业或商业授权，请通过观远官方销售、支持或商务渠道联系杭州观远数据有限公司。
+
+3. MCP Server 与智能体集成
+
+对于观远 MCP Server 或任何兼容 MCP 的工具集成，免费许可仅限于个人本地测试、学习和非生产环境评估。
+
+免费许可不允许将 MCP Server 用于企业级智能体平台、生产环境 AI 应用、团队共享环境、面向客户的系统、托管服务、自动化业务流程，或任何访问、处理、暴露、操作企业数据的集成场景。
+
+任何组织用途、商业用途、托管用途、生产用途，或涉及企业数据连接的 MCP Server 使用，均需取得杭州观远数据有限公司的单独商业授权。
+
+4. 限制
+
+除非本协议明确允许、为按照本协议安装和使用本软件所合理必需，或杭州观远数据有限公司通过单独书面协议明确允许，你不得：
+
+- 复制、分发、再许可、销售、出租、托管本软件，或向第三方提供本软件；
+- 修改、改编、翻译本软件，创作本软件的衍生作品，或以其他方式变更本软件；
+- 对本软件进行反向工程、反编译、反汇编，或试图获取本软件的源代码、结构、顺序、组织方式或底层思想，但适用法律禁止限制的情形除外；
+- 删除或修改版权、商标、许可或专有权利声明；
+- 未经许可使用杭州观远数据有限公司或观远品牌的名称、标识、商标、产品名称或品牌资产；
+- 以违反适用法律法规或第三方权利的方式使用本软件；
+- 绕过任何许可、访问控制、使用限制、遥测、审计或安全机制。
+
+5. 权利归属
+
+本软件的所有权利、所有权和利益均归杭州观远数据有限公司及其授权方所有。除本协议明确授予的权利外，不授予任何其他权利。
+
+6. 第三方组件
+
+本软件中如包含第三方开源组件，该等组件适用其各自的许可协议。本协议仅适用于杭州观远数据有限公司拥有权利的软件部分，并不修改任何第三方许可条款。
+
+7. 无担保
+
+本软件按“现状”和“现有”基础提供，不作任何明示、默示、法定或其他形式的担保，包括但不限于适销性、特定用途适用性、准确性、可用性、安全性和不侵权担保。
+
+8. 责任限制
+
+在适用法律允许的最大范围内，杭州观远数据有限公司不对因本软件引起或与本软件相关的任何间接、附带、特殊、后果性、惩罚性或惩戒性损害承担责任，也不对利润、收入、数据、商誉、商业机会损失或业务中断承担责任，即使杭州观远数据有限公司已被告知可能发生该等损害。
+
+9. 终止
+
+如果你违反本协议的任何条款，你在本协议项下的权利将自动终止。终止后，你必须停止使用本软件，并删除你持有或控制的所有副本。
+
+10. 适用法律与争议解决
+
+本协议适用中华人民共和国法律，但不包括其冲突法规则。
+
+因本协议或本软件引起或与之相关的任何争议，应提交中国浙江省杭州市有管辖权的人民法院解决，除非适用法律另有强制性规定。
+
+11. 联系方式
+
+如需企业授权、商业许可、合作、采购或有其他问题，请通过观远官方网站或官方商务渠道联系杭州观远数据有限公司。
+
+12. 语言
+
+如本协议提供多个语言版本，除非杭州观远数据有限公司另有明确书面说明，以英文版本为准。

package/README.md

@@ -39,6 +39,19 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
 
 ## 版本更新
 
+### @guandata/guancli 1.0.37
+
+- 新增 Personal Access Token 登录方式，支持在自动化、CI 或无浏览器环境中使用 PAT 完成认证。
+- `auth` 相关命令增强 PAT profile 的状态展示和修改保护，避免把 PAT 配置误当普通登录配置处理。
+- API 调用会根据当前认证上下文选择合适的身份信息，提升 PAT 场景下调用 ChatBI、指标和资源接口的稳定性。
+
+### @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.37",
   "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
   "bin": {
     "guancli": "bin/run.js"
@@ -16,6 +16,8 @@
     "binaries/",
     "skills/",
     "CHANGELOG.md",
+    "LICENSE",
+    "LICENSE.zh-CN",
     "README.md"
   ],
   "keywords": [
@@ -25,7 +27,7 @@
     "etl",
     "agent-skill"
   ],
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "os": [
     "darwin",
     "linux",

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`。
 
 ## 数据获取方式
 
@@ -45,13 +47,23 @@ guancli auth login
 
 登录成功后 Token 自动保存在系统标准配置目录下的 `guancli/config.json`。密码方式支持 Token 过期后自动刷新。
 
-### 方式二：直接输入 Token
+### 方式二：直接输入 uIdToken
 
 ```bash
 guancli auth login
 ```
 
-选择登录方式 `2`，直接粘贴已有的 Auth Token。适用于已从 Web 界面或其他途径获取 Token 的场景。
+选择登录方式 `2`，直接粘贴已有的 uIdToken。适用于已从 Web 界面或其他途径获取 uIdToken 的场景。
+
+### 方式三：Personal Access Token
+
+```bash
+guancli auth login --url https://bi.example.com --pat <pat>
+```
+
+交互式登录时选择登录方式 `3`，直接粘贴 Personal Access Token。`--personal-token` 仍可作为长参数使用。PAT 请求会自动携带 `X-Personal-Token` 和 `X-Guandata-Client: cli`，`auth status` 会通过 `/pat/introspect` 做自检。
+
+`chatbi` 子命令仍要求 uIdToken 登录；管理员动态码、管理员登录、SVC 查询等管理员能力由 `guanadmin` 提供，不使用 PAT。
 
 ### 多环境管理
 
@@ -81,7 +93,7 @@ ChatBI 统一复用当前 profile 的 `base_url` 和 `uIdToken`。
 
 ## 能力边界
 
-guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的写操作（Form 表单填报 CRUD、指标写操作引导）。其他写入类任务由专用 skill 负责：
+guancli 是 BI 资源的**查询分析入口**，并支持少量明确边界的写操作（Form 表单填报 CRUD、指标写操作引导）和 SuperApp 模板项目创建。其他写入类任务由专用 skill 负责：
 
 | 任务 | 应使用的工具 |
 |------|-------------|
@@ -91,6 +103,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 +143,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`。