@guandata/guanmetric 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.3 - 2026-07-23
+
+- 完善已有指标资源的原地编辑指引，避免更新时误建新资源并影响既有引用。
+- 优化多资源读取效率，Agent 批量准备和校验指标配置时等待更少。
+
+## @guandata/guanmetric 0.1.2 - 2026-07-20
+
+- 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
+- 随包提供完整的指标管理说明和参考资料。
+
 ## @guandata/guanmetric 0.1.1 - 2026-07-10
 
 - 增强指标 Excel 标准化能力，支持按原子、复合和多类衍生指标拆分标准模板。

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,16 @@ guanmetric public-dim create --file public_dim.json --dry-run
 
 ## 版本更新
 
+### @guandata/guanmetric 0.1.3
+
+- 完善已有指标资源的原地编辑指引，避免更新时误建新资源并影响既有引用。
+- 优化多资源读取效率，Agent 批量准备和校验指标配置时等待更少。
+
+### @guandata/guanmetric 0.1.2
+
+- 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
+- 随包提供完整的指标管理说明和参考资料。
+
 ### @guandata/guanmetric 0.1.1
 
 - 增强指标 Excel 标准化能力，支持按原子、复合和多类衍生指标拆分标准模板。

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.1",
+  "version": "0.1.3",
   "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,6 +21,10 @@ guanmetric public-dim create --file public_dim.json --dry-run
 guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file composite_metric.json
 ```
 
+## 编辑红线：编辑 ≠ 删除重建
+
+用户要求**编辑/重命名/修改**已有指标时，必须用 `guanmetric edit <metric_id>` 原地更新（默认按线上详情合并 patch，改名用 `--set name=新名`）；公共维度用 `public-dim edit`。**严禁**用"delete 后重新 create 一个同名指标"来模拟编辑或改名：指标 ID 被复合指标、衍生指标、指标卡片和指标树引用，删除重建会让这些引用全部断链，指标上的权限和历史配置也会丢失且无法恢复。`delete` 只用于用户明确要求删除该指标本身。指标主题/目录目前只支持创建，不支持改名或删除；用户要求时直接说明 CLI 暂不支持，不要新建一个新主题/目录来替代。无论通过哪个命令或接口，都不得把"编辑"拆成"删除 + 重建"的组合来绕过这条红线。只有用户明确指示"先新建替代、再删除旧的"时才允许该流程，且执行前必须列出会断链和丢失的内容并获得确认。
+
 批量创建指标时，必须先生成固定结构的标准 Excel 返回给用户确认；确认前不生成最终 payload，不提交真实创建。
 
 如果用户提供的是客户原始 Excel/CSV，而不是已经接近标准模板的文件，agent 必须先自行读取并理解表格语义，产出一个语义映射中间表（建议命名为 `*.ai_mapped.xlsx`），再执行 `guanmetric template normalize` 生成最终标准模板。不要直接把客户原始 Excel 丢给 CLI 后交付结果；CLI 不负责穷举客户列名或业务表述。CLI 继续负责固定模板结构、必填项标记、业务属性配置读取、自动填充说明、行状态、问题说明、高亮样式、列宽自适应、基础校验和 report 输出。