@xiaozhi-client/version 1.9.7-beta.21

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shenjingnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 版本号常量（构建时注入）
+ *
+ * 如果构建时能读取到 package.json，则为真实版本号
+ * 否则为占位符，运行时从 package.json 读取
+ */
+declare const VERSION: string;
+declare const APP_NAME: string;
+
+/**
+ * 版本管理工具
+ *
+ * 提供版本号获取、比较、验证等功能
+ */
+/**
+ * 版本信息接口
+ */
+interface VersionInfo {
+    version: string;
+    name?: string;
+    description?: string;
+    author?: string;
+}
+/**
+ * 版本工具类
+ */
+declare class VersionUtils {
+    private static cachedVersion;
+    private static cachedVersionInfo;
+    /**
+     * 获取版本号
+     *
+     * 优先使用构建时注入的版本号常量
+     * 如果是占位符，则运行时从 package.json 读取
+     */
+    static getVersion(): string;
+    /**
+     * 获取完整版本信息
+     */
+    static getVersionInfo(): VersionInfo;
+    /**
+     * 比较版本号
+     *
+     * @param version1 第一个版本号
+     * @param version2 第二个版本号
+     * @returns 返回值：1 表示 version1 > version2，-1 表示 version1 < version2，0 表示相等
+     */
+    static compareVersions(version1: string, version2: string): number;
+    /**
+     * 检查版本是否有效
+     *
+     * @param version 版本号字符串
+     * @returns 是否为有效的语义化版本号
+     */
+    static isValidVersion(version: string): boolean;
+    /**
+     * 运行时从 package.json 读取版本号
+     */
+    private static getRuntimeVersion;
+    /**
+     * 运行时从 package.json 读取完整版本信息
+     */
+    private static getRuntimeVersionInfo;
+    /**
+     * 清除版本缓存
+     *
+     * 主要用于测试场景
+     */
+    static clearCache(): void;
+}
+
+export { APP_NAME, VERSION, type VersionInfo, VersionUtils };

package/dist/index.js

@@ -0,0 +1,158 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/version-constants.ts
+var VERSION = "1.9.7-beta.21";
+var APP_NAME = "xiaozhi-client";
+
+// src/VersionUtils.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var VersionUtils = class _VersionUtils {
+  static {
+    __name(this, "VersionUtils");
+  }
+  static cachedVersion = null;
+  static cachedVersionInfo = null;
+  /**
+   * 获取版本号
+   *
+   * 优先使用构建时注入的版本号常量
+   * 如果是占位符，则运行时从 package.json 读取
+   */
+  static getVersion() {
+    if (VERSION === "__VERSION__") {
+      return _VersionUtils.getRuntimeVersion();
+    }
+    return VERSION;
+  }
+  /**
+   * 获取完整版本信息
+   */
+  static getVersionInfo() {
+    if (_VersionUtils.cachedVersionInfo) {
+      return _VersionUtils.cachedVersionInfo;
+    }
+    if (VERSION === "__VERSION__") {
+      _VersionUtils.cachedVersionInfo = _VersionUtils.getRuntimeVersionInfo();
+      return _VersionUtils.cachedVersionInfo;
+    }
+    _VersionUtils.cachedVersionInfo = {
+      version: VERSION,
+      name: APP_NAME === "__APP_NAME__" ? void 0 : APP_NAME
+    };
+    return _VersionUtils.cachedVersionInfo;
+  }
+  /**
+   * 比较版本号
+   *
+   * @param version1 第一个版本号
+   * @param version2 第二个版本号
+   * @returns 返回值：1 表示 version1 > version2，-1 表示 version1 < version2，0 表示相等
+   */
+  static compareVersions(version1, version2) {
+    const v1Parts = version1.split(".").map(Number);
+    const v2Parts = version2.split(".").map(Number);
+    const maxLength = Math.max(v1Parts.length, v2Parts.length);
+    for (let i = 0; i < maxLength; i++) {
+      const v1Part = v1Parts[i] || 0;
+      const v2Part = v2Parts[i] || 0;
+      if (v1Part > v2Part) return 1;
+      if (v1Part < v2Part) return -1;
+    }
+    return 0;
+  }
+  /**
+   * 检查版本是否有效
+   *
+   * @param version 版本号字符串
+   * @returns 是否为有效的语义化版本号
+   */
+  static isValidVersion(version) {
+    const versionRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/;
+    return versionRegex.test(version);
+  }
+  /**
+   * 运行时从 package.json 读取版本号
+   */
+  static getRuntimeVersion() {
+    if (_VersionUtils.cachedVersion) {
+      return _VersionUtils.cachedVersion;
+    }
+    try {
+      const __filename = fileURLToPath(import.meta.url);
+      const currentDir = path.dirname(__filename);
+      const possiblePaths = [
+        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "..", "package.json"),
+        // 从 dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "package.json"),
+        // 全局安装环境
+        path.join(currentDir, "..", "..", "..", "..", "package.json")
+      ];
+      for (const packagePath of possiblePaths) {
+        if (fs.existsSync(packagePath)) {
+          const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+          if (packageJson.version) {
+            _VersionUtils.cachedVersion = packageJson.version;
+            return packageJson.version;
+          }
+        }
+      }
+      _VersionUtils.cachedVersion = "unknown";
+      return "unknown";
+    } catch (error) {
+      console.warn("\u65E0\u6CD5\u4ECE package.json \u8BFB\u53D6\u7248\u672C\u4FE1\u606F:", error);
+      _VersionUtils.cachedVersion = "unknown";
+      return "unknown";
+    }
+  }
+  /**
+   * 运行时从 package.json 读取完整版本信息
+   */
+  static getRuntimeVersionInfo() {
+    try {
+      const __filename = fileURLToPath(import.meta.url);
+      const currentDir = path.dirname(__filename);
+      const possiblePaths = [
+        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "..", "package.json"),
+        // 从 dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "package.json"),
+        // 全局安装环境
+        path.join(currentDir, "..", "..", "..", "..", "package.json")
+      ];
+      for (const packagePath of possiblePaths) {
+        if (fs.existsSync(packagePath)) {
+          const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+          return {
+            version: packageJson.version || "unknown",
+            name: packageJson.name,
+            description: packageJson.description,
+            author: packageJson.author
+          };
+        }
+      }
+      return { version: "unknown" };
+    } catch (error) {
+      console.warn("\u65E0\u6CD5\u8BFB\u53D6\u7248\u672C\u4FE1\u606F:", error);
+      return { version: "unknown" };
+    }
+  }
+  /**
+   * 清除版本缓存
+   *
+   * 主要用于测试场景
+   */
+  static clearCache() {
+    _VersionUtils.cachedVersion = null;
+    _VersionUtils.cachedVersionInfo = null;
+  }
+};
+export {
+  APP_NAME,
+  VERSION,
+  VersionUtils
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version-constants.ts","../src/VersionUtils.ts"],"sourcesContent":["/**\n * 版本号常量（构建时注入）\n *\n * 如果构建时能读取到 package.json，则为真实版本号\n * 否则为占位符，运行时从 package.json 读取\n */\nexport const VERSION = __VERSION__;\nexport const APP_NAME = __APP_NAME__;\n","/**\n * 版本管理工具\n *\n * 提供版本号获取、比较、验证等功能\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { VERSION, APP_NAME } from \"./version-constants.js\";\n\n/**\n * 版本信息接口\n */\nexport interface VersionInfo {\n  version: string;\n  name?: string;\n  description?: string;\n  author?: string;\n}\n\n/**\n * 版本工具类\n */\nexport class VersionUtils {\n  private static cachedVersion: string | null = null;\n  private static cachedVersionInfo: VersionInfo | null = null;\n\n  /**\n   * 获取版本号\n   *\n   * 优先使用构建时注入的版本号常量\n   * 如果是占位符，则运行时从 package.json 读取\n   */\n  static getVersion(): string {\n    // 如果版本号是占位符，则运行时读取\n    if (VERSION === \"__VERSION__\") {\n      return VersionUtils.getRuntimeVersion();\n    }\n\n    // 使用构建时注入的版本号\n    return VERSION;\n  }\n\n  /**\n   * 获取完整版本信息\n   */\n  static getVersionInfo(): VersionInfo {\n    // 如果有缓存，直接返回\n    if (VersionUtils.cachedVersionInfo) {\n      return VersionUtils.cachedVersionInfo;\n    }\n\n    // 如果版本号是占位符，则运行时读取\n    if (VERSION === \"__VERSION__\") {\n      VersionUtils.cachedVersionInfo = VersionUtils.getRuntimeVersionInfo();\n      return VersionUtils.cachedVersionInfo;\n    }\n\n    // 使用构建时注入的版本号\n    VersionUtils.cachedVersionInfo = {\n      version: VERSION,\n      name: APP_NAME === \"__APP_NAME__\" ? undefined : APP_NAME,\n    };\n\n    return VersionUtils.cachedVersionInfo;\n  }\n\n  /**\n   * 比较版本号\n   *\n   * @param version1 第一个版本号\n   * @param version2 第二个版本号\n   * @returns 返回值：1 表示 version1 > version2，-1 表示 version1 < version2，0 表示相等\n   */\n  static compareVersions(version1: string, version2: string): number {\n    const v1Parts = version1.split(\".\").map(Number);\n    const v2Parts = version2.split(\".\").map(Number);\n    const maxLength = Math.max(v1Parts.length, v2Parts.length);\n\n    for (let i = 0; i < maxLength; i++) {\n      const v1Part = v1Parts[i] || 0;\n      const v2Part = v2Parts[i] || 0;\n\n      if (v1Part > v2Part) return 1;\n      if (v1Part < v2Part) return -1;\n    }\n\n    return 0;\n  }\n\n  /**\n   * 检查版本是否有效\n   *\n   * @param version 版本号字符串\n   * @returns 是否为有效的语义化版本号\n   */\n  static isValidVersion(version: string): boolean {\n    // 支持语义化版本号：1.2.3 或 1.2.3-alpha.1 或 1.2.3-beta.1+build.123\n    const versionRegex = /^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$/;\n    return versionRegex.test(version);\n  }\n\n  /**\n   * 运行时从 package.json 读取版本号\n   */\n  private static getRuntimeVersion(): string {\n    // 如果有缓存，直接返回\n    if (VersionUtils.cachedVersion) {\n      return VersionUtils.cachedVersion;\n    }\n\n    try {\n      // 在 ES 模块环境中获取当前目录\n      const __filename = fileURLToPath(import.meta.url);\n      const currentDir = path.dirname(__filename);\n\n      // 尝试多个可能的 package.json 路径\n      const possiblePaths = [\n        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json\n        path.join(currentDir, \"..\", \"..\", \"..\", \"package.json\"),\n        // 从 dist/version/index.js 到项目根目录的 package.json\n        path.join(currentDir, \"..\", \"..\", \"package.json\"),\n        // 全局安装环境\n        path.join(currentDir, \"..\", \"..\", \"..\", \"..\", \"package.json\"),\n      ];\n\n      for (const packagePath of possiblePaths) {\n        if (fs.existsSync(packagePath)) {\n          const packageJson = JSON.parse(fs.readFileSync(packagePath, \"utf8\"));\n          if (packageJson.version) {\n            VersionUtils.cachedVersion = packageJson.version;\n            return packageJson.version;\n          }\n        }\n      }\n\n      // 如果都找不到，返回默认版本\n      VersionUtils.cachedVersion = \"unknown\";\n      return \"unknown\";\n    } catch (error) {\n      console.warn(\"无法从 package.json 读取版本信息:\", error);\n      VersionUtils.cachedVersion = \"unknown\";\n      return \"unknown\";\n    }\n  }\n\n  /**\n   * 运行时从 package.json 读取完整版本信息\n   */\n  private static getRuntimeVersionInfo(): VersionInfo {\n    try {\n      const __filename = fileURLToPath(import.meta.url);\n      const currentDir = path.dirname(__filename);\n\n      const possiblePaths = [\n        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json\n        path.join(currentDir, \"..\", \"..\", \"..\", \"package.json\"),\n        // 从 dist/version/index.js 到项目根目录的 package.json\n        path.join(currentDir, \"..\", \"..\", \"package.json\"),\n        // 全局安装环境\n        path.join(currentDir, \"..\", \"..\", \"..\", \"..\", \"package.json\"),\n      ];\n\n      for (const packagePath of possiblePaths) {\n        if (fs.existsSync(packagePath)) {\n          const packageJson = JSON.parse(fs.readFileSync(packagePath, \"utf8\"));\n          return {\n            version: packageJson.version || \"unknown\",\n            name: packageJson.name,\n            description: packageJson.description,\n            author: packageJson.author,\n          };\n        }\n      }\n\n      return { version: \"unknown\" };\n    } catch (error) {\n      console.warn(\"无法读取版本信息:\", error);\n      return { version: \"unknown\" };\n    }\n  }\n\n  /**\n   * 清除版本缓存\n   *\n   * 主要用于测试场景\n   */\n  static clearCache(): void {\n    VersionUtils.cachedVersion = null;\n    VersionUtils.cachedVersionInfo = null;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@xiaozhi-client/version",
+  "version": "1.9.7-beta.21",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shenjingnan/xiaozhi-client.git",
+    "directory": "packages/version"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.0.5"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          "^build"
+        ],
+        "outputs": [
+          "{projectRoot}/dist"
+        ]
+      },
+      "test": {
+        "outputs": [
+          "{workspaceRoot}/coverage/version"
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/VersionUtils.ts

@@ -0,0 +1,193 @@
+/**
+ * 版本管理工具
+ *
+ * 提供版本号获取、比较、验证等功能
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION, APP_NAME } from "./version-constants.js";
+
+/**
+ * 版本信息接口
+ */
+export interface VersionInfo {
+  version: string;
+  name?: string;
+  description?: string;
+  author?: string;
+}
+
+/**
+ * 版本工具类
+ */
+export class VersionUtils {
+  private static cachedVersion: string | null = null;
+  private static cachedVersionInfo: VersionInfo | null = null;
+
+  /**
+   * 获取版本号
+   *
+   * 优先使用构建时注入的版本号常量
+   * 如果是占位符，则运行时从 package.json 读取
+   */
+  static getVersion(): string {
+    // 如果版本号是占位符，则运行时读取
+    if (VERSION === "__VERSION__") {
+      return VersionUtils.getRuntimeVersion();
+    }
+
+    // 使用构建时注入的版本号
+    return VERSION;
+  }
+
+  /**
+   * 获取完整版本信息
+   */
+  static getVersionInfo(): VersionInfo {
+    // 如果有缓存，直接返回
+    if (VersionUtils.cachedVersionInfo) {
+      return VersionUtils.cachedVersionInfo;
+    }
+
+    // 如果版本号是占位符，则运行时读取
+    if (VERSION === "__VERSION__") {
+      VersionUtils.cachedVersionInfo = VersionUtils.getRuntimeVersionInfo();
+      return VersionUtils.cachedVersionInfo;
+    }
+
+    // 使用构建时注入的版本号
+    VersionUtils.cachedVersionInfo = {
+      version: VERSION,
+      name: APP_NAME === "__APP_NAME__" ? undefined : APP_NAME,
+    };
+
+    return VersionUtils.cachedVersionInfo;
+  }
+
+  /**
+   * 比较版本号
+   *
+   * @param version1 第一个版本号
+   * @param version2 第二个版本号
+   * @returns 返回值：1 表示 version1 > version2，-1 表示 version1 < version2，0 表示相等
+   */
+  static compareVersions(version1: string, version2: string): number {
+    const v1Parts = version1.split(".").map(Number);
+    const v2Parts = version2.split(".").map(Number);
+    const maxLength = Math.max(v1Parts.length, v2Parts.length);
+
+    for (let i = 0; i < maxLength; i++) {
+      const v1Part = v1Parts[i] || 0;
+      const v2Part = v2Parts[i] || 0;
+
+      if (v1Part > v2Part) return 1;
+      if (v1Part < v2Part) return -1;
+    }
+
+    return 0;
+  }
+
+  /**
+   * 检查版本是否有效
+   *
+   * @param version 版本号字符串
+   * @returns 是否为有效的语义化版本号
+   */
+  static isValidVersion(version: string): boolean {
+    // 支持语义化版本号：1.2.3 或 1.2.3-alpha.1 或 1.2.3-beta.1+build.123
+    const versionRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/;
+    return versionRegex.test(version);
+  }
+
+  /**
+   * 运行时从 package.json 读取版本号
+   */
+  private static getRuntimeVersion(): string {
+    // 如果有缓存，直接返回
+    if (VersionUtils.cachedVersion) {
+      return VersionUtils.cachedVersion;
+    }
+
+    try {
+      // 在 ES 模块环境中获取当前目录
+      const __filename = fileURLToPath(import.meta.url);
+      const currentDir = path.dirname(__filename);
+
+      // 尝试多个可能的 package.json 路径
+      const possiblePaths = [
+        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "..", "package.json"),
+        // 从 dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "package.json"),
+        // 全局安装环境
+        path.join(currentDir, "..", "..", "..", "..", "package.json"),
+      ];
+
+      for (const packagePath of possiblePaths) {
+        if (fs.existsSync(packagePath)) {
+          const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+          if (packageJson.version) {
+            VersionUtils.cachedVersion = packageJson.version;
+            return packageJson.version;
+          }
+        }
+      }
+
+      // 如果都找不到，返回默认版本
+      VersionUtils.cachedVersion = "unknown";
+      return "unknown";
+    } catch (error) {
+      console.warn("无法从 package.json 读取版本信息:", error);
+      VersionUtils.cachedVersion = "unknown";
+      return "unknown";
+    }
+  }
+
+  /**
+   * 运行时从 package.json 读取完整版本信息
+   */
+  private static getRuntimeVersionInfo(): VersionInfo {
+    try {
+      const __filename = fileURLToPath(import.meta.url);
+      const currentDir = path.dirname(__filename);
+
+      const possiblePaths = [
+        // 从 packages/version/dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "..", "package.json"),
+        // 从 dist/version/index.js 到项目根目录的 package.json
+        path.join(currentDir, "..", "..", "package.json"),
+        // 全局安装环境
+        path.join(currentDir, "..", "..", "..", "..", "package.json"),
+      ];
+
+      for (const packagePath of possiblePaths) {
+        if (fs.existsSync(packagePath)) {
+          const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+          return {
+            version: packageJson.version || "unknown",
+            name: packageJson.name,
+            description: packageJson.description,
+            author: packageJson.author,
+          };
+        }
+      }
+
+      return { version: "unknown" };
+    } catch (error) {
+      console.warn("无法读取版本信息:", error);
+      return { version: "unknown" };
+    }
+  }
+
+  /**
+   * 清除版本缓存
+   *
+   * 主要用于测试场景
+   */
+  static clearCache(): void {
+    VersionUtils.cachedVersion = null;
+    VersionUtils.cachedVersionInfo = null;
+  }
+}

package/src/__tests__/VersionUtils.test.ts

@@ -0,0 +1,225 @@
+/**
+ * VersionUtils 单元测试
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { VersionUtils } from "../VersionUtils.js";
+
+describe("VersionUtils", () => {
+  beforeEach(() => {
+    // 清除缓存以确保每个测试独立运行
+    VersionUtils.clearCache();
+  });
+
+  describe("getVersion", () => {
+    it("应该返回版本号字符串", () => {
+      const version = VersionUtils.getVersion();
+      expect(typeof version).toBe("string");
+      expect(version.length).toBeGreaterThan(0);
+    });
+
+    it("应该返回有效的版本号格式", () => {
+      const version = VersionUtils.getVersion();
+      // 版本号应该是数字点分隔格式，或者 "unknown"
+      const isValid =
+        version === "unknown" || /^\d+\.\d+\.\d+/.test(version);
+      expect(isValid).toBe(true);
+    });
+
+    it("多次调用应该返回相同结果（缓存生效）", () => {
+      const version1 = VersionUtils.getVersion();
+      const version2 = VersionUtils.getVersion();
+      expect(version1).toBe(version2);
+    });
+
+    it("清除缓存后应该重新读取版本号", () => {
+      const version1 = VersionUtils.getVersion();
+      VersionUtils.clearCache();
+      const version2 = VersionUtils.getVersion();
+      expect(version1).toBe(version2);
+    });
+  });
+
+  describe("getVersionInfo", () => {
+    it("应该返回包含版本号的对象", () => {
+      const info = VersionUtils.getVersionInfo();
+      expect(info).toHaveProperty("version");
+      expect(typeof info.version).toBe("string");
+    });
+
+    it("应该可能包含应用名称", () => {
+      const info = VersionUtils.getVersionInfo();
+      // name 可能存在也可能不存在，取决于构建配置
+      if (info.name) {
+        expect(typeof info.name).toBe("string");
+      }
+    });
+
+    it("应该可能包含描述信息", () => {
+      const info = VersionUtils.getVersionInfo();
+      // description 可能存在也可能不存在
+      if (info.description) {
+        expect(typeof info.description).toBe("string");
+      }
+    });
+
+    it("应该可能包含作者信息", () => {
+      const info = VersionUtils.getVersionInfo();
+      // author 可能存在也可能不存在
+      if (info.author) {
+        expect(typeof info.author).toBe("string" || typeof info.author === "object");
+      }
+    });
+
+    it("多次调用应该返回相同结果（缓存生效）", () => {
+      const info1 = VersionUtils.getVersionInfo();
+      const info2 = VersionUtils.getVersionInfo();
+      expect(info1).toEqual(info2);
+    });
+  });
+
+  describe("compareVersions", () => {
+    it("应该正确比较相等的版本号", () => {
+      const result = VersionUtils.compareVersions("1.0.0", "1.0.0");
+      expect(result).toBe(0);
+    });
+
+    it("应该正确比较主版本号差异", () => {
+      const result = VersionUtils.compareVersions("2.0.0", "1.0.0");
+      expect(result).toBe(1);
+    });
+
+    it("应该正确比较次版本号差异", () => {
+      const result = VersionUtils.compareVersions("1.2.0", "1.1.0");
+      expect(result).toBe(1);
+    });
+
+    it("应该正确比较补丁版本号差异", () => {
+      const result = VersionUtils.compareVersions("1.0.1", "1.0.0");
+      expect(result).toBe(1);
+    });
+
+    it("应该正确处理小于的情况", () => {
+      const result = VersionUtils.compareVersions("1.0.0", "2.0.0");
+      expect(result).toBe(-1);
+    });
+
+    it("应该正确处理不同长度的版本号", () => {
+      const result = VersionUtils.compareVersions("1.0", "1.0.0");
+      expect(result).toBe(0);
+    });
+
+    it("应该正确处理较短的版本号", () => {
+      const result = VersionUtils.compareVersions("1.0.0", "1.0");
+      expect(result).toBe(0);
+    });
+
+    it("应该正确处理带预发布标签的版本号", () => {
+      // 注意：当前实现不处理预发布标签，仅比较数字部分
+      const result = VersionUtils.compareVersions("1.0.0-alpha", "1.0.0");
+      // 预发布标签会被 split(".") 处理，可能产生非数字部分
+      // 这里测试数字部分的比较
+      expect(typeof result).toBe("number");
+    });
+
+    it("应该正确处理复杂版本号比较", () => {
+      expect(VersionUtils.compareVersions("1.2.3", "1.2.4")).toBe(-1);
+      expect(VersionUtils.compareVersions("1.2.4", "1.2.3")).toBe(1);
+      expect(VersionUtils.compareVersions("2.0.0", "1.9.9")).toBe(1);
+      expect(VersionUtils.compareVersions("0.1.0", "0.0.9")).toBe(1);
+    });
+  });
+
+  describe("isValidVersion", () => {
+    it("应该接受有效的标准版本号", () => {
+      expect(VersionUtils.isValidVersion("1.0.0")).toBe(true);
+      expect(VersionUtils.isValidVersion("0.0.1")).toBe(true);
+      expect(VersionUtils.isValidVersion("10.20.30")).toBe(true);
+    });
+
+    it("应该接受带预发布标签的版本号", () => {
+      expect(VersionUtils.isValidVersion("1.0.0-alpha")).toBe(true);
+      expect(VersionUtils.isValidVersion("1.0.0-beta.1")).toBe(true);
+      expect(VersionUtils.isValidVersion("1.0.0-rc.1")).toBe(true);
+      expect(VersionUtils.isValidVersion("2.0.0-alpha.1.beta.2")).toBe(true);
+    });
+
+    it("应该接受带构建元数据的版本号", () => {
+      expect(VersionUtils.isValidVersion("1.0.0+build.1")).toBe(true);
+      expect(VersionUtils.isValidVersion("1.0.0+20130313144700")).toBe(true);
+    });
+
+    it("应该接受带预发布和构建元数据的版本号", () => {
+      expect(VersionUtils.isValidVersion("1.0.0-alpha+001")).toBe(true);
+      expect(VersionUtils.isValidVersion("1.0.0-beta+exp.sha.5114f85")).toBe(true);
+    });
+
+    it("应该拒绝无效的版本号", () => {
+      expect(VersionUtils.isValidVersion("1")).toBe(false);
+      expect(VersionUtils.isValidVersion("1.0")).toBe(false);
+      expect(VersionUtils.isValidVersion("v1.0.0")).toBe(false);
+      expect(VersionUtils.isValidVersion("")).toBe(false);
+      expect(VersionUtils.isValidVersion("invalid")).toBe(false);
+      expect(VersionUtils.isValidVersion("1.0.0-")).toBe(false); // 只有连字符
+    });
+
+    it("应该拒绝边界情况", () => {
+      expect(VersionUtils.isValidVersion(".1.0.0")).toBe(false);
+      expect(VersionUtils.isValidVersion("1.0.0.")).toBe(false);
+      expect(VersionUtils.isValidVersion("..")).toBe(false);
+    });
+  });
+
+  describe("clearCache", () => {
+    it("应该清除版本缓存", () => {
+      // 获取版本号（建立缓存）
+      const version1 = VersionUtils.getVersion();
+
+      // 清除缓存
+      VersionUtils.clearCache();
+
+      // 再次获取版本号
+      const version2 = VersionUtils.getVersion();
+
+      // 应该返回相同值，但是重新读取的
+      expect(version1).toBe(version2);
+    });
+
+    it("应该清除版本信息缓存", () => {
+      // 获取版本信息（建立缓存）
+      const info1 = VersionUtils.getVersionInfo();
+
+      // 清除缓存
+      VersionUtils.clearCache();
+
+      // 再次获取版本信息
+      const info2 = VersionUtils.getVersionInfo();
+
+      // 应该返回相同值，但是重新读取的
+      expect(info1).toEqual(info2);
+    });
+  });
+
+  describe("边界情况测试", () => {
+    it("应该处理 getRuntimeVersion 的错误情况", () => {
+      // 清除缓存
+      VersionUtils.clearCache();
+
+      // 获取版本号，即使在某些环境中无法读取 package.json
+      // 也应该返回 "unknown" 或有效的版本号
+      const version = VersionUtils.getVersion();
+      expect(["unknown", "1.9.7"].includes(version) || /^\d+\.\d+\.\d+/.test(version)).toBe(true);
+    });
+
+    it("应该处理 getRuntimeVersionInfo 的错误情况", () => {
+      // 清除缓存
+      VersionUtils.clearCache();
+
+      // 获取版本信息，即使在某些环境中无法读取 package.json
+      // 也应该返回包含至少 version 字段的对象
+      const info = VersionUtils.getVersionInfo();
+      expect(info).toHaveProperty("version");
+      expect(typeof info.version).toBe("string");
+    });
+  });
+});

package/src/global.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 全局常量类型声明
+ *
+ * 这些常量由构建工具在构建时注入
+ */
+declare const __VERSION__: string;
+declare const __APP_NAME__: string;

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @xiaozhi-client/version
+ *
+ * 小智客户端版本管理工具
+ *
+ * 提供版本号获取、比较、验证等功能
+ */
+
+export { VERSION, APP_NAME } from "./version-constants.js";
+export { VersionUtils } from "./VersionUtils.js";
+export type { VersionInfo } from "./VersionUtils.js";

package/src/version-constants.ts

@@ -0,0 +1,8 @@
+/**
+ * 版本号常量（构建时注入）
+ *
+ * 如果构建时能读取到 package.json，则为真实版本号
+ * 否则为占位符，运行时从 package.json 读取
+ */
+export const VERSION = __VERSION__;
+export const APP_NAME = __APP_NAME__;

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": false,
+    "outDir": "../../dist/version",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "useUnknownInCatchVariables": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "tsup";
+
+// 获取当前文件所在目录
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 读取根目录 package.json 获取版本号
+const rootPkgPath = resolve(__dirname, "../../package.json");
+const pkg = JSON.parse(readFileSync(rootPkgPath, "utf-8"));
+
+export default defineConfig({
+  entry: {
+    index: resolve(__dirname, "src/index.ts"),
+  },
+  format: ["esm"],
+  target: "node18",
+  outDir: "dist",
+  clean: true,
+  sourcemap: true,
+  dts: true,
+  minify: false,
+  splitting: false,
+  bundle: true,
+  keepNames: true,
+  platform: "node",
+  // 使用版本包自己的 tsconfig.json
+  tsconfig: resolve(__dirname, "tsconfig.json"),
+  esbuildOptions: (options) => {
+    options.resolveExtensions = [".ts", ".js", ".json"];
+
+    // 构建时注入版本号常量
+    // 如果构建时能读取到版本号，则注入真实值
+    // 否则注入占位符，运行时从 package.json 读取
+    const versionValue = pkg.version || "__VERSION__";
+    const appNameValue = pkg.name || "__APP_NAME__";
+
+    options.define = {
+      ...options.define,
+      __VERSION__: JSON.stringify(versionValue),
+      __APP_NAME__: JSON.stringify(appNameValue),
+    };
+  },
+  outExtension: () => ({
+    js: ".js",
+  }),
+});

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+  },
+  esbuild: {
+    define: {
+      __VERSION__: JSON.stringify("1.9.7"),
+      __APP_NAME__: JSON.stringify("xiaozhi-client"),
+    },
+  },
+});